raptor 0.8.0 → 0.10.0

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

@@ -8,12 +8,16 @@ module Raptor
   class Http1
     BODY_BUFFER_THRESHOLD: untyped
 
+    CHUNKED_WRITE_THRESHOLD: untyped
+
     FILE_CHUNK_SIZE: untyped
 
     MAX_CHUNK_OVERHEAD: untyped
 
     READ_BUFFER_SIZE: untyped
 
+    RESPONSE_BUFFER_CAPACITY: untyped
+
     KEEPALIVE_READ_TIMEOUT: ::Float
 
     MAX_KEEPALIVE_REQUESTS: ::Integer
@@ -86,23 +90,27 @@ module Raptor
     # @rbs (String buffer, ?Integer? max_size) -> [String, Symbol]
     def self.decode_chunked: (String buffer, ?Integer? max_size) -> [ String, Symbol ]
 
-    @running: AtomicBoolean
+    @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
 
-    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    @server_port: Integer
 
-    @access_log_io: IO?
+    @server_port_string: String
 
-    @max_keepalive_requests: Integer
+    @write_timeout: Integer
+
+    @max_body_size: Integer?
 
     @body_spool_threshold: Integer?
 
-    @max_body_size: Integer?
+    @max_keepalive_requests: Integer
 
-    @write_timeout: Integer
+    @access_log_io: IO?
 
-    @server_port: Integer
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
-    @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
+    @running: AtomicBoolean
+
+    @env_template: Hash[String, untyped]
 
     # Creates a new Http1 handler.
     #
@@ -132,6 +140,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 +425,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 +519,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
@@ -565,6 +582,18 @@ module Raptor
     # @rbs (Hash[String, String | Array[String]] headers) -> String
     def format_headers: (Hash[String, String | Array[String]] headers) -> String
 
+    # Appends one or more `name: value` header lines to `result`. Newline-
+    # separated values are emitted as separate lines; empty values and values
+    # with illegal characters are skipped silently.
+    #
+    # @param result [String] the buffer to append to
+    # @param name [String] the header name
+    # @param value [Object] the header value (any object responding to `to_s`)
+    # @return [void]
+    #
+    # @rbs (String result, String name, untyped value) -> void
+    def append_header_value: (String result, String name, untyped value) -> void
+
     # Calls all rack.response_finished callbacks registered in the environment.
     #
     # Callbacks are called in reverse registration order. Individual callback

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.10.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