WebTransport.ready — Eigenschaft · JavaScript-Referenz

Signatur

WebTransport.ready

Beschreibung

Die Eigenschaft ready einer WebTransport-Instanz gibt ein Promise<undefined> zurück. Es wird erfüllt, sobald der HTTP/3-Handshake mit dem Server abgeschlossen ist und die Sitzung Datenströme (Streams) und Datagramme übertragen kann. Schlägt der Verbindungsaufbau fehl, etwa weil der Server nicht erreichbar ist, das Zertifikat ungültig ist oder der Server die Sitzung ablehnt, wird das Promise mit einem WebTransportError abgelehnt.

Warten Sie mit await transport.ready, bevor Sie Streams öffnen (createBidirectionalStream(), createUnidirectionalStream()) oder in transport.datagrams.writable schreiben. Das ist nicht in jedem Fall zwingend nötig, weil manche Operationen intern ebenfalls warten. Es macht den Code aber gut lesbar und bündelt die Fehlerbehandlung für den Verbindungsaufbau an einer Stelle.

Das Promise ist ab dem Konstruktoraufruf vorhanden und wird nie ausgetauscht. Sie können es also beliebig oft und an mehreren Stellen abfragen. Das Gegenstück ist WebTransport.closed: Es wird erfüllt oder abgelehnt, wenn die Sitzung endet.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Verbindung steht. Scheitert der Verbindungsaufbau, wird es mit einem WebTransportError abgelehnt.

Beispiele

Auf den Verbindungsaufbau warten

const connect = async (url) => {
  const transport = new WebTransport(url);
  try {
    await transport.ready;
    console.log('WebTransport-Verbindung steht');
    return transport;
  } catch (err) {
    console.error('Verbindung fehlgeschlagen:', err.message);
    throw err;
  }
};

const transport = await connect('https://example.com:4433/wt');

WebTransport-Verbindung steht

Nach ready ein Datagramm senden

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

const writer = transport.datagrams.writable.getWriter();
const data = new TextEncoder().encode('Hallo Server!');
await writer.write(data);
writer.releaseLock();
console.log('Datagramm gesendet');

Datagramm gesendet

Bidirektionaler Stream mit Zeitlimit für den Verbindungsaufbau

const withTimeout = (promise, ms) =>
  Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Timeout beim Verbindungsaufbau')), ms)
    )
  ]);

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

try {
  await withTimeout(transport.ready, 5000);
  const stream = await transport.createBidirectionalStream();
  const writer = stream.writable.getWriter();
  await writer.write(new TextEncoder().encode('ping'));
  await writer.close();

  const reader = stream.readable.getReader();
  const { value } = await reader.read();
  console.log('Antwort:', new TextDecoder().decode(value));
} catch (err) {
  console.error(err.message);
  transport.close();
}

Antwort: ping

// Wichtig · Fallstricke

Ablehnung behandeln: Ein fehlgeschlagener Verbindungsaufbau lehnt ready ab. Ohne try/catch oder .catch() führt das zu einer unhandled rejection. Auch closed wird in diesem Fall abgelehnt, also sollten Sie beide Promises abfangen.
Kein eingebautes Zeitlimit: Wie lange der Verbindungsaufbau dauern darf, bestimmt der Browser. Ein eigenes Zeitlimit lässt sich z. B. mit Promise.race() umsetzen.
Sichere Umgebung: WebTransport funktioniert nur in sicheren Kontexten (HTTPS) und setzt einen Server voraus, der HTTP/3 bzw. QUIC unterstützt. Selbstsignierte Zertifikate sind nur über die Option serverCertificateHashes möglich.
Browser-Kompatibilität: Unterstützt von Chromium-Browsern ab Version 97 und Firefox ab 114. Safari unterstützt WebTransport derzeit nicht, daher vorher prüfen: 'WebTransport' in globalThis.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung.

Siehe auch

WebTransport WebTransport.closed WebTransport.close() WebTransport.createBidirectionalStream() WebTransport.datagrams WebTransportError ImageTrackList.ready