raptor 0.12.0 → 0.13.0

data/lib/raptor/cli.rb

@@ -70,11 +70,9 @@ module Raptor
 
     DEFAULT_CONFIG_PATHS = ["raptor.rb", "config/raptor.rb"].freeze
 
-    # Loads a configuration file and returns the hash it evaluates to.
-    #
-    # The file is evaluated at the top level so constants like `Raptor::*` resolve
-    # the same as in a regular Ruby script. The final expression must be a Hash
-    # of cluster options (the same keys accepted by {Raptor::Cluster#initialize}).
+    # Loads a Ruby config file and returns the options hash it evaluates
+    # to. Evaluated at the top level so `Raptor::*` constants resolve the
+    # same as in a regular script.
     #
     # @param path [String] path to a Ruby file that evaluates to a Hash
     # @return [Hash{Symbol => untyped}] cluster options
@@ -91,9 +89,6 @@ module Raptor
     # Returns the first existing path in {DEFAULT_CONFIG_PATHS} resolved
     # against `root`, or nil if none exist.
     #
-    # Used to pick up a project-local config file when no `-c`/`--config`
-    # flag was supplied.
-    #
     # @param root [String] directory to resolve the default paths against
     # @return [String, nil] the config path, or nil if no default file exists
     #
@@ -106,22 +101,14 @@ module Raptor
     # @rbs @options: Hash[Symbol, untyped]
     # @rbs @parser: OptionParser
 
-    # Creates a new CLI instance and parses command-line arguments.
-    #
-    # Parses the provided command-line arguments and configures the server
-    # options accordingly. A rackup file can be provided as the first
-    # positional argument (defaults to config.ru).
+    # Creates a new CLI instance from `argv`. A rackup file may be given
+    # as the first positional argument; every other value is parsed as a
+    # flag.
     #
     # @param argv [Array<String>] command-line arguments to parse
     # @return [void]
     # @raise [OptionParser::ParseError] if invalid options are provided
     #
-    # @example With rackup file
-    #   cli = CLI.new(["my_app.ru", "-w", "4"])
-    #
-    # @example With options only
-    #   cli = CLI.new(["-t", "8", "-r", "2"])
-    #
     # @rbs (Array[String] argv) -> void
     def initialize(argv)
       @options = DEFAULT_OPTIONS.dup
@@ -180,12 +167,9 @@ module Raptor
       end
     end
 
-    # Scans argv for a `-c`/`--config` flag and returns the configured path.
-    #
-    # The pre-scan runs before the main OptionParser pass so the config file
-    # can be applied as a base layer that CLI args then override. All four
-    # OptionParser-accepted forms (`-c PATH`, `-cPATH`, `--config PATH`,
-    # `--config=PATH`) are recognized.
+    # Returns the path from a `-c`/`--config` flag in `argv`, recognising
+    # all four OptionParser-accepted forms (`-c PATH`, `-cPATH`,
+    # `--config PATH`, `--config=PATH`).
     #
     # @param argv [Array<String>] command-line arguments to scan
     # @return [String, nil] the config path, or nil if no flag was supplied

data/lib/raptor/cluster.rb

@@ -18,39 +18,15 @@ require_relative "stats"
 require_relative "systemd"
 
 module Raptor
-  # Multi-process web server cluster with advanced concurrency architecture.
-  #
-  # Cluster manages multiple worker processes, each running a complete server
-  # stack including a ractor pool for HTTP parsing, a thread pool for
-  # application processing, plus dedicated reactor and server threads. It
-  # handles process forking, signal management, graceful shutdown, and
-  # automatic worker restart when a worker process unexpectedly exits.
-  #
-  # The architecture provides horizontal scaling through processes while
-  # maintaining efficient I/O and CPU utilization within each process
-  # through the combination of ractor-based parsing and thread pools on
-  # top of NIO reactors.
-  #
-  # Flow per worker process:
-  # 1. Server continuously accepts connections but skips acceptance when backlog is high
-  # 2. Reactor manages I/O multiplexing and provides backlog metrics for load control
-  # 3. Ractor pool handles CPU-intensive HTTP parsing in parallel
-  # 4. Thread pool processes Rack applications and handles response writing
-  # 5. Natural load balancing occurs through backpressure-based acceptance control
-  #
-  # @example Basic usage
-  #   options = {
-  #     workers: 4, ractors: 2, threads: 8,
-  #     binds: ["tcp://0.0.0.0:3000"],
-  #     rackup: "config.ru",
-  #     connection: { first_data_timeout: 30, chunk_data_timeout: 10 }
-  #   }
-  #   Cluster.run(options)
+  # Forks and supervises worker processes. Handles graceful shutdown on
+  # `INT` and `TERM`, phased restart on `USR1`, hot restart on `USR2`,
+  # and (on Linux) refork on `URG`. Restarts workers that exit
+  # unexpectedly or stop checking in.
   #
   class Cluster
     INHERITED_FDS_ENV = "RAPTOR_INHERITED_FDS"
 
-    # Convenience method to create and run a cluster with the given options.
+    # Creates and runs a cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
     # @return [void]
@@ -108,11 +84,7 @@ module Raptor
     # @rbs @resp_w: IO?
     # @rbs @bpf_active: bool
 
-    # Creates a new Cluster with the specified configuration.
-    #
-    # Initializes the cluster with worker, ractor, and thread counts,
-    # sets up network binding, loads the Rack application, and prepares
-    # for multi-process operation.
+    # Creates a new Cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
     # @option options [Array<String>] :binds array of bind URIs
@@ -207,20 +179,7 @@ module Raptor
       @seed_vacated_index = nil
     end
 
-    # Starts the multi-process cluster and manages worker processes.
-    #
-    # Forks the configured number of worker processes and monitors them,
-    # restarting any that exit unexpectedly or stop checking in. Handles
-    # graceful shutdown via INT or TERM signals, phased restart via USR1,
-    # and hot restart via USR2.
-    #
-    # Each worker process includes:
-    # - 1 server thread (continuously accepts connections with backpressure control)
-    # - 1 reactor thread (I/O multiplexing, timeout handling, backlog monitoring)
-    # - N pipeline ractors (parallel HTTP parsing)
-    # - 1 pipeline collector thread (coordinates parsing results)
-    # - M worker threads (Rack application processing and response writing)
-    # - 1 stats thread (writes per-worker metrics to shared memory every second)
+    # Runs the cluster until a graceful shutdown is signalled.
     #
     # @return [void]
     #
@@ -288,7 +247,8 @@ module Raptor
     # Returns stats for all worker processes.
     #
     # @return [Array<Hash>] array of per-worker stat hashes, each containing
-    #   :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    #   :pid, :index, :phase, :requests, :backlog, :busy_threads,
+    #   :thread_capacity, :started_at, :last_checkin, and :booted
     #
     # @rbs () -> Array[Hash[Symbol, untyped]]
     def stats
@@ -299,8 +259,7 @@ module Raptor
 
     # Returns the inherited-FDs hash for a systemd socket-activation handoff,
     # pairing each bind URI with the FD systemd passed at the same index.
-    # The activation is skipped (with a warning) when the FD count doesn't
-    # match the number of bind URIs.
+    # Returns an empty hash when the FD count doesn't match the bind count.
     #
     # @param bind_uris [Array<String>] the configured bind URIs
     # @param filenos [Array<Integer>] file descriptors passed by systemd
@@ -779,7 +738,7 @@ module Raptor
       )
       ractor_pool = RactorPool.new(
         size: @ractor_count,
-        worker: http1.http_parser_worker
+        worker: http1.parser_worker
       ) do |parsed_result|
         begin
           if parsed_result[:protocol] == :http2
@@ -802,6 +761,7 @@ module Raptor
 
       worker_listeners = if @bpf_active
         bpf_listeners = ReuseportBPF.create_worker_listeners(@binder.bind_uris, index, @binder.socket_backlog)
+        ReuseportBPF.enable_load_reporting(index)
         non_tcp_listeners = @binder.listeners.reject { |listener| listener.is_a?(TCPServer) }
         bpf_listeners + non_tcp_listeners
       else
@@ -917,7 +877,11 @@ module Raptor
     #
     # @rbs (AtomicThreadPool thread_pool) -> void
     def drain_thread_pool(thread_pool)
-      drain = Thread.new { thread_pool.shutdown }
+      drain = Thread.new do
+        Thread.current.name = "Thread Pool Drain"
+
+        thread_pool.shutdown
+      end
       return if drain.join(@worker_drain_timeout)
 
       Log.warn "Force-killing in-flight app threads after #{@worker_drain_timeout}s drain timeout"

data/lib/raptor/http.rb

@@ -93,6 +93,24 @@ module Raptor
       end
     end
 
+    # Returns a Ractor-safe proc that routes each pipeline task to the
+    # HTTP/1.x or HTTP/2 handler based on the state hash's `:protocol` key.
+    #
+    # @param env_template [Hash] the Rack env template to seed each HTTP/1.x request with
+    # @param max_body_size [Integer, nil] byte limit for HTTP/1.x request bodies, or nil for no limit
+    # @return [Proc]
+    #
+    # @rbs (Hash[String, untyped] env_template, Integer? max_body_size) -> ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+    def self.parser_worker(env_template, max_body_size)
+      proc do |data|
+        if data[:protocol] == :http2
+          Raptor::Http2.process_frames(data)
+        else
+          Raptor::Http1.parse(data, env_template, max_body_size)
+        end
+      end
+    end
+
     # Writes a Common Log Format entry to `io`. Write failures are silently
     # ignored.
     #