Hcs.Websocket

hcs · API reference

WebSocket upgrade and frame I/O support.

Use this module when an HTTP route upgrades to a WebSocket and you want to send or receive text, binary, ping/pong, and close frames directly. HCS does not impose an application channel protocol; build that protocol in your app or combine WebSockets with Hive workers/pubsub.

Constants

val websocket_uuid : string

UUID used in WebSocket handshake per RFC 6455

Types

module Opcode : sig ... end

WebSocket frame opcode

type frame = {
  opcode : Opcode.t;
  extension : int;
  final : bool;
  content : string;
}

WebSocket frame

val pp_frame : Format.formatter -> frame -> unit
val make_frame : 
  ?opcode:Opcode.t ->
  ?extension:int ->
  ?final:bool ->
  ?content:string ->
  unit ->
  frame
val close_frame : int -> frame
val default_max_payload_size : int
type t = {
  flow : Eio.Flow.two_way_ty Eio.Std.r;
  mutable closed : bool;
  is_client : bool;
  read_buf : Buffer.t;
  max_payload_size : int;
}
type error = 
  | Connection_closed
  | Protocol_error of string
  | Io_error of string
  | Payload_too_large of int

Cryptographic helpers

val b64_encoded_sha1sum : String.t -> string

Compute SHA-1 hash and base64 encode

val compute_accept_key : string -> string

Compute the Sec-WebSocket-Accept value

module Rng : sig ... end

Frame parsing/serialization

val xor_mask : string -> string -> string

Apply XOR mask to data

val write_frame_to_buf : is_client:bool -> Buffer.t -> frame -> unit

Serialize a frame to bytes. Client frames must be masked, server frames must not be masked.

val read_exactly : [> Eio.Flow.source_ty ] Eio.Flow.source -> int -> string

Read exactly n bytes from flow

val read_frame : t -> (frame, error) result

Connection API

val is_open : t -> bool

Check if connection is open

val send : t -> frame -> (unit, error) result

Send a frame

val send_text : t -> string -> (unit, error) result

Send a text message

val send_binary : t -> string -> (unit, error) result

Send a binary message

val send_ping : t -> ?content:string -> unit -> (unit, error) result

Send a ping

val send_pong : t -> ?content:string -> unit -> (unit, error) result

Send a pong

val recv : t -> (frame, error) result
val recv_message : t -> (Opcode.t * string, error) result

Receive a complete message (handles fragmentation)

val close : ?code:int -> t -> unit

Close the connection

Handshake helpers

val has_connection_upgrade_token : string -> bool

Check if request headers indicate a WebSocket upgrade

val is_upgrade_request : Http_core.Headers.t -> bool
val get_websocket_key : Http_core.Headers.t -> string option

Get the Sec-WebSocket-Key from request headers

val supported_websocket_version : string
val get_websocket_version : Http_core.Headers.t -> string option
val validate_websocket_version : Http_core.Headers.t -> (unit, string) result
val get_origin : Http_core.Headers.t -> string option

Get the Origin header from request headers

type origin_policy = 
  | Allow_all
  | Allow_list of string list
  | Allow_same_origin

Origin policy for WebSocket connections.

  • ``Allow_all` accepts connections from any origin (NOT RECOMMENDED for production)
  • ``Allow_list origins` only accepts connections from the specified origins
  • ``Allow_same_origin` only accepts connections where Origin matches the Host header
val validate_origin : 
  policy:origin_policy ->
  Http_core.Headers.t ->
  (unit, string) result

Validate Origin header against policy.

parameter policy The origin validation policy parameter headers The request headers (must contain Origin, may contain Host) returns Ok () if origin is allowed, Error reason if rejected

val generate_key : unit -> string

Generate random base64-encoded key for client handshake

Client API

val connect : 
  sw:Eio.Switch.t ->
  net:[> [> `Generic ] Eio.Net.ty ] Eio.Net.t ->
  ?tls_config:Tls_config.Client.t ->
  ?protocols:string list ->
  Uri.t ->
  (t, error) result

Connect to a WebSocket server

Server API

val accept : 
  ?max_payload_size:int ->
  flow:[> Eio.Flow.two_way_ty ] Eio.Flow.sink ->
  key:string ->
  unit ->
  (t, error) result