raptor 0.22.3 → 0.24.0

data/sig/generated/raptor/reuseport_bpf.rbs

@@ -6,14 +6,41 @@ module Raptor
   #
   # 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.
+  # `SO_REUSEPORT` when either is missing, or when there are more workers
+  # or listeners than the BPF maps have slots for. 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
 
+    TCP_INFO_UNACKED_OFFSET: ::Integer
+
+    UNAVAILABLE_LOAD: ::Integer
+
+    MAX_WORKERS: ::Integer
+
+    MAX_LISTENERS: ::Integer
+
+    self.@accepted_load_value: String
+
+    self.@load_value: String
+
+    self.@load_key: String
+
+    self.@worker_listeners: Array[TCPServer]
+
+    self.@shared_listeners: Array[TCPServer]
+
+    self.@loads_fd: Integer?
+
+    self.@socks_fd: Integer
+
+    self.@program_fd: Integer
+
+    self.@object: untyped
+
     # Returns true when the preconditions for BPF-directed reuseport are
     # met on this platform.
     #
@@ -22,28 +49,30 @@ module Raptor
     # @rbs () -> bool
     def self.supported?: () -> bool
 
-    # Prepares BPF-directed routing for `worker_count` workers.
+    # Prepares BPF-directed routing for `worker_count` workers across the
+    # addresses `shared_listeners` are bound to.
     #
     # Returns true when BPF-directed dispatch is active. Returns false
-    # when the platform is unsupported. Raises when the kernel refuses
-    # the program.
+    # when the platform is unsupported or the counts exceed the map slots.
+    # Raises when the kernel refuses the program.
     #
     # @param worker_count [Integer] number of worker processes that will bind sockets
+    # @param shared_listeners [Array<TCPServer>] the binder's tcp listeners
     # @return [Boolean]
     #
-    # @rbs (Integer worker_count) -> bool
-    def self.setup: (Integer worker_count) -> bool
+    # @rbs (Integer worker_count, Array[TCPServer] shared_listeners) -> bool
+    def self.setup: (Integer worker_count, Array[TCPServer] shared_listeners) -> bool
 
-    # Returns tcp listening sockets bound and registered for `worker_index`.
-    # Skips non-tcp bind URIs.
+    # Creates this worker's BPF-routed listeners at the shared listeners'
+    # bound addresses, including resolved `localhost` addresses and ports
+    # assigned by the kernel for port 0.
     #
-    # @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]
+    # @rbs (Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+    def self.create_worker_listeners: (Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
 
     # Prepares this worker's load-reporting slot so subsequent
     # {update_load} calls can publish its backlog.
@@ -54,7 +83,7 @@ module Raptor
     # @rbs (Integer worker_index) -> void
     def self.enable_load_reporting: (Integer worker_index) -> void
 
-    # Publishes this worker's current backlog to the BPF map.
+    # Publishes this worker's load to the BPF map.
     #
     # @param backlog [Integer] the worker's current reactor backlog
     # @return [void]
@@ -62,7 +91,7 @@ module Raptor
     # @rbs (Integer backlog) -> void
     def self.update_load: (Integer backlog) -> void
 
-    # Publishes an accept-side backlog estimate. This uses a separate value
+    # Publishes an accept-side load estimate. This uses a separate value
     # buffer because the server and load reporter call into the map from
     # different threads.
     #
@@ -72,13 +101,21 @@ module Raptor
     # @rbs (Integer backlog) -> void
     def self.update_accepted_load: (Integer backlog) -> void
 
-    # Marks a worker's slot as unavailable by parking its load at the
-    # sentinel maximum so the BPF program's least-loaded pick skips it.
+    # Parks a worker's load at the maximum so BPF favors other workers.
+    # Stop publishing its load first to avoid overwriting the sentinel.
     #
     # @param worker_index [Integer] slot index for the worker to mark
     # @return [void]
     #
     # @rbs (Integer worker_index) -> void
     def self.mark_unavailable: (Integer worker_index) -> void
+
+    # Returns the number of connections waiting in this worker's accept
+    # queues, which the reactor backlog cannot see.
+    #
+    # @return [Integer]
+    #
+    # @rbs () -> Integer
+    def self.accept_queue_length: () -> Integer
   end
 end

data/sig/generated/raptor/server.rbs

@@ -1,10 +1,8 @@
 # Generated from lib/raptor/server.rb with RBS::Inline
 
 module Raptor
-  # Accepts client connections on TCP, Unix, and SSL listeners and
-  # dispatches them into the request pipeline. Yields between accepts
-  # when the thread pool queue exceeds the pool size so overloaded
-  # workers stay responsive to in-flight requests.
+  # Accepts client connections on TCP, Unix, SSL, and cleartext HTTP/2
+  # listeners and dispatches them into the request pipeline.
   class Server
     HTTP_SCHEME: ::String
 
@@ -20,10 +18,6 @@ module Raptor
 
     MIN_BACKPRESSURE_THRESHOLD: ::Integer
 
-    @binder: Binder
-
-    @listeners: Array[TCPServer | UNIXServer | Binder::SslListener]
-
     @reactor: Reactor
 
     @thread_pool: AtomicThreadPool
@@ -34,27 +28,33 @@ module Raptor
 
     @first_data_timeout: Integer
 
+    @listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener]
+
     @drain_accept_queue: bool
 
-    @bpf_active: bool
+    @worker_index: Integer?
 
     @running: AtomicBoolean
 
-    # Creates a new Server instance.
+    @thread: Thread?
+
+    @load_reporter: Thread?
+
+    # Creates a new Server.
     #
-    # @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 http1 [Http1] the HTTP/1.1 handler
-    # @param http2 [Http2] the HTTP/2 handler (provides the initial SETTINGS frame)
+    # @param http2 [Http2] the HTTP/2 handler
     # @param connection_options [Hash] per-connection timeout configuration, used to bound TLS handshakes
-    # @param listeners [Array] the per-worker listeners this server accepts on
+    # @option connection_options [Integer] :first_data_timeout timeout for completing the TLS handshake
+    # @param listeners [Array<TCPServer, UNIXServer, Binder::SslListener, Binder::H2cListener>] 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
+    # @param worker_index [Integer, nil] this worker's BPF slot index, or nil when BPF dispatch is inactive
     # @return [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
+    # @rbs (Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener], ?drain_accept_queue: bool, ?worker_index: Integer?) -> void
+    def initialize: (Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener], ?drain_accept_queue: bool, ?worker_index: Integer?) -> void
 
     # Starts the server's main accept loop in a new thread.
     #
@@ -82,13 +82,13 @@ module Raptor
 
     private
 
-    # Starts a background thread that publishes this worker's reactor
-    # backlog to the BPF map for load-aware dispatch.
+    # Starts a background thread that publishes this worker's load to the
+    # BPF map for load-aware dispatch.
     #
-    # @return [void]
+    # @return [Thread] the load reporter
     #
-    # @rbs () -> void
-    def spawn_load_reporter: () -> void
+    # @rbs () -> Thread
+    def spawn_load_reporter: () -> Thread
 
     # Dispatches every connection already in the kernel accept queue for each
     # listener until all are drained.
@@ -100,13 +100,13 @@ module Raptor
 
     # Accepts a connection from the given listener, immediately publishes
     # the pending work to the BPF map, and dispatches the socket into the
-    # HTTP/1.1 or SSL/HTTP-2 pipeline.
+    # SSL, cleartext HTTP/2, or HTTP/1.1 pipeline.
     #
-    # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
+    # @param listener [TCPServer, UNIXServer, Binder::SslListener, Binder::H2cListener] the ready listener
     # @return [Boolean] true if a connection was accepted, false if the listener had nothing to dispatch
     #
-    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
-    def accept_connection: (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener listener) -> bool
+    def accept_connection: (TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener listener) -> bool
 
     # Performs the TLS handshake for an accepted SSL connection, bounded
     # by `:first_data_timeout`, and dispatches it through the HTTP/2 or
@@ -114,7 +114,7 @@ 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 remote_addr [String] the client IP address
     # @return [void]
     #
     # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void

data/sig/generated/raptor/stats.rbs

@@ -25,7 +25,8 @@ module Raptor
 
     @mmap: untyped
 
-    # Allocates the shared mmap region for `num_workers` slots.
+    # Creates a new Stats and allocates the shared mmap region for
+    # `num_workers` slots.
     #
     # @param num_workers [Integer] number of worker slots to allocate
     # @return [void]
@@ -68,7 +69,7 @@ module Raptor
 
     # Reads stats for a worker slot from shared memory.
     #
-    # @param slot [Integer] slot offset to read from
+    # @param slot [Integer] slot index 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 slot) -> Hash[Symbol, untyped]

data/sig/generated/raptor/thread_locals.rbs

@@ -9,14 +9,15 @@ module Raptor
     # Returns a reusable value stored on the current thread.
     #
     # @param key [Symbol] thread-variable key used to cache the value
-    # @yieldreturn [Object] value to store when the key is unset
+    # @yield when the key is unset
+    # @yieldreturn [Object] the value to store
     # @return [Object] the existing or newly stored value
     #
     # @rbs (Symbol key) { () -> untyped } -> untyped
     def self.fetch: (Symbol key) { () -> untyped } -> untyped
 
-    # Clears application-owned true thread locals while retaining Raptor's
-    # reusable per-thread values.
+    # Clears application thread locals while retaining Raptor's reusable
+    # per-thread values.
     #
     # @return [void]
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.22.3
+  version: 0.24.0
 platform: ruby
 authors:
 - Joshua Young
@@ -141,8 +141,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/brisrails-talk.md
+- docs/assets/profile_picture.png
+- docs/assets/startup_output.svg
 - docs/raptor-vs-puma.md
+- docs/talk.md
 - exe/raptor
 - ext/raptor_bpf/reuseport_select.bpf.c
 - ext/raptor_http/extconf.rb
@@ -163,6 +165,7 @@ files:
 - lib/raptor/http1.rb
 - lib/raptor/http2.rb
 - lib/raptor/log.rb
+- lib/raptor/plugin.rb
 - lib/raptor/reactor.rb
 - lib/raptor/reuseport_bpf.rb
 - lib/raptor/server.rb
@@ -181,6 +184,7 @@ files:
 - sig/generated/raptor/http1.rbs
 - sig/generated/raptor/http2.rbs
 - sig/generated/raptor/log.rbs
+- sig/generated/raptor/plugin.rbs
 - sig/generated/raptor/reactor.rbs
 - sig/generated/raptor/reuseport_bpf.rbs
 - sig/generated/raptor/server.rbs