Démarrage rapide de sgcQUIC

En un coup d'œil

Ce dont a besoin la première requête

Un composant, une URL, et deux bibliothèques OpenSSL à côté de ton exécutable.

Composant

TsgcHTTP3Client sur la page de palette SGC QUIC, déclaré dans sgcQUIC.pas. La page contient aussi TsgcQUICClient, TsgcQUICServer et TsgcHTTP3Server.

Unité

sgcQUIC pour le composant. Ajoute sgcHTTP3_Classes pour TsgcHTTP3Response, et sgcHTTP_AltSvc si tu gères l'événement Alt-Svc.

L'appel

Get(aURL) renvoie le corps sous forme de string et lève une exception en cas d'échec. Le code d'état et les en-têtes arrivent séparément, sur OnResponse.

La contrainte OpenSSL

Le client a besoin de l'API QUIC d'OpenSSL 3.2 ou supérieur, ou d'une version quictls. Le serveur a besoin de la 3.5 ou supérieure, car il appelle une API qui n'existe que là. Livre libcrypto-3.dll et libssl-3.dll à côté de ton exécutable, comme le fait chaque dossier de démo.

Avant de commencer

Prérequis et éditions

La colonne d'édition indique le define qui conditionne le code, avec la ligne où il se trouve dans Source/sgcVer.inc.

Quoi	Valeur
IDE	Delphi 7 jusqu'à RAD Studio 13, et C++Builder 2007 jusqu'à 13. Il n'y a pas de téléchargement sgcQUIC séparé : les composants sont dans le groupe de packages sgcWebSockets.
Clause uses	`sgcQUIC`, plus `sgcHTTP3_Classes` pour l'objet de réponse et `sgcHTTP_AltSvc` pour les types Alt-Svc.
Define du pack	`SGC_PACK_QUIC` est défini à la ligne 872, dans le bloc `{$IFDEF SGC_EDT_ALL}` qui va de la ligne 870 à la ligne 874. Donc All-Access.
Defines de fonctionnalités	Dans le bloc `{$IFDEF SGC_PACK_QUIC}` aux lignes 894 à 899 : `SGC_QUIC` à la ligne 896, `SGC_HTTP3` à la ligne 897 et `SGC_WEBTRANSPORT` à la ligne 898. Les trois se trouvent dans un `{$IFDEF SGC_INDY_LIB}` à la ligne 895, donc une version sans la bibliothèque Indy personnalisée n'en obtient aucun.
OpenSSL, client	3.2 ou supérieur, ou une version quictls. La bibliothèque le dit elle-même : l'erreur levée lorsque QUIC est indisponible indique QUIC is not available. Requires quictls/openssl or OpenSSL 3.2+.
OpenSSL, serveur	3.5 ou supérieur. Le serveur QUIC appelle `SSL_new_listener`, et l'erreur levée quand elle est absente indique QUIC Server requires OpenSSL 3.5 or later. msquic n'est pas utilisé et n'est pas nécessaire.
Plateformes	Aucune garde de plateforme au niveau de l'unité sur `sgcQUIC.pas`, `sgcQUIC_Client.pas`, `sgcHTTP3_Client.pas` ou `sgcHTTP3_Server.pas`, et les quatre composants sont enregistrés avec `ComponentPlatforms(0)`. L'unité serveur sélectionne l'API de sockets par plateforme, avec une branche Windows et une branche POSIX.

Tu n'es pas sûr que le moteur soit présent à l'exécution ? Appelle IsOpenSSL_QUIC_Available, qui indique si l'OpenSSL chargé expose la méthode client QUIC. La démo du client QUIC livrée l'enregistre au démarrage précisément pour cette raison.

Étape 1

Installer et trouver la page de palette

Il n'y a pas d'installeur sgcQUIC séparé. Les composants arrivent avec sgcWebSockets et apparaissent dès que l'édition les active.

1. Décompresser

Décompresse le téléchargement de sgcWebSockets dans un dossier, appelé {$DIR} ci-dessous.

2. Chemin de bibliothèque

Outils, Options, Bibliothèque. Ajoute {$DIR}\source et le dossier lib de ton IDE, par exemple {$DIR}\libD13\$(Platform).

3. Compiler les packages

Ouvre le groupe de packages de ta version d'IDE sous {$DIR}\Packages\. Compile d'abord le .dpk d'exécution, puis installe celui de conception dcl. Il n'existe pas de package spécifique à QUIC.

4. Vérifier la palette

Une page nommée SGC QUIC apparaît avec TsgcQUICClient, TsgcQUICServer, TsgcHTTP3Client et TsgcHTTP3Server. Si la page est absente, la version n'est pas All-Access, car SGC_PACK_QUIC n'est défini qu'à la ligne 872 dans ce bloc.

5. Place OpenSSL à côté de l'exe

Copie libcrypto-3.dll et libssl-3.dll à côté de ton exécutable, 3.2 ou supérieur pour un client et 3.5 ou supérieur pour un serveur. Chaque dossier sous Demos\22.QUIC_Protocol les contient, tu peux donc les copier de là.

QuickStart

Une requête HTTP/3

Crée le client, branche trois événements, appelle Get. La réponse revient sous forme de chaîne et le code d'état arrive sur OnResponse.

FHTTP3Client.pas

uses
  Classes, SysUtils,
  // sgc
  sgcQUIC, sgcHTTP3_Classes;

procedure TfrmHTTP3Client.FormCreate(Sender: TObject);
begin
  FClient := TsgcHTTP3Client.Create(nil);
  FClient.OnConnect := OnH3Connect;
  FClient.OnError := OnH3Error;
  FClient.OnResponse := OnH3Response;
  FClient.TLSOptions.VerifyCertificate := True;
  FClient.ConnectTimeout := 10000;
  FClient.ReadTimeout := 30000;
  FClient.UserAgent := 'sgcWebSockets/HTTP3Client';
end;

procedure TfrmHTTP3Client.btnGetClick(Sender: TObject);
var
  vResult: string;
begin
  try
    // the target comes from the URL, because Host and Port
    // are read-only on this component
    vResult := FClient.Get('https://www.google.com/');
    memoBody.Lines.Text := vResult;
    DoLog('Response received: ' + IntToStr(Length(vResult)) + ' bytes');
  except
    on E: Exception do
      DoLog('Error: ' + E.Message);
  end;
end;

Post, Put et Delete ont la même forme, et chacun possède une surcharge avec flux pour un corps que tu ne veux pas conserver dans une chaîne. Connect(const aHost: string; aPort: Integer = 443) ouvre la connexion avant la première requête quand tu veux séparer les deux.

FHTTP3Client.pas

// OnConnect and OnDisconnect are plain TNotifyEvent on this
// component: one parameter, no connection object.
procedure TfrmHTTP3Client.OnH3Connect(Sender: TObject);
begin
  DoLog('Connected to ' + FClient.Host + ':' + IntToStr(FClient.Port));
end;

procedure TfrmHTTP3Client.OnH3Error(Sender: TObject; const aError: string);
begin
  DoLog('Error: ' + aError);
end;

procedure TfrmHTTP3Client.OnH3Response(Sender: TObject;
  const aResponse: TsgcHTTP3Response);
begin
  DoLog('Status: ' + IntToStr(aResponse.StatusCode));
  memoHeaders.Lines.Assign(aResponse.Headers);
end;

Lire FClient.Host et FClient.Port dans OnConnect est exactement à quoi servent ces deux propriétés. Elles rendent compte de la connexion, elles ne la configurent pas.

FQUICClient.pas

uses
  Classes, SysUtils,
  // sgc
  sgcIdSSLOpenSSLHeaders;

procedure TfrmQUICClient.FormCreate(Sender: TObject);
begin
  DoLog('OpenSSL QUIC Support:');
  DoLog('  quictls API: ' +
    BoolToStr(IsOpenSSL_QUIC_TLS_Available, True));
  DoLog('  Builtin QUIC (3.2+): ' +
    BoolToStr(IsOpenSSL_QUIC_Available, True));
end;

Exécute ceci une fois avant tout le reste. Si les deux renvoient false, l'OpenSSL placé à côté de ton exécutable n'a pas QUIC, et chaque échec de connexion ensuite est le symptôme de ce seul fait plutôt que du réseau.

Les deux premiers onglets proviennent de la démo livrée Demos\22.QUIC_Protocol\03.HTTP3_Client\FHTTP3Client.pas, avec les contrôles de la fiche remplacés par des littéraux. Le troisième est la vérification de disponibilité à l'exécution de 01.QUIC_Client\FQUICClient.pas. Il y a six démos QUIC dans ce dossier, dont une paire WebTransport.

Étape 2

Lire le code d'état, pas seulement le corps

Get renvoie le corps. L'objet de réponse transporte tout le reste, et il arrive sur son propre événement.

La valeur de retour

Get renvoie le corps de la réponse sous forme de string et lève une exception en cas d'échec, c'est pourquoi la démo l'entoure d'un try except. Un corps de la longueur attendue est la première preuve.

`OnResponse`

procedure(Sender: TObject; const aResponse: TsgcHTTP3Response). StatusCode est le nombre que tu veux vraiment, Headers est une TStringList, et GetDataAsString te redonne le corps depuis l'objet de réponse.

`OnConnect`

Un simple TNotifyEvent. Qu'il se déclenche signifie que QUIC a négocié et que la session HTTP/3 s'est ouverte, ce qui est la partie la plus susceptible d'échouer au premier lancement.

Avant d'accuser le code

IsOpenSSL_QUIC_Available répond à la seule question qui vaut la peine d'être posée en premier. QUIC passe aussi par UDP 443, et un réseau qui autorise TCP 443 n'autorise pas forcément cela.

Problèmes courants

Ce qui se passe généralement mal la première fois

Six problèmes expliquent presque toutes les premières requêtes en échec.

Impossible d'affecter Host ou Port

Ils sont en lecture seule sur TsgcHTTP3Client, déclarés comme property Host: string read FHost et property Port: Integer read FPort. Ils indiquent où le client est connecté. Pour choisir une cible, passe une URL complète à Get ou appelle Connect(aHost, aPort).

QUIC n'est pas disponible

L'OpenSSL que tu as chargé est trop ancien ou a été compilé sans QUIC. Le client a besoin de la 3.2 ou supérieure, ou de quictls. Vérifie à l'exécution avec IsOpenSSL_QUIC_Available avant d'accuser le réseau.

Le serveur ne démarre pas

Le serveur QUIC a besoin d'OpenSSL 3.5 ou supérieur, car il appelle SSL_new_listener. Une version 3.2 suffit pour le client mais pas pour le serveur, et le message d'erreur le dit explicitement.

Mauvaise arité sur OnConnect

OnConnect et OnDisconnect sur ce composant sont de simples TNotifyEvent, donc le gestionnaire ne prend que Sender: TObject. Ils ne te transmettent pas d'objet de connexion, contrairement aux composants WebSocket.

L'UDP est bloqué

QUIC passe par UDP sur le port 443, et de nombreux réseaux d'entreprise autorisent TCP 443 et bloquent UDP 443. Si un navigateur peut joindre l'hôte en HTTP/3 et pas ton application, soupçonne le firewall avant le code.

La page de palette est absente

SGC_PACK_QUIC n'est défini qu'à la ligne 872, dans le bloc All-Access. Il nécessite aussi SGC_INDY_LIB, car tout le bloc du pack, lignes 894 à 899, se trouve dans cette garde.

Aller plus loin

Au-delà de la première requête

Quatre directions, toutes dans le même package.

Exécuter un serveur HTTP/3

TsgcHTTP3Server sert du HTTP/3 directement sur QUIC. N'oublie pas le plancher OpenSSL 3.5 côté serveur.

Composant serveur HTTP/3

QUIC brut, sans HTTP

TsgcQUICClient et TsgcQUICServer te donnent des flux QUIC sans la couche HTTP/3, ce qu'il te faut pour un protocole personnalisé nécessitant du multiplexage sans blocage en tête de file.

Client QUIC et serveur QUIC

WebTransport

Flux bidirectionnels et datagrammes vers un navigateur via HTTP/3, conditionnés par SGC_WEBTRANSPORT à la ligne 898. Deux démos sont livrées.

Fonctionnalités de sgcQUIC

Découvrir HTTP/3 depuis HTTP/2

Un serveur annonce HTTP/3 avec un en-tête Alt-Svc. Gère OnAltSvc et tu peux faire passer une connexion existante vers QUIC lorsque l'origine le propose.

Client HTTP/2

Ressources

Référence, démos et documentation

Les projets de démo sont livrés dans le téléchargement, sous Demos\22.QUIC_Protocol. Il y en a six.

	Composant client HTTP/3 Ce qu'expose `TsgcHTTP3Client`, propriété par propriété.	Ouvrir
	Composant serveur HTTP/3 Le côté serveur, y compris la contrainte OpenSSL 3.5.	Ouvrir
	Composant client QUIC Des flux QUIC bruts sans la couche HTTP/3.	Ouvrir
	Fonctionnalités de sgcQUIC QPACK, 0-RTT, migration de connexion, WebTransport et le reste.	Ouvrir
	Télécharger l'essai Un installeur par version d'IDE, avec les composants QUIC déjà inclus.	Ouvrir
	Aide en ligne La référence générée, toujours en phase avec la version actuelle.	Ouvrir

Lectures associées : les composants client et serveur QUIC et les composants HTTP/3. Si tu hésites entre plusieurs transports, le guide des transports temps réel les compare. Chaque produit a son propre démarrage rapide, listé sur la page de prise en main.

FAQ

Questions sur le démarrage rapide de sgcQUIC

TsgcHTTP3Client, de l'unité sgcQUIC, sur la page de palette SGC QUIC. Ajoute sgcHTTP3_Classes pour TsgcHTTP3Response, qui est le type du paramètre de OnResponse, et sgcHTTP_AltSvc si tu gères OnAltSvc. La page de palette contient aussi TsgcQUICClient, TsgcQUICServer et TsgcHTTP3Server.

Cela dépend du côté que tu construis. Le client a besoin de l'API QUIC ajoutée dans OpenSSL 3.2, ou d'une version quictls, et la bibliothèque le dit dans le message qu'elle lève : QUIC is not available. Requires quictls/openssl or OpenSSL 3.2+. Le serveur a besoin de la 3.5 ou supérieure, car il appelle SSL_new_listener, et son message d'erreur nomme explicitement cette version. Livre libcrypto-3.dll et libssl-3.dll à côté de ton exécutable. msquic n'est pas utilisé.

Parce qu'ils sont en lecture seule. TsgcHTTP3Client les déclare comme property Host: string read FHost et property Port: Integer read FPort, ils indiquent donc la connexion en cours au lieu de la configurer. Passe une URL complète à Get, Post, Put ou Delete, ou appelle d'abord Connect(const aHost: string; aPort: Integer = 443).

Un simple TNotifyEvent, donc procedure(Sender: TObject). Idem pour OnDisconnect. Cela diffère des composants WebSocket, dont les événements te transmettent un TsgcWSConnection, et c'est une source fréquente d'erreur de compilation au premier essai. OnResponse est procedure(Sender: TObject; const aResponse: TsgcHTTP3Response) et OnError est procedure(Sender: TObject; const aError: string).

Depuis l'objet de réponse sur OnResponse. TsgcHTTP3Response expose StatusCode, Headers sous forme de TStringList, et GetDataAsString pour le corps. La méthode Get elle-même ne renvoie que le corps sous forme de chaîne, c'est pourquoi la démo branche aussi OnResponse.

SGC_PACK_QUIC est défini à la ligne 872 de sgcVer.inc, dans le bloc {$IFDEF SGC_EDT_ALL} qui va de la ligne 870 à la ligne 874. Donc All-Access. Le bloc du pack lui-même, lignes 894 à 899, se trouve aussi dans un {$IFDEF SGC_INDY_LIB}, la bibliothèque Indy personnalisée doit donc aussi faire partie de la version. Dans ce bloc, SGC_QUIC est à la ligne 896, SGC_HTTP3 à la ligne 897 et SGC_WEBTRANSPORT à la ligne 898.

Non. L'installeur d'essai est propre à chaque version d'IDE et contient déjà les composants QUIC et HTTP/3, et il n'existe pas de fichier de package spécifique à QUIC. Installe sgcWebSockets et la page de palette SGC QUIC apparaît lorsque l'édition l'active.

Oui, et tu devrais. IsOpenSSL_QUIC_Available indique si l'OpenSSL chargé expose la méthode client QUIC, et IsOpenSSL_QUIC_TLS_Available fait de même pour les callbacks TLS de QUIC. La démo du client QUIC livrée écrit les deux dans son journal au démarrage, ce qui transforme un échec de connexion mystérieux en une réponse d'une ligne.

sgcQUIC en cinq minutes