WebTransportBidirectionalStream.writable — Eigenschaft · JavaScript-Referenz

Signatur

WebTransportBidirectionalStream.writable

Beschreibung

Die Eigenschaft writable eines WebTransportBidirectionalStream gibt die Sendehälfte des Streams zurück, ein WebTransportSendStream-Objekt. Dieses erbt von WritableStream. Darüber schickst du Bytes (Uint8Array bzw. ArrayBuffer-Views) über eine HTTP/3-Verbindung an den Server.

Einen bidirektionalen Stream bekommst du auf zwei Wegen: Du öffnest ihn selbst mit WebTransport.createBidirectionalStream() oder du nimmst ihn über WebTransport.incomingBidirectionalStreams an, wenn der Server ihn geöffnet hat. Zum Schreiben holst du dir mit writable.getWriter() einen WritableStreamDefaultWriter. Alternativ leitest du einen ReadableStream per pipeTo() direkt hinein.

Anders als Datagramme sind Streams zuverlässig und geordnet. Deshalb eignen sie sich für Anfrage/Antwort-Protokolle, Dateiübertragungen oder RPC über WebTransport. Die Gegenrichtung liest du über die Eigenschaft readable desselben Stream-Objekts.

Rückgabewert

Typ

WebTransportSendStream

Beschreibung

Ein WebTransportSendStream (Unterklasse von WritableStream) zum Senden von Binärdaten. Es wird bei jedem Zugriff dasselbe Objekt zurückgegeben.

Beispiele

Bidirektionalen Stream öffnen und Text senden

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

const stream = await transport.createBidirectionalStream();
const writer = stream.writable.getWriter();

const encoder = new TextEncoder();
await writer.write(encoder.encode('Hallo Server!'));
// Sendeseite sauber schließen (FIN senden)
await writer.close();
console.log('Daten gesendet');

Daten gesendet

Anfrage senden und Antwort lesen (Request/Response)

const request = async (transport, text) => {
  const { readable, writable } = await transport.createBidirectionalStream();

  const writer = writable.getWriter();
  await writer.write(new TextEncoder().encode(text));
  await writer.close();

  // Antwort vollständig einlesen
  const response = await new Response(readable).text();
  return response;
};

const transport = new WebTransport('https://example.com:4433/echo');
await transport.ready;
console.log(await request(transport, 'ping'));

ping

Vom Server geöffnete Streams beantworten

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

const reader = transport.incomingBidirectionalStreams.getReader();
while (true) {
  const { value: stream, done } = await reader.read();
  if (done) break;
  // Eingehende Daten per Pipe direkt zurückschicken (Echo)
  stream.readable.pipeTo(stream.writable).catch((err) => {
    console.error('Stream abgebrochen:', err);
  });
}

Senden abbrechen

const stream = await transport.createBidirectionalStream();
const writer = stream.writable.getWriter();

try {
  await writer.write(new Uint8Array([1, 2, 3]));
} finally {
  // Sendeseite mit Fehler abbrechen (RESET_STREAM)
  await writer.abort(new WebTransportError({ message: 'Abbruch durch Client', streamErrorCode: 42 }));
}

// Wichtig · Fallstricke

Nur Binärdaten: write() akzeptiert nur ArrayBuffer bzw. ArrayBufferView. Strings musst du vorher mit TextEncoder umwandeln, sonst wird die Schreiboperation mit einem TypeError abgelehnt.
Sperre: Solange ein Writer aktiv ist, ist der Stream gesperrt (locked === true). Ein zweiter Aufruf von getWriter() oder ein pipeTo() wirft dann einen Fehler. Gib die Sperre bei Bedarf mit writer.releaseLock() frei.
Schließen und Abbrechen: close() beendet die Sendeseite normal (FIN). abort() setzt den Stream mit einem Fehler zurück. Beides betrifft nur die Senderichtung, readable bleibt nutzbar.
Gegendruck (Backpressure): Warte mit await writer.ready, bevor du große Datenmengen schreibst, damit der Puffer nicht unbegrenzt wächst.
Kompatibilität: WebTransport wird von Chromium-Browsern (ab 97) und Firefox (ab 114) unterstützt. Safari unterstützt es nicht (Stand 2024). Die API funktioniert nur in sicheren Kontexten (HTTPS) und setzt einen HTTP/3-Server voraus. Prüfe die Unterstützung vorab mit 'WebTransport' in globalThis.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung.

Siehe auch

WebTransportBidirectionalStream WebTransportBidirectionalStream.readable WebTransportSendStream WebTransport.createBidirectionalStream() WebTransport.incomingBidirectionalStreams WritableStream WritableStream.getWriter()