WebSocketStream.url — Eigenschaft · JavaScript-Referenz

Signatur

get WebSocketStream.url

Beschreibung

Die Eigenschaft url einer WebSocketStream-Instanz gibt die Adresse des WebSocket-Servers zurück, die beim Aufruf von new WebSocketStream(url, options) angegeben wurde. Der Wert ist schreibgeschützt: Zuweisungen werden ignoriert, im Strict Mode lösen sie einen TypeError aus. Eine bestehende Verbindung lässt sich also nicht auf einen anderen Server umleiten, dafür muss man eine neue Instanz erzeugen.

Der zurückgegebene String ist die geparste und serialisierte Form der URL und nicht unbedingt die exakte Eingabe. So kann z. B. bei einer reinen Host-Angabe ein abschließender Schrägstrich ergänzt werden (wss://example.com → wss://example.com/), und relative Angaben werden gegen die Basis-URL des Dokuments aufgelöst.

In der Praxis braucht man url vor allem für Logging und Fehlermeldungen, für Logik zum Wiederverbinden (eine neue Instanz mit derselben Adresse anlegen) und zur Prüfung, ob eine Verbindung verschlüsselt über wss: läuft. Die Eigenschaft steht sofort nach dem Konstruktor-Aufruf zur Verfügung, also auch schon, bevor das Promise opened erfüllt ist.

Rückgabewert

Typ

string

Beschreibung

Die serialisierte, absolute URL des WebSocket-Servers (Schema ws: oder wss:), mit der die Instanz erzeugt wurde.

Beispiele

URL einer Verbindung auslesen

const wss = new WebSocketStream('wss://echo.websocket.org');

// Steht sofort zur Verfügung, noch vor dem Verbindungsaufbau
console.log(wss.url);

const { readable, writable } = await wss.opened;
console.log(`Verbunden mit ${wss.url}`);

wss://echo.websocket.org/ Verbunden mit wss://echo.websocket.org/

Automatisch wiederverbinden mit derselben URL

const connect = async (url, retries = 3) => {
  const wss = new WebSocketStream(url);
  try {
    await wss.opened;
    console.log(`Verbindung zu ${wss.url} steht`);
    return wss;
  } catch (err) {
    console.warn(`Verbindung zu ${wss.url} fehlgeschlagen:`, err.message);
    if (retries === 0) throw err;
    await new Promise((r) => setTimeout(r, 1000));
    // Die gespeicherte URL für einen neuen Versuch wiederverwenden
    return connect(wss.url, retries - 1);
  }
};

const stream = await connect('wss://example.com/live');

Verbindung zu wss://example.com/live steht

Prüfen, ob die Verbindung verschlüsselt ist

const wss = new WebSocketStream('ws://localhost:8080/chat');

const { protocol, host, pathname } = new URL(wss.url);

if (protocol !== 'wss:') {
  console.warn(`Unverschlüsselte Verbindung zu ${host}${pathname}`);
}

Unverschlüsselte Verbindung zu localhost:8080/chat

Eigenschaft ist schreibgeschützt

'use strict';
const wss = new WebSocketStream('wss://example.com/feed');

try {
  wss.url = 'wss://andere-domain.example/';
} catch (err) {
  console.log(err.name); // Zuweisung ist nicht erlaubt
}
console.log(wss.url);

TypeError wss://example.com/feed

// Wichtig · Fallstricke

Experimentelle API: WebSocketStream gibt es bisher nur in Chromium-basierten Browsern (Chrome/Edge ab Version 124). Vor der Nutzung sollte man mit 'WebSocketStream' in globalThis prüfen, ob die API vorhanden ist, und sonst auf das klassische WebSocket zurückfallen.
Der Wert ist die serialisierte URL. Ein String-Vergleich mit der ursprünglichen Eingabe kann deshalb scheitern, etwa wegen eines ergänzten / am Ende. Für Vergleiche beide Seiten mit new URL() normalisieren.
Steht in der URL ein Token als Query-Parameter (z. B. ?token=…), landet es beim Loggen von url in Protokollen und Fehlerberichten. Solche Daten vor der Ausgabe entfernen.
Eine ungültige URL oder ein nicht erlaubtes Schema lässt schon der Konstruktor mit einem SyntaxError scheitern. Eine erfolgreich angelegte Instanz hat also immer einen gültigen url-Wert.
url gibt nur an, wohin verbunden werden soll. Ob die Verbindung tatsächlich steht, zeigen die Promises opened und closed.

Siehe auch

WebSocketStream WebSocketStream.opened WebSocketStream.closed WebSocketStream.close() WebSocket.url StorageEvent.url