Hcs.Sse_client

hcs · API reference

Low-level single-connection SSE client.

Use this when you need explicit control over one SSE connection, custom retry/reconnect behavior, direct next polling, or protocol-level tests. For ordinary reconnecting application clients, prefer Event_source.

Low-level Server-Sent Events client.

This module owns one SSE HTTP connection and exposes a pull API. It parses the SSE wire format and tracks id / retry fields, but it does not reconnect. Use Event_source for the higher-level reconnecting client.

Example:

match
  Hcs.Sse_client.connect ~sw ~net ~clock
    (Uri.of_string "http://localhost/events")
with
| Error e -> prerr_endline (Hcs.Sse_client.error_to_string e)
| Ok conn -> (
    match Hcs.Sse_client.next conn with
    | Ok (Some ev) -> print_endline ev.data
    | Ok None -> ()
    | Error e -> prerr_endline (Hcs.Sse_client.error_to_string e))

type event = {
  event_type : string option;
  data : string;
  id : string option;
  retry : int option;
}

Parsed SSE event.

val make_event : 
  ?event_type:string ->
  ?id:string ->
  ?retry:int ->
  string ->
  event

Construct an event value, useful in tests.

type error = 
  | Connection_failed of string
  | Http_error of {
    status : int;
    body : string option;
  }
  | Protocol_error of string
  | Io_error of exn
  | Closed (* Connection or protocol failure. *)

val error_to_string : error -> string

Human-readable error.

type config = {
  connect_timeout : float;
  read_timeout : float;
  buffer_size : int;
  max_response_header_size : int;
  max_line_size : int;
  max_event_data_size : int;
  tls : Tls_config.Client.t;
  headers : (string * string) list;
}

Client limits and transport options.

val default_config : config

val with_connect_timeout : float -> config -> config

val with_read_timeout : float -> config -> config

val with_buffer_size : int -> config -> config

val with_max_response_header_size : int -> config -> config

val with_max_line_size : int -> config -> config

val with_max_event_data_size : int -> config -> config

val with_tls : Tls_config.Client.t -> config -> config

val with_insecure_tls : config -> config

val with_header : string -> string -> config -> config

val with_headers : (string * string) list -> config -> config

Configuration helpers.

type t

Open SSE connection.

val connect : 
  sw:Eio.Switch.t ->
  net:_ Eio.Net.t ->
  clock:_ Eio.Time.clock ->
  ?config:config ->
  ?last_event_id:string ->
  Uri.t ->
  (t, error) result

Connect to an SSE URI. last_event_id is sent as Last-Event-ID.

val next : t -> (event option, error) result

Read the next event. Comments and incomplete records are skipped.

val is_open : t -> bool

val last_event_id : t -> string option

val retry : t -> int option

val close : t -> unit

Connection state helpers.

val to_seq : t -> (event, error) result Seq.t

Lazy sequence of events ending with one error when the connection closes or fails.

val iter : t -> f:(event -> unit) -> (unit, error) result

Iterate until the connection closes or fails.