WebTransportDatagramDuplexStream.createWritable() — Methode · JavaScript-Referenz

Signatur

WebTransportDatagramDuplexStream.prototype.createWritable(options)

Beschreibung

Mit createWritable() erhält man einen beschreibbaren Stream (WebTransportDatagramsWritable, eine Unterklasse von WritableStream), über den unzuverlässige, ungeordnete Datagramme an den Server gesendet werden. Jeder mit writer.write() geschriebene Uint8Array-Block wird als einzelnes Datagramm übertragen. Datagramme eignen sich für Daten, bei denen Aktualität wichtiger ist als Vollständigkeit – etwa Positionsupdates in Spielen, Sensordaten oder Echtzeit-Telemetrie.

Anders als die ältere, inzwischen als veraltet markierte Eigenschaft datagrams.writable, die immer denselben Stream liefert, kann createWritable() mehrfach aufgerufen werden. So lassen sich mehrere Datagramm-Ströme mit unterschiedlicher sendOrder (Priorität) oder sendGroup anlegen, sodass zum Beispiel Steuerbefehle vor weniger wichtigen Statusdaten gesendet werden.

Die maximale Größe eines Datagramms ist durch datagrams.maxDatagramSize begrenzt. Zu große Datagramme werden verworfen, ebenso Datagramme, die länger als outgoingMaxAge in der Warteschlange liegen. Ein erfolgreich aufgelöstes write()-Promise bedeutet also nicht, dass das Datagramm beim Empfänger angekommen ist.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Konfigurationsobjekt für den neuen Stream.
$options.sendGroup	WebTransportSendGroup \| null	null	Sendegruppe, erzeugt über `transport.createSendGroup()`. Streams und Datagramm-Writables derselben Gruppe teilen sich eine gemeinsame Priorisierung. Muss zur selben `WebTransport`-Instanz gehören.
$options.sendOrder	number	0	Sendepriorität innerhalb der Gruppe. Höhere Werte werden bevorzugt gesendet, bevor Daten mit niedrigeren Werten übertragen werden.

Rückgabewert

Typ

WebTransportDatagramsWritable

Beschreibung

Ein neuer WritableStream mit den zusätzlichen Eigenschaften sendGroup und sendOrder, der Uint8Array- bzw. BufferSource-Blöcke als einzelne Datagramme versendet.

Beispiele

Einfaches Datagramm senden

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

const writable = transport.datagrams.createWritable();
const writer = writable.getWriter();

const encoder = new TextEncoder();
await writer.write(encoder.encode('ping'));
console.log('Datagramm in Warteschlange gestellt');

writer.releaseLock();

Datagramm in Warteschlange gestellt

Priorisierte Datagramm-Ströme für ein Echtzeitspiel

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

const group = transport.createSendGroup();

// Steuerbefehle haben Vorrang vor Positionsupdates
const controlWriter = transport.datagrams
  .createWritable({ sendGroup: group, sendOrder: 10 })
  .getWriter();
const positionWriter = transport.datagrams
  .createWritable({ sendGroup: group, sendOrder: 1 })
  .getWriter();

const sendPosition = (x, y) => {
  const buf = new Float32Array([x, y]);
  positionWriter.write(new Uint8Array(buf.buffer));
};

const sendCommand = (code) => controlWriter.write(new Uint8Array([code]));

sendPosition(12.5, 40.25);
sendCommand(0x01); // z. B. "Sprung"

Feature-Erkennung mit Fallback auf die veraltete Eigenschaft

const getDatagramWriter = (transport) => {
  const dg = transport.datagrams;
  const writable = typeof dg.createWritable === 'function'
    ? dg.createWritable()
    : dg.writable; // veralteter Weg
  return writable.getWriter();
};

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

const writer = getDatagramWriter(transport);
const payload = new TextEncoder().encode(JSON.stringify({ temp: 21.4 }));

if (payload.byteLength <= transport.datagrams.maxDatagramSize) {
  await writer.write(payload);
  console.log('Gesendet:', payload.byteLength, 'Bytes');
} else {
  console.warn('Datagramm zu groß');
}

Gesendet: 13 Bytes

// Wichtig · Fallstricke

Browser-Unterstützung: createWritable() ist neuer als WebTransport selbst und nicht in allen Browsern verfügbar (Chromium-Browser bieten teils nur datagrams.writable). Immer per Feature-Erkennung prüfen. WebTransport funktioniert nur in sicheren Kontexten (HTTPS) und benötigt einen HTTP/3-fähigen Server.
Keine Zustellgarantie: Datagramme können verloren gehen, doppelt oder in anderer Reihenfolge ankommen. Ein aufgelöstes write()-Promise bestätigt nur die Übernahme in die Sendewarteschlange.
Größenlimit: Daten größer als maxDatagramSize werden stillschweigend verworfen. Größere Nachrichten gehören in einen unidirektionalen oder bidirektionalen Stream.
Wird eine sendGroup übergeben, die zu einer anderen WebTransport-Instanz gehört, wird ein InvalidStateError geworfen.
Nach dem Schließen der Verbindung (transport.close() oder Fehler) werden Schreibversuche mit einem Fehler abgelehnt – transport.closed überwachen.

Siehe auch

WebTransportDatagramDuplexStream WebTransportDatagramsWritable WebTransportDatagramDuplexStream.readable WebTransportDatagramDuplexStream.maxDatagramSize WebTransport WebTransport.createSendGroup() WritableStream