cable_room 0.5.6.beta1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a40d9bc8bdd5485d15865fb687e644cc8ab0200548dada92f8e721f7ff16e4a
-  data.tar.gz: 635ed5e9748b870a80d2d2928e253eb19d22a78f3e0ea652cd8c96e06b9ecc9e
+  metadata.gz: e13e24ffec8569b5db51f53c822502dedcce3f96425fcdf4a538d35aafd9299e
+  data.tar.gz: 67ba91a549a4534691f6d293833b87b1bac932e35d2861d6413b7dd9de594f2d
 SHA512:
-  metadata.gz: 337ad6e6b5e715c6aec178b2fa0457b0fbc11ff95097434ddbe00e0ede2b9ab4dd06a166c2715ab8004cc79fc14fb7a16b6e832a5a9ed31eaf2e371144d18697
-  data.tar.gz: 162b71c4fb01cb900be4d9e4edf8a7d7cbbb0f35ab1b4cb5dc52f1552a980e239cbd5f1d96e627409f53061e5829baebf0357b284fa5c2608732e853e02d17b7
+  metadata.gz: 65340bae098563857d504f2353776f8a294b39d6b15324307134e9a67339e61ec9db24f91bc022419c6d6f5eb80884ed7313f11ef66ee1db62aa919d09324275
+  data.tar.gz: d598d42249d1e22de5f11b2201b6b9dfa7951ea3d9086397ab25b77d7b6f2d368038e751eb1e78da3ffad8af22befa885e6bd3ecf08498568227a9131da11776

data/cable_room.gemspec

@@ -19,13 +19,12 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://instructure.com"
 
   spec.files = Dir["{app,config,db,lib}/**/*", "README.md", "*.gemspec"]
-  spec.test_files = Dir["spec/**/*"]
   spec.require_paths = ['lib']
 
   spec.add_dependency "rails", ">= 7.2", "< 9.0"
   spec.add_dependency "rufus-scheduler", "~> 3.6"
   spec.add_dependency "redlock", "~> 2.0"
-  spec.add_dependency "rediconn", "~> 0.1.0"
+  spec.add_dependency "rediconn", "~> 0.1.2"
 
   spec.add_development_dependency "redis"
   spec.add_development_dependency 'rspec', '~> 3'

data/lib/cable_room/channel_base.rb

@@ -148,10 +148,25 @@ module CableRoom
       _post_wrapped_work(**kwargs) do
         worker_pool.invoke(self, :instance_exec, connection: self, &blk)
       rescue => e
-        logger.error "Error during work execution: #{e.class.name}: #{e.message}"
+        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
@@ -167,11 +182,13 @@ module CableRoom
     def start_periodic_timer(callback, every:)
       raise "Attempt to start periodic timer on a dead room" if state == :dead || state == :shutting_down
 
-      connection.server.scheduler.schedule_every(every) do
+      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
@@ -197,9 +214,27 @@ module CableRoom
     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, to: :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

data/lib/cable_room/channel_tracker.rb

@@ -94,6 +94,23 @@ module CableRoom
         ActionCable::Server::Worker.connection = pconn
       end
 
+      # ActionCable's Worker#invoke reduces every exception to a log line and a no-argument
+      # `handle_exception` call, which discards the error itself. Rooms run all of their work
+      # through here, so report it properly instead.
+      def invoke(receiver, method, *args, connection:, &block)
+        work(connection) do
+          receiver.send method, *args, &block
+        rescue Exception => e
+          if connection.respond_to?(:report_work_error)
+            connection.report_work_error(e)
+          else
+            logger.error "There was an exception - #{e.class}(#{e.message})"
+            logger.error Array(e.backtrace).join("\n")
+            CableRoom.report_error(e, connection: connection)
+          end
+        end
+      end
+
       def async_invoke(receiver, method, *args, connection: receiver, &block)
         # Instead of posting directly to the global pool, post to a dedicated queue for the room/"connection".
         #   This makes each rooms so that they can be processed by at-most-one thread at a time, while still
@@ -109,8 +126,5 @@ module CableRoom
       end
     end
 
-    Rufus::Scheduler::Job.class_eval do
-      alias_method :shutdown, :unschedule
-    end
   end
 end

data/lib/cable_room/room/base.rb

@@ -1,8 +1,8 @@
 module CableRoom
   module Room
     class Base
-      ROOM_OUT_CHANNEL = :from_room # Many-to-one channel for messages to the room
-      ROOM_IN_CHANNEL = :to_room # One-to-many channel for messages from the room
+      ROOM_OUT_CHANNEL = :from_room # One-to-many: messages the Room broadcasts out to its members
+      ROOM_IN_CHANNEL = :to_room # Many-to-one: messages members send in to the Room
 
       LOCK_DURATION = 15.seconds
       WATCH_DOG_INTERVAL = 15.seconds

data/lib/cable_room/room/channel_adapter.rb

@@ -7,13 +7,11 @@ module CableRoom
 
       class_methods do
         def inherited(subclass)
-          subclass.const_set(:Channel, Class.new(Channel))
+          # Descend from *this* class's Channel, so periodic timers and other channel-level
+          # configuration survive multiple levels of subclassing
+          subclass.const_set(:Channel, Class.new(self::Channel))
           super
         end
-
-        def open_rooms
-          ChannelTracker.room_channels.map(&:room)
-        end
       end
     end
   end

data/lib/cable_room/room/input_handling.rb

@@ -8,13 +8,26 @@ module CableRoom
 
       class_methods do
         def authorize_inbound(symbol_or_proc = nil, only: nil, except: nil, &blk)
-          raise ArgumentError, "Must provide either a symbol, proc, or block" unless symbol_or_proc ^ blk
+          unless symbol_or_proc.nil? ^ blk.nil?
+            raise ArgumentError, "Must provide exactly one of a symbol, proc, or block"
+          end
 
           only = Set.new(Array(only).map(&:to_sym)) if only
           except = Set.new(Array(except).map(&:to_sym)) if except
 
-          blk = symbol_or_proc if symbol_or_proc.is_a?(Proc)
-          blk = -> { send(symbol_or_proc) } if symbol_or_proc.is_a?(Symbol)
+          case symbol_or_proc
+          when nil then nil
+          when Proc then blk = symbol_or_proc
+          when Symbol
+            # Guard methods may take the message or read it off `message`
+            guard = symbol_or_proc
+            blk = proc do |msg|
+              m = method(guard)
+              m.arity == 0 ? m.call : m.call(msg)
+            end
+          else
+            raise ArgumentError, "Expected a symbol or proc, got #{symbol_or_proc.class}"
+          end
 
           set_callback(:receive_message, :before) do
             type = message['type'].to_s.underscore.to_sym

data/lib/cable_room/room/port_management.rb

@@ -15,7 +15,8 @@ module CableRoom
         end
 
         def inherited(subclass)
-          subclass.const_set(:PortClient, Class.new(PortClient))
+          # Descend from *this* class's PortClient, so customizations survive multiple levels of subclassing
+          subclass.const_set(:PortClient, Class.new(self::PortClient))
           super
         end
       end
@@ -28,22 +29,14 @@ module CableRoom
         on_port_connected { reply({type: 'port_acknowledged' }) }
 
         set_callback(:receive_message, :around) do |_, blk|
-          previous_mtok = @current_message_origin
-          begin
-            mtok = message['mtok']
-            @current_message_origin = mtok
-            blk.call
-          ensure
-            @current_message_origin = previous_mtok
-          end
+          with_message_origin(message['mtok']) { blk.call }
         end
 
         system_message_types(:port_connected, :port_disconnected, :port_ping)
 
-        require_relative 'port_policies'
         include PortPolicies
 
-        PortPolicies::TagPolicy.define_tag_alias :connect, [:port_connected, :port_ping, :port_disconnected]
+        define_tag_alias :connect, [:port_connected, :port_ping, :port_disconnected]
 
         inbound_tag_policy(priority: -10) do
           allow :*, :connect
@@ -58,7 +51,7 @@ module CableRoom
       def _apply_port_scope(client_port: nil, tag: nil, **kwargs)
         if client_port && tag
           client_port = resolve_client_port(client_port)
-          throw :abort unless client_port && client_port[:tags]&.include?(tag) || client_port[:as] == tag
+          throw :abort unless client_port && (client_port[:tags]&.include?(tag) || client_port[:as] == tag)
         end
 
         { client_port: client_port || tag, **kwargs }
@@ -92,6 +85,16 @@ module CableRoom
         @_port_clients[@current_message_origin]
       end
 
+      # Run the block with `message_origin` (and anything derived from it) resolving to the given port token.
+      # Used both while handling an inbound message and when the room itself acts on a port's behalf.
+      def with_message_origin(token)
+        previous = @current_message_origin
+        @current_message_origin = token
+        yield
+      ensure
+        @current_message_origin = previous
+      end
+
       def connected_clients
         @_port_clients.values
       end
@@ -110,7 +113,8 @@ module CableRoom
           mo.tag!(message['tags'])
 
           if policy_allows?(message['type'].to_sym)
-            mo.merge!(::ActiveJob::Arguments.deserialize(message['extra'])[0])
+            # `extra` is omitted entirely when the member joins without a user or extra metadata
+            mo.merge!(::ActiveJob::Arguments.deserialize(message['extra'])[0]) if message['extra']
 
             ActiveSupport::Notifications.instrument("port_connected.cable_room", { room: self, message: message }) do
               run_callbacks :port_connected do
@@ -139,13 +143,16 @@ module CableRoom
       def check_port_inactivity
         return unless @_port_clients
 
-        threshold = PORT_TIMEOUT.ago
-        @_port_clients.each do |mtok, data|
+        @_port_clients.to_a.each do |mtok, data|
           next if data.recently_seen?
 
-          ActiveSupport::Notifications.instrument("port_disconnected.cable_room", { room: self, reason: :timeout }) do
-            run_callbacks :port_disconnected do
-              on_port_disconnected
+          # Callbacks run before the client is dropped, and with the origin set, so that handlers
+          # (including user cleanup) can tell *which* port went away.
+          with_message_origin(mtok) do
+            ActiveSupport::Notifications.instrument("port_disconnected.cable_room", { room: self, reason: :timeout }) do
+              run_callbacks :port_disconnected do
+                on_port_disconnected
+              end
             end
           end
           @_port_clients.delete(mtok)

data/lib/cable_room/room/port_policies.rb

@@ -11,25 +11,43 @@ module CableRoom
           end
         end
 
+        # Declare that `key` covers the given methods, for this Room class and its subclasses.
+        # A rule written against `key` then applies to every method it implies.
+        def define_tag_alias(key, implies)
+          merged = _port_tag_aliases.each_with_object({}) { |(method, keys), acc| acc[method] = keys.dup }
+
+          Array(implies).each do |method|
+            (merged[method.to_sym] ||= Set.new) << key.to_sym
+          end
+
+          self._port_tag_aliases = merged
+          @_tag_policy = nil
+          merged
+        end
+
         def inbound_tag_policy(**kwargs, &blk)
           if blk
-            self._port_policy_blocks = [*(_port_policy_blocks || []), {
+            self._port_policy_blocks = [*_port_policy_blocks, {
               **kwargs,
               block: blk,
             }]
+            @_tag_policy = nil
           else
-            @_tag_policy ||= TagPolicy.new().tap do |pol|
-              (_port_policy_blocks || []).each do |p|
+            @_tag_policy ||= TagPolicy.new(_port_tag_aliases).tap do |pol|
+              _port_policy_blocks.each do |p|
                 pol.evaluate(**p.except(:block), &p[:block])
               end
             end
-            @_tag_policy
           end
         end
       end
 
       included do
-        class_attribute :_port_policy_blocks, instance_writer: false, default: {}
+        class_attribute :_port_policy_blocks, instance_writer: false, default: []
+
+        # Aliases are per Room class (inherited by subclasses), so one Room's vocabulary
+        # cannot change how another Room's policies are interpreted.
+        class_attribute :_port_tag_aliases, instance_writer: false, default: {}
 
         authorize_inbound do |message|
           msg_type = message['type'].to_s.underscore.to_sym
@@ -45,16 +63,10 @@ module CableRoom
       end
 
       class TagPolicy
-        ALIASES = {}
-
-        def self.define_tag_alias(key, implies)
-          Array(implies).each do |i|
-            ALIASES[i] ||= Set.new
-            ALIASES[i] << key
-          end
-        end
-
-        def initialize()
+        # `aliases` maps a method to the set of alias keys that cover it, and is owned by the
+        # Room class this policy was built for
+        def initialize(aliases = {})
+          @aliases = aliases
           @policy_rules = []
           @fallback_rule = { action: :allow, priority: -100, tag: :*, methods: :* }
           append_rule(@fallback_rule)
@@ -121,8 +133,8 @@ module CableRoom
           all_aliases << method
 
           bfs(method) do |m|
-            all_aliases.merge(ALIASES[m] || [])
-            ALIASES[m]
+            all_aliases.merge(@aliases[m] || [])
+            @aliases[m]
           end
 
           all_aliases << :*

data/lib/cable_room/room/threading.rb

@@ -3,10 +3,46 @@ module CableRoom
     module Threading
       extend ActiveSupport::Concern
 
-      # Run the given block in the background, so as not to block other operations w/i the Room
-      # (By default, rooms are single-threaded, so any work will block all other work from occurring.)
+      # Run the given block off the Room's thread, so slow work doesn't stop the Room from
+      # processing anything else.
+      #
+      # A Room is otherwise single-threaded: messages and timers run one at a time, which is what
+      # makes Room state safe to touch without locks. Work posted here deliberately escapes that
+      # queue and runs *concurrently* with the Room, so it must not reference Room state. Capture
+      # everything the block needs before posting it:
+      #
+      #   token = message_origin.token
+      #   async { expensive_lookup(token) }          # good - `token` was captured
+      #
+      #   async { expensive_lookup(message_origin) } # BAD - races the Room's thread
+      #
+      # In particular `message` is nil inside the block (it is thread-local to the Room's thread),
+      # and `message_origin` and `reply` refer to whatever the Room is handling *now* rather than
+      # what it was handling when `async` was called.
+      #
+      # `self` is still the Room, so instance methods resolve normally - which is exactly why the
+      # state rule matters. To act on the result, hand it back to the Room's thread:
+      #
+      #   token = message_origin.token
+      #   async do
+      #     result = expensive_lookup(token)
+      #     on_room_thread { broadcast({ type: 'result', result: result }, client_port: token) }
+      #   end
+      #
+      # Exceptions are reported through CableRoom.error_handler, the same as any other Room work.
+      #
+      # Note that this borrows a thread from the worker pool shared by every Room in the process,
+      # so blocking a Room's thread waiting on async work can starve other Rooms. Prefer handing
+      # results back with `on_room_thread` over waiting for them.
       def async(&blk)
-        @cable_channel.post_work(thread_safe: true, &blk)
+        room = self
+        @cable_channel.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) }
       end
     end
   end

data/lib/cable_room/room/user_management.rb

@@ -27,7 +27,7 @@ module CableRoom
 
         system_message_types(:user_joined, :user_left)
 
-        PortPolicies::TagPolicy.define_tag_alias :join, [:connect, :user_joined, :user_left]
+        define_tag_alias :join, [:connect, :user_joined, :user_left]
 
         inbound_tag_policy(priority: -10) do
           allow :*, :join

data/lib/cable_room/room.rb

@@ -15,6 +15,7 @@ module CableRoom
 
       autoload :PortScoping
       autoload :PortManagement
+      autoload :PortPolicies
       autoload :UserManagement
       autoload :Broadcasting
     end

data/lib/cable_room/version.rb

@@ -1,3 +1,3 @@
 module CableRoom
-  VERSION = "0.5.6.beta1".freeze
+  VERSION = "0.6.0".freeze
 end

data/lib/cable_room.rb

@@ -19,6 +19,23 @@ require_relative 'cable_room/version'
 
 module CableRoom
   class << self
+    # Called as `handler.call(error, context)` whenever work inside a Room raises. Rooms swallow
+    # exceptions so that one bad message can't kill the Room, which makes this the only way to
+    # find out that it happened. Set it to forward to your error reporter:
+    #
+    #   CableRoom.error_handler = ->(error, context) { Sentry.capture_exception(error, extra: context) }
+    #
+    # An "error.cable_room" ActiveSupport notification is emitted regardless.
+    attr_accessor :error_handler
+
+    def report_error(error, **context)
+      ActiveSupport::Notifications.instrument("error.cable_room", { error: error, **context })
+      error_handler&.call(error, context)
+    rescue => handler_error
+      # A broken reporter must never mask the failure it was reporting
+      warn "CableRoom.error_handler raised #{handler_error.class}: #{handler_error.message}"
+    end
+
     def redis_pool
       require 'rediconn'
       @redis_pool ||= RediConn::RedisConnection.create(env_prefix: "CABLEROOM")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cable_room
 version: !ruby/object:Gem::Version
-  version: 0.5.6.beta1
+  version: 0.6.0
 platform: ruby
 authors:
 - Ethan Knapp
@@ -63,14 +63,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: redis
   requirement: !ruby/object:Gem::Requirement
@@ -128,16 +128,6 @@ files:
 - lib/cable_room/room_member.rb
 - lib/cable_room/room_proxy_channel.rb
 - lib/cable_room/version.rb
-- spec/cable_room/e2e_room_spec.rb
-- spec/cable_room/room_member_spec.rb
-- spec/internal/config/cable.yml
-- spec/internal/config/database.yml
-- spec/internal/config/routes.rb
-- spec/internal/config/storage.yml
-- spec/internal/db/schema.rb
-- spec/internal/log/test.log
-- spec/internal/public/favicon.ico
-- spec/spec_helper.rb
 homepage: https://instructure.com
 licenses: []
 metadata: {}
@@ -158,14 +148,4 @@ requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
 summary: Build live Rooms on top of ActionCable
-test_files:
-- spec/cable_room/e2e_room_spec.rb
-- spec/cable_room/room_member_spec.rb
-- spec/internal/config/cable.yml
-- spec/internal/config/database.yml
-- spec/internal/config/routes.rb
-- spec/internal/config/storage.yml
-- spec/internal/db/schema.rb
-- spec/internal/log/test.log
-- spec/internal/public/favicon.ico
-- spec/spec_helper.rb
+test_files: []