Guida rapida di sgcQUIC

In sintesi

Cosa serve per la prima richiesta

Un componente, un URL e due librerie OpenSSL accanto al tuo eseguibile.

Componente

TsgcHTTP3Client nella pagina SGC QUIC della palette, dichiarato in sgcQUIC.pas. La pagina contiene anche TsgcQUICClient, TsgcQUICServer e TsgcHTTP3Server.

Unit

sgcQUIC per il componente. Aggiungi sgcHTTP3_Classes per TsgcHTTP3Response e sgcHTTP_AltSvc se gestisci l'evento Alt-Svc.

La chiamata

Get(aURL) restituisce il corpo come string e solleva un'eccezione in caso di errore. Il codice di stato e gli header arrivano separatamente, in OnResponse.

Il requisito OpenSSL

Il client richiede l'API QUIC di OpenSSL 3.2 o successivo, oppure una build quictls. Il server richiede la 3.5 o successiva, perché chiama un'API che esiste solo lì. Distribuisci libcrypto-3.dll e libssl-3.dll accanto al tuo eseguibile, come fa ogni cartella delle demo.

Prima di iniziare

Requisiti ed edizioni

La colonna dell'edizione indica il define che regola il codice, con la riga in cui si trova in Source/sgcVer.inc.

Cosa	Valore
IDE	Da Delphi 7 a RAD Studio 13 e da C++Builder 2007 a 13. Non esiste un download separato di sgcQUIC: i componenti sono nel gruppo di package di sgcWebSockets.
Clausola uses	`sgcQUIC`, più `sgcHTTP3_Classes` per l'oggetto risposta e `sgcHTTP_AltSvc` per i tipi Alt-Svc.
Define del pacchetto	`SGC_PACK_QUIC` è definito alla riga 872, dentro il blocco `{$IFDEF SGC_EDT_ALL}` che va dalla riga 870 alla riga 874. Quindi All-Access.
Define delle funzionalità	Dentro il blocco `{$IFDEF SGC_PACK_QUIC}` alle righe da 894 a 899: `SGC_QUIC` alla riga 896, `SGC_HTTP3` alla riga 897 e `SGC_WEBTRANSPORT` alla riga 898. Tutti e tre si trovano dentro un `{$IFDEF SGC_INDY_LIB}` alla riga 895, quindi una build senza la libreria Indy personalizzata non ottiene nessuno dei tre.
OpenSSL, client	3.2 o successivo, oppure una build quictls. Lo dice la libreria stessa: l'errore sollevato quando QUIC non è disponibile recita QUIC is not available. Requires quictls/openssl or OpenSSL 3.2+.
OpenSSL, server	3.5 o successivo. Il server QUIC chiama `SSL_new_listener` e l'errore che solleva quando manca recita QUIC Server requires OpenSSL 3.5 or later. msquic non viene usato e non serve.
Piattaforme	Nessuna guardia di piattaforma a livello di unit in `sgcQUIC.pas`, `sgcQUIC_Client.pas`, `sgcHTTP3_Client.pas` o `sgcHTTP3_Server.pas`, e tutti e quattro i componenti sono registrati con `ComponentPlatforms(0)`. L'unit del server seleziona l'API dei socket per piattaforma, con un ramo Windows e uno POSIX.

Non sei sicuro che il motore sia presente a runtime? Chiama IsOpenSSL_QUIC_Available, che restituisce se l'OpenSSL che hai caricato espone il metodo client QUIC. La demo inclusa del client QUIC lo registra all'avvio proprio per questo motivo.

Passo 1

Installa e trova la pagina della palette

Non esiste un installer separato di sgcQUIC. I componenti arrivano con sgcWebSockets e compaiono quando l'edizione li abilita.

1. Decomprimi

Decomprimi il download di sgcWebSockets in una cartella, chiamata {$DIR} qui sotto.

2. Library path

Tools, Options, Library. Aggiungi {$DIR}\source e la cartella lib per il tuo IDE, per esempio {$DIR}\libD13\$(Platform).

3. Compila i package

Apri il gruppo di package per la versione del tuo IDE in {$DIR}\Packages\. Compila prima il .dpk di runtime, poi installa quello di design-time dcl. Non esiste un package specifico per QUIC.

4. Controlla la palette

Compare una pagina chiamata SGC QUIC con TsgcQUICClient, TsgcQUICServer, TsgcHTTP3Client e TsgcHTTP3Server. Se la pagina manca, la build non è All-Access, perché SGC_PACK_QUIC è definito solo alla riga 872 dentro quel blocco.

5. Metti OpenSSL accanto all'exe

Copia libcrypto-3.dll e libssl-3.dll accanto al tuo eseguibile, versione 3.2 o successiva per un client e 3.5 o successiva per un server. Ogni cartella in Demos\22.QUIC_Protocol le include, quindi puoi copiarle da lì.

QuickStart

Una richiesta HTTP/3

Crea il client, collega tre eventi, chiama Get. La risposta torna come stringa e il codice di stato arriva in 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 e Delete hanno la stessa forma e ciascuno ha un overload con stream per un corpo che non vuoi tenere in una stringa. Connect(const aHost: string; aPort: Integer = 443) apre la connessione prima della prima richiesta quando vuoi separare le due operazioni.

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;

Leggere FClient.Host e FClient.Port dentro OnConnect è esattamente lo scopo di quelle due proprietà. Riportano la connessione, non la configurano.

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;

Eseguilo una volta prima di qualsiasi altra cosa. Se entrambi restituiscono false, l'OpenSSL accanto al tuo eseguibile non ha QUIC e ogni errore di connessione successivo è un sintomo di questo fatto e non della rete.

Le prime due schede provengono dalla demo inclusa Demos\22.QUIC_Protocol\03.HTTP3_Client\FHTTP3Client.pas, con i controlli del form sostituiti da valori letterali. La terza è il controllo di disponibilità a runtime di 01.QUIC_Client\FQUICClient.pas. In quella cartella ci sono sei demo QUIC, inclusa una coppia WebTransport.

Passo 2

Leggi il codice di stato, non solo il corpo

Get restituisce il corpo. L'oggetto risposta contiene tutto il resto e arriva con un proprio evento.

Il valore restituito

Get restituisce il corpo della risposta come string e solleva un'eccezione in caso di errore, quindi la demo lo racchiude in un try except. Un corpo della lunghezza che ti aspetti è la prima prova.

`OnResponse`

procedure(Sender: TObject; const aResponse: TsgcHTTP3Response). StatusCode è il numero che ti serve davvero, Headers è un TStringList e GetDataAsString ti restituisce di nuovo il corpo dall'oggetto risposta.

`OnConnect`

Un semplice TNotifyEvent. Se viene generato, significa che QUIC ha negoziato e la sessione HTTP/3 si è aperta, che è la parte più probabile a fallire alla prima esecuzione.

Prima di dare la colpa al codice

IsOpenSSL_QUIC_Available risponde all'unica domanda che vale la pena porsi per prima. QUIC funziona anche su UDP 443, e una rete che consente TCP 443 non necessariamente consente quello.

Problemi comuni

Cosa va storto di solito la prima volta

Sei problemi spiegano quasi ogni prima richiesta fallita.

Impossibile assegnare Host o Port

Sono di sola lettura in TsgcHTTP3Client, dichiarate come property Host: string read FHost e property Port: Integer read FPort. Riportano dove il client è connesso. Per scegliere una destinazione, passa un URL completo a Get oppure chiama Connect(aHost, aPort).

QUIC non è disponibile

L'OpenSSL che hai caricato è troppo vecchio o è stato compilato senza QUIC. Il client richiede la 3.2 o successiva, oppure quictls. Verifica a runtime con IsOpenSSL_QUIC_Available prima di dare la colpa alla rete.

Il server non parte

Il server QUIC richiede OpenSSL 3.5 o successivo, perché chiama SSL_new_listener. Una build 3.2 basta per il client e non per il server, e il messaggio di errore lo dice in modo esplicito.

Numero di parametri errato in OnConnect

OnConnect e OnDisconnect di questo componente sono semplici TNotifyEvent, quindi il gestore accetta solo Sender: TObject. Non ti passano un oggetto di connessione, a differenza dei componenti WebSocket.

UDP è bloccato

QUIC funziona su UDP sulla porta 443 e molte reti aziendali consentono TCP 443 e scartano UDP 443. Se un browser raggiunge l'host via HTTP/3 e la tua applicazione no, sospetta il firewall prima del codice.

La pagina della palette manca

SGC_PACK_QUIC è definito solo alla riga 872, dentro il blocco All-Access. Richiede anche SGC_INDY_LIB, perché l'intero blocco del pacchetto alle righe da 894 a 899 si trova dentro quella guardia.

Approfondisci

Oltre la prima richiesta

Quattro direzioni, tutte nello stesso pacchetto.

Esegui un server HTTP/3

TsgcHTTP3Server serve HTTP/3 direttamente su QUIC. Ricorda il requisito minimo OpenSSL 3.5 lato server.

Componente server HTTP/3

QUIC puro, senza HTTP

TsgcQUICClient e TsgcQUICServer ti danno gli stream QUIC senza il livello HTTP/3, che è ciò che serve per un protocollo personalizzato che richiede multiplexing senza head of line blocking.

Client QUIC e server QUIC

WebTransport

Stream bidirezionali e datagram verso un browser su HTTP/3, regolati da SGC_WEBTRANSPORT alla riga 898. Sono incluse due demo.

Funzionalità di sgcQUIC

Scopri HTTP/3 da HTTP/2

Un server annuncia HTTP/3 con un header Alt-Svc. Gestisci OnAltSvc e potrai passare una connessione esistente a QUIC quando l'origine lo offre.

Client HTTP/2

Risorse

Riferimento, demo e documentazione

I progetti demo sono inclusi nel download, in Demos\22.QUIC_Protocol. Sono sei.

	Componente client HTTP/3 Cosa espone `TsgcHTTP3Client`, proprietà per proprietà.	Apri
	Componente server HTTP/3 Il lato server, incluso il requisito OpenSSL 3.5.	Apri
	Componente client QUIC Stream QUIC puri senza il livello HTTP/3.	Apri
	Funzionalità di sgcQUIC QPACK, 0-RTT, migrazione della connessione, WebTransport e il resto.	Apri
	Scarica la versione di prova Un installer per ogni versione dell'IDE, con i componenti QUIC già inclusi.	Apri
	Guida online Il riferimento generato, sempre allineato alla versione corrente.	Apri

Letture correlate: i componenti client e server QUIC e i componenti HTTP/3. Se stai scegliendo tra diversi trasporti, la guida ai trasporti in tempo reale li confronta. Ogni prodotto ha la propria guida rapida, elencata nella pagina per iniziare.

FAQ

Domande sulla guida rapida di sgcQUIC

TsgcHTTP3Client, dall'unit sgcQUIC, nella pagina SGC QUIC della palette. Aggiungi sgcHTTP3_Classes per TsgcHTTP3Response, che è il tipo del parametro di OnResponse, e sgcHTTP_AltSvc se gestisci OnAltSvc. La pagina della palette contiene anche TsgcQUICClient, TsgcQUICServer e TsgcHTTP3Server.

Dipende da quale lato stai costruendo. Il client richiede l'API QUIC aggiunta in OpenSSL 3.2, oppure una build quictls, e la libreria lo dice nel messaggio che solleva: QUIC is not available. Requires quictls/openssl or OpenSSL 3.2+. Il server richiede la 3.5 o successiva, perché chiama SSL_new_listener, e il suo messaggio di errore indica esplicitamente quella versione. Distribuisci libcrypto-3.dll e libssl-3.dll accanto al tuo eseguibile. msquic non viene usato.

Perché sono di sola lettura. TsgcHTTP3Client le dichiara come property Host: string read FHost e property Port: Integer read FPort, quindi riportano la connessione corrente invece di configurarla. Passa un URL completo a Get, Post, Put o Delete, oppure chiama prima Connect(const aHost: string; aPort: Integer = 443).

Un semplice TNotifyEvent, quindi procedure(Sender: TObject). Lo stesso vale per OnDisconnect. Questo differisce dai componenti WebSocket, i cui eventi ti passano un TsgcWSConnection, ed è una fonte comune di errori di compilazione al primo tentativo. OnResponse è procedure(Sender: TObject; const aResponse: TsgcHTTP3Response) e OnError è procedure(Sender: TObject; const aError: string).

Dall'oggetto risposta in OnResponse. TsgcHTTP3Response espone StatusCode, Headers come TStringList e GetDataAsString per il corpo. Il metodo Get restituisce solo il corpo come stringa, ed è per questo che la demo collega anche OnResponse.

SGC_PACK_QUIC è definito alla riga 872 di sgcVer.inc, dentro il blocco {$IFDEF SGC_EDT_ALL} che va dalla riga 870 alla riga 874. Quindi All-Access. Anche il blocco del pacchetto, righe da 894 a 899, si trova dentro un {$IFDEF SGC_INDY_LIB}, quindi anche la libreria Indy personalizzata deve far parte della build. Dentro quel blocco, SGC_QUIC è alla riga 896, SGC_HTTP3 alla riga 897 e SGC_WEBTRANSPORT alla riga 898.

No. L'installer della versione di prova è per versione dell'IDE e contiene già i componenti QUIC e HTTP/3, e non esiste un file di package specifico per QUIC. Installa sgcWebSockets e la pagina SGC QUIC della palette compare quando l'edizione la abilita.

Sì, e dovresti. IsOpenSSL_QUIC_Available restituisce se l'OpenSSL caricato espone il metodo client QUIC, e IsOpenSSL_QUIC_TLS_Available fa lo stesso per le callback TLS di QUIC. La demo inclusa del client QUIC scrive entrambi nel proprio log all'avvio, il che trasforma un misterioso errore di connessione in una risposta di una riga.

sgcQUIC in cinque minuti