raptor 0.4.0 → 0.5.1

data/sig/generated/raptor/cluster.rbs

@@ -4,14 +4,15 @@ module Raptor
   # Multi-process web server cluster with advanced concurrency architecture.
   #
   # Cluster manages multiple worker processes, each running a complete server
-  # stack including a reactor thread, server thread, ractor pool for HTTP
-  # parsing, and thread pool for application processing. It handles process
-  # forking, signal management, graceful shutdown, and automatic worker
-  # restart when a worker process unexpectedly exits.
+  # 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 NIO reactors, ractor-based parsing, and thread pools.
+  # 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
@@ -22,7 +23,7 @@ module Raptor
   #
   # @example Basic usage
   #   options = {
-  #     threads: 8, ractors: 2, workers: 4,
+  #     workers: 4, ractors: 2, threads: 8,
   #     binds: ["tcp://0.0.0.0:3000"],
   #     rackup: "config.ru",
   #     client: { first_data_timeout: 30, chunk_data_timeout: 10 }
@@ -37,53 +38,66 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @phased_restarting: bool
+    @thread_count: Integer
 
-    @phased_restart_requested: bool
+    @client_options: Hash[Symbol, Integer]
 
-    @stats: Stats
+    @worker_timeout: Integer
 
-    @workers: Hash[Integer, Integer]
+    @worker_boot_timeout: Integer
 
-    @shutdown: bool
+    @worker_shutdown_timeout: Integer
 
-    @app: untyped
+    @stats_file: String?
 
-    @server_port: Integer
+    @pid_file: String?
+
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     @binder: Binder
 
-    @pid_file: String?
+    @server_port: Integer
 
-    @stats_file: String?
+    @app: untyped
 
-    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    @shutdown: bool
 
-    @client_options: Hash[Symbol, Integer]
+    @workers: Hash[Integer, Integer]
 
-    @worker_count: Integer
+    @timed_out: Set[Integer]
+
+    @stats: Stats
+
+    @phase: Integer
+
+    @phased_restart_requested: bool
+
+    @phased_restarting: bool
 
     @ractor_count: Integer
 
-    @thread_count: Integer
+    @worker_count: Integer
 
     # Creates a new Cluster with the specified configuration.
     #
-    # Initializes the cluster with thread, ractor, and worker counts,
+    # Initializes the cluster with worker, ractor, and thread counts,
     # sets up network binding, loads the Rack application, and prepares
     # for multi-process operation.
     #
     # @param options [Hash] cluster configuration options
-    # @option options [Integer] :threads number of threads per worker process
-    # @option options [Integer] :ractors number of ractors per worker process
-    # @option options [Integer] :workers number of worker processes
     # @option options [Array<String>] :binds array of bind URIs
+    # @option options [Integer] :workers number of worker processes
+    # @option options [Integer] :ractors number of ractors per worker process
+    # @option options [Integer] :threads number of threads per worker process
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
     # @option options [Hash] :client client configuration
-    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
+    # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
+    # @option options [Integer] :worker_boot_timeout seconds to wait for a worker to finish booting before killing it
+    # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
     # @option options [String, nil] :pid_file path to write the master PID to, or nil to disable
+    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] options) -> void
@@ -92,15 +106,15 @@ module Raptor
     # Starts the multi-process cluster and manages worker processes.
     #
     # Forks the configured number of worker processes and monitors them,
-    # automatically restarting any that exit unexpectedly. Handles graceful
-    # shutdown via INT or TERM signals, stats logging via USR1, and phased
-    # restart via USR2.
+    # restarting any that exit unexpectedly or stop checking in. Handles
+    # graceful shutdown via INT or TERM signals, stats logging via USR1,
+    # and phased 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 ractor workers (parallel HTTP parsing)
-    # - 1 ractor collector thread (coordinates parsing results)
+    # - 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)
     #
@@ -120,6 +134,7 @@ module Raptor
     private
 
     # Forks a new worker process and registers it at the given index.
+    # The worker inherits the cluster's current phase.
     #
     # @param index [Integer] slot index for this worker in the stats region
     # @return [void]
@@ -135,6 +150,25 @@ module Raptor
     # @rbs () -> Symbol
     def reap_workers: () -> Symbol
 
+    # Stops every worker, escalating from TERM to KILL if any fail to
+    # exit within `worker_shutdown_timeout`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def stop_workers: () -> void
+
+    # Kills workers that have stopped checking in. A booted worker that
+    # fails to update its stats slot within `worker_timeout` seconds is
+    # assumed to be hung (deadlocked app, runaway loop, blocked syscall);
+    # a worker still in startup is held to `worker_boot_timeout`. Killed
+    # workers are then restarted by `reap_workers`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def timeout_hung_workers: () -> void
+
     # Replaces each worker process one at a time, waiting for the new
     # worker to boot before moving on to the next. Triggered by SIGUSR2.
     #
@@ -150,10 +184,11 @@ module Raptor
     # critical component fails.
     #
     # @param index [Integer] slot index for this worker in the stats region
+    # @param phase [Integer] the cluster phase this worker was forked at
     # @return [void]
     #
-    # @rbs (Integer index) -> void
-    def run_worker: (Integer index) -> void
+    # @rbs (Integer index, Integer phase) -> void
+    def run_worker: (Integer index, Integer phase) -> void
 
     # Returns a human-readable description of how a process exited.
     #
@@ -170,11 +205,8 @@ module Raptor
     # @rbs () -> void
     def shutdown: () -> void
 
-    # Logs cluster initialization details including architecture and bind addresses.
-    #
-    # Outputs a hierarchical view of the cluster configuration showing
-    # the master process, worker processes, and per-process thread/ractor
-    # allocation along with listening addresses.
+    # Prints the cluster's startup banner showing process structure
+    # and bind addresses.
     #
     # @return [void]
     #

data/sig/generated/raptor/http2.rbs

@@ -39,7 +39,8 @@ module Raptor
     # outbound DATA frames respect RFC 7540 §5.2. Threads dispatching stream
     # responses call `acquire` to reserve send capacity; threads applying
     # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
-    # replenish it. State is held in a single `Atom` so updates use CAS.
+    # replenish it. The connection window and per-stream windows live in
+    # separate `Atom`s so the common fast path skips per-stream tracking.
     class FlowControl
       ACQUIRE_POLL_INTERVAL: ::Float
 

data/sig/generated/raptor/log.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/raptor/log.rb with RBS::Inline
+
+module Raptor
+  # Shared logging helpers. Every line is prefixed with
+  # `[Raptor <pid>|<ractor>|<thread>]` so output is identifiable
+  # and traceable to its source in a mixed log stream.
+  module Log
+    # Writes an informational message to stdout.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.info: (String message) -> void
+
+    # Writes a warning to stderr.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.warn: (String message) -> void
+
+    # Logs a rescued exception to stderr. The full message (class,
+    # message, backtrace) is written on subsequent unprefixed lines.
+    #
+    # @param error [Exception] the rescued exception
+    # @return [void]
+    #
+    # @rbs (Exception error) -> void
+    def self.rescued_error: (Exception error) -> void
+
+    # Builds the log line prefix from the current process, ractor,
+    # and thread. Unnamed ractors and threads are reported as `main`.
+    #
+    # @return [String] the prefix
+    #
+    # @rbs () -> String
+    def self.prefix: () -> String
+  end
+end

data/sig/generated/raptor/reactor.rbs

@@ -5,12 +5,12 @@ module Raptor
   #
   # Reactor uses NIO selectors for efficient I/O multiplexing and implements
   # client timeouts using a red-black tree for O(log n) timeout management.
-  # It coordinates between thread pools for blocking operations and ractor
-  # pools for CPU-intensive HTTP parsing, and provides backlog metrics
-  # that the server uses for backpressure control to prevent overload.
+  # It coordinates between ractor pools for CPU-intensive HTTP parsing and
+  # thread pools for blocking operations, and provides backlog metrics that
+  # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
   #     first_data_timeout: 30,
   #     chunk_data_timeout: 10
   #   })
@@ -19,33 +19,33 @@ module Raptor
   #   # ... later
   #   reactor.shutdown
   class Reactor
-    # Red-black tree node representing a client connection with timeout tracking.
-    #
-    # TimeoutClient extends RedBlackTree::Node to enable efficient timeout
-    # management using the tree's ordering properties.
+    # A client connection node ordered by absolute expiry time so the
+    # soonest-to-expire is always at the tree's minimum.
     class TimeoutClient < RedBlackTree::Node
       # @rbs attr_accessor timeout_at: Float
       attr_accessor timeout_at: untyped
 
-      # Returns the client data stored in this timeout node.
+      # Semantic alias for the inherited `data` slot.
       #
-      # @return [Hash] the client connection state data
+      # @return [Hash] the client connection state
       #
       # @rbs () -> Hash[Symbol, untyped]
       def client_data: () -> Hash[Symbol, untyped]
 
-      # Calculates remaining timeout duration from the current time.
+      # Returns seconds until expiry, clamped to 0 so an already-expired
+      # client doesn't push the next selector wait into the future.
       #
       # @param now [Float] current monotonic timestamp
-      # @return [Float] remaining timeout in seconds, minimum 0
+      # @return [Float] seconds until expiry, never negative
       #
       # @rbs (Float now) -> Float
       def timeout: (Float now) -> Float
 
-      # Compares timeout nodes by their timeout_at values for tree ordering.
+      # Orders nodes by `timeout_at` so the tree minimum is the next
+      # client to expire.
       #
       # @param other [TimeoutClient] another timeout client to compare
-      # @return [Integer] -1, 0, or 1 for ordering
+      # @return [Integer] -1, 0, or 1
       #
       # @rbs (TimeoutClient other) -> Integer
       def <=>: (TimeoutClient other) -> Integer
@@ -79,16 +79,16 @@ module Raptor
 
     # Creates a new Reactor instance.
     #
-    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param client_options [Hash] timeout configuration options
     # @option client_options [Integer] :first_data_timeout timeout for initial data
     # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
     # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
     # @return [void]
     #
-    # @rbs (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize: (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
+    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
+    def initialize: (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
 
     # Starts the reactor's main event loop in a new thread.
     #
@@ -123,13 +123,12 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def update_state: (Hash[Symbol, untyped] state) -> void
 
-    # Removes a client connection from the reactor.
-    #
-    # Called when an HTTP request is complete and ready for application
-    # processing. Triggers server accept re-enabling if system capacity allows.
+    # Drops the reactor's references to a client whose parsed request
+    # has been handed off to the thread pool. The socket itself is kept
+    # open so the worker can write the response.
     #
     # @param id [Integer] unique client identifier
-    # @return [TCPSocket, nil] the removed socket, if found
+    # @return [TCPSocket, nil] the socket associated with `id`, if any
     #
     # @rbs (Integer id) -> TCPSocket?
     def remove: (Integer id) -> TCPSocket?
@@ -202,10 +201,8 @@ module Raptor
     # @rbs (Integer id) -> void
     def close_connection: (Integer id) -> void
 
-    # Initiates reactor shutdown.
-    #
-    # Closes the registration queue and wakes up the selector to begin
-    # graceful shutdown process.
+    # Closes the registration queue and wakes the selector so the
+    # event loop drains pending work and exits.
     #
     # @return [void]
     #

data/sig/generated/raptor/request.rbs

@@ -1,13 +1,10 @@
 # Generated from lib/raptor/request.rb with RBS::Inline
 
 module Raptor
-  # Handles HTTP request processing and Rack application integration.
-  #
-  # Request manages the HTTP parsing pipeline using Ractors and coordinates
-  # with the reactor for connection state management. It bridges between the
-  # low-level HTTP parsing and high-level Rack application interface, handling
-  # both incomplete requests (that need more data) and complete requests
-  # (ready for application processing).
+  # Parses HTTP/1.x requests and dispatches them to the Rack
+  # application. Coordinates with the Ractor pool for parsing and
+  # with the reactor for requests that need more data before they
+  # can be handled.
   class Request
     BODY_BUFFER_THRESHOLD: untyped
 
@@ -21,8 +18,6 @@ module Raptor
 
     MAX_KEEPALIVE_REQUESTS: ::Integer
 
-    HTTP_SCHEME: ::String
-
     HTTP_10: ::String
 
     HTTP_11: ::String
@@ -80,10 +75,8 @@ module Raptor
     # @rbs (String buffer, ?Integer? max_size) -> [String, Symbol]
     def self.decode_chunked: (String buffer, ?Integer? max_size) -> [ String, Symbol ]
 
-    # Writes a string to the socket, retrying on partial writes and flow control blocks.
-    #
-    # Uses write_nonblock with `WRITE_TIMEOUT` to avoid blocking the thread
-    # indefinitely on slow clients.
+    # Writes `string` in full, retrying on partial writes. Bounded by
+    # `WRITE_TIMEOUT` so a slow client can't pin the writing thread.
     #
     # @param socket [TCPSocket] the socket to write to
     # @param string [String] the data to write

data/sig/generated/raptor/server.rbs

@@ -1,26 +1,20 @@
 # Generated from lib/raptor/server.rb with RBS::Inline
 
 module Raptor
-  # High-performance HTTP server that accepts connections and dispatches them.
+  # Accepts client connections and dispatches them into the request
+  # pipeline. Skips acceptance when the reactor backlog is high so an
+  # overloaded process leaves connections for peers that can absorb
+  # them (via shared `SO_REUSEPORT` listeners).
   #
-  # Server manages the main accept loop, handling incoming client connections from
-  # bound sockets. It uses IO.select for efficient polling and implements automatic
-  # load balancing by checking reactor backlog before accepting connections,
-  # providing natural backpressure based on system capacity.
-  #
-  # Supports TCP, Unix domain, and SSL listeners transparently. TCP_NODELAY is
-  # applied only to TCP sockets, and SSL handshakes are offloaded to the thread
-  # pool so a slow client cannot block the server thread.
-  #
-  # For HTTP/1.1 connections the first request is parsed inline on the server
-  # thread and dispatched directly to the thread pool, falling back to the
-  # reactor only when more data is needed. For HTTP/2 connections (negotiated
-  # via ALPN) the server sends initial SETTINGS and registers the connection
-  # with the reactor for frame processing through the ractor pool.
+  # Supports TCP, Unix, and SSL listeners. SSL handshakes are offloaded
+  # to the thread pool so a slow client can't pin the server thread.
+  # For HTTP/1.1 the first request is parsed inline and dispatched
+  # straight to the thread pool; HTTP/2 (negotiated via ALPN) is
+  # registered with the reactor for frame processing.
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {})
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {})
   #   request = Request.new(app, 3000)
   #   server = Server.new(binder, reactor, thread_pool, request, client_options: { first_data_timeout: 30 })
   #   server.run
@@ -33,6 +27,10 @@ module Raptor
 
     H2_PROTOCOL: ::String
 
+    DEFAULT_REMOTE_ADDR: ::String
+
+    DEFAULT_SERVER_NAME: ::String
+
     @running: AtomicBoolean
 
     @client_options: Hash[Symbol, untyped]

data/sig/generated/raptor/stats.rbs

@@ -9,13 +9,17 @@ module Raptor
   # assigned a fixed-size slot in the shared region.
   #
   # Binary layout per slot (native byte order):
-  #   pid           uint32    4 bytes
-  #   requests      uint64    8 bytes
-  #   backlog       uint32    4 bytes
-  #   started_at    float64   8 bytes
-  #   last_checkin  float64   8 bytes
-  #   booted        uint8     1 byte
-  #                          33 bytes total
+  #   pid               uint32    4 bytes
+  #   index             uint32    4 bytes
+  #   phase             uint32    4 bytes
+  #   requests          uint64    8 bytes
+  #   backlog           uint32    4 bytes
+  #   busy_threads      uint32    4 bytes
+  #   thread_capacity   uint32    4 bytes
+  #   started_at        float64   8 bytes
+  #   last_checkin      float64   8 bytes
+  #   booted            uint8     1 byte
+  #                              49 bytes total
   class Stats
     SLOT_FORMAT: ::String
 
@@ -25,11 +29,8 @@ module Raptor
 
     @mmap: untyped
 
-    # Creates a new Stats instance backed by anonymous shared memory.
-    #
-    # Allocates a MAP_ANON | MAP_SHARED mmap region large enough for
-    # num_workers slots. Must be called before forking so that all
-    # worker processes share the same backing memory.
+    # Allocates the shared mmap region. Must be called before forking
+    # workers so the mapping is inherited by every child process.
     #
     # @param num_workers [Integer] number of worker slots to allocate
     # @return [void]
@@ -39,21 +40,24 @@ module Raptor
 
     # Writes stats for a worker slot into shared memory.
     #
-    # @param index [Integer] slot index to write into
+    # @param index [Integer] slot index to write into; also written into the slot itself
     # @param pid [Integer] worker process ID
+    # @param phase [Integer] cluster phase this worker was forked at
     # @param requests [Integer] total requests handled by this worker
     # @param backlog [Integer] current queue depth
+    # @param busy_threads [Integer] worker threads currently processing requests
+    # @param thread_capacity [Integer] worker threads configured for this worker
     # @param started_at [Float] process start time as a Unix timestamp
     # @param last_checkin [Float] time of last stats write as a Unix timestamp
     # @param booted [Boolean] whether the worker has finished starting
     # @return [void]
     #
-    # @rbs (Integer index, pid: Integer, requests: Integer, backlog: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
-    def write: (Integer index, pid: Integer, requests: Integer, backlog: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
+    # @rbs (Integer index, pid: Integer, phase: Integer, requests: Integer, backlog: Integer, busy_threads: Integer, thread_capacity: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
+    def write: (Integer index, pid: Integer, phase: Integer, requests: Integer, backlog: Integer, busy_threads: Integer, thread_capacity: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
 
     # Returns stats for all worker slots.
     #
-    # @return [Array<Hash>] per-worker stat hashes with :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    # @return [Array<Hash>] per-worker stat hashes with :pid, :index, :phase, :requests, :backlog, :busy_threads, :thread_capacity, :started_at, :last_checkin, and :booted
     #
     # @rbs () -> Array[Hash[Symbol, untyped]]
     def all: () -> Array[Hash[Symbol, untyped]]
@@ -69,10 +73,10 @@ module Raptor
 
     # Reads stats for a worker slot from shared memory.
     #
-    # @param index [Integer] slot index to read from
-    # @return [Hash] stat hash with :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    # @param slot [Integer] slot offset to read from
+    # @return [Hash] stat hash with :pid, :index, :phase, :requests, :backlog, :busy_threads, :thread_capacity, :started_at, :last_checkin, and :booted
     #
-    # @rbs (Integer index) -> Hash[Symbol, untyped]
-    def read: (Integer index) -> Hash[Symbol, untyped]
+    # @rbs (Integer slot) -> Hash[Symbol, untyped]
+    def read: (Integer slot) -> Hash[Symbol, untyped]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Joshua Young
@@ -103,6 +103,8 @@ extensions:
 extra_rdoc_files: []
 files:
 - ".buildkite/pipeline.yml"
+- ".mise.toml"
+- Brewfile
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -120,6 +122,7 @@ files:
 - lib/raptor/cli.rb
 - lib/raptor/cluster.rb
 - lib/raptor/http2.rb
+- lib/raptor/log.rb
 - lib/raptor/reactor.rb
 - lib/raptor/request.rb
 - lib/raptor/server.rb
@@ -131,6 +134,7 @@ files:
 - sig/generated/raptor/cli.rbs
 - sig/generated/raptor/cluster.rbs
 - sig/generated/raptor/http2.rbs
+- sig/generated/raptor/log.rbs
 - sig/generated/raptor/reactor.rbs
 - sig/generated/raptor/request.rbs
 - sig/generated/raptor/server.rbs