WebSocketStream.opened — Eigenschaft · JavaScript-Referenz

Signatur

WebSocketStream.opened

Beschreibung

Die schreibgeschützte Eigenschaft opened einer WebSocketStream-Instanz liefert ein Promise. Es wird erfüllt, sobald der Handshake mit dem Server erfolgreich war. Der Erfüllungswert ist ein Objekt mit den Eigenschaften readable (ReadableStream), writable (WritableStream), protocol und extensions.

Anders als beim klassischen WebSocket mit onopen und onmessage arbeitet man hier mit der Streams-API. Nachrichten liest man über einen Reader aus readable und sendet sie über einen Writer von writable. Der Vorteil ist Gegendruck (Backpressure): Liest die Anwendung langsamer, als der Server sendet, puffert der Browser nicht einfach ohne Grenze weiter. Beim Senden kann man mit await writer.write() auf freie Kapazität warten.

Kann die Verbindung nicht aufgebaut werden, wird das Promise abgelehnt, zum Beispiel wenn der Server nicht erreichbar ist, der Handshake fehlschlägt oder die Verbindung über ein AbortSignal abgebrochen wird. Deshalb sollte man await wss.opened immer in try/catch einschließen.

Rückgabewert

Typ

Promise<{ readable: ReadableStream, writable: WritableStream, protocol: string, extensions: string }>

Beschreibung

Promise mit einem Objekt:

readable: ReadableStream mit den eingehenden Nachrichten (string oder Uint8Array)
writable: WritableStream zum Senden (string oder BufferSource)
protocol: das vom Server gewählte Unterprotokoll oder ein leerer String
extensions: die ausgehandelten Erweiterungen, z. B. permessage-deflate

Schlägt der Verbindungsaufbau fehl, wird das Promise abgelehnt.

Beispiele

Verbindung öffnen und Echo empfangen

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

try {
  const { readable, writable, protocol, extensions } = await wss.opened;
  console.log('Verbunden:', { protocol, extensions });

  const writer = writable.getWriter();
  const reader = readable.getReader();

  await writer.write('Hallo Server');

  const { value, done } = await reader.read();
  if (!done) console.log('Antwort:', value);
} catch (err) {
  console.error('Verbindung fehlgeschlagen:', err);
}

Verbunden: { protocol: '', extensions: 'permessage-deflate; client_max_window_bits' } Antwort: Hallo Server

Alle eingehenden Nachrichten mit Gegendruck verarbeiten

const wss = new WebSocketStream('wss://example.com/ticker', {
  protocols: ['json.v1']
});

const { readable, protocol } = await wss.opened;
console.log('Protokoll:', protocol);

// Langsame Verarbeitung: Der Browser liest erst weiter, wenn wir bereit sind
for await (const message of readable) {
  const data = JSON.parse(message);
  await new Promise((r) => setTimeout(r, 100)); // simulierte Arbeit
  console.log('Kurs:', data.symbol, data.price);
}

Protokoll: json.v1 Kurs: ACME 42.17 ...

Verbindungsaufbau mit Zeitlimit abbrechen

const connect = async (url, timeoutMs = 5000) => {
  const signal = AbortSignal.timeout(timeoutMs);
  const wss = new WebSocketStream(url, { signal });
  try {
    return { wss, ...(await wss.opened) };
  } catch (err) {
    console.warn('Kein Verbindungsaufbau:', err.name);
    return null;
  }
};

if (!('WebSocketStream' in globalThis)) {
  console.log('WebSocketStream nicht unterstützt – Fallback auf WebSocket');
} else {
  const conn = await connect('wss://nicht-erreichbar.example/', 3000);
  console.log(conn ? 'offen' : 'fehlgeschlagen');
}

Kein Verbindungsaufbau: WebSocketError fehlgeschlagen

// Wichtig · Fallstricke

Kompatibilität: WebSocketStream ist nicht standardisiert und experimentell. Die API gibt es nur in Chromium-Browsern (Chrome/Edge ab 124). Firefox und Safari unterstützen sie nicht. Prüfe sie per 'WebSocketStream' in globalThis und nutze sonst WebSocket als Fallback.
Ablehnung behandeln: Wenn der Verbindungsaufbau fehlschlägt, wird opened abgelehnt. Ohne catch entsteht eine unbehandelte Promise-Ablehnung (unhandledrejection). Der genaue Fehlertyp (z. B. WebSocketError oder AbortError) kann sich je nach Browser-Version unterscheiden.
opened wird nur einmal erfüllt. Ein Wiederverbinden erfordert eine neue WebSocketStream-Instanz.
Ein Stream kann nur einen aktiven Reader bzw. Writer haben. Ein zweiter Aufruf von getReader() wirft einen TypeError, solange die Sperre nicht mit releaseLock() gelöst wurde.
Wird writable geschlossen oder abgebrochen, schließt das auch die Verbindung. Für Close-Code und Grund ist wss.close({ closeCode, reason }) besser geeignet.
Nutze aus Sicherheitsgründen immer wss://. Auf HTTPS-Seiten blockiert der Browser unverschlüsselte ws://-Verbindungen als Mixed Content.

Siehe auch

WebSocketStream WebSocketStream.closed WebSocketStream.close() WebSocket ReadableStream WritableStream AbortSignal.timeout()