cable_room 0.6.2.beta1 → 0.7.0.beta2

data/lib/cable_room/room_member.rb

@@ -1,9 +1,30 @@
 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
 
+    # How often a silent member reminds its room that it is alive. A member that has sent
+    # anything within this interval skips the ping (the room counts every inbound message as
+    # activity), so the room hears from a live member at least every 2 x PING_INTERVAL — which
+    # must stay under Room::PortManagement::PORT_TIMEOUT with margin for queue lag. Pings were
+    # ~30% of all room messages at 10 s with no skipping.
+    PING_INTERVAL = 15.seconds
+
     included do
-      periodically :ping_room_memberships, every: 10.seconds
+      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
@@ -12,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]
@@ -41,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
@@ -60,18 +148,28 @@ module CableRoom
       on_left: nil,
       tags: [],
       extra: nil,
+      tenant: nil,
       &preconfigure
     )
       @mutex = Monitor.new
 
       @has_left = false
       @has_established = false
+      @hello_received = false
 
       @cable_channel = cable_channel
       @room_class = room_class
       @room_key = room_key
       @allow_create = create
 
+      # Defaults to the ambient tenant right here, at join_room's own call site -- the member's
+      # own request thread, the last point before this room's work moves to a Host thread with no
+      # request of its own to derive one from (see Runner#initialize). An app only needs to pass
+      # `tenant:` explicitly to ask for something other than "whatever tenant this join is
+      # happening under", which is the common case. nil isn't a real tenant either way, so it
+      # doubles as "not given".
+      @tenant = tenant || (Apartment::Tenant.current if defined?(Apartment))
+
       @on_room_opened = on_room_opened
       @on_joined = on_joined
       @on_message = on_message
@@ -99,17 +197,95 @@ 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,
+        "tenant" => @tenant,
+      }
+    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
-        port_transmit(room_class::ROOM_IN_CHANNEL, { type: 'port_ping' }, secure_context: true)
-      elsif @streams_live
-        # Announced but never acknowledged. Our streams were already live when we announced (see
-        # initiate_connection), so this is not the subscribe race — 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 #<<), so re-announce instead
-        # of pinging: port_connected is idempotent on the room side (the port is merged,
-        # user_joined fires only once).
+      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?
+      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
@@ -140,37 +316,54 @@ module CableRoom
 
     def key; @room_key; end
 
-    # Every stream this membership opens reports back once it is live; the last one to come up
-    # sends port_connected (see initiate_connection).
-    #
-    # The adapter runs the liveness callback on its own terms — the async and inline adapters call
-    # it while holding their subscriber-map lock, the Redis adapter on the event loop — so nothing
-    # may happen inside it except a hop to a worker thread: taking @mutex there deadlocks against
-    # an initiate_connection that is mid-broadcast, and broadcasting from it re-enters the lock.
-    def stream_port(port, on_live: nil, **kwargs, &blk)
-      generation = @stream_generation
-      @streams_pending += 1
-      connection = @cable_channel.connection
-      super(port, **kwargs, on_live: lambda do
-        connection.worker_pool.async_invoke(self, :_stream_became_live, generation, connection: connection)
-        on_live&.call
-      end, &blk)
-    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
 
+      type = (data[:type] || data['type'])&.to_sym
       unless secure_context
-        t = (data[:type] || data['type']).to_sym
-        if room_class._system_message_types.include?(t)
-          logger.warn "Dropping attempt to send system message type: #{t.inspect}"
+        if room_class._system_message_types.include?(type)
+          logger.warn "Dropping attempt to send system message type: #{type.inspect}"
           return
         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
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     def room_port_key(port)
@@ -187,9 +380,10 @@ module CableRoom
         @has_established = true
         @on_joined&.call(self) if first_acknowledgement
       when 'room_opened'
-        # If our streams are not all live yet, the pending announcement covers this (and an early
-        # one would be acknowledged into a stream nobody is listening to yet).
-        transmit_port_connected if @streams_live
+        # 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!
@@ -211,17 +405,11 @@ module CableRoom
         @has_established = false
         @cable_channel._room_memberships << self
 
-        # port_connected must not go out until every stream below is live on the pubsub adapter.
-        # Subscribing is asynchronous and the room acknowledges on the private @token stream, so
-        # announcing first lets a fast room — in practice one on another server — reply into a
-        # stream nobody is listening to yet; the acknowledgement is lost and the membership never
-        # establishes. stream_port (overridden above) counts the streams it opens and the last one
-        # to come up announces (_stream_became_live). The generation discards confirmations from
-        # a previous connection that land after a rejoin!.
-        @stream_generation = (@stream_generation || 0) + 1
-        @streams_pending = 0
-        @streams_armed = false
-        @streams_live = false
+        # 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|
@@ -248,31 +436,27 @@ module CableRoom
 
         @preconfigure&.call(self)
 
-        # Streams whose adapter confirmed synchronously are already counted down; announce now if
-        # that was all of them, otherwise the last confirmation will.
-        @streams_armed = true
-        _announce_if_streams_live
+        transmit_port_connected if @hello_received
 
         maybe_provision_room
       end
     end
 
-    def _stream_became_live(generation)
-      @mutex.synchronize do
-        return unless generation == @stream_generation
-
-        @streams_pending -= 1
-        _announce_if_streams_live
-      end
-    end
-
-    # Under @mutex. Sends port_connected once per connection, when every stream opened by
-    # initiate_connection has been confirmed live.
-    def _announce_if_streams_live
-      return if @streams_live || !@streams_armed || @streams_pending > 0 || left?
+    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
 
-      @streams_live = true
-      transmit_port_connected
+      @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
+      @tenant = record["tenant"]
     end
 
     def transmit_port_connected
@@ -280,16 +464,56 @@ 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
 
-      @room_class.ensure(@room_key)
+      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
+
+      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,
+        # Whatever `join_room` was given for `tenant:` (nil for a single-tenant app). The Host has
+        # no request of its own to derive this from, so a multi-tenant app has to hand it over
+        # explicitly here rather than have the Runner guess at ambient state (see Runner#initialize).
+        tenant: @tenant,
+      }
+
+      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

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.beta1".freeze
+  VERSION = "0.7.0.beta2".freeze
 end