sgcQUIC w pięć minut

QUIC i HTTP/3 w natywnym Object Pascal, na silniku QUIC wbudowanym w OpenSSL. W pakiecie są cztery komponenty. Najkrótsza droga do czegoś działającego wiedzie przez klienta HTTP/3, więc ta strona wykonuje jedno żądanie, odczytuje kod statusu i dokładnie wyjaśnia, jakiego OpenSSL potrzebujesz.

QUIC RFC 9000 i HTTP/3 RFC 9114
OpenSSL 3.2 lub nowszy dla klienta
Edycja All-Access

Czego potrzebuje pierwsze żądanie

Jeden komponent, jeden adres URL i dwie biblioteki OpenSSL obok pliku wykonywalnego.

Komponent

TsgcHTTP3Client na stronie palety SGC QUIC, zadeklarowany w sgcQUIC.pas. Strona zawiera także TsgcQUICClient, TsgcQUICServer i TsgcHTTP3Server.

Jednostka

sgcQUIC dla komponentu. Dodaj sgcHTTP3_Classes dla TsgcHTTP3Response oraz sgcHTTP_AltSvc, jeśli obsługujesz zdarzenie Alt-Svc.

Wywołanie

Get(aURL) zwraca treść jako string i zgłasza wyjątek w razie niepowodzenia. Kod statusu i nagłówki docierają osobno, w OnResponse.

Wymaganie dotyczące OpenSSL

Klient potrzebuje API QUIC z OpenSSL 3.2 lub nowszego albo kompilacji quictls. Serwer potrzebuje wersji 3.5 lub nowszej, ponieważ wywołuje API, które istnieje tylko tam. Dołącz libcrypto-3.dll i libssl-3.dll obok pliku wykonywalnego, tak jak robi to każdy folder dema.

Wymagania i edycje

Kolumna edycji to define, który ogranicza kod, wraz z linią w Source/sgcVer.inc, w której się znajduje.

Co Wartość
IDE Od Delphi 7 do RAD Studio 13 oraz od C++Builder 2007 do 13. Nie ma osobnego pakietu sgcQUIC do pobrania: komponenty znajdują się w grupie pakietów sgcWebSockets.
Klauzula uses sgcQUIC, a także sgcHTTP3_Classes dla obiektu odpowiedzi i sgcHTTP_AltSvc dla typów Alt-Svc.
Define pakietu SGC_PACK_QUIC jest zdefiniowany w linii 872, wewnątrz bloku {$IFDEF SGC_EDT_ALL}, który biegnie od linii 870 do linii 874. Czyli All-Access.
Definy funkcji Wewnątrz bloku {$IFDEF SGC_PACK_QUIC} w liniach 894 do 899: SGC_QUIC w linii 896, SGC_HTTP3 w linii 897 i SGC_WEBTRANSPORT w linii 898. Wszystkie trzy znajdują się wewnątrz {$IFDEF SGC_INDY_LIB} w linii 895, więc kompilacja bez własnej biblioteki Indy nie dostaje żadnego z nich.
OpenSSL, klient 3.2 lub nowszy albo kompilacja quictls. Biblioteka sama to mówi: błąd zgłaszany, gdy QUIC jest niedostępny, brzmi QUIC is not available. Requires quictls/openssl or OpenSSL 3.2+.
OpenSSL, serwer 3.5 lub nowszy. Serwer QUIC wywołuje SSL_new_listener, a błąd zgłaszany, gdy go brakuje, brzmi QUIC Server requires OpenSSL 3.5 or later. msquic nie jest używany i nie jest potrzebny.
Platformy Brak warunku platformy na poziomie jednostki w sgcQUIC.pas, sgcQUIC_Client.pas, sgcHTTP3_Client.pas ani sgcHTTP3_Server.pas, a wszystkie cztery komponenty są zarejestrowane z ComponentPlatforms(0). Jednostka serwera wybiera API gniazd dla danej platformy, z gałęzią zarówno dla Windows, jak i POSIX.

Nie masz pewności, czy silnik jest dostępny w czasie działania? Wywołaj IsOpenSSL_QUIC_Available, które zwraca, czy załadowany OpenSSL udostępnia metodę klienta QUIC. Dostarczane demo klienta QUIC zapisuje to w logu przy uruchomieniu właśnie z tego powodu.

Zainstaluj i znajdź stronę palety

Nie ma osobnego instalatora sgcQUIC. Komponenty przychodzą z sgcWebSockets i pojawiają się, gdy edycja je włącza.

1. Rozpakuj

Rozpakuj pobrany plik sgcWebSockets do folderu, który poniżej nazywamy {$DIR}.

2. Ścieżka biblioteki

Tools, Options, Library. Dodaj {$DIR}\source oraz folder lib dla swojego IDE, na przykład {$DIR}\libD13\$(Platform).

3. Zbuduj pakiety

Otwórz grupę pakietów dla swojej wersji IDE w {$DIR}\Packages\. Najpierw skompiluj uruchomieniowy .dpk, a potem zainstaluj ten czasu projektowania z prefiksem dcl. Nie ma pakietu specyficznego dla QUIC.

4. Sprawdź paletę

Pojawia się strona o nazwie SGC QUIC z TsgcQUICClient, TsgcQUICServer, TsgcHTTP3Client i TsgcHTTP3Server. Jeśli strony brakuje, kompilacja nie jest All-Access, ponieważ SGC_PACK_QUIC jest zdefiniowany tylko w linii 872 wewnątrz tego bloku.

5. Umieść OpenSSL obok pliku exe

Skopiuj libcrypto-3.dll i libssl-3.dll obok swojego pliku wykonywalnego, wersja 3.2 lub nowsza dla klienta i 3.5 lub nowsza dla serwera. Każdy folder w Demos\22.QUIC_Protocol je zawiera, więc możesz skopiować stamtąd.

Jedno żądanie HTTP/3

Utwórz klienta, podepnij trzy zdarzenia, wywołaj Get. Odpowiedź wraca jako tekst, a kod statusu dociera w 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 i Delete mają ten sam kształt, a każde ma przeciążenie ze strumieniem dla treści, której nie chcesz trzymać w tekście. Connect(const aHost: string; aPort: Integer = 443) otwiera połączenie przed pierwszym żądaniem, gdy chcesz rozdzielić oba kroki.

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;

Odczyt FClient.Host i FClient.Port wewnątrz OnConnect to dokładnie to, do czego służą te dwie właściwości. Raportują połączenie, nie konfigurują go.

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;

Uruchom to raz przed czymkolwiek innym. Jeśli oba zwrócą false, OpenSSL obok twojego pliku wykonywalnego nie ma QUIC, a każda późniejsza awaria połączenia jest objawem tego jednego faktu, a nie sieci.

Pierwsze dwie karty pochodzą z dostarczanego dema Demos\22.QUIC_Protocol\03.HTTP3_Client\FHTTP3Client.pas, z kontrolkami formularza zastąpionymi literałami. Trzecia to sprawdzenie dostępności w czasie działania z 01.QUIC_Client\FQUICClient.pas. W tym folderze jest sześć dem QUIC, w tym para WebTransport.

Odczytaj kod statusu, nie tylko treść

Get zwraca treść. Obiekt odpowiedzi niesie całą resztę i dociera we własnym zdarzeniu.

Wartość zwracana

Get zwraca treść odpowiedzi jako string i zgłasza wyjątek w razie niepowodzenia, dlatego demo opakowuje go w try except. Treść o oczekiwanej długości to pierwszy dowód.

OnResponse

procedure(Sender: TObject; const aResponse: TsgcHTTP3Response). StatusCode to liczba, której naprawdę potrzebujesz, Headers to TStringList, a GetDataAsString zwraca treść ponownie z obiektu odpowiedzi.

OnConnect

Zwykły TNotifyEvent. Samo jego wywołanie oznacza, że QUIC został wynegocjowany i sesja HTTP/3 się otworzyła, czyli część, która najczęściej zawodzi przy pierwszym uruchomieniu.

Zanim obwinisz kod

IsOpenSSL_QUIC_Available odpowiada na jedyne pytanie, które warto zadać najpierw. QUIC działa też przez UDP 443, a sieć, która dopuszcza TCP 443, niekoniecznie dopuszcza to.

Co zwykle idzie nie tak za pierwszym razem

Sześć problemów odpowiada za niemal każde nieudane pierwsze żądanie.

Nie można przypisać do Host ani Port

W TsgcHTTP3Client są tylko do odczytu, zadeklarowane jako property Host: string read FHost i property Port: Integer read FPort. Raportują, gdzie klient jest połączony. Aby wybrać cel, przekaż pełny adres URL do Get lub wywołaj Connect(aHost, aPort).

QUIC jest niedostępny

Załadowany OpenSSL jest zbyt stary albo został zbudowany bez QUIC. Klient wymaga wersji 3.2 lub nowszej albo quictls. Zanim obwinisz sieć, sprawdź w czasie działania przez IsOpenSSL_QUIC_Available.

Serwer się nie uruchamia

Serwer QUIC wymaga OpenSSL 3.5 lub nowszego, ponieważ wywołuje SSL_new_listener. Kompilacja 3.2 wystarcza dla klienta, ale nie dla serwera, a komunikat błędu mówi to wprost.

Zła liczba parametrów w OnConnect

OnConnect i OnDisconnect w tym komponencie to zwykłe TNotifyEvent, więc procedura obsługi przyjmuje tylko Sender: TObject. Nie przekazują obiektu połączenia, w przeciwieństwie do komponentów WebSocket.

UDP jest zablokowany

QUIC działa przez UDP na porcie 443, a wiele sieci firmowych dopuszcza TCP 443 i odrzuca UDP 443. Jeśli przeglądarka dociera do hosta przez HTTP/3, a twoja aplikacja nie, podejrzewaj firewall, zanim kod.

Brakuje strony palety

SGC_PACK_QUIC jest zdefiniowany tylko w linii 872, wewnątrz bloku All-Access. Wymaga też SGC_INDY_LIB, ponieważ cały blok pakietu w liniach 894 do 899 znajduje się wewnątrz tego warunku.

Poza pierwszym żądaniem

Cztery kierunki, wszystkie w tym samym pakiecie.

Uruchom serwer HTTP/3

TsgcHTTP3Server obsługuje HTTP/3 bezpośrednio przez QUIC. Pamiętaj o dolnej granicy OpenSSL 3.5 po stronie serwera.

Komponent serwera HTTP/3

Czysty QUIC, bez HTTP

TsgcQUICClient i TsgcQUICServer dają strumienie QUIC bez warstwy HTTP/3, czyli to, czego potrzebujesz dla własnego protokołu wymagającego multipleksowania bez blokowania head of line.

Klient QUIC i serwer QUIC

WebTransport

Strumienie dwukierunkowe i datagramy do przeglądarki przez HTTP/3, ograniczone przez SGC_WEBTRANSPORT w linii 898. W pakiecie są dwa dema.

Funkcje sgcQUIC

Wykryj HTTP/3 z poziomu HTTP/2

Serwer ogłasza HTTP/3 nagłówkiem Alt-Svc. Obsłuż OnAltSvc, a będziesz mógł uaktualnić istniejące połączenie do QUIC, gdy serwer źródłowy to oferuje.

Klient HTTP/2

Dokumentacja, dema i materiały

Projekty demo znajdują się w pobranym pakiecie, w Demos\22.QUIC_Protocol. Jest ich sześć.

Komponent klienta HTTP/3 Co udostępnia TsgcHTTP3Client, właściwość po właściwości.
Komponent serwera HTTP/3 Strona serwera, w tym wymaganie OpenSSL 3.5.
Komponent klienta QUIC Czyste strumienie QUIC bez warstwy HTTP/3.
Funkcje sgcQUIC QPACK, 0-RTT, migracja połączeń, WebTransport i reszta.
Pobierz wersję próbną Jeden instalator na wersję IDE, z komponentami QUIC już w środku.
Pomoc online Generowana dokumentacja, zawsze zgodna z bieżącym wydaniem.

Powiązane lektury: komponenty klienta i serwera QUIC oraz komponenty HTTP/3. Jeśli wybierasz między transportami, przewodnik po transporcie w czasie rzeczywistym je porównuje. Każdy produkt ma własny szybki start, wymieniony na stronie pierwszych kroków.

Pytania o szybki start sgcQUIC

TsgcHTTP3Client, z jednostki sgcQUIC, na stronie palety SGC QUIC. Dodaj sgcHTTP3_Classes dla TsgcHTTP3Response, który jest typem parametru OnResponse, oraz sgcHTTP_AltSvc, jeśli obsługujesz OnAltSvc. Strona palety zawiera także TsgcQUICClient, TsgcQUICServer i TsgcHTTP3Server.
Zależy to od tego, którą stronę budujesz. Klient potrzebuje API QUIC dodanego w OpenSSL 3.2 albo kompilacji quictls, a biblioteka mówi to w zgłaszanym komunikacie: QUIC is not available. Requires quictls/openssl or OpenSSL 3.2+. Serwer potrzebuje wersji 3.5 lub nowszej, ponieważ wywołuje SSL_new_listener, a jego komunikat błędu wprost wymienia tę wersję. Dołącz libcrypto-3.dll i libssl-3.dll obok pliku wykonywalnego. msquic nie jest używany.
Ponieważ są tylko do odczytu. TsgcHTTP3Client deklaruje je jako property Host: string read FHost i property Port: Integer read FPort, więc raportują bieżące połączenie zamiast je konfigurować. Przekaż pełny adres URL do Get, Post, Put lub Delete albo najpierw wywołaj Connect(const aHost: string; aPort: Integer = 443).
Zwykły TNotifyEvent, czyli procedure(Sender: TObject). To samo dotyczy OnDisconnect. Różni się to od komponentów WebSocket, których zdarzenia przekazują TsgcWSConnection, i jest częstym źródłem pierwszego błędu kompilacji. OnResponse to procedure(Sender: TObject; const aResponse: TsgcHTTP3Response), a OnError to procedure(Sender: TObject; const aError: string).
Z obiektu odpowiedzi w OnResponse. TsgcHTTP3Response udostępnia StatusCode, Headers jako TStringList oraz GetDataAsString dla treści. Sama metoda Get zwraca tylko treść jako tekst, dlatego demo podpina także OnResponse.
SGC_PACK_QUIC jest zdefiniowany w linii 872 pliku sgcVer.inc, wewnątrz bloku {$IFDEF SGC_EDT_ALL}, który biegnie od linii 870 do linii 874. Czyli All-Access. Sam blok pakietu, linie 894 do 899, znajduje się też wewnątrz {$IFDEF SGC_INDY_LIB}, więc w kompilacji musi być również własna biblioteka Indy. Wewnątrz tego bloku SGC_QUIC to linia 896, SGC_HTTP3 to linia 897, a SGC_WEBTRANSPORT to linia 898.
Nie. Instalator wersji próbnej jest przypisany do wersji IDE i zawiera już komponenty QUIC i HTTP/3, a pliku pakietu specyficznego dla QUIC nie ma. Zainstaluj sgcWebSockets, a strona palety SGC QUIC pojawi się, gdy edycja ją włącza.
Tak, i powinieneś. IsOpenSSL_QUIC_Available zwraca, czy załadowany OpenSSL udostępnia metodę klienta QUIC, a IsOpenSSL_QUIC_TLS_Available robi to samo dla wywołań zwrotnych QUIC TLS. Dostarczane demo klienta QUIC zapisuje oba w logu przy uruchomieniu, co zamienia tajemniczą awarię połączenia w odpowiedź w jednej linijce.
Najkorzystniejsza oferta: All-AccessWszystkie produkty eSeGeCe, ze wsparciem Premium w cenie, już od €1,059 rocznie.
Zobacz cennik All-Access

Gotowy wypróbować HTTP/3 z Delphi?

Pobierz wersję próbną i uruchom demo klienta HTTP/3 na prawdziwym serwerze źródłowym.