TsgcQUICClient

QUIC is the transport protocol standardised in RFC 9000, with its TLS integration in RFC 9001 and its loss detection and congestion control in RFC 9002. It is the transport HTTP/3 runs on. Compared with TCP plus TLS it changes four things that matter to an application:

• It runs over UDP. QUIC lives in user space on top of UDP datagrams, so it does not depend on the operating system TCP stack and can be deployed without kernel changes. The trade-off is that a network which blocks or rate-limits UDP will block QUIC.
• TLS 1.3 is built in, not layered on. There is no such thing as an unencrypted QUIC connection: the handshake is part of the transport, and even most of the packet header is protected. This also collapses the round trips, a fresh connection is established in 1-RTT instead of the TCP handshake followed by a separate TLS handshake.
• Streams are multiplexed inside one connection. A connection carries many independent streams, each ordered and flow-controlled on its own. A packet lost on one stream does not stall the others, which removes the head-of-line blocking that HTTP/2 suffers from when multiplexing over a single TCP connection. Streams can be bidirectional or unidirectional, and either side can open them.
• Connections are identified by a connection id, not by the 4-tuple. This is what lets QUIC survive a change of IP address or port in the protocol design.

TsgcQUICClient exposes this transport directly, as raw bytes on streams. It does not speak HTTP/3 or any other application protocol: use TsgcHTTP3Client when you want HTTP semantics over QUIC. Reach for TsgcQUICClient when you are carrying your own protocol over QUIC, or testing a QUIC endpoint.

Scope worth knowing before you start. The component is a thin client over the QUIC transport, and two of its limits surprise people:

• There is no read path until you call EnableMultiStream. A plain client can connect and send, but nothing it receives is reported. OnQUICStreamData is the only data-received event, and it stays inert until multi-stream mode is switched on. There is no OnQUICData on the client, unlike TsgcQUICServer.
• ALPN is fixed to h3 and cannot be configured. 0-RTT resumption and connection migration are implemented in the underlying transport class but are not surfaced as properties on this component.

The two QUIC engines

The library can drive QUIC through either of two engines. The engine follows SSLQUICOptions.IOHandler:

1. With iohOpenSSL (the default), if the OpenSSL build exports OSSL_QUIC_client_method, the builtin engine (qmBuiltin) is used. Here OpenSSL 3.5 or later owns the whole QUIC connection and the library drives it through the OpenSSL stream API.
2. Otherwise, if the build exports the OpenSSL 3.5 QUIC TLS API (SSL_set_quic_tls_cbs), the sgc engine (qmCustom) is used as the fallback. This is the pure Pascal QUIC stack in the sgcQUIC_* units: it builds and parses the packets itself and uses OpenSSL only to drive the TLS 1.3 handshake. If neither API is available, for example with a quictls build, initialising the connection raises an exception.
3. With iohNativeTLS the sgc engine is always used and the TLS 1.3 handshake runs on the native TLS engine, with session tickets, resumption and 0-RTT. The packet protection is native too, so OpenSSL is not loaded at all.

With the OpenSSL 3.5 binaries bundled with the demos qmBuiltin is selected. IsOpenSSL_QUIC_Available and IsOpenSSL_QUIC_TLS_Available, declared in sgcIdSSLOpenSSLHeaders, report which of the two OpenSSL APIs the loaded library exports. The engines compare as follows:

Feature	qmBuiltin (OpenSSL 3.5+)	qmCustom (sgc engine)
Connect, disconnect, send on the default stream	Yes	Yes
EnableMultiStream	Yes	Yes
OpenStream / WriteStreamData	Yes	Yes
OnQUICStreamData (the read path)	Yes, after EnableMultiStream	Yes, after EnableMultiStream
QUICOptions.Settings tuning	Mostly negotiated by OpenSSL, values not consulted	Yes, drives the Pascal stack

See QUIC for the full engine comparison.

Quick start

1. Create a TsgcQUICClient and set Host and Port of the QUIC server. QUIC runs over UDP, so Port is a UDP port, commonly 443.

2. Configure TLS through SSLQUICOptions. Verification is off by default, so turn VerifyCertificate on and point RootCertFile at your CA for anything but a throwaway test. With verification on the certificate must now also match the host you are connecting to, so a self-signed certificate, or one issued for a different name, is rejected where it used to be accepted.

3. Handle OnQUICConnect, OnQUICDisconnect and OnQUICException. Handling OnQUICException is not optional: connect failures do not raise, they are reported there, and Connect merely returns False.

4. Open the connection with Connect (blocking, returns a result) or Start / Active := True (non-blocking).

5. If you need to receive anything, call EnableMultiStream once connected and handle OnQUICStreamData. To send, use WriteData for the default stream, or OpenStream plus WriteStreamData for a specific one.

oClient := TsgcQUICClient.Create(nil);
oClient.Host := 'www.example.com';
oClient.Port := 443;

oClient.SSLQUICOptions.VerifyCertificate := True;
oClient.SSLQUICOptions.RootCertFile := 'ca.pem';
oClient.SSLQUICOptions.ConnectTimeout := 10000;

oClient.OnQUICConnect := OnQUICConnectEvent;
oClient.OnQUICStreamData := OnQUICStreamDataEvent;
oClient.OnQUICException := OnQUICExceptionEvent;

if oClient.Connect then
  oClient.WriteData('Hello QUIC');

uses
  sgcHTTP, sgcQUIC_Client, sgcQUIC_Classes;

procedure TForm1.Start;
begin
  FClient := TsgcQUICClient.Create(nil);
  FClient.Host := 'www.example.com';
  FClient.Port := 443;

  // TLS 1.3. Verification is off by default, turn it on.
  FClient.SSLQUICOptions.VerifyCertificate := True;
  FClient.SSLQUICOptions.RootCertFile := 'ca.pem';
  // the handshake timeout, 10000 ms is already the default
  FClient.SSLQUICOptions.ConnectTimeout := 10000;

  FClient.OnQUICConnect := OnQUICConnectEvent;
  FClient.OnQUICStreamData := OnQUICStreamDataEvent;
  FClient.OnQUICDisconnect := OnQUICDisconnectEvent;
  FClient.OnQUICException := OnQUICExceptionEvent;

  // Connect returns False without raising, the reason arrives on OnQUICException
  if not FClient.Connect(10000) then
    Log('connect failed');
end;

procedure TForm1.OnQUICConnectEvent(Sender: TObject; const Connection: TsgcQUICConnection);
var
  oStream: TsgcQUICClientStream;
begin
  Log('connected');

  // required before OnQUICStreamData will ever fire
  FClient.EnableMultiStream;

  oStream := FClient.OpenStream; // bidirectional
  if Assigned(oStream) then
    FClient.WriteStreamData(oStream, TEncoding.UTF8.GetBytes('Hello QUIC'))
  else
    Log('could not open a stream, is the builtin OpenSSL QUIC engine active?');
end;

procedure TForm1.OnQUICStreamDataEvent(Sender: TObject; aStreamId: Int64;
  aUnidirectional: Boolean; const aData: TBytes);
begin
  // raised on the read thread, do not touch the UI directly here
  Log(Format('stream %d: %d bytes', [aStreamId, Length(aData)]));
end;

procedure TForm1.OnQUICDisconnectEvent(Sender: TObject; const Connection: TsgcQUICConnection;
  Code: Int64; const Reason: string);
begin
  if Code = 0 then
    Log('closed cleanly')
  else
    Log(Format('closed, code %d: %s', [Code, Reason]));
end;

procedure TForm1.OnQUICExceptionEvent(Sender: TObject; const Connection: TsgcQUICConnection;
  const E: Exception);
begin
  Log('error: ' + E.Message);
end;