cable_room 0.6.1 → 0.7.0.beta1

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,78 @@
+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),
+          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