cable_room 0.6.2 → 0.7.0.beta1

data/lib/cable_room/cli.rb

@@ -0,0 +1,237 @@
+# 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 host" role from the
+  # distributed-rooms design: boot the Rails app, become a rooms host, run until SIGTERM or SIGINT,
+  # then shut every room down cleanly.
+  #
+  # It only makes sense with `room_host = :remote` and refuses to run otherwise: in :inline the
+  # web processes host rooms themselves, so a server here would only race them for locks.
+  #
+  # 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` is loaded before the app boots, so the app's Gemfile decides
+  # when the Railtie loads, the same as in a web process.
+  #
+  # `--workers N` picks the process model. With N = 1 this process hosts rooms itself. With
+  # N > 1 (the default is the machine's core count) the app is booted once, here, and then
+  # `Host::Supervisor` forks N children that each host rooms; this parent only watches them,
+  # replaces one that dies, and relays SIGTERM and SIGINT. The parent never builds a Host, a Bus
+  # subscriber, or a Redis connection of its own: those belong to the children, which build them
+  # after the fork so no process ever shares a socket or a thread with another.
+  #
+  # Everything is instance state and `run` returns an exit status, so specs can drive the parsing
+  # and the refusals in-process; only the exe calls `exit`.
+  class CLI
+    STOP_SIGNALS = %w[TERM INT].freeze
+
+    attr_reader :options, :command
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @options = { workers: nil, require: Dir.pwd }
+    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 core.
+    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 "Runs a CableRoom rooms host: boots the Rails app in the current directory and"
+        o.separator "hosts rooms until SIGTERM or SIGINT. Needs CableRoom.config.room_host = :remote."
+        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 core, #{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.config.remote?
+        @stderr.puts "cable_room server: CableRoom.config.room_host is #{CableRoom.config.room_host.inspect}, but a " \
+                     "rooms host only makes sense with :remote (in :inline the web processes host rooms " \
+                     "themselves). Set CABLE_ROOM_HOST=remote or `c.room_host = :remote` and try again."
+        return 1
+      end
+
+      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
+    def boot_app!
+      path = File.expand_path(options[:require])
+      path = File.join(path, "config", "environment.rb") if File.directory?(path)
+      require path
+    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)")
+      say "supervising #{workers} workers (pid #{Process.pid}, room_host=#{CableRoom.config.room_host}, " \
+          "broadcaster=#{CableRoom.config.broadcaster})"
+
+      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
+
+    # 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 starting the Host, 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
+
+      host = CableRoom::Host.start!
+      say "hosting rooms (pid #{Process.pid}, room_host=#{CableRoom.config.room_host}, " \
+          "broadcaster=#{CableRoom.config.broadcaster})", worker: worker
+
+      signal = wait_for_stop_signal(signals)
+      stop_host(host, signal, worker: worker)
+      say "shut down", worker: worker
+      0
+    ensure
+      restore_traps
+    end
+
+    # A stop signal with rooms open is a planned shutdown: hand the rooms to peer hosts before
+    # leaving (`Host#drain!`, bounded by `drain_timeout`; a room nobody adopts closes with
+    # `room_closed`). With nothing open there is nothing to move, so just shut down. Both are
+    # idempotent, so the one SIGTERM a supervisor relays and a later `at_exit` don't collide.
+    def stop_host(host, signal, worker: nil)
+      rooms = host.rooms.size
+      if rooms.zero?
+        say "got SIG#{signal}, shutting down 0 room(s)", worker: worker
+        host.shutdown!
+        return
+      end
+
+      say "got SIG#{signal}, migrating #{rooms} room(s) to peer hosts", worker: worker
+      result = host.drain!(reason: "SIG#{signal}")
+      say "drained: #{result.migrated.size} room(s) migrated, #{result.closed.size} closed, " \
+          "in #{result.duration.round(1)}s", worker: worker
+    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, or Rails' BroadcastLogger fanning out to several) 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
+
+    def say(message, worker: nil)
+      prefix = worker ? "cable_room server (worker #{worker})" : "cable_room server"
+      @stdout.puts "#{prefix}: #{message}"
+      @stdout.flush
+    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. Returns the queue.
+    def trap_stop_signals
+      signals = Queue.new
+      @previous_traps = STOP_SIGNALS.to_h { |sig| [sig, trap(sig) { signals << sig }] }
+      signals
+    end
+
+    # Block the main thread until SIGTERM or SIGINT; returns the signal's name. A timed pop, not
+    # a plain one: if this were the only thread left (a worker whose rooms have all gone quiet,
+    # say), a blocking pop would trip Ruby's deadlock detector, because a trap isn't a thread.
+    def wait_for_stop_signal(signals)
+      loop do
+        signal = signals.pop(timeout: 1)
+        return signal if signal
+      end
+    end
+
+    def restore_traps
+      @previous_traps&.each { |sig, handler| trap(sig, handler) }
+      @previous_traps = nil
+    end
+  end
+end

data/lib/cable_room/config.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module CableRoom
+  # Holds the app-wide settings for CableRoom. Get the current one with `CableRoom.config`
+  # and change it with `CableRoom.configure`:
+  #
+  #   CableRoom.configure do |c|
+  #     c.room_host   = :remote       # :inline | :remote
+  #     c.broadcaster = :anycable     # :action_cable | :anycable
+  #     c.provision_delay_ms = 20
+  #     c.drain_timeout   = 10.minutes
+  #     c.handoff_timeout = 10.seconds
+  #   end
+  #
+  # The env vars CABLE_ROOM_HOST and CABLE_ROOM_BROADCASTER override `room_host` and
+  # `broadcaster`, even when the configure block sets them. That lets one build run in
+  # both modes without a code change. With no configuration at all, every default keeps
+  # today's behavior: rooms run inline and broadcast through ActionCable.
+  class Config
+    class InvalidOption < ArgumentError; end
+
+    ROOM_HOSTS = %i[inline remote].freeze
+    BROADCASTERS = %i[action_cable anycable].freeze
+
+    ENV_OVERRIDES = {
+      room_host: "CABLE_ROOM_HOST",
+      broadcaster: "CABLE_ROOM_BROADCASTER",
+    }.freeze
+
+    DEFAULTS = {
+      room_host: :inline,
+      broadcaster: :action_cable,
+      provision_delay_ms: 20,
+      drain_timeout: 10.minutes,
+      handoff_timeout: 10.seconds,
+    }.freeze
+
+    attr_reader :room_host, :broadcaster
+    attr_accessor :provision_delay_ms, :drain_timeout, :handoff_timeout
+
+    def initialize
+      DEFAULTS.each { |name, value| instance_variable_set("@#{name}", value) }
+    end
+
+    # Where rooms run. `:inline` keeps them in the web process; `:remote` moves them to a
+    # dedicated host pool. Accepts a Symbol or String; unknown values raise right away.
+    def room_host=(value)
+      @room_host = validate_choice!(:room_host, value, ROOM_HOSTS)
+    end
+
+    # How a room pushes messages to members. Accepts a Symbol or String; unknown values raise.
+    def broadcaster=(value)
+      @broadcaster = validate_choice!(:broadcaster, value, BROADCASTERS)
+    end
+
+    # Rooms run inside every process that joins them (the web process in a Rails app).
+    def inline?
+      room_host == :inline
+    end
+
+    # Rooms run only in `cable_room server` processes; a web process never hosts one.
+    def remote?
+      room_host == :remote
+    end
+
+    # Copies CABLE_ROOM_HOST and CABLE_ROOM_BROADCASTER onto this config. Blank or missing
+    # variables leave the current value alone. `env` is injectable for specs.
+    def apply_env_overrides(env = ENV)
+      ENV_OVERRIDES.each do |name, var|
+        value = env[var]
+        next if value.nil? || value.strip.empty?
+
+        public_send("#{name}=", value)
+      end
+      self
+    end
+
+    # Checks every knob at once. The choice knobs are already checked by their setters, so
+    # this mostly guards the timing knobs, which are plain accessors.
+    def validate!
+      validate_choice!(:room_host, room_host, ROOM_HOSTS)
+      validate_choice!(:broadcaster, broadcaster, BROADCASTERS)
+      validate_number!(:provision_delay_ms, provision_delay_ms, min: 0)
+      validate_number!(:drain_timeout, drain_timeout, min: 0, exclusive: true)
+      validate_number!(:handoff_timeout, handoff_timeout, min: 0, exclusive: true)
+      self
+    end
+
+    def to_h
+      DEFAULTS.keys.to_h { |name| [name, public_send(name)] }
+    end
+
+    private
+
+    def validate_choice!(name, value, allowed)
+      symbol = value.to_s.to_sym unless value.nil?
+      return symbol if allowed.include?(symbol)
+
+      raise InvalidOption,
+            "CableRoom config: #{name} must be one of #{allowed.map(&:inspect).join(', ')} " \
+            "(got #{value.inspect})"
+    end
+
+    def validate_number!(name, value, min:, exclusive: false)
+      ok = value.is_a?(Numeric) && (exclusive ? value > min : value >= min)
+      return value if ok
+
+      bound = exclusive ? "greater than #{min}" : "at least #{min}"
+      raise InvalidOption, "CableRoom config: #{name} must be a number #{bound} (got #{value.inspect})"
+    end
+  end
+end

data/lib/cable_room/host/bus_inbound.rb

@@ -0,0 +1,36 @@
+module CableRoom
+  class Host
+    # How rooms receive messages: off the process-wide CableRoom::Bus (see `CableRoom.bus`), on
+    # the channels `Room::Base.inbound_channel` names. This is the only room-side code that
+    # touches the inbound transport, and it's the same in `:inline` and `:remote` mode — the only
+    # difference is which process the Host lives in. Anything with these two methods can be handed
+    # to `Host.new(inbound:)`.
+    #
+    # `subscribe` returns a handle that `unsubscribe` needs back. Handlers get the decoded message
+    # on the Bus's single subscriber thread, in publish order, so they must be quick and hand the
+    # real work off; Host::Runner does that by queueing it on the room. `subscribe` blocks until
+    # Redis confirms the subscription, so `on_live` runs on the caller's thread right before it
+    # returns, and anything published after that is delivered.
+    class BusInbound
+      # `bus` defaults to `CableRoom.bus` (looked up lazily so specs can swap it)
+      def initialize(bus: nil)
+        @bus = bus
+      end
+
+      def subscribe(channel, on_live: nil, &on_message)
+        bus.subscribe(channel) { |message, _channel| on_message.call(message) }
+        on_live&.call
+        on_message
+      end
+
+      def unsubscribe(channel, _handle)
+        bus.unsubscribe(channel)
+      end
+
+      # The Bus behind this transport (the process-wide one unless a spec handed us another)
+      def bus
+        @bus || CableRoom.bus
+      end
+    end
+  end
+end