Flyology HTTP API reference

Description

HTTP/3 session framing over an Ada-native QUIC connection.

The caller owns UDP I/O and the QUIC connection. This package owns HTTP/3 control streams, SETTINGS, request and response sequencing, and the static-table QPACK profile. Every operation is synchronous and returns packets for the caller to send through Flyology.QUIC.Connections.IO.

Append

procedure Append (Item : in out Header_Block; Value : Header_Field)

Append one field to a field section.

Parameters

Item: Field section to update
Value: Field appended at the end

Application_Error_Code

subtype Application_Error_Code is QUIC.Stream_Offset;

HTTP/3 application error carried when an operation aborts a QUIC stream.

Cancel_Request

procedure Cancel_Request
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Stream    : QUIC.Stream_ID;
   Reason    : Request_Cancellation_Reason := Cancel_Processing;
   Now       : QUIC.Timestamp;
   Packet    : out QUIC.Datagram;
   Status    : out Operation_Status)

Abruptly terminate both directions of a request stream. Clients use Cancel_Processing; clients use Malformed_Message after a stream-local response validation failure. Servers may select either processing reason based on whether request processing began.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC connection
Stream: Request stream identifier
Reason: Retry-safe rejection or cancellation after processing
Now: Monotonic microsecond timestamp
Packet: Datagram to send when Status is Succeeded
Status: Operation outcome

Clear

procedure Clear (Item : in out Header_Block)

Remove every field while retaining the block's bounded storage.

Parameters

Item: Field section to reuse

Endpoint_Role

type Endpoint_Role is (Client, Server);

HTTP/3 endpoint behavior.

Enumeration literals

Client: Opens request streams and receives responses
Server: Receives request streams and sends responses

Event

type Event is record
   Kind        : Event_Kind := No_Event;
   Stream      : QUIC.Stream_ID := 0;
   Identifier  : QUIC.Stream_Offset := 0;
   Headers     : Header_Block;
   Data        : Ada.Streams.Stream_Element_Array (1 .. Max_Event_Data) :=
     (others => 0);
   Data_Length : Event_Data_Length := 0;
   Application_Error : Application_Error_Code := 0;
end record;

One decoded HTTP/3 application event.

Record fields

Kind: Event classification
Stream: QUIC stream carrying the event
Identifier: GOAWAY stream or push identifier
Headers: Decoded field section for a HEADERS event
Data: Bounded payload storage for a DATA event
Data_Length: Number of meaningful octets in Data
Application_Error: Peer error code for a Stream_Reset event

Event_Data_Length

subtype Event_Data_Length is Natural range 0 .. Max_Event_Data;

Length of the DATA payload retained by an event.

Event_Kind

type Event_Kind is
  (No_Event,
   Settings_Received,
   Goaway_Received,
   Headers_Received,
   Data_Received,
   Stream_Reset,
   Stream_Ended);

Kind of complete HTTP/3 input returned by Poll.

Enumeration literals

No_Event: No complete input is available
Settings_Received: Peer SETTINGS were accepted
Goaway_Received: Peer initiated graceful shutdown
Headers_Received: A HEADERS field section was decoded
Data_Received: A DATA frame payload was decoded
Stream_Reset: The peer abruptly terminated a request stream
Stream_Ended: A complete request or response reached stream FIN

Field_At

function Field_At
  (Item : Header_Block; Index : Positive) return Header_Field

Return a field by one-based position.

Parameters

Item: Field section to inspect
Index: One-based field position

Return value

Selected field

Field_Name

function Field_Name (Item : Header_Field) return String

Return a field name.

Parameters

Item: Field to inspect

Return value

Exact field name

Field_Value

function Field_Value (Item : Header_Field) return String

Return a field value.

Parameters

Item: Field to inspect

Return value

Exact field value

H3_Message_Error

H3_Message_Error : constant Application_Error_Code := 16#10E#;

One request or response message violated HTTP/3 field or sequencing semantics without invalidating the connection.

H3_Request_Cancelled

H3_Request_Cancelled : constant Application_Error_Code := 16#10C#;

Request or response processing was cancelled after it could begin.

H3_Request_Rejected

H3_Request_Rejected : constant Application_Error_Code := 16#10B#;

A server did not process the request and permits transparent retry.

Has_Peer_Goaway

function Has_Peer_Goaway (Item : Session) return Boolean

Report whether the peer initiated graceful shutdown.

Parameters

Item: Session to inspect

Return value

True after a Goaway_Received event

Has_Peer_Settings

function Has_Peer_Settings (Item : Session) return Boolean

Report whether the peer's mandatory SETTINGS frame was accepted.

Parameters

Item: Session to inspect

Return value

True after a Settings_Received event

Header_Block

type Header_Block is private;

Bounded ordered HTTP field section.

Header_Count

function Header_Count (Item : Header_Block) return Natural

Return the number of fields in a field section.

Parameters

Item: Field section to inspect

Return value

Number of retained fields

Header_Field

type Header_Field is private;

One HTTP field with bounded name and value storage.

Initialize

procedure Initialize
  (Item           : in out Session;
   Role           : Endpoint_Role;
   Local_Settings : Settings := (others => <>))

Configure a fresh HTTP/3 session.

Parameters

Item: Fresh session
Role: Client or server behavior
Local_Settings: SETTINGS sent to the peer

Is_Initialized

function Is_Initialized (Item : Session) return Boolean

Report whether an endpoint role and local settings were installed.

Parameters

Item: Session to inspect

Return value

True after Initialize succeeds

Make_Field

function Make_Field (Name, Value : String) return Header_Field

Construct one field while preserving its wire spelling.

Parameters

Name: Lowercase field name or a recognized pseudo-field
Value: Field value

Return value

Bounded field value

Max_Event_Data

Max_Event_Data : constant := 65_535;

Largest DATA payload surfaced by one event.

Max_Fields

Max_Fields : constant := 32;

Largest number of fields retained in one field section.

Max_Name_Length

Max_Name_Length : constant := 256;

Largest field name retained by the bounded QPACK profile.

Max_Prepared_Responses

Max_Prepared_Responses : constant Positive := 8;

Maximum complete responses combined into one QUIC packet.

Max_Value_Length

Max_Value_Length : constant := 16 * 1_024;

Largest field value retained by the bounded QPACK profile. Bounded field-value size, including long :path values used by presigned object requests.

Open_Request

procedure Open_Request
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Stream    : out QUIC.Stream_ID;
   Status    : out Operation_Status)

Allocate a client-initiated bidirectional request stream.

Parameters

Item: Initialized client session
Transport: Connected QUIC connection
Stream: Allocated stream identifier on success
Status: Operation outcome

Operation_Status

type Operation_Status is
  (Succeeded,
   No_Event,
   Uninitialized,
   Not_Connected,
   Not_Started,
   Already_Started,
   Connection_Draining,
   Wrong_Role,
   …,
   Header_Error);

Outcome of one HTTP/3 session operation.

Enumeration literals

Succeeded: Operation completed and any packet is ready
No_Event: No complete application event is currently buffered
Uninitialized: Initialize has not been called
Not_Connected: QUIC application keys are not active
Not_Started: The local HTTP/3 control stream does not exist
Already_Started: The local control stream already exists
Connection_Draining: The peer sent GOAWAY
Wrong_Role: The operation is not valid for this endpoint role
Stream_Limit_Reached: The peer permits no additional stream
Transport_Blocked: QUIC flow or congestion credit is unavailable
Transport_Error: QUIC could not encode the requested stream data
Frame_Too_Large: The frame exceeds bounded packet storage
Stream_Capacity_Exceeded: HTTP/3 stream storage is exhausted
Stream_Creation_Error: The stream role or identifier is invalid
Closed_Critical_Stream: A mandatory peer stream ended
Missing_Settings: Peer control stream did not begin with SETTINGS
Frame_Unexpected: The frame is forbidden in its current context
Settings_Error: Peer SETTINGS are malformed
Frame_Error: A frame is malformed or unsupported
ID_Error: A stream or push identifier violates HTTP/3 rules
QPACK_Decompression_Failed: A field section cannot be decoded
QPACK_Encoder_Stream_Error: An encoder instruction is invalid
QPACK_Decoder_Stream_Error: A decoder instruction is invalid
Peer_Field_Section_Too_Large: Fields exceed the peer's advertised maximum field-section size
Message_Error: HTTP message sequencing is invalid
Header_Error: HTTP field semantics are invalid

Peer_Goaway_ID

function Peer_Goaway_ID (Item : Session) return QUIC.Stream_Offset

Return the lowest GOAWAY identifier received from the peer.

Parameters

Item: Session whose peer GOAWAY was accepted

Return value

First request or push the peer will not accept

Peer_Settings

function Peer_Settings (Item : Session) return Settings

Return the SETTINGS advertised by the peer.

Parameters

Item: Session whose peer SETTINGS were accepted

Return value

Peer settings used for subsequent sends

Poll

procedure Poll
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Output    : out Event;
   Status    : out Operation_Status)

Decode at most one complete event from QUIC stream buffers.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC connection
Output: Decoded event when Status is Succeeded
Status: Operation outcome

Prepare_Response

procedure Prepare_Response
  (Item      : in out Session;
   Transport : QUIC.Connection;
   Stream    : QUIC.Stream_ID;
   Headers   : Header_Block;
   Data      : Ada.Streams.Stream_Element_Array;
   Output    : out Prepared_Response;
   Status    : out Operation_Status)

Validate and encode a complete response without consuming QUIC packet or congestion credit. The bounded result can later be committed alone or with other streams by Send_Prepared_Responses.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC transport used for validation
Stream: Request stream receiving the response
Headers: Response header fields
Data: Complete response body
Output: Prepared response when Status is Success
Status: Preparation outcome

Prepared_Response

type Prepared_Response is private;

One validated and encoded complete response awaiting transport commit.

Prepared_Response_Array

type Prepared_Response_Array is
  array (Positive range <>) of Prepared_Response;

Bounded collection of complete responses awaiting one transport commit.

Release_Request

procedure Release_Request
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Stream    : QUIC.Stream_ID;
   Status    : out Operation_Status)

Release a completed server request after its response has been sent. High-level servers do this automatically; low-level server drivers call it after Poll reports Stream_Ended and response construction completes.

Parameters

Item: Initialized server session
Transport: Connected QUIC connection
Stream: Completed request stream identifier
Status: Operation outcome

Request_Cancellation_Reason

type Request_Cancellation_Reason is
  (Reject_Unprocessed, Cancel_Processing, Malformed_Message);

Reason for abruptly terminating both directions of a request stream.

Enumeration literals

Reject_Unprocessed: Server did not process the request and permits transparent retry
Cancel_Processing: Request or response processing could have begun
Malformed_Message: Peer response fields or sequencing were invalid

Send_Data

procedure Send_Data
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Stream    : QUIC.Stream_ID;
   Data      : Ada.Streams.Stream_Element_Array;
   Fin       : Boolean;
   Now       : QUIC.Timestamp;
   Packet    : out QUIC.Datagram;
   Status    : out Operation_Status)

Encode and protect one DATA frame.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC connection
Stream: Request stream identifier
Data: Frame payload
Fin: Whether this closes the sending direction
Now: Monotonic microsecond timestamp
Packet: Datagram to send when Status is Succeeded
Status: Operation outcome

Send_Goaway

procedure Send_Goaway
  (Item       : in out Session;
   Transport  : in out QUIC.Connection;
   Identifier : QUIC.Stream_Offset;
   Now        : QUIC.Timestamp;
   Packet     : out QUIC.Datagram;
   Status     : out Operation_Status)

Send GOAWAY on the local control stream. Servers provide a client- initiated bidirectional stream ID; clients provide a push ID. Repeated identifiers may stay equal or decrease.

Parameters

Item: Initialized and started HTTP/3 session
Transport: Connected QUIC connection
Identifier: First request or push that will not be accepted
Now: Monotonic microsecond timestamp
Packet: Datagram to send when Status is Succeeded
Status: Operation outcome

Send_Headers

procedure Send_Headers
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Stream    : QUIC.Stream_ID;
   Headers   : Header_Block;
   Fin       : Boolean;
   Now       : QUIC.Timestamp;
   Packet    : out QUIC.Datagram;
   Status    : out Operation_Status)

Encode and protect a request, response, or trailer HEADERS frame.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC connection
Stream: Request stream identifier
Headers: Field section to encode
Fin: Whether this closes the sending direction
Now: Monotonic microsecond timestamp
Packet: Datagram to send when Status is Succeeded
Status: Operation outcome

Send_Prepared_Responses

procedure Send_Prepared_Responses
  (Item         : in out Session;
   Transport    : in out QUIC.Connection;
   Responses    : in out Prepared_Response_Array;
   Now          : QUIC.Timestamp;
   Packet       : out QUIC.Datagram;
   Status       : out Operation_Status;
   ACK_Included : out Boolean)

Commit one or more prepared responses in a single protected QUIC packet. Frame_Too_Large leaves every response uncommitted so callers can retry smaller groups or use Send_Response.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC transport to update transactionally
Responses: Prepared responses to commit
Now: Monotonic microsecond timestamp for recovery accounting
Packet: Datagram to transmit when Status is Success
Status: Commit outcome
ACK_Included: Whether the datagram carries an ACK frame

Send_Response

procedure Send_Response
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Stream    : QUIC.Stream_ID;
   Headers   : Header_Block;
   Data      : Ada.Streams.Stream_Element_Array;
   Now       : QUIC.Timestamp;
   Packet    : out QUIC.Datagram;
   Status    : out Operation_Status;
   ACK_Included : out Boolean)

Encode final response HEADERS and DATA into one QUIC STREAM packet. Frame_Too_Large leaves the response unsent so callers can fall back to separate packets.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC connection
Stream: Peer request stream identifier
Headers: Final response field section
Data: Complete response body
Now: Monotonic microsecond timestamp
Packet: Datagram to send when Status is Succeeded
Status: Operation outcome
ACK_Included: Whether the datagram also carries a QUIC ACK

Session

type Session is limited private;

Owning, noncopyable HTTP/3 session state.

Settings

type Settings is record
   Has_Max_Field_Size : Boolean := False;
   Max_Field_Size     : QUIC.Stream_Offset := 0;
end record;

Local HTTP/3 SETTINGS sent on the mandatory control stream. The current profile keeps QPACK dynamic-table capacity and blocked streams at zero.

Record fields

Has_Max_Field_Size: Whether Max_Field_Size is advertised
Max_Field_Size: Maximum accepted field-section size

Start

procedure Start
  (Item      : in out Session;
   Transport : in out QUIC.Connection;
   Now       : QUIC.Timestamp;
   Packet    : out QUIC.Datagram;
   Status    : out Operation_Status)

Create the mandatory local control stream and SETTINGS frame.

Parameters

Item: Initialized HTTP/3 session
Transport: Connected QUIC connection
Now: Monotonic microsecond timestamp
Packet: Datagram to send when Status is Succeeded
Status: Operation outcome