cable_room 0.8.0.beta1 → 0.8.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c01eff2a2851ae08dbbdfd83e8e168c874ba57eba33d473c2d1142b6f08bd5f
-  data.tar.gz: 29956f4064236b00b416e947813f60ec35602964df2825c84257c4d3e6030044
+  metadata.gz: d0506851a3e7f5f160cc74d3c114f0233b91322b2c0037ae63a641c7486876c7
+  data.tar.gz: 448745b3feb776e0d3e32f3a720f3c25b549cc66659056911b2d6a6ae5116891
 SHA512:
-  metadata.gz: 4b1b1b7bbf0d1482076987191905c32fe064357639558cb83f9964636e2dfb2436b65d67195a2ef342efce7a9114374c785a043183d9e060e6671605a9e18994
-  data.tar.gz: 6119631c493af515e52a2d69ef7d796b0b27b22684faeb0c75aacade5ef50793d1b6983f0ecadf8c7718ade8f4bc602bfc689ca5f100c99b5233d9c7949a67be
+  metadata.gz: 7c41faeb794a2f112471ecf9202693a237f0839e63493df9100383b21bf151029f915eff74f8b2cf70980a51290eeb5a85a5cdc1cb675168d1aa1ee25eb7db2c
+  data.tar.gz: c0cdfaa13741102891ed4951d59b521ddd82671e73634ec23c68eac4eb9528a829c02a323feff95219e46b312119ef8c797e29ad021547551772e132583ca0be

data/cable_room.gemspec

@@ -18,14 +18,21 @@ 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", "*.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"
+  # Workaround approved October 2, 2026: rediconn requires "redis" at load time but only declares
+  # it as a development dependency, so cable_room declares it instead. Drop this once rediconn
+  # does. The Bus needs >= 5: redis-rb 4 holds its client lock for the whole SUBSCRIBE loop, so
+  # another thread can't add a channel to a live session. The ceiling matches ActionCable 8.1's
+  # Redis adapter (7.2's is "< 6"), so apps on that adapter still resolve.
+  spec.add_dependency "redis", ">= 5", "< 7"
 
-  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/bus.rb

@@ -0,0 +1,342 @@
+require 'set'
+require 'redis'
+require 'active_support/json'
+
+module CableRoom
+  # The Redis pub/sub bus for member-to-room traffic. It's a thin layer over the `CABLEROOM_*`
+  # Redis connection (see `CableRoom.redis_pool`) that adds three things:
+  #
+  #   * One place that knows the channel names (`cr:{room_port_key}:in` and friends, and
+  #     `cr:provision`).
+  #   * 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.
+  #
+  # Reconnects: when the pub/sub connection drops, the subscriber thread reports the error and
+  # opens a new session for every channel it still has a handler for, backing off from 0.1 s up
+  # to 5 s between attempts. Redis pub/sub doesn't queue, so anything published while the
+  # session is down is lost. Callers that can't afford that need their own recovery (members
+  # re-announce on their ping, for example).
+  #
+  # 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
+
+    INITIAL_BACKOFF = 0.1
+    MAX_BACKOFF = 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_port_key}:in`); a custom inbound port gets one
+      # (`cr:{room_port_key}:in:{port}`), so every channel a room listens on shares one prefix.
+      # The room part is the room's own stream name, so an app's `broadcasting_for` override
+      # (PandaPal's tenant prefix) keeps two tenants' rooms apart here too.
+      def inbound_channel(room_class, room_key, port = nil)
+        channel = room_channel(room_class.room_port_key(room_key), "in")
+        port.nil? ? channel : "#{channel}:#{port}"
+      end
+
+      # The one process-wide channel `create: true` members ask for rooms on, and every rooms
+      # Host's Placement listens to (see Host::Placement). It isn't per tenant: the tenant rides in
+      # the request, and the Host that claims the room switches into it.
+      def provision_channel
+        "#{KEY_PREFIX}:provision"
+      end
+
+      private
+
+      def room_channel(port_key, suffix)
+        key = port_key.to_s
+        raise ArgumentError, "room_port_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 --------------------------------------------------------------------------
+
+    # 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
+
+    # ---- 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. With `handler:`, only unsubscribes while that
+    # handler is still the one registered (a later `subscribe` may have replaced it).
+    def unsubscribe(channel, handler: nil, timeout: DEFAULT_TIMEOUT)
+      channel = channel.to_s
+
+      @mutex.synchronize do
+        return false if handler && !@handlers[channel].equal?(handler)
+        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 = INITIAL_BACKOFF
+      loop do
+        channels = @mutex.synchronize do
+          if @handlers.empty?
+            @thread = nil
+            @changed.broadcast
+            return
+          end
+          @handlers.keys
+        end
+
+        begin
+          run_session(channels)
+          backoff = INITIAL_BACKOFF
+        rescue StandardError => e
+          CableRoom.report_error(e, bus: self, channels: channels)
+          sleep backoff
+          backoff = [backoff * 2, MAX_BACKOFF].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.
+    #
+    # The writes below happen under @mutex, which is safe because they only queue a command on
+    # the socket: nothing here waits on a reply, and the subscriber thread never needs anything
+    # but @mutex to make progress.
+    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
+    rescue Redis::BaseConnectionError, RedisClient::ConnectionError
+      # The socket died under us. Stop writing to it and let the subscriber thread notice, report
+      # it, and open a new session for every channel still wanted. A caller waiting in
+      # `subscribe` rides on that session's confirmation (or times out) rather than seeing the
+      # connection error for a subscription the bus is about to retry anyway.
+      @session_live = false
+      @subscriber_redis = nil
+    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

data/lib/cable_room/cli.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "etc"
+require "logger"
+require_relative "version"
+
+module CableRoom
+  # The `cable_room` command. Its one command, `server`, is the rooms process for
+  # `room_host = :remote`: boot the Rails app, become this process's rooms Host, run until SIGTERM
+  # or SIGINT, then shut every room down (members get room_closed). Rooms aren't migrated
+  # anywhere on the way out.
+  #
+  # It refuses to run in :inline, where the web processes host rooms themselves and a server here
+  # would only race them for locks.
+  #
+  # What the rooms process needs from the app:
+  #
+  #   * The app's own config/cable.yml with a Redis adapter. Rooms still talk to members with
+  #     `ActionCable.server.broadcast`, which reaches web processes only through a shared
+  #     pubsub; the async and inline adapters keep broadcasts inside this process.
+  #   * The same CABLEROOM_* Redis settings as the web processes. Members publish to rooms on
+  #     the Bus there, and room locks live there.
+  #   * A tenant for every room it starts, in a multi-tenant app. Provision requests carry the
+  #     member's tenant; a room started here by hand needs `MyRoom.ensure(key, tenant: ...)`.
+  #
+  # Rooms start here through provisioning: a `create: true` join on the web side publishes a
+  # provision request on the Bus, and each rooms Host's Placement (started by `Host.start!`)
+  # waits in proportion to its load, then races for the room's lock (see Host::Placement).
+  #
+  # Boot works the way sidekiq and good_job do it: `require` the app's config/environment.rb from
+  # the current directory, or from `--require PATH` (an app directory or a boot file). Bundler is
+  # already set up because the command runs under `bundle exec`. Nothing from the gem beyond this
+  # file and `version` loads before the app boots, so the app's Gemfile decides when the Railtie
+  # loads, the same as in a web process. Nothing subscribes to Redis or starts a thread until
+  # the app has booted and been eager-loaded, so a supervisor can fork after that point.
+  #
+  # `--workers N` picks the process model. With N = 1 this process hosts rooms itself, as a
+  # single rooms process always has; the container's restart policy is its supervisor. With
+  # N > 1 (the default is the machine's processor count) the app is booted once, here, and then
+  # `Host::Supervisor` forks N children that each host rooms with their own Bus connection;
+  # this parent only watches them, replaces one that dies, and relays SIGTERM and SIGINT. The
+  # parent never builds a Host, subscribes the Bus, or keeps a Redis or database connection:
+  # the children build their own after the fork, so no two processes ever share a socket or a
+  # thread.
+  #
+  # `run` returns an exit status rather than exiting, so specs can drive it in-process.
+  class CLI
+    STOP_SIGNALS = %w[TERM INT].freeze
+
+    # How long a room's startup waits for Redis to confirm each Bus subscription here. A healthy
+    # Redis confirms in milliseconds; this only bounds a sick one, and failing sooner frees the
+    # room's lock sooner. The web-side default (Bus::DEFAULT_TIMEOUT, 5 s) is sized for a member
+    # join that can afford to wait.
+    SUBSCRIBE_TIMEOUT = 2
+
+    attr_reader :options, :command
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @options = { require: Dir.pwd, workers: nil }
+    end
+
+    # Parse and run. Returns the process exit status.
+    def run
+      parse!
+      return 0 if @help_shown
+
+      case command
+      when "server" then server
+      when nil
+        @stderr.puts parser
+        1
+      else
+        @stderr.puts "Unknown command #{command.inspect}.", parser
+        1
+      end
+    rescue OptionParser::ParseError => e
+      @stderr.puts e.message, parser
+      1
+    end
+
+    # How many worker processes `server` runs: `--workers`, or one per processor
+    def workers
+      options[:workers] || Etc.nprocessors
+    end
+
+    private
+
+    def parser
+      @parser ||= OptionParser.new do |o|
+        o.banner = "Usage: cable_room server [options]"
+        o.separator ""
+        o.separator "Hosts CableRoom rooms for a Rails app with room_host = :remote: boots the app in"
+        o.separator "the current directory and runs until SIGTERM or SIGINT. Needs the app's"
+        o.separator "config/cable.yml (a Redis adapter) and the same CABLEROOM_* Redis as the web."
+        o.separator ""
+        o.on("-r", "--require PATH", "App directory (with config/environment.rb) or a boot file to require") do |path|
+          @options[:require] = path
+        end
+        o.on("-w", "--workers N", Integer,
+             "Worker processes to fork (default: one per processor, #{Etc.nprocessors} here). 1 runs in this process.") do |n|
+          @options[:workers] = n
+        end
+        o.on("-v", "--version", "Print the version and exit") do
+          @stdout.puts CableRoom::VERSION
+          @help_shown = true
+        end
+        o.on("-h", "--help", "Show this help") do
+          @stdout.puts o
+          @help_shown = true
+        end
+      end
+    end
+
+    def parse!
+      rest = parser.parse(@argv)
+      @command = rest.shift
+      raise OptionParser::ParseError, "Unexpected arguments: #{rest.join(' ')}" if rest.any?
+    end
+
+    def server
+      # Check the cheap things before booting Rails, so a bad flag fails in milliseconds
+      unless workers >= 1
+        @stderr.puts "cable_room server: --workers must be at least 1 (got #{workers})."
+        return 1
+      end
+
+      boot_app!
+
+      unless CableRoom.remote?
+        @stderr.puts "cable_room server: CableRoom.room_host is #{CableRoom.room_host.inspect}, but a rooms " \
+                     "process only makes sense with :remote (in :inline the web processes host rooms " \
+                     "themselves). Set CABLE_ROOM_HOST=remote or `CableRoom.room_host = :remote` and try again."
+        return 1
+      end
+
+      warn_about_local_cable_adapter
+      return run_host if workers == 1
+
+      supervise_workers
+    end
+
+    # Load the app: a directory means its config/environment.rb, anything else is required as-is.
+    # Then eager-load it, as production does anyway, so every room class is loaded before any
+    # room starts (and before a supervisor forks).
+    def boot_app!
+      path = File.expand_path(options[:require])
+      path = File.join(path, "config", "environment.rb") if File.directory?(path)
+      require path
+
+      Rails.application.eager_load! if defined?(Rails) && Rails.application && !Rails.application.config.eager_load
+    end
+
+    def warn_about_local_cable_adapter
+      cable = ActionCable.server.config.cable || {}
+      adapter = (cable[:adapter] || cable["adapter"]).to_s
+      return unless %w[async inline test].include?(adapter)
+
+      @stderr.puts "cable_room server: warning: ActionCable's adapter is #{adapter.inspect}, so room broadcasts " \
+                   "never leave this process and members won't hear their rooms. Use the app's Redis cable.yml."
+    end
+
+    # Fork `workers` children that each run `run_host`, and watch them until a stop signal has
+    # come and gone. This parent hosts nothing itself (see the class comment for why).
+    def supervise_workers
+      Process.setproctitle("cable_room server: supervisor (#{workers} workers)")
+      # Fail now, once, if the CABLEROOM_* Redis is unreachable, rather than in N workers that
+      # would each die and come back with backoff. Then let go of what the ping (or the app's
+      # boot) opened, so the children inherit no Redis or database sockets.
+      CableRoom.redis(&:ping)
+      release_connections_before_fork
+      say "supervising #{workers} workers (pid #{Process.pid}, room_host=#{CableRoom.room_host})"
+
+      supervisor = CableRoom::Host::Supervisor.new(count: workers, logger: supervisor_logger) do |index|
+        run_host(worker: index)
+      end
+      status = supervisor.run
+      say "shut down"
+      status
+    end
+
+    # Close the parent's idle pooled Redis connections and its ActiveRecord connections. The
+    # children would drop their copies anyway (see `CableRoom.after_fork!`); closing them here
+    # means there are no copies to drop, and the parent, which only waits on children from now
+    # on, holds nothing it won't use. Both pools reconnect lazily if anything asks again.
+    def release_connections_before_fork
+      CableRoom.redis_pool.reload(&:close)
+      ActiveRecord::Base.connection_handler.clear_all_connections!(:all) if defined?(ActiveRecord::Base)
+    end
+
+    # Logs from the supervisor go to the same place as the CLI's own messages, in the same style.
+    # Unbuffered, so a "forked worker" line shows up when it happens, not when the process exits.
+    def supervisor_logger
+      @stdout.sync = true if @stdout.respond_to?(:sync=)
+      Logger.new(@stdout).tap do |logger|
+        logger.formatter = ->(_severity, _time, _progname, message) { "cable_room server: #{message}\n" }
+      end
+    end
+
+    # Host rooms in this process until SIGTERM or SIGINT, then shut them down. This is the whole
+    # life of a single-process server and of each forked worker (`worker` is the worker's index,
+    # nil when there's no supervisor). Returns the exit status.
+    def run_host(worker: nil)
+      # Trap before anything slow, so a signal that lands while rooms are still coming up (the
+      # supervisor relaying a SIGTERM that arrived mid-boot, say) is kept, not fatal
+      signals = trap_stop_signals
+
+      if worker
+        Process.setproctitle("cable_room server: worker #{worker}")
+        tag_logger("cable_room worker #{worker}")
+      end
+
+      # Fail now, not at the first room, if the CABLEROOM_* Redis is unreachable
+      CableRoom.redis(&:ping)
+
+      host = CableRoom::Host.start!(subscribe_timeout: SUBSCRIBE_TIMEOUT)
+      say "hosting rooms (pid #{Process.pid}, room_host=#{CableRoom.room_host})", worker: worker
+
+      signal = signals.pop
+      say "got SIG#{signal}, shutting down #{host.open_rooms_count} room(s)", worker: worker
+      # A second signal from here on gets the previous handler (the default one kills at once)
+      restore_signal_handlers
+      host.shutdown!
+      CableRoom.bus.shutdown
+      say "shut down", worker: worker
+      0
+    ensure
+      restore_signal_handlers
+    end
+
+    # Every room on this Host logs through `ActionCable.server.logger` (Host#logger); give that
+    # logger a tag naming the worker, so lines from the N workers sharing one stdout can be told
+    # apart. `tagged` without a block returns a logger whose tags apply on every thread, which is
+    # what we need: rooms log from the worker pool, not from this thread. A logger without tags
+    # (a plain Logger, say) is left as it is.
+    def tag_logger(tag)
+      logger = ActionCable.server.logger
+      return unless logger.respond_to?(:tagged)
+
+      tagged = logger.tagged(tag)
+      ActionCable.server.config.logger = tagged if tagged.respond_to?(:info)
+    end
+
+    # Signal handlers may only do trivial work, so each one just drops the signal's name on a
+    # queue for the main thread to pick up
+    def trap_stop_signals
+      signals = Queue.new
+      @previous_handlers = STOP_SIGNALS.to_h { |sig| [sig, trap(sig) { signals << sig }] }
+      signals
+    end
+
+    def restore_signal_handlers
+      @previous_handlers&.each { |sig, handler| trap(sig, handler) }
+      @previous_handlers = nil
+    end
+
+    def say(message, worker: nil)
+      prefix = worker ? "cable_room server (worker #{worker})" : "cable_room server"
+      @stdout.puts "#{prefix}: #{message}"
+      @stdout.flush
+    end
+  end
+end