raptor 0.22.0 → 0.22.2

data/lib/raptor/reactor.rb

@@ -6,12 +6,15 @@ require "openssl"
 require "red-black-tree"
 require "timeout"
 
-require "atomic-ruby/atomic_queue"
 require "atomic-ruby/atom"
+require "atomic-ruby/atomic_boolean"
 require "atomic-ruby/atomic_condition_variable"
-require "atomic-ruby/atomic_count_down_latch"
+require "atomic-ruby/atomic_queue"
 
 require_relative "detached_body"
+require_relative "http1"
+require_relative "http2"
+require_relative "log"
 
 module Raptor
   # Multiplexes client connections, manages connection deadlines, feeds
@@ -82,6 +85,10 @@ module Raptor
       # @rbs attr_reader output: Array[String]
       attr_reader :output
 
+      # Creates empty connection I/O state for reactor-owned writes.
+      #
+      # @return [void]
+      #
       # @rbs () -> void
       def initialize
         @output = []
@@ -93,6 +100,10 @@ module Raptor
         @timeout = nil
       end
 
+      # Returns whether the connection has no output waiting to be written.
+      #
+      # @return [Boolean]
+      #
       # @rbs () -> bool
       def empty?
         output.empty?
@@ -117,6 +128,12 @@ module Raptor
       # @rbs attr_reader state: Hash[Symbol, untyped]
       attr_reader :state
 
+      # Creates I/O state for an HTTP/1.x detached response.
+      #
+      # @param body [DetachedBody] the response body
+      # @param state [Hash] connection state restored after the response finishes
+      # @return [void]
+      #
       # @rbs (DetachedBody body, Hash[Symbol, untyped] state) -> void
       def initialize(body, state)
         super()
@@ -128,6 +145,10 @@ module Raptor
         @finishing = false
       end
 
+      # Returns whether the connection has no output or detached body remaining.
+      #
+      # @return [Boolean]
+      #
       # @rbs () -> bool
       def empty?
         super && !body
@@ -149,6 +170,10 @@ module Raptor
       # @rbs attr_reader budget: DetachedBody::Budget
       attr_reader :budget
 
+      # Creates empty I/O state for an HTTP/2 connection and its detached streams.
+      #
+      # @return [void]
+      #
       # @rbs () -> void
       def initialize
         super
@@ -158,6 +183,10 @@ module Raptor
         @budget = DetachedBody::Budget.new(DETACHED_CONNECTION_BUFFER_SIZE)
       end
 
+      # Returns whether the connection has no output or detached streams remaining.
+      #
+      # @return [Boolean]
+      #
       # @rbs () -> bool
       def empty?
         super && detached.empty?
@@ -166,8 +195,7 @@ module Raptor
 
     CHUNK_SIZE = 64 * 1024
     DETACHED_CONNECTION_BUFFER_SIZE = 1024 * 1024
-    DETACHED_MAX_CHUNKS = 8
-    DETACHED_MAX_FRAMES = 8
+    DETACHED_WRITE_BATCH = 8
     DETACHED_WORKER_BUFFER_SIZE = 16 * 1024 * 1024
     TIMEOUT_RESPONSE = "HTTP/1.1 408 Request Timeout\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
 
@@ -183,6 +211,7 @@ module Raptor
     # @rbs @selector: NIO::Selector
     # @rbs @queue: Queue[TCPSocket]
     # @rbs @io_queue: AtomicQueue
+    # @rbs @io_applied: AtomicConditionVariable
     # @rbs @timeouts: RedBlackTree[TimeoutClient]
     # @rbs @id_to_socket: Hash[Integer, TCPSocket]
     # @rbs @socket_to_state: Hash[TCPSocket, Hash[Symbol, untyped]]
@@ -206,6 +235,7 @@ module Raptor
     # @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
+    # @option connection_options [Integer] :write_timeout timeout for non-blocking writes
     # @param http1_options [Hash] HTTP/1.1-specific configuration
     # @option http1_options [Integer] :persistent_data_timeout timeout for keep-alive idle connections
     # @param http2_options [Hash] HTTP/2-specific configuration
@@ -228,6 +258,7 @@ module Raptor
       @selector = NIO::Selector.new
       @queue = Queue.new
       @io_queue = AtomicQueue.new
+      @io_applied = AtomicConditionVariable.new
       @timeouts = RedBlackTree.new
 
       @id_to_socket = {}
@@ -409,12 +440,19 @@ module Raptor
 
     # Attaches a detached response body to an HTTP/1.x connection.
     #
+    # @param socket [TCPSocket] the client socket
+    # @param id [Integer] unique client identifier
+    # @param body [DetachedBody] the response body
+    # @param state [Hash] connection state restored once the response finishes
+    # @param finished [Proc] called with the close reason
+    # @return [Boolean] whether the body was attached
+    #
     # @rbs (TCPSocket socket, Integer id, DetachedBody body, Hash[Symbol, untyped] state, ^(Symbol) -> void finished) -> bool
     def attach_http1_body(socket, id, body, state, finished)
-      attached = AtomicCountDownLatch.new(1)
+      attached = AtomicBoolean.new(false)
       @io_queue << [:attach_http1, id, socket, body, attached, finished, state]
       @selector.wakeup rescue nil
-      attached.wait
+      @io_applied.wait { attached.true? }
       return false if body.closed?
 
       body.open
@@ -484,12 +522,18 @@ module Raptor
 
     # Attaches a detached response body to an HTTP/2 stream.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param body [DetachedBody] the response body
+    # @param finished [Proc] called with the close reason
+    # @return [Boolean] whether the body was attached
+    #
     # @rbs (Integer id, Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
     def attach_http2_body(id, stream_id, body, finished)
-      attached = AtomicCountDownLatch.new(1)
+      attached = AtomicBoolean.new(false)
       @io_queue << [:attach_http2, id, stream_id, body, attached, finished]
       @selector.wakeup rescue nil
-      attached.wait
+      @io_applied.wait { attached.true? }
       return false if body.closed?
 
       body.open
@@ -501,6 +545,9 @@ module Raptor
 
     # Reconsiders detached streams after an outbound window update.
     #
+    # @param id [Integer] unique connection identifier
+    # @return [void]
+    #
     # @rbs (Integer id) -> void
     def resume_http2_bodies(id)
       return if @detached_count.value.zero?
@@ -511,6 +558,10 @@ module Raptor
 
     # Cancels a detached response stream.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @return [void]
+    #
     # @rbs (Integer id, Integer stream_id) -> void
     def cancel_http2_body(id, stream_id)
       return if @detached_count.value.zero?
@@ -522,12 +573,15 @@ module Raptor
     # Waits for detached responses to finish, then cancels any that outlive
     # the worker drain period.
     #
+    # @param timeout [Numeric] seconds to wait before cancelling open bodies
+    # @return [void]
+    #
     # @rbs (Numeric timeout) -> void
     def drain_detached_bodies(timeout)
-      barrier = AtomicCountDownLatch.new(1)
+      barrier = AtomicBoolean.new(false)
       @io_queue << [:barrier, nil, barrier]
       @selector.wakeup rescue nil
-      barrier.wait
+      @io_applied.wait { barrier.true? }
 
       Timeout.timeout(timeout) do
         @detached_drained.wait { @detached_count.value.zero? }
@@ -560,7 +614,7 @@ module Raptor
       @id_to_io[id] = Http2IO.new
       writer.attach(self, id)
       if @http2_keepalive_interval.positive?
-        @id_to_http2_keepalive[id] = {frame: ping_frame, payload: ping_payload}
+        @id_to_http2_keepalive[id] = { frame: ping_frame, payload: ping_payload }
       end
     end
 
@@ -696,14 +750,16 @@ module Raptor
           begin
             attach_http2_detached_body(id, value, body, finished)
           ensure
-            attached.count_down
+            attached.make_true
+            @io_applied.broadcast
           end
           connections[id] = true
         when :attach_http1
           begin
             attach_http1_detached_body(value, id, body, state, finished)
           ensure
-            attached.count_down
+            attached.make_true
+            @io_applied.broadcast
           end
         when :ready_http1
           flush_http1_detached_body(id)
@@ -720,7 +776,8 @@ module Raptor
         when :cancel_all
           cancel_detached_bodies
         when :barrier
-          value.count_down
+          value.make_true
+          @io_applied.broadcast
         end
       end
 
@@ -733,6 +790,13 @@ module Raptor
 
     # Adds a detached body to an HTTP/1.x connection.
     #
+    # @param socket [TCPSocket] the client socket
+    # @param id [Integer] unique client identifier
+    # @param body [DetachedBody] the response body
+    # @param state [Hash] connection state restored once the response finishes
+    # @param finished [Proc] called with the close reason
+    # @return [void]
+    #
     # @rbs (TCPSocket socket, Integer id, DetachedBody body, Hash[Symbol, untyped] state, ^(Symbol) -> void finished) -> void
     def attach_http1_detached_body(socket, id, body, state, finished)
       io = Http1IO.new(body, state)
@@ -747,7 +811,7 @@ module Raptor
       end
 
       @id_to_socket[id] = socket
-      @socket_to_state[socket] = {id: id, protocol: :http1, detached: true}
+      @socket_to_state[socket] = { id: id, protocol: :http1, detached: true }
       @id_to_io[id] = io
       @detached_count.swap { |count| count + 1 }
       update_monitor(id, io)
@@ -755,12 +819,15 @@ module Raptor
 
     # Writes buffered HTTP/1.x body chunks without blocking.
     #
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
     # @rbs (Integer id) -> void
     def flush_http1_detached_body(id)
       io = @id_to_io[id]
       return unless io.is_a?(Http1IO) && !io.wait && io.output.empty?
 
-      DETACHED_MAX_CHUNKS.times do
+      DETACHED_WRITE_BATCH.times do
         size = io.body&.next_size
         break unless size
 
@@ -785,6 +852,10 @@ module Raptor
 
     # Finishes an HTTP/1.x detached response and either reuses or closes its connection.
     #
+    # @param id [Integer] unique client identifier
+    # @param io [Http1IO] connection I/O state
+    # @return [void]
+    #
     # @rbs (Integer id, Http1IO io) -> void
     def finish_http1_detached_body(id, io)
       socket = @id_to_socket[id]
@@ -804,7 +875,7 @@ module Raptor
           request_count: io.state[:request_count],
           remote_addr: io.state[:remote_addr],
           url_scheme: io.state[:url_scheme],
-          persisted: true,
+          persisted: true
         }
         unless io.input.empty?
           state[:buffer] = io.input
@@ -823,6 +894,10 @@ module Raptor
 
     # Cancels an HTTP/1.x detached response and closes its connection.
     #
+    # @param id [Integer] unique client identifier
+    # @param reason [Symbol] why the response closed
+    # @return [void]
+    #
     # @rbs (Integer id, Symbol reason) -> void
     def remove_http1_detached_body(id, reason)
       io = @id_to_io[id]
@@ -837,6 +912,12 @@ module Raptor
 
     # Adds a detached body to an HTTP/2 stream.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param body [DetachedBody] the response body
+    # @param finished [Proc] called with the close reason
+    # @return [void]
+    #
     # @rbs (Integer id, Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> void
     def attach_http2_detached_body(id, stream_id, body, finished)
       io = @id_to_io[id]
@@ -859,6 +940,10 @@ module Raptor
 
     # Marks an HTTP/2 detached stream eligible for fair scheduling.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @return [void]
+    #
     # @rbs (Integer id, Integer stream_id) -> void
     def mark_http2_detached_body_ready(id, stream_id)
       io = @id_to_io[id]
@@ -870,6 +955,9 @@ module Raptor
 
     # Marks every HTTP/2 detached stream eligible after flow-control capacity changes.
     #
+    # @param id [Integer] unique connection identifier
+    # @return [void]
+    #
     # @rbs (Integer id) -> void
     def resume_http2_detached_bodies(id)
       io = @id_to_io[id]
@@ -880,6 +968,9 @@ module Raptor
 
     # Writes HTTP/2 detached streams in round-robin order without waiting for flow control.
     #
+    # @param id [Integer] unique connection identifier
+    # @return [void]
+    #
     # @rbs (Integer id) -> void
     def flush_http2_detached_bodies(id)
       io = @id_to_io[id]
@@ -887,7 +978,7 @@ module Raptor
       socket = @id_to_socket[id]
       return unless io && flow_control && socket
 
-      DETACHED_MAX_FRAMES.times do
+      DETACHED_WRITE_BATCH.times do
         break if io.wait || !io.output.empty?
 
         stream_id = io.ready.shift
@@ -925,6 +1016,11 @@ module Raptor
 
     # Finishes an HTTP/2 detached stream with DATA or trailing HEADERS.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param body [DetachedBody] the response body
+    # @return [void]
+    #
     # @rbs (Integer id, Integer stream_id, DetachedBody body) -> void
     def finish_http2_detached_body(id, stream_id, body)
       parser = Http2Parser.new
@@ -942,6 +1038,11 @@ module Raptor
 
     # Removes an HTTP/2 detached stream and schedules its close callback.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param reason [Symbol] why the stream closed
+    # @return [void]
+    #
     # @rbs (Integer id, Integer stream_id, Symbol reason) -> void
     def remove_http2_detached_body(id, stream_id, reason)
       io = @id_to_io[id]
@@ -955,6 +1056,8 @@ module Raptor
 
     # Cancels every detached response during worker shutdown.
     #
+    # @return [void]
+    #
     # @rbs () -> void
     def cancel_detached_bodies
       @id_to_io.to_a.each do |id, io|
@@ -970,6 +1073,8 @@ module Raptor
 
     # Records one detached stream finishing.
     #
+    # @return [void]
+    #
     # @rbs () -> void
     def detached_body_removed
       remaining = nil
@@ -1127,7 +1232,7 @@ module Raptor
     # @rbs (Integer id, ConnectionIO io) -> void
     def track_write_timeout(id, io)
       clear_write_timeout(io)
-      client = TimeoutClient.new({id: id, write: true})
+      client = TimeoutClient.new({ id: id, write: true })
       client.timeout_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @write_timeout
       @timeouts << client
       io.timeout = client
@@ -1281,6 +1386,10 @@ module Raptor
 
     # Handles readiness for an HTTP/1.x detached response.
     #
+    # @param monitor [NIO::Monitor] ready selector monitor
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
     # @rbs (NIO::Monitor monitor, Integer id) -> void
     def handle_http1_detached_monitor(monitor, id)
       socket = monitor.value

data/lib/raptor/thread_locals.rb

@@ -9,12 +9,14 @@ module Raptor
     PRESERVED_KEYS = [
       :raptor_http_parser,
       :raptor_read_buffer,
-      :raptor_response_buffer,
+      :raptor_response_buffer
     ].freeze
 
     # Returns a reusable value stored on the current thread.
     #
-    # @return [Object]
+    # @param key [Symbol] thread-variable key used to cache the value
+    # @yieldreturn [Object] value to store when the key is unset
+    # @return [Object] the existing or newly stored value
     #
     # @rbs (Symbol key) { () -> untyped } -> untyped
     def self.fetch(key)

data/lib/raptor/version.rb

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

data/sig/generated/raptor/control_server.rbs

@@ -3,20 +3,18 @@
 module Raptor
   # Serves cluster statistics over a Unix socket.
   class ControlServer
+    SHUTDOWN: ::Symbol
+
     @path: String
 
     @stats: ^() -> Hash[Symbol, untyped]
 
     @server: UNIXServer?
 
-    @client: UNIXSocket?
+    @client: Atom
 
     @thread: Thread?
 
-    @running: bool
-
-    @mutex: Mutex
-
     # Creates a control server for `url` without binding it.
     #
     # @param url [String] `unix://` URL to listen on
@@ -50,12 +48,26 @@ module Raptor
 
     private
 
+    # Removes a stale socket while refusing to replace an active server.
+    #
+    # @return [void]
+    # @raise [RuntimeError] if another server is listening on the socket
+    #
     # @rbs () -> void
     def remove_stale_socket: () -> void
 
+    # Accepts and handles control requests until shutdown begins.
+    #
+    # @return [void]
+    #
     # @rbs () -> void
     def serve: () -> void
 
+    # Writes the response for one control-socket request.
+    #
+    # @param client [UNIXSocket] connected control client
+    # @return [void]
+    #
     # @rbs (UNIXSocket client) -> void
     def handle: (UNIXSocket client) -> void
   end

data/sig/generated/raptor/detached_body.rbs

@@ -12,12 +12,27 @@ module Raptor
 
       @size: Atom
 
+      # Creates a shared budget with the given byte limit.
+      #
+      # @param max_size [Integer] maximum bytes that may be reserved
+      # @return [void]
+      #
       # @rbs (Integer max_size) -> void
       def initialize: (Integer max_size) -> void
 
+      # Reserves bytes when they fit within the shared limit.
+      #
+      # @param bytes [Integer] number of bytes to reserve
+      # @return [Boolean] whether the bytes were reserved
+      #
       # @rbs (Integer bytes) -> bool
       def reserve: (Integer bytes) -> bool
 
+      # Releases bytes previously charged to the shared limit.
+      #
+      # @param bytes [Integer] number of bytes to release
+      # @return [void]
+      #
       # @rbs (Integer bytes) -> void
       def release: (Integer bytes) -> void
     end
@@ -46,7 +61,8 @@ module Raptor
     # @rbs (?max_buffer_size: Integer) -> void
     def initialize: (?max_buffer_size: Integer) -> void
 
-    # Registers a callback for when the server accepts the response stream.
+    # Registers a callback that runs on the request thread once the server
+    # accepts the response stream.
     #
     # @yieldparam stream [DetachedBody] the opened response stream
     # @return [DetachedBody]
@@ -87,40 +103,68 @@ module Raptor
 
     # Connects the body to its reactor-owned response stream.
     #
+    # @param budgets [Array<Budget>] buffer budgets shared with other bodies
+    # @param wake [Proc] called when buffered data or a close is ready to write
+    # @param dispatch [Proc] schedules application callbacks off the reactor thread
+    # @param finished [Proc] called with the close reason after `on_close`
+    # @return [Boolean] false when the bytes already buffered exceed a budget
+    #
     # @rbs (Array[Budget] budgets, ^() -> void wake, ^(Proc) -> void dispatch, ^(Symbol) -> void finished) -> bool
     def attach: (Array[Budget] budgets, ^() -> void wake, ^(Proc) -> void dispatch, ^(Symbol) -> void finished) -> bool
 
     # Notifies the application that its response stream is ready.
     #
+    # @return [void]
+    #
     # @rbs () -> void
     def open: () -> void
 
     # Returns the size of the next buffered chunk, 0 when closing, or nil
     # while waiting for more data.
     #
+    # @return [Integer, nil]
+    #
     # @rbs () -> Integer?
     def next_size: () -> Integer?
 
     # Removes up to `max_bytes` from the next buffered chunk.
     #
+    # @param max_bytes [Integer] the largest chunk to return
+    # @return [String, nil] the removed bytes, or nil when nothing is buffered
+    #
     # @rbs (Integer max_bytes) -> String?
     def shift: (Integer max_bytes) -> String?
 
     # Returns the response trailers supplied when the body closed.
     #
+    # @return [Hash] trailing response headers
+    #
     # @rbs () -> Hash[String, String | Array[String]]
     def trailers: () -> Hash[String, String | Array[String]]
 
     # Closes the stream and invokes its callback exactly once.
     #
+    # @param reason [Symbol] why the stream closed
+    # @return [void]
+    #
     # @rbs (Symbol reason) -> void
     def finish: (Symbol reason) -> void
 
     private
 
+    # Reserves bytes from every budget attached to this body.
+    #
+    # @param bytes [Integer] number of bytes to reserve
+    # @return [Boolean] whether every budget accepted the reservation
+    #
     # @rbs (Integer bytes) -> bool
     def reserve: (Integer bytes) -> bool
 
+    # Releases bytes from every budget attached to this body.
+    #
+    # @param bytes [Integer] number of bytes to release
+    # @return [void]
+    #
     # @rbs (Integer bytes) -> void
     def release: (Integer bytes) -> void
   end

data/sig/generated/raptor/http.rbs

@@ -26,6 +26,14 @@ module Raptor
       def message: () -> String
     end
 
+    # Returns whether an HTTP status forbids an entity body.
+    #
+    # @param status [Integer] the response status code
+    # @return [Boolean]
+    #
+    # @rbs (Integer status) -> bool
+    def self.no_entity_body_status?: (Integer status) -> bool
+
     # Writes `string` in full, retrying on partial writes. Bounded by
     # `timeout` so a slow client can't pin the writing thread.
     #

data/sig/generated/raptor/http1.rbs

@@ -80,11 +80,17 @@ module Raptor
 
     # Encodes one HTTP/1.1 response chunk.
     #
+    # @param chunk [String] response body bytes
+    # @return [String] the encoded chunk
+    #
     # @rbs (String chunk) -> String
     def self.encode_chunk: (String chunk) -> String
 
     # Encodes the final HTTP/1.1 response chunk and its trailers.
     #
+    # @param trailers [Hash] trailing response headers
+    # @return [String] the final chunk followed by the trailer section
+    #
     # @rbs (Hash[String, String | Array[String]] trailers) -> String
     def self.encode_trailers: (Hash[String, String | Array[String]] trailers) -> String
 
@@ -307,6 +313,17 @@ module Raptor
 
     # Calls the Rack app and writes its response for one request.
     #
+    # @param socket [TCPSocket] the client socket
+    # @param id [Integer] unique client identifier
+    # @param env [Hash] partial env hash from the HTTP parser
+    # @param parse_data [Hash] metadata from the parsing pass
+    # @param body [String, nil] decoded request body
+    # @param reactor [Reactor] the reactor managing the client connection
+    # @param request_count [Integer] number of requests handled on this connection
+    # @param remote_addr [String] client IP address
+    # @param url_scheme [String] "http" or "https"
+    # @return [Boolean] true if the connection should be kept alive
+    #
     # @rbs (TCPSocket socket, Integer id, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, Reactor reactor, Integer request_count, String remote_addr, String url_scheme) -> bool
     def perform_request: (TCPSocket socket, Integer id, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, Reactor reactor, Integer request_count, String remote_addr, String url_scheme) -> bool
 
@@ -434,6 +451,13 @@ module Raptor
     # Starts a detached response, chunked on HTTP/1.1 and ended by closing
     # the connection on HTTP/1.0.
     #
+    # @param socket [TCPSocket] the client socket to write to
+    # @param status [Integer] HTTP status code
+    # @param headers [Hash] response headers from the Rack application
+    # @param chunked [Boolean] whether to use chunked transfer encoding
+    # @param keep_alive [Boolean] whether to send a keep-alive connection header
+    # @return [void]
+    #
     # @rbs (TCPSocket socket, Integer status, Hash[String, String | Array[String]] headers, chunked: bool, keep_alive: bool) -> void
     def write_detached_response: (TCPSocket socket, Integer status, Hash[String, String | Array[String]] headers, chunked: bool, keep_alive: bool) -> void