cable_room 0.6.2.beta3 → 0.7.0.beta1

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

data/lib/cable_room/room_member.rb

@@ -1,4 +1,8 @@
 module CableRoom
+  # Raised at subscribe time when `join_room` asks for something AnyCable can't deliver
+  # (see RoomMember#refuse_unsupported_under_anycable!).
+  class AnyCableUnsupported < ArgumentError; end
+
   module RoomMember
     extend ActiveSupport::Concern
 
@@ -12,6 +16,16 @@ module CableRoom
     included do
       periodically :ping_room_memberships, every: PING_INTERVAL
 
+      # Where MembershipStore::AnyCable keeps the memberships between anycable-rails' per-call
+      # channel instances. `state_attr_accessor` only exists once anycable-rails is loaded; without
+      # it the channel lives for the socket and the in-memory store is all there is. Private
+      # because every public method of a channel is an action a client can perform, and a client
+      # that could write this could claim another member's token.
+      if respond_to?(:state_attr_accessor)
+        state_attr_accessor MembershipStore::AnyCable::STATE_ATTRIBUTE
+        private MembershipStore::AnyCable::STATE_ATTRIBUTE, :"#{MembershipStore::AnyCable::STATE_ATTRIBUTE}="
+      end
+
       after_unsubscribe do
         to_close = _room_memberships.to_a
         _room_memberships.clear
@@ -19,13 +33,51 @@ module CableRoom
       end
     end
 
+    # The channel's memberships (a MembershipStore). RoomMembership registers itself here, so this
+    # has to stay public; treat it as internal and read `room_memberships` instead.
     def _room_memberships
-      @_room_memberships ||= Set.new
+      @_room_memberships ||= MembershipStore.for(self)
+    end
+
+    # True when anycable-rails is handling this channel: the connection carries an AnyCable socket,
+    # this instance exists for one RPC call only, its streams are held by anycable-go, and its
+    # timers never run. `anycabled?` is what anycable-rails itself checks; it only exists once the
+    # gem is loaded. (Public methods are actions; performing this one is harmless.)
+    def anycable_channel?
+      connection.respond_to?(:anycabled?) && !!connection.anycabled?
+    end
+
+    # The `hello` channel action. The browser performs it once ActionCable has confirmed the
+    # subscription (`connected()` in the JS client), which is the first moment every stream this
+    # channel opened is guaranteed live. Each membership announces itself to its room in response;
+    # nothing is announced before then. A channel with no memberships ignores it.
+    #
+    # Public methods on a channel are its actions, so every RoomMember channel accepts
+    # `perform("hello")` without further wiring.
+    def hello(_data = nil)
+      hello_room_memberships
+    end
+
+    # The `ping` channel action. Under ActionCable the channel's own timer pings, so a client that
+    # performs this is doing harmless extra work. Under AnyCable channel timers never run (there is
+    # no long-lived channel object to run them on), so the browser performs this every
+    # PING_INTERVAL and each membership turns it into port_ping. See README "Using AnyCable".
+    def ping(_data = nil)
+      ping_room_memberships
     end
 
     protected
 
+    # The memberships `join_room` created on this channel. Under AnyCable the instance variable
+    # `subscribed` assigned is gone by the next call; this still has them, rebuilt from the
+    # channel state.
+    def room_memberships
+      _room_memberships
+    end
+
     def join_room(room_class, room_key = nil, as: :not_given, forward: false, **kwargs, &blk)
+      refuse_unsupported_under_anycable!(forward: forward, callbacks: kwargs, block: blk)
+
       if forward
         # raise ArgumentError, "Cannot specify both `forward: true` and `on_message:`" if kwargs[:on_message]
         original_on_message = kwargs[:on_message]
@@ -48,6 +100,35 @@ module CableRoom
     def ping_room_memberships
       _room_memberships.each(&:ping!)
     end
+
+    # Under AnyCable, room→member broadcasts go anycable-go → socket and never pass through this
+    # process, and the channel object is rebuilt per call, so nothing here can run a proc when a
+    # message arrives. That rules out `forward: false` (nothing would deliver messages to the app),
+    # every `on_*:` callback, and a preconfigure block (custom stream handlers). Failing at
+    # subscribe time beats a join that silently never fires anything. RoomProxyChannel's own
+    # `forward` wrapper is added after this check, so it is exempt. Plain ActionCable: no-op.
+    UNSUPPORTED_UNDER_ANYCABLE_CALLBACKS = %i[on_joined on_message on_room_opened on_room_closed on_left].freeze
+
+    def refuse_unsupported_under_anycable!(forward:, callbacks:, block:)
+      return unless anycable_channel?
+
+      unsupported = []
+      unsupported << "forward: false" unless forward
+      unsupported.concat(UNSUPPORTED_UNDER_ANYCABLE_CALLBACKS.select { |cb| callbacks[cb] }.map { |cb| "#{cb}:" })
+      unsupported << "a preconfigure block" if block
+      return if unsupported.empty?
+
+      raise AnyCableUnsupported,
+        "join_room used #{unsupported.join(', ')} on an AnyCable-backed channel (#{self.class.name}). " \
+        "Under AnyCable room messages never pass through this process, so these can't work; " \
+        "use forward: true without callbacks (see README, \"Using AnyCable\")."
+    end
+
+    # Server-side entry point for the hello signal, for channels that learn the client is ready
+    # some other way than the `hello` action (a custom handshake message, for instance).
+    def hello_room_memberships
+      _room_memberships.each(&:hello!)
+    end
   end
 
   class RoomMembership
@@ -73,6 +154,7 @@ module CableRoom
 
       @has_left = false
       @has_established = false
+      @hello_received = false
 
       @cable_channel = cable_channel
       @room_class = room_class
@@ -106,11 +188,94 @@ module CableRoom
       @mutex.synchronize { @has_left }
     end
 
+    def hello_received?
+      @hello_received
+    end
+
+    # Whether room→member traffic reaches this object. Under ActionCable the streams opened in
+    # initiate_connection dispatch into handle_received_message. Under AnyCable anycable-go holds
+    # the streams and delivers them straight to the socket, so this process never sees a room
+    # message: acknowledgements, room_opened, and room_closed are invisible here, and none of the
+    # on_* callbacks can fire.
+    def hears_room?
+      !@cable_channel.anycable_channel?
+    end
+
+    # Whether the room has acknowledged this port, as far as this process can tell. Under
+    # ActionCable that is the acknowledgement itself. Under AnyCable the acknowledgement went to
+    # the socket, so the most this process knows is that hello went out; the browser, which does
+    # see port_acknowledged, owns the retry (README "Using AnyCable").
+    def presumed_established?
+      hears_room? ? @has_established : @hello_received
+    end
+
+    # Whether client input can be handed to the room. Under ActionCable input waits for the
+    # acknowledgement, because until then the room has no port to attribute it to. Under AnyCable
+    # it goes as soon as hello has: hello's port_connected and the input travel the same Bus
+    # channel from the same process, so the room sees them in that order, and a room that doesn't
+    # exist yet drops both the way ActionCable would have dropped the input.
+    def accepts_input?
+      !left? && presumed_established?
+    end
+
+    # What MembershipStore::AnyCable writes into the channel state: enough to rebuild this
+    # membership on a later RPC call (see .restore). Callbacks are procs and can't go; `extra`
+    # travels in the ActiveJob-serialized form the room deserializes, which needs no lookup here.
+    def persisted_identity
+      {
+        "token" => @token,
+        "room_class" => room_class.name,
+        "room_key" => @room_key,
+        "tags" => @tags,
+        "extra" => serialized_extra,
+        "create" => @allow_create,
+        "hello_received" => @hello_received,
+      }
+    end
+
+    # The inverse of #persisted_identity, for a channel instance anycable-rails built for one RPC
+    # call. The result can hello!, ping!, leave!, and forward input with the token the subscribe
+    # call created. It does not open streams (anycable-go still holds the ones subscribe opened)
+    # and does not announce itself (only hello! does); it carries no callbacks.
+    def self.restore(cable_channel, record)
+      membership = allocate
+      membership.send(:restore_from, cable_channel, record)
+      membership
+    end
+
+    # The client has said hello: its subscription is confirmed, so every stream this membership
+    # opened is live and the room's acknowledgement has somewhere to land. This is the only thing
+    # that lets port_connected go out — a membership that never hears hello never announces.
+    #
+    # Hello is remembered for the life of the membership, across rejoin!: the browser says it
+    # once per subscription, and a rejoin happens server-side without the browser knowing.
+    def hello!
+      return if left?
+
+      ActiveSupport::Notifications.instrument(
+        "hello_received.cable_room",
+        { membership: self, room_class: room_class, room_key: @room_key, channel: @cable_channel }
+      ) do
+        @hello_received = true
+        # Under AnyCable the next call starts from a fresh channel; it has to know hello happened.
+        @cable_channel._room_memberships.persist!
+        # A repeated hello re-announces, which is harmless: port_connected is idempotent room-side.
+        transmit_port_connected
+      end
+    end
+
     def ping!
       return if left?
-      if @has_established
+      if presumed_established?
+        # The room already heard from us if we sent anything since the last interval; the next
+        # ping lands within 2 x PING_INTERVAL of that, well inside PORT_TIMEOUT.
         port_transmit(room_class::ROOM_IN_CHANNEL, { type: 'port_ping' }, secure_context: true) unless recently_transmitted?
-      else
+      elsif @hello_received
+        # Announced but never acknowledged: the announcement or the acknowledgement was lost in
+        # transit, or the room did not exist yet. An unestablished membership silently drops
+        # everything the client sends (see RoomProxyChannel#receive), so re-announce instead of
+        # pinging: port_connected is idempotent on the room side (the port is merged, user_joined
+        # fires only once). Before hello there is nothing to heal — the client isn't ready.
         transmit_port_connected
       end
       @mutex.synchronize do
@@ -141,8 +306,11 @@ module CableRoom
 
     def key; @room_key; end
 
-    protected
+    # -- The member side of Ports ---------------------------------------------------------------
 
+    # Everything a member sends goes to its room, so it's published on the room's Bus channel for
+    # `port` (see Room::Base.inbound_channel). The room's Host is subscribed there and queues the
+    # message on the room. Public because `ports[:x] << msg` reaches it through a PortProxy.
     def port_transmit(port, data, secure_context: false)
       data[:mtok] = @token
 
@@ -154,11 +322,32 @@ module CableRoom
         end
       end
 
-      super(port, data)
+      CableRoom.bus.publish(room_class.inbound_channel(@room_key, port), data)
       # Pings don't count: a ping must never be the reason the next ping is skipped.
       @last_transmit_at = monotonic_now unless type == :port_ping
     end
 
+    # Room→member traffic arrives on ActionCable streams (the broadcaster publishes to them), so
+    # listening on a port is a plain stream_from on the member's channel.
+    #
+    # Subscribing is asynchronous: anything published to the port before the pubsub adapter
+    # confirms the subscription can be lost. ActionCable confirms the channel subscription to the
+    # client only after every stream is live, which is why members wait for the client's `hello`
+    # (see #hello!) rather than announcing themselves from here.
+    def stream_port(port, auto_close: true, &blk)
+      @cable_channel.stream_from(room_port_key(port), coder: ActiveSupport::JSON, &blk)
+      _streamed_ports << port if auto_close
+    end
+
+    def close_streamed_ports!
+      _streamed_ports.each do |port|
+        @cable_channel.stop_stream_from(room_port_key(port))
+      end
+      _streamed_ports.clear
+    end
+
+    protected
+
     def recently_transmitted?
       @last_transmit_at && (monotonic_now - @last_transmit_at) < RoomMember::PING_INTERVAL
     end
@@ -181,7 +370,10 @@ module CableRoom
         @has_established = true
         @on_joined&.call(self) if first_acknowledgement
       when 'room_opened'
-        transmit_port_connected
+        # The room we were waiting for just came up. Announce again if the client is ready;
+        # before hello the announcement waits for hello itself, and a premature one would be
+        # acknowledged into a stream the client isn't listening on yet.
+        transmit_port_connected if @hello_received
         @on_room_opened&.call(self)
       when 'room_closed'
         leave!
@@ -203,6 +395,12 @@ module CableRoom
         @has_established = false
         @cable_channel._room_memberships << self
 
+        # Subscribing is asynchronous, and the room acknowledges on the private @token stream. We
+        # never announce here: port_connected waits for the client's hello (see hello!), which
+        # only arrives after ActionCable has confirmed the subscription — that is, after every one
+        # of these streams is live. A rejoin! is the exception: hello already happened for this
+        # socket, so announce now and let ping! repeat it if the room misses it.
+
         # Listen to public/broadcast channel
         stream_port(room_class::ROOM_OUT_CHANNEL) do |message|
           handle_received_message(message)
@@ -228,15 +426,26 @@ module CableRoom
 
         @preconfigure&.call(self)
 
-        transmit_port_connected
+        transmit_port_connected if @hello_received
 
         maybe_provision_room
       end
     end
 
-    def transmit_subscription_confirmation(...)
-      super
-      transmit_port_connected
+    def restore_from(cable_channel, record)
+      @mutex = Monitor.new
+      @has_left = false
+      # Never learned here (see #hears_room?); the browser sees the acknowledgement instead.
+      @has_established = false
+
+      @cable_channel = cable_channel
+      @room_class = record.fetch("room_class").constantize
+      @room_key = record.fetch("room_key")
+      @token = record.fetch("token")
+      @tags = Array(record["tags"]).map(&:to_sym)
+      @serialized_extra = record["extra"]
+      @allow_create = record["create"] == true
+      @hello_received = record["hello_received"] == true
     end
 
     def transmit_port_connected
@@ -244,16 +453,52 @@ module CableRoom
         type: 'port_connected',
         tags: @tags,
       }
-      msg[:extra] = ::ActiveJob::Arguments.serialize([@extra]) if @extra
+      msg[:extra] = serialized_extra if serialized_extra
       port_transmit(room_class::ROOM_IN_CHANNEL, msg, secure_context: true)
     end
 
+    # `extra` as the room receives it. Serialized once: a restored membership only ever has this
+    # form (see #persisted_identity), a fresh one builds it from what join_room was given.
+    def serialized_extra
+      return @serialized_extra if defined?(@serialized_extra)
+
+      @serialized_extra = @extra ? ::ActiveJob::Arguments.serialize([@extra]) : nil
+    end
+
+    # Ask the rooms hosts to start our room if `create: true` asked for it and nobody has
+    # acknowledged us yet. This never starts a room in the member's process: it publishes a
+    # `provision` request on the Bus, and every Host (the web process's own in :inline, the
+    # `cable_room server` fleet in :remote) hears it and races for the room's lock, the least
+    # loaded one first (see CableRoom::Placement). One code path, both modes.
+    #
+    # Called at join and again on every ping until the room acknowledges the port, so a lost
+    # request costs at most one ping interval, and a room whose host died comes back on the next
+    # ping from any member. Once acknowledged the room plainly exists, so we stop asking.
     def maybe_provision_room
       return if left?
       return unless @allow_create
-      return if ChannelTracker.instance.shutdown?
+      return if @has_established
+
+      if CableRoom.config.inline?
+        # In :inline this process hosts rooms itself, so make sure its Host is up and listening
+        # before asking; otherwise the very first request in a fresh process would go unheard.
+        return if Host.instance.shutdown?
+      end
 
-      @room_class.ensure(@room_key)
+      request = {
+        type: "provision",
+        room_class: room_class.name,
+        # 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,
+      }
+
+      ActiveSupport::Notifications.instrument(
+        "provision_requested.cable_room",
+        { membership: self, room_class: room_class, room_key: @room_key, channel: @cable_channel, request: request }
+      ) do
+        CableRoom.bus.publish(Bus.provision_channel, request)
+      end
     end
   end
 end

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