WebSocket connection lifecycle for Supabase Realtime.
Holds a single hato-backed WebSocket per connect call. State lives in
one atom; mutation goes through swap!; user callbacks run outside the
swap to avoid running user code under contention.
The Transport protocol is the test seam — tests substitute a recording
transport (see realtime_test) without redefining hato internals.
WebSocket connection lifecycle for Supabase Realtime. Holds a single hato-backed WebSocket per `connect` call. State lives in one atom; mutation goes through `swap!`; user callbacks run outside the swap to avoid running user code under contention. The `Transport` protocol is the test seam — tests substitute a recording transport (see `realtime_test`) without redefining hato internals.
(add-binding! conn topic binding)Appends a binding to channel topic. Returns the new channel-state or nil.
Appends a binding to channel `topic`. Returns the new channel-state or nil.
(build-ws-url client)(build-ws-url client extra-params)Returns the full Realtime WebSocket URL for client with params
(default: apikey + vsn) merged into the query string.
Returns the full Realtime WebSocket URL for `client` with `params` (default: `apikey` + `vsn`) merged into the query string.
(channel-state conn topic)Reads the current channel-state map for topic, or nil.
Reads the current channel-state map for `topic`, or nil.
(connect client)(connect client opts)Opens a Realtime connection for client.
:on-error — (fn [anomaly]) for async transport/server errors:heartbeat-ms — heartbeat interval in ms (default 30000):params — extra query params merged into the WS URL:transport-factory — (fn [url headers handlers]) returning a
Transport. Defaults to ws-transport.
Useful for tests.Returns a connection map: {:client :transport :state :on-error :heartbeat},
or an anomaly on failure.
Opens a Realtime connection for `client`.
## Options
- `:on-error` — `(fn [anomaly])` for async transport/server errors
- `:heartbeat-ms` — heartbeat interval in ms (default 30000)
- `:params` — extra query params merged into the WS URL
- `:transport-factory` — `(fn [url headers handlers])` returning a
`Transport`. Defaults to `ws-transport`.
Useful for tests.
Returns a connection map: `{:client :transport :state :on-error :heartbeat}`,
or an anomaly on failure.(disconnect conn)Closes the connection: stops the heartbeat, closes the socket, and marks
state as :closed. Idempotent.
Closes the connection: stops the heartbeat, closes the socket, and marks state as `:closed`. Idempotent.
(dispatch-frame conn frame)Routes a decoded inbound frame to the matching state-update + user
callbacks. Pure mechanism; user callbacks run after state updates.
Routes a decoded inbound `frame` to the matching state-update + user callbacks. Pure mechanism; user callbacks run after state updates.
(enqueue! conn frame)Buffers a frame if the socket isn't open yet, otherwise sends it now. Returns true on send, false on buffer.
Buffers a frame if the socket isn't open yet, otherwise sends it now. Returns true on send, false on buffer.
(remove-channel! conn topic)Drops topic from the channels map.
Drops `topic` from the channels map.
(close! this code reason)Initiates an orderly close of the underlying connection.
Initiates an orderly close of the underlying connection.
(send-text this text)Sends text as a single text frame. Returns truthy on success or
throws/returns an exception object on failure.
Sends `text` as a single text frame. Returns truthy on success or throws/returns an exception object on failure.
(update-channel! conn topic f & args)Applies f (with extra args) to the channel-state at topic. Returns
the new channel-state, or nil if the topic isn't tracked.
Applies `f` (with extra `args`) to the channel-state at `topic`. Returns the new channel-state, or nil if the topic isn't tracked.
(upsert-channel! conn topic config)Initializes channel-state for topic if absent. Returns the updated
channel-state.
Initializes channel-state for `topic` if absent. Returns the updated channel-state.
(ws-transport url headers handlers)Opens a hato WebSocket to url with the given upgrade headers and
handlers map. Returns a reified Transport.
handlers keys:
:on-open (fn [])
:on-text (fn [text])
:on-close (fn [code reason])
:on-error (fn [throwable])
Partial text frames are buffered until last? is true.
Opens a hato WebSocket to `url` with the given upgrade `headers` and `handlers` map. Returns a reified `Transport`. `handlers` keys: :on-open (fn []) :on-text (fn [text]) :on-close (fn [code reason]) :on-error (fn [throwable]) Partial text frames are buffered until `last?` is true.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |