cable_room 0.6.2.beta1 → 0.7.0.beta2

data/lib/cable_room/room/port_management.rb

@@ -3,7 +3,12 @@ module CableRoom
     module PortManagement
       extend ActiveSupport::Concern
 
-      PORT_TIMEOUT = 30.seconds
+      # A port that the room has not heard from for this long is dropped. Any inbound message
+      # counts as hearing from it (see the receive_message callback below), and members only
+      # ping when they have been otherwise silent for RoomMember::PING_INTERVAL, so the longest
+      # gap a live member produces is 2 x PING_INTERVAL. Keep this comfortably above that: under
+      # load the room processes its queue late, and a reaped port is a lost student.
+      PORT_TIMEOUT = 45.seconds
 
       class_methods do
         def on_port_connected(...)
@@ -29,7 +34,13 @@ module CableRoom
         on_port_connected { reply({type: 'port_acknowledged' }) }
 
         set_callback(:receive_message, :around) do |_, blk|
-          with_message_origin(message['mtok']) { blk.call }
+          with_message_origin(message['mtok']) do
+            # Every message from a known port is proof of life, not just port_ping — so a member
+            # that is actively sending never needs to ping (RoomMembership#ping!). Unknown origins
+            # (a port_connected creating its port) are touched when the port is created.
+            message_origin&.touch_activity!
+            blk.call
+          end
         end
 
         system_message_types(:port_connected, :port_disconnected, :port_ping)
@@ -57,6 +68,13 @@ module CableRoom
         { client_port: client_port || tag, **kwargs }
       end
 
+      # How many member ports are attached right now. Public, unlike `connected_clients`, because
+      # the Host reads it from outside the room's thread to total up `Host#open_ports`; a plain
+      # size is safe to read that way and a moment's staleness doesn't matter for a gauge.
+      def open_port_count
+        @_port_clients.size
+      end
+
       def reply(message = nil, **kwargs)
         raise ArgumentError, "Can only use reply when handling a message" unless message_origin
         raise ArgumentError, "Must provide message or block" unless message || block_given?
@@ -140,6 +158,29 @@ module CableRoom
         end
       end
 
+      # -- Snapshot and restore (see CableRoom::Snapshot) ----------------------------------------
+
+      def _snapshot_port_clients
+        @_port_clients.values.map(&:to_snapshot)
+      end
+
+      # Re-create every port exactly as it was, without running port_connected callbacks: the
+      # members are still there and were already acknowledged. A port whose user can't be found
+      # any more (its record was deleted) is dropped rather than failing the whole room; that
+      # member will be re-acknowledged when it next pings.
+      def _restore_port_clients(entries)
+        Array(entries).each do |entry|
+          client = PortClient.new(self, entry["token"])
+          begin
+            client.restore!(entry)
+          rescue ::ActiveJob::DeserializationError => e
+            logger.warn "Dropping port #{entry['token']} from the snapshot: #{e.message}"
+            next
+          end
+          @_port_clients[client.token] = client
+        end
+      end
+
       def check_port_inactivity
         return unless @_port_clients
 
@@ -197,6 +238,33 @@ module CableRoom
         def tag!(*tags)
           self[:tags].merge(tags.flatten.map(&:to_sym))
         end
+
+        SNAPSHOT_OWN_KEYS = %w[tags as last_seen_at].freeze
+
+        # This port as one `port_clients` entry of a CableRoom::Snapshot. `as` goes through the
+        # same serializer the member used to send it (a GlobalID for a record). Everything else on
+        # the port — what the member's `extra:` merged in, plus anything the room stored with
+        # `message_origin[:x] = ...` — travels under `metadata`, the same way, so records survive.
+        def to_snapshot
+          metadata = @metadata.to_h.except(*SNAPSHOT_OWN_KEYS)
+          {
+            token: token,
+            tags: self[:tags].map(&:to_s),
+            as: Snapshot.serialize_argument(self[:as]),
+            last_seen_at: Snapshot.encode_time(self[:last_seen_at]),
+            metadata: Snapshot.serialize_argument(metadata),
+          }
+        end
+
+        # The inverse of `to_snapshot`. `last_seen_at` is kept, not reset: the port is exactly as
+        # old as it was, and its member's next ping refreshes it as usual.
+        def restore!(entry)
+          merge!(Snapshot.deserialize_argument(entry["metadata"]))
+          tag!(entry["tags"])
+          self[:as] = Snapshot.deserialize_argument(entry["as"])
+          self[:last_seen_at] = Snapshot.decode_time(entry["last_seen_at"]) || self[:last_seen_at]
+          self
+        end
       end
     end
   end

data/lib/cable_room/room/reaping.rb

@@ -59,7 +59,7 @@ module CableRoom
       protected
 
       def ping_watchdog
-        @cable_channel.ping_watchdog
+        @runner.ping_watchdog
       end
 
       def check_reapers_now!
@@ -74,6 +74,39 @@ module CableRoom
         ping_watchdog
       end
 
+      # -- Snapshot and restore (see CableRoom::Snapshot) ----------------------------------------
+
+      # One entry per `reap_when`, in declaration order. `last_keep_at` is the wall-clock moment
+      # the reaper's grace period started counting from (nil until it has run once), so the
+      # deadline — `last_keep_at + grace` — is the same on whichever host restores it.
+      def _snapshot_reaper_state
+        self.class.reaper_checkers.each_with_index.map do |cfg, index|
+          state = _reaper_states[cfg] || {}
+          { key: cfg[:key]&.to_s, index: index, last_keep_at: Snapshot.encode_time(state[:last_keep_at]) }
+        end
+      end
+
+      # Runs before the startup callbacks, which add the timer to each state and leave the rest
+      # alone. A named reaper matches by name and an anonymous one by position, so a Room whose
+      # reapers changed between the two hosts' code versions keeps what still lines up and drops
+      # the rest.
+      def _restore_reaper_state(entries)
+        checkers = self.class.reaper_checkers
+        Array(entries).each do |entry|
+          cfg =
+            if entry["key"].present?
+              checkers.find { |c| c[:key].to_s == entry["key"] }
+            else
+              candidate = checkers[entry["index"].to_i]
+              candidate if candidate && candidate[:key].nil?
+            end
+          next unless cfg
+
+          last_keep_at = Snapshot.decode_time(entry["last_keep_at"])
+          (_reaper_states[cfg] ||= {})[:last_keep_at] = last_keep_at if last_keep_at
+        end
+      end
+
       private
 
       def _reaper_states

data/lib/cable_room/room/snapshotting.rb

@@ -0,0 +1,82 @@
+module CableRoom
+  module Room
+    # The room's side of a migration: turning itself into a CableRoom::Snapshot and coming back
+    # from one. The gem carries what it owns (ports, tags, users, reaper deadlines); a Room can
+    # carry its own state too with two optional hooks:
+    #
+    #   class QuizRoom < CableRoom::Room::Base
+    #     def snapshot_state
+    #       { question_id: @question.id, answers: @answers }   # JSON only; records by id
+    #     end
+    #
+    #     def restore_state(state)
+    #       @question = Question.find(state[:question_id])      # indifferent access: :key or "key"
+    #       @answers = state[:answers]
+    #     end
+    #   end
+    #
+    # A room that defines `restore_state` gets it instead of `startup` when it's restored, with
+    # whatever `snapshot_state` returned (nil if the room that was snapshotted had no
+    # `snapshot_state`). A room without `restore_state` just runs `startup` again and rebuilds its
+    # state the way it did the first time. Either way the `before_startup`/`after_startup`
+    # callbacks run as usual, except that the gem does not broadcast `room_opened`: the members
+    # were there the whole time and never saw the room go away. `restored?` tells a callback which
+    # case it's in.
+    module Snapshotting
+      extend ActiveSupport::Concern
+
+      # True for a room that was rebuilt from a snapshot rather than started fresh.
+      def restored?
+        @_restored == true
+      end
+
+      private
+
+      # Build the snapshot (see CableRoom::Snapshot for the shape). Only meaningful once the room
+      # is frozen: nothing else may be touching its state while this reads it.
+      def _snapshot
+        document = {
+          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,
+          app_state: _snapshot_app_state,
+        }
+
+        ActiveSupport::Notifications.instrument("room_snapshotted.cable_room", { room: self }) do
+          Snapshot.round_trip(document)
+        end
+      end
+
+      def _snapshot_app_state
+        return nil unless respond_to?(:snapshot_state, true)
+
+        state = snapshot_state
+        Snapshot.assert_json!(state, room: self)
+        state
+      end
+
+      # Rebuild from `snapshot`: gem state first, quietly (no port_connected or user_joined
+      # callbacks, since none of it is new), then the startup chain with `restore_state` in place
+      # of `startup`. Runs where `_startup` would, before the runner starts the periodic timers.
+      def _restore(snapshot)
+        snapshot = Snapshot.validate!(snapshot)
+        @_restored = true
+
+        _restore_port_clients(snapshot["port_clients"])
+        _restore_user_state(snapshot["user_state"])
+        _restore_reaper_state(snapshot["reaper_state"])
+
+        app_state = snapshot["app_state"]
+        app_state = app_state.with_indifferent_access if app_state.is_a?(Hash)
+        _startup(restoring: true, app_state: app_state)
+      end
+    end
+  end
+end

data/lib/cable_room/room/threading.rb

@@ -36,13 +36,13 @@ module CableRoom
       # results back with `on_room_thread` over waiting for them.
       def async(&blk)
         room = self
-        @cable_channel.post_work(async: true) { room.instance_exec(&blk) }
+        @runner.post_work(async: true) { room.instance_exec(&blk) }
       end
 
       # Queue the block back onto the Room's own thread, where touching Room state is safe again.
       def on_room_thread(&blk)
         room = self
-        @cable_channel.post_work(async: false, silent: true) { room.instance_exec(&blk) }
+        @runner.post_work(async: false, silent: true) { room.instance_exec(&blk) }
       end
     end
   end

data/lib/cable_room/room/user_management.rb

@@ -98,6 +98,33 @@ module CableRoom
         tags
       end
 
+      # -- Snapshot and restore (see CableRoom::Snapshot) ----------------------------------------
+
+      # The user map is carried on its own rather than rebuilt from the ports: a port whose join
+      # the tag policy refused has no user entry, and a rebuild would invent one.
+      def _snapshot_user_state
+        @_user_map_mutex.synchronize do
+          @_user_state_map.map do |user, usm|
+            { user: Snapshot.serialize_argument(user), port_tokens: usm[:port_tokens].to_a }
+          end
+        end
+      end
+
+      # No user_joined callbacks here: these users joined long ago, on the previous host.
+      def _restore_user_state(entries)
+        @_user_map_mutex.synchronize do
+          Array(entries).each do |entry|
+            begin
+              user = Snapshot.deserialize_argument(entry["user"])
+            rescue ::ActiveJob::DeserializationError => e
+              logger.warn "Dropping a user from the snapshot: #{e.message}"
+              next
+            end
+            @_user_state_map[user] = { port_tokens: Set.new(entry["port_tokens"]) }
+          end
+        end
+      end
+
       def _apply_port_scope(user: nil, tag: nil, **kwargs)
         if user && tag
           user_tags = all_user_tags(user) || []

data/lib/cable_room/room.rb

@@ -7,9 +7,10 @@ module CableRoom
 
       autoload :Callbacks
       autoload :Threading
-      autoload :ChannelAdapter
+      autoload :HostAdapter
 
       autoload :Lifecycle
+      autoload :Snapshotting
       autoload :Reaping
       autoload :InputHandling
 
@@ -20,8 +21,10 @@ module CableRoom
       autoload :Broadcasting
     end
 
+    # Every room running in this process. Asking never creates a Host, so a process that hosts
+    # no rooms (a web process in :remote) just gets an empty list.
     def self.locally_open_rooms
-      ChannelTracker.instance.room_channels.map(&:room)
+      Host.current&.rooms || []
     end
   end
 end

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