WebSocketStream.close() — Methode · JavaScript-Referenz

Signatur

WebSocketStream.prototype.close(options)

Beschreibung

Mit close() beendet man eine Verbindung, die über WebSocketStream aufgebaut wurde. Das ist die Stream-basierte Alternative zur klassischen WebSocket-API. Die Methode startet den WebSocket-Schließ-Handshake und kann dem Server einen Close-Code und einen Grund (reason) als Text mitgeben.

Die Methode gibt selbst nichts zurück. Wann das Schließen wirklich abgeschlossen ist, erfährt man über das Promise WebSocketStream.closed. Es wird mit einem Objekt { closeCode, reason } erfüllt, sobald die Verbindung zu ist. Schlägt der Verbindungsaufbau fehl oder wird die Verbindung nicht sauber getrennt, wird es abgelehnt. Nach close() werden die zugehörigen ReadableStream- und WritableStream-Objekte (aus opened) ebenfalls geschlossen.

Wenn man keinen bestimmten Code oder Grund senden muss, kann man die Verbindung auch über den Stream selbst beenden, zum Beispiel mit writer.close() am WritableStreamDefaultWriter. Wird close() vor dem vollständigen Verbindungsaufbau aufgerufen, bricht der Browser den Aufbau ab. Das ist vergleichbar mit einem AbortSignal, das man dem Konstruktor übergibt.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Objekt mit den Eigenschaften `closeCode` und `reason`.
$options.closeCode	number		Close-Code, der an den Server gesendet wird. Erlaubt sind nur `1000` (normales Schließen) und Werte von `3000` bis `4999`. Fehlt er, wird ohne Code geschlossen oder `1000` verwendet, falls ein `reason` angegeben ist.
$options.reason	string	""	Für Menschen lesbarer Grund für das Schließen. Er darf in UTF-8-Kodierung höchstens 123 Byte lang sein.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Ob das Schließen abgeschlossen ist, prüft man über das Promise WebSocketStream.closed.

Beispiele

Verbindung normal schließen und auf das Ende warten

const wss = new WebSocketStream('wss://echo.example.com/');
const { readable, writable } = await wss.opened;

const writer = writable.getWriter();
await writer.write('Hallo Server');

// Verbindung mit Code und Grund beenden
wss.close({ closeCode: 1000, reason: 'Sitzung beendet' });

const { closeCode, reason } = await wss.closed;
console.log(`Geschlossen: ${closeCode} – ${reason}`);

Geschlossen: 1000 – Sitzung beendet

Eigener Close-Code bei Inaktivität

const wss = new WebSocketStream('wss://chat.example.com/live');
const { readable } = await wss.opened;
const reader = readable.getReader();

let timer;
const resetTimer = () => {
  clearTimeout(timer);
  // Nach 60 s ohne Nachricht mit anwendungseigenem Code schließen
  timer = setTimeout(() => {
    wss.close({ closeCode: 4000, reason: 'Timeout: keine Aktivität' });
  }, 60_000);
};

resetTimer();
try {
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    console.log('Nachricht:', value);
    resetTimer();
  }
} finally {
  clearTimeout(timer);
}

console.log(await wss.closed);

{ closeCode: 4000, reason: 'Timeout: keine Aktivität' }

Fehler bei ungültigen Optionen abfangen

const wss = new WebSocketStream('wss://echo.example.com/');
await wss.opened;

try {
  // 1001 darf nicht vom Skript gesetzt werden
  wss.close({ closeCode: 1001 });
} catch (err) {
  console.log(err.name); // InvalidAccessError
  wss.close({ closeCode: 1000, reason: 'Fallback' });
}

InvalidAccessError

Mit Feature-Erkennung auf WebSocket zurückfallen

const url = 'wss://echo.example.com/';

if ('WebSocketStream' in globalThis) {
  const wss = new WebSocketStream(url);
  await wss.opened;
  wss.close();
  console.log('WebSocketStream geschlossen:', await wss.closed);
} else {
  const ws = new WebSocket(url);
  ws.addEventListener('open', () => ws.close(1000, 'fertig'));
  ws.addEventListener('close', (e) => console.log('WebSocket geschlossen:', e.code));
}

// Wichtig · Fallstricke

Browser-Unterstützung: WebSocketStream ist nicht standardisiert und experimentell. Bisher unterstützen es nur Chromium-Browser (Chrome/Edge ab 124). Man sollte immer eine Feature-Erkennung einbauen und bei Bedarf auf WebSocket zurückfallen.
Ungültiger Close-Code: Ein anderer Wert als 1000 oder 3000–4999 löst eine InvalidAccessError-DOMException aus. Codes wie 1001 oder 1006 sind für das Protokoll bzw. den Browser reserviert.
Zu langer Grund: Ist reason in UTF-8 länger als 123 Byte, wird ein SyntaxError ausgelöst. Umlaute und Emojis belegen mehrere Byte.
Nach dem Schließen führen weitere Schreibversuche auf den writable-Stream zu Fehlern. Aktive reader.read()-Aufrufe enden mit done: true oder werden abgelehnt.
Wird close() erneut aufgerufen, nachdem die Verbindung schon geschlossen wird, passiert nichts.
Das Promise closed sollte man immer mit await abwarten oder mit .catch() absichern. Sonst kann bei einem Verbindungsabbruch ein unbehandeltes abgelehntes Promise entstehen.

Siehe auch

WebSocketStream WebSocketStream.closed WebSocketStream.opened WebSocket.close() WritableStreamDefaultWriter.close() TaskSignal.any()