WebTransport API

Konzepte und Verwendung

HTTP/3 wurde 2022 nach mehreren Jahren Entwicklung standardisiert. Es basiert auf dem QUIC-Protokoll (das seinerseits auf UDP basiert und 2021 standardisiert wurde) und behebt mehrere Probleme des klassischen TCP-Protokolls, auf dem HTTP und WebSockets basieren.

Dazu gehören:

Head-of-line blocking

HTTP/2 ermöglicht Multiplexing, sodass eine einzelne Verbindung mehrere Ressourcen gleichzeitig streamen kann. Wenn jedoch eine einzelne Ressource fehlschlägt, werden alle anderen Ressourcen auf dieser Verbindung aufgehalten, bis fehlende Pakete erneut übertragen wurden. Mit QUIC ist nur die fehlschlagende Ressource betroffen.

Schnellere Leistung

QUIC ist TCP in vielerlei Hinsicht leistungsfähiger. QUIC kann Sicherheitsfunktionen selbst handhaben, anstatt die Verantwortung an andere Protokolle wie TLS zu übergeben — was weniger Roundtrips bedeutet. Und Streams bieten eine bessere Transporteffizienz als der ältere Paketmechanismus. Das kann insbesondere in Netzwerken mit hoher Latenz einen erheblichen Unterschied ausmachen.

Bessere Netzwerkübergänge

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

Unzuverlässiger Transport

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

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

Anfängliche Verbindung

Um eine Verbindung zu einem HTTP/3-Server zu öffnen, übergeben Sie dessen URL an den Konstruktor WebTransport(). Beachten Sie, dass das Schema HTTPS sein und die Portnummer ausdrücklich angegeben werden muss. Sobald das Promise WebTransport.ready erfüllt ist, können Sie die Verbindung verwenden.

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;

  // …
}

Schließen der Verbindung

Sie können auf das Schließen der Verbindung reagieren, indem Sie darauf warten, dass das Promise WebTransport.closed erfüllt wird. Von WebTransport-Operationen zurückgegebene Fehler haben den Typ WebTransportError und enthalten zusätzlich zu den Standardinformationen von DOMException weitere Daten.

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}.`);
  }
}

Der Server kann auch angeben, dass er die Verbindung vor dem Schließen leeren möchte, etwa aufgrund der Verwaltung des zugrunde liegenden Transports. Wenn dies geschieht, sollte der Client beginnen, Streams zu schließen, und eine neue Sitzung erstellen, falls er seine Arbeit fortsetzen muss. Sie können dies mithilfe des Promise WebTransport.draining erkennen, das erfüllt wird, sobald der Server signalisiert, dass die Sitzung in den Leerungszustand übergeht:

async function watchForDraining(transport) {
  // Fulfills when the server signals that the session is draining
  await transport.draining;

  console.log("The session is draining: avoid opening new streams.");
}

Aushandeln eines Anwendungsprotokolls

Ein WebTransport-Server kann mehrere Anwendungen unterstützen, die jeweils ein eigenes „benutzerdefiniertes“ Kommunikationsprotokoll verwenden. Um dies zu unterstützen, kann der Client über die Option protocols des WebTransport()-Konstruktors eine Liste möglicher Protokollnamen in bevorzugter Reihenfolge anbieten. Der Server kann dann während des Verbindungsaufbaus eines davon auswählen.

Sobald das Promise WebTransport.ready erfüllt ist, ist das ausgehandelte Protokoll, falls vorhanden, über die Eigenschaft WebTransport.protocol verfügbar. Dies ist die leere Zeichenfolge, wenn protocols nicht verwendet wurde oder wenn der Server keines der angebotenen Protokolle ausgewählt hat. Ein Server, der keines der angebotenen Protokolle unterstützt, kann die Verbindung stattdessen direkt ablehnen, wodurch ready abgelehnt 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 ist und auch nicht ihre Ankunft in einer bestimmten Reihenfolge. Dies ist in einigen Situationen ausreichend und ermöglicht eine sehr schnelle Zustellung. Beispielsweise möchten Sie möglicherweise regelmäßige Aktualisierungen des Spielzustands übertragen, bei denen jede Nachricht die zuletzt eingetroffene ersetzt und die Reihenfolge nicht wichtig ist.

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

Die Eigenschaft WebTransportDatagramDuplexStream.writable gibt ein WritableStream-Objekt zurück, in das Sie mithilfe eines Writers Daten zur Übertragung 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 zum Empfangen von Daten vom Server verwenden können:

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 die Übertragung und die Reihenfolge der Daten garantiert sind. Dies ermöglicht eine langsamere Zustellung, wenn auch schneller als mit WebSockets, und wird in Situationen benötigt, in denen Zuverlässigkeit und Reihenfolge wichtig sind, beispielsweise in Chat-Anwendungen.

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

Unidirektionale Übertragung

Um einen unidirektionalen Stream von einem User Agent aus zu öffnen, verwenden Sie die Methode WebTransport.createUnidirectionalStream(), um eine Referenz auf einen WritableStream zu erhalten. Daraus können Sie einen Writer abrufen, 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 Verwendung 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 auf diesen beim Client über die Eigenschaft WebTransport.incomingUnidirectionalStreams zugegriffen werden, die einen ReadableStream von WebTransportReceiveStream-Objekten zurückgibt. Diese können verwendet werden, um vom Server gesendete Uint8Array-Instanzen zu lesen.

In diesem Fall müssen Sie zunächst eine Funktion einrichten, um einen WebTransportReceiveStream zu lesen. Diese Objekte erben von der Klasse ReadableStream und können daher auf genau dieselbe Weise verwendet werden:

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);
  }
}

Rufen Sie als Nächstes WebTransport.incomingUnidirectionalStreams auf, holen Sie eine Referenz auf den Reader, der im zurückgegebenen ReadableStream verfügbar ist, und verwenden Sie den Reader anschließend, um die Daten vom Server zu lesen. Jeder Chunk ist ein WebTransportReceiveStream, und wir verwenden 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 aus zu öffnen, verwenden Sie die Methode WebTransport.createBidirectionalStream(), um eine Referenz auf einen WebTransportBidirectionalStream zu erhalten. Dieser enthält die Eigenschaften readable und writable, die Referenzen auf WebTransportReceiveStream- bzw. WebTransportSendStream-Instanzen zurückgeben, die zum Lesen vom und Schreiben auf den Server verwendet werden können.

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;

  // …
}

Das Lesen aus dem WebTransportReceiveStream kann dann wie folgt erfolgen:

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);
  }
}

Das Schreiben in den WebTransportSendStream kann folgendermaßen erfolgen:

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 an den Client zu übertragen und Daten von ihm zu empfangen, kann auf diesen über die Eigenschaft WebTransport.incomingBidirectionalStreams zugegriffen werden, die einen ReadableStream von WebTransportBidirectionalStream-Objekten zurückgibt. Jedes davon kann verwendet werden, um Uint8Array-Instanzen zu lesen und zu schreiben, wie oben gezeigt. Wie beim unidirektionalen Beispiel benötigen Sie jedoch zunächst eine Funktion zum Lesen des bidirektionalen Streams:

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

Stellt Funktionen bereit, mit denen ein User Agent eine Verbindung zu einem HTTP/3-Server herstellen, zuverlässigen und unzuverlässigen Transport in eine oder beide Richtungen initiieren und die Verbindung schließen kann, sobald sie nicht mehr benötigt wird.

WebTransportBidirectionalStream

Repräsentiert einen von einem Server oder Client erstellten bidirektionalen Stream, der für zuverlässigen Transport verwendet werden kann. Bietet Zugriff auf einen ReadableStream zum Lesen eingehender Daten und einen WritableStream zum Schreiben ausgehender Daten.

WebTransportDatagramDuplexStream

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

WebTransportError

Repräsentiert einen Fehler im Zusammenhang mit der WebTransport API, der durch Serverfehler, Probleme mit der Netzwerkverbindung oder vom Client initiierte Abbruchoperationen entstehen kann, beispielsweise durch einen Aufruf von WritableStream.abort().

WebTransportReceiveStream

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

WebTransportSendStream

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

Beispiele

Vollständige Beispiele finden Sie unter:

• WebTransport über HTTP/3-Client

Spezifikationen

Browser-Kompatibilität

Siehe auch

• WebTransport verwenden
• WebSockets API
• Streams API
• WebTransport über HTTP/3