WebTransport.close() — Methode · JavaScript-Referenz

Signatur

WebTransport.prototype.close(closeInfo)

Beschreibung

Mit close() beendest du eine WebTransport-Sitzung (HTTP/3 bzw. QUIC) gezielt. Der Browser schickt dem Server dabei eine Schließ-Nachricht (Capsule CLOSE_WEBTRANSPORT_SESSION), die einen numerischen closeCode und einen Text als reason enthält. Alle offenen unidirektionalen und bidirektionalen Streams sowie die Datagramm-Streams werden danach abgebrochen oder geschlossen.

Die Methode gibt nichts zurück. Ob das Schließen abgeschlossen ist, erfährst du über das Promise transport.closed. Nach einem sauberen Schließen wird es mit einem Objekt { closeCode, reason } erfüllt. Bei einem Verbindungsfehler wird es stattdessen mit einem WebTransportError abgelehnt.

Rufe close() auf, wenn deine Anwendung die Verbindung nicht mehr braucht, zum Beispiel beim Verlassen einer Seite, beim Abmelden oder nach einem Protokollfehler auf Anwendungsebene. So werden Ressourcen auf Client und Server sofort freigegeben, statt auf einen Timeout zu warten. Über eigene Fehlercodes kann der Server erkennen, warum der Client die Sitzung beendet hat.

Parameter

Name	Typ	Default	Beschreibung
$closeInfo	{ closeCode?: number, reason?: string }	{}	Optionales Objekt mit Angaben zum Schließen.
$closeInfo.closeCode	number (unsigned long, 32 Bit)	0	Anwendungsspezifischer Fehlercode, der an den Server übermittelt wird. `0` steht üblicherweise für ein reguläres Schließen.
$closeInfo.reason	string	""	Lesbarer Grund für das Schließen. Wird UTF-8-kodiert übertragen und auf höchstens 1024 Byte gekürzt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Den Abschluss meldet das Promise WebTransport.closed.

Beispiele

Sitzung regulär schließen und auf Abschluss warten

const transport = new WebTransport('https://example.com:4433/chat');
await transport.ready;

// ... Daten austauschen ...

transport.close({ closeCode: 0, reason: 'Sitzung beendet' });

const info = await transport.closed;
console.log(`Geschlossen: Code ${info.closeCode}, Grund: "${info.reason}"`);

Geschlossen: Code 0, Grund: "Sitzung beendet"

Eigene Fehlercodes bei Protokollverletzung

const PROTOCOL_ERROR = 4001;

const transport = new WebTransport('https://example.com:4433/game');
await transport.ready;

const reader = transport.datagrams.readable.getReader();
const { value } = await reader.read();

if (value[0] !== 0x01) {
  // Unerwartete Protokollversion: Verbindung mit Fehlercode beenden
  transport.close({
    closeCode: PROTOCOL_ERROR,
    reason: `Unbekannte Protokollversion ${value[0]}`
  });
}

Verbindung beim Verlassen der Seite aufräumen und Fehler abfangen

const transport = new WebTransport('https://example.com:4433/live');

transport.closed
  .then(({ closeCode, reason }) => {
    console.log('Sauber geschlossen:', closeCode, reason);
  })
  .catch((err) => {
    // Z. B. Netzwerkabbruch oder Schließen während des Verbindungsaufbaus
    console.error('Verbindung abgebrochen:', err.message);
  });

window.addEventListener('pagehide', () => {
  transport.close({ reason: 'Seite verlassen' });
});

Sauber geschlossen: 0 Seite verlassen

// Wichtig · Fallstricke

Kein Promise: close() selbst gibt undefined zurück. Wenn du auf das Ende warten willst, nutze await transport.closed.
Schließen während des Verbindungsaufbaus: Rufst du close() auf, bevor ready erfüllt ist, wird die Sitzung mit einem WebTransportError abgebaut. ready und closed werden dann abgelehnt. Ältere Implementierungen warfen hier stattdessen einen InvalidStateError. Fang solche Ablehnungen immer ab, sonst entstehen „unhandled rejection“-Warnungen.
Mehrfacher Aufruf: Ist die Sitzung bereits geschlossen oder fehlgeschlagen, bewirkt ein weiterer Aufruf nichts.
Länge von reason: Längere Texte werden auf 1024 Byte (UTF-8) gekürzt. Mehrbyte-Zeichen zählen entsprechend mehr.
Offene Streams: Daten, die noch nicht gesendet wurden, können verloren gehen. Wenn der Server alle Daten erhalten soll, schließe die Writer vorher mit await writer.close().
Kompatibilität: WebTransport funktioniert nur in sicheren Kontexten (HTTPS) und braucht einen HTTP/3-Server. Chromium-Browser und Firefox unterstützen die API. In Safari fehlt sie je nach Version, prüfe das also vorher mit 'WebTransport' in globalThis. Die API steht auch in Web Workern zur Verfügung.

Siehe auch

WebTransport WebTransport.closed WebTransport.ready WebTransport.datagrams SyncManager.register()