Signatur
new WebTransport(url, options)
Beschreibung
Der Konstruktor WebTransport() startet eine WebTransport-Sitzung über HTTP/3 (QUIC) zur angegebenen https://-URL. Die Verbindung wird sofort beim Erzeugen aufgebaut. Ob sie klappt, erfährst du über das Promise transport.ready. Das Ende der Sitzung meldet transport.closed.
WebTransport ist ein moderner Ersatz für WebSockets, wenn du niedrige Latenz brauchst oder mehrere unabhängige Streams ohne Head-of-Line-Blocking. Es eignet sich auch für unzuverlässige Datagramme, etwa bei Spielen, Echtzeit-Telemetrie, Audio und Video oder Cloud-Gaming. Nach dem Aufbau stehen dir transport.datagrams, createBidirectionalStream(), createUnidirectionalStream() sowie die eingehenden Streams incomingBidirectionalStreams und incomingUnidirectionalStreams zur Verfügung.
Über das Objekt options steuerst du:
- ob die Verbindung mit anderen Sitzungen geteilt werden darf (Pooling),
- ob unzuverlässiger Transport, also Datagramme, zwingend verfügbar sein muss,
- welches Verfahren zur Überlastkontrolle bevorzugt wird,
- welchen Server-Zertifikaten per Hash vertraut wird, etwa bei selbstsignierten Zertifikaten in der Entwicklung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $url Pflicht | string | URL | Adresse des WebTransport-Servers. Sie muss das Schema https: verwenden, z. B. https://example.com:4433/chat. |
|
| $options | object | {} | Optionales Konfigurationsobjekt mit den folgenden Eigenschaften. |
| $options.allowPooling | boolean | false | Bei true darf die Sitzung eine bestehende HTTP/3-Verbindung mit anderen Sitzungen teilen. |
| $options.requireUnreliable | boolean | false | Bei true schlägt der Aufbau fehl, wenn keine HTTP/3-Verbindung mit Datagramm-Unterstützung möglich ist. Ein Rückfall auf HTTP/2 ist dann ausgeschlossen. |
| $options.congestionControl | "default" | "throughput" | "low-latency" | "default" | Wunsch für die Überlastkontrolle: optimiert auf Durchsatz oder auf niedrige Latenz. Der Browser behandelt das nur als Hinweis. |
| $options.serverCertificateHashes | Array<{algorithm: string, value: BufferSource}> | Liste von Zertifikat-Hashes (derzeit nur algorithm: "sha-256"). Damit wird ein Server akzeptiert, dessen Zertifikat nicht von einer öffentlichen Zertifizierungsstelle stammt. Das Zertifikat darf höchstens 14 Tage gültig sein. Die Option lässt sich nicht mit allowPooling: true kombinieren. |
|
| $options.protocols | string[] | [] | Neuere Ergänzung: Liste der gewünschten Anwendungsprotokolle, aus denen der Server eines auswählt (vergleichbar mit WebSocket-Subprotokollen). Nicht in allen Browsern verfügbar. |
Rückgabewert
Typ
WebTransport
Beschreibung
Eine neue
WebTransport-Instanz, deren Verbindungsaufbau bereits läuft. Mit await transport.ready wartest du, bis die Verbindung steht.Beispiele
Verbindung aufbauen und auf Bereitschaft warten
const connect = async () => {
const transport = new WebTransport('https://example.com:4433/echo');
// Ende der Sitzung überwachen
transport.closed
.then(({ closeCode, reason }) => console.log('Geschlossen:', closeCode, reason))
.catch((err) => console.error('Verbindung abgebrochen:', err));
try {
await transport.ready;
console.log('WebTransport verbunden');
return transport;
} catch (err) {
console.error('Verbindungsaufbau fehlgeschlagen:', err);
throw err;
}
};
connect();WebTransport verbunden
Datagramme für Echtzeit-Positionen senden und empfangen
const transport = new WebTransport('https://game.example.com:4433/state', {
requireUnreliable: true,
congestionControl: 'low-latency'
});
await transport.ready;
const encoder = new TextEncoder();
const decoder = new TextDecoder();
// Senden
const writer = transport.datagrams.writable.getWriter();
await writer.write(encoder.encode(JSON.stringify({ x: 10, y: 20 })));
// Empfangen
const reader = transport.datagrams.readable.getReader();
while (true) {
const { value, done } = await reader.read();
if (done) break;
console.log('Update:', decoder.decode(value));
}Update: {"x":12,"y":21}
Bidirektionalen Stream für eine Anfrage/Antwort nutzen
const transport = new WebTransport('https://api.example.com:4433/rpc');
await transport.ready;
const stream = await transport.createBidirectionalStream();
const writer = stream.writable.getWriter();
await writer.write(new TextEncoder().encode('PING'));
await writer.close();
const response = await new Response(stream.readable).text();
console.log('Antwort:', response);
transport.close({ closeCode: 0, reason: 'fertig' });Antwort: PONG
Lokale Entwicklung mit selbstsigniertem Zertifikat
// SHA-256-Hash des Server-Zertifikats als Hex-String (z. B. per openssl ermittelt)
const certHashHex = '3a1f...'; // vollständigen 64-stelligen Hash einsetzen
const hashBytes = new Uint8Array(
certHashHex.match(/../g).map((h) => parseInt(h, 16))
);
const transport = new WebTransport('https://localhost:4433/dev', {
serverCertificateHashes: [{ algorithm: 'sha-256', value: hashBytes }]
});
await transport.ready;
console.log('Mit lokalem Dev-Server verbunden');Mit lokalem Dev-Server verbunden