Signatur
Beschreibung
Die Eigenschaft protocol einer WebTransport-Instanz gibt an, auf welches Anwendungsprotokoll sich Client und Server beim Verbindungsaufbau geeinigt haben. Das Prinzip entspricht den Subprotokollen bei WebSocket: Der Client bietet im Konstruktor über die Option protocols eine Liste von Protokollnamen an, zum Beispiel ["chat-v2", "chat-v1"]`, und der Server wählt genau eines davon aus. Beim Handshake werden dafür HTTP-Header verwendet (WT-Available-Protocols bzw. WT-Protocol).
Der Wert ist erst dann sinnvoll, wenn die Sitzung aufgebaut ist, also nachdem das Promise transport.ready erfüllt wurde. Vorher, oder wenn der Server kein Protokoll ausgewählt hat, ist der Wert ein leerer String "".
Einsatzgebiete sind vor allem Versionierung und Aushandeln von Funktionen: Ein Client kann mehrere Versionen seines Nachrichtenformats unterstützen und sein Verhalten danach richten, welche Version der Server bestätigt. So lassen sich Server-Updates ausrollen, ohne dass ältere Clients sofort nicht mehr funktionieren.
Rückgabewert
"", wenn kein Protokoll ausgehandelt wurde oder die Verbindung noch nicht bereit ist.Beispiele
Ausgehandeltes Protokoll nach dem Verbindungsaufbau lesen
const transport = new WebTransport('https://example.com:4433/wt', {
protocols: ['chat-v2', 'chat-v1']
});
console.log('Vor ready:', JSON.stringify(transport.protocol));
await transport.ready;
console.log('Ausgehandelt:', transport.protocol);Nachrichtenformat je nach Protokollversion wählen
const encoders = {
'chat-v2': (msg) => new TextEncoder().encode(JSON.stringify({ v: 2, ...msg })),
'chat-v1': (msg) => new TextEncoder().encode(msg.text)
};
const connect = async (url) => {
const transport = new WebTransport(url, { protocols: Object.keys(encoders) });
await transport.ready;
const encode = encoders[transport.protocol];
if (!encode) {
// Server hat kein (bekanntes) Protokoll ausgewählt
transport.close({ closeCode: 4000, reason: 'Kein unterstütztes Protokoll' });
throw new Error('Protokollaushandlung fehlgeschlagen');
}
const writer = transport.datagrams.writable.getWriter();
await writer.write(encode({ text: 'Hallo!' }));
return transport;
};
await connect('https://example.com:4433/chat');Funktionserkennung und Fallback
const supportsProtocols = 'WebTransport' in globalThis &&
'protocol' in WebTransport.prototype;
console.log(supportsProtocols
? 'Protokollaushandlung verfügbar'
: 'Keine Protokollaushandlung – Version z. B. per URL-Parameter übermitteln');// Wichtig · Fallstricke
- Erst nach
readylesen: Vor dem Aufbau der Sitzung ist der Wert immer"". Lesen Sie ihn deshalb erst nachawait transport.ready. - Leerer String ist ein gültiges Ergebnis: Unterstützt der Server keine Protokollaushandlung oder wählt er keines der angebotenen Protokolle, bleibt der Wert leer. Die Verbindung kann trotzdem bestehen, deshalb sollten Sie diesen Fall ausdrücklich behandeln.
- Schreibgeschützt: Eine Zuweisung hat keine Wirkung. Das Protokoll lässt sich nur über die Konstruktoroption
protocolsbeeinflussen. Doppelte oder ungültige Einträge können im Konstruktor einenSyntaxErrorauslösen. - Kompatibilität: WebTransport gibt es nur in sicheren Kontexten (HTTPS), im Fenster und in Web Workern. Die Option
protocolsund die Eigenschaftprotocolkamen erst später zur Spezifikation hinzu und fehlen in älteren Browserversionen, auch wenn diese WebTransport selbst schon unterstützen. Safari unterstützt WebTransport bisher nur eingeschränkt oder gar nicht. Prüfen Sie die Verfügbarkeit per Funktionserkennung. - Sicherheit: Das ausgehandelte Protokoll sagt nur, dass sich beide Seiten auf ein Format geeinigt haben. Es ersetzt keine Authentifizierung und keine Prüfung der Eingaben auf dem Server.