raptor 0.12.0 → 0.13.0

data/lib/raptor/http2.rb

@@ -12,16 +12,9 @@ require_relative "raptor_http2"
 module Raptor
   # Handles HTTP/2 request processing and Rack application integration.
   #
-  # Http2 manages the HTTP/2 protocol lifecycle including frame processing,
-  # HPACK header compression, stream management, and response writing.
-  # It integrates with the same reactor, ractor pool, and thread pool
-  # pipeline used by HTTP/1.1 connections.
-  #
   class Http2
-    # Lock-free per-connection frame writer.
-    #
-    # Serializes concurrent socket writes from multiple stream workers
-    # without blocking any of them.
+    # Serialises concurrent frame writes on a single HTTP/2 connection so
+    # exactly one thread is writing at any moment.
     #
     class Writer
       IDLE = :idle
@@ -49,7 +42,7 @@ module Raptor
       #
       # @rbs (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
       def write_frames(socket, frames)
-        return if frames.nil? || frames.empty?
+        return if !frames || frames.empty?
 
         claimed = false
         @state.swap do |current|
@@ -80,14 +73,8 @@ module Raptor
       end
     end
 
-    # Per-connection outbound flow-control accounting.
-    #
     # Tracks the peer's connection-level and per-stream receive windows so
-    # outbound DATA frames respect RFC 7540 section 5.2. Threads dispatching stream
-    # responses call `acquire` to reserve send capacity; threads applying
-    # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
-    # replenish it. The connection window and per-stream windows live in
-    # separate `Atom`s so the common fast path skips per-stream tracking.
+    # outbound `DATA` frames respect RFC 7540 section 5.2.
     #
     class FlowControl
       ACQUIRE_POLL_INTERVAL = 0.001
@@ -98,6 +85,8 @@ module Raptor
 
       # Creates a new FlowControl with the spec-default windows.
       #
+      # @return [void]
+      #
       # @rbs () -> void
       def initialize
         @connection_window = Atom.new(DEFAULT_WINDOW_SIZE)
@@ -109,12 +98,6 @@ module Raptor
       # least one byte is available on both the connection and stream
       # windows. The returned size is capped at `MAX_FRAME_SIZE`.
       #
-      # When `end_stream` is true, `max_bytes` fits within the peer's
-      # initial stream window, and no per-stream override has been
-      # recorded, only the connection window is consulted. The stream
-      # closes on this frame, so its remaining send window will not be
-      # consulted again and need not be tracked.
-      #
       # @param stream_id [Integer] the HTTP/2 stream identifier
       # @param max_bytes [Integer] the largest size the caller would like to send
       # @param end_stream [Boolean] true when this is the final frame on the stream
@@ -127,11 +110,7 @@ module Raptor
 
         if end_stream && capped <= initial && !@stream_windows.value.key?(stream_id)
           loop do
-            granted = 0
-            @connection_window.swap do |window|
-              granted = window > capped ? capped : window
-              granted > 0 ? window - granted : window
-            end
+            granted = reserve_connection(capped)
             return granted if granted > 0
 
             sleep ACQUIRE_POLL_INTERVAL
@@ -141,14 +120,7 @@ module Raptor
         loop do
           stream_window = @stream_windows.value[stream_id] || initial
           capped_full = capped < stream_window ? capped : stream_window
-
-          granted = 0
-          if capped_full > 0
-            @connection_window.swap do |window|
-              granted = window > capped_full ? capped_full : window
-              granted > 0 ? window - granted : window
-            end
-          end
+          granted = capped_full > 0 ? reserve_connection(capped_full) : 0
 
           if granted > 0
             @stream_windows.swap do |windows|
@@ -162,8 +134,7 @@ module Raptor
         end
       end
 
-      # Increments the connection-level send window. Called when the peer
-      # sends a WINDOW_UPDATE on stream 0.
+      # Increments the connection-level send window by `increment` bytes.
       #
       # @param increment [Integer] the byte count to add
       # @return [void]
@@ -173,8 +144,7 @@ module Raptor
         @connection_window.swap { |window| window + increment }
       end
 
-      # Increments the per-stream send window. Called when the peer sends
-      # a WINDOW_UPDATE on a specific stream.
+      # Increments the send window for the given stream by `increment` bytes.
       #
       # @param stream_id [Integer] the HTTP/2 stream identifier
       # @param increment [Integer] the byte count to add
@@ -207,9 +177,7 @@ module Raptor
         end
       end
 
-      # Discards any per-stream tracking for the given stream. Called
-      # after a stream closes so `@stream_windows` does not grow without
-      # bound across the lifetime of a connection.
+      # Discards any per-stream tracking for the given stream.
       #
       # @param stream_id [Integer] the HTTP/2 stream identifier
       # @return [void]
@@ -226,6 +194,25 @@ module Raptor
           pruned
         end
       end
+
+      private
+
+      # Reserves up to `capped` bytes from the connection window,
+      # returning the number of bytes granted (0 when the window is
+      # exhausted).
+      #
+      # @param capped [Integer] the largest reservation the caller will accept
+      # @return [Integer]
+      #
+      # @rbs (Integer capped) -> Integer
+      def reserve_connection(capped)
+        granted = 0
+        @connection_window.swap do |window|
+          granted = window > capped ? capped : window
+          granted > 0 ? window - granted : window
+        end
+        granted
+      end
     end
 
     EAGER_READ_TIMEOUT = 0.001
@@ -287,9 +274,10 @@ module Raptor
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
     # @rbs @initial_settings_frame: String
 
-    # The initial server SETTINGS frame sent on every new HTTP/2 connection.
+    # Returns the initial server SETTINGS frame to send on every new
+    # HTTP/2 connection.
     #
-    # @return [String] the encoded SETTINGS frame
+    # @return [String]
     attr_reader :initial_settings_frame
 
     # Creates a new Http2 handler.
@@ -329,11 +317,9 @@ module Raptor
       Writer.new(write_timeout: @write_timeout)
     end
 
-    # Processes HTTP/2 frames from the connection buffer.
-    #
-    # Parses frames, handles HPACK decoding, tracks stream state, and returns
+    # Advances HTTP/2 frame parsing from the connection buffer, returning
     # updated connection state along with any outgoing protocol frames and
-    # completed stream requests. Ractor-safe.
+    # completed stream requests.
     #
     # @param data [Hash] the connection state including buffer and HPACK table
     # @return [Hash] updated state with outgoing_frames and completed_requests
@@ -414,7 +400,7 @@ module Raptor
           end
 
         when :continuation
-          if pending_headers.nil? || frame[:stream_id] != pending_headers[:stream_id]
+          if !pending_headers || frame[:stream_id] != pending_headers[:stream_id]
             goaway_error = ERROR_PROTOCOL_ERROR
             break
           end
@@ -566,12 +552,10 @@ module Raptor
     end
     private_class_method :build_result
 
-    # Handles a parsed HTTP/2 request from the ractor pool.
-    #
-    # Writes outgoing protocol frames to the socket, updates reactor state,
-    # and dispatches completed stream requests to the thread pool. Eagerly
-    # consumes subsequent frame batches that are already buffered, skipping
-    # the reactor and ractor pool hops while the connection is hot.
+    # Handles a parsed HTTP/2 result. Writes outgoing frames, dispatches
+    # completed stream requests to the thread pool, and eagerly consumes
+    # further buffered frame batches before returning control to the
+    # reactor.
     #
     # @param result [Hash] the parsed result from the ractor pool
     # @param reactor [Reactor] the reactor managing the connection
@@ -706,10 +690,8 @@ module Raptor
       flow_control.discard_stream(stream_id) if flow_control
     end
 
-    # Writes a Rack response as HTTP/2 frames to the socket.
-    #
-    # DATA frames are partitioned through `flow_control` so each write fits
-    # within the peer's per-stream and connection windows.
+    # Writes a Rack response as HTTP/2 frames to the socket, partitioning
+    # DATA frames through `flow_control` to fit within the peer's windows.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
     # @param writer [Writer] lock-free frame writer for the connection
@@ -805,9 +787,6 @@ module Raptor
 
     # Builds a Rack environment hash from HTTP/2 headers and body.
     #
-    # Translates HTTP/2 pseudo-headers into Rack-compatible environment keys
-    # and populates all required Rack env entries.
-    #
     # @param headers [Array<Array(String, String)>] HTTP/2 header pairs
     # @param body [String] the request body
     # @param remote_addr [String] the client IP address

data/lib/raptor/reactor.rb

@@ -5,25 +5,10 @@ require "nio"
 require "red-black-tree"
 
 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
@@ -33,7 +18,7 @@ module Raptor
       # @rbs attr_accessor timeout_at: Float
       attr_accessor :timeout_at
 
-      # Semantic alias for the inherited `data` slot.
+      # Returns the client connection state.
       #
       # @return [Hash] the client connection state
       #
@@ -112,11 +97,8 @@ module Raptor
       @id_to_flow_control = {}
     end
 
-    # 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
     #
@@ -185,10 +167,8 @@ module Raptor
       read_and_queue_for_parse(socket, state)
     end
 
-    # 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
@@ -220,11 +200,8 @@ module Raptor
       end
     end
 
-    # 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
@@ -253,9 +230,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
     #
@@ -265,8 +239,7 @@ module Raptor
     end
 
     # 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
@@ -276,9 +249,8 @@ module Raptor
       @id_to_writer[id]
     end
 
-    # 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
@@ -288,10 +260,8 @@ module Raptor
       @id_to_flow_control[id]
     end
 
-    # 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]
@@ -308,9 +278,8 @@ module Raptor
       socket.close
     end
 
-    # 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]
@@ -386,8 +355,8 @@ module Raptor
       read_and_queue_for_parse(socket, state)
     end
 
-    # 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
@@ -431,7 +400,7 @@ module Raptor
       socket.close
     end
 
-    # 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/lib/raptor/reuseport_bpf.rb

@@ -23,8 +23,8 @@ module Raptor
     LIBBPF_LOADED = !!defined?(LibBPFRuby)
     BPF_OBJECT_PATH = File.expand_path("../../ext/raptor_bpf/reuseport_select.bpf.o", __dir__)
 
-    # 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]
     #
@@ -65,9 +65,6 @@ module Raptor
     #
     # @rbs (Array[String] bind_uris, Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
     def self.create_worker_listeners(bind_uris, worker_index, socket_backlog)
-      @load_key = [worker_index + 1].pack("L")
-      @load_value = String.new("\x00\x00\x00\x00", encoding: Encoding::ASCII_8BIT)
-
       bind_uris.filter_map do |bind_uri|
         uri = URI(bind_uri)
         next unless uri.scheme == "tcp"
@@ -92,6 +89,18 @@ module Raptor
       end
     end
 
+    # 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(worker_index)
+      @load_key = [worker_index + 1].pack("L")
+      @load_value = String.new("\x00\x00\x00\x00", encoding: Encoding::ASCII_8BIT)
+    end
+
     # Publishes this worker's current backlog to the BPF map.
     #
     # @param backlog [Integer] the worker's current reactor backlog

data/lib/raptor/server.rb

@@ -8,26 +8,10 @@ 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
-  # 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 = "http"
@@ -80,11 +64,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
@@ -148,7 +127,7 @@ module Raptor
 
         while @running.true?
           ReuseportBPF.update_load(@reactor.backlog)
-          sleep 0.01
+          sleep 0.001
         end
       end
     end
@@ -167,13 +146,8 @@ module Raptor
       end
     end
 
-    # 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
@@ -210,9 +184,9 @@ module Raptor
       true
     end
 
-    # 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/lib/raptor/stats.rb

@@ -4,12 +4,8 @@
 require "mmap-ruby"
 
 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
@@ -31,8 +27,7 @@ module Raptor
     # @rbs @num_workers: Integer
     # @rbs @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]

data/lib/raptor/systemd.rb

@@ -24,7 +24,7 @@ module Raptor
     # @rbs (String message) -> bool
     def self.notify(message)
       socket_path = ENV[NOTIFY_SOCKET_ENV]
-      return false if socket_path.nil? || socket_path.empty?
+      return false if !socket_path || socket_path.empty?
 
       address = if socket_path.start_with?("@")
         Socket.pack_sockaddr_un("\0#{socket_path[1..]}")

data/lib/raptor/version.rb

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