object

http_sse

High-level Server-Sent Events (SSE) predicates for opening client connections, accepting server connections, exchanging events, and running common client and server session loops.

Availability:
logtalk_load(http_sse(loader))
Author: Paulo Moura
Version: 1:0:0
Date: 2026-08-08
Compilation flags:
static, context_switching_calls
Imports:
public options
Uses:
atom
http_client
json
list
term_io
url(Representation)
user
utf_8
Remarks:
(none)
Inherited public predicates:
 check_option/1  check_options/1  default_option/1  default_options/1  option/2  option/3  valid_option/1  valid_options/1

Public predicates

open/2

Opens a client SSE connection to the given absolute http:// or https:// URL and returns an opaque handle managed by this object. Equivalent to open/3 with an empty options list.

Compilation flags:
static
Template:
open(URL,SSE)
Mode and number of proofs:
open(+atom,--compound) - one_or_error
Exceptions:
URL is a variable:
instantiation_error
URL is neither a variable nor a supported absolute SSE URL:
domain_error(http_client_sse_url,URL)
URL is a supported absolute SSE URL but uses an unsupported SSE scheme:
domain_error(http_client_sse_scheme,Scheme)
The SSE server response is not a 200 text/event-stream response:
domain_error(http_client_sse_response,Response)

open/3

Opens a client SSE connection to the given URL and returns an opaque handle. The transport/1 option selects the transport, with transport(default) deriving it from the URL scheme (http uses http_socket_transport and https uses http_process_transport). The max_field_length/1 option bounds the length, in bytes, of any single field line read from the connection (default none, meaning unbounded). Remaining options, including headers/1, query/1, version/1, connection_options/1, and last_event_id/1 (used to populate an initial Last-Event-ID request header and the handle last_event_id/1 property), are forwarded to http_client::open_sse/4.

Compilation flags:
static
Template:
open(URL,SSE,Options)
Mode and number of proofs:
open(+atom,--compound,+list) - one_or_error
Exceptions:
URL is a variable:
instantiation_error
URL is neither a variable nor a supported absolute SSE URL:
domain_error(http_client_sse_url,URL)
URL is a supported absolute SSE URL but uses an unsupported SSE scheme:
domain_error(http_client_sse_scheme,Scheme)
Options is a variable or a partial list:
instantiation_error
Options is neither a variable nor a list:
type_error(list,Options)
Options contains an invalid direct SSE option:
domain_error(http_sse_option,Option)
Options contains an invalid SSE client option:
domain_error(http_client_sse_option,Option)
The SSE server response is not a 200 text/event-stream response:
domain_error(http_client_sse_response,Response)

accept/3

Accepts one incoming SSE request on the given listener using the default response policy and returns an opaque server-side handle together with the accepted client information. Equivalent to accept/4 with an empty options list.

Compilation flags:
static
Template:
accept(Listener,SSE,ClientInfo)
Mode and number of proofs:
accept(+compound,--compound,--compound) - one_or_error
Exceptions:
The SSE request does not exist:
existence_error(http_socket_transport_sse_request,end_of_file)
The SSE request is not a valid normalized SSE request:
domain_error(http_server_core_sse_request,Request)

accept/4

Accepts one incoming SSE request on the given listener and returns an opaque server-side handle. The transport/1 and max_field_length/1 options are interpreted as in open/3. The retry/1 option (default none), when not none, writes a retry(Milliseconds) record, as accepted by send/2, immediately after acceptance, before returning; this is equivalent to, but saves, a first call to send_retry/2. Remaining options, including headers/1 (extra response headers) and properties/1 (extra response properties), are forwarded to http_server_core::accept_sse/3.

Compilation flags:
static
Template:
accept(Listener,SSE,ClientInfo,Options)
Mode and number of proofs:
accept(+compound,--compound,--compound,+list) - one_or_error
Exceptions:
Options is a variable or a partial list:
instantiation_error
Options is neither a variable nor a list:
type_error(list,Options)
Options contains an invalid direct SSE option:
domain_error(http_sse_option,Option)
Options contains an invalid SSE acceptance option:
domain_error(http_server_core_sse_option,Option)
Options contains reserved SSE response headers:
domain_error(http_server_core_sse_headers,Headers)
The SSE request does not exist:
existence_error(http_socket_transport_sse_request,end_of_file)
The SSE request is not a valid normalized SSE request:
domain_error(http_server_core_sse_request,Request)

send/2

Writes one outbound SSE record using the opaque handle. Accepts normalized event(Type, Data, Id) terms (Type and Id are the atom none when absent) and the convenience wrappers data(Data), event(Type, Data), id_data(Id, Data), comment(Text), retry(Milliseconds), json(JSON), and term(Term). Equivalent to send/3 with an empty options list.

Compilation flags:
static
Template:
send(SSE,Event)
Mode and number of proofs:
send(+compound,+term) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
Event is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

send/3

Writes one outbound SSE record using the opaque handle and the given write options. The direct API accepts a flush(on|off) option controlling whether the underlying stream is flushed after writing (default on).

Compilation flags:
static
Template:
send(SSE,Event,Options)
Mode and number of proofs:
send(+compound,+term,+list) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
Event is not a valid outbound SSE record:
domain_error(http_sse_event,Event)
Options is a variable or a partial list:
instantiation_error
Options is neither a variable nor a list:
type_error(list,Options)
Options contains an invalid write option:
domain_error(http_sse_write_option,Option)

receive/2

Reads and dispatches the next SSE event using the opaque handle, following the event stream interpretation algorithm. Comment lines and retry fields are consumed silently and, for retry, update the handle retry/1 property. Returns end_of_file, and closes and deregisters the handle, when the peer closes the connection before another event is dispatched. Equivalent to receive/3 with an empty options list.

Compilation flags:
static
Template:
receive(SSE,Event)
Mode and number of proofs:
receive(+compound,--term) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
A field line uses a line ending other than a line feed or a carriage return immediately followed by a line feed:
domain_error(http_sse_line_ending,Byte)
A field line exceeds the configured maximum length:
domain_error(http_sse_field_length,Length)

receive/3

Reads the next SSE event using the opaque handle and the given read options. The direct API accepts a max_field_length(Bytes|none) override of the handle default set by open/3 or accept/4.

Compilation flags:
static
Template:
receive(SSE,Event,Options)
Mode and number of proofs:
receive(+compound,--term,+list) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
Options is a variable or a partial list:
instantiation_error
Options is neither a variable nor a list:
type_error(list,Options)
Options contains an invalid direct SSE option:
domain_error(http_sse_option,Option)
A field line uses a line ending other than a line feed or a carriage return immediately followed by a line feed:
domain_error(http_sse_line_ending,Byte)
A field line exceeds the configured maximum length:
domain_error(http_sse_field_length,Length)

close/1

Best-effort close of the SSE handle.

Compilation flags:
static
Template:
close(SSE)
Mode and number of proofs:
close(+compound) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)

close/2

Best-effort close of the SSE handle. First attempts to write the given final record, which must be valid for send/2; the handle is closed and deregistered regardless of whether that write succeeds.

Compilation flags:
static
Template:
close(SSE,Event)
Mode and number of proofs:
close(+compound,+term) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
Event is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

property/2

Enumerates properties of an open opaque SSE handle. Supported properties are role(client|server), transport(Transport), response(Response), connection(Connection), client_info(ClientInfo) (server-side handles only), last_event_id(Id|none), and retry(Milliseconds|none).

Compilation flags:
static
Template:
property(SSE,Property)
Mode and number of proofs:
property(+compound,+compound) - zero_or_one
property(+compound,--compound) - zero_or_more

send_data/2

Convenience predicate equivalent to send(SSE, data(Data)).

Compilation flags:
static
Template:
send_data(SSE,Data)
Mode and number of proofs:
send_data(+compound,+atom) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
data(Data) is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

send_event/3

Convenience predicate equivalent to send(SSE, event(Type, Data)).

Compilation flags:
static
Template:
send_event(SSE,Type,Data)
Mode and number of proofs:
send_event(+compound,+atom,+atom) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
event(Type, Data) is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

send_id_data/3

Convenience predicate equivalent to send(SSE, id_data(Id, Data)).

Compilation flags:
static
Template:
send_id_data(SSE,Id,Data)
Mode and number of proofs:
send_id_data(+compound,+atom,+atom) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
send(SSE, id_data(Id, Data)) is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

send_comment/2

Convenience predicate equivalent to send(SSE, comment(Text)). Commonly used to send an idle keep-alive ping that the peer silently discards.

Compilation flags:
static
Template:
send_comment(SSE,Text)
Mode and number of proofs:
send_comment(+compound,+atom) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
send(SSE, comment(Text)) is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

send_retry/2

Convenience predicate equivalent to send(SSE, retry(Milliseconds)).

Compilation flags:
static
Template:
send_retry(SSE,Milliseconds)
Mode and number of proofs:
send_retry(+compound,+integer) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
send(SSE, retry(Milliseconds)) is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

send_json/2

Convenience predicate that JSON-encodes JSON and sends it as a data-only event.

Compilation flags:
static
Template:
send_json(SSE,JSON)
Mode and number of proofs:
send_json(+compound,+term) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)

receive_json/2

Convenience predicate that reads the next dispatched event and JSON-decodes its data.

Compilation flags:
static
Template:
receive_json(SSE,JSON)
Mode and number of proofs:
receive_json(+compound,--term) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
The event data is not valid JSON text:
domain_error(http_sse_json_text,Text)

send_term/2

Convenience predicate that writes Term to an atom and sends it as a data-only event.

Compilation flags:
static
Template:
send_term(SSE,Term)
Mode and number of proofs:
send_term(+compound,+term) - one_or_error
Exceptions:
SSE is a variable:
instantiation_error
SSE is neither a variable nor an open opaque SSE handle:
domain_error(http_sse_handle,SSE)
SSE is an open opaque SSE handle but refers to a closed opaque SSE handle:
existence_error(http_sse_handle,SSE)
term(Term) is not a valid outbound SSE record:
domain_error(http_sse_event,Event)

receive_term/2

Convenience predicate that reads the next dispatched event and reads its data back as a term.

Compilation flags:
static
Template:
receive_term(SSE,Term)
Mode and number of proofs:
receive_term(+compound,--term) - one_or_error
Exceptions:
The event data does not read back as a term:
domain_error(http_sse_term_text,Text)

receive_data/2

Convenience predicate that reads the next dispatched event and returns just its data.

Compilation flags:
static
Template:
receive_data(SSE,Data)
Mode and number of proofs:
receive_data(+compound,--atom) - one_or_error
Exceptions:
The received record is not a dispatched event:
domain_error(http_sse_event_message,Event)

open_session/4

Convenience wrapper that opens a client SSE connection and runs one callback-driven client session, reconnecting with the last received event id when the connection drops, until the handler signals stop or reconnection is exhausted. Equivalent to open_session/5 with an empty options list.

Compilation flags:
static
Template:
open_session(URL,Handler,Response,State)
Mode and number of proofs:
open_session(+atom,+object_identifier,--compound,--compound) - one_or_error
Exceptions:
URL is a variable:
instantiation_error
URL is neither a variable nor a supported absolute SSE URL:
domain_error(http_client_sse_url,URL)
URL is a supported absolute SSE URL but uses an unsupported SSE scheme:
domain_error(http_client_sse_scheme,Scheme)
Handler is a variable:
instantiation_error
Handler is neither a variable nor an existing object:
existence_error(object,Handler)
Handler does not conform to http_sse_service_handler_protocol:
domain_error(http_sse_service_handler,Handler)
URL is not a supported absolute SSE URL:
domain_error(http_client_sse_url,URL)
URL uses an unsupported SSE scheme:
domain_error(http_client_sse_scheme,Scheme)
The SSE server response is not a 200 text/event-stream response:
domain_error(http_client_sse_response,Response)

open_session/5

Convenience wrapper over open_session/4 that also accepts reconnect(on|off) (default on) and max_reconnect_attempts(Count|infinite) (default infinite) session loop options, in addition to the direct client options accepted by open/3. Reconnection is attempted immediately, without an inter-attempt delay. State is unified with closed(LastEventId) when the session ends.

Compilation flags:
static
Template:
open_session(URL,Handler,Response,State,Options)
Mode and number of proofs:
open_session(+atom,+object_identifier,--compound,--compound,+list) - one_or_error
Exceptions:
URL is a variable:
instantiation_error
URL is neither a variable nor a supported absolute SSE URL:
domain_error(http_client_sse_url,URL)
URL is a supported absolute SSE URL but uses an unsupported SSE scheme:
domain_error(http_client_sse_scheme,Scheme)
Handler is a variable:
instantiation_error
Handler is neither a variable nor an existing object:
existence_error(object,Handler)
Handler is an object but does not conform to http_sse_service_handler_protocol:
domain_error(http_sse_service_handler,Handler)
Options contains an invalid SSE service loop option:
domain_error(http_sse_service_option,Option)

serve_once/5

Convenience wrapper that accepts one incoming SSE request on the given listener using the default response policy and runs one callback-driven server session, repeatedly asking the handler for the next records to write until it signals stop, then closes the connection. Equivalent to serve_once/6 with an empty options list.

Compilation flags:
static
Template:
serve_once(Listener,Handler,Response,State,ClientInfo)
Mode and number of proofs:
serve_once(+compound,+object_identifier,--compound,--compound,--compound) - one_or_error
Exceptions:
Handler is a variable:
instantiation_error
Handler is neither a variable nor an existing object:
existence_error(object,Handler)
Handler is an object but does not conform to http_sse_service_handler_protocol:
domain_error(http_sse_service_handler,Handler)
The SSE opening request does not exist:
existence_error(http_socket_transport_sse_request,end_of_file)
The SSE opening response is invalid:
domain_error(http_socket_transport_sse_response,Response)
The delegated HTTP server rejects the response stream:
domain_error(http_response_stream,Error)

serve_once/6

Convenience wrapper that accepts one incoming SSE request on the given listener and runs one callback-driven server session using the given combined acceptance and direct options, as accepted by accept/4.

Compilation flags:
static
Template:
serve_once(Listener,Handler,Response,State,ClientInfo,Options)
Mode and number of proofs:
serve_once(+compound,+object_identifier,--compound,--compound,--compound,+list) - one_or_error
Exceptions:
Handler is a variable:
instantiation_error
Handler is neither a variable nor an existing object:
existence_error(object,Handler)
Handler is an object but does not conform to http_sse_service_handler_protocol:
domain_error(http_sse_service_handler,Handler)

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

handle_seed_/1

Last allocated opaque SSE handle identifier.

Compilation flags:
dynamic
Template:
handle_seed_(HandleId)
Mode and number of proofs:
handle_seed_(?positive_integer) - zero_or_one

handle_state_/9

Stored opaque SSE handle state.

Compilation flags:
dynamic
Template:
handle_state_(HandleId,Role,Transport,Connection,Response,ClientInfo,LastEventId,Retry,MaxFieldLength)
Mode and number of proofs:
handle_state_(?positive_integer,?atom,?object_identifier,?compound,?compound,?term,?atom,?term,?term) - zero_or_more

Operators

(none)

See also

http_sse_service_handler_protocol