raptor 0.12.0 → 0.13.0

data/sig/generated/raptor/reactor.rbs

@@ -1,25 +1,10 @@
 # Generated from lib/raptor/reactor.rb with RBS::Inline
 
 module Raptor
-  # High-performance I/O reactor for managing client connections and timeouts.
-  #
-  # Reactor uses NIO selectors for efficient I/O multiplexing and implements
-  # client timeouts using a red-black tree for O(log n) timeout management.
-  # It coordinates between ractor pools for CPU-intensive HTTP parsing and
-  # thread pools for blocking operations, and provides backlog metrics that
-  # the server uses for backpressure control to prevent overload.
-  #
-  # @example
-  #   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
-  #   reactor.shutdown
+  # Multiplexes client connections and closes them when they overrun
+  # their per-phase timeouts (first data, subsequent chunks, and
+  # keep-alive idle). Feeds ready bytes to the parser pipeline and hands
+  # completed requests back to the caller-provided handlers.
   class Reactor
     # A client connection node ordered by absolute expiry time so the
     # soonest-to-expire is always at the tree's minimum.
@@ -27,7 +12,7 @@ module Raptor
       # @rbs attr_accessor timeout_at: Float
       attr_accessor timeout_at: untyped
 
-      # Semantic alias for the inherited `data` slot.
+      # Returns the client connection state.
       #
       # @return [Hash] the client connection state
       #
@@ -97,11 +82,8 @@ module Raptor
     # @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.
-    #
-    # The event loop handles I/O events, processes timeouts, manages
-    # the registration queue, and controls server connection acceptance.
-    # It continues until the queue is closed and emptied.
+    # Starts the reactor's main event loop in a new thread. Runs until
+    # the registration queue is closed and drained.
     #
     # @return [Thread] the thread running the reactor event loop
     #
@@ -118,10 +100,8 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def add: (Hash[Symbol, untyped] state) -> void
 
-    # Updates the state of an existing client connection.
-    #
-    # Called when an incomplete HTTP request needs to be
-    # re-registered with the reactor for further processing.
+    # Updates the state of an existing client connection and re-registers
+    # it for further I/O.
     #
     # @param state [Hash] updated client connection state
     # @option state [Integer] :id client identifier
@@ -140,11 +120,8 @@ module Raptor
     # @rbs (Integer id) -> TCPSocket?
     def remove: (Integer id) -> TCPSocket?
 
-    # Re-registers a kept-alive connection for the next request cycle.
-    #
-    # Called after successfully writing a response when keep-alive is active.
-    # Resets the connection state and re-queues the socket in the selector
-    # using the persistent data timeout.
+    # Re-registers a kept-alive connection for the next request cycle
+    # under the persistent-data timeout.
     #
     # @param socket [TCPSocket] the kept-alive client socket
     # @param id [Integer] the unique client identifier
@@ -158,9 +135,6 @@ module Raptor
 
     # Returns the socket for a given client identifier without removing it.
     #
-    # Used by HTTP/2 connections where the socket remains registered across
-    # multiple stream requests.
-    #
     # @param id [Integer] unique client identifier
     # @return [TCPSocket, nil] the socket, if found
     #
@@ -168,8 +142,7 @@ module Raptor
     def socket_for: (Integer id) -> TCPSocket?
 
     # Returns the writer object associated with a given connection, if one
-    # was supplied when the connection was added. Used by protocol handlers
-    # that need to coordinate concurrent socket writes.
+    # was supplied when the connection was added.
     #
     # @param id [Integer] unique client identifier
     # @return [Object, nil] the writer, if found
@@ -177,9 +150,8 @@ module Raptor
     # @rbs (Integer id) -> untyped?
     def writer_for: (Integer id) -> untyped?
 
-    # Returns the flow controller associated with a given connection, if one
-    # was supplied when the connection was added. Used by HTTP/2 stream
-    # dispatchers to honour the peer's flow-control windows.
+    # Returns the flow controller associated with a given connection, if
+    # one was supplied when the connection was added.
     #
     # @param id [Integer] unique client identifier
     # @return [Object, nil] the flow controller, if found
@@ -187,10 +159,8 @@ module Raptor
     # @rbs (Integer id) -> untyped?
     def flow_control_for: (Integer id) -> untyped?
 
-    # Updates connection state for an HTTP/2 connection after frame processing.
-    #
-    # Re-registers the socket with the selector for further reads and stores
-    # the updated HPACK table and stream states.
+    # Updates connection state for an HTTP/2 connection and re-registers
+    # the socket for further reads.
     #
     # @param state [Hash] updated connection state from the ractor pool
     # @return [void]
@@ -198,9 +168,8 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def update_http2_state: (Hash[Symbol, untyped] state) -> void
 
-    # Closes the socket for the given connection and drops all reactor state
-    # associated with it. Used to terminate HTTP/2 connections after sending
-    # a GOAWAY frame.
+    # Closes the socket for the given connection and drops all reactor
+    # state associated with it.
     #
     # @param id [Integer] unique client identifier
     # @return [void]
@@ -242,8 +211,8 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def wakeup!: (TCPSocket socket) -> void
 
-    # Reads data from a socket and either queues it for parsing,
-    # or for selector registration.
+    # Reads data from a socket and either queues it for parsing or
+    # returns it to the selector.
     #
     # @param socket [TCPSocket] the socket to read from and queue
     # @param state [Hash] current connection state
@@ -260,7 +229,7 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def cleanup: (TCPSocket socket) -> void
 
-    # Checks if a request is complete i.e., processable.
+    # Returns true when the request has been fully parsed.
     #
     # @param state [Hash] connection state
     # @return [Boolean] true if the request is complete

data/sig/generated/raptor/reuseport_bpf.rbs

@@ -14,8 +14,8 @@ module Raptor
 
     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.
+    # Returns true when the preconditions for BPF-directed reuseport are
+    # met on this platform.
     #
     # @return [Boolean]
     #
@@ -45,6 +45,15 @@ module Raptor
     # @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]
 
+    # Prepares this worker's load-reporting slot so subsequent
+    # {update_load} calls can publish its backlog.
+    #
+    # @param worker_index [Integer] slot index for this worker
+    # @return [void]
+    #
+    # @rbs (Integer worker_index) -> void
+    def self.enable_load_reporting: (Integer worker_index) -> void
+
     # Publishes this worker's current backlog to the BPF map.
     #
     # @param backlog [Integer] the worker's current reactor backlog

data/sig/generated/raptor/server.rbs

@@ -1,26 +1,10 @@
 # Generated from lib/raptor/server.rb with RBS::Inline
 
 module Raptor
-  # Accepts client connections and dispatches them into the request
-  # pipeline. Skips acceptance when the reactor backlog is high so an
-  # overloaded process leaves connections for peers that can absorb
-  # them (via shared `SO_REUSEPORT` listeners).
-  #
-  # Supports TCP, Unix, and SSL listeners. SSL handshakes are offloaded
-  # to the thread pool so a slow client can't pin the server thread.
-  # For HTTP/1.1 the first request is parsed inline and dispatched
-  # straight to the thread pool; HTTP/2 (negotiated via ALPN) is
-  # registered with the reactor for frame processing.
-  #
-  # @example
-  #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   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
+  # Accepts client connections on TCP, Unix, and SSL listeners and
+  # dispatches them into the request pipeline. Backs off from accepting
+  # when the reactor backlog is high so an overloaded process leaves
+  # connections for peers to absorb.
   class Server
     HTTP_SCHEME: ::String
 
@@ -72,11 +56,6 @@ module Raptor
 
     # Starts the server's main accept loop in a new thread.
     #
-    # The accept loop polls listening sockets for ready connections and accepts
-    # 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
@@ -117,13 +96,8 @@ module Raptor
     # @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
-    # a slow client cannot block the server thread. For SSL connections with
-    # h2 negotiated via ALPN, the server sends initial SETTINGS and adds the
-    # connection to the reactor as an HTTP/2 connection. All other connections
-    # follow the HTTP/1.1 path.
+    # Accepts a connection from the given listener and dispatches it into
+    # the HTTP/1.1 or SSL/HTTP-2 pipeline.
     #
     # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
     # @return [Boolean] true if a connection was accepted, false if the listener had nothing to dispatch
@@ -131,9 +105,9 @@ module Raptor
     # @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
-    # `:first_data_timeout` so a slow client cannot pin a worker thread.
+    # Performs the TLS handshake for an accepted SSL connection, bounded
+    # by `:first_data_timeout`, and dispatches it through the HTTP/2 or
+    # HTTP/1.1 path.
     #
     # @param listener [Binder::SslListener] the SSL listener that accepted the connection
     # @param tcp_client [TCPSocket] the accepted TCP socket

data/sig/generated/raptor/stats.rbs

@@ -1,12 +1,8 @@
 # Generated from lib/raptor/stats.rb with RBS::Inline
 
 module Raptor
-  # Shared memory store for per-worker process statistics.
-  #
-  # Stats uses an anonymous mmap (MAP_ANON | MAP_SHARED) created before
-  # forking so that worker processes can write their stats and the master
-  # process can read them without any pipes or signals. Each worker is
-  # assigned a fixed-size slot in the shared region.
+  # Shared-memory store for per-worker process statistics. Each worker
+  # holds a fixed-size slot in an anonymous mmap region.
   #
   # Binary layout per slot (native byte order):
   #   pid               uint32    4 bytes
@@ -29,8 +25,7 @@ module Raptor
 
     @mmap: untyped
 
-    # Allocates the shared mmap region. Must be called before forking
-    # workers so the mapping is inherited by every child process.
+    # Allocates the shared mmap region for `num_workers` slots.
     #
     # @param num_workers [Integer] number of worker slots to allocate
     # @return [void]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Joshua Young