puma-plus 0.1.0

data/lib/puma_plus/launcher.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "puma_plus/config_file"
+require "puma_plus/version"
+
+module PumaPlus
+  # The `puma-plus` command.
+  #
+  # Ruby parses the configuration and then *execs* the Go server. Two decisions
+  # worth stating, because both could reasonably have gone the other way.
+  #
+  # Why Ruby reads the config: it is a Ruby file. Worker counts get computed from
+  # Etc.nprocessors, settings branch on the environment, and lifecycle hooks are
+  # blocks. Only Ruby can evaluate that, and a config format Go could parse
+  # would be a worse config format.
+  #
+  # Why exec rather than spawn: exec replaces this process, so the Go server ends
+  # up with the pid the shell started, inherits the terminal and the process
+  # group directly, and receives signals from the user with nothing in between.
+  # A supervising Ruby parent would have to forward signals, mirror exit
+  # statuses, and would show up as a stray process in every `ps` -- all to
+  # supervise a process that supervises Ruby itself. After exec there is no Ruby
+  # in the tree except the workers the Go server starts.
+  class Launcher
+    DEFAULTS = {
+      listen: "0.0.0.0:9292",
+      control: "127.0.0.1:9293",
+      app: "config.ru",
+      threads: 5,
+      workers: 1,
+      environment: "development"
+    }.freeze
+
+    # Searched in order, mirroring puma's config/puma/<env>.rb then config/puma.rb.
+    def self.config_candidates(env)
+      ["config/puma-plus/#{env}.rb", "config/puma-plus.rb"]
+    end
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr, env: ENV)
+      @argv = argv
+      @stdout = stdout
+      @stderr = stderr
+      @env = env
+      @options = Options.new(DEFAULTS.dup)
+    end
+
+    attr_reader :options
+
+    def run
+      parse_cli!
+
+      # RACK_ENV is consulted before the config file is chosen, because which
+      # file gets loaded depends on the environment.
+      if (e = @env["RACK_ENV"]) && !@options.user.key?(:environment)
+        @options.default[:environment] = e
+      end
+
+      dsl = load_config!
+      Dir.chdir(@options[:directory]) if @options[:directory]
+
+      (dsl&.warnings || []).each { |w| @stderr.puts "[puma-plus] config: #{w}" }
+      validate!
+
+      argv = go_argv
+      if @dry_run
+        print_plan(argv)
+        return 0
+      end
+
+      write_pidfile
+      exec_go(argv)
+    rescue ConfigError, URI::Error, OptionParser::ParseError, ArgumentError => e
+      @stderr.puts "[puma-plus] #{e.message}"
+      1
+    end
+
+    private
+
+    def parse_cli!
+      u = @options.user
+
+      OptionParser.new do |o|
+        o.banner = "usage: puma-plus [options] [rackup file]"
+
+        o.on("-C", "--config PATH", "config file (default: config/puma-plus.rb)") { |v| @config_path = v }
+        o.on("--no-config", "skip config file discovery") { @no_config = true }
+        o.on("-b", "--bind URL", "tcp://host:port or ssl://host:port") { |v| @bind = v }
+        o.on("-p", "--port PORT", Integer, "port to bind (default 9292)") { |v| @port = v }
+        o.on("-e", "--environment ENV", "environment (default development)") { |v| u[:environment] = v }
+        o.on("-t", "--threads N", "worker connections per process") { |v| u[:threads] = Integer(v.split(":").last) }
+        o.on("-w", "--workers N", Integer, "worker processes") { |v| u[:workers] = v }
+        o.on("--ractors N", Integer, "serve from N Ractors in one process") { |v| u[:ractors] = v }
+        o.on("--autoscale", "scale workers from measured queue time") { u[:autoscale] = true }
+        o.on("--min-workers N", Integer) { |v| u[:min_workers] = v }
+        o.on("--max-workers N", Integer) { |v| u[:max_workers] = v }
+        o.on("--target-queue-p95 D", "queue-time p95 to steer toward, e.g. 25ms") { |v| u[:target_queue_p95] = v }
+        o.on("--control-url URL", "--control URL", "where /stats and /metrics listen") do |v|
+          u[:control] = Address.host_port(v, 9293, "--control-url")
+        end
+        o.on("--tls-cert PATH", "PEM certificate chain for the TLS/h3 listener") { |v| u[:tls_cert] = File.expand_path(v) }
+        o.on("--tls-key PATH", "PEM private key matching --tls-cert") { |v| u[:tls_key] = File.expand_path(v) }
+        o.on("--dir DIR", "chdir here before booting") { |v| u[:directory] = File.expand_path(v) }
+        o.on("--pidfile PATH") { |v| u[:pidfile] = v }
+        o.on("--dry-run", "print the resolved configuration and exit") { @dry_run = true }
+        o.on("-v", "--version") do
+          # Both halves, because they are separately installed and a mismatched
+          # pair is the failure worth being able to see at a glance.
+          @stdout.puts "puma-plus #{PumaPlus::VERSION}"
+          begin
+            require "puma_plus/core/version"
+            @stdout.puts "puma-plus-core #{PumaPlus::Core::VERSION}"
+          rescue LoadError
+            @stdout.puts "puma-plus-core (not installed)"
+          end
+          exit 0
+        end
+        o.on("-h", "--help") { @stdout.puts o; exit 0 }
+      end.parse!(@argv)
+
+      # A bare argument is the rackup file, as `puma config.ru` accepts.
+      u[:app] = @argv.shift if @argv.first
+
+      # -b and -p are resolved after parsing so their interaction is defined
+      # rather than order-dependent: an explicit --bind wins, and a lone --port
+      # keeps whatever host the bind would have used.
+      if @bind
+        scheme = @bind[%r{\A([a-zA-Z][a-zA-Z0-9+.-]*)://}, 1] || "tcp"
+        case scheme
+        when "tcp", "http" then u[:listen] = Address.host_port(@bind, @port || 9292, "--bind")
+        when "ssl", "https" then u[:listen_tls] = Address.host_port(@bind, @port || 9443, "--bind")
+        else raise ConfigError, "--bind #{@bind.inspect}: unsupported scheme #{scheme.inspect} " \
+                                "(use tcp:// or ssl://)"
+        end
+      elsif @port
+        u[:listen] = "0.0.0.0:#{@port}"
+      end
+    end
+
+    def load_config!
+      return nil if @no_config
+
+      path = @config_path || self.class.config_candidates(@options[:environment]).find { |f| File.exist?(f) }
+      return nil unless path
+
+      unless File.exist?(path)
+        raise ConfigError, "config file not found: #{path}"
+      end
+
+      @config_used = path
+      ConfigFile.load(path, @options)
+    end
+
+    def validate!
+      if @options[:ractors].to_i.positive?
+        if @options[:workers].to_i > 1
+          raise ConfigError, "ractors and workers cannot both be set: Ractor mode is " \
+                             "one process. Use one or the other."
+        end
+      end
+
+      unless File.exist?(@options[:app].to_s)
+        raise ConfigError, "rackup file not found: #{@options[:app]} " \
+                           "(pass one as an argument, or set `rackup` in the config)"
+      end
+
+      validate_tls!
+
+      min = @options[:min_workers]
+      max = @options[:max_workers]
+      if min && max && min > max
+        raise ConfigError, "min_workers (#{min}) must be <= max_workers (#{max})"
+      end
+    end
+
+    # Checked here rather than left to the server, because an unreadable path is
+    # a typo in a config file and should be reported by the thing that read it.
+    def validate_tls!
+      cert = @options[:tls_cert]
+      key = @options[:tls_key]
+
+      if (cert && !key) || (key && !cert)
+        raise ConfigError, "tls_cert and tls_key must be given together " \
+                           "(got only #{cert ? 'tls_cert' : 'tls_key'})"
+      end
+      return unless cert
+
+      { "tls_cert" => cert, "tls_key" => key }.each do |what, path|
+        raise ConfigError, "#{what}: no such file: #{path}" unless File.exist?(path)
+        raise ConfigError, "#{what}: not readable: #{path}" unless File.readable?(path)
+      end
+
+      if @options[:listen_tls].nil? && @options[:listen_h3].nil?
+        @stderr.puts "[puma-plus] config: tls_cert is set but no TLS or HTTP/3 " \
+                     "listener is configured; it will not be used"
+      end
+    end
+
+    # Translate resolved options into the Go server's flags.
+    #
+    # One-way on purpose: the Go binary's flags stay the machine interface and
+    # the DSL stays the human one, so neither constrains the other's naming.
+    def go_argv
+      o = @options
+      args = []
+
+      args += ["-app", File.expand_path(o[:app])]
+      args += ["-control", o[:control]] if o[:control]
+      args += ["-threads", o[:threads].to_s] if o[:threads]
+
+      if o[:ractors].to_i.positive?
+        args += ["-ractors", o[:ractors].to_s]
+      else
+        args += ["-workers", o[:workers].to_s] if o[:workers]
+      end
+
+      # A TLS or HTTP/3 listener replaces the cleartext one unless both were
+      # asked for; -listen "" is how the Go side is told not to open it.
+      if o[:listen_tls]
+        args += ["-listen-tls", o[:listen_tls]]
+        args += ["-listen", o.origin(:listen) == :default ? "" : o[:listen]]
+      else
+        args += ["-listen", o[:listen]]
+      end
+      args += ["-h2c"] if o[:h2c]
+      args += ["-listen-h3", o[:listen_h3]] if o[:listen_h3]
+      args += ["-tls-hosts", o[:tls_hosts]] if o[:tls_hosts]
+      if o[:tls_cert] && o[:tls_key]
+        args += ["-tls-cert", o[:tls_cert], "-tls-key", o[:tls_key]]
+      end
+
+      if o[:autoscale]
+        args << "-autoscale"
+        args += ["-min-workers", o[:min_workers].to_s] if o[:min_workers]
+        args += ["-max-workers", o[:max_workers].to_s] if o[:max_workers]
+        args += ["-target-queue-p95", o[:target_queue_p95]] if o[:target_queue_p95]
+      end
+      args += ["-mem-limit-mb", o[:mem_limit_mb].to_s] if o[:mem_limit_mb]
+      args += ["-decision-log", o[:decision_log]] if o[:decision_log]
+      args += ["-max-conns", o[:max_conns].to_s] if o[:max_conns]
+      args += ["-acquire-timeout", o[:acquire_timeout]] if o[:acquire_timeout]
+      args += ["-debug-headers"] if o[:debug_headers]
+      args += ["-websockets=false"] if o[:websockets] == false
+      args += ["-webtransport=false"] if o[:webtransport] == false
+
+      args
+    end
+
+    # The worker script this gem ships, in whichever layout we are in.
+    def worker_script
+      here = File.expand_path("../..", __dir__) # gem/lib/puma_plus -> gem
+      %w[exe/puma-plus-worker ../gem/exe/puma-plus-worker].each do |rel|
+        cand = File.expand_path(rel, here)
+        return cand if File.exist?(cand)
+      end
+      raise ConfigError, "cannot find puma-plus-worker next to #{__dir__}"
+    end
+
+    # Load paths the worker needs: this gem's lib, plus the GVL extension if it
+    # was built in place (a checkout). An installed gem puts the compiled
+    # extension on the default load path already, so the extra entry is absent
+    # rather than wrong.
+    def ruby_load_path
+      lib = File.expand_path("../..", __dir__)
+      paths = [lib]
+      ext = File.expand_path("../ext/puma_plus_gvl", lib)
+      paths << ext if File.directory?(ext)
+      paths
+    end
+
+    # Locate the compiled server.
+    #
+    # PUMA_PLUS_BINARY wins, then the puma-plus-core gem if it is installed, then
+    # a build sitting in the checkout. The core gem is how a real install finds
+    # it: the Go server ships there, precompiled for the platform.
+    def go_binary_from_core
+      require "puma_plus/core"
+      path = PumaPlus::Core.binary_path
+      path if path && File.executable?(path)
+    rescue LoadError
+      nil
+    end
+
+    def go_binary
+      env = @env["PUMA_PLUS_BINARY"]
+      return env if env && File.executable?(env)
+
+      if (core = go_binary_from_core)
+        return core
+      end
+
+      here = File.expand_path("../../..", __dir__)
+      %w[puma-plus bin/puma-plus].each do |rel|
+        cand = File.join(here, rel)
+        return cand if File.executable?(cand) && !File.directory?(cand)
+      end
+
+      found = ENV["PATH"].to_s.split(File::PATH_SEPARATOR)
+                         .map { |d| File.join(d, "puma-plus-server") }
+                         .find { |f| File.executable?(f) }
+      return found if found
+
+      raise ConfigError, "cannot find the puma-plus server binary. Install the " \
+                         "puma-plus-core gem, build it with " \
+                         "`go build -o puma-plus ./cmd/puma-plus`, or set PUMA_PLUS_BINARY."
+    end
+
+    def write_pidfile
+      return unless @options[:pidfile]
+
+      # Written before exec, so it holds the pid the Go server will have -- exec
+      # keeps this process id. Writing it after would be impossible; writing a
+      # child's pid would be wrong.
+      File.write(@options[:pidfile], "#{Process.pid}\n")
+    end
+
+    def exec_go(args)
+      bin = go_binary
+      @stderr.puts "[puma-plus] #{@config_used ? "config #{@config_used}, " : ''}" \
+                   "env #{@options[:environment]}"
+      env = {}
+      env["RACK_ENV"] = @options[:environment].to_s
+      env["PUMA_PLUS_CONFIG"] = @config_used if @config_used
+      # This file lives inside the gem, so it knows where the worker script and
+      # the load path are. Telling the server outright is the only thing that
+      # works in both layouts: a checkout has gem/exe and gem/lib, an installed
+      # gem has exe/ and lib/, and nothing the server could compute is right for
+      # both.
+      env["PUMA_PLUS_WORKER"] = worker_script
+      env["PUMA_PLUS_RUBY_LIB"] = ruby_load_path.join(File::PATH_SEPARATOR)
+      Kernel.exec(env, bin, *args)
+    end
+
+    def print_plan(args)
+      @stdout.puts "config file : #{@config_used || '(none)'}"
+      @stdout.puts "environment : #{@options[:environment]}"
+      @stdout.puts "server      : #{begin; go_binary; rescue ConfigError; '(not built)'; end}"
+      @stdout.puts
+      @stdout.puts "resolved options (origin):"
+      @options.to_h.keys.sort_by(&:to_s).each do |k|
+        @stdout.printf("  %-20s %-28s %s\n", k, @options[k].inspect, @options.origin(k))
+      end
+      @stdout.puts
+      @stdout.puts "exec: #{File.basename(begin; go_binary; rescue ConfigError; 'puma-plus'; end)} #{args.join(' ')}"
+    end
+  end
+end

data/lib/puma_plus/rack_env.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "puma_plus/wire"
+
+module PumaPlus
+  # Assembles the Rack env from a REQUEST frame.
+  #
+  # Go emits the *complete, final* env in CGI form, so this class performs zero
+  # string transformation -- no dash/underscore mangling, no Host splitting, no
+  # case folding. All of that lives in internal/frontend/env.go. What remains
+  # here is a hash dup plus byteslice merges, which is the cheapest per-request
+  # env construction available without a C extension.
+  #
+  # Compare puma, which builds the env in five layers (Binder's @proto_env, the
+  # Ragel C parser writing straight into the hash, normalize_env,
+  # req_env_post_parse, then handle_request). Moving parsing to Go collapses that
+  # to one pass.
+  class RackEnv
+    # Keys that appear on essentially every request, pre-frozen so the common
+    # path never allocates a key string. Same optimization as puma's 35
+    # pre-interned header names in ext/puma_http11/puma_http11.c:78-118.
+    COMMON_KEYS = %w[
+      REQUEST_METHOD PATH_INFO SCRIPT_NAME QUERY_STRING SERVER_PROTOCOL
+      SERVER_NAME SERVER_PORT REMOTE_ADDR SERVER_SOFTWARE
+      CONTENT_LENGTH CONTENT_TYPE
+      rack.url_scheme
+      HTTP_HOST HTTP_ACCEPT HTTP_ACCEPT_CHARSET HTTP_ACCEPT_ENCODING
+      HTTP_ACCEPT_LANGUAGE HTTP_AUTHORIZATION HTTP_CACHE_CONTROL HTTP_CONNECTION
+      HTTP_COOKIE HTTP_IF_MODIFIED_SINCE HTTP_IF_NONE_MATCH HTTP_ORIGIN
+      HTTP_PRAGMA HTTP_REFERER HTTP_USER_AGENT HTTP_X_FORWARDED_FOR
+      HTTP_X_FORWARDED_PROTO HTTP_X_REQUEST_ID HTTP_X_REQUEST_START
+    ].each_with_object({}) { |k, h| h[k.b.freeze] = k.freeze }.freeze
+
+    # Uncommon keys are deduplicated into this cache on first sight, so a long
+    # tail of custom headers costs one allocation per distinct name for the
+    # lifetime of the process rather than one per request.
+    # multithread and multiprocess describe THIS process, and are computed by the
+    # caller from the real configuration rather than assumed.
+    #
+    # Rack 3 dropped these from the spec, along with rack.version and
+    # rack.run_once. They are kept because apps still read them -- sizing a
+    # connection pool is the usual reason -- and because puma still sets them
+    # (puma/lib/puma/binder.rb:33-35). rack.version is NOT kept: Rack 3 removed
+    # it and any value would be a claim about a spec version that no longer
+    # numbers itself that way.
+    #
+    # Hardcoding them, as this used to, meant a single-threaded worker still
+    # announced rack.multithread, and an app sizing a pool from it over-allocated
+    # by exactly the factor it was trying to compute.
+    def initialize(errors: $stderr, multithread: true, multiprocess: false)
+      @key_cache = Hash.new { |h, k| h[k] = -k.dup.force_encoding(Encoding::UTF_8) }
+      @prototype = {
+        "rack.errors" => errors,
+        "rack.hijack?" => true,
+        "rack.multithread" => multithread,
+        "rack.multiprocess" => multiprocess,
+        "rack.run_once" => false
+      }.freeze
+    end
+
+    # Build an env from a decoded env kv blob.
+    #
+    # +pairs+ is the array of [key, value] byteslices from Wire.decode_kv. Values
+    # are handed through as-is: they are byteslices of the single frame payload,
+    # so the whole env costs one payload string plus N slice headers.
+    def build(pairs, meta)
+      env = @prototype.dup
+
+      pairs.each do |key, value|
+        env[COMMON_KEYS[key] || @key_cache[key]] = value
+      end
+
+      # Timing, in the three shapes callers expect.
+      #
+      # puma.request_queue_time is ours and authoritative: nanoseconds measured
+      # entirely inside Go from a monotonic clock, so no cross-process skew.
+      #
+      # puma.request_body_wait keeps puma's exact key and millisecond unit
+      # (lib/puma/client.rb:746) so middleware written against puma works
+      # unchanged.
+      env["puma.request_queue_time"] = meta[:queue_ns] / 1_000_000_000.0
+      env["puma.request_body_wait"] = meta[:body_wait_ns] / 1_000_000.0
+
+      # X-Request-Start in the exact `t=<unix micros>` format New Relic, Scout
+      # and Skylight already parse, injected only if absent so an upstream load
+      # balancer's value always wins. Existing APM gems light up with no changes.
+      env["HTTP_X_REQUEST_START"] ||= "t=#{meta[:runnable_wall_us]}"
+
+      env
+    end
+  end
+end

data/lib/puma_plus/ractor_worker.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "socket"
+require "etc"
+require "puma_plus/wire"
+require "puma_plus/control_channel"
+require "puma_plus/worker_thread"
+require "puma_plus/app_loader"
+require "puma_plus/hooks"
+require "puma_plus/gvl"
+
+module PumaPlus
+  # A worker process whose unit of capacity is a Ractor rather than a thread.
+  #
+  # Same contract as Worker: N units of capacity, each dialing the Go server and
+  # serving one request at a time. What differs is what a unit *is*. Threads
+  # share one lock, so N threads running CPU-bound Ruby is still one core's worth
+  # of throughput -- that is the entire reason this project scales by forking
+  # processes, and the reason the controller carries GVL instrumentation to
+  # detect when adding a thread would be pointless. Ractors each hold their own
+  # lock and genuinely run in parallel, so the actuator the controller wants
+  # ("add capacity") becomes available without a fork.
+  #
+  # This architecture is an unusually good fit for Ractors, and the reason is
+  # what is absent rather than what is present. The hard part of a Ractor web
+  # server is work distribution: Ractors cannot share a mutable queue, so cougar
+  # (github.com/jhawthorn/cougar) has every Ractor call accept() on one shared
+  # TCPServer and lets the kernel do the balancing. puma-plus has no listener and
+  # no queue in Ruby at all -- both are in Go -- so each Ractor dials its own
+  # unix socket and shares literally nothing with its siblings. There is no
+  # shared object to make shareable, and no accept-balancing to get wrong.
+  #
+  # Cost model versus forking a worker: a Ractor starts in roughly a millisecond
+  # against tens to hundreds for fork-plus-app-boot, and it starts *warm* --
+  # same heap, same JIT state, no re-require. Fork dead time is exactly what
+  # costs the autoscaler its p99 in the step-mix benchmark, so this is the
+  # actuator most likely to close that gap.
+  #
+  # The remaining constraint is the app, which must be deeply frozen to cross a
+  # Ractor boundary. That is a real limitation and it excludes most of the
+  # ecosystem today, Rails very much included. See #shareable!.
+  #
+  # Known gap for the spike: WS/WebTransport publishing (PumaPlus::WS) keeps
+  # module-level state in the main Ractor and is not reachable from inside one,
+  # so realtime apps must still use the threaded worker.
+  class RactorWorker
+    def initialize(socket_path:, app_path:, ractors:, worker_id: 0, config_path: nil,
+                   logger: $stderr)
+      @socket_path = socket_path
+      @app_path = app_path
+      @ractors = ractors
+      @worker_id = worker_id
+      @logger = logger
+      @hooks = Hooks.load(config_path, logger: logger)
+    end
+
+    def run
+      run_preloaded(AppLoader.load(@app_path))
+    end
+
+    # Serve using an already-loaded app, mirroring Worker#run_preloaded so a
+    # shepherd can preload once and hand the same object to either worker kind.
+    def run_preloaded(app)
+      # Ruby still prints an experimental-feature warning on first Ractor use.
+      # Scoped to this call rather than set globally, so warnings from anything
+      # else stay visible.
+      warning_was = Warning[:experimental]
+      Warning[:experimental] = false
+
+      app = shareable!(app)
+
+      # The event hook is VM-wide, so one registration covers every Ractor. What
+      # it measures changes meaning here: siblings no longer contend for a shared
+      # lock, so a rising GVL fraction now indicates contention *within* a
+      # Ractor rather than across the process.
+      PumaPlus::GVL.start!
+
+      # Each argument crosses a Ractor boundary, so each must be shareable.
+      # Integers and the frozen path are; `app` was just checked.
+      @app = app
+      @path = @socket_path.dup.freeze
+      @live = {}
+      @mutex = Mutex.new
+      @exit_port = Ractor::Port.new
+      @next_index = 0
+      @running = true
+
+      # In the main Ractor, before any Ractor starts. Hooks cannot run *inside* a
+      # Ractor at all -- they are blocks closing over the config file's scope,
+      # which is exactly what cannot cross a Ractor boundary -- so there is one
+      # boot hook per process here rather than one per unit of capacity. For the
+      # usual use, establishing a connection pool, per-process is what you want
+      # anyway.
+      @hooks.run(:on_worker_boot, @worker_id)
+
+      reaper = Thread.new { reap_loop }
+      @ractors.times { spawn_ractor }
+
+      @logger.puts "[puma-plus] worker #{@worker_id} pid=#{Process.pid} " \
+                   "serving with #{@ractors} ractors"
+
+      # A Ractor cannot be killed from outside, so unlike the threaded worker
+      # there is no Thread#kill equivalent to drain with. The graceful path is
+      # GOAWAY from Go, which breaks each WorkerThread's read loop from the
+      # inside; TERM is the abrupt fallback and does drop in-flight requests.
+      trap("TERM") { @running = false }
+      trap("INT")  { @running = false }
+
+      # The control connection is what makes autoscaling possible: without it
+      # Go can retire Ractors on its own (GOAWAY an idle conn) but has no way to
+      # ask for a new one, since only Ruby can call Ractor.new.
+      @control = ControlChannel.new(socket_path: @socket_path, logger: @logger).connect!
+      @control.run(self)
+      reaper.kill
+    ensure
+      @hooks.run(:on_worker_shutdown, @worker_id, fatal: false)
+      @control&.close
+      Warning[:experimental] = warning_was unless warning_was.nil?
+    end
+
+    # --- ControlChannel handler protocol ---
+
+    def running? = @running
+
+    # SET_SLOTS carries the desired Ractor count.
+    def set_slots(target) = adjust_ractors(target)
+
+    # Nothing to stop replacing: Ractors are never respawned on death here, and
+    # Go decides the count.
+    def quiesce = @logger.puts("[puma-plus] quiescing")
+
+    def shutdown(_grace_ms) = @running = false
+
+    # One process, so one pid. Go reads its RSS from /proc; a per-Ractor share
+    # is not a real quantity, because Ractors share a heap.
+    def heartbeat_kv
+      [["workers", live_count], ["worker_pids", Process.pid.to_s]]
+    end
+
+    private
+
+    # Start one Ractor serving one connection.
+    #
+    # thread_index comes from a monotonic counter rather than the current size
+    # of the set, because a process that scaled down and back up would otherwise
+    # reuse an index still held by a Ractor that had not finished draining --
+    # and Go identifies a connection by (worker_id, thread_index).
+    def spawn_ractor
+      idx = @next_index
+      @next_index += 1
+
+      r = Ractor.new(@path, @app, @worker_id, idx, @exit_port, @ractors > 1,
+                     name: "puma-plus #{@worker_id}/#{idx}") do |p, a, wid, i, port, mt|
+        # multithread because sibling Ractors call the app concurrently in this
+        # process; not multiprocess, since Ractor mode is a single process.
+        WorkerThread.new(socket_path: p, app: a, worker_id: wid, thread_index: i,
+                         multithread: mt, multiprocess: false).run
+      ensure
+        # Reported from inside because a Ractor's exit cannot be polled from
+        # outside: there is no #alive?, and #join blocks. An ensure block also
+        # covers the Ractor dying of an exception, which a success-only signal
+        # would miss -- leaving the count permanently too high and the process
+        # unable to scale back up.
+        port.send(i)
+      end
+
+      @mutex.synchronize { @live[idx] = r }
+      r
+    end
+
+    # Remove Ractors as they finish.
+    #
+    # A Ractor ends when Go sends GOAWAY to its connection and WorkerThread's
+    # read loop breaks, so scale-down is initiated entirely from Go and arrives
+    # here only as bookkeeping. Runs in its own thread because Port#receive
+    # blocks; it is an ordinary thread in the main Ractor, so it can share
+    # @live under a mutex like any other.
+    def reap_loop
+      while @running
+        idx = @exit_port.receive
+        @mutex.synchronize { @live.delete(idx) }
+      end
+    rescue Ractor::ClosedError, Ractor::Error
+      nil
+    end
+
+    def live_count = @mutex.synchronize { @live.size }
+
+    # SET_SLOTS carries the desired Ractor count.
+    #
+    # Only ever grows. Shrinking is Go's job and it has already happened by the
+    # time this arrives: Go drains an idle connection with GOAWAY and then sends
+    # the lower target, so acting on a shrink here would at best be redundant
+    # and at worst would race the drain. This is the one place the Ractor
+    # actuator is genuinely simpler than the forking one -- the shepherd has to
+    # pick a pid and TERM it, and has to distinguish that from a crash.
+    def adjust_ractors(target)
+      target = 1 if target.nil? || target < 1
+
+      spawned = 0
+      while live_count < target
+        spawn_ractor
+        spawned += 1
+      end
+      return if spawned.zero?
+
+      @logger.puts "[puma-plus] spawned #{spawned} ractor(s), now #{live_count}"
+    end
+
+    # An app crosses into a Ractor only if it is deeply frozen. Modules and
+    # classes already qualify -- an app that is `MyApp` with `def self.call`
+    # needs nothing. A Rack::Builder middleware chain is a graph of ordinary
+    # objects and has to be deep-frozen, which is where most real apps refuse:
+    # anything memoizing into an ivar on first request, or holding a connection
+    # pool, or lazily building a route table, will raise here or (worse) at the
+    # first request. That is a genuine limitation of Ractor mode, not a bug.
+    def shareable!(app)
+      return app if Ractor.shareable?(app)
+
+      Ractor.make_shareable(app)
+    rescue StandardError => e
+      raise "#{@app_path} is not Ractor-shareable (#{e.class}: #{e.message}). " \
+            "Ractor mode requires an app that can be deep-frozen; run with " \
+            "--threads instead."
+    end
+  end
+end