cable_room 0.7.0.beta1 → 0.7.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 890aa545d8211663c2270322da9440b0dbd685e7cdcfa9858df04390d06e7533
-  data.tar.gz: 074e6c49a9886c90483500bdb61cdf40fa4d3c9e83ddc583415cc9ac051e90f6
+  metadata.gz: 230a3cec91f557f72ae459ed02fdf93ca4cc72d33a09a1e886ba503d27d665df
+  data.tar.gz: 4bc92906a5db6b957265f09b7fb3b596e587208fa01057890ad273ed1d9d0a94
 SHA512:
-  metadata.gz: 3304bd77c3d455a2b867d83d82d4985ff7e1a3ec10bd80ec6a097f50be040fadbbaac501d7f26234384ba50dbe9f09864c92e1114d8cecff75d308ae2a770261
-  data.tar.gz: 408c73ab717cd8aaa5a7fbc8ce6b5d209ee2169fe50a731ac8b6d7b2b417b61e64c5a9ceac55155e07e677f6b3a952bb56edd4043a16b624bb264cd6ca1fb21d
+  metadata.gz: '0268892f4951a1c869caf8e5ab8d2218e4e06def83df3d5b32a3ae21b768678175668276dc47f4cb4a8fb3abcff42bc28092989aa9385c1df345e5c677de33af'
+  data.tar.gz: 186b3001f84e157c856164b22aff29984a7ec8471bc2e4ea28ac9c830a26a638ceae8852b3a5301f43eb27e26d4e0294f294543637353dbe04999dd91d71f70c

data/README.md

@@ -218,7 +218,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 +535,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 +557,70 @@ 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.
+
+If you're wiring this up yourself, here's the shape of that hook:
+
+```ruby
+# 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.
+ActionCable::Server::Worker.set_callback :work, :around do |_, blk|
+  Thread.current[:cable_tenant] = {
+    adapter: Apartment::Tenant.adapter,
+    tenant: connection.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, connection.tenant)
+
+  blk.call
+ensure
+  Thread.current[:cable_tenant] = nil
+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
+```
+
+`connection` here is whatever `Worker#work(connection)` was handed — a real
+`ActionCable::Connection::Base` for ordinary channel work, a `Host::Runner` for Room work. Either
+way it's read fresh on every unit of work, 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.
+
 ### 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

@@ -25,7 +25,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 +48,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,

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/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.beta2".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.beta2
 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