bond-channels
bond-channels adds an Action Cable WebSocket (the actioncable-v1-json protocol) to a Bond app. The browser opens one WebSocket per tab. It subscribes to channels, and the app sends to the subscribers of a topic with a broadcast, from an HTTP handler or from a channel.
It speaks the Rails protocol, so the Action Cable client of Rails and <turbo-cable-stream-source> of Turbo work with it. The stream names that Rails signs verify here, and the other way round.
Install #
Needs Agentica 0.31.0 or later and Bond 0.13.1. The app depends on Bond itself, at the same tag as the package, because two sources for one name in a tree is PKG-SOURCE-CONFLICT. Add both in a project with an agentica.toml:
agentica add bond https://github.com/agentica-lang/bond --tag 0.13.1
agentica add bond-channels https://github.com/agentica-lang/packages --tag bond-channels-0.6.1 --subdir bond-channelsThat writes these lines of agentica.toml, and the entries of agentica.lock:
[dependencies]
bond = { git = "https://github.com/agentica-lang/bond", tag = "0.13.1" }
bond-channels = { git = "https://github.com/agentica-lang/packages", tag = "bond-channels-0.6.1", subdir = "bond-channels" }On Agentica 0.30, stay on bond-channels-0.3.1 with Bond 0.11.0.
The releases and their notes are in the changelog.
Example #
A chat room. A person is the cookie user. A subscription listens to the topic room:ROOM, and GET /say?room=1&text=hi tells everyone in room 1:
import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Channels from "pkg/bond-channels/channels"
# The person is the cookie "user"; a connection with no cookie is refused.
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
def room_of(params: JSON.Value) -> Result[String]
room = try JSON.get(params, "room")
return JSON.string(room)
end
# A subscription listens to the topic of its room.
def subscribed(session: Channels.Session, params: JSON.Value) -> Result[Channels.Subscription]
room = try room_of(params)
return ok(Channels.Subscription(streams: ["room:#{room}"]))
end
# GET /say?room=1&text=hi tells every subscriber of the room.
def say(hub: Channels.Hub, conn: Bond.Conn) -> Result[Bond.Conn]
room = try Bond.query(conn, "room")
text = try Bond.query(conn, "text")
try Channels.broadcast_text(hub, "room:#{room}", text)
return ok(Bond.text(conn, 200, "sent"))
end
def main() -> Void
hub = Channels.start_hub().unwrap!
options = Channels.MountOptions(
connect: &connect,
handlers: {"RoomChannel": Channels.handler(&subscribed)},
)
app = Bond.app() |> Bond.get("/say", ->(conn) { say(hub, conn) })
mounted = Channels.mount(app, "/cable", hub, options).unwrap!
server = Bond.start_with(mounted, "127.0.0.1", 0, HTTP.ServerOptions()).unwrap!
puts("listening on #{Bond.local_port(server)}")
IO.flush()
Bond.wait(server).unwrap!
endA client that connects to /cable with the subprotocol actioncable-v1-json and the cookie user=ana gets {"type":"welcome"}. After it sends {"command":"subscribe","identifier":"{\"channel\":\"RoomChannel\",\"room\":\"1\"}"}, it gets the confirmation, and then every /say of room 1:
{"identifier":"{\"channel\":\"RoomChannel\",\"room\":\"1\"}","type":"confirm_subscription"}
{"identifier":"{\"channel\":\"RoomChannel\",\"room\":\"1\"}","message":"hi"}The three parts:
- The hub (
Channels.start_hub) is one task that holds the topics and sends the broadcasts. Channels.mountadds the WebSocket route to the Bond app. Itsconnectdecides who the person is, and itshandlersmap the channel names of the client to their functions.- A broadcast (
Channels.broadcast_text,Channels.broadcast_json) sends to the subscribers of a topic. A subscription chooses its topics insubscribed.
Pages #
- Channels:
connect, the handlers, whatsubscribeddecides, actions, and when a connection leaves. - Turbo Streams: signed stream names and
<turbo-cable-stream-source>. - The hub: the options, the limits,
stats,disconnectandstop_hub.
API #
Everything is under Channels, from import Channels from "pkg/bond-channels/channels".
| Name | What it is |
|---|---|
Channels.start_hub(options), Channels.stop_hub(hub) | start and end the hub |
Channels.mount(app, path, hub, options) | adds the WebSocket route; returns a Result[Bond.App] |
Channels.handler(subscribed), .with(...) | a channel handler |
Channels.broadcast_text(hub, topic, text), Channels.broadcast_json(hub, topic, value) | send to the subscribers of a topic |
Channels.stats(hub) | the connections and subscriptions now, the drops and the lost broadcasts |
Channels.disconnect(hub, identity, reconnect) | ends every connection of one person |
Channels.stream_key, signed_stream_name, verified_stream_name, turbo_streams | Turbo Streams |
Channels.Hub, Identity, Session, Subscription, Handler, HubOptions, MountOptions, Stats | the records |