HTTP1
Click here to see this page in full context

HTTP/1

TsgcHTTP1Client is a non-visual component that inherits from TIdHTTP indy component and adds some new properties.

This component is located in sgcHTTP unit.

TLSOptions

Allows you to configure how to connect to secure SSL/TLS servers using the HTTP/1 protocol.

 

ALPNProtocols: list of the ALPN protocols which will be sent to the server.

RootCertFile: path to root certificate file.

CertFile: path to certificate file.

KeyFile: path to certificate key file.

Password: if the certificate is secured with a password, set it here.

VerifyCertificate: if the certificate must be verified, enable this property. Use the event OnSSLVerifyPeer to customize the SSL verification.

VerifyDepth: is an Integer property that represents the maximum number of links permitted when verification is performed for the X.509 certificate.

Version: by default uses TLS 1.0. If the server requires a higher TLS version, it can be selected here.

Preset: applies a set of secure defaults in a single assignment. With tlspCustom (the default) every option keeps the value configured manually. Setting tlspSecureDefaults enables VerifyCertificate, raises Version to at least TLS 1.2 (when a lower or undefined version was configured) and enables hostname verification of the server certificate.

Proxy: here you can define if you want to connect through a Proxy Server, you can connect to the following proxy servers:

pxyHTTP: HTTP Proxy Server.

pxySocks4: SOCKS4 Proxy Server.

pxySocks4A: SOCKS4A Proxy Server.

pxySocks5: SOCKS5 Proxy Server.

IOHandler: select which library you will use to connect using TLS.

iohOpenSSL: uses OpenSSL library and is the default for Indy components. Requires deploying OpenSSL libraries for win32/win64.

iohSChannel: uses Secure Channel, which is a security protocol implemented by Microsoft for Windows. It does not require deploying OpenSSL libraries. Only works on Windows 32/64 bits.

OpenSSL_Options: configuration of the openSSL libraries.

APIVersion: allows defining which OpenSSL API will be used.

oslAPI_1_0: uses API 1.0 OpenSSL, it's latest supported by Indy

oslAPI_1_1: uses API 1.1 OpenSSL, requires our custom Indy library and allows using OpenSSL 1.1.1 libraries (with TLS 1.3 support).

oslAPI_3_0: uses API 3.0 OpenSSL, requires our custom Indy library and allows using OpenSSL 3.0.0 libraries (with TLS 1.3 support).

LibPath: here you can configure where the OpenSSL libraries are located

oslpNone: this is the default. The OpenSSL libraries should be in the same folder as the binary or in a known path.

oslpDefaultFolder: automatically sets the OpenSSL path where the libraries should be located for all IDE personalities.

oslpCustomFolder: if this is the option selected, define the full path in the property LibPathCustom.

LibPathCustom: when LibPath = oslpCustomFolder define here the full path where the OpenSSL libraries are located.

UnixSymLinks: enable or disable the loading of SymLinks under Unix systems (by default is enabled, except under OSX64):

oslsSymLinksDefault: by default, symlinks are enabled except under OSX64 (macOS Monterey and later fail when trying to load the library without a version).

oslsSymLinksLoadFirst: load symlinks first, before trying to load the versioned libraries.

oslsSymLinksLoad: load symlinks after trying to load the versioned libraries.

oslsSymLinksDontLoad: don't load the SymLinks.

MinVersion: set here the minimum version that will use the client to connect to a secure server. By default, the value is tlsUndefined which means the minimum version is the same which has been set in the Version property. Example: if you want to set the Client to only connect using TLS 1.2 or TLS 1.3 set the following values.

 

    SSLOptions.Version := tls1_3;

    SSLOptions.OpenSSL_Options.MinVersion := tls1_2;

X509Checks: use this property to enable additional X509 certificate validations:

    Mode: select which options will be validated

      oslx509chHostName: verifies the hostname certificate.

      oslx509chIPAddress: verifies the ip address of the certificate.

    HostName: set the hostname if it's different from the request.

    IPAddress: set the ip address if it's different from the request.

 

SChannel_Options: allows you to use a certificate from Windows Certificate Store.

CertHash: is the certificate Hash. You can find the certificate Hash running a dir command in powershell.

CipherList: here you can set which Ciphers will be used (separated by ":"). Example: CALG_AES_256:CALG_AES_128

CertStoreName: the store name where the certificate is stored. Select one of the following:

scsnMY (the default)

scsnCA

scsnRoot

scsnTrust

CertStorePath: the store path where the certificate is stored. Select one of the following:

scspStoreCurrentUser (the default)

scspStoreLocalMachine

 

Log

If the Log property is enabled, it saves socket messages to a specified log file, useful for debugging.

 

LogOptions.FileName: full path to the filename.

 

Authentication

Allows you to authenticate using OAuth2 or JWT.

 

 

RetryOptions

Automatically retries failed HTTP requests using exponential backoff with optional jitter. Retries are disabled by default, so the behaviour is unchanged unless Enabled is set to true. A request is retried when the response status code is in StatusCodes or when a transient network error occurs (connection closed, socket error, connect or read timeout).

Enabled: enables the automatic retry of failed requests. By default false.

MaxRetries: maximum number of retries after the initial request. By default 3.

InitialInterval: delay in milliseconds before the first retry. By default 500.

MaxInterval: maximum delay in milliseconds between retries. By default 30000.

Multiplier: factor applied to the delay after every attempt. By default 2.0, which doubles the delay on each retry: 500, 1000, 2000...

Jitter: random factor between 0 and 1 applied to every delay (0.2 varies each delay by up to 20%), which avoids many clients retrying at exactly the same time. By default 0.2.

HonorRetryAfter: when the server replies with a Retry-After header (as seconds or as an HTTP date, usually with a 429 or 503 response), the client waits the time requested by the server instead of the computed backoff delay. By default true.

StatusCodes: comma-separated list of HTTP status codes that trigger a retry. By default "429,502,503,504".

Example: retry up to 5 times, starting at 1 second between attempts.


oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.RetryOptions.Enabled := True;
oHTTP.RetryOptions.MaxRetries := 5;
oHTTP.RetryOptions.InitialInterval := 1000;
ShowMessage(oHTTP.Get('https://www.esegece.com'));

The AI provider clients (OpenAI, Anthropic, Gemini and the other LLM API clients) use this same retry engine through the RetryOptions property of their Options.

Asynchronous Requests

By default, the HTTP1Client uses blocking requests, so after calling an HTTP request method, the client waits for the response from the server. Alternatively, you can use asynchronous methods to execute these HTTP requests in a secondary thread, avoiding blocking the thread where the request is called. The following asynchronous methods are implemented:

 

 

After calling these methods, instead of waiting for the response, the code continues to the next line, and the response can be handled using the event OnAsyncResponse.

 


procedure OnAsyncResultEvent(Sender: TObject; const aRequest:
    TsgcHTTPAsyncRequest; const aResponse: TIdHTTPResponse);

If there is any error while processing the Asynchronous request, the exception will be raised in the event OnAsyncException.

 

Futures

In Delphi 2010 and later, the client also implements future-style asynchronous requests that do not require any event handler:


function GetFuture(const AURL: string): IsgcFuture<string>;
function PostFuture(const AURL: string; aData: TStream): IsgcFuture<string>;

The request runs on a background thread and the returned future resolves to the response body: call Await to block until the response arrives, ThenProc to consume it in a continuation and OnError to handle failures. Calling Cancel aborts the underlying HTTP request instead of letting it run to completion.


oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.GetFuture('https://www.esegece.com')
  .ThenProc(procedure(const aBody: string)
    begin
      Log(aBody);
    end)
  .OnError(procedure(E: Exception)
    begin
      Log(E.Message);
    end);

Examples

Request a GET method to HTTPs server and using TLS 1.2


oHTTP := TsgcHTTP1Client.Create(nil);
Try
  oHTTP.TLSOptions.Version := tls1_2;
  ShowMessage(oHTTP.Get('https://www.google.es'));
Finally
  oHTTP.Free;
End;

Request a GET method to HTTPs server using openSSL 1.1 and TLS 1.3


oHTTP := TsgcHTTP1Client.Create(nil);
Try
  oHTTP.TLSOptions.OpenSSL_Options.APIVersion := oslAPI_1_1;
  oHTTP.TLSOptions.Version := tls1_3;
  ShowMessage(oHTTP.Get('https://www.google.es'));
Finally
  oHTTP.Free;
End;

Request an Asynchronous POST method and read the response using the OnAsyncResultEvent.

 


procedure OnAsyncExceptionEvent(Sender: TObject; const aThread:
    TsgcThread; const E: Exception);
begin
  Log(E.Message);
end;
procedure OnAsyncResultEvent(Sender: TObject; const aRequest:
    TsgcHTTPAsyncRequest; const aResponse: TIdHTTPResponse);
begin
  if aResponse.ResponseCode = 200 then
    Log('ok', aRequest.Response)
  else 
    Log('error', aRequest.Response);
end;
oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.OnAsyncResult := OnAsyncResultEvent;
oHTTP.OnAsyncException := OnAsyncResultEvent;
oRequest := TStringStream.Create('body');
oResponse := TStringStream.Create('');
oHTTP.PostAsync('https://localhost/test', oRequest, oResponse);

 

Request a GET method to HTTPs server using SChannel for Windows.


oHTTP := TsgcHTTP1Client.Create(nil);
Try
  oHTTP.TLSOptions.IOHandler := iohSChannel;
  oHTTP.TLSOptions.Version := tls1_2;
  ShowMessage(oHTTP.Get('https://www.google.es'));
Finally
  oHTTP.Free;
End;

Request SSE method to get data events

 


oHTTP := TsgcHTTP1Client.Create(nil);
oHTTP.OnSSEMessage := OnSSEMessageEvent;
oHTTP.GetSSE('https://www.yoursite.com/sse');
 
procedure OnSSEMessageEvent(Sender: TObject; const aMessage: string; var Cancel: Boolean);
begin
  ShowMessage(aMessage);
end;

 

Events

OnSSEMessage

 

The event is called when a new SSE message is received.

 

OnSSLVerifyPeer

 

If verify certificate is enabled, in this event you can verify and decide whether to accept the server certificate.

 

OnSSLGetHandler

 

This event is raised before the SSL handler is created. You can create your own SSL handler here (it needs to be inherited from TIdServerIOHandlerSSLBase or TIdIOHandlerSSLBase) and set the properties needed.

 

OnSSLAfterCreateHandler

 

If no custom SSL object has been created, a default one is created using the OpenSSL handler. You can access the SSL handler properties and modify them if needed.

 

OnAsyncResult

 

The event is called after requesting an Async method (using GetAsync, PutAsync... methods). Use the Response parameter to know the result of the request.

 

OnAsyncException

 

If there is any error while processing an async request, this event is called with the exception raised.