WebSocket connection lifecycle for Supabase Realtime.
Holds a single WebSocket per connect call — hato-backed on the JVM,
js/WebSocket on ClojureScript. 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 the platform socket.
Platform notes: browsers cannot set headers on the WebSocket upgrade, so
on ClojureScript the Authorization header is skipped (the apikey
query param and the access_token join payload carry auth instead), and
timers use js/setInterval/js/setTimeout in place of JVM executors.
WebSocket connection lifecycle for Supabase Realtime. Holds a single WebSocket per `connect` call — hato-backed on the JVM, `js/WebSocket` on ClojureScript. 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 the platform socket. Platform notes: browsers cannot set headers on the WebSocket upgrade, so on ClojureScript the `Authorization` header is skipped (the `apikey` query param and the `access_token` join payload carry auth instead), and timers use `js/setInterval`/`js/setTimeout` in place of JVM executors.
(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.:auto-reconnect? — reconnect on unexpected close (default true):reconnect-after-ms — (fn [tries]) → delay before attempt tries.
Defaults to default-reconnect-after-ms.:max-reconnect-attempts — give up after N attempts (default: never):access-token-fn — zero-arity fn returning a token string.
Called for the initial upgrade and re-resolved
at every reconnect and channel (re)join, so a
refreshed token is picked up. On exception or
non-string result, falls back to the token set
via set-auth, then the client's
:access-token, then :api-key.:http-fallback? — send plain broadcasts over HTTP POST when the
socket is not :open (default false). See
supabase.realtime/broadcast.Returns a connection map, 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.
- `:auto-reconnect?` — reconnect on unexpected close (default true)
- `:reconnect-after-ms` — `(fn [tries])` → delay before attempt `tries`.
Defaults to `default-reconnect-after-ms`.
- `:max-reconnect-attempts` — give up after N attempts (default: never)
- `:access-token-fn` — zero-arity fn returning a token string.
Called for the initial upgrade and re-resolved
at every reconnect and channel (re)join, so a
refreshed token is picked up. On exception or
non-string result, falls back to the token set
via `set-auth`, then the client's
`:access-token`, then `:api-key`.
- `:http-fallback?` — send plain broadcasts over HTTP POST when the
socket is not `:open` (default false). See
`supabase.realtime/broadcast`.
Returns a connection map, or an anomaly on failure.(default-reconnect-after-ms tries)Default backoff: min(10s, 2s^tries) — 2s, 4s, 8s, then 10s cap.
Matches realtime-ex.
Default backoff: `min(10s, 2s^tries)` — 2s, 4s, 8s, then 10s cap. Matches realtime-ex.
(disconnect conn)Closes the connection: stops the heartbeat and reconnect timer, closes the
socket, and marks state as :closed. Idempotent; no reconnect is
scheduled.
Closes the connection: stops the heartbeat and reconnect timer, closes the socket, and marks state as `:closed`. Idempotent; no reconnect is scheduled.
(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.
(resolve-token conn)Resolves the bearer token for conn: the :access-token-fn result when
supplied and successful, then the last token set via set-auth (cleared
on sign-out), then the client's :access-token, then :api-key.
Resolves the bearer token for `conn`: the `:access-token-fn` result when supplied and successful, then the last token set via `set-auth` (cleared on sign-out), then the client's `:access-token`, then `:api-key`.
(set-auth-token! conn token)Records token as the connection's current auth token (nil clears it,
e.g. on sign-out). Later channel joins and reconnect rejoins resolve the
token via resolve-token, so a cleared token no longer leaks into join
payloads. Mirrors realtime-js updating the join payload on auth change.
Records `token` as the connection's current auth token (nil clears it, e.g. on sign-out). Later channel joins and reconnect rejoins resolve the token via `resolve-token`, so a cleared token no longer leaks into join payloads. Mirrors realtime-js updating the join payload on auth change.
(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. JVM only.
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`. JVM only. `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.
(ws-transport url _headers handlers)Opens a js/WebSocket to url with the given handlers map and
returns a reified Transport. ClojureScript only.
headers is ignored: the browser WebSocket API cannot set upgrade
headers. Auth still reaches the server via the apikey query param
and the access_token join payload.
Works in browsers and in Node.js >= 22 (global WebSocket). Messages
arrive as whole text frames, so no reassembly is needed.
Opens a `js/WebSocket` to `url` with the given `handlers` map and returns a reified `Transport`. ClojureScript only. `headers` is ignored: the browser WebSocket API cannot set upgrade headers. Auth still reaches the server via the `apikey` query param and the `access_token` join payload. Works in browsers and in Node.js >= 22 (global `WebSocket`). Messages arrive as whole text frames, so no reassembly is needed.
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 |