WebTransportDatagramDuplexStream.outgoingHighWaterMark — Eigenschaft · JavaScript-Referenz

Signatur

WebTransportDatagramDuplexStream.outgoingHighWaterMark

Beschreibung

Die Eigenschaft outgoingHighWaterMark der Schnittstelle WebTransportDatagramDuplexStream legt fest, wie viele ausgehende Datagramme sich in der internen Warteschlange des writable-Streams ansammeln dürfen, bevor Gegendruck (Backpressure) entsteht. Gezählt wird in Blöcken (Chunks), also in einzelnen Datagrammen. Die Größe in Bytes spielt dafür keine Rolle.

Ist die Warteschlange voll, wird WritableStreamDefaultWriter.desiredSize null oder negativ. Das Promise writer.ready wird dann erst erfüllt, wenn wieder Platz frei ist. Mit einem kleinen Wert sendet die Anwendung zeitnah und hält die Latenz niedrig, zum Beispiel bei Spielständen oder Positionsdaten in Echtzeit. Ein größerer Wert fängt kurze Lastspitzen ab, verbraucht dafür mehr Speicher und lässt ältere Daten länger warten.

Datagramme sind grundsätzlich unzuverlässig: Der Browser kann sie verwerfen. Deshalb arbeitet die Eigenschaft oft mit outgoingMaxAge zusammen. Diese Eigenschaft sorgt dafür, dass veraltete Datagramme aus der Warteschlange entfernt werden, statt sie verspätet zu senden.

Parameter

Name	Typ	Default	Beschreibung
$value	number	browserabhängig	Nur beim Setzen: neue Obergrenze in Blöcken. Negative Werte oder `NaN` lösen einen `RangeError` aus.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Obergrenze der Warteschlange für ausgehende Datagramme, gemessen in Blöcken.

Beispiele

Aktuellen Wert auslesen und anpassen

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

const datagrams = transport.datagrams;
console.log('Standard:', datagrams.outgoingHighWaterMark);

// Kleine Warteschlange für niedrige Latenz
datagrams.outgoingHighWaterMark = 4;
console.log('Neu:', datagrams.outgoingHighWaterMark);

Standard: 1 (browserabhängig) Neu: 4

Positionsdaten mit Rücksicht auf Gegendruck senden

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

const { datagrams } = transport;
datagrams.outgoingHighWaterMark = 8;
datagrams.outgoingMaxAge = 100; // ms, veraltete Pakete verwerfen

const writer = datagrams.writable.getWriter();
const encoder = new TextEncoder();

const sendPosition = async (x, y) => {
  await writer.ready; // wartet, wenn mehr als 8 Datagramme anstehen
  const payload = encoder.encode(JSON.stringify({ x, y, t: Date.now() }));
  writer.write(payload).catch(err => console.warn('Senden fehlgeschlagen:', err));
};

for (let i = 0; i < 20; i++) {
  await sendPosition(i, i * 2);
}
console.log('desiredSize:', writer.desiredSize);

desiredSize: 8 (sobald die Warteschlange abgearbeitet ist)

Funktionsprüfung mit Fallback

const configureDatagrams = (transport, hwm) => {
  const { datagrams } = transport;
  if ('outgoingHighWaterMark' in datagrams) {
    try {
      datagrams.outgoingHighWaterMark = hwm;
    } catch (err) {
      console.error('Ungültiger Wert:', err.name);
    }
  } else {
    console.info('outgoingHighWaterMark wird nicht unterstützt');
  }
};

const transport = new WebTransport('https://example.com:4433/');
await transport.ready;
configureDatagrams(transport, -1);

Ungültiger Wert: RangeError

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser ab Version 97 und Firefox ab 114 unterstützen die Eigenschaft. In Safari ist WebTransport erst seit Version 26.4 verfügbar. Deshalb gilt die Eigenschaft nicht als Baseline. Vor dem Einsatz sollte man mit 'outgoingHighWaterMark' in transport.datagrams prüfen, ob sie vorhanden ist.
Sicherer Kontext: WebTransport steht nur über HTTPS bzw. in einem sicheren Kontext zur Verfügung. Der Server muss HTTP/3 unterstützen.
Einheit Blöcke: Gezählt werden Datagramme, keine Bytes. Wie groß ein einzelnes Datagramm höchstens sein darf, verrät maxDatagramSize. Größere Datagramme werden stillschweigend verworfen.
Ungültige Werte: Negative Zahlen oder NaN lösen einen RangeError aus.
Keine Zustellgarantie: Auch wenn Gegendruck beachtet wird, können Datagramme verloren gehen. Für zuverlässige Übertragung eignen sich createBidirectionalStream() oder createUnidirectionalStream().
Standard ändert sich: In neueren Fassungen der Spezifikation wandern Einstellungen wie outgoingHighWaterMark teilweise zu createWritable()-Optionen. Das Verhalten kann sich also noch ändern.

Siehe auch

WebTransport WebTransportDatagramDuplexStream.incomingHighWaterMark WebTransportDatagramDuplexStream.outgoingMaxAge WebTransportDatagramDuplexStream.incomingMaxAge WebTransportDatagramDuplexStream.maxDatagramSize