cable_room 0.6.2 → 0.7.0.beta1

data/cable_room.gemspec

@@ -18,14 +18,17 @@ Gem::Specification.new do |spec|
   spec.summary       = "Build live Rooms on top of ActionCable"
   spec.homepage      = "https://instructure.com"
 
-  spec.files = Dir["{app,config,db,lib}/**/*", "README.md", "*.gemspec"]
+  spec.files = Dir["{app,config,db,exe,lib}/**/*", "README.md", "CHANGELOG.md", "*.gemspec"]
+  spec.bindir = "exe"
+  spec.executables = ["cable_room"]
   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.2"
+  # rediconn builds pools of redis-rb clients but doesn't declare the gem; the Bus needs it too
+  spec.add_dependency "redis", ">= 5.0"
 
-  spec.add_development_dependency "redis"
   spec.add_development_dependency 'rspec', '~> 3'
 end

data/exe/cable_room

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Loads only the CLI, not the gem: `cable_room server` boots the Rails app itself, and the app's
+# Gemfile is what should load CableRoom (so its Railtie runs at the usual time).
+require "cable_room/cli"
+
+exit CableRoom::CLI.new(ARGV).run

data/lib/cable_room/broadcaster.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module CableRoom
+  # How a Room pushes messages out to its members. Every room→member message (`from_room`, tag,
+  # user, and `mtok` streams, plus `Room::Base.send_message`) goes through one of these, so
+  # swapping the transport is a config change, not a code change.
+  #
+  # `CableRoom.config.broadcaster` picks the implementation:
+  #
+  #   :action_cable  -> ActionCableBroadcaster (the default; today's behavior)
+  #   :anycable      -> AnyCableBroadcaster (needs the optional `anycable-rails` gem)
+  #
+  # Every broadcaster answers `broadcast(stream, payload)`. Specs can swap in a recording fake
+  # with `Broadcaster.current = fake`; `CableRoom.reset_config!` drops it again.
+  module Broadcaster
+    # Raised when the config asks for a broadcaster whose gem isn't in the bundle.
+    class MissingDependency < LoadError; end
+
+    class << self
+      # The broadcaster the current config selects. Built once per config object and reused,
+      # so `CableRoom.reset_config!` or `CableRoom.configure` picks up a fresh one on the next
+      # call without anyone having to remember to clear a cache.
+      def current
+        config = CableRoom.config
+        return @current if @current && @current_config.equal?(config)
+
+        @current_config = config
+        @current = build(config.broadcaster)
+      end
+
+      # Replace the broadcaster for the life of the current config object. Meant for specs that
+      # need a fake without rspec-mocks; `CableRoom.reset_config!` builds a new config, which
+      # makes `current` rebuild from it and forget this one.
+      def current=(broadcaster)
+        @current_config = CableRoom.config
+        @current = broadcaster
+      end
+
+      # Builds the broadcaster named by `name`. Config already rejects unknown names, so the
+      # `else` branch only fires if someone bypasses config.
+      def build(name)
+        case name&.to_sym
+        when :action_cable
+          ActionCableBroadcaster.new
+        when :anycable
+          AnyCableBroadcaster.new
+        else
+          raise ArgumentError,
+                "CableRoom broadcaster must be one of #{Config::BROADCASTERS.map(&:inspect).join(', ')} " \
+                "(got #{name.inspect})"
+        end
+      end
+    end
+
+    # Publishes through the ActionCable server, which hands the message to whatever pubsub
+    # adapter the app configured (Redis, async, ...).
+    class ActionCableBroadcaster
+      def broadcast(stream, payload)
+        ActionCable.server.broadcast(stream, payload)
+      end
+    end
+
+    # Publishes through `AnyCable.broadcast`, so anycable-go fans the message out to sockets.
+    # Stream names are the same ones ActionCableBroadcaster uses, so a member subscribed through
+    # anycable-go sees the same traffic it would through ActionCable.
+    #
+    # `anycable-rails` is optional at runtime: it's only loaded when this broadcaster is built, and
+    # a missing gem raises MissingDependency naming what to add.
+    #
+    # Payload encoding: `ActionCable.server.broadcast` runs every message through its coder
+    # (ActiveSupport::JSON by default) and hands the pubsub adapter a JSON string; anycable-rails's
+    # own ActionCable adapter forwards that string to `AnyCable.broadcast` untouched, and
+    # anycable-go expects the `data` field to be a pre-encoded string. So we encode here with the
+    # same coder, and a member decodes the message exactly as it would from ActionCable.
+    class AnyCableBroadcaster
+      CODER = ActiveSupport::JSON
+      GEM_NAME = "anycable-rails"
+
+      class << self
+        # Loads AnyCable on first use. `anycable` (a dependency of anycable-rails) is what defines
+        # `AnyCable.broadcast`; requiring it rather than `anycable-rails` avoids re-running the
+        # Rails integration in a process that already booted without it.
+        def ensure_loaded!
+          return if defined?(::AnyCable) && ::AnyCable.respond_to?(:broadcast)
+
+          begin
+            require "anycable"
+          rescue LoadError
+            raise MissingDependency,
+                  "CableRoom broadcaster :anycable needs the #{GEM_NAME} gem. " \
+                  "Add `gem \"#{GEM_NAME}\"` to your Gemfile, or set broadcaster to :action_cable."
+          end
+        end
+      end
+
+      def initialize
+        self.class.ensure_loaded!
+      end
+
+      def broadcast(stream, payload)
+        publish(stream, encode(payload))
+      end
+
+      protected
+
+      # The one call that leaves the process. Fakes override this to record instead of publish.
+      def publish(stream, encoded_payload)
+        ::AnyCable.broadcast(stream, encoded_payload)
+      end
+
+      def encode(payload)
+        CODER.encode(payload)
+      end
+    end
+  end
+end

data/lib/cable_room/bus.rb

@@ -0,0 +1,372 @@
+require 'set'
+require 'active_support/json'
+
+module CableRoom
+  # The Redis bus that carries member-to-room traffic in every mode: `to_room` messages,
+  # provision requests, and the handoff data a room leaves behind when it migrates to another
+  # host. It's a thin layer over the `CABLEROOM_*` Redis connection (see `CableRoom.redis_pool`)
+  # that adds three things:
+  #
+  #   * One place that knows the channel and key names (`cr:{room_key}:in` and friends).
+  #   * JSON encoding on the way in and decoding on the way out, using the same coder the room
+  #     ports already use for ActionCable streams, so a bad payload fails at the publisher.
+  #   * A single subscriber thread that owns a dedicated pub/sub connection and hands each
+  #     decoded message to the handler registered for its channel.
+  #
+  # Ordering: Redis delivers messages on one channel in publish order, and one thread dispatches
+  # them one at a time, so a handler sees them in the order they were published. `subscribe`
+  # blocks until Redis confirms the subscription, so anything published after it returns is
+  # delivered.
+  #
+  # Handlers run on the subscriber thread. Keep them short (hand the work to a queue) and never
+  # block in them waiting on the bus itself. A handler is allowed to call `subscribe` and
+  # `unsubscribe`; those calls return without waiting when made from the subscriber thread,
+  # because the confirmation they'd wait for is delivered by that same thread.
+  class Bus
+    # Raised at the publisher when a payload can't be turned into JSON.
+    class EncodeError < ArgumentError; end
+
+    # Raised when Redis doesn't confirm a subscribe or unsubscribe within the timeout.
+    class TimeoutError < StandardError; end
+
+    KEY_PREFIX = "cr".freeze
+    DEFAULT_TIMEOUT = 5
+
+    class << self
+      # Pub/sub channel that a room's host listens on for member-to-room messages. A room's main
+      # inbound port has no suffix (`cr:{room_key}:in`); a custom inbound port gets one
+      # (`cr:{room_key}:in:{port}`), so every channel a room listens on shares one prefix.
+      # `Room::Base.inbound_channel` is what turns a room class, key, and port into these.
+      def inbound_channel(room_key, port = nil)
+        channel = room_channel(room_key, "in")
+        port.nil? ? channel : "#{channel}:#{port}"
+      end
+
+      # Pub/sub channel every host listens on for "someone wants room X to exist" requests.
+      def provision_channel
+        "#{KEY_PREFIX}:provision"
+      end
+
+      # Redis list where a migrating room's old host parks inbound messages until the new host
+      # has adopted the room.
+      def handoff_list(room_key)
+        room_channel(room_key, "handoff")
+      end
+
+      # Redis string (with a TTL) holding the frozen room's snapshot during a migration.
+      def snapshot_key(room_key)
+        room_channel(room_key, "snapshot")
+      end
+
+      # Pub/sub channel the adopting host publishes on once it has taken over the room.
+      def adopted_channel(room_key)
+        room_channel(room_key, "adopted")
+      end
+
+      private
+
+      def room_channel(room_key, suffix)
+        key = room_key.to_s
+        raise ArgumentError, "room_key can't be blank" if key.empty?
+        "#{KEY_PREFIX}:#{key}:#{suffix}"
+      end
+    end
+
+    # `redis_pool` defaults to `CableRoom.redis_pool` (looked up lazily so specs can swap it).
+    def initialize(redis_pool: nil)
+      @redis_pool = redis_pool
+
+      # Everything below is guarded by @mutex and changes are announced on @changed
+      @mutex = Mutex.new
+      @changed = ConditionVariable.new
+      @handlers = {}          # channel => handler; the channels we want to be subscribed to
+      @requested = Set.new    # channels we've sent SUBSCRIBE for in the current session
+      @confirmed = Set.new    # channels Redis has confirmed in the current session
+      @thread = nil           # the subscriber thread, nil when no channels are wanted
+      @session_live = false   # true while @subscriber_redis accepts commands from other threads
+      @subscriber_redis = nil
+    end
+
+    # ---- Publisher and plain key operations --------------------------------------------------
+
+    # Publish a JSON-encodable payload. Returns the number of subscribers that received it.
+    def publish(channel, payload)
+      encoded = encode(payload)
+      redis { |r| r.publish(channel, encoded) }
+    end
+
+    # Append one or more payloads to the end of a list. Returns the list's new length. With `ttl`
+    # (seconds or a Duration) the list's expiry is reset in the same round trip, so a list nobody
+    # deletes (a host that died mid-handoff) still goes away on its own.
+    def rpush(key, *payloads, ttl: nil)
+      encoded = payloads.map { |payload| encode(payload) }
+      return redis { |r| r.rpush(key, encoded) } unless ttl
+
+      seconds = ttl.to_i
+      raise ArgumentError, "ttl must be a positive number of seconds" unless seconds.positive?
+      length, = redis { |r| r.pipelined { |p| p.rpush(key, encoded); p.expire(key, seconds) } }
+      length
+    end
+
+    # The whole list, oldest first, decoded.
+    def lrange(key)
+      redis { |r| r.lrange(key, 0, -1) }.map { |raw| decode(raw) }
+    end
+
+    # Delete keys. Returns how many existed.
+    def del(*keys)
+      redis { |r| r.del(*keys) }
+    end
+
+    # Store a payload under a key that expires after `ttl` (seconds or an
+    # ActiveSupport::Duration). Migration uses this for snapshots so a dead handoff cleans
+    # itself up.
+    def set(key, payload, ttl:)
+      seconds = ttl.to_i
+      raise ArgumentError, "ttl must be a positive number of seconds" unless seconds.positive?
+      encoded = encode(payload)
+      redis { |r| r.set(key, encoded, ex: seconds) }
+    end
+
+    # The decoded payload stored under a key, or nil when there isn't one.
+    def get(key)
+      raw = redis { |r| r.get(key) }
+      raw.nil? ? nil : decode(raw)
+    end
+
+    # ---- Subscriber -------------------------------------------------------------------------
+
+    # Register `handler` for `channel` and block until Redis confirms the subscription. The
+    # handler is called as `handler.call(message, channel)` with the decoded message on the
+    # subscriber thread. Subscribing again to the same channel replaces the handler.
+    #
+    # Raises TimeoutError (and forgets the handler) if the subscription isn't confirmed in time,
+    # which usually means Redis is unreachable.
+    def subscribe(channel, timeout: DEFAULT_TIMEOUT, &handler)
+      raise ArgumentError, "subscribe needs a block to handle messages" unless handler
+      channel = channel.to_s
+
+      @mutex.synchronize do
+        @handlers[channel] = handler
+        if @thread
+          reconcile
+        else
+          start_subscriber_thread
+        end
+
+        return true if on_subscriber_thread?
+
+        begin
+          wait_until(timeout, "subscription to #{channel}") { @confirmed.include?(channel) }
+        rescue TimeoutError
+          @handlers.delete(channel)
+          reconcile
+          raise
+        end
+      end
+      true
+    end
+
+    # Drop the handler for `channel` and block until Redis confirms the unsubscribe. When no
+    # channels are left the subscriber thread exits, and this also waits for that. Returns
+    # false if the channel wasn't subscribed.
+    def unsubscribe(channel, timeout: DEFAULT_TIMEOUT)
+      channel = channel.to_s
+
+      @mutex.synchronize do
+        return false unless @handlers.delete(channel)
+        reconcile
+
+        return true if on_subscriber_thread?
+
+        wait_until(timeout, "unsubscribe from #{channel}") do
+          !@confirmed.include?(channel) && (@thread.nil? || @handlers.any?)
+        end
+      end
+      true
+    end
+
+    # Unsubscribe from everything and wait for the subscriber thread to exit.
+    def shutdown(timeout: DEFAULT_TIMEOUT)
+      @mutex.synchronize do
+        @handlers.clear
+        reconcile
+        return true if on_subscriber_thread?
+        wait_until(timeout, "subscriber thread to exit") { @thread.nil? }
+      end
+      true
+    end
+
+    # Channels Redis has confirmed we're subscribed to right now.
+    def subscribed_channels
+      @mutex.synchronize { @confirmed.to_a }
+    end
+
+    def subscribed?(channel)
+      @mutex.synchronize { @confirmed.include?(channel.to_s) }
+    end
+
+    def subscriber_alive?
+      thread = @mutex.synchronize { @thread }
+      !!thread&.alive?
+    end
+
+    private
+
+    def redis_pool
+      @redis_pool || CableRoom.redis_pool
+    end
+
+    def redis(&blk)
+      redis_pool.with(&blk)
+    end
+
+    def encode(payload)
+      ActiveSupport::JSON.encode(payload)
+    rescue StandardError => e
+      raise EncodeError, "payload can't be encoded as JSON: #{e.class}: #{e.message}"
+    end
+
+    def decode(raw)
+      ActiveSupport::JSON.decode(raw)
+    end
+
+    def on_subscriber_thread?
+      Thread.current == @thread
+    end
+
+    # The subscriber needs a connection of its own: a pub/sub connection can't run other
+    # commands, and it lives as long as there are subscriptions, so it must not be a pooled
+    # one (a small pool would run dry). Borrow a pooled client just long enough to dup it,
+    # which gives an unconnected client with the same settings and no pool ties.
+    def build_subscriber_redis
+      redis(&:dup)
+    end
+
+    def start_subscriber_thread
+      @thread = Thread.new { subscriber_loop }
+      @thread.name = "cable_room-bus-subscriber"
+      @thread.report_on_exception = false
+    end
+
+    # Runs on the subscriber thread. Each pass opens one pub/sub session covering every wanted
+    # channel; a session ends when the last channel is unsubscribed (normal) or the connection
+    # fails (reported, then retried with backoff). The loop exits once nothing is wanted.
+    def subscriber_loop
+      backoff = 0.1
+      loop do
+        channels = @mutex.synchronize do
+          if @handlers.empty?
+            @thread = nil
+            @changed.broadcast
+            return
+          end
+          @handlers.keys
+        end
+
+        begin
+          run_session(channels)
+          backoff = 0.1
+        rescue StandardError => e
+          CableRoom.report_error(e, bus: self, channels: channels)
+          sleep backoff
+          backoff = [backoff * 2, 5].min
+        end
+      end
+    end
+
+    def run_session(channels)
+      redis = build_subscriber_redis
+      @mutex.synchronize { @requested = Set.new(channels) }
+
+      # redis-rb blocks here until the subscription count drops to zero, calling back for every
+      # event. Other threads add and remove channels by sending commands on the same client.
+      redis.subscribe(*channels) do |on|
+        on.subscribe do |channel, _count|
+          @mutex.synchronize do
+            unless @session_live
+              # redis-rb has the pub/sub socket up once the first confirmation arrives, so from
+              # here on other threads may send SUBSCRIBE/UNSUBSCRIBE through it
+              @session_live = true
+              @subscriber_redis = redis
+            end
+            @confirmed << channel
+            reconcile
+            @changed.broadcast
+          end
+        end
+
+        on.unsubscribe do |channel, count|
+          @mutex.synchronize do
+            @confirmed.delete(channel)
+            @requested.delete(channel)
+            if count.zero?
+              # redis-rb closes the socket as soon as this callback returns, so stop other
+              # threads from writing to it. Anything wanted by then starts a fresh session.
+              @session_live = false
+              @subscriber_redis = nil
+            else
+              reconcile
+            end
+            @changed.broadcast
+          end
+        end
+
+        on.message do |channel, raw|
+          dispatch(channel, raw)
+        end
+      end
+    ensure
+      @mutex.synchronize do
+        @session_live = false
+        @subscriber_redis = nil
+        @requested.clear
+        @confirmed.clear
+        @changed.broadcast
+      end
+      redis&.close
+    end
+
+    # Bring the server-side subscription set in line with the handlers we hold. Only possible
+    # while a session is live; before that, the thread's first confirmation calls this to pick
+    # up anything added or removed while it was connecting. Caller must hold @mutex.
+    def reconcile
+      return unless @session_live
+
+      wanted = @handlers.keys
+      (wanted - @requested.to_a).each do |channel|
+        @requested << channel
+        @subscriber_redis.subscribe(channel)
+      end
+      (@requested.to_a - wanted).each do |channel|
+        @requested.delete(channel)
+        @subscriber_redis.unsubscribe(channel)
+      end
+    end
+
+    # Decode and hand one message to its handler. A handler that raises is reported and the
+    # thread carries on; one bad message must never take the bus down.
+    def dispatch(channel, raw)
+      handler = @mutex.synchronize { @handlers[channel] }
+      return unless handler # unsubscribed while the message was in flight
+
+      handler.call(decode(raw), channel)
+    rescue StandardError => e
+      CableRoom.report_error(e, bus: self, channel: channel, raw_message: raw)
+    end
+
+    # Wait on @changed until the block is true or the timeout passes. Caller must hold @mutex.
+    def wait_until(timeout, reason)
+      deadline = monotonic_now + timeout
+      until yield
+        remaining = deadline - monotonic_now
+        raise TimeoutError, "Timed out after #{timeout}s waiting for #{reason}" if remaining <= 0
+        @changed.wait(@mutex, remaining)
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end