raptor 0.18.0 → 0.20.0

data/lib/rackup/handler/raptor.rb

@@ -44,7 +44,7 @@ module Rackup
           "Port=PORT"      => "Port to listen on (default: #{DEFAULT_OPTIONS[:Port]})",
           "Workers=NUM"    => "Number of worker processes (default: available processor count)",
           "Threads=NUM"    => "Number of threads per worker (default: 3)",
-          "MaxThreads=NUM" => "Maximum threads per worker (`unlimited` for no limit; default: fixed at Threads)",
+          "MaxThreads=NUM" => "Maximum threads per worker (`unlimited` for no limit; default: unlimited)",
           "Config=PATH"    => "Load additional configuration from PATH"
         }
       end
@@ -71,6 +71,8 @@ module Rackup
         cli_defaults = ::Raptor::CLI::DEFAULT_OPTIONS
         config_path = options[:Config] || ::Raptor::CLI.default_config_path
         config = config_path ? ::Raptor::CLI.load_config_file(config_path) : {}
+        threads = (options[:Threads] || ENV["RAPTOR_THREADS"] || config[:threads] || cli_defaults[:threads]).to_i
+        max_threads = options[:MaxThreads] || ENV["RAPTOR_MAX_THREADS"] || config.fetch(:max_threads, cli_defaults[:max_threads])
 
         result = {
           binds: if options[:Host] || options[:Port]
@@ -80,9 +82,12 @@ module Rackup
           end,
           socket_backlog: (config[:socket_backlog] || cli_defaults[:socket_backlog]).to_i,
           drain_accept_queue: config.key?(:drain_accept_queue) ? config[:drain_accept_queue] : cli_defaults[:drain_accept_queue],
-          workers: (options[:Workers] || config[:workers] || Concurrent.available_processor_count).to_i,
-          threads: (options[:Threads] || config[:threads] || cli_defaults[:threads]).to_i,
-          max_threads: ::Raptor::CLI.parse_max_threads(options[:MaxThreads] || config[:max_threads]),
+          workers: (options[:Workers] || ENV["RAPTOR_WORKERS"] || config[:workers] || Concurrent.available_processor_count).to_i,
+          threads: threads,
+          max_threads: ::Raptor::CLI.parse_max_threads(max_threads, threads: threads),
+          cpu_affinity: config.key?(:cpu_affinity) ? config[:cpu_affinity] : cli_defaults[:cpu_affinity],
+          clean_thread_locals: config.key?(:clean_thread_locals) ? config[:clean_thread_locals] : cli_defaults[:clean_thread_locals],
+          clean_fiber_locals: config.key?(:clean_fiber_locals) ? config[:clean_fiber_locals] : cli_defaults[:clean_fiber_locals],
           app: app
         }
         result[:rackup] = config[:rackup] if config.key?(:rackup)
@@ -96,6 +101,7 @@ module Rackup
         result[:worker_drain_timeout] = (config[:worker_drain_timeout] || cli_defaults[:worker_drain_timeout]).to_i
         result[:worker_shutdown_timeout] = (config[:worker_shutdown_timeout] || cli_defaults[:worker_shutdown_timeout]).to_i
         result[:stats_file] = config.key?(:stats_file) ? config[:stats_file] : cli_defaults[:stats_file]
+        result[:control_url] = config[:control_url] if config.key?(:control_url)
         result[:pid_file] = config[:pid_file] if config.key?(:pid_file)
         result[:stdout_file] = config[:stdout_file] if config.key?(:stdout_file)
         result[:stderr_file] = config[:stderr_file] if config.key?(:stderr_file)

data/lib/raptor/binder.rb

@@ -106,6 +106,15 @@ module Raptor
       tcp_listener.local_address.ip_port
     end
 
+    # Returns whether any listener can negotiate HTTP/2.
+    #
+    # @return [Boolean]
+    #
+    # @rbs () -> bool
+    def http2?
+      @listeners.any? { |listener| listener.is_a?(SslListener) }
+    end
+
     # Closes all listening sockets.
     #
     # @return [void]

data/lib/raptor/cli.rb

@@ -34,7 +34,10 @@ module Raptor
       drain_accept_queue: false,
       workers: DEFAULT_WORKER_COUNT,
       threads: 3,
-      max_threads: nil,
+      max_threads: Float::INFINITY,
+      cpu_affinity: false,
+      clean_thread_locals: true,
+      clean_fiber_locals: false,
       rackup: "config.ru",
       chdir: nil,
       environment: nil,
@@ -48,7 +51,7 @@ module Raptor
       http1: {
         ractors: nil,
         persistent_data_timeout: 65,
-        max_keepalive_requests: 100,
+        max_keepalive_requests: 1000,
       },
       http2: {
         ractors: nil,
@@ -64,6 +67,7 @@ module Raptor
       before_worker_shutdown: [].freeze,
       before_refork: [].freeze,
       stats_file: "tmp/raptor.json",
+      control_url: nil,
       pid_file: nil,
       stdout_file: nil,
       stderr_file: nil,
@@ -101,17 +105,27 @@ module Raptor
 
     # Parses a maximum thread count from a CLI, config, or Rack handler value.
     #
-    # @param value [Integer, Float, String, nil] maximum thread count
-    # @return [Integer, Float, nil] parsed thread count, `Float::INFINITY` for
-    #   `"unlimited"`, or nil for a fixed-size pool
+    # @param value [Integer, Float, String] maximum thread count
+    # @param threads [Integer] baseline thread count
+    # @return [Integer, Float] parsed thread count, or `Float::INFINITY` for
+    #   `"unlimited"`
+    # @raise [ArgumentError] if the maximum is nil or less than the baseline
     #
-    # @rbs (Integer | Float | String | nil value) -> (Integer | Float)?
-    def self.parse_max_threads(value)
-      return unless value
-      return Float::INFINITY if value == "unlimited" || value == Float::INFINITY
-      return value if value.is_a?(Integer)
+    # @rbs (Integer | Float | String value, threads: Integer) -> (Integer | Float)
+    def self.parse_max_threads(value, threads:)
+      raise ArgumentError, "max_threads cannot be nil" unless value
+
+      max_threads = if value == "unlimited" || value == Float::INFINITY
+        Float::INFINITY
+      elsif value.is_a?(Integer)
+        value
+      else
+        Integer(value, 10)
+      end
+
+      raise ArgumentError, "max_threads must be greater than or equal to threads" if max_threads < threads
 
-      Integer(value, 10)
+      max_threads
     end
 
     # @rbs @command: Symbol
@@ -141,12 +155,13 @@ module Raptor
       end
 
       apply_config_file(extract_config_path(argv) || self.class.default_config_path)
+      apply_environment
 
       @parser = create_parser
       @parser.parse!(argv)
 
       @options[:rackup] = argv.first if @command == :server && argv.first
-      @options[:max_threads] = self.class.parse_max_threads(@options[:max_threads])
+      @options[:max_threads] = self.class.parse_max_threads(@options[:max_threads], threads: @options[:threads])
     end
 
     # Runs the requested command.
@@ -222,6 +237,18 @@ module Raptor
       end
     end
 
+    # Applies worker and thread settings from the environment. Explicit CLI
+    # options are parsed afterwards and take precedence.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def apply_environment
+      @options[:workers] = Integer(ENV["RAPTOR_WORKERS"], 10) if ENV["RAPTOR_WORKERS"]
+      @options[:threads] = Integer(ENV["RAPTOR_THREADS"], 10) if ENV["RAPTOR_THREADS"]
+      @options[:max_threads] = ENV["RAPTOR_MAX_THREADS"] if ENV["RAPTOR_MAX_THREADS"]
+    end
+
     # Creates the OptionParser instance with all supported command-line options.
     #
     # @return [OptionParser] configured option parser
@@ -259,10 +286,22 @@ module Raptor
           @options[:threads] = num
         end
 
-        opts.on("--max-threads NUM", "Maximum application threads per worker (`unlimited` for no limit; default: fixed at --threads)") do |num|
+        opts.on("--max-threads NUM", "Maximum application threads per worker (`unlimited` for no limit; default: unlimited)") do |num|
           @options[:max_threads] = num
         end
 
+        opts.on("--[no-]cpu-affinity", "Pin each worker process to a CPU (default: off)") do |bool|
+          @options[:cpu_affinity] = bool
+        end
+
+        opts.on("--[no-]clean-thread-locals", "Clear application thread locals after each request (default: on)") do |bool|
+          @options[:clean_thread_locals] = bool
+        end
+
+        opts.on("--[no-]clean-fiber-locals", "Process each request in a fresh Fiber (default: off)") do |bool|
+          @options[:clean_fiber_locals] = bool
+        end
+
         opts.on("-C", "--chdir PATH", String, "Change to PATH before loading the Rack application (default: none)") do |path|
           @options[:chdir] = path
         end
@@ -299,7 +338,7 @@ module Raptor
           @options[:http1][:persistent_data_timeout] = timeout
         end
 
-        opts.on("--http1-max-keepalive-requests NUM", Integer, "Maximum HTTP/1.1 requests per keep-alive connection (default: 100)") do |num|
+        opts.on("--http1-max-keepalive-requests NUM", Integer, "Maximum HTTP/1.1 requests per keep-alive connection (default: 1000)") do |num|
           @options[:http1][:max_keepalive_requests] = num
         end
 
@@ -335,6 +374,10 @@ module Raptor
           @options[:stats_file] = path
         end
 
+        opts.on("--control-url URI", String, "Serve cluster stats on a unix:// URI (default: off)") do |uri|
+          @options[:control_url] = uri
+        end
+
         opts.on("--pid-file PATH", String, "PID file path (default: none)") do |path|
           @options[:pid_file] = path
         end

data/lib/raptor/cluster.rb

@@ -3,6 +3,7 @@
 
 require "concurrent/utility/processor_counter"
 require "json"
+require "time"
 
 require "atomic-ruby/atomic_thread_pool"
 require "rack/builder"
@@ -10,6 +11,7 @@ require "ractor-pool"
 
 require_relative "log"
 require_relative "binder"
+require_relative "control_server"
 require_relative "reactor"
 require_relative "server"
 require_relative "reuseport_bpf"
@@ -74,6 +76,9 @@ module Raptor
     # @rbs @http2_ractor_count: Integer
     # @rbs @thread_count: Integer
     # @rbs @max_thread_count: (Integer | Float)?
+    # @rbs @cpu_affinity: bool
+    # @rbs @clean_thread_locals: bool
+    # @rbs @clean_fiber_locals: bool
     # @rbs @environment: String
     # @rbs @connection_options: Hash[Symbol, untyped]
     # @rbs @http1_options: Hash[Symbol, untyped]
@@ -87,6 +92,7 @@ module Raptor
     # @rbs @before_worker_shutdown: Array[Proc]
     # @rbs @before_refork: Array[Proc]
     # @rbs @stats_file: String?
+    # @rbs @control_server: ControlServer?
     # @rbs @pid_file: String?
     # @rbs @stdout_file: String?
     # @rbs @stderr_file: String?
@@ -102,6 +108,7 @@ module Raptor
     # @rbs @workers: Hash[Integer, Integer]
     # @rbs @timed_out: Set[Integer]
     # @rbs @stats: Stats
+    # @rbs @started_at: Float
     # @rbs @phase: Integer
     # @rbs @phased_restart_requested: bool
     # @rbs @phased_restarting: bool
@@ -126,7 +133,10 @@ module Raptor
     # @option options [Boolean] :drain_accept_queue whether to drain the kernel accept queue on shutdown
     # @option options [Integer] :workers number of worker processes
     # @option options [Integer] :threads number of threads per worker process
-    # @option options [Integer, Float, nil] :max_threads maximum number of threads per worker process, `Float::INFINITY` for no limit, or nil for a fixed-size pool
+    # @option options [Integer, Float] :max_threads maximum number of threads per worker process, or `Float::INFINITY` for no limit
+    # @option options [Boolean] :cpu_affinity whether to pin each worker to a CPU
+    # @option options [Boolean] :clean_thread_locals whether to clear application thread locals after each request
+    # @option options [Boolean] :clean_fiber_locals whether to process each request in a fresh Fiber
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
     # @option options [String, nil] :chdir directory to change to before loading the Rack application, or nil to leave the working directory unchanged
@@ -140,10 +150,11 @@ module Raptor
     # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [Integer, Array<Integer>, nil] :refork_after request-count threshold(s) at which a warm worker is promoted to a fork source for phased refork; nil or 0 disables. Requires `PR_SET_CHILD_SUBREAPER` (Linux)
     # @option options [Array<Proc>] :before_fork procs called in the master before every worker fork
-    # @option options [Array<Proc>] :before_worker_boot procs called in each worker before it begins serving
-    # @option options [Array<Proc>] :before_worker_shutdown procs called in each worker before its graceful shutdown
+    # @option options [Array<Proc>] :before_worker_boot procs called with the worker index before it begins serving
+    # @option options [Array<Proc>] :before_worker_shutdown procs called with the worker index before its graceful shutdown
     # @option options [Array<Proc>] :before_refork procs called in a worker before it transitions to a seed
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
+    # @option options [String, nil] :control_url `unix://` URL serving cluster stats, or nil to disable
     # @option options [String, nil] :pid_file path to write the master PID to, or nil to disable
     # @option options [String, nil] :stdout_file path to redirect stdout to, reopened on SIGHUP, or nil to disable
     # @option options [String, nil] :stderr_file path to redirect stderr to, reopened on SIGHUP, or nil to disable
@@ -161,6 +172,9 @@ module Raptor
       @http2_ractor_count = options[:http2][:ractors] || self.class.default_http2_ractor_count(@worker_count)
       @thread_count = options[:threads]
       @max_thread_count = options[:max_threads]
+      @cpu_affinity = options[:cpu_affinity]
+      @clean_thread_locals = options[:clean_thread_locals]
+      @clean_fiber_locals = options[:clean_fiber_locals]
       @environment = options[:environment] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
       @connection_options = options[:connection]
       @http1_options = options[:http1]
@@ -174,6 +188,7 @@ module Raptor
       @before_worker_shutdown = Array(options[:before_worker_shutdown])
       @before_refork = Array(options[:before_refork])
       @stats_file = options[:stats_file]
+      @control_server = ControlServer.new(options[:control_url]) { stats_hash } if options[:control_url]
       @pid_file = options[:pid_file]
       @stdout_file = options[:stdout_file]
       @stderr_file = options[:stderr_file]
@@ -202,6 +217,7 @@ module Raptor
       @workers = {}
       @timed_out = Set.new
       @stats = Stats.new(@worker_count)
+      @started_at = Process.clock_gettime(Process::CLOCK_REALTIME)
       @phase = 0
       @phased_restart_requested = false
       @phased_restarting = false
@@ -247,7 +263,9 @@ module Raptor
 
       @bpf_active = ReuseportBPF.setup(@worker_count)
 
+      @control_server&.bind
       @worker_count.times { |index| spawn_worker(index) }
+      @control_server&.start
 
       stats_file_thread = if @stats_file
         Thread.new do
@@ -274,6 +292,7 @@ module Raptor
       Systemd.notify("STOPPING=1")
       stop_workers
       stats_file_thread&.join
+      @control_server&.shutdown
       File.delete(@stats_file) rescue nil if @stats_file
       File.delete(@pid_file) rescue nil if @pid_file
       @stats.unmap
@@ -291,8 +310,57 @@ module Raptor
       @stats.all
     end
 
+    # Returns cluster statistics for the control server.
+    # For an adaptive pool, `max_threads` is the number of threads currently
+    # running so utilization reflects the capacity available at that moment.
+    #
+    # @return [Hash] cluster statistics
+    #
+    # @rbs () -> Hash[Symbol, untyped]
+    def stats_hash
+      worker_stats = @stats.all
+      worker_status = @workers.sort.map do |index, pid|
+        stat = worker_stats[index]
+        stat = {} unless stat && stat[:pid] == pid
+        capacity = stat.fetch(:thread_capacity, 0)
+        active = stat.fetch(:busy_threads, 0)
+        total_work = stat.fetch(:backlog, 0)
+
+        {
+          started_at: timestamp(stat.fetch(:started_at, 0)),
+          pid: pid,
+          index: index,
+          phase: stat.fetch(:phase, @phase),
+          booted: stat.fetch(:booted, false),
+          last_checkin: timestamp(stat.fetch(:last_checkin, 0)),
+          last_status: {
+            backlog: [total_work - active, 0].max,
+            running: capacity,
+            pool_capacity: [capacity - total_work, 0].max,
+            busy_threads: active,
+            max_threads: capacity,
+            requests_count: stat.fetch(:requests, 0),
+          },
+        }
+      end
+
+      {
+        started_at: timestamp(@started_at),
+        workers: worker_status.length,
+        phase: @phase,
+        booted_workers: worker_status.count { |worker| worker[:booted] },
+        old_workers: worker_status.count { |worker| worker[:phase] != @phase },
+        worker_status: worker_status,
+      }
+    end
+
     private
 
+    # @rbs (Float timestamp) -> String
+    def timestamp(timestamp)
+      Time.at(timestamp).utc.iso8601(6)
+    end
+
     # Returns the inherited-FDs hash for a systemd socket-activation handoff,
     # pairing each bind URI with the FD systemd passed at the same index.
     # Returns an empty hash when the FD count doesn't match the bind count.
@@ -700,6 +768,7 @@ module Raptor
       stop_workers
       @binder.clear_close_on_exec
       ENV[INHERITED_FDS_ENV] = JSON.generate(@binder.inheritable_fds)
+      @control_server&.shutdown
       File.delete(@stats_file) rescue nil if @stats_file
       File.delete(@pid_file) rescue nil if @pid_file
       @stats.unmap
@@ -731,7 +800,7 @@ module Raptor
       trap("USR2", "IGNORE")
       trap("URG") { promote_to_seed = true } if @fork_r
 
-      Raptor::CPU.pin(index) if Raptor::CPU.count >= @worker_count
+      Raptor::CPU.pin(index) if @cpu_affinity && Raptor::CPU.count >= @worker_count
 
       started_at = Process.clock_gettime(Process::CLOCK_REALTIME)
       request_count = 0
@@ -762,6 +831,8 @@ module Raptor
         connection_options: @connection_options,
         http1_options: @http1_options,
         access_log_io: @access_log_io,
+        clean_thread_locals: @clean_thread_locals,
+        clean_fiber_locals: @clean_fiber_locals,
         on_error: @on_error
       )
       http2 = Http2.new(
@@ -770,6 +841,8 @@ module Raptor
         connection_options: @connection_options,
         http2_options: @http2_options,
         access_log_io: @access_log_io,
+        clean_thread_locals: @clean_thread_locals,
+        clean_fiber_locals: @clean_fiber_locals,
         on_error: @on_error
       )
       http1_ractor_pool = RactorPool.new(
@@ -784,15 +857,17 @@ module Raptor
         end
       end
 
-      http2_ractor_pool = RactorPool.new(
-        size: @http2_ractor_count,
-        worker: http2.parser_worker,
-        name: "HTTP/2"
-      ) do |parsed_result|
-        begin
-          http2.handle_parsed_request(parsed_result, reactor, thread_pool)
-        rescue => error
-          Log.rescued_error(error)
+      http2_ractor_pool = if @binder.http2?
+        RactorPool.new(
+          size: @http2_ractor_count,
+          worker: http2.parser_worker,
+          name: "HTTP/2"
+        ) do |parsed_result|
+          begin
+            http2.handle_parsed_request(parsed_result, reactor, thread_pool)
+          rescue => error
+            Log.rescued_error(error)
+          end
         end
       end
 
@@ -827,7 +902,7 @@ module Raptor
       )
       server_thread = server.run
 
-      @before_worker_boot.each(&:call)
+      @before_worker_boot.each { |hook| hook.parameters.empty? ? hook.call : hook.call(index) }
 
       Log.info "Worker #{index} booted"
 
@@ -863,7 +938,7 @@ module Raptor
         @before_refork.each(&:call)
         server.stop_accepting
       else
-        @before_worker_shutdown.each(&:call)
+        @before_worker_shutdown.each { |hook| hook.parameters.empty? ? hook.call : hook.call(index) }
         server.shutdown
       end
 
@@ -871,7 +946,7 @@ module Raptor
       reactor.shutdown
       reactor_thread.join
       http1_ractor_pool.shutdown
-      http2_ractor_pool.shutdown
+      http2_ractor_pool&.shutdown
       http1.shutdown
       drain_thread_pool(thread_pool)
       stats_thread.join
@@ -979,8 +1054,10 @@ module Raptor
       Log.info "│     ├─ 1 server thread"
       Log.info "│     ├─ 1 reactor thread"
       Log.info "│     ├─ #{@http1_ractor_count} HTTP/1.1 pipeline ractor#{"s" if @http1_ractor_count > 1}"
-      Log.info "│     ├─ #{@http2_ractor_count} HTTP/2 pipeline ractor#{"s" if @http2_ractor_count > 1}"
-      Log.info "│     ├─ 2 pipeline collector threads"
+      http2_enabled = @binder.http2?
+      Log.info "│     ├─ #{@http2_ractor_count} HTTP/2 pipeline ractor#{"s" if @http2_ractor_count > 1}" if http2_enabled
+      collector_count = http2_enabled ? 2 : 1
+      Log.info "│     ├─ #{collector_count} pipeline collector thread#{"s" if collector_count > 1}"
       thread_limit = if @max_thread_count == Float::INFINITY
         " (scaling, no limit)"
       elsif @max_thread_count

data/lib/raptor/control_server.rb

@@ -0,0 +1,164 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "uri"
+
+require "atomic-ruby/atom"
+require "atomic-ruby/atomic_boolean"
+
+module Raptor
+  # Serves cluster statistics over a Unix socket.
+  #
+  class ControlServer
+    MAX_REQUEST_SIZE = 16 * 1024
+    REQUEST_TIMEOUT = 1
+
+    # @rbs @path: String
+    # @rbs @stats: ^() -> Hash[Symbol, untyped]
+    # @rbs @server: UNIXServer?
+    # @rbs @client: Atom
+    # @rbs @thread: Thread?
+    # @rbs @running: AtomicBoolean
+
+    # Creates a control server for `url` without binding it.
+    #
+    # @param url [String] `unix://` URL to listen on
+    # @yieldreturn [Hash] cluster statistics
+    # @return [void]
+    # @raise [ArgumentError] if the URL is not a Unix socket
+    #
+    # @rbs (String url) { () -> Hash[Symbol, untyped] } -> void
+    def initialize(url, &stats)
+      uri = URI(url)
+      raise ArgumentError, "control_url must use unix://" unless uri.scheme == "unix" && !uri.path.empty?
+
+      @path = uri.path
+      @stats = stats
+      @server = nil
+      @client = Atom.new(nil)
+      @thread = nil
+      @running = AtomicBoolean.new(false)
+    end
+
+    # Binds the Unix socket.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def bind
+      remove_stale_socket
+      @server = UNIXServer.new(@path)
+    end
+
+    # Starts serving requests in a background thread.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def start
+      @running.make_true
+      owner_pid = Process.pid
+      at_exit { File.delete(@path) rescue nil if Process.pid == owner_pid }
+
+      @thread = Thread.new do
+        Thread.current.name = "Control Server"
+
+        serve
+      end
+    end
+
+    # Stops serving and removes the socket.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown
+      @running.make_false
+      @server&.close
+      close_client
+      @thread&.join
+      File.delete(@path) rescue nil
+    end
+
+    private
+
+    # @rbs () -> void
+    def remove_stale_socket
+      return unless File.exist?(@path)
+
+      begin
+        UNIXSocket.new(@path).close
+        raise "Socket #{@path.inspect} is already in use"
+      rescue Errno::ECONNREFUSED
+        File.delete(@path)
+      end
+    end
+
+    # @rbs () -> void
+    def serve
+      while @running.true?
+        readable, = IO.select([@server], nil, nil, 1)
+        next unless readable
+
+        client = @server.accept_nonblock(exception: false)
+        next unless client.is_a?(UNIXSocket)
+
+        @client.swap { client }
+        unless @running.true?
+          close_client
+          break
+        end
+
+        handle(client)
+      end
+    rescue IOError, Errno::EBADF
+    end
+
+    # @rbs (UNIXSocket client) -> void
+    def handle(client)
+      request = read_request(client)
+      return unless request
+
+      if request.start_with?("GET /stats ")
+        body = JSON.generate(@stats.call)
+        client.write("HTTP/1.0 200 OK\r\nContent-Type: application/json\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}")
+      else
+        client.write("HTTP/1.0 404 Not Found\r\nContent-Length: 0\r\n\r\n")
+      end
+    rescue IOError, SystemCallError
+    ensure
+      close_client
+    end
+
+    # @rbs (UNIXSocket client) -> String?
+    def read_request(client)
+      request = String.new
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + REQUEST_TIMEOUT
+
+      loop do
+        return request if request.include?("\r\n\r\n")
+        return if request.bytesize >= MAX_REQUEST_SIZE
+
+        timeout = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return if timeout <= 0 || !client.wait_readable(timeout)
+
+        chunk = client.read_nonblock(MAX_REQUEST_SIZE - request.bytesize, exception: false)
+        return unless chunk.is_a?(String)
+
+        request << chunk
+      end
+    end
+
+    # @rbs () -> void
+    def close_client
+      client = nil
+      @client.swap do |current|
+        client = current
+        nil
+      end
+      client&.close
+    end
+  end
+end