raptor 0.4.0 → 0.5.1

data/lib/raptor/http2.rb

@@ -81,7 +81,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 = 0.001
@@ -529,7 +530,7 @@ module Raptor
 
       result[:completed_requests]&.each do |request|
         stream_id = request[:stream_id]
-        remote_addr = result[:remote_addr] || "127.0.0.1"
+        remote_addr = result[:remote_addr] || Server::DEFAULT_REMOTE_ADDR
 
         thread_pool << proc do
           dispatch_stream_request(
@@ -749,7 +750,7 @@ module Raptor
         env[Rack::SERVER_NAME] ||= host
         env[Rack::SERVER_PORT] ||= port || @server_port.to_s
       else
-        env[Rack::SERVER_NAME] ||= "localhost"
+        env[Rack::SERVER_NAME] ||= Server::DEFAULT_SERVER_NAME
         env[Rack::SERVER_PORT] ||= @server_port.to_s
       end
     end

data/lib/raptor/log.rb

@@ -0,0 +1,55 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+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(message)
+      Kernel.puts "#{prefix} #{message}"
+    end
+
+    # Writes a warning to stderr.
+    #
+    # @param message [String] the message to log
+    # @return [void]
+    #
+    # @rbs (String message) -> void
+    def self.warn(message)
+      Kernel.warn "#{prefix} #{message}"
+    end
+
+    # 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(error)
+      Kernel.warn "#{prefix} rescued:"
+      Kernel.warn error.full_message
+    end
+
+    # 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
+      ractor = Ractor.current.name || "main"
+      thread = Thread.current.name || "main"
+      "[Raptor #{Process.pid}|#{ractor}|#{thread}]"
+    end
+    private_class_method :prefix
+  end
+end

data/lib/raptor/reactor.rb

@@ -9,12 +9,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
   #   })
@@ -24,38 +24,38 @@ module Raptor
   #   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
 
-      # 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
         data
       end
 
-      # 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(now)
         [timeout_at - now, 0].max
       end
 
-      # 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 <=>(other)
@@ -80,18 +80,18 @@ 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(thread_pool, ractor_pool, client_options:)
-      @thread_pool = thread_pool
+    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
+    def initialize(ractor_pool, thread_pool, client_options:)
       @ractor_pool = ractor_pool
+      @thread_pool = thread_pool
       @client_options = client_options
 
       @selector = NIO::Selector.new
@@ -149,8 +149,7 @@ module Raptor
               register(@queue.pop)
             end
           rescue => error
-            warn "#{Thread.current.name} rescued:"
-            warn error.full_message
+            Log.rescued_error(error)
           end
         end
 
@@ -200,13 +199,12 @@ module Raptor
       socket.close
     end
 
-    # 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(id)
@@ -321,10 +319,8 @@ module Raptor
       socket.close rescue nil
     end
 
-    # 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/lib/raptor/request.rb

@@ -11,13 +11,10 @@ require "rack"
 require_relative "raptor_http"
 
 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 = 256 * 1024
@@ -27,7 +24,6 @@ module Raptor
     KEEPALIVE_READ_TIMEOUT = 0.001
     MAX_KEEPALIVE_REQUESTS = 100
 
-    HTTP_SCHEME = "http"
     HTTP_10 = "HTTP/1.0"
     HTTP_11 = "HTTP/1.1"
     STATUS_LINE_CACHE_10 = Hash.new do |h, status|
@@ -94,10 +90,8 @@ module Raptor
       [decoded, :incomplete]
     end
 
-    # 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
@@ -330,8 +324,8 @@ module Raptor
       else
         socket = reactor.remove(parsed_request[:id])
         request_count = (parsed_request[:request_count] || 0) + 1
-        remote_addr = parsed_request[:remote_addr] || "127.0.0.1"
-        url_scheme = parsed_request[:url_scheme] || HTTP_SCHEME
+        remote_addr = parsed_request[:remote_addr] || Server::DEFAULT_REMOTE_ADDR
+        url_scheme = parsed_request[:url_scheme] || Server::HTTP_SCHEME
 
         thread_pool << proc do
           process_client(
@@ -607,7 +601,7 @@ module Raptor
     # @return [Hash] fully populated Rack environment hash
     #
     # @rbs (Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, TCPSocket socket, ?remote_addr: String, ?url_scheme: String) -> Hash[String, untyped]
-    def build_rack_env(env, parse_data, body, socket, remote_addr: "127.0.0.1", url_scheme: HTTP_SCHEME)
+    def build_rack_env(env, parse_data, body, socket, remote_addr: Server::DEFAULT_REMOTE_ADDR, url_scheme: Server::HTTP_SCHEME)
       env[Rack::RACK_VERSION] = Rack::VERSION
       env[Rack::RACK_URL_SCHEME] = url_scheme
       env[Rack::RACK_INPUT] = build_rack_input(body)
@@ -647,7 +641,7 @@ module Raptor
         env[Rack::SERVER_NAME] ||= host
         env[Rack::SERVER_PORT] ||= port || @server_port.to_s
       else
-        env[Rack::SERVER_NAME] ||= "localhost"
+        env[Rack::SERVER_NAME] ||= Server::DEFAULT_SERVER_NAME
         env[Rack::SERVER_PORT] ||= @server_port.to_s
       end
 

data/lib/raptor/server.rb

@@ -6,26 +6,20 @@ require "socket"
 require "atomic-ruby/atomic_boolean"
 
 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
@@ -35,8 +29,12 @@ module Raptor
   class Server
     HTTP_SCHEME = "http"
     HTTPS_SCHEME = "https"
+
     H2_PROTOCOL = "h2"
 
+    DEFAULT_REMOTE_ADDR = "127.0.0.1"
+    DEFAULT_SERVER_NAME = "localhost"
+
     # @rbs @binder: Binder
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
@@ -133,7 +131,7 @@ module Raptor
         tcp_client.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
         remote_addr = tcp_client.remote_address.ip_address
       else
-        remote_addr = "127.0.0.1"
+        remote_addr = DEFAULT_REMOTE_ADDR
       end
 
       if listener.is_a?(Binder::SslListener)
@@ -218,7 +216,7 @@ module Raptor
 
         retry
       rescue OpenSSL::SSL::SSLError => error
-        warn "SSL handshake failed: #{error.message}"
+        Log.rescued_error(error)
         ssl_socket.close rescue nil
         false
       end
@@ -244,7 +242,7 @@ module Raptor
       end
       return true if ready
 
-      warn "SSL handshake timed out"
+      Log.warn "SSL handshake timed out"
       ssl_socket.close rescue nil
       false
     end

data/lib/raptor/stats.rb

@@ -12,26 +12,27 @@ 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 = "LQLddC"
-    SLOT_SIZE = [0, 0, 0, 0.0, 0.0, 0].pack(SLOT_FORMAT).bytesize
+    SLOT_FORMAT = "LLLQLLLddC"
+    SLOT_SIZE = [0, 0, 0, 0, 0, 0, 0, 0.0, 0.0, 0].pack(SLOT_FORMAT).bytesize
 
     # @rbs @num_workers: Integer
     # @rbs @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]
@@ -44,24 +45,27 @@ 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(index, pid:, requests:, backlog:, started_at:, last_checkin:, booted:)
-      data = [pid, requests, backlog, started_at, last_checkin, booted ? 1 : 0].pack(SLOT_FORMAT)
+    # @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(index, pid:, phase:, requests:, backlog:, busy_threads:, thread_capacity:, started_at:, last_checkin:, booted:)
+      data = [pid, index, phase, requests, backlog, busy_threads, thread_capacity, started_at, last_checkin, booted ? 1 : 0].pack(SLOT_FORMAT)
       @mmap.semlock { @mmap[index * SLOT_SIZE, SLOT_SIZE] = data }
     end
 
     # 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
@@ -81,14 +85,14 @@ 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(index)
-      data = @mmap[index * SLOT_SIZE, SLOT_SIZE]
-      pid, requests, backlog, started_at, last_checkin, booted = data.unpack(SLOT_FORMAT)
-      { pid:, requests:, backlog:, started_at:, last_checkin:, booted: booted == 1 }
+    # @rbs (Integer slot) -> Hash[Symbol, untyped]
+    def read(slot)
+      data = @mmap[slot * SLOT_SIZE, SLOT_SIZE]
+      pid, index, phase, requests, backlog, busy_threads, thread_capacity, started_at, last_checkin, booted = data.unpack(SLOT_FORMAT)
+      { pid:, index:, phase:, requests:, backlog:, busy_threads:, thread_capacity:, started_at:, last_checkin:, booted: booted == 1 }
     end
   end
 end

data/lib/raptor/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Raptor
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/sig/generated/raptor/cli.rbs

@@ -5,7 +5,7 @@ module Raptor
   #
   # CLI parses command-line arguments and starts the server cluster with the
   # specified configuration options. It supports configuring the number of
-  # workers, threads, ractors, bind addresses, and various client timeout
+  # workers, ractors, threads, bind addresses, and various client timeout
   # settings.
   #
   # @example Basic usage