cable_room 0.7.0.beta1 → 0.7.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 890aa545d8211663c2270322da9440b0dbd685e7cdcfa9858df04390d06e7533
-  data.tar.gz: 074e6c49a9886c90483500bdb61cdf40fa4d3c9e83ddc583415cc9ac051e90f6
+  metadata.gz: 196a159b658502db6be07f62ae5987283192a3f76580f5ed79b3790c8c387732
+  data.tar.gz: c2ae315fee416f4e823f51fb2bea539692e6161f4849dd590fe845ffa3fe5f6e
 SHA512:
-  metadata.gz: 3304bd77c3d455a2b867d83d82d4985ff7e1a3ec10bd80ec6a097f50be040fadbbaac501d7f26234384ba50dbe9f09864c92e1114d8cecff75d308ae2a770261
-  data.tar.gz: 408c73ab717cd8aaa5a7fbc8ce6b5d209ee2169fe50a731ac8b6d7b2b417b61e64c5a9ceac55155e07e677f6b3a952bb56edd4043a16b624bb264cd6ca1fb21d
+  metadata.gz: c3210f7c372f5085b2acf3de7fd8ee98f9e7d81a951b319d2476faa71266d57e48ba21b8018815504b969ca86e2431e907462bc08dedb14fb5fbbae2a6bc4ada
+  data.tar.gz: 03adad866d9348d12acd61b848ca0a5cfd45b4557b0dd978d43a9b8d8581fa863674fe2e993b2404b0d7db4376d134e7e0a9d1f1912c29b0784704bbd871ceb0

data/README.md

@@ -154,12 +154,22 @@ class MyRoom < CableRoom::Room::Base
   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.
 
@@ -218,7 +228,8 @@ Timer bodies run on the Room's thread, so they're serialized against message han
 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:
+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
@@ -534,6 +545,7 @@ end
 | `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.                                            |
@@ -555,6 +567,91 @@ request on the bus, and one of the Rooms hosts starts the Room (see
 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

data/lib/cable_room/host/runner.rb

@@ -18,6 +18,11 @@ module CableRoom
     class Runner
       FROZEN_STATES = %i[freezing frozen].freeze
 
+      # Thread-local flag guarding re-entry into a Room's `:work` callbacks (see
+      # `with_room_context`). Namespaced so it can never collide with a key an app's own callback
+      # (PandaPal's, or anything else touching `Thread.current`) happens to use for its own purposes.
+      APP_WORK_KEY = :"cable_room.in_room_work_callbacks"
+
       attr_reader :host, :room, :room_class, :key, :uuid, :tenant, :logger
 
       # Monotonic time this runner was built. `Host#drain!` migrates rooms oldest first.
@@ -25,7 +30,7 @@ module CableRoom
 
       delegate :worker_pool, :inbound, to: :host
 
-      def initialize(host, room_class, key, lock_info, watchdog_interval:, lock_duration:)
+      def initialize(host, room_class, key, lock_info, watchdog_interval:, lock_duration:, tenant: nil)
         @host = host
         @room_class = room_class
         @key = key
@@ -48,7 +53,13 @@ module CableRoom
         @handlers = {}  # stream => the room's handler, so a message can be fed in by hand (see `inject`)
         @periodic_timers = []
 
-        @tenant = Apartment::Tenant.current if defined?(Apartment)
+        # Whatever the member's provision request said (RoomMembership defaults that to the
+        # ambient tenant at join_room's own call site -- see RoomMembership#initialize) or, for a
+        # migrated room, whatever its snapshot carried forward. Nothing here parses it out of
+        # `key` or guesses from ambient state itself: a Host thread has no request of its own, so
+        # anything read here would be leftover from whatever this thread ran last, not this room's
+        # tenant.
+        @tenant = tenant
 
         @logger = ActionCable::Connection::TaggedLoggerProxy.new(
           host.logger,
@@ -116,7 +127,7 @@ module CableRoom
         room.send(:_shutdown_reason=, reason) unless reason.nil?
         unsubscribe_all
         begin
-          with_executor { room.send(:_shutdown) }
+          with_executor { with_room_context { room.send(:_shutdown) } }
         ensure
           terminate!
         end
@@ -275,7 +286,7 @@ module CableRoom
       def snapshot
         raise "#{room_class.name}[#{key}] must be frozen before it can be snapshotted (state: #{state})" unless state == :frozen
 
-        with_executor { Snapshot.take(room) }
+        with_executor { with_room_context { Snapshot.take(room) } }
       end
 
       # Give the room's lock up while staying alive, so another host can claim the room and this
@@ -359,7 +370,7 @@ module CableRoom
       # message can't take the room down with it.
       def post_work(async: false, silent: false, &blk)
         work = proc do
-          worker_pool.invoke(blk, :call, connection: self)
+          worker_pool.invoke(-> { with_room_context(&blk) }, :call, connection: self)
         rescue => e
           report_work_error(e)
         end
@@ -448,8 +459,10 @@ module CableRoom
       def start_with(final_state: :started)
         @current_state = :starting
         with_executor do
-          yield
-          start_periodic_timers unless final_state == :frozen
+          with_room_context do
+            yield
+            start_periodic_timers unless final_state == :frozen
+          end
         end
         @current_state = final_state
       rescue => e
@@ -566,6 +579,48 @@ module CableRoom
           yield
         end
       end
+
+      # The one seam a Room hooks to run its own around-work logic -- Apartment switching,
+      # tracing, whatever -- instead of reaching for ActionCable::Server::Worker's `:work`
+      # callback the way PandaPal does (see README's Multi-tenancy section). Deliberately the
+      # Room's own `before_work`/`after_work`/`around_work` (see Room::Callbacks), not a second,
+      # separately-configured extension point: a Room class already is cable_room's own
+      # (non-shared, non-leaky) namespace, ordinary Ruby inheritance already gives "every Room"
+      # (define it on your own base Room class, or reopen CableRoom::Room::Base itself) and
+      # "just this one" (define it again on a specific subclass) for free, and there's no reason
+      # to make an app choose between two different mechanisms for the same thing. Still supports
+      # PandaPal's lazy pattern: stage a thread-local here, apply it from an ActiveRecord
+      # `checkout` hook, so a message that never queries anything never pays for a schema switch.
+      #
+      # Every place this Runner touches Room code goes through here: `post_work`'s dispatched
+      # work, and the lifecycle methods (`start_with`, `stop!`, `snapshot`) that -- unlike
+      # `post_work` -- run directly on the calling thread rather than through the worker pool.
+      # A Room's `around_work` never has to know which of those it's wrapping, or guard against
+      # being entered twice: called from inside work that's already running (`Room::Lifecycle#stop!`
+      # from a message handler, say, or the watchdog's own `stop!`), this just yields through.
+      #
+      # AR query-log tagging (tag the log with this Room's own tags, the way
+      # `ActiveRecordConnectionManagement` did when WorkerPool was still a Worker subclass) wraps
+      # every call here regardless of re-entry -- tagging nests safely, unlike `:work` callbacks
+      # that stage-and-clear a thread-local.
+      def with_room_context(&blk)
+        with_ar_log_tagging do
+          next yield if Thread.current[APP_WORK_KEY]
+
+          Thread.current[APP_WORK_KEY] = true
+          begin
+            room.send(:run_callbacks, :work, &blk)
+          ensure
+            Thread.current[APP_WORK_KEY] = false
+          end
+        end
+      end
+
+      def with_ar_log_tagging(&blk)
+        return yield unless defined?(ActiveRecord::Base)
+
+        logger.tag(ActiveRecord::Base.logger, &blk)
+      end
     end
   end
 end

data/lib/cable_room/host/worker_pool.rb

@@ -1,37 +1,50 @@
+require 'concurrent'
+
 module CableRoom
   class Host
-    # The thread pool every room's work runs on. It's an ActionCable Worker so the `:work`
-    # callbacks Rails installs (the executor wrap, ActiveRecord log tagging) still apply to room
-    # work exactly as they did when rooms were channels.
-    #
-    # The "connection" passed around here is the room's Host::Runner. ActionCable's Worker was
-    # written for connections; rooms don't have one, but the runner fills the same role: it's
-    # the thing with a logger and an error reporter.
-    class WorkerPool < ActionCable::Server::Worker
-      set_callback :work, :around do |_, blk|
-        pconn = ActionCable::Server::Worker.connection
-        ActionCable::Server::Worker.connection = connection
-        blk.call
-      ensure
-        ActionCable::Server::Worker.connection = pconn
+    # The thread pool every room's work runs on. Deliberately *not* an ActionCable::Server::Worker
+    # subclass: that would put Room work on the same shared `:work` callback chain as ordinary
+    # ActionCable connections, and that chain is leaky by construction -- `ActiveSupport::Callbacks`
+    # re-injects a callback added to the base class into every existing descendant regardless of
+    # load order, so an app's own tenant-switching hook (PandaPal's, say, registered from a Rails
+    # initializer well after this class is defined) ends up wrapping Room work too, whether we want
+    # it to or not. Owning a distinct namespace here avoids that category of problem entirely:
+    # nothing outside cable_room can attach to Room work by surprise. The one seam an app gets is
+    # a Room's own `before_work`/`after_work`/`around_work` (see Room::Callbacks and
+    # Host::Runner#with_room_context).
+    class WorkerPool
+      attr_reader :executor
+
+      def initialize(max_size: 5)
+        @executor = Concurrent::ThreadPoolExecutor.new(
+          name: "CableRoom",
+          min_threads: 1,
+          max_threads: max_size,
+          max_queue: 0,
+        )
       end
 
-      # ActionCable's Worker#invoke reduces every exception to a log line and a no-argument
-      # `handle_exception` call, which discards the error itself. Rooms run all of their work
-      # through here, so report it properly instead.
+      # Reduces every exception to a proper report instead of ActionCable's Worker#invoke, which
+      # logs a line and calls a no-argument `handle_exception`, discarding the error itself. Rooms
+      # run all of their work through here, so report it properly. `connection:` is always a
+      # Host::Runner in practice (see Runner#post_work); the else branch is a defensive fallback.
       def invoke(receiver, method, *args, connection:, &block)
-        work(connection) do
-          receiver.send method, *args, &block
-        rescue Exception => e
-          if connection.respond_to?(:report_work_error)
-            connection.report_work_error(e)
-          else
-            logger.error "There was an exception - #{e.class}(#{e.message})"
-            logger.error Array(e.backtrace).join("\n")
-            CableRoom.report_error(e, connection: connection)
-          end
+        receiver.send method, *args, &block
+      rescue Exception => e
+        if connection.respond_to?(:report_work_error)
+          connection.report_work_error(e)
+        else
+          logger.error "There was an exception - #{e.class}(#{e.message})"
+          logger.error Array(e.backtrace).join("\n")
+          CableRoom.report_error(e, connection: connection)
         end
       end
+
+      private
+
+      def logger
+        ActionCable.server.logger
+      end
     end
   end
 end

data/lib/cable_room/host.rb

@@ -147,7 +147,7 @@ module CableRoom
     # made after the lock is won, so it can't be raced. `handoff_only: true` (a handoff request)
     # starts nothing when there is no snapshot to adopt — it has expired, or the old host took
     # the room back — and lets the lock go.
-    def ensure_room(room_class, key = nil, handoff_only: false)
+    def ensure_room(room_class, key = nil, handoff_only: false, tenant: nil)
       lock_key = room_class.room_port_key(key)
       lock_info = CableRoom.lock_manager.lock(lock_key, room_class::LOCK_DURATION.in_milliseconds)
       return false unless lock_info
@@ -167,6 +167,7 @@ module CableRoom
         lock_info,
         watchdog_interval: room_class::WATCH_DOG_INTERVAL,
         lock_duration: room_class::LOCK_DURATION,
+        tenant: tenant,
       )
 
       true
@@ -176,9 +177,12 @@ module CableRoom
     end
 
     # Start running a room here. The caller (`ensure_room`) has already taken the room's Redlock;
-    # the runner renews it from now on and releases it when the room dies.
-    def start_room(room_class, key, lock_info, watchdog_interval:, lock_duration:)
-      runner = Runner.new(self, room_class, key, lock_info, watchdog_interval:, lock_duration:)
+    # the runner renews it from now on and releases it when the room dies. `tenant:` comes from the
+    # member's provision request (see RoomMembership#initialize / #maybe_provision_room and
+    # Placement#claim), already defaulted there to the ambient tenant if the app didn't pass one
+    # explicitly -- nil past that point just means no Apartment multi-tenancy is in play.
+    def start_room(room_class, key, lock_info, watchdog_interval:, lock_duration:, tenant: nil)
+      runner = Runner.new(self, room_class, key, lock_info, watchdog_interval:, lock_duration:, tenant:)
       runner.start!
       runner
     end
@@ -215,6 +219,7 @@ module CableRoom
         lock_info,
         watchdog_interval: room_class::WATCH_DOG_INTERVAL,
         lock_duration: room_class::LOCK_DURATION,
+        tenant: snapshot["tenant"],
       )
       runner.restore!(snapshot, hold_inbound: hold_inbound)
       runner

data/lib/cable_room/placement.rb

@@ -181,10 +181,12 @@ module CableRoom
         # `handoff: true` (with a `reason`) is a draining host offering a room to its peers. The
         # race is the same — the lock decides — but the winner rebuilds the room from the offered
         # snapshot and replays what the old host relayed instead of starting it from scratch (see
-        # CableRoom::Migration.adopt). A plain request starts the room fresh.
+        # CableRoom::Migration.adopt). A plain request starts the room fresh. A handoff request
+        # carries no `tenant` of its own -- the snapshot it adopts from carries it instead (see
+        # Room::Snapshotting#_snapshot), so `ensure_room` only needs it for the fresh-start path.
         handoff = request["handoff"] == true
         notification[:handoff] = handoff
-        notification[:claimed] = host.ensure_room(room_class, room_key, handoff_only: handoff)
+        notification[:claimed] = host.ensure_room(room_class, room_key, handoff_only: handoff, tenant: request["tenant"])
       end
 
       if claimed

data/lib/cable_room/room/base.rb

@@ -73,7 +73,7 @@ module CableRoom
 
       attr_reader :key
 
-      delegate :logger, to: :@runner
+      delegate :logger, :tenant, to: :@runner
 
       def initialize(runner, key = nil)
         super()

data/lib/cable_room/room/callbacks.rb

@@ -7,6 +7,7 @@ module CableRoom
       included do
         define_callbacks :startup
         define_callbacks :shutdown
+        define_callbacks :work
       end
 
       class_methods do
@@ -27,6 +28,27 @@ module CableRoom
           set_callback(:shutdown, :after, *methods, &block)
         end
         alias_method :on_shutdown, :after_shutdown
+
+        # Wraps every piece of Room code that runs on a Host thread: startup/restore, message and
+        # timer handlers, snapshot_state, and shutdown alike (see Host::Runner#with_room_context,
+        # the one thing that ever triggers the :work callback chain). This is the seam for
+        # anything that has to be true before a Room's own code runs on a given thread -- Apartment
+        # switching first among them (see README's Multi-tenancy section).
+        #
+        # Define it once on your own shared base Room class (or reopen CableRoom::Room::Base
+        # itself) to cover every Room; define it again on a specific Room subclass for one that
+        # needs something different -- ordinary callback inheritance, nothing cable_room-specific.
+        def before_work(*methods, &block)
+          set_callback(:work, :before, *methods, &block)
+        end
+
+        def after_work(*methods, &block)
+          set_callback(:work, :after, *methods, &block)
+        end
+
+        def around_work(*methods, &block)
+          set_callback(:work, :around, *methods, &block)
+        end
       end
     end
   end

data/lib/cable_room/room/snapshotting.rb

@@ -39,6 +39,10 @@ module CableRoom
           version: Snapshot::VERSION,
           room_class: self.class.name,
           key: Snapshot.serialize_argument(key),
+          # Carried forward so the host that adopts this room (Host#restore_room) gets the same
+          # tenant this one was given at provisioning, instead of falling back to a guess (see
+          # Runner#initialize). nil for a room that was never given one either.
+          tenant: @runner.tenant,
           port_clients: _snapshot_port_clients,
           user_state: _snapshot_user_state,
           reaper_state: _snapshot_reaper_state,

data/lib/cable_room/room_harness.rb

@@ -0,0 +1,168 @@
+require "cable_room"
+require "active_support/tagged_logging"
+
+module CableRoom
+  # Builds a Room without a Host, a live pubsub subscription, or a Redis lock, so the parts of a
+  # Room that are pure logic (authorization, port scoping, callbacks, reaping) can be tested
+  # directly and synchronously. Anything that needs real message delivery belongs in an e2e spec.
+  #
+  # Not loaded by `require "cable_room"` -- an app (or this gem's own suite) opts in with
+  # `require "cable_room/room_harness"`, typically from spec_helper.
+  #
+  # Stands in for CableRoom::Host::Runner.
+  class StubRoomRunner
+    attr_reader :logger, :state, :shutdown_reason, :watchdog_pings, :tenant
+
+    def initialize(tenant: nil)
+      @logger = ActiveSupport::TaggedLogging.new(Logger.new(IO::NULL))
+      @state = :started
+      @watchdog_pings = 0
+      @timers = []
+      @tenant = tenant
+    end
+
+    def ping_watchdog
+      @watchdog_pings += 1
+    end
+
+    # Record streams rather than subscribing, so startup can run without a live pubsub. There is
+    # nothing to wait for, so `on_live` runs at once.
+    def subscribe(stream, on_live: nil, &blk)
+      streams[stream] = blk
+      on_live&.call
+    end
+
+    def unsubscribe(stream)
+      streams.delete(stream)
+    end
+
+    def streams
+      @streams ||= {}
+    end
+
+    # Feed a message to whatever the room streamed from this port, the way pubsub would
+    def deliver_to_stream(stream, message)
+      streams.fetch(stream).call(message)
+    end
+
+    def initiate_shutdown(reason)
+      @shutdown_reason = reason
+      @state = :shutting_down
+    end
+
+    def stop!
+      @state = :dead
+    end
+
+    # Run inline so specs stay synchronous
+    def post_work(**_kwargs, &blk)
+      blk.call
+    end
+
+    # Record timers rather than scheduling them, so specs can fire them on demand
+    def start_periodic_timer(callback, every:)
+      timer = StubTimer.new(callback, every)
+      @timers << timer
+      timer
+    end
+
+    def timers
+      @timers.reject(&:shutdown?)
+    end
+
+    class StubTimer
+      attr_reader :interval
+
+      def initialize(callback, interval)
+        @callback = callback
+        @interval = interval
+        @shutdown = false
+      end
+
+      def fire!
+        @callback.call
+      end
+
+      def shutdown
+        @shutdown = true
+      end
+
+      def shutdown?
+        @shutdown
+      end
+    end
+  end
+
+  module RoomHarness
+    # A fully-initialized Room backed by a StubRoomRunner. Pass `started: true` to run the
+    # startup callbacks (which is what registers reaper timers and the inbound stream). Pass
+    # `tenant:` the way a member's provision request would (see RoomMembership#initialize) for a
+    # Room whose logic needs Apartment scoped correctly -- this switches into it for the duration
+    # of startup, the way PandaPal's ActionCable::Server::Worker hook does in production for a
+    # real Runner, so a Room can't tell the difference from here.
+    def build_room(room_class, key: "harness-key", started: false, tenant: nil)
+      runner = StubRoomRunner.new(tenant: tenant)
+      room = room_class.allocate
+      room.send(:initialize, runner, key)
+      runner.define_singleton_method(:room) { room }
+      with_room_tenant(runner) { room.send(:_startup) } if started
+      room
+    end
+
+    # A Room rebuilt from `snapshot` on a fresh StubRoomRunner, the way Host#restore_room would
+    # build it: gem state restored, then the startup chain with `restore_state` in place of
+    # `startup`. Pass the class explicitly so a spec reads as "restore a FooRoom", even though the
+    # snapshot names it too. `tenant` comes off the snapshot itself, same as Host#restore_room.
+    def restore_room(room_class, snapshot)
+      runner = StubRoomRunner.new(tenant: snapshot["tenant"])
+      room = room_class.allocate
+      room.send(:initialize, runner, Snapshot.key_for(snapshot))
+      runner.define_singleton_method(:room) { room }
+      with_room_tenant(runner) { room.send(:_restore, snapshot) }
+      room
+    end
+
+    def stub_runner_for(room)
+      room.instance_variable_get(:@runner)
+    end
+
+    # Push a message through the same callback chain the real stream handler uses.
+    # Returns false when authorization halted the chain, otherwise :handled.
+    def deliver(room, message)
+      message = message.deep_stringify_keys if message.is_a?(Hash)
+      Room.current_message = message
+      with_room_tenant(stub_runner_for(room)) do
+        room.send(:run_callbacks, :receive_message) do
+          room.send(:handle_received_message, message)
+          :handled
+        end
+      end
+    ensure
+      Room.current_message = nil
+    end
+
+    # Register a port on the room the way a real RoomMembership would, returning its token.
+    def connect_port(room, token: SecureRandom.hex(16), tags: [], as: nil)
+      message = { type: 'port_connected', mtok: token, tags: tags }
+      message[:extra] = ::ActiveJob::Arguments.serialize([{ as: as }]) if as
+      deliver(room, message)
+      token
+    end
+
+    def port_client(room, token)
+      room.send(:resolve_client_port, token)
+    end
+
+    private
+
+    # Stands in for PandaPal's ActionCable::Server::Worker hook, which is what actually switches
+    # Apartment before a Host thread's DB calls in production. A Room without a `tenant` (a
+    # single-tenant app, or a spec that doesn't need one) gets no-op behavior; the gem itself
+    # stays Apartment-optional either way.
+    def with_room_tenant(runner, &blk)
+      return blk.call unless runner.tenant && defined?(Apartment)
+
+      Apartment::Tenant.switch(runner.tenant, &blk)
+    end
+  end
+end

data/lib/cable_room/room_member.rb

@@ -148,6 +148,7 @@ module CableRoom
       on_left: nil,
       tags: [],
       extra: nil,
+      tenant: nil,
       &preconfigure
     )
       @mutex = Monitor.new
@@ -161,6 +162,14 @@ module CableRoom
       @room_key = room_key
       @allow_create = create
 
+      # Defaults to the ambient tenant right here, at join_room's own call site -- the member's
+      # own request thread, the last point before this room's work moves to a Host thread with no
+      # request of its own to derive one from (see Runner#initialize). An app only needs to pass
+      # `tenant:` explicitly to ask for something other than "whatever tenant this join is
+      # happening under", which is the common case. nil isn't a real tenant either way, so it
+      # doubles as "not given".
+      @tenant = tenant || (Apartment::Tenant.current if defined?(Apartment))
+
       @on_room_opened = on_room_opened
       @on_joined = on_joined
       @on_message = on_message
@@ -230,6 +239,7 @@ module CableRoom
         "extra" => serialized_extra,
         "create" => @allow_create,
         "hello_received" => @hello_received,
+        "tenant" => @tenant,
       }
     end
 
@@ -446,6 +456,7 @@ module CableRoom
       @serialized_extra = record["extra"]
       @allow_create = record["create"] == true
       @hello_received = record["hello_received"] == true
+      @tenant = record["tenant"]
     end
 
     def transmit_port_connected
@@ -491,6 +502,10 @@ module CableRoom
         # Keys travel the way `extra` does, so a record key arrives on the host as the record
         room_key: ::ActiveJob::Arguments.serialize([@room_key]),
         requested_at: Time.current,
+        # Whatever `join_room` was given for `tenant:` (nil for a single-tenant app). The Host has
+        # no request of its own to derive this from, so a multi-tenant app has to hand it over
+        # explicitly here rather than have the Runner guess at ambient state (see Runner#initialize).
+        tenant: @tenant,
       }
 
       ActiveSupport::Notifications.instrument(

data/lib/cable_room/version.rb

@@ -1,3 +1,3 @@
 module CableRoom
-  VERSION = "0.7.0.beta1".freeze
+  VERSION = "0.7.0.beta3".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cable_room
 version: !ruby/object:Gem::Version
-  version: 0.7.0.beta1
+  version: 0.7.0.beta3
 platform: ruby
 authors:
 - Ethan Knapp
@@ -140,6 +140,7 @@ files:
 - lib/cable_room/room/snapshotting.rb
 - lib/cable_room/room/threading.rb
 - lib/cable_room/room/user_management.rb
+- lib/cable_room/room_harness.rb
 - lib/cable_room/room_member.rb
 - lib/cable_room/room_proxy_channel.rb
 - lib/cable_room/snapshot.rb