WebTransport

WebTransport über HTTP/3 ermöglicht es beiden Peers, viele unabhängige Streams innerhalb einer einzigen QUIC-Verbindung zu öffnen, ausgehandelt mit einer einzigen Extended-CONNECT-Anfrage.

Einführung

:method    = CONNECT
:protocol  = webtransport
:scheme    = https
:authority = example.com
:path      = /echo

Server-Ablauf

Aktivieren Sie WebTransport, indem Sie H3Settings.Settings.WebTransportMaxSessions auf einen Wert über null setzen, und behandeln Sie dann OnWebTransportSession. Der Handler erhält eine aktive Sitzung und ein Annahme-Flag, var aAccept in Delphi und C++Builder, e.Accept in .NET. Es kommt auf jedem Stack als True an, nichts zu tun nimmt die Sitzung also an; setzen Sie es auf False, um sie abzulehnen, der Server antwortet dann mit :status = 404 und verwirft die Sitzung. Bei Annahme antwortet der Server mit :status = 200, hält den CONNECT-Stream offen und registriert die Sitzung.

Weisen Sie OnStream innerhalb des Handlers zu, bevor Sie zurückkehren, da vom Peer geöffnete Streams eintreffen können, sobald die Sitzung registriert ist.

// WebTransport is enabled only when WebTransportMaxSessions > 0
FServer := TsgcHTTP3Server.Create(nil);
FServer.H3Settings.Settings.WebTransportMaxSessions := 4;
FServer.OnWebTransportSession := OnWTSession;

procedure TfrmServer.OnWTSession(Sender: TObject;
  const aConnection: TsgcQUICServerConnection;
  const aSession: TsgcWebTransportSession; var aAccept: Boolean);
begin
  aAccept := True;   // already True on entry; set False to reject with 404
  aSession.OnStream := OnWTStream;
  aSession.OnClose := OnWTSessionClose;
end;

procedure TfrmServer.OnWTStream(Sender: TObject;
  const aStream: TsgcWebTransportStream);
begin
  aStream.OnData := OnWTStreamData;
end;

procedure TfrmServer.OnWTStreamData(Sender: TObject; const aData: TBytes);
begin
  // echo the bytes back on the same stream
  TsgcWebTransportStream(Sender).WriteData(aData);
end;

Client-Ablauf

Rufen Sie WebTransportConnect mit der URL der Sitzung auf. Es öffnet eine dedizierte QUIC-Verbindung, sendet das Extended CONNECT, wartet auf die durch ConnectTimeout begrenzte Antwort und gibt bei :status = 200 die Sitzung zurück, andernfalls nil. Ein vorheriger Aufruf von Connect ist nicht erforderlich: Wenn der Client bereits verbunden ist, trennt er zuerst die Verbindung, denn eine WebTransport-Sitzung erfordert, dass die CONNECT-Anfrage auf dem ersten vom Client initiierten bidirektionalen Stream übertragen wird.

Die WebTransport-Verbindung ist nicht-blockierend, daher wird nichts vom Socket gelesen, solange Sie sie nicht pumpen. Rufen Sie WebTransportProcessEvents regelmäßig aus einem Timer oder einem Hintergrund-Thread auf. Ohne das werden OnData und OnStream nie ausgelöst.

FClient := TsgcHTTP3Client.Create(nil);
FClient.TLSOptions.VerifyCertificate := False;
FClient.ConnectTimeout := 10000;

// Opens the QUIC connection and performs the Extended CONNECT. Returns nil if
// the server rejects the session or does not support WebTransport.
FSession := FClient.WebTransportConnect('https://127.0.0.1:4433/echo');
if Assigned(FSession) then
begin
  FStream := FSession.OpenStream(False);   // False = bidirectional
  FStream.OnData := OnStreamData;
  FStream.WriteData('Hello WebTransport');
  tmrPump.Enabled := True;
end;

procedure TfrmClient.tmrPumpTimer(Sender: TObject);
begin
  // Pump the QUIC connection so incoming stream data is harvested
  FClient.WebTransportProcessEvents;
end;

Datagramme: aktueller Status

WebTransport bietet gemäß Spezifikation auch unzuverlässige Datagramme, und diese Bibliothek stellt die API dafür bereit: SendDatagram an der Sitzung und das Ereignis OnDatagram.

Im Auslieferungszustand unterstützt WebTransport in sgcWebSockets nur Streams. Datagramme gelangen nicht auf die Leitung und treffen auch nicht von dort ein. Das gilt auf dem Client, auf dem Server, in Delphi, in C++Builder und unter .NET. Streams funktionieren vollständig; Datagramme funktionieren überhaupt nicht. Der ausgehende Aufruf schlägt laut statt still fehl, das ist die eine Sache, die sich geändert hat. Konkret:

• Ausgehend. In Delphi und C++Builder löst SendDatagram eine TsgcQUICException aus. Es prüft DatagramsSupported, das Flag, mit dem ein Transport erklärt, dass sein Datagramm-Writer-Hook (OnSendDatagramData) tatsächlich die Leitung erreicht. Kein ausgelieferter Transport setzt es: Der HTTP/3-Client bindet diesen Hook an einen bewusst leeren Handler, und der HTTP/3-Server bindet ihn an TsgcHTTP3Server.SendDatagram, dessen Basisimplementierung ein bewusster No-Op ist. Die Methode verweigert daher den Dienst, bevor sie überhaupt etwas codiert, anstatt Ihre Payload stillschweigend zu verlieren. Unter .NET löst das verwaltete SendDatagram keine Ausnahme aus, es verwirft sein Argument direkt.
• Eingehend. OnDatagram wird ausschließlich von TsgcWebTransportSession.DoDatagram ausgelöst. Dessen einziger Aufrufer ist TsgcHTTP3ServerConnection.ProcessWebTransportDatagram, ein Integrationspunkt für einen datagrammfähigen Transport, den der ausgelieferte HTTP/3-Stack nie aufruft. OnDatagram wird daher nie ausgelöst.

Warum, und auf welcher Engine. sgcWebSockets besitzt zwei QUIC-Engines, TsgcQUICMode = (qmCustom, qmBuiltin), die automatisch gewählt werden, wenn OpenSSL geladen wird, und die von der Anwendung nicht auswählbar sind. qmCustom ist der Pascal-QUIC-Stack, der verwendet wird, wenn die geladene Bibliothek die quictls-QUIC-TLS-API bereitstellt. qmBuiltin ist OpenSSLs eigenes natives QUIC, das andernfalls verwendet wird.

WebTransport läuft in jeder ausgelieferten Konfiguration auf qmBuiltin. Das mitgelieferte OpenSSL 3.5 exportiert OSSL_QUIC_client_method, aber nicht die QUIC-TLS-Einstiegspunkte von quictls, daher wird qmBuiltin ausgewählt. Es ist auch die einzige praktikable Wahl: qmCustom hat keine Serverunterstützung und kann die zusätzlichen QUIC-Streams, die eine WebTransport-Sitzung benötigt, nicht öffnen.

Und qmBuiltin ist genau die Engine ohne Datagramm-Pfad. WebTransport-Datagramme benötigen die QUIC-DATAGRAM-Erweiterung (RFC 9221) unterhalb der HTTP-Datagramm-Schicht (RFC 9297). Das native QUIC von OpenSSL implementiert RFC 9221 nicht, und seine Serverseite stellt keinen DATAGRAM-Schreibpfad bereit, es gibt also keine Stelle, an die die Bytes geschrieben werden könnten. Sie stattdessen auf einen zuverlässigen Stream zu schreiben, würde das HTTP/3-Framing beschädigen, daher verweigert die Bibliothek den Aufruf, anstatt die Verbindung zu zerstören. Unter .NET ist die Ursache dieselbe in anderer Gestalt: System.Net.Quic stellt keine rohen QUIC-Datagramme bereit.

Dennoch kündigt der Server weiterhin SETTINGS_H3_DATAGRAM an. Das Aktivieren von WebTransport veranlasst den Server, es zusammen mit SETTINGS_ENABLE_CONNECT_PROTOCOL und SETTINGS_WEBTRANSPORT_MAX_SESSIONS anzukündigen, obwohl kein Datagramm transportiert werden kann. Das ist beabsichtigt und keine veraltete Einstellung. Der Entwurf WebTransport over HTTP/3 verlangt die Einstellung, und Browser weigern sich, ohne sie eine Sitzung aufzubauen, daher wird sie aus Gründen der Interoperabilität angekündigt: Ohne sie wäre die Stream-Hälfte von WebTransport, die Hälfte, die funktioniert, aus einem Browser nicht erreichbar.

Was vorhanden ist. Der vollständige Kodier- und Demultiplex-Pfad in sgcWebTransport ist implementiert und korrekt: Kodierung und Dekodierung der Quarter-Stream-ID, die Suche der Sitzung über die Quarter-Stream-ID und die Zustellung der Payload. Ein datagrammfähiges QUIC-Backend kann Datagramme aktivieren, indem es einen echten Writer bereitstellt (durch Zuweisen von OnSendDatagramData oder durch Überschreiben des virtuellen TsgcHTTP3Server.SendDatagram), für jede Sitzung DatagramsSupported := True setzt, damit der Encoder läuft, statt eine Ausnahme auszulösen, und beim Empfang ProcessWebTransportDatagram aufruft. Solange ein solches Backend nicht existiert, betrachten Sie die Datagramm-Unterstützung als nicht vorhanden und entwerfen Sie Ihr Protokoll auf Basis von Streams.

Anforderungen

• In sgcVer.inc ist das HTTP/3-Feature-Pack SGC_PACK_HTTP3 innerhalb des Editionsblocks All-Access (SGC_EDT_ALL) deklariert und erfordert SGC_INDY_LIB.
• HTTP/3 und WebTransport werden deaktiviert ausgeliefert. Entfernen Sie die Kommentierung von {$DEFINE SGC_PACK_HTTP3} in sgcVer.inc. Das definiert wiederum SGC_QUIC, SGC_HTTP3 und SGC_WEBTRANSPORT. Der gesamte WebTransport-Code ist durch {$IFDEF SGC_WEBTRANSPORT} geschützt.
• Units: sgcWebTransport für die Sitzungs- und Stream-Klassen, sgcHTTP für TsgcHTTP3Client und TsgcHTTP3Server, sgcQUIC_Server für TsgcQUICServerConnection.
• Erfordert OpenSSL 3.5 oder neuer. Die QUIC-Engine (qmCustom oder qmBuiltin) wird beim Laden von OpenSSL automatisch erkannt und ist nicht vom Benutzer wählbar. WebTransport läuft auf qmBuiltin, dem nativen QUIC von OpenSSL, das vom mitgelieferten OpenSSL 3.5 bereitgestellt wird und die einzige Engine mit der Server- und Multi-Stream-Unterstützung ist, die eine Sitzung benötigt. Diese Engine hat keinen DATAGRAM-Pfad nach RFC 9221, weshalb Datagramme wirkungslos bleiben und SendDatagram eine Ausnahme auslöst.
• .NET: verfügbar in der rein verwalteten Bibliothek ab net8.0, sofern MsQuic vorhanden ist. WebTransportConnect löst PlatformNotSupportedException aus, wenn netstandard2.0 verwendet wird oder wenn QuicConnection.IsSupported False ist.

Referenz

• TsgcWebTransportSession — eine WebTransport-Sitzung; wird von WebTransportConnect des Clients zurückgegeben und an OnWebTransportSession des Servers übergeben.
• TsgcWebTransportStream — ein bidirektionaler oder unidirektionaler Stream innerhalb einer Sitzung.
• TsgcHTTP3Client — der HTTP/3-Client, der WebTransport-Sitzungen öffnet.
• TsgcHTTP3Server — der HTTP/3-Server, der sie annimmt.
• HTTP/3 — das Protokoll, auf dem WebTransport aufsetzt.