Signatur
Beschreibung
Die Eigenschaft incomingMaxAge eines WebTransportDatagramDuplexStream (erreichbar über transport.datagrams) legt fest, wie alt ein empfangenes Datagramm in der internen Warteschlange höchstens werden darf. Datagramme, die länger als diese Zeit ungelesen in der Warteschlange liegen, verwirft der Browser. Sie kommen dann nie beim readable-Stream an.
Das ist vor allem bei Echtzeit-Anwendungen nützlich, also bei Multiplayer-Spielen, Telemetrie, Positionsdaten oder Audio- und Video-Metadaten. Dort ist ein veralteter Zustand wertlos, und ein aktuelles Paket ist wichtiger als ein vollständiger Verlauf. Kommt die Anwendung mit dem Lesen nicht hinterher (etwa weil der Hauptthread blockiert ist), stauen sich die Pakete nicht beliebig lange an.
Der Wert ist eine Zahl in Millisekunden oder null. null ist der Standardwert und bedeutet: keine Altersgrenze. Die Anwendung erhält also alle Datagramme, solange die Warteschlange (incomingHighWaterMark) nicht überläuft. Laut Spezifikation wird das Setzen auf 0 als null behandelt. Negative Werte und NaN lösen einen RangeError aus.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | null | null | Neues Höchstalter in Millisekunden (nur beim Setzen). null oder 0 heißt: keine Begrenzung. |
Rückgabewert
null, wenn keine Grenze gesetzt ist.Beispiele
Standardwert lesen und Höchstalter setzen
const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;
const { datagrams } = transport;
console.log('Vorher:', datagrams.incomingMaxAge);
// Datagramme, die älter als 100 ms sind, verwerfen
datagrams.incomingMaxAge = 100;
console.log('Nachher:', datagrams.incomingMaxAge);Spielzustand in Echtzeit empfangen, veraltete Pakete verwerfen
const connectGame = async (url, onState) => {
const transport = new WebTransport(url);
await transport.ready;
// Positionsdaten älter als 50 ms sind für das Rendering nutzlos
transport.datagrams.incomingMaxAge = 50;
transport.datagrams.incomingHighWaterMark = 16;
const reader = transport.datagrams.readable.getReader();
const decoder = new TextDecoder();
while (true) {
const { value, done } = await reader.read();
if (done) break;
onState(JSON.parse(decoder.decode(value)));
}
};
connectGame('https://game.example.com:4433/state', (state) => {
console.log('Neuer Zustand:', state.tick);
});Ungültige Werte abfangen und Grenze wieder aufheben
const transport = new WebTransport('https://example.com:4433/wt');
await transport.ready;
try {
transport.datagrams.incomingMaxAge = -10;
} catch (err) {
console.log(err.name);
}
// Begrenzung wieder aufheben
transport.datagrams.incomingMaxAge = null;
console.log(transport.datagrams.incomingMaxAge);// Wichtig · Fallstricke
- Datagramme sind grundsätzlich unzuverlässig: Auch ohne
incomingMaxAgekönnen Pakete verloren gehen oder in anderer Reihenfolge ankommen. Die Eigenschaft sorgt zusätzlich dafür, dass Pakete absichtlich verworfen werden. Nutzen Sie sie also nicht für Daten, die vollständig ankommen müssen. Dafür sind Streams gedacht (createBidirectionalStream()). - Negative Werte und
NaNlösen einenRangeErroraus.0wird alsnull(keine Grenze) behandelt und bedeutet nicht, dass sofort alles verworfen wird. - Wie das Alter genau gemessen wird, hängt vom Browser ab. Rechnen Sie mit einer Genauigkeit im Bereich weniger Millisekunden, nicht mit exaktem Timing.
- Verworfene Datagramme lösen kein Ereignis und keinen Fehler aus. Die Anwendung bemerkt sie nicht, außer sie zählt eigene Sequenznummern mit.
- Kompatibilität: WebTransport gibt es nur in sicheren Kontexten (HTTPS) und es braucht einen HTTP/3-Server. Chromium-basierte Browser unterstützen es seit Version 97, Firefox seit Version 114. In Safari ist die Unterstützung erst neu bzw. eingeschränkt. Prüfen Sie vorher mit
'WebTransport' in globalThis, ob die API vorhanden ist.