raptor 0.3.0 → 0.5.0

data/lib/raptor/server.rb

@@ -6,28 +6,22 @@ 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 performed synchronously
-  # before the connection is dispatched.
-  #
-  # 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)
+  #   server = Server.new(binder, reactor, thread_pool, request, client_options: { first_data_timeout: 30 })
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -35,12 +29,17 @@ 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
     # @rbs @request: Request
+    # @rbs @client_options: Hash[Symbol, untyped]
     # @rbs @running: AtomicBoolean
 
     # Creates a new Server instance.
@@ -49,14 +48,16 @@ module Raptor
     # @param reactor [Reactor] the reactor for handling client connections
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param request [Request] the HTTP/1.1 request handler
+    # @param client_options [Hash] client timeout configuration, used to bound TLS handshakes
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request) -> void
-    def initialize(binder, reactor, thread_pool, request)
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
+    def initialize(binder, reactor, thread_pool, request, client_options:)
       @binder = binder
       @reactor = reactor
       @thread_pool = thread_pool
       @request = request
+      @client_options = client_options
       @running = AtomicBoolean.new(true)
     end
 
@@ -108,9 +109,11 @@ module Raptor
 
     # Accepts a connection from the given listener and dispatches it.
     #
-    # For SSL connections with h2 negotiated via ALPN, the server sends
-    # initial SETTINGS and adds the connection to the reactor as an HTTP/2
-    # connection. All other connections follow the HTTP/1.1 path.
+    # For SSL listeners the TLS handshake is offloaded to the thread pool so
+    # a slow client cannot block the server thread. For SSL connections with
+    # h2 negotiated via ALPN, the server sends initial SETTINGS and adds the
+    # connection to the reactor as an HTTP/2 connection. All other connections
+    # follow the HTTP/1.1 path.
     #
     # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
     # @param reactor [Reactor] the reactor to dispatch connections to
@@ -128,49 +131,120 @@ 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
 
-      url_scheme = HTTP_SCHEME
-      client = tcp_client
-
       if listener.is_a?(Binder::SslListener)
-        url_scheme = HTTPS_SCHEME
-        begin
-          ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_client, listener.ssl_context)
-          ssl_socket.sync_close = true
-          ssl_socket.accept
-          client = ssl_socket
-        rescue OpenSSL::SSL::SSLError => error
-          warn "SSL handshake failed: #{error.message}"
-          tcp_client.close rescue nil
-          return
+        @thread_pool << proc do
+          dispatch_ssl_connection(listener, tcp_client, remote_addr, reactor)
         end
+        return
+      end
 
-        if ssl_socket.alpn_protocol == H2_PROTOCOL
-          ssl_socket.write(Http2.build_server_settings_frame) rescue nil
+      @request.eager_accept(
+        tcp_client,
+        tcp_client.object_id,
+        reactor,
+        @thread_pool,
+        remote_addr,
+        HTTP_SCHEME
+      )
+    end
 
-          reactor.add(
-            id: ssl_socket.object_id,
-            socket: ssl_socket,
-            remote_addr: remote_addr,
-            url_scheme: HTTPS_SCHEME,
-            protocol: :http2,
-            writer: Http2::Writer.new
-          )
+    # Performs the TLS handshake for an accepted SSL connection and dispatches
+    # it through the HTTP/2 or HTTP/1.1 path. The handshake is bounded by
+    # `:first_data_timeout` so a slow client cannot pin a worker thread.
+    #
+    # @param listener [Binder::SslListener] the SSL listener that accepted the connection
+    # @param tcp_client [TCPSocket] the accepted TCP socket
+    # @param remote_addr [String] the client's IP address
+    # @param reactor [Reactor] the reactor to dispatch the connection to
+    # @return [void]
+    #
+    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
+    def dispatch_ssl_connection(listener, tcp_client, remote_addr, reactor)
+      ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_client, listener.ssl_context)
+      ssl_socket.sync_close = true
+      return unless perform_ssl_handshake(ssl_socket)
+
+      if ssl_socket.alpn_protocol == H2_PROTOCOL
+        ssl_socket.write(Http2.build_server_settings_frame) rescue nil
+
+        reactor.add(
+          id: ssl_socket.object_id,
+          socket: ssl_socket,
+          remote_addr: remote_addr,
+          url_scheme: HTTPS_SCHEME,
+          protocol: :http2,
+          writer: Http2::Writer.new,
+          flow_control: Http2::FlowControl.new
+        )
 
-          return
-        end
+        return
       end
 
       @request.eager_accept(
-        client,
-        client.object_id,
+        ssl_socket,
+        ssl_socket.object_id,
         reactor,
         @thread_pool,
         remote_addr,
-        url_scheme
+        HTTPS_SCHEME
       )
     end
+
+    # Drives a non-blocking SSL handshake to completion, bounded by the
+    # configured first-data timeout. Returns true on success, false on
+    # timeout or SSL error.
+    #
+    # @param ssl_socket [OpenSSL::SSL::SSLSocket] the SSL socket to hand-shake
+    # @return [Boolean] true if the handshake completed
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket ssl_socket) -> bool
+    def perform_ssl_handshake(ssl_socket)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @client_options[:first_data_timeout]
+
+      begin
+        ssl_socket.accept_nonblock
+        true
+      rescue IO::WaitReadable
+        return false unless wait_for_handshake(ssl_socket, deadline, :read)
+
+        retry
+      rescue IO::WaitWritable
+        return false unless wait_for_handshake(ssl_socket, deadline, :write)
+
+        retry
+      rescue OpenSSL::SSL::SSLError => error
+        Log.rescued_error(error)
+        ssl_socket.close rescue nil
+        false
+      end
+    end
+
+    # Waits up to `deadline` for the socket to become ready for the next step
+    # of the SSL handshake. Closes the socket and returns false on timeout.
+    #
+    # @param ssl_socket [OpenSSL::SSL::SSLSocket] the SSL socket
+    # @param deadline [Float] absolute monotonic deadline
+    # @param direction [Symbol] either `:read` or `:write`
+    # @return [Boolean] true if the socket became ready before the deadline
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket ssl_socket, Float deadline, Symbol direction) -> bool
+    def wait_for_handshake(ssl_socket, deadline, direction)
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      ready = if remaining <= 0
+        false
+      elsif direction == :read
+        ssl_socket.wait_readable(remaining)
+      else
+        ssl_socket.wait_writable(remaining)
+      end
+      return true if ready
+
+      Log.warn "SSL handshake timed out"
+      ssl_socket.close rescue nil
+      false
+    end
   end
 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.3.0"
+  VERSION = "0.5.0"
 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
@@ -20,6 +20,8 @@ module Raptor
 
     DEFAULT_OPTIONS: untyped
 
+    DEFAULT_CONFIG_PATHS: untyped
+
     # Loads a configuration file and returns the hash it evaluates to.
     #
     # The file is evaluated at the top level so constants like `Raptor::*` resolve
@@ -33,6 +35,18 @@ module Raptor
     # @rbs (String path) -> Hash[Symbol, untyped]
     def self.load_config_file: (String path) -> Hash[Symbol, untyped]
 
+    # 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
+    #
+    # @rbs (?String root) -> String?
+    def self.default_config_path: (?String root) -> String?
+
     @command: Symbol
 
     @options: Hash[Symbol, untyped]

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
 
-    @pidfile: 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] :pidfile path to write the master PID to, 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]
     #