WebTransport API

Konzepte und Verwendung

HTTP/3 ist seit 2018 in Arbeit. Es basiert auf dem von Google entwickelten QUIC-Protokoll (das selbst auf UDP basiert) und behebt mehrere Probleme des klassischen TCP-Protokolls, auf dem HTTP und WebSockets basieren.

Dazu gehören:

Head-of-line blocking

HTTP/2 erlaubt Multiplexing, sodass eine einzelne Verbindung mehrere Ressourcen gleichzeitig streamen kann. Wenn jedoch eine einzelne Ressource fehlschlägt, werden alle anderen Ressourcen dieser Verbindung zurückgehalten, bis fehlende Pakete erneut übertragen werden. Bei QUIC wird nur die fehlerhafte Ressource beeinflusst.

Schnellere Leistung

QUIC ist in vielerlei Hinsicht leistungsfähiger als TCP. Es kann Sicherheitsfunktionen selbst verwalten, anstatt die Verantwortung an andere Protokolle wie TLS zu übergeben, was weniger Round-Trips bedeutet. Und Streams bieten bessere Transporteffizienz als der ältere Paketmechanismus. Das kann einen erheblichen Unterschied machen, insbesondere in Hochlatenz-Netzwerken.

Bessere Netzwerkübergänge

QUIC verwendet eine einzigartige Verbindungs-ID, um die Quelle und das Ziel jeder Anfrage zu verwalten - um sicherzustellen, dass Pakete korrekt zugestellt werden. Diese ID kann zwischen verschiedenen Netzwerken bestehen bleiben, was bedeutet, dass ein Download zum Beispiel fortgesetzt werden kann, ohne unterbrochen zu werden, wenn Sie von einem Wi-Fi- zu einem Mobilnetzwerk wechseln. HTTP/2 hingegen verwendet IP-Adressen als Bezeichner, sodass Netzwerkübergänge problematisch sein können.

Unzuverlässiger Transport

HTTP/3 unterstützt die unzuverlässige Datenübertragung über Datagramme.

Die WebTransport API bietet einen Low-Level-Zugang zu einer bidirektionalen Kommunikation über HTTP/3, nutzt die oben genannten Vorteile und unterstützt sowohl zuverlässige als auch unzuverlässige Datenübertragung.

Initiale Verbindung

Um eine Verbindung zu einem HTTP/3-Server herzustellen, übergeben Sie seine URL an den WebTransport()-Konstruktor. Beachten Sie, dass das Schema HTTPS sein muss und die Portnummer explizit angegeben werden muss. Sobald das Versprechen WebTransport.ready erfüllt ist, können Sie die Verbindung nutzen.

Außerdem können Sie auf das Schließen der Verbindung reagieren, indem Sie auf das Erfüllen des Versprechens WebTransport.closed warten. Fehler, die durch WebTransport-Operationen zurückgegeben werden, sind vom Typ WebTransportError und enthalten zusätzliche Daten über den Standard-Datensatz DOMException hinaus.

const url = "https://example.com:4999/wt";

async function initTransport(url) {
  // Initialize transport connection
  const transport = new WebTransport(url);

  // The connection can be used once ready fulfills
  await transport.ready;

  // …
}

// …

async function closeTransport(transport) {
  // Respond to connection closing
  try {
    await transport.closed;
    console.log(`The HTTP/3 connection to ${url} closed gracefully.`);
  } catch (error) {
    console.error(`The HTTP/3 connection to ${url} closed due to ${error}.`);
  }
}

Aushandlung eines Anwendungsprotokolls

Ein WebTransport-Server kann mehrere Anwendungen unterstützen, die jeweils ihr eigenes „benutzerdefiniertes“ Kommunikationsprotokoll verwenden. Um dies zu unterstützen, kann der Client eine Liste von Protokollnamen in Präferenzreihenfolge über die protocols-Option des WebTransport()-Konstruktors anbieten. Der Server kann dann während der Verbindungsherstellung eines dieser Protokolle auswählen.

Sobald das Versprechen WebTransport.ready erfüllt ist, ist das ausgehandelte Protokoll (falls vorhanden) über die Eigenschaft WebTransport.protocol verfügbar. Dies ist der leere String, wenn protocols nicht verwendet wurde oder der Server keines der angebotenen Protokolle ausgewählt hat. Ein Server, der keines der angebotenen Protokolle unterstützt, kann stattdessen die Verbindung ablehnen, wodurch ready zurückgewiesen wird.

const url = "https://example.com:4999/wt";

async function initTransport(url) {
  const transport = new WebTransport(url, {
    protocols: ["chat", "file-transfer"],
  });

  try {
    await transport.ready;
    console.log(transport.protocol); // e.g. "chat", or "" if none was selected
    return transport;
  } catch (error) {
    console.error(`Connection failed: ${error}`);
  }
}

Unzuverlässige Übertragung über Datagramme

„Unzuverlässig“ bedeutet, dass die Übertragung von Daten nicht garantiert wird, noch ihre Ankunft in einer bestimmten Reihenfolge. Dies ist in manchen Situationen in Ordnung und liefert sehr schnelle Ergebnisse. Zum Beispiel könnten Sie regelmäßige Aktualisierungen des Spielstatus übertragen wollen, bei denen jede Nachricht die letzte, die ankommt, überschreibt und die Reihenfolge nicht wichtig ist.

Die unzuverlässige Datenübertragung wird über die Eigenschaft WebTransport.datagrams gehandhabt — dies gibt ein WebTransportDatagramDuplexStream-Objekt zurück, das alles enthält, was Sie benötigen, um Datagramme an den Server zu senden und zurück zu empfangen.

Die Eigenschaft WebTransportDatagramDuplexStream.writable gibt ein WritableStream-Objekt zurück, in das Sie Daten zum Senden an den Server schreiben können:

const writer = transport.datagrams.writable.getWriter();
const data1 = new Uint8Array([65, 66, 67]);
const data2 = new Uint8Array([68, 69, 70]);
writer.write(data1);
writer.write(data2);

Die Eigenschaft WebTransportDatagramDuplexStream.readable gibt ein ReadableStream-Objekt zurück, das Sie verwenden können, um Daten vom Server zu empfangen:

async function readData() {
  const reader = transport.datagrams.readable.getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array.
    console.log(value);
  }
}

Zuverlässige Übertragung über Streams

„Zuverlässig“ bedeutet, dass Übertragung und Reihenfolge der Daten garantiert sind. Dies bietet eine langsamere Lieferung (wenngleich schneller als mit WebSockets) und ist in Situationen erforderlich, in denen Zuverlässigkeit und Reihenfolge wichtig sind (wie beispielsweise bei Chat-Anwendungen).

Bei der Verwendung von zuverlässiger Übertragung über Streams können Sie außerdem die relative Priorität verschiedener Streams über den gleichen Transport festlegen.

Unidirektionale Übertragung

Um einen unidirektionalen Stream von einem User-Agent zu öffnen, verwenden Sie die Methode WebTransport.createUnidirectionalStream(), um eine Referenz zu einem WritableStream zu erhalten. Von diesem aus können Sie einen Writer erhalten, um Daten in den Stream zu schreiben und an den Server zu senden.

async function writeData() {
  const stream = await transport.createUnidirectionalStream();
  const writer = stream.writable.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);

  try {
    await writer.close();
    console.log("All data has been sent.");
  } catch (error) {
    console.error(`An error occurred: ${error}`);
  }
}

Beachten Sie auch die Nutzung der Methode WritableStreamDefaultWriter.close(), um die zugehörige HTTP/3-Verbindung zu schließen, sobald alle Daten gesendet wurden.

Wenn der Server einen unidirektionalen Stream öffnet, um Daten an den Client zu übertragen, kann dieser auf dem Client über die Eigenschaft WebTransport.incomingUnidirectionalStreams zugegriffen werden, die einen ReadableStream von WebTransportReceiveStream-Objekten zurückgibt. Diese können verwendet werden, um Uint8Array-Instanzen zu lesen, die vom Server gesendet werden.

In diesem Fall ist der erste Schritt, eine Funktion einzurichten, um einen WebTransportReceiveStream zu lesen. Diese Objekte erben von der ReadableStream-Klasse, sodass sie auf die gleiche Weise verwendet werden können:

async function readData(receiveStream) {
  const reader = receiveStream.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array
    console.log(value);
  }
}

Als nächstes rufen Sie WebTransport.incomingUnidirectionalStreams auf und erhalten eine Referenz auf den Leser, der auf dem ReadableStream, den es zurückgibt, verfügbar ist, und verwenden dann den Leser, um die Daten vom Server zu lesen. Jeder Chunk ist ein WebTransportReceiveStream und wir nutzen das zuvor eingerichtete readFrom(), um sie zu lesen:

async function receiveUnidirectional() {
  const uds = transport.incomingUnidirectionalStreams;
  const reader = uds.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    }
    // value is an instance of WebTransportReceiveStream
    await readData(value);
  }
}

Bidirektionale Übertragung

Um einen bidirektionalen Stream von einem User-Agent zu öffnen, verwenden Sie die Methode WebTransport.createBidirectionalStream(), um eine Referenz zu einem WebTransportBidirectionalStream zu erhalten. Dieses enthält readable und writable Eigenschaften, die Referenzen zu WebTransportReceiveStream und WebTransportSendStream Instanzen zurückgeben, die verwendet werden können, um Daten vom und zum Server zu lesen und zu schreiben.

async function setUpBidirectional() {
  const stream = await transport.createBidirectionalStream();
  // stream is a WebTransportBidirectionalStream
  // stream.readable is a WebTransportReceiveStream
  const readable = stream.readable;
  // stream.writable is a WebTransportSendStream
  const writable = stream.writable;

  // …
}

Lesen vom WebTransportReceiveStream kann dann wie folgt durchgeführt werden:

async function readData(readable) {
  const reader = readable.getReader();
  while (true) {
    const { value, done } = await reader.read();
    if (done) {
      break;
    }
    // value is a Uint8Array.
    console.log(value);
  }
}

Und das Schreiben in den WebTransportSendStream kann so gemacht werden:

async function writeData(writable) {
  const writer = writable.getWriter();
  const data1 = new Uint8Array([65, 66, 67]);
  const data2 = new Uint8Array([68, 69, 70]);
  writer.write(data1);
  writer.write(data2);
}

Wenn der Server einen bidirektionalen Stream öffnet, um Daten zu übertragen und vom Client zu empfangen, kann darauf über die Eigenschaft WebTransport.incomingBidirectionalStreams zugegriffen werden, die einen ReadableStream von WebTransportBidirectionalStream-Objekten zurückgibt. Jede kann verwendet werden, um Uint8Array-Instanzen wie oben gezeigt zu lesen und zu schreiben. Allerdings benötigen Sie, wie im unidirektionalen Beispiel, eine anfängliche Funktion, um den bidirektionalen Stream zunächst zu lesen:

async function receiveBidirectional() {
  const bds = transport.incomingBidirectionalStreams;
  const reader = bds.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) {
      break;
    }
    // value is an instance of WebTransportBidirectionalStream
    await readData(value.readable);
    await writeData(value.writable);
  }
}

Schnittstellen

WebTransport

Bietet Funktionalität, um einem User-Agent zu ermöglichen, eine Verbindung zu einem HTTP/3-Server herzustellen, zuverlässige und unzuverlässige Transporte in eine oder beide Richtungen zu initiieren und die Verbindung zu schließen, sobald sie nicht mehr benötigt wird.

WebTransportBidirectionalStream

Stellt einen bidirektionalen Stream dar, der von einem Server oder Client erstellt wurde, der für den zuverlässigen Transport verwendet werden kann. Bietet Zugriff auf einen ReadableStream für das Lesen eingehender Daten und einen WritableStream für das Schreiben ausgehender Daten.

WebTransportDatagramDuplexStream

Stellt einen Duplex-Stream dar, der für den unzuverlässigen Transport von Datagrammen zwischen Client und Server verwendet werden kann. Bietet Zugriff auf einen ReadableStream für das Lesen eingehender Datagramme, einen WritableStream für das Schreiben ausgehender Datagramme sowie verschiedene Einstellungen und Statistiken, die den Stream betreffen.

WebTransportError

Stellt einen Fehler dar, der mit der WebTransport API verbunden ist und durch Serverfehler, Netzwerkverbindungsprobleme oder vom Client initiierte Abbruchvorgänge (zum Beispiel durch einen Aufruf von WritableStream.abort()) hervorgerufen werden kann.

WebTransportReceiveStream

Bietet Streaming-Features für einen eingehenden unidirektionalen oder bidirektionalen WebTransport-Stream des WebTransport.

WebTransportSendStream

Bietet Streaming-Features für einen ausgehenden unidirektionalen oder bidirektionalen WebTransport-Stream des WebTransport.

Beispiele

Für vollständige Beispiele siehe:

• WebTransport über HTTP/3 Client

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Verwendung von WebTransport
• WebSockets API
• Streams API
• WebTransport über HTTP/3