raptor 0.8.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
@@ -22,7 +24,7 @@ module Raptor
   #   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 })
+  #   server = Server.new(binder, reactor, thread_pool, http1, http2, connection_options: { first_data_timeout: 30 }, listeners: binder.listeners)
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -36,15 +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 @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.
@@ -55,44 +59,52 @@ module Raptor
     # @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, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], ?drain_accept_queue: bool) -> void
-    def initialize(binder, reactor, thread_pool, http1, http2, connection_options:, drain_accept_queue: false)
+    # @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
       @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
+      spawn_load_reporter if @bpf_active
+
       Thread.new do
         Thread.current.name = "Server"
 
+        backpressure_threshold = [(@thread_pool.size * 1.2).ceil, MIN_BACKPRESSURE_THRESHOLD].max
+
         while @running.true?
           begin
-            ready_servers, _, _ = IO.select(@binder.listeners, 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 { |listener| accept_connection(listener) }
         end
@@ -111,11 +123,28 @@ module Raptor
     def shutdown
       @running.make_false
       drain_accept_queue if @drain_accept_queue
-      @binder.close
+      @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.
     #
@@ -125,7 +154,7 @@ module Raptor
     def drain_accept_queue
       loop do
         accepted = false
-        @binder.listeners.each { |listener| accepted = true if accept_connection(listener) }
+        @listeners.each { |listener| accepted = true if accept_connection(listener) }
         break unless accepted
       end
     end

data/lib/raptor/version.rb

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

data/sig/generated/raptor/binder.rbs

@@ -61,6 +61,16 @@ module Raptor
 
     @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

data/sig/generated/raptor/cluster.rbs

@@ -40,8 +40,6 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @http1_options: Hash[Symbol, untyped]
-
     @http2_options: Hash[Symbol, untyped]
 
     @worker_boot_timeout: Integer
@@ -92,6 +90,10 @@ module Raptor
 
     @hot_restart_requested: bool
 
+    @bpf_active: bool
+
+    @http1_options: Hash[Symbol, untyped]
+
     @connection_options: Hash[Symbol, untyped]
 
     @environment: String

data/sig/generated/raptor/http.rbs

@@ -36,6 +36,19 @@ module Raptor
     # @rbs (TCPSocket socket, String string, ?timeout: Integer) -> void
     def self.socket_write: (TCPSocket socket, String string, ?timeout: Integer) -> void
 
+    # Writes `strings` in full via a single `writev(2)` syscall when possible,
+    # falling back to per-string writes on partial results. Bounded by
+    # `timeout` so a slow client can't pin the writing thread.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param strings [Array<String>] the buffers to write in order
+    # @param timeout [Integer] seconds to wait for the socket to become writable on each retry
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
+    def self.socket_writev: (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
+
     # Writes a Common Log Format entry to `io`. Write failures are silently
     # ignored.
     #

data/sig/generated/raptor/http1.rbs

@@ -14,6 +14,8 @@ module Raptor
 
     READ_BUFFER_SIZE: untyped
 
+    RESPONSE_BUFFER_CAPACITY: untyped
+
     KEEPALIVE_READ_TIMEOUT: ::Float
 
     MAX_KEEPALIVE_REQUESTS: ::Integer
@@ -132,6 +134,17 @@ module Raptor
     # @rbs (TCPSocket socket, String string) -> void
     def socket_write: (TCPSocket socket, String string) -> void
 
+    # Instance-level wrapper around {Http.socket_writev} that applies the
+    # configured `write_timeout`.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param strings [Array<String>] the buffers to write in order
+    # @return [void]
+    # @raise [Http::WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, Array[String] strings) -> void
+    def socket_writev: (TCPSocket socket, Array[String] strings) -> void
+
     # Signals eager keep-alive loops to stop processing further requests on
     # their connections. In-flight requests complete normally.
     #
@@ -406,7 +419,8 @@ module Raptor
     # @rbs (Hash[String, String | Array[String]] headers, Integer status) -> void
     def validate_headers: (Hash[String, String | Array[String]] headers, Integer status) -> void
 
-    # Builds the HTTP status line string.
+    # Returns the HTTP status line for `status`. Callers must not retain the
+    # returned string across further calls on the same thread.
     #
     # @param http_version [String] "HTTP/1.1" or "HTTP/1.0"
     # @param status [Integer] HTTP status code
@@ -499,10 +513,7 @@ module Raptor
     # @rbs (TCPSocket socket, String response, Array[String] body_array, bool use_chunked) -> void
     def write_array_body: (TCPSocket socket, String response, Array[String] body_array, bool use_chunked) -> void
 
-    # Writes a single-element array body, optionally buffering it with the headers.
-    #
-    # Small bodies are concatenated with the headers into one write to reduce
-    # system call overhead.
+    # Writes a single-element array body to the socket.
     #
     # @param socket [TCPSocket] the client socket
     # @param response [String] headers already serialized, to be written before the body

data/sig/generated/raptor/reuseport_bpf.rbs

@@ -0,0 +1,56 @@
+# Generated from lib/raptor/reuseport_bpf.rb with RBS::Inline
+
+module Raptor
+  # Routes incoming connections across worker processes to the worker with
+  # the lowest reactor backlog.
+  #
+  # Auto-enabled on Linux when the `libbpf-ruby` gem is installed and the
+  # BPF object file has been compiled. Falls back silently to standard
+  # `SO_REUSEPORT` when either is missing. Raises when the kernel refuses
+  # the BPF program. Wraps `tcp://` bindings only; non-tcp bindings are
+  # left to the binder's shared listeners.
+  module ReuseportBPF
+    LIBBPF_LOADED: untyped
+
+    BPF_OBJECT_PATH: untyped
+
+    # Whether the preconditions for BPF-directed reuseport are met on this
+    # platform. Does not imply that the kernel will accept the program.
+    #
+    # @return [Boolean]
+    #
+    # @rbs () -> bool
+    def self.supported?: () -> bool
+
+    # Prepares BPF-directed routing for `worker_count` workers.
+    #
+    # Returns true when BPF-directed dispatch is active. Returns false
+    # when the platform is unsupported. Raises when the kernel refuses
+    # the program.
+    #
+    # @param worker_count [Integer] number of worker processes that will bind sockets
+    # @return [Boolean]
+    #
+    # @rbs (Integer worker_count) -> bool
+    def self.setup: (Integer worker_count) -> bool
+
+    # Returns tcp listening sockets bound and registered for `worker_index`.
+    # Skips non-tcp bind URIs.
+    #
+    # @param bind_uris [Array<String>] the configured bind URIs
+    # @param worker_index [Integer] slot index for this worker in the socks map
+    # @param socket_backlog [Integer] kernel listen() queue depth
+    # @return [Array<TCPServer>] the tcp listening sockets created for this worker
+    #
+    # @rbs (Array[String] bind_uris, Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+    def self.create_worker_listeners: (Array[String] bind_uris, Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+
+    # Publishes this worker's current backlog to the BPF map.
+    #
+    # @param backlog [Integer] the worker's current reactor backlog
+    # @return [void]
+    #
+    # @rbs (Integer backlog) -> void
+    def self.update_load: (Integer backlog) -> void
+  end
+end

data/sig/generated/raptor/server.rbs

@@ -17,7 +17,7 @@ module Raptor
   #   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 })
+  #   server = Server.new(binder, reactor, thread_pool, http1, http2, connection_options: { first_data_timeout: 30 }, listeners: binder.listeners)
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -36,6 +36,8 @@ module Raptor
 
     @running: AtomicBoolean
 
+    @bpf_active: bool
+
     @drain_accept_queue: bool
 
     @first_data_timeout: Integer
@@ -48,6 +50,8 @@ module Raptor
 
     @reactor: Reactor
 
+    @listeners: Array[TCPServer | UNIXServer | Binder::SslListener]
+
     @binder: Binder
 
     # Creates a new Server instance.
@@ -58,18 +62,20 @@ module Raptor
     # @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, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], ?drain_accept_queue: bool) -> void
-    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], ?drain_accept_queue: bool) -> void
+    # @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 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
 
     # 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
     #
@@ -89,6 +95,14 @@ module Raptor
 
     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: () -> void
+
     # Dispatches every connection already in the kernel accept queue for each
     # listener until all are drained.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Joshua Young
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: libbpf-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - djry1999@gmail.com
 executables:
@@ -100,22 +114,29 @@ executables:
 extensions:
 - ext/raptor_http/extconf.rb
 - ext/raptor_http2/extconf.rb
+- ext/raptor_native/extconf.rb
 extra_rdoc_files: []
 files:
 - ".buildkite/pipeline.yml"
+- ".dockerignore"
 - ".mise.toml"
 - Brewfile
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Dockerfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/raptor-vs-puma.md
 - exe/raptor
+- ext/raptor_bpf/reuseport_select.bpf.c
 - ext/raptor_http/extconf.rb
 - ext/raptor_http/raptor_http.c
 - ext/raptor_http2/extconf.rb
 - ext/raptor_http2/huffman_table.h
 - ext/raptor_http2/raptor_http2.c
+- ext/raptor_native/extconf.rb
+- ext/raptor_native/raptor_native.c
 - lib/rackup/handler/raptor.rb
 - lib/raptor.rb
 - lib/raptor/binder.rb
@@ -126,6 +147,7 @@ files:
 - lib/raptor/http2.rb
 - lib/raptor/log.rb
 - lib/raptor/reactor.rb
+- lib/raptor/reuseport_bpf.rb
 - lib/raptor/server.rb
 - lib/raptor/stats.rb
 - lib/raptor/systemd.rb
@@ -140,6 +162,7 @@ files:
 - sig/generated/raptor/http2.rbs
 - sig/generated/raptor/log.rbs
 - sig/generated/raptor/reactor.rbs
+- sig/generated/raptor/reuseport_bpf.rbs
 - sig/generated/raptor/server.rbs
 - sig/generated/raptor/stats.rbs
 - sig/generated/raptor/systemd.rbs