Flyology HTTP API reference

Description

Consumes WHATWG server-sent event streams over the protocol selected by Flyology.HTTP.Client. Parsing and reconnect state are independent of the HTTP/1.1, HTTP/2, or HTTP/3 response framing used by the underlying client.

Data

function Data (Item : Event) return String

Return the event data with embedded LF separators between data fields.

Parameters

Item: Event to inspect

Return value

UTF-8 event data

Event

type Event is private;

One dispatched server-sent event. Text values contain UTF-8 bytes; malformed input sequences are decoded as U+FFFD.

Event_Source

type Event_Source
  (HTTP                : not null access Client;
   Maximum_Event_Bytes : Positive) is limited private;

Stateful EventSource bound to an existing origin client. The caller's byte bound covers the retained current line, event fields, and event id.

Record fields

HTTP: Client borrowed for every initial and reconnect request
Maximum_Event_Bytes: Maximum retained parser-field bytes

Event_Too_Large

Event_Too_Large : exception;

Raised before retained parser fields exceed the EventSource byte bound.

Event_Type

function Event_Type (Item : Event) return String

Return the event type, or message when no event field was supplied.

Parameters

Item: Event to inspect

Return value

UTF-8 event type

Finish

procedure Finish
  (Operation : in out Read_Operation;
   Result    : out Read_Result;
   Value     : out Event)

Consume one terminal composable read.

Parameters

Operation: Terminal read operation
Result: Whether an event or permanent stop was observed
Value: Next event when Result is Event_Available

Invalid_Event_Stream

Invalid_Event_Stream : exception;

Raised when a response is not a valid EventSource response.

Last_Event_ID

function Last_Event_ID (Item : Event) return String

Return the EventSource last-event id current at dispatch.

Parameters

Item: Event to inspect

Return value

UTF-8 last-event id, possibly empty

Last_Event_ID

function Last_Event_ID (Item : Event_Source) return String

Return the id that will be sent on the next reconnect request.

Parameters

Item: Initialized EventSource

Return value

Current UTF-8 last-event id

Open

procedure Open
  (Item                    : in out Event_Source;
   Value                   : Request;
   Initial_Reconnect_Delay : Duration;
   Maximum_Reconnect_Delay : Duration;
   Deadline                : Monotonic_Deadline)

Initialize or reset an EventSource without performing network I/O. The supplied request contributes its target, headers, and redirect policy. Open makes its retained copy a bodyless GET and controls the Accept and Last-Event-ID fields. One absolute deadline covers the initial request, every body read, reconnect wait, and later request.

Parameters

Item: EventSource to initialize
Value: Request template retained by Item
Initial_Reconnect_Delay: Initial reconnection delay in seconds
Maximum_Reconnect_Delay: Largest server retry value accepted
Deadline: Absolute lifecycle deadline

Raised exceptions

Constraint_Error: A delay is negative or initial exceeds max

Read

function Read
  (Set   : not null access Flyology.Operations.Completion_Set'Class;
   Item  : not null access Event_Source;
   Token : access Flyology.Cancellation.Token := null)
   return Read_Operation

Start one composable EventSource read.

Parameters

Set: Owner completion set
Item: Initialized EventSource borrowed through terminal drain
Token: Optional cancellation source borrowed through drain

Return value

Started EventSource read operation

Read

procedure Read
  (Item   : aliased in out Event_Source;
   Result : out Read_Result;
   Value  : out Event;
   Token  : access Flyology.Cancellation.Token := null)

Return the next event, reconnecting after clean EOF or recoverable transport failure. HTTP 204 returns Stream_Stopped and permanently disables reconnect. Cancellation and the absolute deadline interrupt requests, reads, and reconnect waits using their ordinary exceptions.

Parameters

Item: Initialized EventSource to advance
Result: Whether an event or permanent stop was observed
Value: Next event when Result is Event_Available
Token: Optional cancellation source borrowed for this call

Raised exceptions

Program_Error: Item was not initialized by Open
Invalid_Event_Stream: Response status or media type violates the EventSource contract
Event_Too_Large: Retained parser state would exceed the bound
Reconnect_Delay_Too_Large: A retry field exceeds caller policy

Read

procedure Read
  (Item      : not null access Event_Source;
   Token     : access Flyology.Cancellation.Token := null;
   Operation : in out Read_Operation)

Start or restart a composable read in an established operation.

Parameters

Item: Initialized EventSource borrowed through terminal drain
Token: Optional cancellation source borrowed through drain
Operation: Inactive established operation to start

Read_Operation

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

One owner-driven read through initial connection, response parsing, reconnect timers, and later connections. Item and Token are borrowed until terminal Finish or cancellation drain.

Read_Result

type Read_Result is (Event_Available, Stream_Stopped);

Outcome of one Read call.

Enumeration literals

Event_Available: Item contains the next dispatched event
Stream_Stopped: HTTP 204 permanently stopped this event source

Reconnect_Delay

function Reconnect_Delay (Item : Event_Source) return Duration

Return the reconnect delay currently selected by the stream.

Parameters

Item: Initialized EventSource

Return value

Current delay in seconds

Reconnect_Delay_Too_Large

Reconnect_Delay_Too_Large : exception;

Raised when a server retry field exceeds the caller's configured Maximum_Reconnect_Delay.