WebTransportError.streamErrorCode — Eigenschaft · JavaScript-Referenz

Signatur

WebTransportError.streamErrorCode

Beschreibung

Die Eigenschaft streamErrorCode eines WebTransportError enthält den Fehlercode des Anwendungsprotokolls, der beim Abbruch eines einzelnen WebTransport-Streams übertragen wurde. Bricht die Gegenseite einen Stream ab (bei HTTP/3 über RESET_STREAM oder STOP_SENDING), wird das zugehörige Lese- oder Schreib-Promise mit einem WebTransportError abgelehnt. Dessen streamErrorCode sagt dann, warum die Anwendung auf der anderen Seite abgebrochen hat.

Die Bedeutung der Codes legst du selbst fest. Du vereinbarst sie zwischen Client und Server, zum Beispiel 1 = „Upload abgelehnt“ und 2 = „Kontingent überschritten“. Der Browser wertet die Codes nicht aus, er reicht sie nur durch. Ursprünglich lag der Wertebereich bei 0–255. Die aktuelle Spezifikation sieht einen vorzeichenlosen 32-Bit-Wert vor (unsigned long).

Der Wert ist null, wenn der Fehler nicht zu einem Stream gehört (dann ist source gleich "session") oder wenn kein Code übermittelt wurde. Frag daher immer zuerst error.source ab und prüfe dann auf null, bevor du den Code auswertest.

Wenn du selbst einen Stream mit einem bestimmten Code abbrechen willst, erzeugst du einen WebTransportError mit der Option streamErrorCode. Diesen übergibst du an writable.abort() bzw. readable.cancel().

Rückgabewert

Typ

number | null

Beschreibung

Der anwendungsspezifische Stream-Fehlercode als ganze Zahl oder null, wenn kein Code vorhanden ist (z. B. bei Fehlern auf Sitzungsebene).

Beispiele

Abbruchgrund der Gegenseite beim Lesen auswerten

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

const ERROR_TEXTE = {
  1: 'Upload abgelehnt',
  2: 'Kontingent überschritten'
};

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:', value.byteLength, 'Bytes');
  }
} catch (err) {
  if (err instanceof WebTransportError && err.source === 'stream') {
    const code = err.streamErrorCode;
    console.warn('Stream abgebrochen:', code === null ? 'ohne Code' : ERROR_TEXTE[code] ?? `Code ${code}`);
  } else {
    throw err;
  }
}

Stream abgebrochen: Kontingent überschritten

Eigenen Stream mit Fehlercode abbrechen

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

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

await writer.write(new TextEncoder().encode('Teil 1'));

// Der Nutzer bricht den Upload ab → Code 3 an den Server senden
const grund = new WebTransportError('Vom Nutzer abgebrochen', {
  source: 'stream',
  streamErrorCode: 3
});
console.log(grund.streamErrorCode);
await writer.abort(grund);

3

Fehler auf Sitzungsebene: kein Stream-Code

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

try {
  await transport.ready;
} catch (err) {
  if (err instanceof WebTransportError) {
    console.log(err.source);          // 'session'
    console.log(err.streamErrorCode); // null
  }
}

session null

// Wichtig · Fallstricke

Auf null prüfen: Bei Fehlern mit source === "session" und bei Abbrüchen ohne Code ist der Wert null. Schreib daher nicht if (err.streamErrorCode), denn so fällt auch der gültige Code 0 durch. Prüf stattdessen mit !== null.
Wertebereich: Ältere Fassungen der Spezifikation und ältere Browser erlauben nur Codes von 0–255. Werte außerhalb des erlaubten Bereichs führen im Konstruktor zu einem Fehler. Wenn du in allen Browsern sicher sein willst, bleib bei 0–255.
Nur für Streams: Den Grund für das Schließen der ganzen Sitzung erfährst du nicht über diese Eigenschaft. Dafür gibt es transport.closed mit closeCode und reason.
Schreibgeschützt: Du kannst den Wert nur über den Konstruktor setzen (new WebTransportError(msg, { streamErrorCode })).
Kompatibilität: WebTransport gibt es in Chromium-Browsern und in Firefox. In Safari ist die Unterstützung erst neu bzw. eingeschränkt. Die API braucht HTTPS und einen Server, der HTTP/3 mit WebTransport unterstützt. Prüf die Verfügbarkeit per Feature-Erkennung, z. B. 'WebTransport' in globalThis.

Siehe auch

WebTransportError WebTransportError.source WebTransport WebTransport.closed WritableStream.prototype.abort() ReadableStream.prototype.cancel()