cable_room 0.7.0.beta3 → 0.8.0.beta1

data/README.md

@@ -1,1288 +1 @@
 # 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
-
-  before_work { }   # about to run on a Host thread: a message/timer handler, startup, shutdown...
-  after_work  { }   # ...same set, on the way back out
-  around_work { |room, blk| blk.call }   # wrap the whole thing (see Multi-tenancy)
-end
-```
-
-You can also just define `startup` and `shutdown` methods; they run inside the corresponding
-callback chain.
-
-`before_work`/`after_work`/`around_work` wrap *every* piece of Room code that ever runs on a Host
-thread — not just messages, but `startup`, `restore_state`, `snapshot_state`, and `shutdown` too
-(see [Multi-tenancy](#multi-tenancy)). Define them on `MyRoom` for just this Room, or on your own
-shared base Room class for all of them — ordinary callback inheritance, so a subclass's own
-`around_work` nests inside whatever its ancestors already declared.
-
-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; each reaper's deadline; and the Room's tenant, if `join_room` was given one (see
-[Multi-tenancy](#multi-tenancy)). 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`.                  |
-| `tenant:`                       | This Room's tenant, for a multi-tenant app. Defaults to the ambient tenant right here (see [Multi-tenancy](#multi-tenancy)). |
-| `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.
-
-### Multi-tenancy.
-
-A Room's own work runs on its Host's worker pool, not on the joining member's request thread, so
-there's no Rack middleware and no request to derive an app's tenant from once the Room is up. Pass
-`tenant:` to `join_room` for exactly this — whatever it's given rides along on the provision
-request, comes back out as `Runner#tenant` (and `Room#tenant`), and survives a host migration
-(it's part of what a Room's snapshot carries, alongside its ports and users; see
-[Migration hooks](#migration-hooks)). Leave it out and it defaults to whatever
-`Apartment::Tenant.current` returns right where `join_room` is called — the member's own request
-thread, the last place with real request context before the Room's work moves to a Host thread:
-
-```ruby
-join_room(QuizRoom, params[:quiz_id], create: true)                          # tenant: Apartment::Tenant.current, captured here
-join_room(QuizRoom, params[:quiz_id], create: true, tenant: "some-other-org")  # explicit override
-```
-
-cable_room doesn't depend on Apartment (or anything else) to use this — `tenant` is just a value it
-carries around for you, the same way `key` or `extra` are. **It never switches anything itself.**
-Whatever ends up on `Runner#tenant` still has to actually be applied before a Room's DB calls run,
-the same way a request's tenant has to be applied before a controller action's do.
-
-`around_work` (alongside `before_work`/`after_work`, see [Lifecycle](#lifecycle)) is the hook for
-that. It wraps every piece of Room code that runs on a Host thread — `startup`/`restore_state`,
-message and timer handlers, `snapshot_state`, and `shutdown` alike — not just message dispatch, so
-there's exactly one place to apply a tenant no matter which of those runs first for a given Room.
-Define it once on your own shared base Room class (every app Room already inherits from
-`CableRoom::Room::Base`, directly or through one of your own) to cover every Room, or again on a
-specific Room subclass for one that needs something different — ordinary callback inheritance,
-nothing cable_room-specific:
-
-```ruby
-class ApplicationRoom < CableRoom::Room::Base
-  # Lazily switch a worker thread to the right tenant only when it's about to touch the DB.
-  # Actively switching up front checks out a connection and runs SET search_path even for a
-  # message that never queries anything, so this only stages the tenant (no DB call) and lets
-  # the connection pool's own checkout hook apply it the moment a connection is actually acquired.
-  around_work do |room, blk|
-    Thread.current[:cable_tenant] = {
-      adapter: Apartment::Tenant.adapter,
-      tenant: room.tenant,
-    }
-
-    # If this thread already holds a connection from earlier work, release it so the checkout
-    # hook below gets a fresh checkout to apply the schema to.
-    pool = Apartment.connection_class.connection_pool
-    pool.release_connection if pool.active_connection?
-
-    Apartment::Tenant.adapter.instance_variable_set(:@current, room.tenant)
-
-    blk.call
-  ensure
-    Thread.current[:cable_tenant] = nil
-  end
-end
-
-ActiveSupport.on_load(:active_record) do
-  ActiveRecord::ConnectionAdapters::AbstractAdapter.set_callback :checkout, :after do |conn|
-    next unless (ct = Thread.current[:cable_tenant]).present?
-    next unless Apartment::Tenant.adapter.is_a?(Apartment::Adapters::PostgresqlSchemaAdapter)
-    next unless conn.pool == Apartment.connection_class.connection_pool
-
-    adapter = ct[:adapter]
-    adapter.instance_variable_set(:@current, ct[:tenant])
-    conn.schema_search_path = adapter.send :full_search_path
-  end
-end
-```
-
-`room` is the Room instance itself — `room.tenant` (delegated to its `Host::Runner`) is read fresh
-on every call, so a Room only ever sees its own tenant even though many Rooms for many orgs share
-the same small pool of Host worker threads. `around_work` never has to guard against running
-twice: cable_room only ever enters it once per thread, even when one piece of Room code calls
-another (a message handler that shuts the Room down, say) — the inner call just runs inside the
-outer one's context.
-
-This replaces reaching for `ActionCable::Server::Worker.set_callback :work, :around` the way
-PandaPal does for ordinary channels — that hook only ever fired for message dispatch, and never
-for a Room's `startup`, `snapshot_state`, or `shutdown`, which run directly on a Host thread
-instead. It's structural, not just a convention: `Host::WorkerPool` isn't an
-`ActionCable::Server::Worker` subclass, so it doesn't share ActionCable's `:work` callback chain at
-all. If PandaPal (or anything else) already has a `:work` hook installed, it's harmless to leave in
-place — it simply has nothing to attach to for Room work, so it can neither conflict with,
-double-apply with, nor be relied on in place of `around_work`. Define `around_work` and that's
-the one thing actually switching a Room's tenant.
-
-### 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.