Description
Provides an origin-bound synchronous RFC 6455 client. Calls preserve the same native and lightweight task semantics as Flyology.HTTP.Client. One Client owns at most one WebSocket transport and serializes its lifecycle; applications must not invoke operations on the same Client concurrently.
Abort_Connection
procedure Abort_Connection (Item : in out Client)
Close the transport without a WebSocket close handshake. The configured client may subsequently Connect again.
Parameters
- Item
Client whose transport is discarded
Add_Header
procedure Add_Header
(Item : in out Request; Name : String; Value : String)
Append one handshake field such as Authorization or Cookie. Host, framing, connection, upgrade, and every Sec-WebSocket field are owned by the client and rejected.
Parameters
- Item
Request to change
- Name
End-to-end field name
- Value
Field value
Raised exceptions
- Constraint_Error
Field syntax or ownership is invalid
- Flyology
.HTTP.Headers.Headers_Too_Large Storage is exhausted
Client
type Client is limited private;
One configured origin and at most one active WebSocket session.
Close
procedure Close
(Item : in out Client;
Code : Positive := 1_000;
Reason : String := "";
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Send a masked close and wait for the peer close under one monotonic deadline. Timeout or cancellation terminates the session. Code and Reason are validated before transmission. A successful wss close also completes TLS close-notify before releasing the transport.
Parameters
- Item
Open or close-pending client
- Code
RFC 6455 close status permitted on the wire
- Reason
UTF-8 reason of at most 123 bytes
- Timeout
Whole-close deadline
- Token
Optional cancellation source
Raised exceptions
- Program_Error
Item is not active
- Constraint_Error
Code or Reason is invalid
- Connection_Error
Masking entropy is unavailable
- Flyology
.IO.Timeout_Error Deadline expires
.Cancellation.Operation_Cancelled Token is requested
Close_Code
function Close_Code (Item : Client) return Natural
Return the received close status, or 1005 when the peer sent no status.
Parameters
- Item
Client whose peer close was received
Return value
Peer close status or 1005
Raised exceptions
- Program_Error
No peer close has been received
Close_Reason
function Close_Reason (Item : Client) return String
Return the received UTF-8 close reason.
Parameters
- Item
Client whose peer close was received
Return value
Peer close reason, possibly empty
Raised exceptions
- Program_Error
No peer close has been received
Configure
procedure Configure (Item : in out Client; Origin_Value : Origin)
Bind an unconfigured client to a cleartext ws origin represented by a compatibility HTTP Origin. No DNS or socket work occurs here. HTTPS requires the TLS overload.
Parameters
- Item
Unconfigured client
- Origin_Value
HTTP origin used as ws
Raised exceptions
- Program_Error
Item is configured or Origin_Value is HTTPS
Configure
procedure Configure
(Item : in out Client;
Origin_Value : Origin;
Backend : not null access Flyology.IO.TLS.Provider'Class)
Bind a client from a compatibility HTTP Origin and retain independent TLS provider state. This overload is required for HTTPS-as-wss and is accepted for HTTP-as-ws.
Parameters
- Item
Unconfigured client
- Origin_Value
HTTP or HTTPS origin used as ws or wss
- Backend
Initialized provider retained by Item
Raised exceptions
- Program_Error
Item is already configured
- Flyology
.IO.TLS.TLS_Error Backend cannot be retained
Configure
procedure Configure
(Item : in out Client; Origin_Value : WebSocket_Origin)
Bind an unconfigured client to a cleartext ws origin. No DNS or socket work occurs here. Secure wss origins require the TLS overload.
Parameters
- Item
Unconfigured client
- Origin_Value
Parsed ws origin
Raised exceptions
- Program_Error
Item is configured or Origin_Value is wss
Configure
procedure Configure
(Item : in out Client;
Origin_Value : WebSocket_Origin;
Backend : not null access Flyology.IO.TLS.Provider'Class)
Bind a client to a WebSocket origin and retain independent TLS provider state. This overload is required for wss and is accepted for ws.
Parameters
- Item
Unconfigured client
- Origin_Value
Parsed ws or wss origin
- Backend
Initialized provider retained by Item
Raised exceptions
- Program_Error
Item is already configured
- Flyology
.IO.TLS.TLS_Error Backend cannot be retained
Connect
procedure Connect
(Item : in out Client;
Value : Request;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Establish TCP, optional authenticated TLS, and a strict HTTP/1.1 WebSocket upgrade under one monotonic deadline. Redirects, proxying, extension negotiation, and challenge retries are not performed.
Parameters
- Item
Configured inactive client
- Value
Handshake request
- Timeout
Whole-connect deadline; negative is unlimited
- Token
Optional cancellation source
Raised exceptions
- Connection_Error
Resolution or every address attempt fails
- Constraint_Error
Serialized request head exceeds its bound
- Protocol_Error
Upgrade response is malformed or unacceptable
- Flyology
.IO.Timeout_Error Deadline expires
.Cancellation.Operation_Cancelled Token is requested
Connection_Error
Connection_Error : exception;
Raised when resolution or every address attempt fails before upgrade.
Data_Kind
type Data_Kind is (Text_Message, Binary_Message);
Application data message kind.
Enumeration literals
- Text_Message
UTF-8 text data
- Binary_Message
Opaque binary data
Default_Max_Message
Default_Max_Message : constant := 1_024 * 1_024;
Default application receive bound: one MiB after reassembly.
Header
function Header
(Item : Client; Name : String; Occurrence : Positive := 1) return String
Return one named upgrade-response field occurrence or an empty string.
Parameters
- Item
Connected client
- Name
Field name
- Occurrence
One-based occurrence
Return value
Matching value or empty string
Raised exceptions
- Program_Error
No successful handshake is retained
Header_Count
function Header_Count (Item : Client) return Natural
Return the number of physical upgrade-response fields.
Parameters
- Item
Connected client
Return value
Retained field count
Raised exceptions
- Program_Error
No successful handshake is retained
Header_Count
function Header_Count (Item : Client; Name : String) return Natural
Count case-insensitive upgrade-response field occurrences.
Parameters
- Item
Connected client
- Name
Field name
Return value
Matching physical occurrence count
Raised exceptions
- Program_Error
No successful handshake is retained
Header_Name
function Header_Name (Item : Client; Index : Positive) return String
Return one upgrade-response field name in wire order.
Parameters
- Item
Connected client
- Index
One-based physical index
Return value
Preserved field name
Raised exceptions
- Program_Error
No successful handshake is retained
- Constraint_Error
Index exceeds Header_Count
Header_Value
function Header_Value (Item : Client; Index : Positive) return String
Return one upgrade-response field value in wire order.
Parameters
- Item
Connected client
- Index
One-based physical index
Return value
Preserved field value
Raised exceptions
- Program_Error
No successful handshake is retained
- Constraint_Error
Index exceeds Header_Count
Host
function Host (Value : WebSocket_Origin) return String
Return the normalized DNS name or numeric address without IPv6 brackets.
Parameters
- Value
Origin to inspect
Return value
Origin host
Image
function Image (Value : WebSocket_Origin) return String
Format the normalized WebSocket origin, omitting a default port.
Parameters
- Value
Origin to format
Return value
Absolute ws or wss origin without a trailing slash
Is_Open
function Is_Open (Item : Client) return Boolean
Report whether application data may be sent or received.
Parameters
- Item
Client to inspect
Return value
True after Connect and before either close handshake begins
Max_Frame_Length
Max_Frame_Length : constant := 16 * 1_024 * 1_024;
Absolute supported data-frame and reassembled-message bound: 16 MiB.
Max_Handshake_Bytes
Max_Handshake_Bytes : constant := 48 * 1_024;
Maximum serialized HTTP upgrade request head: 48 KiB.
Max_Protocol_Count
Max_Protocol_Count : constant := 16;
Maximum number of subprotocol tokens retained by one request.
Max_Protocol_Length
Max_Protocol_Length : constant := 256;
Maximum byte length of one offered subprotocol token.
Max_Protocol_Offer_Bytes
Max_Protocol_Offer_Bytes : constant := 4 * 1_024;
Maximum serialized bytes retained by all subprotocol offers.
Message_Too_Large
Message_Too_Large : exception;
Raised when a received message exceeds the caller's explicit bound.
Negotiated_Protocol
function Negotiated_Protocol (Item : Client) return String
Return the selected subprotocol, or an empty string when none was negotiated.
Parameters
- Item
Connected client
Return value
Selected case-sensitive subprotocol
Raised exceptions
- Program_Error
No successful handshake is retained
Offer_Protocol
procedure Offer_Protocol (Item : in out Request; Value : String)
Append one case-sensitive WebSocket subprotocol token. Individual, aggregate, and count limits are exposed by the Max_Protocol constants. The server may select at most one offered token.
Parameters
- Item
Request to change
- Value
Nonempty HTTP token not already offered
Raised exceptions
- Constraint_Error
Value is invalid, repeated, or oversized
Parse_Origin
function Parse_Origin (Value : String) return WebSocket_Origin
Parse an absolute ws or wss origin. The input must not contain userinfo, a path other than one trailing slash, a query, or a fragment. DNS names are lower-cased; omitted ports become 80 or 443.
Parameters
- Value
Absolute WebSocket origin text
Return value
Parsed normalized WebSocket origin
Raised exceptions
- Constraint_Error
Value is not a supported ws or wss origin
Port
function Port (Value : WebSocket_Origin) return Port_Number
Return the effective origin port, including a scheme default.
Parameters
- Value
Origin to inspect
Return value
TCP port
Receive
procedure Receive
(Item : in out Client;
Kind : out Data_Kind;
Data : out Flyology.Bytes.Unbounded_Bytes;
Closed : out Boolean;
Max_Message : Natural := Default_Max_Message;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Receive and reassemble one data message. Ping is answered and pong is ignored. A valid peer close is acknowledged, retained for Close_Code and Close_Reason, and reported through Closed. Server frames must be unmasked. Max_Message is capped by Max_Frame_Length. Timeout or cancellation terminates the session because a partially consumed frame cannot be exposed as a resumable application value.
Parameters
- Item
Connected client
- Kind
Returned data kind; Text_Message when Closed is True
- Data
Complete message payload; empty when Closed is True
- Closed
Whether a valid close frame completed the session
- Max_Message
Application message bound
- Timeout
Whole-message deadline
- Token
Optional cancellation source
Raised exceptions
- Message_Too_Large
Message exceeds Max_Message
- Program_Error
Item is not active
- Constraint_Error
Max_Message exceeds Max_Frame_Length
- Connection_Error
Control-frame masking entropy is unavailable
- Protocol_Error
Peer framing or content is invalid
- Flyology
.IO.Timeout_Error Deadline expires
.Cancellation.Operation_Cancelled Token is requested
Request
type Request is private;
Mutable WebSocket handshake request. The default target is slash.
Scheme
function Scheme (Value : WebSocket_Origin) return WebSocket_Scheme
Return the WebSocket origin scheme.
Parameters
- Value
Origin to inspect
Return value
Plain_WS or Secure_WSS
Send
procedure Send
(Item : in out Client;
Kind : Data_Kind;
Data : Ada.Streams.Stream_Element_Array;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Send one final masked data frame. Text bytes must be valid UTF-8 and all data frames are bounded by Max_Frame_Length.
Parameters
- Item
Open client
- Kind
Text or binary message kind
- Data
Message payload
- Timeout
Whole-frame deadline
- Token
Optional cancellation source
Raised exceptions
- Program_Error
Item is not open
- Constraint_Error
Data is too large or invalid UTF-8
- Connection_Error
Masking entropy is unavailable
- Flyology
.IO.Timeout_Error Deadline expires
.Cancellation.Operation_Cancelled Token is requested
Send
procedure Send
(Item : in out Client;
Data : String;
Timeout : Duration := 30.0;
Token : access Flyology.Cancellation.Token := null)
Send one final masked UTF-8 text message of at most Max_Frame_Length.
Parameters
- Item
Open client
- Data
UTF-8 encoded octets
- Timeout
Whole-frame deadline
- Token
Optional cancellation source
Raised exceptions
- Program_Error
Item is not open
- Constraint_Error
Data is too large or invalid UTF-8
- Connection_Error
Masking entropy is unavailable
- Flyology
.IO.Timeout_Error Deadline expires
.Cancellation.Operation_Cancelled Token is requested
Set_Origin
procedure Set_Origin (Item : in out Request; Value : String)
Set the optional browser-style Origin field, or clear it with an empty value. The client does not derive this value automatically. Invalid or oversized field content is rejected before it is retained.
Parameters
- Item
Request to change
- Value
Origin field value or empty string
Raised exceptions
- Constraint_Error
Value is not valid field content
Set_Target
procedure Set_Target (Item : in out Request; Value : String)
Replace the origin-form handshake target. Fragments, absolute-form, controls, spaces, non-ASCII bytes, and values over 8 KiB are rejected.
Parameters
- Item
Request to change
- Value
Origin-form target
Raised exceptions
- Constraint_Error
Value is not a supported target
WebSocket_Origin
type WebSocket_Origin is private;
Normalized WebSocket origin containing only scheme, host, and port.
WebSocket_Scheme
type WebSocket_Scheme is (Plain_WS, Secure_WSS);
Scheme represented by a WebSocket origin.
Enumeration literals
- Plain_WS
Cleartext WebSocket
- Secure_WSS
WebSocket over authenticated TLS