raptor 0.7.0 → 0.9.0

data/sig/generated/raptor/reactor.rbs

@@ -10,10 +10,12 @@ module Raptor
   # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
-  #     first_data_timeout: 30,
-  #     chunk_data_timeout: 10
-  #   })
+  #   reactor = Reactor.new(
+  #     ractor_pool,
+  #     thread_pool,
+  #     connection_options: { first_data_timeout: 30, chunk_data_timeout: 10 },
+  #     http1_options: { persistent_data_timeout: 65 }
+  #   )
   #   reactor.run
   #   reactor.add(id: client.object_id, socket: client)
   #   # ... later
@@ -71,7 +73,11 @@ module Raptor
 
     @selector: NIO::Selector
 
-    @client_options: Hash[Symbol, Integer]
+    @persistent_data_timeout: Integer
+
+    @chunk_data_timeout: Integer
+
+    @first_data_timeout: Integer
 
     @ractor_pool: untyped
 
@@ -81,14 +87,15 @@ module Raptor
     #
     # @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
+    # @param connection_options [Hash] per-connection timeout configuration
+    # @option connection_options [Integer] :first_data_timeout timeout for initial data
+    # @option connection_options [Integer] :chunk_data_timeout timeout for subsequent chunks
+    # @param http1_options [Hash] HTTP/1.1-specific configuration
+    # @option http1_options [Integer] :persistent_data_timeout timeout for keep-alive idle connections
     # @return [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
+    # @rbs (untyped ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> void
+    def initialize: (untyped ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> void
 
     # Starts the reactor's main event loop in a new thread.
     #

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

@@ -14,9 +14,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,14 +36,22 @@ module Raptor
 
     @running: AtomicBoolean
 
-    @client_options: Hash[Symbol, untyped]
+    @bpf_active: bool
 
-    @request: Request
+    @drain_accept_queue: bool
+
+    @first_data_timeout: Integer
+
+    @http2: Http2
+
+    @http1: Http1
 
     @thread_pool: AtomicThreadPool
 
     @reactor: Reactor
 
+    @listeners: Array[TCPServer | UNIXServer | Binder::SslListener]
+
     @binder: Binder
 
     # Creates a new Server instance.
@@ -50,19 +59,23 @@ 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 binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> 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
     #
@@ -71,8 +84,9 @@ module Raptor
 
     # 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]
     #
@@ -81,6 +95,22 @@ 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.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def drain_accept_queue: () -> void
+
     # Accepts a connection from the given listener and dispatches it.
     #
     # For SSL listeners the TLS handshake is offloaded to the thread pool so
@@ -90,11 +120,10 @@ 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: (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
+    def accept_connection: (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
 
     # 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
@@ -103,11 +132,10 @@ 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: (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
+    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
+    def dispatch_ssl_connection: (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
 
     # Drives a non-blocking SSL handshake to completion, bounded by the
     # configured first-data timeout. Returns true on success, false on

data/sig/generated/raptor/systemd.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/raptor/systemd.rb with RBS::Inline
+
+module Raptor
+  # Integration with systemd's service notification protocol and
+  # socket-activation file descriptors.
+  module Systemd
+    LISTEN_FDS_START: ::Integer
+
+    LISTEN_FDNAMES_ENV: ::String
+
+    LISTEN_FDS_ENV: ::String
+
+    LISTEN_PID_ENV: ::String
+
+    NOTIFY_SOCKET_ENV: ::String
+
+    # 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: (String message) -> bool
+
+    # 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: () -> Array[Integer]
+
+    # Clears the socket-activation environment variables so children don't
+    # act on stale values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear_listen_env: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.7.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,45 +114,58 @@ 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
 - lib/raptor/cli.rb
 - lib/raptor/cluster.rb
+- lib/raptor/http.rb
+- lib/raptor/http1.rb
 - lib/raptor/http2.rb
 - lib/raptor/log.rb
 - lib/raptor/reactor.rb
-- lib/raptor/request.rb
+- lib/raptor/reuseport_bpf.rb
 - lib/raptor/server.rb
 - lib/raptor/stats.rb
+- lib/raptor/systemd.rb
 - lib/raptor/version.rb
 - sig/generated/rackup/handler/raptor.rbs
 - sig/generated/raptor.rbs
 - sig/generated/raptor/binder.rbs
 - sig/generated/raptor/cli.rbs
 - sig/generated/raptor/cluster.rbs
+- sig/generated/raptor/http.rbs
+- sig/generated/raptor/http1.rbs
 - sig/generated/raptor/http2.rbs
 - sig/generated/raptor/log.rbs
 - sig/generated/raptor/reactor.rbs
-- sig/generated/raptor/request.rbs
+- sig/generated/raptor/reuseport_bpf.rbs
 - sig/generated/raptor/server.rbs
 - sig/generated/raptor/stats.rbs
+- sig/generated/raptor/systemd.rbs
 - sig/generated/raptor/version.rbs
 homepage: https://github.com/joshuay03/raptor
 licenses: