Description
Supplies a request-scoped application exchange above the raw HTTP engine. Exchange borrows its request, connection, application context, and optional cancellation token. It must not escape the handler call that created it.
Accept_WebSocket
procedure Accept_WebSocket
(Item : in out Exchange;
Protocol : String := "";
Origin_Policy : WebSocket_Origin_Policy := Reject_Browser_Origins;
Allowed_Origin : String := "";
Compression : WebSocket_Compression_Mode :=
No_WebSocket_Compression)
Upgrade through the raw WebSocket engine while retaining Exchange response observation. The calling handler remains the sole writer.
Parameters
- Item
Request exchange
- Protocol
Optional selected subprotocol
- Origin_Policy
Browser-origin policy
- Allowed_Origin
Exact origin for Require_Exact_Origin
- Compression
Explicit RFC 7692 negotiation policy
Add_Header
procedure Add_Header
(Item : in out Exchange;
Name : String;
Value : String)
Add one response header for the next high-level fixed response. Header names and values are validated immediately against injection.
Parameters
- Item
Request exchange
- Name
Header field name
- Value
Header field value
Add_Parameter
procedure Add_Parameter
(Item : in out Exchange;
Name : String;
Value : String)
Append one decoded route parameter. Duplicate names or capacity excess raise Program_Error. Intended for Flyology router packages.
Parameters
- Item
Request exchange
- Name
Parameter name
- Value
Decoded parameter value
Apply_Body_Policy
procedure Apply_Body_Policy
(Item : in out Exchange;
Accepted : out Boolean)
Apply the configured route body policy after request-head middleware accepts the request. This is the only application-layer operation that may emit delayed 100 Continue. Rejection sends a final response and returns Accepted false.
Parameters
- Item
Request exchange
- Accepted
True when downstream application work may run
Authentication
function Authentication (Item : Exchange) return Authentication_Mode
Return the selected route authentication requirement.
Parameters
- Item
Request exchange
Return value
Route authentication mode
Authentication_Mode
type Authentication_Mode is
(No_Authentication, Optional_Authentication, Required_Authentication);
Route authentication requirement interpreted by optional middleware.
Enumeration literals
- No_Authentication
Route does not request authentication
- Optional_Authentication
Install a principal when credentials exist
- Required_Authentication
Reject unauthenticated requests
Begin_SSE
procedure Begin_SSE (Item : in out Exchange)
Start a server-sent event response through the raw SSE engine while retaining Exchange response observation.
Parameters
- Item
Request exchange
Begin_Stream
procedure Begin_Stream
(Item : in out Exchange;
Status : Positive;
Content_Type : String;
Close : Boolean := False)
Start an optional high-level streaming response. The active handler remains its sole writer; child tasks must communicate through a bounded mailbox rather than retaining Item or its connection.
Parameters
- Item
Request exchange
- Status
HTTP status
- Content_Type
Media type, or empty to omit
- Close
Force connection close after the stream
Body_Complete
function Body_Complete (Item : Exchange) return Boolean
Report whether the decoded body and trailers are fully consumed.
Parameters
- Item
Request exchange
Return value
True when body processing is complete
Body_Policy
function Body_Policy (Item : Exchange) return Request_Body_Policy
Return the route-selected body policy.
Parameters
- Item
Request exchange
Return value
Current body policy
Body_State
function Body_State (Item : Exchange) return Request_Body_State
Return the current body lifecycle without forcing body consumption.
Parameters
- Item
Request exchange
Return value
Current body state
Cancellation
function Cancellation
(Item : Exchange) return access Flyology.Cancellation.Token
Borrow the request cancellation token, or null when none was supplied.
Parameters
- Item
Request exchange
Return value
Borrowed cancellation token
Close_WebSocket
procedure Close_WebSocket
(Item : in out Exchange;
Code : Positive := 1_000;
Reason : String := "")
Complete an upgraded WebSocket with a normal close frame.
Parameters
- Item
Upgraded request exchange
- Code
RFC 6455 close status
- Reason
Optional UTF-8 close reason
Complete_WebSocket
procedure Complete_WebSocket (Item : in out Exchange)
Record a peer-initiated WebSocket close already completed by the raw protocol engine. Intended for lifecycle adapters.
Parameters
- Item
Upgraded request exchange
Concurrency_Limit
function Concurrency_Limit (Item : Exchange) return Natural
Return the route concurrency limit; zero means unlimited.
Parameters
- Item
Request exchange
Return value
Route concurrency bound
Configure_Route
procedure Configure_Route
(Item : in out Exchange;
Name : String;
Normalized_Path : String;
Policy : Request_Body_Policy;
Authentication : Authentication_Mode;
CORS_Policy : Natural;
Concurrency : Natural;
Rate_Per_Second : Natural;
Upgrade : Upgrade_Mode)
Configure routing metadata before invoking application components. This integration operation is intended for Flyology router packages.
Parameters
- Item
Request exchange
- Name
Stable route name
- Normalized_Path
Decoded path used for matching
- Policy
Route body policy
- Authentication
Route authentication requirement
- CORS_Policy
Bounded CORS registry slot
- Concurrency
Route concurrency limit
- Rate_Per_Second
Route per-client request rate
- Upgrade
Permitted application protocol lifecycle
Content
function Content (Item : Exchange) return String
Return buffered request content.
Parameters
- Item
Request exchange
Return value
Buffered decoded body
CORS_Policy
function CORS_Policy (Item : Exchange) return Natural
Return the selected bounded CORS policy registry slot.
Parameters
- Item
Request exchange
Return value
CORS policy slot or zero
Create
function Create
(Value : aliased in out Request;
Item : aliased in out Connection;
Peer : Flyology.IO.Sockets.Endpoint;
Token : access Flyology.Cancellation.Token;
Deadline : Ada.Real_Time.Time) return Exchange
Construct one exchange around values owned by the active handler. Access discriminants let Ada reject an exchange whose request, connection, or token would not outlive it.
Parameters
- Value
Parsed request owned by the handler
- Item
Sole-writer HTTP connection owned by the handler
- Peer
Connected peer address
- Token
Optional borrowed cancellation token
- Deadline
Absolute monotonic request deadline
Return value
Request-scoped exchange
Deadline
function Deadline (Item : Exchange) return Ada.Real_Time.Time
Return the current absolute deadline.
Parameters
- Item
Request exchange
Return value
Original or narrowed monotonic deadline
End_SSE
procedure End_SSE (Item : in out Exchange)
Complete an active SSE response.
Parameters
- Item
Request exchange
End_Stream
procedure End_Stream (Item : in out Exchange)
Complete an active streaming response.
Parameters
- Item
Exchange with an active streaming response
Exchange
type Exchange (<>) is tagged limited private;
Borrowed request scope. The object is tagged for Ada prefixed calls such as X.Text, but concrete helpers do not require dynamic dispatch.
Has_Parameter
function Has_Parameter (Item : Exchange; Name : String) return Boolean
Report whether a named route parameter is present, distinguishing an absent value from a present empty remainder.
Parameters
- Item
Request exchange
- Name
Parameter name
Return value
True when the route installed Name
Has_Principal
function Has_Principal (Item : Exchange) return Boolean
Report whether authentication middleware installed a principal.
Parameters
- Item
Request exchange
Return value
True when a principal is present
JSON
procedure JSON
(Item : in out Exchange;
Status : Positive;
Serialized : String)
Send a caller-serialized JSON response without choosing a JSON library.
Parameters
- Item
Request exchange
- Status
HTTP status
- Serialized
Complete JSON representation
Mark_Failed
procedure Mark_Failed (Item : in out Exchange)
Mark response framing unsafe and require connection close. Error middleware uses this after a failure once response bytes may exist.
Parameters
- Item
Request exchange
Max_Path_Parameters
Max_Path_Parameters : constant := 16;
Maximum named parameters installed by one matched route.
Narrow_Deadline
procedure Narrow_Deadline
(Item : in out Exchange;
Value : Ada.Real_Time.Time)
Shorten the request deadline. Extending it raises Program_Error.
Parameters
- Item
Request exchange
- Value
Earlier absolute monotonic deadline
No_Content
procedure No_Content (Item : in out Exchange)
Send a 204 response.
Parameters
- Item
Request exchange
Parameter
function Parameter (Item : Exchange; Name : String) return String
Return a decoded named route parameter. Names are case-sensitive.
Parameters
- Item
Request exchange
- Name
Parameter name
Return value
Parameter value, or an empty string when absent
Path
function Path (Item : Exchange) return String
Return the normalized decoded path used by the router.
Parameters
- Item
Request exchange
Return value
Decoded path
Peer
function Peer (Item : Exchange) return Flyology.IO.Sockets.Endpoint
Return the portable connected-peer endpoint supplied by the server adapter.
Parameters
- Item
Request exchange
Return value
Peer endpoint
Principal
function Principal (Item : Exchange) return String
Return the authenticated principal, or an empty string.
Parameters
- Item
Request exchange
Return value
Application-defined bounded principal
Problem
procedure Problem
(Item : in out Exchange;
Status : Positive;
Kind : String;
Detail : String)
Send a small application/problem+json response.
Parameters
- Item
Request exchange
- Status
HTTP status
- Kind
Stable application problem identifier
- Detail
Safe human-readable detail
Rate_Per_Second
function Rate_Per_Second (Item : Exchange) return Natural
Return the route per-client request rate; zero means unlimited.
Parameters
- Item
Request exchange
Return value
Requests per second
Read_Body
procedure Read_Body
(Item : in out Exchange;
Data : out Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Finished : out Boolean)
Stream decoded request bytes under the current absolute deadline.
Parameters
- Item
Request exchange configured for Stream_Body
- Data
Caller-owned destination
- Last
Last decoded byte, or Data'First - 1
- Finished
True after body framing and trailers are consumed
Receive_WebSocket
procedure Receive_WebSocket
(Item : in out Exchange;
Kind : out WebSocket_Data_Kind;
Data : out Flyology.Bytes.Unbounded_Bytes;
Closed : out Boolean;
Max_Message : Natural := Default_Max_WebSocket_Message;
Timeout : Duration := 30.0;
Message_Timeout : Duration := 30.0)
Receive one complete WebSocket message through the borrowed connection. A retry-quantum expiry raises Timeout_Error while the exchange remains active. A whole-message or control-write timeout makes the exchange failed and re-raises Timeout_Error.
Parameters
- Item
Upgraded request exchange
- Kind
Text or binary message kind
- Data
Complete message payload
- Closed
True when the peer completed the close handshake
- Max_Message
Maximum retained/reassembled message bytes
- Timeout
Receive quantum capped by the request deadline
- Message_Timeout
Whole-message deadline, also request-capped
Redirect
procedure Redirect
(Item : in out Exchange;
Status : Positive;
Location : String)
Send a redirect with a validated Location header.
Parameters
- Item
Request exchange
- Status
Redirect status
- Location
Redirect target
Remaining
function Remaining (Item : Exchange) return Duration
Return time remaining, or a negative value for an unlimited deadline.
Parameters
- Item
Request exchange
Return value
Remaining seconds
Request_Body_Bytes
function Request_Body_Bytes (Item : Exchange) return Natural
Return decoded request-body bytes observed so far.
Parameters
- Item
Request exchange
Return value
Decoded request bytes
Request_Body_Policy
type Request_Body_Policy is
(Reject_Body, Stream_Body, Buffer_Body, Discard_Request_Body);
Route-selected request-body handling.
Enumeration literals
- Reject_Body
Reject a request carrying a body
- Stream_Body
Decode into caller buffers
- Buffer_Body
Buffer under the shared ingress budget
- Discard_Request_Body
Explicitly consume and ignore the body
Request_Body_State
type Request_Body_State is
(Body_Pending, Body_Streaming, Body_Buffered, Body_Completed,
Body_Rejected);
Observable request-body lifecycle.
Enumeration literals
- Body_Pending
Admission or consumption has not completed
- Body_Streaming
Caller reads decoded chunks
- Body_Buffered
Buffered content is available
- Body_Completed
No retained content remains to consume
- Body_Rejected
Route policy does not accept the pending body
Request_Header
function Request_Header (Item : Exchange; Name : String) return String
Return a case-insensitive request header value. Repeated fields retain the core parser's comma-joined wire order.
Parameters
- Item
Request exchange
- Name
Header field name
Return value
Header value or an empty string
Request_Header_Count
function Request_Header_Count
(Item : Exchange; Name : String) return Natural
Count physical occurrences of a case-insensitive request field.
Parameters
- Item
Request exchange
- Name
Header field name
Return value
Physical field count before comma joining
Request_ID
function Request_ID (Item : Exchange) return String
Return the request identifier installed by middleware.
Parameters
- Item
Request exchange
Return value
Bounded validated request identifier, or an empty string
Request_Method
function Request_Method (Item : Exchange) return String
Return the request method without copying the complete request.
Parameters
- Item
Request exchange
Return value
Request method
Request_Target
function Request_Target (Item : Exchange) return String
Return the original request target.
Parameters
- Item
Request exchange
Return value
Request target
Request_Value
function Request_Value (Item : Exchange) return Request
Return a copy of the parsed request. Body storage is present after a buffered body policy has completed.
Parameters
- Item
Request exchange
Return value
Parsed request value
Respond
procedure Respond
(Item : in out Exchange;
Status : Positive;
Content_Type : String;
Payload : String;
Close : Boolean := False)
Send one complete response through the borrowed connection.
Parameters
- Item
Request exchange
- Status
HTTP status
- Content_Type
Media type, or empty to omit
- Payload
Response representation
- Close
Force connection close
Response
function Response (Item : Exchange) return Response_State
Return the high-level response lifecycle.
Parameters
- Item
Request exchange
Return value
Current response state
Response_Bytes
function Response_Bytes (Item : Exchange) return Natural
Return response payload bytes written, excluding suppressed HEAD data.
Parameters
- Item
Request exchange
Return value
Observed payload bytes
Response_State
type Response_State is
(Not_Started, Completed, Streaming_Response, Streaming_SSE,
Upgraded, Failed);
High-level response lifecycle observed through this exchange.
Enumeration literals
- Not_Started
No response bytes have been written
- Completed
One complete fixed response was written
- Streaming_Response
A chunked/close-delimited response is active
- Streaming_SSE
A server-sent event response is active
- Upgraded
A protocol upgrade owns the connection
- Failed
Response completion is unsafe or failed
Response_Status
function Response_Status (Item : Exchange) return Natural
Return the fixed response status, or zero before a response.
Parameters
- Item
Request exchange
Return value
HTTP status or zero
Route_Name
function Route_Name (Item : Exchange) return String
Return the normalized matched route name.
Parameters
- Item
Request exchange
Return value
Stable configured route name, or an empty string before routing
Seal_Route
procedure Seal_Route (Item : in out Exchange)
Freeze router-owned identity and policy before middleware runs.
Parameters
- Item
Configured request exchange
Send_SSE
procedure Send_SSE
(Item : in out Exchange;
Data : String;
Event : String := "";
Id : String := "";
Retry : Natural := 0;
Include_Id : Boolean := False;
Include_Retry : Boolean := False)
Send one SSE event with transport backpressure.
Parameters
- Item
Exchange with an active SSE response
- Data
Event data
- Event
Optional event type
- Id
Optional event id
- Retry
Optional retry milliseconds
- Include_Id
Emit id even when Id is empty
- Include_Retry
Emit retry even when Retry is zero
Send_SSE_Comment
procedure Send_SSE_Comment
(Item : in out Exchange; Comment : String := "")
Send an SSE comment heartbeat without dispatching an application event.
Parameters
- Item
Exchange with an active SSE response
- Comment
Optional comment text
Send_WebSocket
procedure Send_WebSocket
(Item : in out Exchange;
Kind : WebSocket_Data_Kind;
Data : Ada.Streams.Stream_Element_Array)
Send one WebSocket message from the sole connection-owner handler.
Parameters
- Item
Upgraded request exchange
- Kind
Text or binary message kind
- Data
Message payload
Send_WebSocket
procedure Send_WebSocket
(Item : in out Exchange;
Kind : WebSocket_Data_Kind;
Data : Flyology.Bytes.Unbounded_Bytes)
Send one owned WebSocket message without a contiguous task-stack copy.
Parameters
- Item
Upgraded request exchange
- Kind
Text or binary message kind
- Data
Owned message payload
Send_WebSocket
procedure Send_WebSocket
(Item : in out Exchange;
Data : String)
Send a validated UTF-8 text message from the sole connection owner.
Parameters
- Item
Upgraded request exchange
- Data
UTF-8 byte string
Set_Principal
procedure Set_Principal (Item : in out Exchange; Value : String)
Install an authenticated principal. Header control bytes and values longer than 256 bytes are rejected.
Parameters
- Item
Request exchange
- Value
Application-defined principal
Set_Request_ID
procedure Set_Request_ID (Item : in out Exchange; Value : String)
Install a validated request identifier for helpers and observation. Control bytes and values longer than 128 bytes are rejected.
Parameters
- Item
Request exchange
- Value
Request identifier
Text
procedure Text
(Item : in out Exchange;
Status : Positive;
Value : String)
Send a UTF-8 text response.
Parameters
- Item
Request exchange
- Status
HTTP status
- Value
Response text
Upgrade_Mode
type Upgrade_Mode is (No_Upgrade, Allow_SSE, Allow_WebSocket);
Route-selected application protocol upgrade.
Enumeration literals
- No_Upgrade
Ordinary HTTP responses only
- Allow_SSE
Server-sent event lifecycle is permitted
- Allow_WebSocket
WebSocket lifecycle is permitted
Wire_Response_Started
function Wire_Response_Started (Item : Exchange) return Boolean
Report whether the protocol engine has emitted response bytes. This narrow query supports safe error mapping without exposing the borrowed connection.
Parameters
- Item
Request exchange
Return value
True after response framing begins on the wire
Write_Chunk
procedure Write_Chunk
(Item : in out Exchange;
Data : Ada.Streams.Stream_Element_Array)
Write one binary response chunk with synchronous transport backpressure.
Parameters
- Item
Exchange with an active streaming response
- Data
Response bytes
Write_Chunk
procedure Write_Chunk (Item : in out Exchange; Data : String)
Write one response chunk with synchronous transport backpressure.
Parameters
- Item
Exchange with an active streaming response
- Data
Response bytes