TsgcQUICServer

TsgcQUICServer is a low-level QUIC server: it listens for QUIC connections over UDP and exchanges raw application bytes over QUIC streams.

Introduction

openssl req -x509 -newkey rsa:2048 -keyout server.key -out server.crt -days 365 -nodes -subj "/CN=localhost"

oServer := TsgcQUICServer.Create(nil);
oServer.Port := 4433;
oServer.QUICOptions.SSLOptions.CertFile := 'server.crt';
oServer.QUICOptions.SSLOptions.KeyFile := 'server.key';
oServer.OnQUICConnect := OnQUICConnectEvent;
oServer.OnQUICData := OnQUICDataEvent;
oServer.Start;

procedure TfrmServer.OnQUICDataEvent(Sender: TObject;
  const aConnection: TsgcQUICServerConnection; const aData: TBytes);
begin
  // echo the received bytes back to the peer
  oServer.WriteData(aConnection, aData);
end;

Relationship with TsgcHTTP3Server

TsgcHTTP3Server_Base descends from TsgcQUICServer_Base, so TsgcHTTP3Server is a QUIC server with the HTTP/3 protocol layered on it. Use TsgcQUICServer when you want a raw byte transport with your own protocol on top, and TsgcHTTP3Server when you want to serve HTTP/3.

If you use the HTTP/3 server, note that it claims part of this component's surface: its constructor sets AlwaysMultiStream to True (HTTP/3 needs the client's unidirectional control and QPACK streams, RFC 9114) and wires OnQUICConnect, OnQUICData, OnQUICStreamData and OnQUICDisconnect to its own handlers. Assigning those events, or clearing AlwaysMultiStream, breaks the HTTP/3 layer. OnQUICException is the one exception, the HTTP/3 server only claims it if you have not assigned it yourself.

Reference

• Properties — 7 properties available on the component.
• Methods — 6 public methods.
• Events — 7 events you can handle.

Two classes complete the API:

• TsgcQUICServerConnection — a single accepted connection, the object handed to every event.
• TsgcQUICServerStream — one additional QUIC stream on a connection.

Key Properties

Key Methods

Key Events

Complete Example

An echo server that reports connections and errors. Note that PeerIP is not populated by the Delphi server, because OpenSSL exposes no getter for it, so the session is identified by the connection instance.

uses
  sgcQUIC_Server, sgcHTTP;

procedure TfrmServer.StartServer;
begin
  oServer := TsgcQUICServer.Create(nil);
  oServer.Port := 4433;

  // mandatory: QUIC always runs over TLS 1.3
  oServer.QUICOptions.SSLOptions.CertFile := 'server.crt';
  oServer.QUICOptions.SSLOptions.KeyFile := 'server.key';
  oServer.QUICOptions.MaxConnections := 1000;

  oServer.OnQUICConnect := OnQUICConnectEvent;
  oServer.OnQUICData := OnQUICDataEvent;
  oServer.OnQUICDisconnect := OnQUICDisconnectEvent;
  oServer.OnQUICException := OnQUICExceptionEvent;
  oServer.OnStartup := OnStartupEvent;

  // Start raises on a bad configuration, OnStartup fires once it is listening
  try
    oServer.Start;
  except
    on E: Exception do
      Log('start failed: ' + E.Message);
  end;
end;

procedure TfrmServer.StopServer;
begin
  oServer.Stop; // OnQUICDisconnect is NOT raised for these connections
  Log('QUIC server stopped');
  oServer.Free;
end;

procedure TfrmServer.OnStartupEvent(Sender: TObject);
begin
  // raised once the listener is bound and accepting
  Log('QUIC server listening on UDP port ' + IntToStr(oServer.Port));
end;

procedure TfrmServer.OnQUICConnectEvent(Sender: TObject;
  const aConnection: TsgcQUICServerConnection);
begin
  Log(Format('connected at %s (%d live)',
    [DateTimeToStr(aConnection.CreatedAt), oServer.ConnectionCount]));
end;

procedure TfrmServer.OnQUICDataEvent(Sender: TObject;
  const aConnection: TsgcQUICServerConnection; const aData: TBytes);
begin
  // aData is a chunk, not a message: frame at the application level
  oServer.WriteData(aConnection, aData);
end;

procedure TfrmServer.OnQUICDisconnectEvent(Sender: TObject;
  const aConnection: TsgcQUICServerConnection; aCode: Int64; const aReason: string);
begin
  // aCode 0 / empty reason on a normal close, otherwise an OpenSSL error code
  Log(Format('disconnected (code=%d %s)', [aCode, aReason]));
end;

procedure TfrmServer.OnQUICExceptionEvent(Sender: TObject;
  const aConnection: TsgcQUICServerConnection; const aException: Exception);
begin
  // aConnection is nil for a listener error, otherwise it is the failing session
  if Assigned(aConnection) then
    Log('connection error: ' + aException.Message)
  else
    Log('listener error: ' + aException.Message);
end;

Requirements