raptor 0.7.0 → 0.9.0

data/lib/raptor/server.rb

@@ -5,6 +5,8 @@ require "socket"
 
 require "atomic-ruby/atomic_boolean"
 
+require_relative "reuseport_bpf"
+
 module Raptor
   # Accepts client connections and dispatches them into the request
   # pipeline. Skips acceptance when the reactor backlog is high so an
@@ -19,9 +21,10 @@ module Raptor
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   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 })
+  #   reactor = Reactor.new(ractor_pool, thread_pool, connection_options: {}, http1_options: {})
+  #   http1 = Http1.new(app, 3000)
+  #   http2 = Http2.new(app, 3000)
+  #   server = Server.new(binder, reactor, thread_pool, http1, http2, connection_options: { first_data_timeout: 30 }, listeners: binder.listeners)
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -35,13 +38,17 @@ module Raptor
     DEFAULT_REMOTE_ADDR = "127.0.0.1"
     DEFAULT_SERVER_NAME = "localhost"
 
-    MIN_BACKPRESSURE_THRESHOLD = 64
+    MIN_BACKPRESSURE_THRESHOLD = 8
 
     # @rbs @binder: Binder
+    # @rbs @listeners: Array[TCPServer | UNIXServer | Binder::SslListener]
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
-    # @rbs @request: Request
-    # @rbs @client_options: Hash[Symbol, untyped]
+    # @rbs @http1: Http1
+    # @rbs @http2: Http2
+    # @rbs @first_data_timeout: Integer
+    # @rbs @drain_accept_queue: bool
+    # @rbs @bpf_active: bool
     # @rbs @running: AtomicBoolean
 
     # Creates a new Server instance.
@@ -49,66 +56,109 @@ module Raptor
     # @param binder [Binder] the binder managing listening sockets
     # @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
+    # @param http1 [Http1] the HTTP/1.1 handler
+    # @param http2 [Http2] the HTTP/2 handler (provides the initial SETTINGS frame)
+    # @param connection_options [Hash] per-connection timeout configuration, used to bound TLS handshakes
+    # @param listeners [Array] the per-worker listeners this server accepts on
+    # @param drain_accept_queue [Boolean] whether to drain the kernel accept queue on shutdown
+    # @param worker_index [Integer, nil] the slot index for BPF load reporting
     # @return [void]
     #
-    # @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:)
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], listeners: Array[untyped], ?drain_accept_queue: bool, ?worker_index: Integer?) -> void
+    def initialize(binder, reactor, thread_pool, http1, http2, connection_options:, listeners:, drain_accept_queue: false, worker_index: nil)
       @binder = binder
+      @listeners = listeners
       @reactor = reactor
       @thread_pool = thread_pool
-      @request = request
-      @client_options = client_options
+      @http1 = http1
+      @http2 = http2
+      @first_data_timeout = connection_options[:first_data_timeout]
+      @drain_accept_queue = drain_accept_queue
+      @bpf_active = !!worker_index
       @running = AtomicBoolean.new(true)
     end
 
     # Starts the server's main accept loop in a new thread.
     #
     # The accept loop polls listening sockets for ready connections and accepts
-    # them when system capacity allows. It checks reactor backlog before accepting
-    # to prevent overload. This provides natural load balancing across multiple
-    # worker processes through backpressure control.
+    # them when the reactor backlog is under the backpressure threshold. On
+    # Linux with BPF-directed dispatch active, a companion thread publishes
+    # this worker's backlog to the BPF map.
     #
     # @return [Thread] the thread running the accept loop
     #
     # @rbs () -> Thread
     def run
-      Thread.new(@binder.listeners, @reactor, @running) do |server_sockets, reactor, running|
+      spawn_load_reporter if @bpf_active
+
+      Thread.new do
         Thread.current.name = "Server"
 
-        while running.true?
+        backpressure_threshold = [(@thread_pool.size * 1.2).ceil, MIN_BACKPRESSURE_THRESHOLD].max
+
+        while @running.true?
           begin
-            ready_servers, _, _ = IO.select(server_sockets, nil, nil, 1)
+            ready_servers, _, _ = IO.select(@listeners, nil, nil, 1)
           rescue IOError, Errno::EBADF
             break
           end
 
           next unless ready_servers
-          next if @reactor.backlog >= [(@thread_pool.size * 1.2).ceil, MIN_BACKPRESSURE_THRESHOLD].max
+          next if @reactor.backlog >= backpressure_threshold
 
-          ready_servers.each do |listener|
-            accept_connection(listener, reactor)
-          end
+          ready_servers.each { |listener| accept_connection(listener) }
         end
       end
     end
 
     # Gracefully shuts down the server.
     #
-    # Stops accepting new connections and closes all listening sockets.
-    # The server thread will exit after handling any in-flight accept operations.
+    # Stops accepting new connections and closes all listening sockets. When
+    # `drain_accept_queue` is enabled, dispatches every connection already in
+    # the kernel accept queue before closing the listeners.
     #
     # @return [void]
     #
     # @rbs () -> void
     def shutdown
       @running.make_false
-      @binder.close
+      drain_accept_queue if @drain_accept_queue
+      @listeners.each(&:close)
     end
 
     private
 
+    # Starts a background thread that publishes this worker's reactor
+    # backlog to the BPF map for load-aware dispatch.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def spawn_load_reporter
+      Thread.new do
+        Thread.current.name = "Load Reporter"
+
+        while @running.true?
+          ReuseportBPF.update_load(@reactor.backlog)
+          sleep 0.01
+        end
+      end
+    end
+
+    # Dispatches every connection already in the kernel accept queue for each
+    # listener until all are drained.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def drain_accept_queue
+      loop do
+        accepted = false
+        @listeners.each { |listener| accepted = true if accept_connection(listener) }
+        break unless accepted
+      end
+    end
+
     # Accepts a connection from the given listener and dispatches it.
     #
     # For SSL listeners the TLS handshake is offloaded to the thread pool so
@@ -118,15 +168,14 @@ module Raptor
     # follow the HTTP/1.1 path.
     #
     # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
-    # @param reactor [Reactor] the reactor to dispatch connections to
-    # @return [void]
+    # @return [Boolean] true if a connection was accepted, false if the listener had nothing to dispatch
     #
-    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
-    def accept_connection(listener, reactor)
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
+    def accept_connection(listener)
       tcp_client = begin
         listener.is_a?(Binder::SslListener) ? listener.tcp_server.accept_nonblock : listener.accept_nonblock
       rescue IO::WaitReadable
-        return
+        return false
       end
 
       if tcp_client.is_a?(TCPSocket)
@@ -138,19 +187,20 @@ module Raptor
 
       if listener.is_a?(Binder::SslListener)
         @thread_pool << proc do
-          dispatch_ssl_connection(listener, tcp_client, remote_addr, reactor)
+          dispatch_ssl_connection(listener, tcp_client, remote_addr)
         end
-        return
+        return true
       end
 
-      @request.eager_accept(
+      @http1.eager_accept(
         tcp_client,
         tcp_client.object_id,
-        reactor,
+        @reactor,
         @thread_pool,
         remote_addr,
         HTTP_SCHEME
       )
+      true
     end
 
     # Performs the TLS handshake for an accepted SSL connection and dispatches
@@ -160,35 +210,34 @@ module Raptor
     # @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)
+    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
+    def dispatch_ssl_connection(listener, tcp_client, remote_addr)
       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
+        ssl_socket.write(@http2.initial_settings_frame) rescue nil
 
-        reactor.add(
+        @reactor.add(
           id: ssl_socket.object_id,
           socket: ssl_socket,
           remote_addr: remote_addr,
           url_scheme: HTTPS_SCHEME,
           protocol: :http2,
-          writer: Http2::Writer.new,
+          writer: @http2.create_writer,
           flow_control: Http2::FlowControl.new
         )
 
         return
       end
 
-      @request.eager_accept(
+      @http1.eager_accept(
         ssl_socket,
         ssl_socket.object_id,
-        reactor,
+        @reactor,
         @thread_pool,
         remote_addr,
         HTTPS_SCHEME
@@ -204,7 +253,7 @@ module Raptor
     #
     # @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]
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @first_data_timeout
 
       begin
         ssl_socket.accept_nonblock

data/lib/raptor/stats.rb

@@ -60,7 +60,7 @@ module Raptor
     # @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 }
+      @mmap[index * SLOT_SIZE, SLOT_SIZE] = data
     end
 
     # Returns stats for all worker slots.

data/lib/raptor/systemd.rb

@@ -0,0 +1,69 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "socket"
+
+module Raptor
+  # Integration with systemd's service notification protocol and
+  # socket-activation file descriptors.
+  #
+  module Systemd
+    LISTEN_FDS_START = 3
+
+    LISTEN_FDNAMES_ENV = "LISTEN_FDNAMES"
+    LISTEN_FDS_ENV = "LISTEN_FDS"
+    LISTEN_PID_ENV = "LISTEN_PID"
+    NOTIFY_SOCKET_ENV = "NOTIFY_SOCKET"
+
+    # Sends `message` to the systemd notification socket, returning true on
+    # success and false when the socket is unset or the send fails.
+    #
+    # @param message [String] notify protocol payload, e.g. "READY=1"
+    # @return [Boolean]
+    #
+    # @rbs (String message) -> bool
+    def self.notify(message)
+      socket_path = ENV[NOTIFY_SOCKET_ENV]
+      return false if socket_path.nil? || socket_path.empty?
+
+      address = if socket_path.start_with?("@")
+        Socket.pack_sockaddr_un("\0#{socket_path[1..]}")
+      else
+        Socket.pack_sockaddr_un(socket_path)
+      end
+
+      socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_DGRAM, 0)
+      socket.send(message, 0, address)
+      true
+    rescue SystemCallError, IOError
+      false
+    ensure
+      socket&.close
+    end
+
+    # Returns the file descriptors passed in via socket activation, or an
+    # empty array when systemd has not exported any.
+    #
+    # @return [Array<Integer>]
+    #
+    # @rbs () -> Array[Integer]
+    def self.listen_fds
+      return [] unless ENV[LISTEN_PID_ENV]&.to_i == Process.pid
+
+      count = ENV[LISTEN_FDS_ENV]&.to_i || 0
+      Array.new(count) { |index| LISTEN_FDS_START + index }
+    end
+
+    # Clears the socket-activation environment variables so children don't
+    # act on stale values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear_listen_env
+      ENV.delete(LISTEN_FDNAMES_ENV)
+      ENV.delete(LISTEN_FDS_ENV)
+      ENV.delete(LISTEN_PID_ENV)
+    end
+  end
+end

data/lib/raptor/version.rb

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

data/sig/generated/raptor/binder.rbs

@@ -51,10 +51,26 @@ module Raptor
       def members: () -> [ :tcp_server, :ssl_context ]
     end
 
-    @bind_uris: Array[String]
+    @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener]]
 
     @listeners: Array[TCPServer | UNIXServer | SslListener]
 
+    @inherited_fds: Hash[String, Array[Integer]]
+
+    @socket_backlog: Integer
+
+    @bind_uris: Array[String]
+
+    # Array of bind URIs.
+    #
+    # @return [Array<String>] the bind URIs
+    attr_reader bind_uris: untyped
+
+    # Kernel listen() queue depth for TCP/SSL listeners.
+    #
+    # @return [Integer] the socket backlog
+    attr_reader socket_backlog: untyped
+
     # Array of listening sockets.
     #
     # @return [Array<TCPServer, UNIXServer, SslListener>] the server sockets
@@ -64,17 +80,21 @@ module Raptor
     #
     # Parses the provided bind URIs and creates listening sockets for each one.
     # Supports tcp://, unix://, and ssl:// schemes. Localhost is expanded to
-    # all available loopback addresses (both IPv4 and IPv6).
+    # all available loopback addresses (both IPv4 and IPv6). When `inherited_fds`
+    # supplies file descriptors for a URI, the listener is reconstructed from
+    # those FDs instead of binding fresh.
     #
     # @param bind_uris [Array<String>] array of URI strings to bind to
+    # @param socket_backlog [Integer] kernel listen() queue depth for TCP/SSL listeners
+    # @param inherited_fds [Hash{String => Array<Integer>}] inherited listener FDs keyed by bind URI
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI has an unsupported scheme
     #
     # @example
     #   binder = Binder.new(["tcp://0.0.0.0:3000", "unix:///tmp/raptor.sock"])
     #
-    # @rbs (Array[String] bind_uris) -> void
-    def initialize: (Array[String] bind_uris) -> void
+    # @rbs (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
+    def initialize: (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
 
     # Returns the bound addresses as strings.
     #
@@ -106,9 +126,27 @@ module Raptor
     # @rbs () -> void
     def close: () -> void
 
+    # Returns the file descriptors of every listener, grouped by the bind URI
+    # they were created from. The result is the payload to hand to a successor
+    # process via the `inherited_fds:` constructor argument.
+    #
+    # @return [Hash{String => Array<Integer>}]
+    #
+    # @rbs () -> Hash[String, Array[Integer]]
+    def inheritable_fds: () -> Hash[String, Array[Integer]]
+
+    # Clears the close-on-exec flag on every listener so the file descriptors
+    # survive `Kernel.exec`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def clear_close_on_exec: () -> void
+
     private
 
-    # Parses bind URIs and creates listening sockets.
+    # Parses bind URIs and creates listening sockets, reusing inherited file
+    # descriptors for URIs supplied in `@inherited_fds`.
     #
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI scheme is not supported
@@ -116,6 +154,26 @@ module Raptor
     # @rbs () -> void
     def parse: () -> void
 
+    # Creates fresh listeners for the given bind URI.
+    #
+    # @param bind_uri [String] the URI to bind
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @raise [UnknownBindSchemeError] if the URI scheme is not supported
+    #
+    # @rbs (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
+    def create_listeners: (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
+
+    # Reconstructs listeners for the given bind URI from inherited file
+    # descriptors.
+    #
+    # @param bind_uri [String] the URI the FDs were bound to
+    # @param filenos [Array<Integer>] file descriptors to wrap
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @raise [UnknownBindSchemeError] if the URI scheme is not supported
+    #
+    # @rbs (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    def restore_listeners: (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+
     # Creates TCP server sockets for the given host and port.
     #
     # @param host [String, nil] hostname or IP address to bind to
@@ -138,6 +196,16 @@ module Raptor
     # @rbs (String path) -> Array[UNIXServer]
     def create_unix_listeners: (String path) -> Array[UNIXServer]
 
+    # Registers an `at_exit` hook that removes the Unix socket file on the
+    # owning master's clean exit. Each call records the current process so
+    # forked workers won't delete a socket their master still owns.
+    #
+    # @param path [String] filesystem path of the Unix socket
+    # @return [void]
+    #
+    # @rbs (String path) -> void
+    def register_unix_socket_cleanup: (String path) -> void
+
     # Creates SSL server sockets for the given host, port, and SSL parameters.
     #
     # Wraps each TCP listener with an SSL context to produce SslListener objects.
@@ -152,6 +220,15 @@ module Raptor
     # @rbs (String? host, Integer? port, Hash[String, String] ssl_params) -> Array[SslListener]
     def create_ssl_listeners: (String? host, Integer? port, Hash[String, String] ssl_params) -> Array[SslListener]
 
+    # Builds a frozen `OpenSSL::SSL::SSLContext` configured for HTTP/2 and
+    # HTTP/1.1 ALPN negotiation.
+    #
+    # @param ssl_params [Hash<String, String>] SSL options ("cert" and "key" paths)
+    # @return [OpenSSL::SSL::SSLContext]
+    #
+    # @rbs (Hash[String, String] ssl_params) -> OpenSSL::SSL::SSLContext
+    def build_ssl_context: (Hash[String, String] ssl_params) -> OpenSSL::SSL::SSLContext
+
     # Returns all available loopback IP addresses.
     #
     # @return [Array<String>] unique loopback addresses (IPv4 and IPv6)

data/sig/generated/raptor/cli.rbs

@@ -18,6 +18,8 @@ module Raptor
   class CLI
     DEFAULT_WORKER_COUNT: untyped
 
+    NESTED_OPTION_KEYS: untyped
+
     DEFAULT_OPTIONS: untyped
 
     DEFAULT_CONFIG_PATHS: untyped
@@ -103,9 +105,6 @@ module Raptor
 
     # Loads a config file and merges it into `@options` over the defaults.
     #
-    # Top-level keys replace defaults; the nested `:client` hash is merged
-    # key-by-key so a config file does not need to restate every client option.
-    #
     # @param path [String, nil] path to the config file, or nil to no-op
     # @return [void]
     #