WebTransportError.source — Eigenschaft · JavaScript-Referenz

Signatur

WebTransportError.source

Beschreibung

Die schreibgeschützte Eigenschaft source des Interfaces WebTransportError sagt, wo ein Fehler entstanden ist. Der Wert ist ein String aus einer festen Aufzählung (Enum). Mögliche Werte:

"stream": Der Fehler betrifft nur einen einzelnen uni- oder bidirektionalen Stream, zum Beispiel weil die Gegenstelle ihn per RESET_STREAM oder STOP_SENDING abgebrochen hat. Die Sitzung selbst kann weiterlaufen.
"session": Der Fehler betrifft die ganze WebTransport-Sitzung, etwa bei einem Verbindungsabbruch oder einem fehlgeschlagenen Handshake. Alle Streams und Datagramme sind danach nicht mehr nutzbar.

Die Eigenschaft ist vor allem für die Fehlerbehandlung gedacht. Bei einem Stream-Fehler reicht es meist, einen neuen Stream zu öffnen. Bei einem Sitzungsfehler muss dagegen eine neue WebTransport-Verbindung aufgebaut werden, zum Beispiel mit Wiederverbindung und Backoff. Bei Stream-Fehlern liefert streamErrorCode zusätzlich den anwendungsspezifischen Fehlercode, den die Gegenstelle gesendet hat.

Der Wert wird beim Erzeugen des Fehlers festgelegt. Bei eigenen Instanzen setzt man ihn über die Option source im Konstruktor new WebTransportError(message, options). Ohne diese Option ist der Standardwert "stream".

Rückgabewert

Typ

"stream" | "session"

Beschreibung

Ein String, der die Fehlerquelle angibt: "stream" für einen Fehler auf einem einzelnen Stream oder "session" für einen Fehler der ganzen Sitzung.

Beispiele

Stream- und Sitzungsfehler beim Lesen unterscheiden

const transport = new WebTransport('https://example.com:4433/wt');
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) {
    if (err.source === 'stream') {
      // Nur dieser Stream ist betroffen – die Sitzung läuft weiter
      console.warn(`Stream abgebrochen, Code: ${err.streamErrorCode}`);
    } else {
      // Die ganze Sitzung ist weg
      console.error('Sitzung verloren:', err.message);
    }
  } else {
    throw err;
  }
}

Stream abgebrochen, Code: 42

Automatisch neu verbinden bei Sitzungsfehlern

const connect = async (url, attempt = 0) => {
  const transport = new WebTransport(url);

  transport.closed
    .then(({ closeCode, reason }) => {
      // Sauber geschlossen: closed wird erfüllt, nicht abgelehnt
      console.log(`Sauber geschlossen (${closeCode}): ${reason}`);
    })
    .catch((err) => {
      if (err instanceof WebTransportError && err.source === 'session') {
        const delay = Math.min(1000 * 2 ** attempt, 30000);
        console.warn(`Sitzungsfehler, neuer Versuch in ${delay} ms`);
        setTimeout(() => connect(url, attempt + 1), delay);
      }
    });

  await transport.ready;
  return transport;
};

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

Sitzungsfehler, neuer Versuch in 1000 ms

Eigenen WebTransportError erzeugen und prüfen

const streamErr = new WebTransportError('Stream vom Client abgebrochen', {
  streamErrorCode: 7
});
console.log(streamErr.source, streamErr.streamErrorCode);

const sessionErr = new WebTransportError('Sitzung beendet', {
  source: 'session'
});
console.log(sessionErr.source, sessionErr.streamErrorCode);

// Schreibgeschützt: Die Zuweisung wird ignoriert (im Strict Mode TypeError)
try {
  'use strict';
  sessionErr.source = 'stream';
} catch (e) {
  console.log(e.name);
}
console.log(sessionErr.source);

stream 7 session null session

// Wichtig · Fallstricke

Standardwert: Wird im Konstruktor keine source angegeben, ist der Wert \"stream\". Wer einen Sitzungsfehler nachbilden will, muss source: 'session' ausdrücklich setzen.
Nur lesbar: Zuweisungen werden stillschweigend ignoriert, im Strict Mode (z. B. in ES-Modulen) werfen sie einen TypeError.
Sauberes Schließen ist kein Fehler: Beendet eine Seite die Sitzung mit transport.close(), wird transport.closed erfüllt und nicht mit einem WebTransportError abgelehnt. Eine Prüfung von source gibt es dann nicht.
streamErrorCode ist bei source === 'session' in der Regel null. Ein Anwendungscode ist nur bei Stream-Fehlern zuverlässig vorhanden.
Nicht jeder Fehler aus WebTransport ist ein WebTransportError. Es können auch andere DOMExceptions oder TypeErrors auftreten, deshalb vorher mit instanceof WebTransportError prüfen.
Kompatibilität: Unterstützt in Chromium-Browsern ab Version 97 und in Firefox ab Version 114. In Safari fehlt die Unterstützung bislang oder ist eingeschränkt. Die API gibt es nur in sicheren Kontexten (HTTPS), und sie braucht einen HTTP/3-fähigen Server. Vor der Nutzung mit 'WebTransport' in globalThis prüfen.

Siehe auch

WebTransportError WebTransportError.streamErrorCode WebTransport WebTransport.closed DOMException MediaTrackSupportedConstraints.groupId