# The hub

## 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:

| Field | Default | What it is |
|---|---|---|
| `broadcast_wait_ms` | 5000 | how long a broadcast waits for room in the inbox of the hub (0 or more) |
| `beat_ms` | 3000 | the 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`:

| Field | Default | What it is |
|---|---|---|
| `connect` | none | gives the [identity](https://agentica-lang.github.io/packages/bond-channels/channels/index.md) of the person, or an `error` |
| `handlers` | none | the channel names of the client, mapped to their [handlers](https://agentica-lang.github.io/packages/bond-channels/channels/index.md) |
| `allowed_origins` | `[]` | the origins that may connect, as in `Bond.websocket` |
| `inbox` | 256 | the 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_ms` | 120000 | a peer silent for this long is closed; 0 turns it off |
| `max_message_bytes` | 65536 | a 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`:

| Field | What it counts |
|---|---|
| `connections` | the connections now |
| `subscriptions` | the subscriptions now |
| `drops` | the connections that the hub closed for a full queue |
| `lost` | the 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.

```agentica
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).
