WebTransportSendStream.getWriter() — Methode · JavaScript-Referenz

Signatur

WebTransportSendStream.prototype.getWriter()

Beschreibung

getWriter() überschreibt die gleichnamige Methode von WritableStream. Statt eines einfachen WritableStreamDefaultWriter liefert sie einen WebTransportWriter. Dieser erbt alle bekannten Schreiber-Methoden (write(), close(), abort(), releaseLock(), ready, closed, desiredSize) und ergänzt sie um WebTransport-spezifische Methoden wie atomicWrite() (nach aktuellem Spezifikationsstand zusätzlich commit()).

Einen Sendestrom bekommt man über WebTransport.createUnidirectionalStream() oder als writable-Seite eines WebTransportBidirectionalStream (aus createBidirectionalStream() oder incomingBidirectionalStreams). Mit dem Schreiber schickt man dann Binärdaten (Uint8Array, ArrayBuffer, …) über HTTP/3 zum Server.

Mit dem Aufruf wird der Stream gesperrt (stream.locked === true). Solange die Sperre besteht, kann weder ein zweiter Schreiber angelegt noch pipeTo() auf den Stream ausgeführt werden. Mit writer.releaseLock() geben Sie die Sperre wieder frei.

Rückgabewert

Typ

WebTransportWriter

Beschreibung

Ein neuer WebTransportWriter, der an diesen Sendestrom gebunden ist. Er erweitert WritableStreamDefaultWriter um atomicWrite().

Beispiele

Daten über einen unidirektionalen Stream senden

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

// Unidirektionaler Stream: nur Client → Server
const stream = await transport.createUnidirectionalStream();
const writer = stream.getWriter();

const encoder = new TextEncoder();
await writer.write(encoder.encode('Hallo Server!'));
await writer.write(encoder.encode(' Zweite Nachricht.'));

// Stream sauber beenden (FIN)
await writer.close();
console.log('Stream geschlossen, gesperrt:', stream.locked);

Stream geschlossen, gesperrt: true

Bidirektionaler Stream: Anfrage senden, Antwort lesen

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

const { readable, writable } = await transport.createBidirectionalStream();
const writer = writable.getWriter();

await writer.ready; // Gegendruck (Backpressure) beachten
await writer.write(new TextEncoder().encode('ping'));
await writer.close();

const reader = readable.getReader();
const decoder = new TextDecoder();
let antwort = '';
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  antwort += decoder.decode(value, { stream: true });
}
console.log('Antwort:', antwort);

Antwort: ping

Sperre freigeben und Fehler bei doppeltem getWriter()

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

const writer1 = stream.getWriter();
try {
  stream.getWriter(); // Stream ist bereits gesperrt
} catch (err) {
  console.log(err.name);
}

await writer1.write(new Uint8Array([1, 2, 3]));
writer1.releaseLock();          // Sperre aufheben
console.log(stream.locked);

const writer2 = stream.getWriter(); // jetzt wieder möglich
await writer2.close();

TypeError false

Atomares Schreiben (falls unterstützt)

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

const paket = new Uint8Array([0x01, 0x02, 0x03, 0x04]);

if (typeof writer.atomicWrite === 'function') {
  // Wird ganz oder gar nicht angenommen – kein Teil-Puffern
  await writer.atomicWrite(paket);
} else {
  await writer.write(paket);
}
await writer.close();

// Wichtig · Fallstricke

Exklusive Sperre: Ist der Stream schon gesperrt, etwa durch einen anderen Schreiber oder ein laufendes pipeTo(), wirft getWriter() einen TypeError. Prüfen Sie vorher stream.locked oder rufen Sie releaseLock() auf.
releaseLock() schließt nicht: Das Freigeben der Sperre beendet den Stream nicht. Zum Beenden brauchen Sie close() (sauberes Ende) oder abort(reason) (Abbruch mit RESET_STREAM).
Gegendruck (Backpressure): Warten Sie vor großen Schreibvorgängen mit await writer.ready. Sonst sammeln sich die Daten im internen Puffer.
Nur Binärdaten: Chunks müssen BufferSource sein (Uint8Array, ArrayBuffer …). Zeichenketten vorher mit TextEncoder umwandeln, sonst wird die Schreib-Promise mit einem TypeError abgelehnt.
Kompatibilität: WebTransport ist experimentell und nur in sicheren Kontexten (HTTPS) verfügbar. Chromium-Browser unterstützen es seit Version 97, Firefox seit 114, Safari erst seit Kurzem bzw. eingeschränkt. atomicWrite() und commit() fehlen in manchen Implementierungen noch. Prüfen Sie vor der Nutzung, ob sie vorhanden sind.
Schließt oder scheitert die Verbindung (transport.closed), werden offene Schreib-Promises abgelehnt. Fangen Sie diese Fehler mit try/catch ab.

Siehe auch

WebTransportSendStream.getStats() WebTransportSendGroup.getStats() WebTransportReceiveStream.getStats() WritableStream.getWriter() WebTransport.exportKeyingMaterial()