cable_room 0.6.2 → 0.7.0.beta1

data/README.md

@@ -1 +1,1191 @@
 # CableRoom
+
+Build live Rooms on top of ActionCable.
+
+A **Room** is a long-lived, server-side object that owns a piece of shared realtime state — a
+quiz session, a collaborative document, a game lobby, a live dashboard. Exactly one instance of a
+Room runs across your whole cluster at a time, it processes messages one at a time on its own
+thread, and clients attach to it as **ports**.
+
+ActionCable gives you channels, which are per-connection and stateless. CableRoom gives you the
+thing on the other side of those channels: a single authoritative object that outlives any one
+connection, holds state in memory, and shuts itself down when nobody needs it any more.
+
+## Contents.
+
+- [How it works](#how-it-works)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Defining a Room](#defining-a-room)
+- [Ports and messaging](#ports-and-messaging)
+- [Users](#users)
+- [Authorization](#authorization)
+- [Reaping and the watchdog](#reaping-and-the-watchdog)
+- [Joining a Room from a channel](#joining-a-room-from-a-channel)
+- [Background work](#background-work)
+- [Instrumentation and errors](#instrumentation-and-errors)
+- [Configuration](#configuration)
+- [Introspection](#introspection)
+- [Subclassing](#subclassing)
+- [Upgrading from 0.6 to 1.0](#upgrading-from-06-to-10)
+- [Development](#development)
+
+## How it works.
+
+Every Room runs inside a **Host**, one per process, on a shared pool of threads. The Host holds a
+Redis lock on the Room's key, which is what guarantees a single instance cluster-wide, and renews
+it every few seconds. Members don't talk to the Room directly. They send and receive on named
+lanes called ports. Member→room traffic rides cable_room's own Redis bus (the `CABLEROOM_*`
+connection) to whichever process hosts the Room; room→member traffic goes out through the
+configured broadcaster (ActionCable or AnyCable) on pubsub streams the members listen to.
+
+Where the Host lives is a deployment choice. By default it runs inside every web process
+(`room_host = :inline`). With `room_host = :remote`, only `cable_room server` processes host
+Rooms, and web processes just carry members. See [Configuration](#configuration).
+
+```
+   Browser              Your ActionCable Channel                 The Room
+      |                  (include RoomMember)                (Room::Base subclass)
+      |                            |                                  |
+      |  --- hello (action) -----> |  --- to_room port -------------->  |  port_connected
+      |  <-- port_acknowledged --- |  <-- <token> port -------------   |
+      |                            |                                  |
+      |  --- websocket message --> |  --- to_room port ------------->  |  handle_received_message
+      |                            |                                  |
+      |  <-- websocket message --- |  <-- from_room port -----------   |  broadcast / self <<
+      |                            |  <-- <token> port -------------   |  reply
+      |                            |  <-- <user> / <tag> port ------   |  broadcast(tag: :admin)
+```
+
+Four things follow from that design:
+
+- **One instance, many processes.** A `create: true` join asks the hosts to start the Room. Every
+  host races for the Redis lock; the one that wins runs the Room and the rest do nothing. Members
+  everywhere just publish to its ports.
+- **No connection affinity.** Members can be spread across every app server, and the Room can run
+  on none of them. They only need Redis.
+- **Single-threaded Room state.** Messages and timers run one at a time, so you can touch
+  instance variables without locks.
+- **Rooms are disposable.** A Room is expected to die when it's idle and be re-created on demand.
+  Persist anything you can't lose.
+
+## Requirements.
+
+- Ruby 3.4 (CI runs 3.4)
+- Rails 7.2 through 8.x
+- Redis, reachable from every web process and every rooms host, for the bus and the Room locks
+  (ActionCable's adapter or anycable-go need one too; it can be the same server)
+
+## Installation.
+
+```ruby
+gem "cable_room"
+```
+
+Then point it at Redis:
+
+```sh
+export CABLEROOM_REDIS_URL=redis://localhost:6379/1
+```
+
+See [Configuration](#configuration) for the full list of variables.
+
+## Quick start.
+
+Define a Room:
+
+```ruby
+class ChatRoom < CableRoom::Room::Base
+  # Shut down 30 seconds after the last member leaves
+  reap_when { connected_clients.empty? }
+
+  after_startup do
+    @history = []
+  end
+
+  # Handles { "type": "chat", "body": "..." } from any member
+  def on_chat(msg)
+    entry = { user: message_origin.user, body: msg["body"], at: Time.current }
+    @history << entry
+    broadcast({ type: "chat", **entry })
+  end
+
+  # Send the backlog only to the member who just connected
+  on_port_connected do
+    reply({ type: "history", entries: @history })
+  end
+end
+```
+
+Define a channel that joins it:
+
+```ruby
+class ChatChannel < ApplicationCable::Channel
+  include CableRoom::RoomProxyChannel
+
+  subscribe_to_room do
+    join_room ChatRoom, params[:room_id], create: true, tags: params[:tags]
+  end
+end
+```
+
+Connect from the browser, and say `hello` once the subscription is confirmed:
+
+```js
+consumer.subscriptions.create({ channel: "ChatChannel", room_id: 42 }, {
+  connected() { this.perform("hello") },
+  received(message) { console.log(message) },
+})
+```
+
+That's the whole loop. `RoomProxyChannel` forwards everything the client sends into the Room and
+everything the Room broadcasts back out to the client. `hello` is what announces the member to the
+Room; nothing is announced until the client sends it (see [The hello handshake](#the-hello-handshake)).
+`create: true` means this channel will provision the Room if it isn't already running somewhere.
+
+## Defining a Room.
+
+### Lifecycle.
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  before_startup  { }   # streams aren't open yet
+  after_startup   { }   # aliased as on_startup
+  before_shutdown { }   # last chance to broadcast
+  after_shutdown  { }   # aliased as on_shutdown
+end
+```
+
+You can also just define `startup` and `shutdown` methods; they run inside the corresponding
+callback chain.
+
+Out of the box a Room broadcasts `{ type: "room_opened" }` after startup and
+`{ type: "room_closed", reason: ... }` before shutdown.
+
+To stop a Room from inside itself:
+
+```ruby
+shutdown!("everyone left")   # graceful: drains queued messages first
+stop!                        # immediate: drops anything pending
+```
+
+`lifecycle_state` returns `:initializing`, `:starting`, `:started`, `:shutting_down`, or `:dead`.
+A Room being moved to another host passes through `:freezing` and `:frozen` on the way (see
+[Migration hooks](#migration-hooks)).
+
+### Handling messages.
+
+Inbound messages arrive on the `:to_room` port and dispatch by `type`. A message of type
+`"start_quiz"` (or `"StartQuiz"`) calls `on_start_quiz`. Unknown types log a warning.
+
+```ruby
+def on_start_quiz(msg)
+  logger.info "starting with #{msg['question_count']} questions"
+end
+```
+
+Inside a handler:
+
+| Helper            | What it gives you                                       |
+| ----------------- | ------------------------------------------------------- |
+| `message`         | The raw message hash                                    |
+| `message_origin`  | The `PortClient` that sent it                           |
+| `reply(data)`     | Send back to that port alone                            |
+| `broadcast(data)` | Send to every member                                    |
+
+Override `handle_received_message(message)` if you'd rather dispatch yourself. Call `super` for
+anything you don't handle, so the built-in port and user bookkeeping keeps working.
+
+Sending the string `"KILL"` to the `:to_room` port shuts the Room down. It's a blunt instrument,
+useful in a console.
+
+### Timers.
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  periodically :tick, every: 5.seconds
+  periodically -> { broadcast({ type: "still_here" }) }, every: 1.minute
+
+  def tick; end
+end
+```
+
+Timer bodies run on the Room's thread, so they're serialized against message handling.
+
+### Migration hooks.
+
+When a host shuts down on purpose, it can move its Rooms to another host instead of closing them.
+Members don't notice: their streams stay open, and the new host picks up where the old one left
+off. The gem carries what it owns — every port with its token, tags, user, and last-seen time; the
+user map; and each reaper's deadline. A Room's own state moves through two optional hooks:
+
+```ruby
+class QuizRoom < CableRoom::Room::Base
+  def snapshot_state
+    { question_id: @question.id, answers: @answers }   # JSON only; refer to records by id
+  end
+
+  def restore_state(state)
+    @question = Question.find(state[:question_id])      # state[:key] and state["key"] both work
+    @answers = state[:answers]
+  end
+end
+```
+
+`snapshot_state` runs once the Room is frozen (nothing else is touching its state) and must return
+plain JSON: hashes, arrays, strings, numbers, booleans, and `nil`. The gem checks this when it
+takes the snapshot and raises `CableRoom::Snapshot::NotSerializable`, naming the Room class and
+key, if anything else is in there — a `Time`, a record, or a `Symbol` value, since those would
+quietly come back as something different.
+
+On the new host, a Room that defines `restore_state` gets it instead of `startup`, with whatever
+`snapshot_state` returned. A Room without these hooks is restored with its ports and users intact
+and runs `startup` again to rebuild its own state. Either way the `before_startup` and
+`after_startup` callbacks run as usual, `restored?` is true inside them, and the gem doesn't
+broadcast `room_opened` — the members were there the whole time.
+
+## Ports and messaging.
+
+A port is a name derived from the Room class, the Room key, and a port name. Members send on it
+over the Redis bus (`cr:RoomClass:key:in`, with a `:port` suffix for custom ports) and the Room
+publishes on it as a broadcaster stream (`RoomClass:key:port`). Two are reserved:
+
+- `:to_room` — many-to-one. Members publish here; the Room streams from it.
+- `:from_room` — one-to-many. The Room publishes here; every member streams from it.
+
+Every member also gets a private port named after its random token, plus a port for the user it
+joined as and one for each tag it carries. That's how targeted delivery works without the Room
+tracking connections.
+
+### Sending.
+
+```ruby
+self << { type: "tick" }                            # to :from_room, i.e. everyone
+broadcast({ type: "tick" })                         # same thing
+broadcast({ type: "secret" }, client_port: token)   # one port
+broadcast({ type: "hi" }, user: "user_42")          # every port that user joined from
+broadcast({ type: "tools" }, tag: :admin)           # every port carrying the tag
+reply({ type: "pong" })                             # the port whose message you're handling
+message_origin << { type: "pong" }                  # the same, spelled differently
+```
+
+Combining a target with a tag makes the tag a filter, not a second audience.
+`broadcast(msg, user: "user_42", tag: :admin)` reaches that user only if one of their ports is
+tagged `admin`, and sends nothing otherwise.
+
+### Scoping.
+
+`with_port_scope` sets an ambient target so nested code doesn't have to pass it around:
+
+```ruby
+with_port_scope(tag: :admin) do
+  broadcast({ type: "diagnostics", data: expensive_report })
+end
+```
+
+Scopes merge when nested. `without_port_scope` clears them. `with_port_scope!` skips the block
+entirely when nothing matches, which is the cheap way to avoid building a payload nobody will
+receive. The block form of `reply` does the same for a single port:
+
+```ruby
+reply do
+  broadcast({ type: "a" })
+  broadcast({ type: "b" })
+end
+```
+
+### Custom ports.
+
+Ports aren't limited to the built-ins. Open your own for a side channel:
+
+```ruby
+ports[:telemetry] << { fps: 60 }
+
+stream_port(:control) do |message|
+  logger.info "control: #{message.inspect}"
+end
+```
+
+Ports opened with `stream_port` close automatically at shutdown.
+
+### Port liveness.
+
+Every message a member sends counts as activity. A member that has been silent for 15 seconds
+(`RoomMember::PING_INTERVAL`) pings instead, so the room hears from a live member at least every
+30 seconds. A port that goes quiet for 45 seconds (`PortManagement::PORT_TIMEOUT`) is dropped,
+and `on_port_disconnected` runs for it with `message_origin` still set, so cleanup can tell
+which port went away. Under AnyCable the channel's timer never runs and the browser sends the
+ping instead; see [Using AnyCable](#using-anycable).
+
+```ruby
+on_port_connected    { logger.info "port #{message_origin.token} joined" }
+on_port_disconnected { logger.info "port #{message_origin.token} gone" }
+```
+
+`connected_clients` returns the live `PortClient` objects. Each one carries a `token`, its `tags`,
+its `user`, and any extra metadata the member passed in. Read and write metadata with `[]` and
+`[]=`.
+
+## Users.
+
+Members can join *as* a user. CableRoom then collapses that user's ports into a single identity,
+so a person with three browser tabs joins once and leaves once.
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  on_user_joined { broadcast({ type: "joined", user: message_origin.user }) }
+  on_user_left   { broadcast({ type: "left",   user: message_origin.user }) }
+end
+```
+
+`on_user_joined` fires on the first port for that user; `on_user_left` fires when the last one
+goes away. `connected_users` lists them, and `all_user_tags(user)` unions the tags across every
+port that user is connected from.
+
+A `RoomMember` channel that defines `current_user` passes it automatically. Pass `as:` to override
+it, or `as: nil` for an anonymous port. The value is serialized with ActiveJob's argument
+serializer, so an ActiveRecord object survives the trip and arrives as the same record.
+
+## Authorization.
+
+Two layers, and they compose. Use guards for anything that depends on the message; use tag
+policies for anything that depends on who's asking.
+
+### Guards.
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  # Block, symbol, or proc. Return false to drop the message.
+  authorize_inbound { |message| message["body"].to_s.length < 1_000 }
+  authorize_inbound :quiz_running?, only: [:answer, :skip]
+  authorize_inbound :not_locked?, except: :leave
+
+  protected
+
+  # Zero-arity guards read `message` themselves
+  def quiz_running? = @state == :running
+  def not_locked?(msg) = !@locked
+end
+```
+
+A dropped message logs a warning and never reaches a handler.
+
+### Tag policies.
+
+Members join with tags (`join_room MyRoom, key, tags: [:admin]`). Policies then say which tags
+may trigger which handlers.
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  inbound_tag_policy do
+    deny  :muted, :chat          # muted members can't chat...
+    allow :*,     :chat          # ...but everyone else can
+    allow :admin, [:kick, :ban]  # admins get the moderation verbs
+  end
+end
+```
+
+Two rules govern how this resolves:
+
+1. **Declaring any policy flips the default to deny.** Before you write one, everything is
+   allowed. After, only what you allow is allowed. The built-in connection and user messages stay
+   permitted, so members can still join and leave.
+2. **Highest priority wins.** Rules default to priority 10. Pass `priority:` to layer a base
+   policy under, or an override over, another. `inbound_tag_policy(priority: -10)` adds
+   permissions without flipping the default.
+
+Within a priority, the first matching rule decides, and rules match in declaration order. That
+means a `deny` exception has to come **before** the broad `allow` it carves out of — write
+`allow :*, :chat` first and it swallows every member, muted ones included. When the ordering
+matters a lot, give the two rules different priorities instead of relying on where they sit in
+the block:
+
+```ruby
+inbound_tag_policy(priority: 20) { deny :muted, :chat }
+inbound_tag_policy(priority: 10) { allow :*, :chat }
+```
+
+Group related handlers behind one name with `define_tag_alias`. A rule written against the alias
+covers everything it implies:
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  define_tag_alias :moderation, [:kick, :ban, :mute]
+
+  inbound_tag_policy do
+    allow :admin, :moderation
+  end
+end
+```
+
+Aliases are per Room class and inherited by subclasses, so one Room's vocabulary can't change how
+another Room reads its policies.
+
+### System message types.
+
+Some message types are the framework's, not the client's. Members can't forge them:
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  system_message_types :score_awarded, :quiz_finished
+end
+```
+
+Attempts to send one from a member are dropped with a warning at the sender. `port_connected`,
+`port_disconnected`, `port_ping`, `user_joined`, and `user_left` are already protected.
+
+## Reaping and the watchdog.
+
+Rooms hold memory and a Redis lock, so they need to know when to quit. `reap_when` declares a
+check that runs on a timer:
+
+```ruby
+class MyRoom < CableRoom::Room::Base
+  # Idle for 30 seconds with nobody connected -> shut down
+  reap_when { connected_clients.empty? }
+
+  # Tighter window, and named so the shutdown reason says which check fired
+  reap_when(key: :abandoned, grace: 5.minutes, interval: 30.seconds) do
+    connected_users.empty?
+  end
+
+  # Return :reap to skip the grace period entirely
+  reap_when(grace: 1.hour) { @cancelled ? :reap : false }
+end
+```
+
+- **Truthy** starts the grace clock. Once the condition has held for `grace:` (default 30
+  seconds), the Room shuts down.
+- **Falsey** resets the clock and pings the watchdog.
+- **`:reap`** shuts down now, whatever the grace period says.
+
+Declare as many checks as you like; each gets its own timer and its own grace clock. Call
+`check_reapers_now!` to run them all immediately instead of waiting for the next tick.
+
+### The watchdog.
+
+Separately, every Room is supervised. Every five seconds its channel extends the Redis lock and
+confirms the Room has pinged its watchdog within the last 15 seconds
+(`Room::Base::WATCH_DOG_INTERVAL`). Lose the lock and the Room stops, since another process may
+now own the key. Miss the ping and it shuts down as wedged.
+
+**Reaper checks are what ping the watchdog.** A Room that declares no `reap_when` has nothing
+pinging it, so the watchdog will shut it down about 15 seconds after startup. Every long-lived
+Room needs at least one `reap_when` — or its own timer calling `ping_watchdog` — to stay up.
+
+## Joining a Room from a channel.
+
+### The proxy shortcut.
+
+When the client only needs a pipe to the Room, `RoomProxyChannel` is the whole channel:
+
+```ruby
+class QuizChannel < ApplicationCable::Channel
+  include CableRoom::RoomProxyChannel
+
+  subscribe_to_room do
+    join_room QuizRoom, params[:quiz_id], create: true
+  end
+end
+```
+
+It wires up `subscribed`, `receive`, `unsubscribed`, and the `hello` action, and forwards messages
+both ways.
+
+### Full control.
+
+`RoomMember` gives you the membership without the forwarding, so the channel can filter,
+transform, or fan out:
+
+```ruby
+class QuizChannel < ApplicationCable::Channel
+  include CableRoom::RoomMember
+
+  def subscribed
+    @membership = join_room(
+      QuizRoom,
+      params[:quiz_id],
+      create: true,
+      tags: current_user.teacher? ? [:admin] : [:student],
+      extra: { device: params[:device] },
+      on_joined:      ->(m) { transmit(type: "ready") },
+      on_message:     ->(msg) { transmit(msg) if msg["type"] != "internal" },
+      on_room_closed: ->(m) { transmit(type: "over") },
+      on_left:        ->(m) { logger.info "left #{m.key}" }
+    )
+  end
+
+  def answer(data)
+    @membership << { type: "answer", choice: data["choice"] }
+  end
+
+  def unsubscribed
+    @membership&.leave!
+  end
+end
+```
+
+`join_room` options:
+
+| Option                          | Meaning                                                              |
+| ------------------------------- | -------------------------------------------------------------------- |
+| `create:`                       | Provision the Room if it isn't running. Defaults to `false`.          |
+| `as:`                           | The user identity. Defaults to `current_user` when the channel has one. |
+| `tags:`                         | Tags this port carries, for policies and targeted broadcasts.         |
+| `extra:`                        | Extra metadata, readable on the Room's `PortClient`.                  |
+| `forward:`                      | Pipe every Room message straight to the websocket.                    |
+| `on_joined:`                    | The Room acknowledged this port.                                      |
+| `on_message:`                   | Any message from the Room.                                            |
+| `on_room_opened:`               | The Room opened while we were connecting. Not guaranteed.             |
+| `on_room_closed:`               | The Room closed while we were connected. Not guaranteed.              |
+| `on_left:`                      | This membership ended.                                                |
+
+The returned membership responds to `<<`, `connected?`, `accepts_input?`, `hello!`,
+`hello_received?`, `left?`, `key`, `ping!`, `leave!`, and `rejoin!`.
+
+Under AnyCable an instance variable set in `subscribed` is gone by the next call, because
+anycable-rails builds a new channel object for every one (see [Using AnyCable](#using-anycable)).
+Read `room_memberships` in your actions instead of `@membership`; it holds the memberships
+`join_room` created, rebuilt from the channel state when needed.
+
+With `create: true`, the membership doesn't start the Room itself. It publishes a provision
+request on the bus, and one of the Rooms hosts starts the Room (see
+[Provisioning](#provisioning)). The request goes out at join and again on every ping until the
+Room acknowledges the port, so a lost request costs at most one ping interval, and if the Room's
+host process dies the next ping from any member brings it back somewhere else.
+
+### The hello handshake.
+
+A membership doesn't announce itself to the Room when the channel subscribes. Stream subscriptions
+are asynchronous, so the Room's acknowledgement could land on a stream nobody is listening to yet,
+and the member would stay deaf on the inbound side. Instead, the client performs `hello` once
+ActionCable confirms the subscription (`connected()` in the JS client), and the membership sends
+`port_connected` then. `RoomMember` defines `hello` as a public channel action, so both
+`RoomProxyChannel` and `RoomMember` channels like the `QuizChannel` above accept
+`perform("hello")` with no extra wiring. A channel that learns the client is ready some other way
+can call `hello_room_memberships` itself.
+
+If the announcement or the acknowledgement is lost, or the Room isn't running yet, the membership
+re-announces on every ping until the Room acknowledges it, so a lost message costs at most one
+ping interval. That only starts after `hello`. `hello_received.cable_room` fires each time a
+membership hears it. Under AnyCable the server never sees the acknowledgement, so the browser
+does the retrying; see [Using AnyCable](#using-anycable).
+
+**Breaking change in 1.0.** Clients must send `hello`, and there is no fallback. A client that
+only subscribes still receives broadcasts on the shared stream, but the Room never sees it and
+everything it sends is dropped. Browser tabs open across the deploy speak the old handshake and
+need a reload.
+
+### From outside a channel.
+
+```ruby
+QuizRoom.ensure("quiz_9")                                        # => true if this process now runs it
+QuizRoom.send_message("quiz_9", { type: "extend", by: 60 })      # publish to :to_room over the bus
+QuizRoom.room_port_key("quiz_9", :from_room)                     # the raw stream name members listen on
+QuizRoom.inbound_channel("quiz_9")                               # the raw bus channel the Room listens on
+```
+
+`ensure` only works in a process that hosts Rooms. In `remote` mode that's the `cable_room server`
+process; a web process raises `CableRoom::Host::NotHosting` (see [Remote rooms](#remote-rooms)).
+
+## Background work.
+
+A Room is single-threaded on purpose. Slow work belongs off its thread:
+
+```ruby
+def on_export(msg)
+  token = message_origin.token   # capture before leaving the Room's thread
+
+  async do
+    report = build_expensive_report
+
+    on_room_thread do
+      broadcast({ type: "export_ready", url: report.url }, client_port: token)
+    end
+  end
+end
+```
+
+`async` borrows a thread from the pool shared by every Room in the process and runs concurrently
+with the Room, so **the block must not touch Room state.** Capture what it needs first. Inside
+it, `message` is nil, and `message_origin` and `reply` point at whatever the Room is handling
+*now* rather than what it was handling when you called `async`.
+
+`on_room_thread` queues work back onto the Room's thread, where state is safe again. Prefer
+handing results back that way over blocking on `async` work, since a blocked Room thread can
+starve its neighbours.
+
+## Instrumentation and errors.
+
+Rooms swallow exceptions so one bad message can't take the Room down. That makes the error
+handler the only place you'll hear about it:
+
+```ruby
+CableRoom.error_handler = ->(error, context) do
+  Sentry.capture_exception(error, extra: context)
+end
+```
+
+For an error inside a Room the context has `room`, `room_class`, `room_key`, and `runner` (the
+`Host::Runner` driving it; 0.6 called this key `channel`). Errors from the other moving parts
+name themselves instead: `bus`, `host`, `placement`, `migration`, or `adoption`, with
+`room_class` and `room_key` where they apply. An `error.cable_room` notification fires either way.
+
+ActiveSupport notifications, every one the gem emits:
+
+| Event                            | Fires                                | Payload                    |
+| -------------------------------- | ------------------------------------ | -------------------------- |
+| `room_opened.cable_room`         | Around a Room's startup              | `room`                     |
+| `room_restored.cable_room`       | Around a restore, in place of `room_opened` | `room`              |
+| `room_closed.cable_room`         | Around a Room's shutdown             | `room`, `reason`           |
+| `room_snapshotted.cable_room`    | When a frozen Room is snapshotted    | `room`                     |
+| `room_migrated.cable_room`       | On the old host, once a peer has the Room | `room`, `room_class`, `room_key`, `duration`, `relayed_messages`, `to_host`, `from_host`, `reason` |
+| `host_draining.cable_room`       | Around a whole `drain!`              | `host`, `rooms`, `reason`; on finish also `migrated`, `closed` |
+| `provision_requested.cable_room` | Member side, each `provision` request | `membership`, `room_class`, `room_key`, `channel`, `request` |
+| `provision_claimed.cable_room`   | Host side, each lock attempt         | `host`, `room_class`, `room_key`, `delay`, `open_rooms`, `request`; on finish also `handoff`, `claimed` |
+| `hello_received.cable_room`      | Member side, each `hello`            | `membership`, `room_class`, `room_key`, `channel` |
+| `message_received.cable_room`    | Each inbound message a Room handles  | `room`, `message`          |
+| `port_connected.cable_room`      | A port joins                         | `room`, `message`          |
+| `port_disconnected.cable_room`   | A port leaves or times out           | `room`, `reason`, `message` |
+| `user_joined.cable_room`         | A user's first port joins            | `room`, `user`             |
+| `user_left.cable_room`           | A user's last port leaves            | `room`, `user`             |
+| `error.cable_room`               | Any reported error                   | `error`, plus context      |
+
+`port_disconnected` reports a `reason` of `:left` for a clean departure and `:timeout` for a port
+that stopped pinging (no `message` in that case). `room_closed` always has a `reason`: the string
+passed to `shutdown!`, the reaper that fired, `"Server shutting down"`, `"Watchdog timeout"`, or
+the signal that started a drain.
+
+Every Room also gets a tagged logger, so `logger.info` from inside a Room is prefixed with the
+Room class and a short UUID. That UUID is how you follow one instance through the logs.
+
+## Configuration.
+
+### Deployment knobs.
+
+CableRoom works with no setup. Rooms run inside the web process and broadcast through
+ActionCable. To change that, add an initializer:
+
+```ruby
+CableRoom.configure do |c|
+  c.room_host   = :inline        # :inline | :remote
+  c.broadcaster = :action_cable  # :action_cable | :anycable
+  c.provision_delay_ms = 20
+  c.drain_timeout   = 10.minutes
+  c.handoff_timeout = 10.seconds
+end
+```
+
+The env vars `CABLE_ROOM_HOST` and `CABLE_ROOM_BROADCASTER` override `room_host` and
+`broadcaster`, even when the block sets them. An unknown value raises at boot with the list
+of valid options. Read the current settings with `CableRoom.config`.
+
+### Deployment modes.
+
+The two knobs combine freely. Pick where rooms run and what serves the websockets:
+
+| `room_host` | `broadcaster`  | Where rooms run      | Sockets served by      | Notes                                   |
+| ----------- | -------------- | -------------------- | ---------------------- | --------------------------------------- |
+| `inline`    | `action_cable` | web process (thread) | Passenger + ActionCable | The default. Today's behavior.          |
+| `remote`    | `action_cable` | rooms pool           | Passenger + ActionCable | Valid. Covered by the remote-host integration spec. Measure this step first. |
+| `remote`    | `anycable`     | rooms pool           | anycable-go + RPC       | The target for large installs.          |
+| `inline`    | `anycable`     | web process          | anycable-go + RPC       | Valid. Suits small installs.            |
+
+`broadcaster` only changes how a Room pushes messages *out* to members. Stream names stay the
+same in both modes, so a member on ActionCable and a member on anycable-go would see the same
+traffic — but a Room publishes to one broadcaster, so members on the other stack hear nothing.
+Running both stacks at once is covered in [Dual-stack](#dual-stack-actioncable-and-anycable-side-by-side).
+
+### Remote rooms.
+
+With `room_host = :remote`, a web process never hosts a Room. Channels still join, say `hello`,
+send on the bus, and receive on their streams exactly as in `inline`; the only difference is where
+the Room lives. Two guards keep it that way:
+
+- `join_room(..., create: true)` starts nothing in the web process. It publishes a provision
+  request, and a `cable_room server` process starts the Room (see [Provisioning](#provisioning)).
+- `CableRoom::Host.instance` raises `CableRoom::Host::NotHosting` in a web process, so
+  `MyRoom.ensure(key)` (and anything else that would start a Room) fails loudly instead of
+  quietly hosting a Room in the web tier. `CableRoom::Host.current` answers `nil` there, and
+  `CableRoom::Room.locally_open_rooms` is empty.
+
+Rooms run in a separate pool of processes started with the gem's command:
+
+```sh
+CABLE_ROOM_HOST=remote bundle exec cable_room server
+```
+
+`cable_room server` boots the Rails app in the current directory (its `config/environment.rb`),
+refuses to run unless `room_host` is `remote`, starts a Host, and runs until SIGTERM or SIGINT.
+On exit it asks every Room to finish its queued work and shut down, which sends `room_closed` to
+members. Pass `--require PATH` to boot from another app directory or a boot file.
+
+`--workers N` sets how many processes host Rooms. It defaults to the machine's core count. With
+`--workers 1` the command hosts Rooms in its own process. With more, it boots the app once and
+then forks `N` workers, each with its own Host, bus subscription, and Redis connections; the
+parent hosts nothing and only supervises. A worker that dies is replaced (with a growing delay
+if it keeps dying at boot, so a broken app can't fork-bomb the box). SIGTERM or SIGINT to the
+parent is relayed to every worker, and the parent waits for all of them before it exits `0`,
+so wrap it in the container's own deadline (`timeout -k 2m 24h bundle exec cable_room server`).
+Each worker tags what its Rooms log (the ActionCable logger) with `cable_room worker N` and shows
+up in `ps` as `cable_room server: worker N`.
+
+The rooms host exposes its load as `CableRoom::Host.current.open_ports`, the number of member
+ports attached across every Room it runs. Publish that as a gauge to scale the pool on.
+
+### Provisioning.
+
+A `create: true` join publishes a `provision` request on the bus (`cr:provision`) naming the
+Room class and key. Every host hears it, in `inline` and `remote` alike: in `inline` that's the
+web process's own host, in `remote` it's every `cable_room server`. Each host waits a delay
+proportional to how many Rooms it already runs, then races for the Room's Redis lock. Exactly one
+wins and starts the Room, and it's usually the least loaded one; the others find the lock held and
+do nothing. A host that is draining never claims. The member keeps re-publishing the request on
+every ping until the Room acknowledges it, so a lost request costs at most one ping interval, and
+a member that joined before the Room existed completes its join as soon as the Room comes up.
+
+The delay is `provision_delay_ms × (open_rooms + jitter)`, with `jitter` a random number in
+`0..1` and `provision_delay_ms` defaulting to 20. A host running nothing waits at most one
+`provision_delay_ms`; a host with more Rooms always waits longer than one with fewer, so the
+jitter only breaks ties. `provision_requested.cable_room` fires on the member side for each request
+and `provision_claimed.cable_room` on the host side for each lock attempt (with `room_class`,
+`room_key`, `delay`, `open_rooms`, and `claimed`).
+
+`MyRoom.ensure(key)` still works inside a process that hosts Rooms, for starting a Room from a
+console or an initializer without any member asking.
+
+### Using AnyCable.
+
+`broadcaster = :anycable` sends room broadcasts through `AnyCable.broadcast`, so anycable-go
+fans them out to sockets. The gem doesn't depend on AnyCable; add it yourself:
+
+```ruby
+gem "anycable-rails"
+```
+
+Boot with `:anycable` set and the gem missing, and CableRoom raises at startup naming the gem to
+add. AnyCable reads its own settings from the environment. Point it at the same Redis as
+anycable-go:
+
+```sh
+export ANYCABLE_BROADCAST_ADAPTER=redis
+export ANYCABLE_REDIS_URL=redis://localhost:6379/1
+```
+
+Room broadcasts are JSON-encoded with the same coder ActionCable uses, so a channel decodes them
+the same way whichever broadcaster sent them.
+
+#### What AnyCable buys, and what it doesn't.
+
+AnyCable moves two things out of Ruby: holding sockets, and fanning a broadcast out to them.
+It does not move the inbound path. Know which side of that line your traffic is on before you
+adopt it.
+
+**Outbound gets cheap.** Under ActionCable a Room broadcast to *N* members is *N* Redis
+deliveries, each decoded, re-encoded, and written by a Ruby worker thread; plus ActionCable's
+own 3-second heartbeat to every socket, also written by Ruby. Under AnyCable the Room publishes
+once and anycable-go writes *N* frames; heartbeats never touch Ruby. In a quiz deployment
+measured in August 2026 a 30-student room produced ~250 inbound messages, ~1,400 outbound socket
+deliveries, and ~700 heartbeats over its life — Ruby's share fell from all ~2,400 to the ~250
+inbound plus a few dozen publishes.
+
+**Inbound does not get cheaper.** Every client message is an RPC round trip from anycable-go to
+Ruby. On each one anycable-rails rebuilds the connection from its serialized identifiers,
+builds a new channel object, restores channel state, runs `receive`, and serializes state back.
+The socket read and JSON decode leave Ruby; the object rebuild and state round-trip arrive; the
+Room still processes the message once, as before. Per inbound message it is a wash, plus roughly
+half a millisecond to a millisecond of RPC latency on the reply. A protocol that is mostly
+inbound — cursor positions, keystroke sync, anything chatty from the client — gains little from
+AnyCable and should batch on the client instead. (AnyCable's "whispers" carry client-to-client
+messages without Ruby, but a whisper never reaches a Room.)
+
+**Two things make inbound worse than a wash if you let them:**
+
+- **Identifiers are deserialized on every RPC.** `identified_by :current_user` holding a record
+  is serialized as a GlobalID and located again on each call — a database read per inbound
+  message. Identify the connection by a primitive (a user id, a session key) and resolve the
+  record lazily in the channel or the Room. Room→member scoping by user (`notify: user`,
+  `broadcast(user: ...)`) works on whatever `as:` you pass to `join_room`; pass the same primitive.
+- **The gRPC server is one Ruby process.** `bundle exec anycable` serves every RPC from one
+  interpreter with a thread pool (30 threads by default; anycable-go's concurrency limit defaults
+  to 28), so a receive-heavy load hits one GVL. HTTP RPC mode (`--rpc_host http://...`) sends each
+  command to the Rails app as a short HTTP request, which an app server spreads across its process
+  pool; prefer it when inbound volume matters, and protect the endpoint with the bearer token.
+
+Everything else AnyCable changes is structural rather than per-message: sockets live in Go, so
+socket memory, `worker_connections`-style limits, and app-server routing rules for long-lived
+connections stop being Ruby's problem.
+
+#### What changes for the channel.
+
+anycable-rails builds a fresh channel object for every call the socket makes (subscribe, each
+message, unsubscribe, disconnect) and never re-runs `subscribed`. Three things follow:
+
+- **Memberships live in the channel state.** `join_room` records each membership's identity
+  (token, Room, key, tags, `extra`, `create`, whether `hello` happened) with anycable-rails'
+  `state_attr_accessor`, and `hello`, `receive`, `ping`, and `unsubscribed` rebuild it from there
+  (`CableRoom::MembershipStore`). A rebuilt membership keeps the token subscribe created, opens
+  no streams (anycable-go still holds them), and announces nothing until `hello`. Under plain
+  ActionCable the channel object lives for the socket and none of this runs.
+- **No `on_*` callbacks fire.** Room→member traffic goes anycable-go → socket and never passes
+  through this process, so `on_joined`, `on_message`, `on_room_opened`, and `on_room_closed` have
+  nothing to fire on, and a rebuilt membership carries no procs, so `on_left` doesn't either.
+  `RoomProxyChannel` needs none of them: the forwarding it does under ActionCable is what
+  anycable-go does natively. `connected?` stays `false` on the server for the same reason;
+  input is forwarded once `hello` has gone out (`accepts_input?`). The `port_connected` from
+  `hello` and the input travel the same Bus channel from the same process, so the Room sees them
+  in that order.
+- **Channel timers don't run.** `periodically` is disabled by anycable-rails, so the member-side
+  ping and re-announce never happen on their own. The browser has to drive them.
+- **Unsupported `join_room` features raise.** `forward: false`, any `on_*:` callback, and a
+  preconfigure block all need a message to pass through this process, so on an AnyCable-backed
+  channel `join_room` raises `CableRoom::AnyCableUnsupported` at subscribe time naming the feature.
+  `RoomProxyChannel`'s default join (`forward: true`, no callbacks) is the supported shape.
+
+#### What the browser must send.
+
+1. Subscribe, and wait for `confirm_subscription`.
+2. `perform("hello")`. Expect a `port_acknowledged` message within a few seconds. If it doesn't
+   arrive, `perform("hello")` again: the server can't see that the acknowledgement was lost, so
+   the retry that `ping!` does under ActionCable is the browser's job here. `port_connected` is
+   idempotent Room-side, so a repeat is harmless.
+3. `perform("ping")` every 15 seconds (`RoomMember::PING_INTERVAL`) for as long as the
+   subscription is open. Each ping becomes a `port_ping` for the membership, so the Room keeps the
+   port past `PORT_TIMEOUT`, and retries provisioning for a `create: true` join whose Room went
+   away. A browser that stops pinging loses its port after 45 seconds.
+4. On `room_closed`, leave: stop pinging and sending, and unsubscribe the channel. That is what
+   the membership does by itself under ActionCable (`leave!`, which sends `port_disconnected` —
+   the same thing unsubscribing does here). Under AnyCable the server never sees the broadcast,
+   so a tab that keeps pinging would keep the port alive and, with `create: true`, re-provision
+   the Room on its next ping. To rejoin, resubscribe — as under ActionCable.
+
+`KILL` is an administrative break-glass message. Under ActionCable the membership leaves when it
+sees one; under AnyCable the bare string reaches the socket and nothing else happens, which is
+fine — use `room_closed` (`shutdown!`) to end a Room for its members.
+
+Unsubscribing or closing the socket sends `port_disconnected` as before: anycable-go turns both
+into an RPC call that rebuilds the channel with its state. Both actions exist under plain
+ActionCable too, where `ping` is harmless and unnecessary.
+
+#### Dual-stack: ActionCable and AnyCable side by side.
+
+You may want some channels on AnyCable and others on ActionCable — high-fan-out Rooms on
+anycable-go, a channel that still needs `on_*` callbacks or `forward: false` on ActionCable, or a
+migration where the two overlap. Half of that works today and half needs one addition.
+
+**What already works: the member side is decided per connection, not per process.** The gem
+checks `connection.anycabled?` on the channel it is given. A channel reached through anycable-go
+gets the AnyCable behavior above (state store, `hello`/`ping` actions, no callbacks); the same
+channel class reached through a Passenger-served ActionCable socket gets the classic behavior.
+Both can run in one Rails process at once, provided both socket servers are up and routed:
+
+```nginx
+location /cable         { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1;
+                          proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }
+location /cable-classic { passenger_app_group_name myapp_action_cable;
+                          passenger_force_max_concurrent_requests_per_process 0; }
+```
+
+Which stack a channel uses is then the browser's choice of consumer, per feature:
+
+```js
+const fast    = createConsumer("/cable")          // anycable-go
+const classic = createConsumer("/cable-classic")  // ActionCable
+fast.subscriptions.create({ channel: "QuizChannel", ... }, { connected() { this.perform("hello") }, ... })
+classic.subscriptions.create({ channel: "LegacyDashboardChannel" }, { ... })
+```
+
+`config/cable.yml` keeps its `redis` adapter for the classic sockets; anycable-go and
+`AnyCable.broadcast` use `ANYCABLE_*`. Nothing in the gem needs to know which channel classes go
+where. If you want to enforce it server-side, a channel can `reject` in `subscribed` when
+`anycable_channel?` disagrees with where it belongs.
+
+**What does not work yet: a Room broadcasts to one stack.** `broadcaster` is process-wide and
+chooses *either* `ActionCable.server.broadcast` *or* `AnyCable.broadcast`, so with
+`broadcaster = :anycable` a Room's messages reach anycable-go sockets only, and members joined
+through `/cable-classic` hear nothing (their `hello` and input still reach the Room; the Room's
+replies don't come back). Dual-stack therefore needs a `:both` broadcaster that publishes every
+Room message through both adapters. It is one class and one allowed value in
+`CableRoom::Config::BROADCASTERS`; the cost is a second publish per Room broadcast (per fan-out,
+not per socket — the ActionCable adapter then does the classic *N* deliveries for the classic
+members, as it does today). Until it exists, run one stack at a time, or make sure every member
+of a given Room joins through the same stack.
+
+Rooms themselves never know which stack a member is on: `port_connected`, `port_ping`, input,
+and `port_disconnected` arrive on the same Bus channel from either path, and stream names are
+identical.
+
+### Redis.
+
+Three things need a Redis, and each reads its own variables. They can all point at one server
+to start; splitting them later is a config change.
+
+| Variable                                        | Read by                | Purpose                                                  |
+| ----------------------------------------------- | ---------------------- | -------------------------------------------------------- |
+| `CABLEROOM_REDIS_URL`                           | cable_room             | The bus (member→room traffic, provisioning, handoff) and the Room locks. Must be reachable from every web process and every rooms host. |
+| `REDIS_URL`                                     | ActionCable's adapter  | Room→member streams under `broadcaster = :action_cable` (`config/cable.yml` decides; this is the usual name). |
+| `ANYCABLE_BROADCAST_ADAPTER` / `ANYCABLE_REDIS_URL` | anycable-go and `AnyCable.broadcast` | Room→member streams under `broadcaster = :anycable`. Set the adapter to `redis` and point both the Go process and the Rails process at the same URL. |
+
+CableRoom keeps its own pool for the bus and the locks, separate from the ActionCable adapter's:
+
+| Variable                     | Purpose                                                  |
+| ---------------------------- | -------------------------------------------------------- |
+| `CABLEROOM_REDIS_URL`        | The connection URL.                                       |
+| `CABLEROOM_REDIS_PROVIDER`   | Name of another variable holding the URL.                 |
+| `CABLEROOM_REDIS_POOL_SIZE`  | Pool size. Defaults to `RAILS_MAX_THREADS`, then five.    |
+
+Without a prefixed variable it falls back to `REDIS_PROVIDER` and `REDIS_URL`, so a single-Redis
+app needs no CableRoom-specific configuration at all. Reach the pool directly with
+`CableRoom.redis { |conn| ... }`, the lock manager with `CableRoom.lock_manager`, and the bus with
+`CableRoom.bus`.
+
+Room threads come from a pool sized by ActionCable's own `worker_pool_size`.
+
+Timings live in constants:
+
+| Constant                          | Default        | What it controls                        |
+| --------------------------------- | -------------- | --------------------------------------- |
+| `Room::Base::LOCK_DURATION`       | `15.seconds`   | Redis lock TTL, extended on every beat.  |
+| `Room::Base::WATCH_DOG_INTERVAL`  | `15.seconds`   | How stale a watchdog ping may get.       |
+| `PortManagement::PORT_TIMEOUT`    | `45.seconds`   | How long a silent port survives.         |
+| `Host::BEAT_INTERVAL`             | `5.seconds`    | Lock extension and watchdog sweep.       |
+
+The first two are read as `self::CONSTANT`, so a Room subclass can redefine them. The other two
+are module constants that apply process-wide.
+
+### Shutdown.
+
+On process exit, CableRoom asks every local Room to shut down gracefully and waits up to 15
+seconds for them to drain. It also hooks ActionCable's `restart`, so a code reload in development
+stops Rooms instead of orphaning their locks. `cable_room server` with no Rooms open does the
+same when it gets SIGTERM or SIGINT; with Rooms open it migrates them first (next section).
+
+### Planned shutdown and migration.
+
+A `cable_room server` that gets SIGTERM or SIGINT with Rooms open doesn't close them. It hands
+them to its peers, one Redis round trip at a time, and members never notice: their streams stay
+open, their messages keep arriving in order, and the Room's broadcasts resume from the new host.
+The same thing is available from code as `CableRoom::Host.current.drain!(reason: "...")`.
+
+What moves is what the gem owns — every port with its token, tags, user, and last-seen time, the
+user map, and each reaper's deadline — plus whatever the Room returns from `snapshot_state`
+(see [Migration hooks](#migration-hooks)). A Room without `snapshot_state` still moves; it runs
+`startup` again on the new host to rebuild its own state.
+
+Per Room, in order:
+
+1. **Freeze.** The Room finishes what it has queued and stops. Its inbound subscription stays up;
+   from here on every message a member sends is pushed to a Redis list instead of handled.
+2. **Snapshot.** The gem takes the snapshot. A Room whose `snapshot_state` isn't JSON, or raises,
+   can't move: it closes with `room_closed`, the error is reported, and the drain moves on.
+3. **Offer.** The snapshot is parked in Redis with a 60 second TTL, the Room's lock is released,
+   and a provision request flagged `handoff` goes out. Every peer hears it and races for the lock
+   the same load-weighted way it does for a new Room; the draining host never claims.
+4. **Adopt.** The winner rebuilds the Room from the snapshot, replays the relayed messages, and
+   takes over the inbound subscription. A short exchange of markers between the two hosts decides,
+   message by message, which of them runs each one, so nothing is lost, doubled, or reordered.
+5. **Let go.** The old host drops its copy without a word to the members and reports
+   `room_migrated.cable_room`.
+
+Nobody adopts within `handoff_timeout` (default 10 seconds) — a fleet of one, say — and the Room
+takes its lock back and closes with `room_closed`; members re-provision on their next ping and get
+a fresh Room somewhere. Rooms go oldest first, four at a time. When `drain_timeout` (default 10
+minutes) passes with Rooms still waiting, all of them are offered at once, so the drain ends within
+about one more `handoff_timeout` whatever the fleet does. Then the host shuts down.
+
+Both timeouts are config knobs (`c.handoff_timeout`, `c.drain_timeout`). To know when a drain has
+finished — to complete an ASG termination lifecycle action, say — register a callback:
+
+```ruby
+CableRoom::Host.after_drain do |host, result|
+  result.migrated   # the Rooms that moved (CableRoom::Migration objects)
+  result.closed     # the Rooms that closed instead
+  result.duration   # seconds
+  Aws::AutoScaling::Client.new.complete_lifecycle_action(...)
+end
+```
+
+The container has to give the process that long. With CodeDeploy, set the `ApplicationStop` hook
+timeout to `drain_timeout` plus two minutes; on an ASG, put a termination lifecycle hook in front of
+the instance with a heartbeat timeout at least as long, and complete it from `after_drain`. The
+`--workers N` supervisor relays the signal to every worker and waits for all of them, without a
+deadline of its own.
+
+In `inline` mode the gem doesn't migrate on exit: there's no fleet of Room hosts by design, and a
+web process that exits closes its Rooms the way it always has. An app that runs several inline
+processes can still call `drain!` from its own signal handling; other inline processes will adopt.
+
+## Introspection.
+
+```ruby
+CableRoom::Room.locally_open_rooms        # every Room running in this process
+QuizRoom.locally_running_instances       # just the QuizRooms
+CableRoom::Host.current                   # this process's Host, or nil if it hosts no Rooms
+CableRoom::Host.current&.open_ports       # member ports attached across every local Room
+```
+
+All of these are process-local. There's no cluster-wide registry — the Redis lock is the only
+source of truth about who owns a key.
+
+## Subclassing.
+
+Room classes build a private `PortClient` for each subclass, chained to the parent's.
+Periodic timers, callbacks, policies, and tag aliases all inherit correctly through
+however many levels you need:
+
+```ruby
+class BaseGameRoom < CableRoom::Room::Base
+  periodically :tick, every: 1.second
+  reap_when { connected_users.empty? }
+end
+
+class TriviaRoom < BaseGameRoom
+  # keeps tick and the reaper, adds its own
+  periodically :rotate_question, every: 30.seconds
+end
+```
+
+Note that a Room's pubsub keys derive from its class name, so anonymous Room classes won't work.
+
+## Upgrading from 0.6 to 1.0.
+
+1.0 is one gem release, and an app flips every knob in one deploy. Room definitions don't change.
+The channel contract and the deployment do. `CHANGELOG.md` lists every breaking change; this is
+the order to work through them.
+
+### Before the deploy.
+
+1. **Send `hello` from every client.** Add `connected() { this.perform("hello") }` to each
+   subscription that joins a Room. Nothing is announced until it arrives, and there's no
+   fallback. Shipping it early is harmless: a 0.6 server logs an unknown action and carries on.
+   Shipping it late isn't: a 1.0 server never hears a member that doesn't say it.
+2. **Plan for open tabs.** A browser tab open across the deploy speaks the old handshake. It
+   still receives the shared stream, but the Room never sees it and drops everything it sends.
+   Deploy when few people are in a Room, and have the client show "reload to continue" when it
+   gets `room_closed` after the deploy.
+3. **Find internal names you reached for.** Inside a Room, `@cable_channel` is `@runner`; an
+   error handler reading `context[:channel]` should read `context[:runner]`; `Room#params` is
+   gone; `ChannelTracker::BEAT_INTERVAL` is `Host::BEAT_INTERVAL`. Anything that called
+   `MyRoom.ensure` from a web process needs a look: with `room_host = :remote` it raises
+   `CableRoom::Host::NotHosting`, and a `create: true` join provisions the Room for you.
+4. **Give the bus a Redis every process can reach.** `CABLEROOM_REDIS_URL` (or its `REDIS_URL`
+   fallback) now carries member→room traffic, not just locks. A web process and a rooms host
+   that can't both see it can't talk. Same server as ActionCable is fine.
+5. **Check `PORT_TIMEOUT`.** It's 45 seconds now, not 30. If you tuned client ping intervals or
+   tests around the old number, adjust them.
+6. **Check `room_closed` handling.** The `reason` is never `nil` any more. A client that
+   treated `reason: nil` as "server restart" should look for `"Server shutting down"` or the
+   signal name instead.
+7. **Add `snapshot_state` and `restore_state`** to any Room whose in-memory state should
+   survive a host moving it. Rooms without them still move; they run `startup` again. Do this
+   before turning on `:remote`, or the first drain rebuilds every Room from scratch.
+8. **Decide the deployment mode.** Stay on `inline` + `action_cable` and nothing else changes.
+   For `remote`:
+   - run `bundle exec cable_room server --workers N` on the rooms hosts under a deadline the
+     container owns (`timeout -k 2m 24h ...`);
+   - set `CABLE_ROOM_HOST=remote` on web and rooms hosts alike;
+   - give the container `drain_timeout` plus two minutes to stop, and complete any ASG
+     termination lifecycle hook from `CableRoom::Host.after_drain`;
+   - publish `CableRoom::Host.current.open_ports` as the gauge to scale on.
+
+   For `anycable`, also add `gem "anycable-rails"`, run anycable-go and the `anycable` RPC next
+   to each web process, set `CABLE_ROOM_BROADCASTER=anycable` on web and rooms hosts, set
+   `ANYCABLE_BROADCAST_ADAPTER=redis` and `ANYCABLE_REDIS_URL`, and make the browser drive
+   liveness: `perform("ping")` every 15 seconds and a second `hello` if `port_acknowledged`
+   doesn't arrive (see [What the browser must send](#what-the-browser-must-send)).
+
+### After the deploy.
+
+- Watch `hello_received.cable_room` and `port_connected.cable_room`. Members that subscribe but
+  never `hello` are the old tabs.
+- In `remote`, watch `provision_claimed.cable_room` with `claimed: true` on the rooms hosts and
+  `CableRoom::Room.locally_open_rooms` staying empty on web.
+- Trigger one planned restart of a rooms host and confirm `room_migrated.cable_room` fires for
+  each open Room with `closed: 0` in `host_draining.cable_room`.
+
+### Attribution runbook.
+
+If load or latency regresses after the all-knobs deploy, several things changed at once. Flip
+them back one at a time, in this order, and re-measure after each:
+
+1. **`broadcaster` back to `action_cable`** (`CABLE_ROOM_BROADCASTER=action_cable` on web and
+   rooms hosts, and route `/cable` back to ActionCable; one deploy). Rooms stay remote. If this
+   fixes it, the problem is in the anycable-go path.
+2. **`room_host` back to `inline`** (`CABLE_ROOM_HOST=inline`, one deploy; stop the
+   `cable_room server` pool). If this fixes it, the problem is in the remote hosting path: bus
+   latency, provisioning, or the rooms pool's sizing.
+
+Both are env changes, so neither needs a code change or a gem downgrade. `hello` stays either
+way; it's part of 1.0 in every mode.
+
+## Development.
+
+Rooms need Redis and, for the test suite, Postgres:
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+To run against every supported Rails version:
+
+```sh
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
+The suite has two halves. Unit specs use `RoomHarness#build_room`, which runs a Room against a
+stub channel with no Redis and no pubsub, so logic is testable synchronously. End-to-end specs
+run the async ActionCable adapter and real message delivery, and wait on observable conditions
+with `wait_until` rather than sleeping.
+
+`spec/internal` holds a Combustion app, so `rackup` boots a minimal Rails host if you want to
+poke at Rooms by hand.
+
+### The anycable-go E2E.
+
+`spec/e2e` proves the member protocol on a real wire: a WebSocket client subscribes through
+anycable-go, says `hello`, gets `port_acknowledged`, sends a message and gets the Room's reply,
+pings, and unsubscribes or closes, with anycable-rails rebuilding the channel from its state on
+every call. It's excluded from `bundle exec rspec` and runs only when `CABLE_ROOM_E2E=1` is set.
+CI runs it in its own job. `spec/cable_room/anycable_channel_state_spec.rb` drives the same
+anycable-rails RPC handler in-process, without anycable-go, and is part of the default suite.
+
+Locally it needs Redis and anycable-go. Start anycable-go from Docker, pointed at the RPC server
+the spec starts inside its own process:
+
+```sh
+docker run --rm -p 8080:8080 \
+  -e ANYCABLE_HOST=0.0.0.0 \
+  -e ANYCABLE_RPC_HOST=host.docker.internal:50051 \
+  -e ANYCABLE_BROADCAST_ADAPTER=redis \
+  -e ANYCABLE_REDIS_URL=redis://host.docker.internal:6379/0 \
+  anycable/anycable-go:1.6
+```
+
+Then, in another shell:
+
+```sh
+CABLE_ROOM_E2E=1 ANYCABLE_REDIS_URL=redis://localhost:6379/0 bundle exec rspec spec/e2e
+```
+
+The spec process is the Rails app, the AnyCable RPC server (listening on `0.0.0.0:50051`; set
+`ANYCABLE_RPC_HOST` to change it), and the room host. Set `CABLE_ROOM_E2E_WS_URL` if anycable-go
+isn't at `ws://127.0.0.1:8080/cable`. If anycable-go isn't reachable the spec fails; it never
+skips.
+
+Things that bite on a laptop:
+
+- A Homebrew Redis listens on `127.0.0.1` only, so the container can't reach it. Run one from
+  Docker instead (`docker run -d -p 6380:6379 redis:7.2`) and point both `ANYCABLE_REDIS_URL`s at
+  port 6380.
+- On plain Docker Engine (Linux) add `--add-host host.docker.internal:host-gateway`. Don't on
+  Docker Desktop or Rancher Desktop; there it overrides the built-in name with the VM's bridge
+  address and the RPC becomes unreachable.
+- If something else already has port 8080 (an ssh tunnel, VS Code's port forwarding), publish a
+  different one (`-p 18080:8080`) and set `CABLE_ROOM_E2E_WS_URL=ws://127.0.0.1:18080/cable`. If a
+  tool grabs the loopback port after Docker does, use your machine's LAN address in the URL.
+- Restart anycable-go between runs. Each rspec process stops its RPC on exit, and anycable-go's
+  gRPC client then backs off for minutes; until it reconnects every socket is closed with "Auth
+  Error". CI gets a fresh container per run for the same reason.