Flyology HTTP API reference

Description

Provides origin-bound synchronous and owner-driven composable HTTP exchanges with bounded connection pooling. Synchronous Execute drives the same completion-set operation engine as composable exchanges. Lightweight callers suspend on Flyology I/O; native callers block only their pthread. Protocol modes enable HTTP/1.1, HTTP/2, and HTTP/3 without exposing transport or stream ownership through the request/response API.

Add_Header

procedure Add_Header
  (Item : in out Request; Name : String; Value : String)

Append one end-to-end request field. Framing, connection, upgrade, and Expect fields are client-controlled and rejected here.

Parameters

Item: Request to change
Name: Field name
Value: Field value

Raised exceptions

Constraint_Error: Name, Value, or a client-controlled field is invalid
Flyology: .HTTP.Headers.Headers_Too_Large Request field storage is exhausted

Add_Trailer

procedure Add_Trailer
  (Item : in out Request; Name : String; Value : String)

Append one request trailer field. The client generates the Trailer declaration where required and sends retained trailer values after an unknown-length source finishes on HTTP/1.1, HTTP/2, or HTTP/3. Trailers are rejected for retained or known-length bodies. Known fields affecting framing, routing, authentication, request semantics, or payload interpretation are prohibited, and repeated names are rejected. The caller must know that the field definition permits use in trailers.

Parameters

Item: Request to change
Name: Trailer field name
Value: Trailer field value retained by Item

Raised exceptions

Constraint_Error: Name is prohibited or repeated in request trailers, or Name or Value has invalid HTTP field syntax
Flyology: .HTTP.Headers.Headers_Too_Large Trailer storage is exhausted

Admission

function Admission
  (Operation : Exchange_Operation) return Admission_Certainty

Return current monotonic admission knowledge before typed Finish.

Parameters

Operation: Started exchange to inspect

Return value

Current admission certainty

Admission_Certainty

type Admission_Certainty is
  (Not_Admitted, Possibly_Admitted, Response_Observed);

Monotonic knowledge about possible server admission. This state never moves backward. Response_Observed is diagnostic and does not by itself make a conditional mutation conclusive.

Enumeration literals

Not_Admitted: No request head byte, frame, or datagram was handed to the kernel or a protocol queue
Possibly_Admitted: At least one request handoff occurred, so the server may have accepted the request
Response_Observed: At least one peer response byte or protocol response event was observed; only Response_Complete is conclusive

Body_Complete

function Body_Complete (Item : Response) return Boolean

Report whether body framing is complete and no connection lease remains.

Parameters

Item: Response to inspect

Return value

True after complete body consumption

Raised exceptions

Program_Error: Item is not initialized by Execute

Body_Length

type Body_Length is private;

Known or unknown streaming request body length. Unknown bodies use the active protocol's streaming framing; HTTP/1.1 uses chunked coding.

Body_Size

subtype Body_Size is Flyology.HTTP.Body_Size;

Maximum representable request body byte count.

Certainty

function Certainty (Item : Exchange_Result) return Admission_Certainty

Return admission certainty captured at terminal completion.

Parameters

Item: Result to inspect

Return value

Monotonic admission certainty

Client

type Client (Capacity : Positive := 4) is limited private;

Origin-bound client. Capacity is the maximum number of open plus connecting transports. Configure must complete before concurrent use. Finalize requests shutdown and closes transports. Execute's aliased controlling parameter lets Ada accessibility reject a response that would escape Item's lifetime. Internal retention also protects cleanup during abort and finalization races.

Record fields

Capacity: Maximum open plus connecting transport count

Client_Closed

Client_Closed : exception;

Raised after client shutdown rejects a request or interrupts pool admission.

Client_Diagnostics

type Client_Diagnostics is record
   Transport_Capacity : Positive;
   Pending_Transports : Natural;
   Active_Exchanges    : Natural;
   Reusable_Transports : Natural;
   Closing_Transports  : Natural;
   Admission_Waiters   : Natural;
   Transports_Created  : Natural;
   Transport_Reuses    : Natural;
   Transports_Closed   : Natural;
   Stale_Retries       : Natural;
   Admission_Timeouts  : Natural;
end record;

Coherent client counters. Exchange and transport counts are separate so multiplexed protocols can report several exchanges on one transport without changing this record's meaning.

Record fields

Transport_Capacity: Configured transport slot bound
Pending_Transports: Transports being established
Active_Exchanges: Requests that own protocol exchanges
Reusable_Transports: Established transports eligible for reuse
Closing_Transports: Transports being closed outside the pool lock
Admission_Waiters: Requests waiting for exchange capacity
Transports_Created: Successfully established transports
Transport_Reuses: Exchanges assigned an existing transport
Transports_Closed: Transports removed from the client
Stale_Retries: Idempotent exchanges retried once after an existing transport failed before producing response bytes
Admission_Timeouts: Pool waits whose request deadline expired

Configure

procedure Configure
  (Item         : in out Client;
   Origin_Value : Origin;
   Pool         : Pool_Configuration := Default_Pool_Configuration;
   Connect_Policy : Connect_Target_Filter := null)

Bind a new client to one origin and immutable pool policy. The call does no DNS, socket, TLS, task, or event-loop work. Reconfiguration and an HTTPS origin without a retained TLS backend is rejected.

Parameters

Item: Unconfigured client
Origin_Value: Normalized origin
Pool: Pool retention policy
Connect_Policy: Optional veto over each resolved connect target

Raised exceptions

Program_Error: Item is configured or arguments are invalid

Configure

procedure Configure
  (Item                   : in out Client;
   Origin_Value           : Origin;
   Mode                   : Protocol_Mode;
   HTTP_3_Certificate_DER : Ada.Streams.Stream_Element_Array;
   Pool                   : Pool_Configuration :=
     Default_Pool_Configuration;
   Connect_Policy         : Connect_Target_Filter := null)

Bind a direct HTTP/3 client. Require_HTTP_3 sends QUIC to the HTTPS origin's UDP port and authenticates the server with the pinned DER certificate. No TCP TLS provider is needed because fallback is disabled.

Parameters

Item: Unconfigured client
Origin_Value: Normalized HTTPS origin
Mode: Must be Require_HTTP_3
HTTP_3_Certificate_DER: Expected QUIC peer certificate
Pool: Pool retention policy
Connect_Policy: Optional veto over each resolved connect target

Raised exceptions

Program_Error: Item is configured or arguments are invalid

Configure

procedure Configure
  (Item         : in out Client;
   Origin_Value : Origin;
   Mode         : Protocol_Mode;
   Pool         : Pool_Configuration := Default_Pool_Configuration;
   Connect_Policy : Connect_Target_Filter := null)

Bind a client with an explicit cleartext protocol mode. Negotiated modes require TLS and are rejected here; HTTP_2_Prior_Knowledge is cleartext HTTP/2 without the deprecated Upgrade handshake.

Parameters

Item: Unconfigured client
Origin_Value: Normalized cleartext origin
Mode: HTTP/1.1 or HTTP/2 prior-knowledge behavior
Pool: Pool retention policy
Connect_Policy: Optional veto over each resolved connect target

Raised exceptions

Program_Error: Item is configured or arguments are invalid

Configure

procedure Configure
  (Item         : in out Client;
   Origin_Value : Origin;
   Transport    : Unix_Socket_Transport;
   Pool         : Pool_Configuration := Default_Pool_Configuration)

Bind a client to one cleartext HTTP origin carried over a pathname Unix-domain stream socket. Origin_Value supplies Host and HTTP/2 :authority; Transport supplies only the connect pathname. Configure does not open the socket. Connect_Policy is intentionally absent because no DNS address or Internet endpoint is used.

Parameters

Item: Unconfigured client
Origin_Value: Cleartext origin and request authority
Transport: Explicit pathname Unix-domain socket transport
Pool: Pool retention policy

Raised exceptions

Program_Error: Item is configured, Origin_Value is HTTPS, or configuration arguments are invalid

Configure

procedure Configure
  (Item         : in out Client;
   Origin_Value : Origin;
   Transport    : Unix_Socket_Transport;
   Mode         : Protocol_Mode;
   Pool         : Pool_Configuration := Default_Pool_Configuration)

Bind a client to a cleartext Unix-domain stream transport with an explicit protocol. Mode must be HTTP_1_Only or HTTP_2_Prior_Knowledge. TLS negotiation and HTTP/3 are not Unix socket transport modes.

Parameters

Item: Unconfigured client
Origin_Value: Cleartext origin and request authority
Transport: Explicit pathname Unix-domain socket transport
Mode: HTTP/1.1 or HTTP/2 prior-knowledge behavior
Pool: Pool retention policy

Raised exceptions

Program_Error: Item is configured, Origin_Value is HTTPS, Mode is unsupported, or configuration arguments are invalid

Configure

procedure Configure
  (Item         : in out Client;
   Origin_Value : Origin;
   Backend      : not null access Flyology.IO.TLS.Provider'Class;
   Pool         : Pool_Configuration := Default_Pool_Configuration;
   Connect_Policy : Connect_Target_Filter := null)

Bind a new client to one origin using an explicit TLS provider. The client retains independently owned provider state, so Backend may be finalized after Configure returns. This overload is required for HTTPS and accepted for HTTP so callers may share configuration code.

Parameters

Item: Unconfigured client
Origin_Value: Normalized origin
Backend: Initialized TLS provider retained by Item
Pool: Pool retention policy
Connect_Policy: Optional veto over each resolved connect target

Raised exceptions

Program_Error: Item is configured or arguments are invalid
Flyology: .IO.TLS.TLS_Error Backend cannot be retained

Configure

procedure Configure
  (Item                   : in out Client;
   Origin_Value           : Origin;
   Backend                : not null access Flyology.IO.TLS.Provider'Class;
   Mode                   : Protocol_Mode;
   HTTP_3_Certificate_DER : Ada.Streams.Stream_Element_Array;
   Pool                   : Pool_Configuration :=
     Default_Pool_Configuration;
   Connect_Policy         : Connect_Target_Filter := null)

Bind an HTTPS client with HTTP/3 authentication and TCP fallback. Negotiate_HTTP_3 begins with ALPN h2/http/1.1 and accepts only a same-origin Alt-Svc h3=":port" alternative. The pool retains healthy TCP and QUIC transports together: H3 is preferred when available, while a concurrent exchange can use TCP when the H3 lane is busy or still connecting. A failed H3 establishment is forgotten and retried once through TCP inside the original exchange deadline. Require_HTTP_3 is also accepted and does not use the retained TCP provider.

Parameters

Item: Unconfigured client
Origin_Value: Normalized HTTPS origin
Backend: Initialized ALPN-capable TLS provider retained by Item
Mode: Negotiate_HTTP_3 or Require_HTTP_3
HTTP_3_Certificate_DER: Expected QUIC peer certificate
Pool: Pool retention policy
Connect_Policy: Optional veto over each resolved connect target

Raised exceptions

Program_Error: Item is configured or arguments are invalid
Flyology: .IO.TLS.TLS_Error Backend cannot be retained

Configure

procedure Configure
  (Item         : in out Client;
   Origin_Value : Origin;
   Backend      : not null access Flyology.IO.TLS.Provider'Class;
   Mode         : Protocol_Mode;
   Pool         : Pool_Configuration := Default_Pool_Configuration;
   Connect_Policy : Connect_Target_Filter := null)

Bind a client with a retained TLS provider and explicit protocol mode. Negotiate_HTTP_2 permits HTTP/1.1 fallback; Require_HTTP_2 rejects any other ALPN result. As with the existing provider overload, a cleartext origin is accepted for shared configuration code and does not use TLS.

Parameters

Item: Unconfigured client
Origin_Value: Normalized origin
Backend: Initialized TLS provider retained by Item
Mode: TLS protocol selection behavior
Pool: Pool retention policy
Connect_Policy: Optional veto over each resolved connect target

Raised exceptions

Program_Error: Item is configured, arguments are invalid, or an HTTP/2 negotiation mode receives a backend without ALPN support
Flyology: .IO.TLS.TLS_Error Backend cannot be retained

Connect_Target_Filter

type Connect_Target_Filter is access function
  (Host    : String;
   Address : String;
   Port    : Port_Number) return Boolean;

Optional veto over one resolved Internet connect target. Configure retains it, and the client consults it once for every address the origin host resolves to before any socket is created for that address. An application can refuse loopback, link-local, or private destinations that a name resolves to. Returning False skips that address and the client tries the next one; refusing every resolved address raises Connection_Error and opens no socket. The owner-driven exchange tries permitted IPv4 and IPv6 addresses serially in resolver order. It advances after an immediate connection or handshake failure under the same absolute deadline. The filter runs on the requesting task before each attempt and must not block. Only the initial connect is filtered; this client is bound to one origin and never follows a redirect that leaves it.

Parameters

Host: Configured origin host
Address: Canonical numeric text of one resolved address
Port: Origin port the client would connect to

Return value

True to allow a connection attempt to Address

Connection_Error

Connection_Error : exception;

Raised when the origin cannot be resolved or every resolved address fails before an HTTP exchange starts.

Deadline_After

function Deadline_After (Timeout : Duration) return Monotonic_Deadline

Construct an absolute deadline from the current monotonic clock. Negative Timeout returns No_Deadline; zero is already due.

Parameters

Timeout: Remaining relative budget in seconds

Return value

Absolute monotonic deadline

Declared_Length

function Declared_Length
  (Item : Operation_Request_Body_Source) return Body_Length

Return the source's stable exact or unknown length.

Parameters

Item: Source to inspect

Return value

Stable declared body length

Declared_Length

function Declared_Length
  (Item : Request_Body_Source) return Body_Length

Return the source's stable framing length. Known lengths generate Content-Length; Unknown_Length selects the protocol's streaming framing.

Parameters

Item: Source to inspect before its first read

Return value

Known byte count or Unknown_Length

Default_Pool_Configuration

Default_Pool_Configuration : constant Pool_Configuration := (others => <>);

Default conservative pool policy.

Default_Same_Origin_Redirects

Default_Same_Origin_Redirects : constant Redirect_Configuration :=
  (Mode => Follow_Same_Origin, Maximum_Hops => 5);

Opt-in policy that follows at most five same-origin redirects.

Diagnostics

function Diagnostics (Item : Client) return Client_Diagnostics

Return coherent exchange and transport diagnostics without starting I/O.

Parameters

Item: Client to inspect

Return value

Current and cumulative counters

Exchange_Operation

type Exchange_Operation is new Flyology.Operations.Operation with private;

Full request/response exchange driven on its completion-set owner's stack. The operation terminalizes only after the complete response body is delivered and every transport, stream, pool, source, sink, token, and request borrow is drained or detached.

Exchange_Phase

type Exchange_Phase is
  (Not_Started,
   Admission_Wait,
   Resolving,
   Connecting,
   Securing,
   Sending_Request_Head,
   Sending_Request_Body,
   Waiting_Response_Head,
   Receiving_Response_Body,
   Draining);

Raw exchange stage retained for diagnostics and deterministic tests. Certainty must be consulted separately.

Enumeration literals

Not_Started: No exchange was started
Admission_Wait: Waiting for a pool lease or creation slot
Resolving: Resolving the configured origin
Connecting: Connecting one resolved address
Securing: Establishing the TLS or QUIC security context
Sending_Request_Head: Encoding or transmitting request metadata
Sending_Request_Body: Pulling or transmitting request body bytes
Waiting_Response_Head: Waiting for a complete final response head
Receiving_Response_Body: Delivering decoded response body bytes
Draining: Cancelling or draining retained protocol work

Exchange_Result

type Exchange_Result is private;

Bounded terminal exchange result.

Exchange_Result_Kind

type Exchange_Result_Kind is
  (Response_Complete,
   Pre_Admission_Rejected,
   Cancelled,
   Timed_Out,
   Client_Unavailable,
   Connection_Failed,
   Transport_Failed,
   Request_Source_Failed,
   …,
   Response_Sink_Failed);

Typed terminal HTTP exchange result. Expected environmental outcomes do not raise from typed Finish; exceptions are reserved for programming errors and violated provider invariants.

Enumeration literals

Response_Complete: Complete valid response head and body
Pre_Admission_Rejected: Unsupported request configuration rejected before any request handoff
Cancelled: Caller cancellation completed its protocol drain
Timed_Out: Absolute exchange deadline expired
Client_Unavailable: Client is stopped or cannot admit new work
Connection_Failed: Resolution or every address attempt failed
Transport_Failed: Established transport or protocol I/O failed
Request_Source_Failed: Request source violated its contract
Response_Invalid: Response parsing or framing failed
Response_Body_Too_Large: Bounded response destination overflowed
Response_Sink_Failed: Response sink raised while consuming data

Exchange_To_Buffer

function Exchange_To_Buffer
  (Set      : not null access
     Flyology.Operations.Completion_Set'Class;
   Item     : not null access Client;
   Value    : not null access constant Request;
   Destination : in out Flyology.Buffers.Unique_Buffer;
   Deadline : Monotonic_Deadline;
   Token    : access Flyology.Cancellation.Token := null)
   return Exchange_Operation

Composable constructors, reusable initiation, and typed completion for full client exchanges. These overloads use the same provider state machine and semantics as synchronous Execute. Start a retained-body exchange into an acquired writable buffer. Validation and completion-slot reservation precede ownership transfer. A typed Pre_Admission_Rejected result leaves Destination unchanged; any initiating exception restores it before returning.

Parameters

Set: Owner completion set
Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Destination: Acquired writable response buffer moved on start
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain

Return value

Started full-exchange operation

Exchange_To_Buffer

function Exchange_To_Buffer
  (Set      : not null access
     Flyology.Operations.Completion_Set'Class;
   Item     : not null access Client;
   Value    : not null access constant Request;
   Source   : not null access Operation_Request_Body_Source'Class;
   Destination : in out Flyology.Buffers.Unique_Buffer;
   Deadline : Monotonic_Deadline;
   Token    : access Flyology.Cancellation.Token := null)
   return Exchange_Operation

Start a streamed-body exchange into an acquired writable buffer.

Parameters

Set: Owner completion set
Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Source: Request source borrowed through terminal drain
Destination: Acquired writable response buffer moved on start
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain

Return value

Started full-exchange operation

Exchange_To_Buffer

procedure Exchange_To_Buffer
  (Item      : not null access Client;
   Value     : not null access constant Request;
   Destination : in out Flyology.Buffers.Unique_Buffer;
   Deadline  : Monotonic_Deadline;
   Token     : access Flyology.Cancellation.Token := null;
   Operation : in out Exchange_Operation)

Start or restart the retained-body/bounded-response form in an established child suitable for Operations.Continue_After.

Parameters

Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Destination: Acquired writable response buffer moved on start
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain
Operation: Inactive established child to start

Exchange_To_Buffer

procedure Exchange_To_Buffer
  (Item      : not null access Client;
   Value     : not null access constant Request;
   Source    : not null access Operation_Request_Body_Source'Class;
   Destination : in out Flyology.Buffers.Unique_Buffer;
   Deadline  : Monotonic_Deadline;
   Token     : access Flyology.Cancellation.Token := null;
   Operation : in out Exchange_Operation)

Start or restart the streamed-body/bounded-response form.

Parameters

Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Source: Request source borrowed through terminal drain
Destination: Acquired writable response buffer moved on start
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain
Operation: Inactive established child to start

Exchange_To_Sink

function Exchange_To_Sink
  (Set      : not null access
     Flyology.Operations.Completion_Set'Class;
   Item     : not null access Client;
   Value    : not null access constant Request;
   Source   : not null access Operation_Request_Body_Source'Class;
   Sink     : not null access Response_Body_Sink'Class;
   Deadline : Monotonic_Deadline;
   Token    : access Flyology.Cancellation.Token := null)
   return Exchange_Operation

Start a streamed-body exchange whose decoded response is delivered to an immediate sink.

Parameters

Set: Owner completion set
Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Source: Request source borrowed through terminal drain
Sink: Immediate response consumer borrowed through drain
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain

Return value

Started full-exchange operation

Exchange_To_Sink

function Exchange_To_Sink
  (Set      : not null access
     Flyology.Operations.Completion_Set'Class;
   Item     : not null access Client;
   Value    : not null access constant Request;
   Sink     : not null access Response_Body_Sink'Class;
   Deadline : Monotonic_Deadline;
   Token    : access Flyology.Cancellation.Token := null)
   return Exchange_Operation

Start a retained-body exchange whose decoded response is delivered to an immediate sink. Sink effects before failure are not rolled back.

Parameters

Set: Owner completion set
Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Sink: Immediate response consumer borrowed through drain
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain

Return value

Started full-exchange operation

Exchange_To_Sink

procedure Exchange_To_Sink
  (Item      : not null access Client;
   Value     : not null access constant Request;
   Source    : not null access Operation_Request_Body_Source'Class;
   Sink      : not null access Response_Body_Sink'Class;
   Deadline  : Monotonic_Deadline;
   Token     : access Flyology.Cancellation.Token := null;
   Operation : in out Exchange_Operation)

Start or restart the streamed-body/sink form.

Parameters

Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Source: Request source borrowed through terminal drain
Sink: Immediate response consumer borrowed through drain
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain
Operation: Inactive established child to start

Exchange_To_Sink

procedure Exchange_To_Sink
  (Item      : not null access Client;
   Value     : not null access constant Request;
   Sink      : not null access Response_Body_Sink'Class;
   Deadline  : Monotonic_Deadline;
   Token     : access Flyology.Cancellation.Token := null;
   Operation : in out Exchange_Operation)

Start or restart the retained-body/sink form.

Parameters

Item: Configured origin client borrowed through terminal drain
Value: Request metadata borrowed through terminal drain
Sink: Immediate response consumer borrowed through drain
Deadline: Absolute whole-exchange deadline
Token: Optional cancellation token borrowed through drain
Operation: Inactive established child to start

Execute

function Execute
  (Item    : aliased in out Client;
   Value   : Request;
   Source  : in out Request_Body_Source'Class;
   Timeout : Duration := 30.0;
   Token   : access Flyology.Cancellation.Token := null) return Response

Execute one request while pulling its body from Source. The source's Declared_Length controls protocol framing. Source is not retained and is replayed only when it implements Rewindable_Request_Body_Source and the ordinary idempotent stale-transport retry conditions hold. Its exceptions propagate after the leased transport is discarded. HTTP/1.1, HTTP/2, and HTTP/3 all pull Source synchronously with bounded protocol flow-control storage. Request trailers terminate an unknown-length source on every supported protocol. Expect: 100-continue remains HTTP/1.1-only.

Parameters

Item: Shared configured client that outlives the result
Value: Request metadata; a retained body is rejected
Source: Request body producer used only during this call
Timeout: Whole-exchange deadline interval
Token: Optional cancellation source

Return value

Response head with a streaming response body lease

Raised exceptions

Client_Closed

Client is stopping

Connection_Error

Resolution fails, the connect policy refuses every resolved address, all Internet address attempts fail, or a configured Unix socket cannot be connected

Constraint_Error

Request metadata is unsupported or already contains a retained body

Request_Body_Error

Source violates its progress contract or ends before a known length is complete

Protocol_Error

Response framing is malformed or unsupported

Response_Too_Large

Response head exceeds its bound

Redirect_Error

An enabled redirect cannot be followed safely

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket transmission fails

.IO.TLS.TLS_Error TLS setup or transmission fails

.Cancellation.Operation_Cancelled Token is requested

Execute

function Execute
  (Item    : aliased in out Client;
   Value   : Request;
   Timeout : Duration := 30.0;
   Token   : access Flyology.Cancellation.Token := null) return Response

Execute one request. One monotonic Timeout starts before pool admission and covers admission, DNS, all address attempts, TLS, request send, the response head, and later body reads. Negative is unlimited and zero is immediate. Token is borrowed only until the final response head is returned; body reads receive their own optional cancellation token.

Parameters

Item: Shared configured client that outlives the result
Value: Request to execute
Timeout: Whole-exchange deadline interval
Token: Optional cancellation source An idempotent request assigned a reused transport is retried once when that transport fails before any response byte is received. Retained bodies can be replayed directly; streamed bodies are eligible only when Source implements Rewindable_Request_Body_Source. The retry remains inside the original deadline. Non-idempotent requests are never retried. HTTP/2 additionally applies this one-retry budget to streams that the peer explicitly leaves unprocessed with GOAWAY or REFUSED_STREAM.

Return value

Response head with a streaming body lease

Raised exceptions

Client_Closed

Client is stopping

Connection_Error

Resolution fails, the connect policy refuses every resolved address, all Internet address attempts fail, or a configured Unix socket cannot be connected

Constraint_Error

Request fields, target, or method-body combination is unsupported; CONNECT is not implemented

Protocol_Error

Response framing is malformed or unsupported

Response_Too_Large

Response head exceeds its bound

Redirect_Error

An enabled redirect cannot be followed safely

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket transmission fails

.IO.TLS.TLS_Error TLS setup or transmission fails

.Cancellation.Operation_Cancelled Token is requested

Execute

procedure Execute
  (Item    : aliased in out Client;
   Value   : Request;
   Source  : in out Request_Body_Source'Class;
   Result  : in out Response;
   Timeout : Duration := 30.0;
   Token   : access Flyology.Cancellation.Token := null)

Execute a streamed request into a reusable response object. Result is uninitialized and reusable if the new exchange raises. The exceptions are the same as the streamed function overload above.

Parameters

Item: Shared configured client that outlives the result
Value: Request metadata; a retained body is rejected
Source: Request body producer used only during this call
Result: Reusable response destination
Timeout: Whole-exchange deadline interval
Token: Optional cancellation source

Raised exceptions

Client_Closed

Client is stopping

Connection_Error

Resolution or connection setup fails

Constraint_Error

Request metadata is unsupported or already contains a retained body

Request_Body_Error

Source violates its progress contract

Protocol_Error

Response framing is malformed or unsupported

Response_Too_Large

Response head exceeds its bound

Redirect_Error

An enabled redirect cannot be followed safely

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket transmission fails

.IO.TLS.TLS_Error TLS setup or transmission fails

.Cancellation.Operation_Cancelled Token is requested

Execute

procedure Execute
  (Item    : aliased in out Client;
   Value   : Request;
   Result  : in out Response;
   Timeout : Duration := 30.0;
   Token   : access Flyology.Cancellation.Token := null)

Execute one request into a reusable response object. Any previous response in Result is finalized before the new exchange starts. This form avoids successive limited-function return slots in a long-running caller scope. Result is uninitialized and reusable if the new exchange raises. The exceptions are the same as the function overload above.

Parameters

Item: Shared configured client that outlives the result
Value: Request to execute
Result: Reusable response destination
Timeout: Whole-exchange deadline interval
Token: Optional cancellation source

Raised exceptions

Client_Closed

Client is stopping

Connection_Error

Resolution or connection setup fails

Constraint_Error

Request metadata is unsupported

Protocol_Error

Response framing is malformed or unsupported

Response_Too_Large

Response head exceeds its bound

Redirect_Error

An enabled redirect cannot be followed safely

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket transmission fails

.IO.TLS.TLS_Error TLS setup or transmission fails

.Cancellation.Operation_Cancelled Token is requested

Expired

function Expired (Value : Monotonic_Deadline) return Boolean

Report whether a finite deadline is due.

Parameters

Value: Deadline to inspect

Return value

True when the monotonic clock reached Value

Failure_Detail

function Failure_Detail (Item : Exchange_Result) return String

Return bounded sanitized failure detail. It never retains a request target, credentials, signed fields, cookies, or request/body bytes.

Parameters

Item: Result to inspect

Return value

Bounded safe diagnostic category

Finish

procedure Finish
  (Operation : in out Exchange_Operation'Class;
   Result    : out Exchange_Result;
   Reply     : out Response)

Consume a sink exchange. Response_Complete transfers a body-complete, lease-free metadata Response. Other expected outcomes leave Reply uninitialized and are reported in Result without raising.

Parameters

Operation: Terminal sink exchange to consume
Result: Typed terminal result
Reply: Detached complete response metadata on success

Finish

procedure Finish
  (Operation : in out Exchange_Operation'Class;
   Result    : out Exchange_Result;
   Reply     : out Response;
   Destination : in out Flyology.Buffers.Unique_Buffer)

Consume a bounded-buffer exchange. When the operation owns a detached token, Destination must be vacant and from the same pool; this is validated before the terminal result is consumed. Finish always restores that exact token. Only Response_Complete commits received length; every other result restores length zero. A pre-admission rejection that did not move Destination leaves it unchanged.

Parameters

Operation: Terminal bounded exchange to consume
Result: Typed terminal result
Reply: Detached complete response metadata on success
Destination: Vacant same-pool handle for token restoration

Header

function Header
  (Item : Response; Name : String; Occurrence : Positive := 1)
   return String

Return one physical response field occurrence.

Parameters

Item: Response to inspect
Name: Field name
Occurrence: One-based occurrence

Return value

Field value or empty when absent

Raised exceptions

Program_Error: Item is not initialized by Execute

Header_Count

function Header_Count (Item : Response) return Natural

Return the number of physical response fields.

Parameters

Item: Response to inspect

Return value

Field count

Raised exceptions

Program_Error: Item is not initialized by Execute

Header_Count

function Header_Count (Item : Response; Name : String) return Natural

Count physical response fields with a case-insensitive name.

Parameters

Item: Response to inspect
Name: Field name

Return value

Physical occurrence count

Raised exceptions

Program_Error: Item is not initialized by Execute

Header_Name

function Header_Name (Item : Response; Index : Positive) return String

Return one response field name by wire order.

Parameters

Item: Response to inspect
Index: One-based physical field index

Return value

Preserved field name

Raised exceptions

Program_Error: Item is not initialized by Execute
Constraint_Error: Index exceeds Header_Count

Header_Value

function Header_Value (Item : Response; Index : Positive) return String

Return one response field value by wire order.

Parameters

Item: Response to inspect
Index: One-based physical field index

Return value

Preserved field value

Raised exceptions

Program_Error: Item is not initialized by Execute
Constraint_Error: Index exceeds Header_Count

Kind

function Kind (Item : Exchange_Result) return Exchange_Result_Kind

Return the typed terminal result.

Parameters

Item: Result to inspect

Return value

Typed terminal outcome

Known_Length

function Known_Length (Bytes : Body_Size) return Body_Length

Construct a known streaming request body length.

Parameters

Bytes: Exact number of source bytes to transmit

Return value

Known body length

Length_Requirement

type Length_Requirement is record
   Known : Boolean := False;
   Bytes : Body_Size := 0;
end record;

Optional exact response length requirement.

Record fields

Known: Whether Bytes is exact
Bytes: Exact syntactically valid Content-Length when Known

Max_Failure_Detail_Bytes

Max_Failure_Detail_Bytes : constant Positive := 512;

Maximum sanitized diagnostic detail retained by a composable exchange.

Max_Request_Target_Bytes

Max_Request_Target_Bytes : constant Positive := 16 * 1_024;

Maximum request-target bytes retained by a Request. This accommodates long presigned object URLs while keeping request metadata bounded.

Monotonic_Deadline

type Monotonic_Deadline is private;

Absolute monotonic budget shared by a parent operation and one HTTP exchange. Construct it before signing or other parent preparation so those steps and the later HTTP admission, transport, head, body, and drain consume one budget.

Negotiated_Protocol

function Negotiated_Protocol (Item : Response) return Protocol

Return the negotiated protocol.

Parameters

Item: Response to inspect

Return value

HTTP_1_1_Protocol, HTTP_2_Protocol, or HTTP_3_Protocol

Raised exceptions

Program_Error: Item is not initialized by Execute

No_Deadline

No_Deadline : constant Monotonic_Deadline;

Deadline without a time limit.

No_Redirects

No_Redirects : constant Redirect_Configuration := (others => <>);

Default policy: return redirect responses without following them.

Operation_Request_Body_Source

type Operation_Request_Body_Source is limited interface;

Definite set-independent streaming upload capability. It never owns a completion-set slot; the visible HTTP exchange owns the only slot and borrows the source through terminal Finish or cancellation drain.

Phase

function Phase (Item : Exchange_Result) return Exchange_Phase

Return the causal terminal exchange phase. Protocol cleanup does not overwrite this value with Draining; use Raw_Phase to observe an active drain before terminal completion.

Parameters

Item: Result to inspect

Return value

Causal terminal diagnostic phase

Pool_Configuration

type Pool_Configuration is record
   Max_Idle                   : Natural := 1;
   Idle_Timeout               : Duration := 30.0;
   Max_Connection_Age         : Duration := 300.0;
   Max_Requests_Per_Connection : Natural := 0;
end record;

Pool reuse and retention policy. Capacity remains the Client discriminant and bounds open plus connecting slots.

Record fields

Max_Idle: Maximum reusable connections retained, capped by client capacity; zero disables reuse without disabling concurrent requests. Use at least two to keep both TCP and QUIC warm in Negotiate_HTTP_3
Idle_Timeout: Seconds an unused connection may remain reusable; negative disables the age check
Max_Connection_Age: Total reusable lifetime in seconds; negative disables the age check
Max_Requests_Per_Connection: Total requests before rotation; zero disables request-count rotation

Protocol_Mode

type Protocol_Mode is
  (HTTP_1_Only,
   Negotiate_HTTP_2,
   Require_HTTP_2,
   HTTP_2_Prior_Knowledge,
   Negotiate_HTTP_3,
   Require_HTTP_3);

Connection protocol selection. Existing Configure overloads retain HTTP/1.1-only behavior; callers opt into newer protocols with an overload that requires this value. HTTP/3 modes require a pinned DER certificate through an HTTP/3 Configure overload.

Enumeration literals

HTTP_1_Only: Use HTTP/1.1 without offering HTTP/2
Negotiate_HTTP_2: Offer h2 then http/1.1 over TLS
Require_HTTP_2: Require h2 negotiation over TLS
HTTP_2_Prior_Knowledge: Start HTTP/2 directly on cleartext HTTP
Negotiate_HTTP_3: Start with TLS HTTP/2 or HTTP/1.1, learn a same-origin h3 UDP port from Alt-Svc, and prefer HTTP/3 while retaining TCP for concurrent work and fallback
Require_HTTP_3: Use HTTP/3 directly on the HTTPS origin's UDP port

Prune_Idle

procedure Prune_Idle (Item : in out Client)

Close every currently idle connection. Active leases are unaffected.

Parameters

Item: Configured client

Raw_Phase

function Raw_Phase
  (Operation : Exchange_Operation) return Exchange_Phase

Return the current raw driver phase before typed Finish.

Parameters

Operation: Started exchange to inspect

Return value

Current diagnostic phase

Read

procedure Read
  (Item     : in out Request_Body_Source;
   Data     : out Ada.Streams.Stream_Element_Array;
   Last     : out Ada.Streams.Stream_Element_Offset;
   Finished : out Boolean;
   Timeout  : Duration;
   Token    : access Flyology.Cancellation.Token)

Produce the next request body bytes.

Parameters

Item: Source state to advance
Data: Client-owned destination buffer
Last: Last produced byte, or Data'First - 1
Finished: Whether the source has no bytes after this call
Timeout: Remaining whole-exchange deadline interval
Token: Optional cancellation source from Execute

Read_All

function Read_All
  (Item    : in out Response;
   Maximum : Natural := 1_024 * 1_024;
   Token   : access Flyology.Cancellation.Token := null)
   return Flyology.Bytes.Unbounded_Bytes

Read the complete remaining body into owned storage under the original deadline. Maximum bounds decoded bytes retained by this convenience operation.

Parameters

Item: Active response
Maximum: Maximum decoded bytes
Token: Optional cancellation source borrowed for this call

Return value

Complete retained body

Raised exceptions

Program_Error

Item is not initialized by Execute

Response_Too_Large

Maximum would be exceeded

Client_Closed

Client shutdown interrupts the exchange

Protocol_Error

Response body framing is malformed

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket reception fails

.IO.TLS.TLS_Error TLS reception fails

.Cancellation.Operation_Cancelled Token is requested

Read_All

procedure Read_All
  (Item    : in out Response;
   Result  : in out Flyology.Bytes.Unbounded_Bytes;
   Maximum : Natural := 1_024 * 1_024;
   Token   : access Flyology.Cancellation.Token := null)

Read the complete remaining body into reusable owned storage. Result is cleared before reading and is empty if the operation raises. This form avoids successive function-result temporaries in a long-running caller scope.

Parameters

Item: Active response
Result: Reusable owned body destination
Maximum: Maximum decoded bytes
Token: Optional cancellation source borrowed for this call

Raised exceptions

Program_Error

Item is not initialized by Execute

Response_Too_Large

Maximum would be exceeded

Client_Closed

Client shutdown interrupts the exchange

Protocol_Error

Response body framing is malformed

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket reception fails

.IO.TLS.TLS_Error TLS reception fails

.Cancellation.Operation_Cancelled Token is requested

Read_Body

procedure Read_Body
  (Item     : in out Response;
   Data     : out Ada.Streams.Stream_Element_Array;
   Last     : out Ada.Streams.Stream_Element_Offset;
   Finished : out Boolean;
   Token    : access Flyology.Cancellation.Token := null)

Stream decoded response representation bytes. Fixed-length and chunked framing are removed. Last is Data'First - 1 when no bytes are produced. Finished becomes true only after complete framing; that transition releases the underlying HTTP/1.1 or HTTP/3 connection or HTTP/2 stream. The Execute deadline and token remain authoritative and are never restarted.

Parameters

Item: Active response
Data: Caller-owned destination
Last: Last decoded byte, or Data'First - 1
Finished: Whether response framing is complete
Token: Optional cancellation source borrowed for this call

Raised exceptions

Program_Error

Item is not initialized by Execute

Client_Closed

Client shutdown interrupts the exchange

Protocol_Error

Response body framing is malformed

Flyology

.IO.Timeout_Error Whole-exchange deadline expires

.IO.Device_Error Established transport I/O fails

.IO.Sockets.Socket_Error Socket reception fails

.IO.TLS.TLS_Error TLS reception fails

.Cancellation.Operation_Cancelled Token is requested

Read_Now

procedure Read_Now
  (Item   : in out Operation_Request_Body_Source;
   Data   : out Ada.Streams.Stream_Element_Array;
   Last   : out Ada.Streams.Stream_Element_Offset;
   Result : out Source_Step_Kind)

Perform one nonblocking bounded source step. Source_Progress must return a nonempty slice. Every other result returns Last = Data'First - 1. Cumulative progress must equal a known Declared_Length exactly.

Parameters

Item: Source to advance
Data: Caller storage for one produced slice
Last: Last produced element or Data'First minus one
Result: Immediate source result

Reason_Phrase

function Reason_Phrase (Item : Response) return String

Return the final response reason phrase. HTTP/2 and later protocols may return an empty string because they do not carry one.

Parameters

Item: Response to inspect

Return value

Preserved HTTP/1.x reason phrase after its status separator

Raised exceptions

Program_Error: Item is not initialized by Execute

Redirect_Configuration

type Redirect_Configuration is record
   Mode          : Redirect_Mode := Return_Redirects;
   Maximum_Hops  : Redirect_Limit := 5;
end record;

Per-request redirect policy.

Record fields

Mode: Whether redirects are returned or followed within the origin
Maximum_Hops: Maximum redirects followed before Redirect_Error

Redirect_Error

Redirect_Error : exception;

Raised when an enabled redirect cannot be followed safely because its target is invalid, repeats a prior target, exceeds the configured hop limit, or requires replaying a one-shot request source.

Redirect_Limit

subtype Redirect_Limit is Natural range 0 .. 20;

Supported bound for automatically followed redirect hops.

Redirect_Mode

type Redirect_Mode is (Return_Redirects, Follow_Same_Origin);

Automatic redirect behavior. Returning redirects is the default and preserves the response exactly as received. Same-origin following never sends a request to a different scheme, host, or port.

Enumeration literals

Return_Redirects: Return every redirect response to the caller
Follow_Same_Origin: Follow eligible redirects within the client origin

Release_Source

procedure Release_Source
  (Item : in out Operation_Request_Body_Source)

Idempotently release every source borrow. The client calls this exactly once after each successful source attachment and before terminal publication on every path.

Parameters

Item: Source whose borrow is released

Request

type Request is private;

Mutable request value. Bodies are retained as owned bytes so request transmission remains valid across task suspension.

Request_Body_Error

Request_Body_Error : exception;

Raised when a streaming request body violates the progress contract or does not finish on exactly its positive declared length.

Request_Body_Source

type Request_Body_Source is limited interface;

Pull source for a streaming request body. Execute queries Declared_Length once, calls Read serially, and never retains the source after returning. The declared length must remain stable during Execute. Implementations must honor the remaining whole-exchange timeout and cancellation token when they perform blocking work. A call must either produce at least one byte or set Finished. Last is Data'First - 1 when no bytes are produced.

Required_Body_Length

function Required_Body_Length
  (Item : Exchange_Result) return Length_Requirement

Return an exact required body length when a trusted Content-Length was available before a bounded destination overflowed.

Parameters

Item: Result to inspect

Return value

Exact or unknown response body length requirement

Response

type Response is limited private;

Limited response owning one exchange lease until its body is consumed. Reading the complete body returns an HTTP/1.1 or HTTP/3 transport lease or an HTTP/2 stream lease to the pool. Finalizing an incomplete HTTP/1.1 or HTTP/3 response closes its transport; finalizing an incomplete HTTP/2 response resets only its stream when the multiplexed transport remains usable.

Response_Body_Sink

type Response_Body_Sink is limited interface;

Immediate response-body consumer. Write receives nonempty bounded slices on the completion-set owner's stack. It must not block or retain Data. Bytes delivered before a later exchange failure are not rolled back.

Response_Too_Large

Response_Too_Large : exception;

Raised when retained response metadata or a Read_All body exceeds its bound.

Rewind

procedure Rewind
  (Item : in out Rewindable_Request_Body_Source)

Restore a rewindable source to its initial byte before one safe retry.

Parameters

Item: Source whose exact initial sequence is restored

Rewindable_Request_Body_Source

type Rewindable_Request_Body_Source is
  limited interface and Request_Body_Source;

Request source that can reproduce exactly the same byte sequence after a failed transport attempt. Rewind must be nonblocking and restore the initial cursor without changing Declared_Length. Execute calls it only after discarding a failed reused transport and only when the method is idempotent and no response byte was received.

Set_Body

procedure Set_Body
  (Item : in out Request; Value : Ada.Streams.Stream_Element_Array)

Replace the request body from contiguous bytes.

Parameters

Item: Request to change
Value: Request representation bytes

Set_Body

procedure Set_Body (Item : in out Request; Value : String)

Replace the request body using a one-to-one byte mapping.

Parameters

Item: Request to change
Value: Request representation bytes

Set_Expect_Continue

procedure Set_Expect_Continue
  (Item         : in out Request;
   Enabled      : Boolean := True;
   Wait_Timeout : Duration := 1.0)

Enable or disable the Expect: 100-continue handshake. When enabled for a nonempty retained or streaming body, Execute sends the request head first and waits up to Wait_Timeout for 100 Continue or a final response. A positive wait expiry with no partial response sends the body; a negative value waits within the whole exchange deadline and zero sends immediately after the head. A final response suppresses body reads and transmission. A 417 final response received before body transmission is retried once on a fresh transport without the expectation, within the same deadline and shared automatic-retry budget. The whole exchange deadline is never extended. The current HTTP/2 and HTTP/3 engines reject this opt-in handshake; use it with an HTTP_1_Only client.

Parameters

Item: Request to change
Enabled: Whether to generate Expect: 100-continue
Wait_Timeout: Maximum continue-specific wait in seconds

Set_Method

procedure Set_Method (Item : in out Request; Value : Method)

Replace the request method.

Parameters

Item: Request to change
Value: Validated method

Set_Redirects

procedure Set_Redirects
  (Item : in out Request; Value : Redirect_Configuration)

Replace the request's automatic redirect policy. One monotonic Execute deadline covers every hop and every intermediate response-body drain. Cross-origin redirects are always returned to the caller.

Parameters

Item: Request to change
Value: Redirect mode and hop bound

Set_Target

procedure Set_Target (Item : in out Request; Value : String)

Replace the origin-form request target. Asterisk-form is retained for OPTIONS and validated when Execute observes the complete Request. Absolute-form, authority-form, fragments, non-ASCII bytes, spaces, control characters, and targets over 16 KiB are rejected.

Parameters

Item: Request to change
Value: Origin-form target

Raised exceptions

Constraint_Error: Value is not a supported request target

Shutdown

procedure Shutdown (Item : in out Client; Timeout : Duration := 5.0)

Terminally reject admission, cancel admitted transport operations, close idle connections, and wait up to Timeout for leases and connecting slots to drain. A timeout leaves Item stopping and may be retried.

Parameters

Item: Client to stop
Timeout: Drain deadline interval; negative waits indefinitely

Raised exceptions

Flyology: .IO.Timeout_Error Active leases do not drain

Source_Step_Kind

type Source_Step_Kind is
  (Source_Progress,
   Source_Finished,
   Source_Needs_Read,
   Source_Needs_Write);

Result of one immediate request-source step.

Enumeration literals

Source_Progress: Data contains a nonempty produced slice
Source_Finished: Source reached its declared end
Source_Needs_Read: Source requires readable readiness
Source_Needs_Write: Source requires writable readiness

Source_Wait_Kind

subtype Source_Wait_Kind is Source_Step_Kind range
  Source_Needs_Read .. Source_Needs_Write;

Source wait results accepted by Source_Wait_Source.

Source_Wait_Source

procedure Source_Wait_Source
  (Item        : in out Operation_Request_Body_Source;
   Required    : Source_Wait_Kind;
   Descriptor  : out Flyology.IO.Descriptor;
   Ready_Now   : out Boolean)

Query the level-triggered or latched readiness source required after Read_Now requests a wait. This is one bounded nonblocking step and does not consume an unreported readiness transition. When Ready_Now is False, Descriptor is valid and a transition after this call remains observable through Descriptor until the next Read_Now. When Ready_Now is True, Descriptor is ignored. The client combines a returned descriptor with transport, outbound, shutdown, and cancellation readiness so an early final response cannot be hidden by a blocked upload source. It disarms that combined wait before the next Read_Now or Release_Source.

Parameters

Item: Source whose readiness is queried
Required: Read or write readiness requested by Read_Now
Descriptor: Latched readiness descriptor when Ready_Now is false
Ready_Now: Whether the source can be polled again immediately

Status

function Status (Item : Response) return Status_Code

Return the final response status.

Parameters

Item: Response to inspect

Return value

Three-digit status

Raised exceptions

Program_Error: Item is not initialized by Execute

Trailer

function Trailer
  (Item : Response; Name : String; Occurrence : Positive := 1)
   return String

Return one completed chunked trailer occurrence.

Parameters

Item: Response whose body has completed
Name: Trailer name
Occurrence: One-based occurrence

Return value

Trailer value or empty when absent

Raised exceptions

Program_Error: Item is uninitialized or its body is incomplete

Trailer_Count

function Trailer_Count (Item : Response) return Natural

Return the number of physical trailer fields available after body completion.

Parameters

Item: Response to inspect

Return value

Trailer field count

Raised exceptions

Program_Error: Item is uninitialized or its body is incomplete

Trailer_Count

function Trailer_Count (Item : Response; Name : String) return Natural

Count completed chunked trailer fields with a case-insensitive name.

Parameters

Item: Response whose body has completed
Name: Trailer name

Return value

Physical occurrence count

Raised exceptions

Program_Error: Item is uninitialized or its body is incomplete

Trailer_Name

function Trailer_Name (Item : Response; Index : Positive) return String

Return one trailer field name by wire order.

Parameters

Item: Response to inspect
Index: One-based physical field index

Return value

Preserved trailer name

Raised exceptions

Program_Error: Item is uninitialized or its body is incomplete
Constraint_Error: Index exceeds Trailer_Count

Trailer_Value

function Trailer_Value (Item : Response; Index : Positive) return String

Return one trailer field value by wire order.

Parameters

Item: Response to inspect
Index: One-based physical field index

Return value

Preserved trailer value

Raised exceptions

Program_Error: Item is uninitialized or its body is incomplete
Constraint_Error: Index exceeds Trailer_Count

Unix_Socket

function Unix_Socket (Path : String) return Unix_Socket_Transport

Construct a pathname Unix-domain stream transport. Path is operating- system configuration, not an HTTP request target. It must be nonempty, contain no NUL byte, and fit the host sockaddr_un pathname capacity.

Parameters

Path: Filesystem pathname of the Unix-domain socket

Return value

Validated transport configuration

Raised exceptions

Constraint_Error: Path is empty, contains NUL, or is too long

Unix_Socket_Transport

type Unix_Socket_Transport is private;

Explicit Unix-domain stream transport configuration for macOS and Linux. The HTTP origin remains independent and supplies the request authority; this value selects only the local socket used to carry exchanges. The client retains an owned copy of the pathname when configured. It never creates, removes, changes permissions on, or assumes ownership of the filesystem entry. Filesystem permissions control connection admission but do not by themselves authenticate the peer; applications remain responsible for the local security boundary.

Unknown_Length

Unknown_Length : constant Body_Length;

Unknown streaming request body length.

Write

procedure Write
  (Item : in out Response_Body_Sink;
   Data : Ada.Streams.Stream_Element_Array)

Consume one complete nonempty decoded response slice.

Parameters

Item: Sink state to update
Data: Ephemeral decoded response bytes