Who is connected #

MountOptions.connect runs once for each connection, with the handshake of the WebSocket (so with its cookies). It returns the Identity of the person, or an error:

def connect(conn: Bond.Conn) -> Result[Channels.Identity]
  user = try Bond.cookie(conn, "user")
  return ok(Channels.Identity(id: user, data: JSON.from(user)))
end

Identity.id is the key of the person (for logs, presence and Channels.disconnect). Identity.data is JSON with whatever the handlers need, so the hub holds no type of your app.

An error is answered with {"type":"disconnect","reason":"unauthorized","reconnect":false} and the close code 1000. The client is not welcomed.

connect runs in the handler of the WebSocket, after the upgrade, and never in a before filter of Bond. A 302 or a 403 on the handshake makes the Rails client retry in a loop, so an app with a global sign-in filter exempts the cable path.

A handshake from another site is answered 403. MountOptions.allowed_origins lists the origins that are allowed, as in Bond.websocket. A client that does not offer the subprotocol actioncable-v1-json is closed with 1002.

The handlers of a channel #

MountOptions.handlers maps the channel names that the client sends ("RoomChannel") to a Channels.Handler, which has three functions:

FunctionTypeWhen it runs
subscribedFn[Session, JSON.Value, Result[Subscription]]the client subscribes; params is the whole identifier
unsubscribedFn[Session, JSON.Value, Result[Void]]the client unsubscribes, or the connection ends in any way
performFn[Session, JSON.Value, String, JSON.Value, Result[List[JSON.Value]]]the client sends a message to the channel

Channels.handler(subscribed) makes a handler that has no unsubscribed and takes no actions. Replace those with with:

room = Channels.handler(&subscribed).with(unsubscribed: on_leave, perform: on_action)
handlers = {"RoomChannel": room}

A Session has the number of the connection, its identity, and the subscriptions it holds now (their identifiers).

Every function runs on the task of its connection, the one that handles the commands of that client. A slow perform (a database call, a lock) stalls the next commands and pings of that client, and a connection whose inbox fills with them is dropped. Broadcasts do not queue there: the hub writes them to the WebSocket itself. Do the slow work in a task of your own and answer with a broadcast.

So a broadcast can reach the client before the reply of the perform that sent it; Action Cable does not promise that order either.

An error from any of them is logged, and the connection stays open. An error from subscribed also rejects the subscription.

What subscribed decides #

subscribed returns a Subscription:

FieldDefaultWhat it is
streams[]the topics whose broadcasts reach this subscription
transmit[]payloads for this connection only, sent before the confirmation; a JSON string is a Turbo Stream, an object is a notice
rejectedfalseanswer reject_subscription instead of the confirmation
def subscribed(session: Channels.Session, params: JSON.Value) -> Result[Channels.Subscription]
  room = try room_of(params)
  greeting = JSON.from("welcome #{session.identity.id}")
  return ok(Channels.Subscription(streams: ["room:#{room}"], transmit: [greeting]))
end

A broadcast never reaches a client before the confirmation of its subscription. A connection holds at most 64 subscriptions; a subscribe over that is logged and ignored.

Actions #

A client message has an action and any other keys in its data. perform gets the action and the whole data, and returns the payloads to send to that connection only. A blank action is receive, as in Action Cable.

def acted(
  hub: Channels.Hub,
  session: Channels.Session,
  params: JSON.Value,
  action: String,
  data: JSON.Value,
) -> Result[List[JSON.Value]]
  room = try room_of(params)
  if action == "say"
    text = try JSON.string(try JSON.get(data, "text"))
    try Channels.broadcast_text(hub, "room:#{room}", "#{session.identity.id}: #{text}")
    return ok([])
  end

  return ok([JSON.from("unknown action #{action}")])
end

A client that sends {"command":"message","identifier":"...","data":"{\"action\":\"say\",\"text\":\"yo\"}"} makes every subscriber of the room hear ana: yo. Any other action gets "unknown action NAME" back, to that client only.

A function of a handler that needs more than its arguments, such as the hub, is a lambda:

on_leave = ->(session, params) { left(hub, session, params) }

What Action Cable only logs #

As in Rails, these get no reply, and the connection stays open: a subscribe to a channel that is not in handlers, an unsubscribe of an identifier that is not subscribed, an action on a subscription that does not exist, and a frame that is not a command.

When a connection ends #

unsubscribed runs for each subscription when the client unsubscribes, closes, drops, is cut off for being too slow, or when its handler crashes. It is the place to announce that a person left:

def left(hub: Channels.Hub, session: Channels.Session, params: JSON.Value) -> Result[Void]
  room = try room_of(params)
  return Channels.broadcast_text(hub, "room:#{room}", "#{session.identity.id} left")
end