cable_room 0.7.0.beta2 → 0.7.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 230a3cec91f557f72ae459ed02fdf93ca4cc72d33a09a1e886ba503d27d665df
-  data.tar.gz: 4bc92906a5db6b957265f09b7fb3b596e587208fa01057890ad273ed1d9d0a94
+  metadata.gz: 196a159b658502db6be07f62ae5987283192a3f76580f5ed79b3790c8c387732
+  data.tar.gz: c2ae315fee416f4e823f51fb2bea539692e6161f4849dd590fe845ffa3fe5f6e
 SHA512:
-  metadata.gz: '0268892f4951a1c869caf8e5ab8d2218e4e06def83df3d5b32a3ae21b768678175668276dc47f4cb4a8fb3abcff42bc28092989aa9385c1df345e5c677de33af'
-  data.tar.gz: 186b3001f84e157c856164b22aff29984a7ec8471bc2e4ea28ac9c830a26a638ceae8852b3a5301f43eb27e26d4e0294f294543637353dbe04999dd91d71f70c
+  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.
 
@@ -578,29 +588,38 @@ carries around for you, the same way `key` or `extra` are. **It never switches a
 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:
+`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
-# 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
+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
@@ -616,10 +635,22 @@ ActiveSupport.on_load(:active_record) do
 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.
+`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.
 

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.
@@ -122,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
@@ -281,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
@@ -365,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
@@ -454,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
@@ -572,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/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/version.rb

@@ -1,3 +1,3 @@
 module CableRoom
-  VERSION = "0.7.0.beta2".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.beta2
+  version: 0.7.0.beta3
 platform: ruby
 authors:
 - Ethan Knapp