WebTransport — Schnittstelle · JavaScript-Referenz

Signatur

interface WebTransport

Beschreibung

Die Schnittstelle WebTransport ist der Einstiegspunkt der WebTransport API. Sie baut über HTTP/3 (QUIC) eine Sitzung zu einem Server auf. Über diese Sitzung laufen mehrere unabhängige Datenkanäle gleichzeitig: zuverlässige, geordnete Streams (unidirektional oder bidirektional) und unzuverlässige, ungeordnete Datagramme. Damit eignet sich WebTransport für Echtzeit-Anwendungen wie Spiele, Live-Streaming, Telemetrie oder kollaboratives Arbeiten mit geringer Latenz.

Im Unterschied zu WebSocket gibt es kein Head-of-Line-Blocking zwischen Streams: Geht ein Paket verloren, wartet nur der betroffene Stream darauf. Datagramme werden gar nicht erneut gesendet, was für zeitkritische Daten ideal ist, bei denen ein verspätetes Paket ohnehin wertlos wäre (z. B. Positionsdaten). Alle Kanäle basieren auf der Streams API (ReadableStream/WritableStream) und unterstützen Gegendruck (Backpressure).

Wichtige Mitglieder:

ready: Promise, das erfüllt wird, sobald die Verbindung steht.
closed: Promise, das beim Schließen mit { closeCode, reason } erfüllt oder bei Fehlern abgelehnt wird.
datagrams: WebTransportDatagramDuplexStream mit readable und writable.
createBidirectionalStream() / createUnidirectionalStream(): öffnen ausgehende Streams.
incomingBidirectionalStreams / incomingUnidirectionalStreams: ReadableStreams der vom Server geöffneten Streams.
close({ closeCode, reason }): beendet die Sitzung sauber.
getStats(): liefert Verbindungsstatistiken (RTT, übertragene Bytes …).

Die API steht nur in sicheren Kontexten (HTTPS) und in Web Workern zur Verfügung. Der Server muss HTTP/3 mit WebTransport-Erweiterung unterstützen (z. B. über aioquic, quic-go/webtransport-go oder Node-Bibliotheken).

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Adresse des WebTransport-Servers; muss das Schema `https:` verwenden.
$options	object	{}	Optionale Einstellungen für den Konstruktor `new WebTransport(url, options)`.
$options.allowPooling	boolean	false	Erlaubt, dass sich die Sitzung eine QUIC-Verbindung mit anderen Sitzungen teilt.
$options.requireUnreliable	boolean	false	Bei `true` schlägt der Aufbau fehl, wenn keine HTTP/3-Verbindung (mit Datagrammen) möglich ist.
$options.serverCertificateHashes	Array<{algorithm: string, value: BufferSource}>		SHA-256-Hashes selbstsignierter Zertifikate (max. 14 Tage gültig), z. B. für lokale Entwicklung ohne öffentliche CA.
$options.congestionControl	"default" \| "throughput" \| "low-latency"	"default"	Hinweis an den Browser, ob Durchsatz oder geringe Latenz priorisiert werden soll.
$options.protocols	string[]	[]	Anwendungsprotokolle zur Aushandlung mit dem Server (neuere Spezifikation, noch nicht überall unterstützt).

Rückgabewert

Typ

WebTransport

Beschreibung

Eine neue WebTransport-Instanz. Der Verbindungsaufbau läuft asynchron; auf transport.ready warten, bevor Daten gesendet werden.

Beispiele

Verbindung aufbauen und Schließen überwachen

const connect = async () => {
  const transport = new WebTransport('https://example.com:4433/game');

  // Schließen bzw. Abbruch protokollieren
  transport.closed
    .then(({ closeCode, reason }) => console.log(`Geschlossen: ${closeCode} ${reason}`))
    .catch((err) => console.error('Verbindung abgebrochen:', err));

  await transport.ready;
  console.log('WebTransport verbunden');
  return transport;
};

const transport = await connect();

WebTransport verbunden

Unzuverlässige Datagramme senden und empfangen

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

const encoder = new TextEncoder();
const decoder = new TextDecoder();

// Position senden – verlorene Pakete sind hier egal
const writer = transport.datagrams.writable.getWriter();
await writer.write(encoder.encode(JSON.stringify({ x: 10, y: 20 })));

// Eingehende Datagramme lesen
const reader = transport.datagrams.readable.getReader();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log('Datagramm:', decoder.decode(value));
}

Datagramm: {"x":12,"y":18}

Bidirektionalen Stream für Anfrage/Antwort nutzen

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

const stream = await transport.createBidirectionalStream();
const writer = stream.writable.getWriter();
await writer.write(new TextEncoder().encode('PING'));
await writer.close(); // signalisiert Ende der Anfrage

// Antwort vollständig einlesen (zuverlässig und geordnet)
const text = await new Response(stream.readable).text();
console.log('Antwort:', text);

transport.close({ closeCode: 0, reason: 'fertig' });

Antwort: PONG

Vom Server geöffnete unidirektionale Streams verarbeiten

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

const handleStream = async (readable) => {
  const text = await new Response(readable).text();
  console.log('Server-Nachricht:', text);
};

const reader = transport.incomingUnidirectionalStreams.getReader();
while (true) {
  const { value: readable, done } = await reader.read();
  if (done) break;
  handleStream(readable); // jeden Stream parallel abarbeiten
}

Server-Nachricht: update #1

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser seit Version 97, Firefox seit 114, Safari erst ab 26.4. Vorher per 'WebTransport' in globalThis prüfen und ggf. auf WebSocket ausweichen.
Nur in sicheren Kontexten (HTTPS, localhost) verfügbar; die Ziel-URL muss https: sein. Serverseitig ist HTTP/3 mit WebTransport-Unterstützung nötig, das bieten klassische HTTP/1.1-/HTTP/2-Server nicht.
Datagramme haben eine begrenzte Größe (transport.datagrams.maxDatagramSize, meist ca. 1200 Byte). Größere Nutzdaten stillschweigend verwerfen oder in Streams senden.
Ohne Behandlung von transport.closed und ready gibt es unbehandelte Promise-Ablehnungen. Verbindungsfehler immer mit try/catch abfangen.
serverCertificateHashes gilt nur für Zertifikate mit höchstens 14 Tagen Laufzeit und ECDSA-Schlüssel. Das ist für die Entwicklung gedacht, nicht als Ersatz für echte Zertifikate.
Unternehmens-Firewalls blockieren UDP/QUIC manchmal. Einen Rückfall auf WebSocket einplanen.
Sicherheit: Eingehende Daten sind nicht vertrauenswürdig. Sie müssen validiert werden, bevor sie ins DOM gelangen (XSS). Der Server sollte den Origin-Header der Sitzung prüfen.

Siehe auch

WebSocket ReadableStream WritableStream WebTransportBidirectionalStream WebTransportDatagramDuplexStream WebTransportError RTCDataChannel