raptor 0.4.0 → 0.5.0

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.0
 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