WebSocket.url — Eigenschaft · JavaScript-Referenz

Signatur

WebSocket.url

Beschreibung

Die Eigenschaft WebSocket.url gibt die absolute URL zurück, mit der die WebSocket-Verbindung aufgebaut wurde. Sie enthält nicht unbedingt genau den String, den du an new WebSocket(url) übergeben hast, sondern die vom Browser aufgelöste und normalisierte Fassung. Zum Beispiel wird aus "wss://example.com" der Wert "wss://example.com/" (mit abschließendem Schrägstrich), und der Hostname wird in Kleinbuchstaben umgewandelt.

In aktuellen Browsern darf der Konstruktor auch relative URLs sowie die Schemata http: und https: annehmen. Diese werden dann gegen die Basis-URL des Dokuments aufgelöst und in ws: bzw. wss: umgewandelt. An url kannst du ablesen, welche Adresse am Ende tatsächlich verwendet wird.

Typische Einsatzfälle sind Logging und Fehlersuche (welcher Endpunkt ist gemeint?), das Wiederverbinden nach einem Abbruch (neue Instanz mit derselben URL anlegen) und das Unterscheiden mehrerer paralleler Verbindungen in einem gemeinsamen Event-Handler. Die Eigenschaft ist schreibgeschützt. Wer die Adresse ändern möchte, muss eine neue WebSocket-Instanz erzeugen.

Rückgabewert

Typ

string

Beschreibung

Die serialisierte, absolute URL der Verbindung (Schema ws: oder wss:). Sie ist ab dem Konstruktor-Aufruf verfügbar, also schon vor dem open-Event, und ändert sich während der Lebensdauer des Objekts nicht.

Beispiele

Normalisierte URL auslesen

const socket = new WebSocket('wss://Echo.Example.COM');

// Schon vor dem Verbindungsaufbau verfügbar
console.log(socket.url);

wss://echo.example.com/

Relative URL und http-Schema auflösen (moderne Browser)

// Seite läuft unter https://app.example.com/dashboard/
const live = new WebSocket('/live?room=42');
console.log(live.url);

const legacy = new WebSocket('https://app.example.com/feed');
console.log(legacy.url);

wss://app.example.com/live?room=42 wss://app.example.com/feed

Automatisches Wiederverbinden mit derselben URL

const connect = (url, attempt = 0) => {
  const ws = new WebSocket(url);

  ws.addEventListener('open', () => {
    console.log(`Verbunden mit ${ws.url}`);
    attempt = 0;
  });

  ws.addEventListener('close', (event) => {
    if (event.wasClean) return;
    const delay = Math.min(1000 * 2 ** attempt, 30000);
    console.warn(`Verbindung zu ${ws.url} verloren, neuer Versuch in ${delay} ms`);
    // url ist schreibgeschützt, deshalb eine neue Instanz anlegen
    setTimeout(() => connect(ws.url, attempt + 1), delay);
  });

  return ws;
};

connect('wss://stream.example.com/ticker');

Verbunden mit wss://stream.example.com/ticker

Mehrere Verbindungen in einem gemeinsamen Handler unterscheiden

const endpoints = ['wss://a.example.com/events', 'wss://b.example.com/events'];

const handleMessage = (event) => {
  // event.target ist die jeweilige WebSocket-Instanz
  const { url } = event.target;
  console.log(`[${new URL(url).host}]`, event.data);
};

const sockets = endpoints.map((u) => {
  const ws = new WebSocket(u);
  ws.addEventListener('message', handleMessage);
  return ws;
});

[a.example.com] {"type":"ping"}

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie socket.url = '…' wird im normalen Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Für eine andere Adresse brauchst du eine neue Instanz.
Nicht identisch mit der Eingabe: Wegen der Normalisierung (abschließender /, kleingeschriebener Host, weggelassener Standard-Port wie :443 bei wss:) solltest du url nicht per === mit dem ursprünglich übergebenen String vergleichen. Normalisiere beide Seiten besser vorher mit new URL().
Relative URLs und http(s)-Schema nimmt der Konstruktor erst in neueren Browsern an (etwa Chrome/Edge 125, Firefox 124, Safari 17.3). Ältere Browser werfen dabei einen SyntaxError. Wenn du ältere Browser unterstützen musst, gib immer absolute ws:/wss:-URLs an.
Fragmente (#abc) sind in WebSocket-URLs nicht erlaubt und führen im Konstruktor zu einem SyntaxError. Eine Instanz mit Fragment in url kann es also nicht geben.
Sicherheit: Tokens in der Query (?token=…) erscheinen vollständig in url und damit leicht in Logs oder Fehlerberichten. Maskiere sie vor dem Protokollieren oder übertrage die Authentifizierung auf anderem Weg, etwa per Cookie oder mit der ersten Nachricht.
In Node.js gibt es WebSocket erst ab Version 22 als stabile globale Klasse. Davor braucht man Bibliotheken wie ws, die ebenfalls eine url-Eigenschaft anbieten.

Siehe auch

WebSocket WebSocket.protocol StorageEvent.url WebSocket.binaryType WebSocket.extensions