cable_room 0.6.2 → 0.7.0.beta1

data/lib/cable_room/room_proxy_channel.rb

@@ -13,12 +13,17 @@ module CableRoom
       @room_membership = subscribe_to_room
     end
 
+    # The channel's actions are `hello` and `ping` (inherited from RoomMember: the client performs
+    # hello once its subscription is confirmed, and the membership announces itself to the room)
+    # and `receive`, which pipes everything else the client sends into the room. Until the room
+    # has acknowledged the membership (or, under AnyCable, until hello has gone out — see
+    # RoomMembership#accepts_input?) there is nowhere for input to go, so it is dropped.
     def receive(data)
-      @room_membership << data if @room_membership&.connected?
+      room_membership << data if room_membership&.accepts_input?
     end
 
     def unsubscribed
-      @room_membership&.leave!
+      room_membership&.leave!
     end
 
     protected
@@ -27,6 +32,12 @@ module CableRoom
       raise NotImplementedError
     end
 
+    # The membership `subscribed` created. Under AnyCable this channel instance may not be the one
+    # that ran `subscribed`, so fall back to the memberships rebuilt from the channel state.
+    def room_membership
+      @room_membership ||= room_memberships.first
+    end
+
     def join_room(*args, **kwargs, &blk)
       kwargs[:forward] = true
       super

data/lib/cable_room/snapshot.rb

@@ -0,0 +1,136 @@
+module CableRoom
+  # The gem-owned picture of a running room, as one JSON document, so a room can be rebuilt on
+  # another host with its members none the wiser. `take` produces it from a frozen room (see
+  # Host::Runner#freeze!); `Host#restore_room` consumes it. Version 1 looks like this (string
+  # keys, because it has been through JSON):
+  #
+  #   {
+  #     "version"      => 1,
+  #     "room_class"   => "QuizRoom",
+  #     "key"          => <room key>,                # ActiveJob-serialized, so a record key travels as a GlobalID
+  #     "port_clients" => [
+  #       {
+  #         "token"        => "3f9a...",
+  #         "tags"         => ["admin"],
+  #         "as"           => <user or nil>,         # ActiveJob-serialized (GlobalID for records)
+  #         "last_seen_at" => "2026-08-27T18:02:11.123456Z",
+  #         "metadata"     => { ... }                # everything else on the PortClient: what `extra:`
+  #       }                                          # merged in, plus anything the room set on it
+  #     ],
+  #     "user_state"   => [{ "user" => <user>, "port_tokens" => ["3f9a..."] }],
+  #     "reaper_state" => [{ "key" => "idle", "index" => 0, "last_keep_at" => "<ISO8601>" | nil }],
+  #     "app_state"    => <whatever the Room's snapshot_state returned, or nil>
+  #   }
+  #
+  # `reaper_state` carries wall-clock times, not remaining durations, so a room restored on
+  # another host keeps the same deadline it had. `app_state` has to be JSON: plain hashes,
+  # arrays, strings, numbers, booleans, and nil. We check that here, at snapshot time, because a
+  # value that JSON would quietly turn into something else (a Time into a string, a record into
+  # its attributes) is a bug that would otherwise only show up in `restore_state` on some other
+  # machine.
+  module Snapshot
+    VERSION = 1
+
+    class Error < StandardError; end
+
+    # `snapshot_state` returned something JSON can't carry faithfully.
+    class NotSerializable < Error; end
+
+    # The snapshot was written by a gem version this one doesn't understand.
+    class UnknownVersion < Error; end
+
+    # The snapshot doesn't name a room class this process knows.
+    class UnknownRoomClass < Error; end
+
+    class << self
+      # The snapshot of `room`, already round-tripped through JSON, so what you get back is
+      # exactly what a restore will see after a trip through Redis.
+      def take(room)
+        room.send(:_snapshot)
+      end
+
+      # Check a snapshot before anything is built from it. Returns the snapshot with string keys,
+      # so callers can read it the same way whether it came straight from `take` or from Redis.
+      def validate!(snapshot)
+        snapshot = snapshot.to_h.deep_stringify_keys
+        version = snapshot["version"]
+        unless version == VERSION
+          raise UnknownVersion, "Snapshot version #{version.inspect} isn't supported (this gem writes version #{VERSION})"
+        end
+
+        snapshot
+      end
+
+      def room_class_for(snapshot)
+        name = snapshot["room_class"]
+        klass = name.to_s.safe_constantize
+        unless klass.is_a?(Class) && klass <= Room::Base
+          raise UnknownRoomClass, "Snapshot names #{name.inspect}, which isn't a CableRoom::Room::Base subclass here"
+        end
+        klass
+      end
+
+      def key_for(snapshot)
+        deserialize_argument(snapshot["key"])
+      end
+
+      # Encode and decode the whole document, so the result is the post-JSON shape (string keys,
+      # ISO8601 times) rather than the Ruby objects the room held.
+      def round_trip(document)
+        ActiveSupport::JSON.decode(ActiveSupport::JSON.encode(document))
+      end
+
+      # Walk `value` and raise NotSerializable at the first thing JSON can't carry unchanged. Hash
+      # keys may be symbols (they come back as strings, and restore_state gets an indifferent-access
+      # hash); symbol *values* are refused because they'd come back as plain strings.
+      def assert_json!(value, room:, path: "app_state")
+        case value
+        when nil, true, false, String, Integer
+          nil
+        when Float
+          raise_not_serializable(room, path, "#{value} isn't a finite number") unless value.finite?
+        when Hash
+          value.each do |k, v|
+            unless k.is_a?(String) || k.is_a?(Symbol)
+              raise_not_serializable(room, path, "has a #{k.class} key (#{k.inspect}); JSON object keys must be strings")
+            end
+            assert_json!(v, room: room, path: "#{path}[#{k.inspect}]")
+          end
+        when Array
+          value.each_with_index { |v, i| assert_json!(v, room: room, path: "#{path}[#{i}]") }
+        when Symbol
+          raise_not_serializable(room, path, "is the Symbol #{value.inspect}; JSON has no symbols, so restore_state would get a String back. Use a string")
+        else
+          raise_not_serializable(room, path, "is a #{value.class}, which JSON can't carry. Reduce it to hashes, arrays, strings, numbers, booleans, and nil (records by id)")
+        end
+      end
+
+      # Room keys and users go through the same serializer members use on the wire
+      # (RoomMembership#transmit_port_connected), so a record travels as its GlobalID and
+      # strings, numbers, and symbols come back as themselves.
+      def serialize_argument(value)
+        ::ActiveJob::Arguments.serialize([value]).first
+      end
+
+      def deserialize_argument(value)
+        ::ActiveJob::Arguments.deserialize([value]).first
+      end
+
+      def encode_time(time)
+        time&.getutc&.iso8601(6)
+      end
+
+      def decode_time(value)
+        return nil if value.blank?
+        value.is_a?(Time) ? value : Time.iso8601(value)
+      end
+
+      private
+
+      def raise_not_serializable(room, path, detail)
+        raise NotSerializable,
+          "#{room.class.name}[#{room.key.inspect}]: snapshot_state returned something that isn't JSON: #{path} #{detail}"
+      end
+    end
+  end
+end

data/lib/cable_room/version.rb

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

data/lib/cable_room.rb

@@ -8,10 +8,18 @@ require 'redlock'
 require 'rufus-scheduler'
 
 require_relative 'cable_room/railtie'
+require_relative 'cable_room/config'
+require_relative 'cable_room/broadcaster'
 
-require_relative 'cable_room/channel_base'
-require_relative 'cable_room/channel_tracker'
+require_relative 'cable_room/bus'
+
+require_relative 'cable_room/periodic_timer'
+require_relative 'cable_room/snapshot'
+require_relative 'cable_room/host'
+require_relative 'cable_room/placement'
+require_relative 'cable_room/migration'
 require_relative 'cable_room/ports'
+require_relative 'cable_room/membership_store'
 require_relative 'cable_room/room_member'
 require_relative 'cable_room/room_proxy_channel'
 require_relative 'cable_room/room/'
@@ -36,6 +44,27 @@ module CableRoom
       warn "CableRoom.error_handler raised #{handler_error.class}: #{handler_error.message}"
     end
 
+    # The active CableRoom::Config. Built on first use with the defaults plus any env
+    # overrides, so an app that never calls `configure` still gets a valid config.
+    def config
+      @config ||= Config.new.apply_env_overrides.validate!
+    end
+
+    # Yields the config so an app can set the knobs, then re-applies the env overrides
+    # (CABLE_ROOM_HOST, CABLE_ROOM_BROADCASTER) and checks every value. Bad values raise
+    # here, at boot, instead of somewhere deep in a room later.
+    def configure
+      cfg = @config || Config.new
+      yield cfg if block_given?
+      @config = cfg.apply_env_overrides.validate!
+    end
+
+    # Drops the current config so the next `config` call rebuilds it, which also makes
+    # `Broadcaster.current` rebuild (and forget any `Broadcaster.current=` override). Meant for specs.
+    def reset_config!
+      @config = nil
+    end
+
     def redis_pool
       require 'rediconn'
       @redis_pool ||= RediConn::RedisConnection.create(env_prefix: "CABLEROOM")
@@ -50,5 +79,31 @@ module CableRoom
         CableRoom.redis,
       ])
     end
+
+    # The process-wide Redis bus (see CableRoom::Bus). Built on first use.
+    def bus
+      @bus ||= Bus.new
+    end
+
+    # Call this in a child process right after `fork`, before it touches Redis or hosts a room.
+    # `cable_room server --workers N` does it for every worker (see Host::Supervisor).
+    #
+    # A forked child starts with copies of the parent's objects but only one thread, so anything
+    # that owns a socket or a thread is broken in the child: the Bus subscriber thread doesn't
+    # exist, its mutex may be held by nobody, and a Redis socket is shared with the parent, so
+    # both processes would read each other's replies. Dropping the memos means the next caller
+    # builds fresh ones. The connection pool and redis-client also notice the fork on their own
+    # (both hook `Process._fork` and drop inherited sockets), and Rails does the same for
+    # ActiveRecord, so those need nothing from us; this keeps the gem's rule simple: nothing
+    # Redis-backed survives a fork.
+    #
+    # The Host goes too. A parent that forks workers must never host rooms itself, and a Host
+    # copied from a parent would have no worker threads and no scheduler thread behind it.
+    def after_fork!
+      @bus = nil
+      @lock_manager = nil
+      @redis_pool = nil
+      Host.replace_current(nil)
+    end
   end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: cable_room
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0.beta1
 platform: ruby
 authors:
 - Ethan Knapp
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -77,14 +77,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: '5.0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -101,32 +101,48 @@ dependencies:
         version: '3'
 email:
 - eknapp@instructure.com
-executables: []
+executables:
+- cable_room
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
 - cable_room.gemspec
+- exe/cable_room
 - lib/cable_room.rb
-- lib/cable_room/channel_base.rb
-- lib/cable_room/channel_tracker.rb
+- lib/cable_room/broadcaster.rb
+- lib/cable_room/bus.rb
+- lib/cable_room/cli.rb
+- lib/cable_room/config.rb
+- lib/cable_room/host.rb
+- lib/cable_room/host/bus_inbound.rb
+- lib/cable_room/host/runner.rb
+- lib/cable_room/host/supervisor.rb
+- lib/cable_room/host/worker_pool.rb
+- lib/cable_room/membership_store.rb
+- lib/cable_room/migration.rb
+- lib/cable_room/periodic_timer.rb
+- lib/cable_room/placement.rb
 - lib/cable_room/ports.rb
 - lib/cable_room/railtie.rb
 - lib/cable_room/room.rb
 - lib/cable_room/room/base.rb
 - lib/cable_room/room/broadcasting.rb
 - lib/cable_room/room/callbacks.rb
-- lib/cable_room/room/channel_adapter.rb
+- lib/cable_room/room/host_adapter.rb
 - lib/cable_room/room/input_handling.rb
 - lib/cable_room/room/lifecycle.rb
 - lib/cable_room/room/port_management.rb
 - lib/cable_room/room/port_policies.rb
 - lib/cable_room/room/port_scoping.rb
 - lib/cable_room/room/reaping.rb
+- lib/cable_room/room/snapshotting.rb
 - lib/cable_room/room/threading.rb
 - lib/cable_room/room/user_management.rb
 - lib/cable_room/room_member.rb
 - lib/cable_room/room_proxy_channel.rb
+- lib/cable_room/snapshot.rb
 - lib/cable_room/version.rb
 homepage: https://instructure.com
 licenses: []

data/lib/cable_room/channel_base.rb

@@ -1,262 +0,0 @@
-module CableRoom
-  class ChannelBase < ActionCable::Channel::Base
-    attr_reader :room, :tenant
-    attr_reader :server, :logger
-    delegate :event_loop, :worker_pool, :pubsub, to: :server
-
-    def initialize(lock_info, room_class, key, config)
-      # We don't really have a "connection" in the ActionCable sense, so
-      #   stuff in something that half looks like one
-      super(DummyConnection.new(self), "Room[]", {})
-
-      # Used mainly for logs and being able to follow a specific Room instance
-      @uuid = SecureRandom.hex(6)
-
-      @mutex = Monitor.new
-      @lock_info = lock_info
-      @current_state = :initializing
-
-      @tenant = Apartment::Tenant.current if defined?(Apartment)
-
-      @server = ChannelTracker.instance
-      @logger = ActionCable::Connection::TaggedLoggerProxy.new(
-        @server.logger,
-        tags: ["#{room_class.name} #{@uuid}"]
-      )
-
-      logger.info "Initializing new #{room_class.name}"
-      logger.info "  UUID: #{@uuid}"
-      logger.info "  Key: #{room_class.room_port_key(key)}"
-
-      @watchdog_interval = config[:watchdog_interval]
-      @lock_duration = config[:lock_duration]
-
-      @processing_work = false
-      @work_queue = []
-
-      @room = room_class.new(self, key)
-      @server.track_room_channel self
-      ping_watchdog
-    end
-
-    def self.channel_name
-      module_parent.name
-    end
-
-    # def stream_from(...) # TODO Try making sync
-    #   raise ArgumentError, "Block required" unless block_given?
-    #   super
-    # end
-
-    def stream_from(broadcasting, callback = nil, coder: nil, &block)
-      raise ArgumentError, "Block required" unless block.present?
-
-      broadcasting = String(broadcasting)
-
-      # Build a stream handler by wrapping the user-provided callback with a decoder
-      # or defaulting to a JSON-decoding retransmitter.
-      handler = worker_pool_stream_handler(broadcasting, callback || block, coder: coder)
-      streams[broadcasting] = handler
-
-      pubsub.subscribe(broadcasting, handler, lambda do
-        logger.info "#{self.class.name} is streaming from #{broadcasting}"
-      end)
-    end
-
-    def state
-      @current_state
-    end
-
-    after_subscribe do
-      begin
-        @current_state = :starting
-        @room.send(:_startup)
-        @current_state = :started
-      rescue => e
-        terminate!
-        raise e
-      end
-    end
-
-    after_unsubscribe do
-      @mutex.synchronize do
-        @current_state = :shutting_down
-        stop_all_streams
-        begin
-          @room.send(:_shutdown)
-        ensure
-          terminate!
-        end
-      end
-    end
-
-    def ping_watchdog
-      return if state == :dead
-
-      logger.debug "Ping watchdog"
-      @last_watchdog_ping_at = Time.current
-    end
-
-    def check_room_watchdog
-      @mutex.synchronize do
-        return if state == :dead || state == :shutting_down
-      end
-
-      relock = CableRoom.lock_manager.lock(@lock_info[:resource], @lock_duration.in_milliseconds, extend: @lock_info)
-      unless relock
-        logger.warn "Lost lock, shutting down"
-        unsubscribe_from_channel
-        return
-      end
-
-      unless @last_watchdog_ping_at && @last_watchdog_ping_at > @watchdog_interval.ago
-        logger.warn "Watchdog timeout for room #{@room.class.name}[#{@room.key}], shutting down"
-        initiate_shutdown("Watchdog timeout")
-        return
-      end
-    end
-
-    def initiate_shutdown(reason)
-      @mutex.synchronize do
-        return if @current_state == :dead || @current_state == :shutting_down
-
-        logger.info "Initiating shutdown: #{reason}"
-
-        # Stop streams immediately to prevent further messages from being added
-        stop_all_streams
-
-        # Append the final unsubscribe to the work queue so we can process remaining messages first
-        post_work(async: false) do
-          unsubscribe_from_channel
-        end
-
-        @current_state = :shutting_down
-      end
-    end
-
-    def terminate!
-      @mutex.synchronize do
-        stop_all_streams
-        @current_state = :dead
-        CableRoom.lock_manager.unlock(@lock_info) if @lock_info
-        server.untrack_room_channel self
-      end
-    end
-
-    def _post_wrapped_work(async: false, silent: false, &blk)
-      if async
-        # Async stuff is mostly untracked - we just post it to the worker pool and forget about it
-        worker_pool.executor.post(&blk)
-      else
-        @mutex.synchronize do
-          if @current_state == :dead || @current_state == :shutting_down
-            raise "Attempt to post work to dead or shutting down room" unless silent
-            return
-          end
-          @work_queue << blk
-        end
-        schedule_work
-      end
-    end
-
-    def post_work(**kwargs, &blk)
-      _post_wrapped_work(**kwargs) do
-        worker_pool.invoke(self, :instance_exec, connection: self, &blk)
-      rescue => e
-        report_work_error(e)
-      end
-    end
-
-    # Work errors are swallowed so one bad message can't take the Room down with it. Log the
-    # backtrace and hand the error to the application so the failure is still discoverable.
-    def report_work_error(error)
-      logger.error "Error during work execution: #{error.class.name}: #{error.message}"
-      Array(error.backtrace).first(20).each { |line| logger.error "  #{line}" }
-
-      CableRoom.report_error(
-        error,
-        room: room,
-        room_class: room&.class,
-        room_key: room&.key,
-        channel: self
-      )
-    end
-
-    def beat
-      post_work(async: true) do
-        check_room_watchdog
-      end
-    end
-
-    def transmit(*args)
-      logger.info("Channel.transmit called, ignoring: #{args.inspect}")
-    end
-
-    protected
-
-    def start_periodic_timer(callback, every:)
-      raise "Attempt to start periodic timer on a dead room" if state == :dead || state == :shutting_down
-
-      job = connection.server.scheduler.schedule_every(every) do
-        post_work(async: false, silent: true) do
-          instance_exec(&callback)
-        end
-      end
-
-      PeriodicTimer.new(job)
-    end
-
-    def schedule_work
-      @mutex.synchronize do
-        return if @processing_work
-
-        work = @work_queue.shift
-        return unless work
-
-        @processing_work = true
-
-        worker_pool.executor.post do
-          begin
-            work.call
-          ensure
-            @mutex.synchronize do
-              @processing_work = false
-            end
-            schedule_work
-          end
-        end
-      end
-    end
-  end
-
-  # ActionCable's `stop_periodic_timers` calls #shutdown on whatever #start_periodic_timer
-  # returned, but Rufus jobs are cancelled with #unschedule. Adapt the one to the other here
-  # rather than aliasing #shutdown onto Rufus::Scheduler::Job for the whole process.
-  class PeriodicTimer
-    attr_reader :job
-
-    delegate :unschedule, :scheduled?, :next_time, to: :job
-
-    def initialize(job)
-      @job = job
-    end
-
-    def shutdown
-      job.unschedule
-    end
-  end
-
-  class DummyConnection
-    attr_reader :channel
-    delegate :server, :logger, :tenant, :transmit, :post_work, :_post_wrapped_work,
-             :report_work_error, to: :channel
-    delegate :event_loop, :pubsub, :worker_pool, to: :server
-
-    attr_reader :identifiers
-
-    def initialize(channel)
-      @channel = channel
-      @identifiers = []
-    end
-  end
-end