WebTransportError — Schnittstelle · JavaScript-Referenz

Signatur

interface WebTransportError extends DOMException

Beschreibung

WebTransportError ist die Fehlerklasse der WebTransport API. Sie erbt von DOMException und hat deshalb die bekannten Eigenschaften name (immer "WebTransportError") und message. Zusätzlich gibt es zwei eigene Eigenschaften, mit denen du die Fehlerursache genauer bestimmen kannst:

source: "stream" oder "session". Gibt an, ob ein einzelner Stream betroffen ist oder die ganze WebTransport-Sitzung.
streamErrorCode: Der Fehlercode der Anwendung, den die Gegenseite beim Abbrechen eines Streams mitgeschickt hat (RESET_STREAM bzw. STOP_SENDING), als Zahl von 0 bis 2³²−1. Wenn kein Code übermittelt wurde, ist der Wert null.

Solche Fehler bekommst du meistens nicht direkt, sondern als Ablehnungsgrund von Promises, zum Beispiel von transport.ready, transport.closed oder von reader.read() und writer.write() auf WebTransport-Streams. Wenn der Server einen Stream zurücksetzt, wird die Lese-Promise mit einem WebTransportError abgelehnt. Dabei ist source === "stream" gesetzt.

Unterscheide in der Fehlerbehandlung mit instanceof WebTransportError zwischen Transportfehlern und anderen Fehlern, etwa TypeError bei ungültigen URLs. Mit source entscheidest du dann, ob du nur einen neuen Stream öffnen musst oder die ganze Verbindung neu aufbauen musst.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Konstruktor-Parameter: lesbare Fehlerbeschreibung, landet in `error.message`.
$options	{ source?: "stream" \| "session", streamErrorCode?: number \| null }	{}	Konstruktor-Parameter: `source` (Standard `"stream"`) legt die Fehlerquelle fest. `streamErrorCode` (Standard `null`) ist ein ganzzahliger Anwendungs-Fehlercode von 0 bis 2³²−1.

Rückgabewert

Typ

WebTransportError

Beschreibung

new WebTransportError() gibt eine Fehlerinstanz zurück. Sie hat name === "WebTransportError" und die schreibgeschützten Eigenschaften source und streamErrorCode.

Beispiele

Instanz erzeugen und Eigenschaften lesen

const err = new WebTransportError('Stream vom Server zurückgesetzt', {
  source: 'stream',
  streamErrorCode: 42
});

console.log(err.name);            // Name der Fehlerklasse
console.log(err.message);
console.log(err.source);
console.log(err.streamErrorCode);
console.log(err instanceof DOMException);

WebTransportError Stream vom Server zurückgesetzt stream 42 true

Abgebrochenen Stream beim Lesen erkennen

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

const stream = await transport.createBidirectionalStream();
const reader = stream.readable.getReader();

try {
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    console.log('Empfangen:', new TextDecoder().decode(value));
  }
} catch (err) {
  if (err instanceof WebTransportError && err.source === 'stream') {
    // Nur dieser Stream ist betroffen, die Sitzung läuft weiter
    console.warn('Stream abgebrochen, Code:', err.streamErrorCode);
  } else {
    throw err;
  }
}

Stream abgebrochen, Code: 7 // falls der Server mit Code 7 zurücksetzt

Sitzungsfehler behandeln und neu verbinden

const connect = async (url, retries = 3) => {
  for (let attempt = 1; attempt <= retries; attempt++) {
    const transport = new WebTransport(url);
    try {
      await transport.ready;
      console.log('Verbunden');
      transport.closed.catch((err) => {
        if (err instanceof WebTransportError && err.source === 'session') {
          console.error('Sitzung verloren:', err.message);
        }
      });
      return transport;
    } catch (err) {
      console.warn(`Versuch ${attempt} fehlgeschlagen:`, err.name);
      await new Promise((r) => setTimeout(r, 1000 * attempt));
    }
  }
  throw new Error('Keine WebTransport-Verbindung möglich');
};

const transport = await connect('https://example.com:4433/live');

Versuch 1 fehlgeschlagen: WebTransportError Verbunden

Eigenen Stream mit Fehlercode abbrechen

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

const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();

// Der Upload wird vom Nutzer abgebrochen. Die Gegenseite erhält den Code 3.
await writer.abort(new WebTransportError('Upload abgebrochen', { streamErrorCode: 3 }));

// Wichtig · Fallstricke

Browser-Kompatibilität: WebTransport und damit WebTransportError gibt es in Chromium-Browsern ab Version 97 und in Firefox ab Version 114. Safari unterstützt die API erst seit Kurzem bzw. eingeschränkt. Prüfe die Unterstützung vorher mit 'WebTransport' in globalThis. Die API ist nur in sicheren Kontexten (HTTPS) verfügbar und funktioniert auch in Web Workern.
Keine HTTP-Statuscodes: Wenn der Verbindungsaufbau scheitert (Server nicht erreichbar, Zertifikat ungültig, HTTP/3 nicht aktiv), bekommst du aus Sicherheitsgründen nur eine allgemeine Meldung. Server-Details werden absichtlich nicht offengelegt.
streamErrorCode ist oft null: Bei Sitzungsfehlern (source === "session") oder wenn kein Code übertragen wurde, fehlt der Wert. Prüfe deshalb immer auf null, bevor du den Code auswertest.
Wertebereich: Ein streamErrorCode außerhalb von 0 bis 4294967295 führt im Konstruktor bzw. beim Abbruch zu einem RangeError.
err.code (von DOMException geerbt) ist immer 0. Werte stattdessen source und streamErrorCode aus.
Ein normales Schließen mit transport.close() lehnt closed nicht ab. Es wird mit { closeCode, reason } erfüllt. Nur unerwartete Abbrüche führen zu einem WebTransportError.

Siehe auch

WebTransport WebTransport.ready WebTransport.closed WebTransportBidirectionalStream DOMException ReadableStreamDefaultReader