Start and stop #

Channels.start_hub(options) starts the hub. It is one task that holds the topics and sends the broadcasts, plus a ticker for the pings. It returns a Result[Channels.Hub].

Channels.stop_hub(hub) ends it, and the ticker. Every broadcast after it fails with "closed". Its connections are told to reconnect (disconnect with reconnect: true, then close 1001) within 2 seconds, and a new connection is refused the same way, without a welcome. A hub that crashes does the same.

Channels.HubOptions has two fields:

FieldDefaultWhat it is
broadcast_wait_ms5000how long a broadcast waits for room in the inbox of the hub (0 or more)
beat_ms3000the Action Cable ping (1 or more), as Rails has it

start_hub returns an error for a beat_ms under 1 or a negative broadcast_wait_ms. The hub whose inbox stays full for broadcast_wait_ms refuses a new connection with reconnect: true and the close code 1013 ("the hub is busy").

Mount #

Channels.mount(app, path, hub, options) adds the cable WebSocket at path (use "/cable", the one that the clients expect). It returns a Result[Bond.App].

Channels.MountOptions:

FieldDefaultWhat it is
connectnonegives the identity of the person, or an error
handlersnonethe channel names of the client, mapped to their handlers
allowed_origins[]the origins that may connect, as in Bond.websocket
inbox256the events queued for the task of one connection (1 or more); its WebSocket holds twice that (at most 1048576); a connection with a full queue at any moment is dropped
idle_ms120000a peer silent for this long is closed; 0 turns it off
max_message_bytes65536a client frame over this closes the connection with 1009

mount returns an error for options that cannot work: an inbox or max_message_bytes under 1, a negative idle_ms, or an idle_ms that is not more than the beat_ms of the hub (the WebSocket ping that keeps a quiet client could never come in time). The two kinds of options are different records, so a field given to the wrong one does not compile.

A WebSocket holds one of the max_connections of the Bond server for its whole life. Set it above the number of clients plus the number of posters (Bond.start_with(app, host, port, HTTP.ServerOptions(max_connections: 1024))).

Broadcasts #

Channels.broadcast_text(hub, topic, text) sends text (Turbo Stream HTML) to the subscribers of topic, as a JSON string. Channels.broadcast_json(hub, topic, value) sends a JSON value.

A broadcast that cannot be queued in broadcast_wait_ms is an error, and it is counted as lost in stats. An HTTP handler may ignore it.

A connection that is too slow for its traffic (a full WebSocket queue, because the client does not read, or a full inbox) is dropped by the hub: it gets a disconnect frame with reconnect: true if its queue has room, and unsubscribed still runs.

Stats #

Channels.stats(hub) returns a Channels.Stats:

FieldWhat it counts
connectionsthe connections now
subscriptionsthe subscriptions now
dropsthe connections that the hub closed for a full queue
lostthe broadcasts that could not be queued

Disconnect a person #

Channels.disconnect(hub, identity, reconnect) ends every connection whose Identity.id is identity. It is remote_connections.where(...).disconnect of Rails: each connection gets {"type":"disconnect","reason":"remote","reconnect":RECONNECT} and is closed with 1000, and unsubscribed runs for its subscriptions.

Use it when a person loses a right that connect or subscribed checked once: a sign-out, a deactivation, a removal from a room.

Channels.disconnect(hub, "ana", false).unwrap!

With reconnect false the client does not come back. With true it reconnects, and connect and subscribed decide again.

A broadcast queued after the call is not delivered to those connections. What a client sent before it, and is still queued, runs first. A connection that registers after the hub handled the call is not ended. An error means the hub did not take the request in broadcast_wait_ms, or is gone (and a gone hub has no connection left to end).