WebTransport.createSendGroup() — Methode · JavaScript-Referenz

Signatur

WebTransport.prototype.createSendGroup()

Beschreibung

Die Methode createSendGroup() der Schnittstelle WebTransport erzeugt ein neues WebTransportSendGroup-Objekt und gibt es zurück. Eine Sendegruppe ist ein logischer Container für ausgehende Streams (und beschreibbare Datagramm-Kanäle) derselben Verbindung. Man ordnet einen Stream einer Gruppe zu, indem man beim Erzeugen die Option sendGroup übergibt, z. B. an createUnidirectionalStream() oder createBidirectionalStream(), oder indem man nachträglich die Eigenschaft WebTransportSendStream.sendGroup setzt.

Sendegruppen sind vor allem für die Priorisierung gedacht: Der Wert sendOrder eines Streams gilt nur innerhalb seiner Gruppe. Streams mit höherem sendOrder werden innerhalb der Gruppe bevorzugt gesendet, während unterschiedliche Gruppen untereinander fair um die verfügbare Bandbreite konkurrieren. So kann eine Anwendung etwa Audio, Video und Chat-Daten jeweils in eigenen Gruppen verwalten, ohne dass eine hohe Priorität in einer Gruppe eine andere vollständig aushungert.

Zusätzlich bietet eine Sendegruppe über getStats() aggregierte Statistiken (z. B. geschriebene, gesendete und bestätigte Bytes) für alle ihr zugeordneten Streams. Das ist praktisch für Monitoring und adaptive Bitraten-Steuerung.

Die Methode ist synchron und benötigt keine Argumente. Eine Sendegruppe ist immer an genau die WebTransport-Instanz gebunden, von der sie erzeugt wurde.

Rückgabewert

Typ

WebTransportSendGroup

Beschreibung

Ein neues WebTransportSendGroup-Objekt, das als Wert der Option sendGroup beim Erzeugen von Streams verwendet werden kann. Wirft einen InvalidStateError (DOMException), wenn die Verbindung bereits geschlossen oder fehlgeschlagen ist.

Beispiele

Sendegruppe erzeugen und Streams zuordnen

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

// Eine Gruppe für Video-Daten anlegen
const videoGroup = transport.createSendGroup();

// Keyframes höher priorisieren als Delta-Frames – gilt nur innerhalb der Gruppe
const keyframeStream = await transport.createUnidirectionalStream({
  sendGroup: videoGroup,
  sendOrder: 10
});
const deltaStream = await transport.createUnidirectionalStream({
  sendGroup: videoGroup,
  sendOrder: 1
});

console.log(keyframeStream.sendGroup === videoGroup);

true

Getrennte Gruppen für Audio und Chat mit fairer Bandbreitenteilung

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

const audioGroup = transport.createSendGroup();
const chatGroup = transport.createSendGroup();

const audio = await transport.createUnidirectionalStream({ sendGroup: audioGroup, sendOrder: 5 });
const chat = await transport.createBidirectionalStream({ sendGroup: chatGroup });

const encoder = new TextEncoder();
const chatWriter = chat.writable.getWriter();
await chatWriter.write(encoder.encode('Hallo!'));

// Stream nachträglich in eine andere Gruppe verschieben
audio.sendGroup = chatGroup;
console.log(audio.sendGroup === chatGroup);

true

Aggregierte Statistiken einer Gruppe abfragen (mit Feature-Erkennung)

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

if (typeof transport.createSendGroup !== 'function') {
  console.warn('Sendegruppen werden nicht unterstützt');
} else {
  const group = transport.createSendGroup();
  const stream = await transport.createUnidirectionalStream({ sendGroup: group });
  const writer = stream.getWriter();
  await writer.write(new Uint8Array(1024));

  const stats = await group.getStats();
  console.log('Geschrieben:', stats.bytesWritten, 'Bestätigt:', stats.bytesAcknowledged);
}

Geschrieben: 1024 Bestätigt: 0 (Werte abhängig vom Netzwerkzustand)

// Wichtig · Fallstricke

Experimentell: Sendegruppen sind ein neuer Teil der WebTransport-Spezifikation und werden nicht von allen Browsern unterstützt, die WebTransport grundsätzlich anbieten. Vor der Nutzung per typeof transport.createSendGroup === 'function' prüfen und eine Rückfallebene ohne Gruppen vorsehen.
sendOrder ist gruppenlokal: Ein hoher sendOrder-Wert bevorzugt einen Stream nur gegenüber Streams derselben Gruppe – nicht gegenüber Streams anderer Gruppen oder ungruppierten Streams.
Eine Gruppe darf nur mit Streams derselben WebTransport-Instanz verwendet werden; eine fremde Gruppe führt zu einem Fehler.
Nach transport.close() oder einem Verbindungsabbruch wirft createSendGroup() einen InvalidStateError.
Priorisierung ist ein Hinweis an den Sendeplaner des Browsers; es gibt keine harte Garantie für die Reihenfolge der Zustellung.
WebTransport ist nur in sicheren Kontexten (HTTPS) und über HTTP/3 verfügbar.

Siehe auch

WebTransport WebTransportSendGroup WebTransport.createUnidirectionalStream() WebTransport.createBidirectionalStream() WebTransportSendStream WebTransportSendGroup.getStats()