TsgcQUICServer

TsgcQUICServer implementiert die Serverseite von QUIC (RFC 9000, mit TLS 1.3 gemäß RFC 9001 und Verlustbehebung gemäß RFC 9002). QUIC ist ein verbindungsorientierter, multiplexter, stets verschlüsselter Transport, der über UDP läuft. Diese Komponente stellt ihn als Byte-Transport bereit: Sie übergibt Ihnen die Bytes, die ein Peer sendet, und lässt Sie Bytes zurückschreiben. Sie implementiert kein darauf aufsetzendes Anwendungsprotokoll. Für HTTP/3 verwenden Sie TsgcHTTP3Server, das von dieser Komponente abgeleitet ist.

Was Ihnen die Komponente bietet:

• Ein UDP-Listener. QUIC hat keinen TCP-Socket. Start erstellt einen UDP-Socket, bindet ihn und führt einen Hintergrundthread aus, der die QUIC-Ereignisschleife antreibt: Verbindungen annehmen, Handshakes vorantreiben und Streams lesen. Denken Sie daran, den UDP-Port in der Firewall zu öffnen, UDP und TCP werden unabhängig voneinander gefiltert.
• Verbindliches TLS 1.3. QUIC hat keinen Klartextmodus, daher sind immer ein Zertifikat und ein privater Schlüssel erforderlich. Konfigurieren Sie diese über QUICOptions.SSLOptions. Ohne sie löst Start eine Ausnahme aus.
• ALPN. QUIC schreibt ALPN vor, der Server handelt daher während des Handshakes ein Anwendungsprotokoll aus. Der eingebaute Auswahl-Callback bevorzugt h3 und akzeptiert andernfalls das erste Angebot des Peers, er ist nicht konfigurierbar. Ein Peer, der nichts anbietet, wird abgelehnt.
• Streams und Multiplexing. Eine Verbindung trägt viele unabhängige, geordnete Streams, ein langsamer Stream blockiert die anderen also nicht (kein Head-of-Line-Blocking). Standardmäßig hält der Server es einfach und verwendet den ersten vom Peer geöffneten Stream als einzigen Standard-Datenstream der Verbindung. Setzen Sie AlwaysMultiStream, um mit allen zu arbeiten.
• Ein Modell pro Verbindung. Jeder akzeptierte Peer ist eine TsgcQUICServerConnection, die an jedes Ereignis übergeben wird und das Handle darstellt, über das Sie zurückschreiben.

Der QUIC-Server läuft standardmäßig auf der integrierten QUIC-Engine von OpenSSL 3.5+. Er ruft OSSL_QUIC_server_method und SSL_new_listener auf, wenn die geladene OpenSSL-Bibliothek diese exportiert. Andernfalls fällt er auf die sgc-QUIC-Engine zurück, und mit QUICOptions.SSLOptions.IOHandler = iohNativeTLS verwendet er immer die sgc-Engine mit dem TLS-1.3-Handshake auf der nativen TLS-Engine. Die schreibgeschützte Eigenschaft QUICMode meldet die beim Start gewählte Engine. Siehe QUIC für den Engine-Vergleich.

Befolgen Sie diese Schritte, um die Komponente zu konfigurieren:

1. Erstellen Sie eine neue Instanz von TsgcQUICServer.

2. Legen Sie den Port fest, auf dem gelauscht wird. Standardmäßig ist er 80, geerbt von der UDP-Basisklasse, setzen Sie ihn daher immer (4433 und 443 sind die üblichen QUIC-Werte).

3. Legen Sie das Zertifikat und den privaten Schlüssel in QUICOptions.SSLOptions fest. Beide sind PEM-Dateien und beide sind zwingend erforderlich. Für ein Testzertifikat:

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

4. Behandeln Sie OnQUICConnect und OnQUICData und rufen Sie Start innerhalb eines try..except auf, weil Konfigurationsfehler dort auftreten.

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;

Threading. Jedes Ereignis wird im Hintergrund-Listener-Thread des Servers ausgelöst, und dieser eine Thread treibt die Ereignisschleife für alle Verbindungen an. Halten Sie Handler daher kurz und marshallen Sie zum Haupt-Thread, bevor Sie die UI ansprechen.

Lebenszyklus. Verwenden Sie Start und Stop oder die Eigenschaft Active, auf der sie aufbauen und die den tatsächlichen Listener-Zustand meldet. OnStartup und OnShutdown werden um diese Übergänge herum ausgelöst, sodass Sie aus einem Handler heraus oder nach der Rückkehr des Aufrufs reagieren können, je nachdem, was Ihnen besser passt.

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;