raptor 0.22.0 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc05eb1a4a916e5094c4496f18a3d3b179869a42efc1a7fd42ccda546b46e0bc
-  data.tar.gz: 1b975f682fcbaea183226775277cf441d4996899f4348237b96bf073586b1082
+  metadata.gz: bfbcd63c857341a9ad73f6d4d40d03dac757deb1074dde954dc966b9b268822b
+  data.tar.gz: 2d2d78611b34df0061f231c18d0c3c0e4bc13f8314b1e61bcfcb9ef7a215297d
 SHA512:
-  metadata.gz: c39ee7c2d2c4f68b8015a841c3fdadfb26b42f587041d6e85e69fc930abcb9fe65ce4841e3562c31b2ff6a0ac904787ba97ca1a26dafa25ba7a0f71b0069b2a1
-  data.tar.gz: 71604474925af588347c5e82f294eca27b5d51c3dc161ece9bb63508b9ea389196173cf890be8f8ebbd030dea284fc1e0d9f4aac26650f02c05303eb09707c7c
+  metadata.gz: 6898ded5b172745d15dd411bc6638686cccb07485ca03cf5b6857194e4b8d263e9b02da8fd24f287dd1a60d43a128f7cd2e5524a1e95122233023c58b18fb086
+  data.tar.gz: 18081bd442db06fc3d60b2686eda2bfb0b36118f6709b23ed88ac8ede2e0a03a39b4ac4bc3c8d95c7d3b50fff52ec071bc414e9041ba7ae9d747fbb450bc0cf6

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.22.1] - 2026-10-03
+
+- Stop waiting for more HTTP/2 frames on the collector thread
+- Run `DetachedBody#on_open` callbacks on the request thread
+- Attach detached response bodies without polling
+
 ## [0.22.0] - 2026-10-03
 
 - Add detached HTTP/1.1 response bodies

data/README.md

@@ -37,7 +37,7 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 > bundle exec raptor -w 10 -t 3 hello_world.ru
 [Raptor 72876|Main|Main] Cluster initializing:
-[Raptor 72876|Main|Main] ├─ Version: 0.22.0
+[Raptor 72876|Main|Main] ├─ Version: 0.22.1
 [Raptor 72876|Main|Main] ├─ Ruby Version: ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +YJIT +PRISM [arm64-darwin23]
 [Raptor 72876|Main|Main] ├─ Environment: development
 [Raptor 72876|Main|Main] ├─ Master PID: 72876
@@ -208,7 +208,7 @@ Set `control_url` to a Unix socket URL such as `unix:///tmp/raptor-control.sock`
 
 ## (Micro) Benchmarks
 
-Raptor 0.22.0 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
+Raptor 0.22.1 vs Puma 8.0.2 vs Falcon 0.57.0 across two workload profiles. **IO-bound** is a GET endpoint that
 interleaves 5-10 short sleeps (total 2.5-15ms) with small CPU work, simulating a read path that makes several DB or
 cache calls. **CPU-bound** is a POST endpoint that accepts a small JSON body, interleaves 3-5 chunks of JSON item
 building (total 450-1500 items) with sub-100µs sleeps, and returns the built array, simulating a write path that does
@@ -222,22 +222,22 @@ disabled, and both threaded servers allow 999 requests per HTTP/1.1 keep-alive c
 Each cell reports the median throughput and median p95 latency independently across 3 runs, so the two numbers in a row
 may come from different runs. Every run starts a fresh server process so the samples are independent of each other;
 state accumulated in a previous run cannot bias the next. Across the whole table, the widest spread
-((max - min) / 2 / median) between runs of a single cell was ±13.2% for throughput and ±25.6% for p95.
+((max - min) / 2 / median) between runs of a single cell was ±19.6% for throughput and ±13.6% for p95.
 
 | Protocol              | Workload | Raptor mode | Raptor req/s | Raptor p95 | Puma req/s  | Puma p95  | vs Puma req/s | vs Puma p95  | Falcon req/s | Falcon p95 | vs Falcon req/s | vs Falcon p95 |
 | --------------------- | -------- | ----------- | ------------ | ---------- | ----------- | --------- | ------------- | ------------ | ------------ | ---------- | --------------- | ------------- |
-| HTTP/1.1              | IO       | Fixed       | 2.91k req/s  | 82.40 ms   | 1.51k req/s | 125.20 ms | 92.2% higher  | 34.2% lower  | 12.08k req/s | 14.40 ms   | 75.9% lower     | 472.2% higher |
-| HTTP/1.1              | IO       | Scaling     | 7.01k req/s  | 31.70 ms   | 1.51k req/s | 125.20 ms | 362.9% higher | 74.7% lower  | 12.08k req/s | 14.40 ms   | 42.0% lower     | 120.1% higher |
-| HTTP/1.1              | CPU      | Fixed       | 7.24k req/s  | 37.90 ms   | 8.50k req/s | 23.10 ms  | 14.9% lower   | 64.1% higher | 6.44k req/s  | 28.90 ms   | 12.4% higher    | 31.1% higher  |
-| HTTP/1.1              | CPU      | Scaling     | 6.48k req/s  | 39.50 ms   | 8.50k req/s | 23.10 ms  | 23.8% lower   | 71.0% higher | 6.44k req/s  | 28.90 ms   | 0.6% higher     | 36.7% higher  |
-| HTTP/1.1 (keep-alive) | IO       | Fixed       | 2.26k req/s  | 67.20 ms   | 1.47k req/s | 105.60 ms | 53.7% higher  | 36.4% lower  | 6.22k req/s  | 28.20 ms   | 63.7% lower     | 138.3% higher |
-| HTTP/1.1 (keep-alive) | IO       | Scaling     | 8.20k req/s  | 21.80 ms   | 1.47k req/s | 105.60 ms | 458.3% higher | 79.4% lower  | 6.22k req/s  | 28.20 ms   | 32.0% higher    | 22.7% lower   |
-| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 7.21k req/s  | 27.10 ms   | 8.38k req/s | 23.60 ms  | 14.0% lower   | 14.8% higher | 6.87k req/s  | 34.20 ms   | 5.0% higher     | 20.8% lower   |
-| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 7.56k req/s  | 28.10 ms   | 8.38k req/s | 23.60 ms  | 9.8% lower    | 19.1% higher | 6.87k req/s  | 34.20 ms   | 10.1% higher    | 17.8% lower   |
-| HTTP/2                | IO       | Fixed       | 1.64k req/s  | 112.08 ms  | N/A         | N/A       | -             | -            | 6.34k req/s  | 28.16 ms   | 74.2% lower     | 298.1% higher |
-| HTTP/2                | IO       | Scaling     | 6.90k req/s  | 27.33 ms   | N/A         | N/A       | -             | -            | 6.34k req/s  | 28.16 ms   | 8.8% higher     | 2.9% lower    |
-| HTTP/2                | CPU      | Fixed       | 6.90k req/s  | 29.30 ms   | N/A         | N/A       | -             | -            | 6.69k req/s  | 65.77 ms   | 3.2% higher     | 55.4% lower   |
-| HTTP/2                | CPU      | Scaling     | 7.51k req/s  | 26.86 ms   | N/A         | N/A       | -             | -            | 6.69k req/s  | 65.77 ms   | 12.2% higher    | 59.2% lower   |
+| HTTP/1.1              | IO       | Fixed       | 2.95k req/s  | 80.20 ms   | 1.55k req/s | 122.60 ms | 90.1% higher  | 34.6% lower  | 12.24k req/s | 14.00 ms   | 75.9% lower     | 472.9% higher |
+| HTTP/1.1              | IO       | Scaling     | 7.05k req/s  | 30.40 ms   | 1.55k req/s | 122.60 ms | 354.1% higher | 75.2% lower  | 12.24k req/s | 14.00 ms   | 42.4% lower     | 117.1% higher |
+| HTTP/1.1              | CPU      | Fixed       | 7.29k req/s  | 35.00 ms   | 8.73k req/s | 20.30 ms  | 16.4% lower   | 72.4% higher | 6.71k req/s  | 26.80 ms   | 8.7% higher     | 30.6% higher  |
+| HTTP/1.1              | CPU      | Scaling     | 6.73k req/s  | 36.90 ms   | 8.73k req/s | 20.30 ms  | 22.8% lower   | 81.8% higher | 6.71k req/s  | 26.80 ms   | 0.4% higher     | 37.7% higher  |
+| HTTP/1.1 (keep-alive) | IO       | Fixed       | 2.52k req/s  | 70.70 ms   | 1.50k req/s | 102.60 ms | 67.8% higher  | 31.1% lower  | 6.23k req/s  | 28.20 ms   | 59.5% lower     | 150.7% higher |
+| HTTP/1.1 (keep-alive) | IO       | Scaling     | 8.19k req/s  | 21.90 ms   | 1.50k req/s | 102.60 ms | 445.8% higher | 78.7% lower  | 6.23k req/s  | 28.20 ms   | 31.6% higher    | 22.3% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Fixed       | 7.04k req/s  | 28.30 ms   | 8.62k req/s | 21.50 ms  | 18.3% lower   | 31.6% higher | 7.07k req/s  | 32.10 ms   | 0.4% lower      | 11.8% lower   |
+| HTTP/1.1 (keep-alive) | CPU      | Scaling     | 7.78k req/s  | 25.70 ms   | 8.62k req/s | 21.50 ms  | 9.8% lower    | 19.5% higher | 7.07k req/s  | 32.10 ms   | 9.9% higher     | 19.9% lower   |
+| HTTP/2                | IO       | Fixed       | 1.50k req/s  | 128.92 ms  | N/A         | N/A       | -             | -            | 6.57k req/s  | 27.29 ms   | 77.2% lower     | 372.4% higher |
+| HTTP/2                | IO       | Scaling     | 9.41k req/s  | 19.30 ms   | N/A         | N/A       | -             | -            | 6.57k req/s  | 27.29 ms   | 43.1% higher    | 29.3% lower   |
+| HTTP/2                | CPU      | Fixed       | 7.75k req/s  | 26.55 ms   | N/A         | N/A       | -             | -            | 7.24k req/s  | 49.42 ms   | 7.1% higher     | 46.3% lower   |
+| HTTP/2                | CPU      | Scaling     | 7.54k req/s  | 26.97 ms   | N/A         | N/A       | -             | -            | 7.24k req/s  | 49.42 ms   | 4.2% higher     | 45.4% lower   |
 
 > ruby 4.0.7 (2026-09-15 revision 229531a6cf) +YJIT +PRISM [aarch64-linux]
 > 10 worker processes; fixed Raptor and Puma run 3 threads per worker; scaling Raptor starts at 3 with no fixed limit;

data/docs/raptor-vs-puma.md

@@ -349,7 +349,7 @@ The `Writer` hands serialized frames to the reactor, which writes as the socket
 
 Flow control uses similar CAS-protected atoms. Ordinary Rack bodies wait for connection and stream capacity as they yield. A `Raptor::DetachedBody` instead returns its application thread immediately; the reactor schedules its bounded buffer as capacity becomes available and closes it when the client cancels. This keeps long-lived streams from consuming one application thread each.
 
-Frame processing also has an eager loop. After processing one batch of frames, the h2 handler tries to `read_nonblock` one more time to see if the next batch is already available. Up to eight rounds are consumed inline before handing back to the reactor, and the loop bails out early once the app thread pool has more queued work than worker slots so one busy connection cannot starve the collector. This is the same principle as the HTTP/1.1 eager keep-alive: amortise the reactor round-trip when the client is actively sending, but back off under saturation.
+Frame processing also has an eager loop. After processing one batch of frames, the h2 handler checks `wait_readable(0)` and reads the next batch only if it has already arrived. Up to eight rounds are consumed inline before handing back to the reactor, and the loop bails out early once the app thread pool has more queued work than worker slots so one busy connection cannot starve the collector. This is the same principle as the HTTP/1.1 eager keep-alive: amortise the reactor round-trip when the client is actively sending, but back off under saturation.
 
 During worker shutdown, Raptor stops accepting connections and sends GOAWAY with the last stream handed to the Rack application. Later streams are refused while application work and detached bodies drain. The reactor remains active so in-flight responses can receive flow-control updates; detached bodies still open when the drain period expires are cancelled before their connections close.
 

data/lib/raptor/cli.rb

@@ -1,10 +1,11 @@
 # rbs_inline: enabled
 # frozen_string_literal: true
 
-require "concurrent/utility/processor_counter"
 require "json"
 require "optparse"
 
+require "concurrent/utility/processor_counter"
+
 require_relative "cluster"
 
 module Raptor
@@ -46,18 +47,18 @@ module Raptor
         chunk_data_timeout: 10,
         write_timeout: 5,
         max_body_size: nil,
-        body_spool_threshold: 1024 * 1024,
+        body_spool_threshold: 1024 * 1024
       },
       http1: {
         ractors: nil,
         persistent_data_timeout: 65,
-        max_keepalive_requests: 1000,
+        max_keepalive_requests: 1000
       },
       http2: {
         ractors: nil,
         max_concurrent_streams: 100,
         keepalive_interval: 10,
-        keepalive_timeout: 5,
+        keepalive_timeout: 5
       },
       worker_boot_timeout: 60,
       worker_timeout: 60,

data/lib/raptor/cluster.rb

@@ -1,11 +1,11 @@
 # rbs_inline: enabled
 # frozen_string_literal: true
 
-require "concurrent/utility/processor_counter"
 require "json"
 require "time"
 
 require "atomic-ruby/atomic_thread_pool"
+require "concurrent/utility/processor_counter"
 require "rack/builder"
 require "ractor-pool"
 
@@ -339,8 +339,8 @@ module Raptor
             pool_capacity: [capacity - total_work, 0].max,
             busy_threads: active,
             max_threads: capacity,
-            requests_count: stat.fetch(:requests, 0),
-          },
+            requests_count: stat.fetch(:requests, 0)
+          }
         }
       end
 
@@ -350,7 +350,7 @@ module Raptor
         phase: @phase,
         booted_workers: worker_status.count { |worker| worker[:booted] },
         old_workers: worker_status.count { |worker| worker[:phase] != @phase },
-        worker_status: worker_status,
+        worker_status: worker_status
       }
     end
 

data/lib/raptor/control_server.rb

@@ -5,17 +5,19 @@ require "json"
 require "socket"
 require "uri"
 
+require "atomic-ruby/atom"
+
 module Raptor
   # Serves cluster statistics over a Unix socket.
   #
   class ControlServer
+    SHUTDOWN = :shutdown
+
     # @rbs @path: String
     # @rbs @stats: ^() -> Hash[Symbol, untyped]
     # @rbs @server: UNIXServer?
-    # @rbs @client: UNIXSocket?
+    # @rbs @client: Atom
     # @rbs @thread: Thread?
-    # @rbs @running: bool
-    # @rbs @mutex: Mutex
 
     # Creates a control server for `url` without binding it.
     #
@@ -32,10 +34,8 @@ module Raptor
       @path = uri.path
       @stats = stats
       @server = nil
-      @client = nil
+      @client = Atom.new(nil)
       @thread = nil
-      @running = false
-      @mutex = Mutex.new
     end
 
     # Binds the Unix socket.
@@ -54,7 +54,6 @@ module Raptor
     #
     # @rbs () -> void
     def start
-      @running = true
       owner_pid = Process.pid
       at_exit { File.delete(@path) rescue nil if Process.pid == owner_pid }
 
@@ -71,17 +70,24 @@ module Raptor
     #
     # @rbs () -> void
     def shutdown
-      @running = false
-      @mutex.synchronize do
-        @server&.close
-        @client&.close
+      client = nil
+      @client.swap do |current|
+        client = current
+        SHUTDOWN
       end
+      @server&.close
+      client.close if client.is_a?(UNIXSocket)
       @thread&.join
       File.delete(@path) rescue nil
     end
 
     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
       return unless File.exist?(@path)
@@ -94,21 +100,34 @@ module Raptor
       end
     end
 
+    # Accepts and handles control requests until shutdown begins.
+    #
+    # @return [void]
+    #
     # @rbs () -> void
     def serve
-      while @running
+      until @client.value == SHUTDOWN
         readable, = IO.select([@server], nil, nil, 1)
         next unless readable
 
-        @mutex.synchronize do
-          client = @server.accept_nonblock(exception: false)
-          @client = client if client.is_a?(UNIXSocket)
+        client = @server.accept_nonblock(exception: false)
+        next unless client.is_a?(UNIXSocket)
+
+        if @client.swap { |current| current == SHUTDOWN ? current : client } == SHUTDOWN
+          client.close
+          return
         end
-        handle(@client) if @client
+
+        handle(client)
       end
     rescue IOError, Errno::EBADF
     end
 
+    # Writes the response for one control-socket request.
+    #
+    # @param client [UNIXSocket] connected control client
+    # @return [void]
+    #
     # @rbs (UNIXSocket client) -> void
     def handle(client)
       request_line = client.gets
@@ -125,7 +144,7 @@ module Raptor
     rescue IOError, SystemCallError
     ensure
       client.close rescue nil
-      @mutex.synchronize { @client = nil }
+      @client.swap { |current| current.equal?(client) ? nil : current }
     end
   end
 end

data/lib/raptor/detached_body.rb

@@ -16,12 +16,22 @@ module Raptor
       # @rbs @max_size: Integer
       # @rbs @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(max_size)
         @max_size = max_size
         @size = Atom.new(0)
       end
 
+      # 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(bytes)
         reserved = false
@@ -32,6 +42,11 @@ module Raptor
         reserved
       end
 
+      # Releases bytes previously charged to the shared limit.
+      #
+      # @param bytes [Integer] number of bytes to release
+      # @return [void]
+      #
       # @rbs (Integer bytes) -> void
       def release(bytes)
         @size.swap { |size| size - bytes }
@@ -57,7 +72,7 @@ module Raptor
       raise ArgumentError, "max_buffer_size must be positive" unless max_buffer_size.positive?
 
       @max_buffer_size = max_buffer_size
-      @state = Atom.new({chunks: [], size: 0, closing: false, closed: false, notified: false, trailers: {}})
+      @state = Atom.new({ chunks: [], size: 0, closing: false, closed: false, notified: false, trailers: {} })
       @budgets = []
       @wake = proc {}
       @dispatch = proc { |callback| callback.call }
@@ -66,7 +81,8 @@ module Raptor
       @on_close = nil
     end
 
-    # 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]
@@ -169,6 +185,12 @@ 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(budgets, wake, dispatch, finished)
       @wake = wake
@@ -191,16 +213,19 @@ module Raptor
 
     # Notifies the application that its response stream is ready.
     #
+    # @return [void]
+    #
     # @rbs () -> void
     def open
-      callback = @on_open
-      @dispatch.call(proc { callback.call(self) }) if callback
+      @on_open&.call(self)
       @wake.call if @state.value[:notified]
     end
 
     # 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
       state = @state.value
@@ -209,6 +234,9 @@ module Raptor
 
     # 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(max_bytes)
       chunk = nil
@@ -236,6 +264,8 @@ module Raptor
 
     # Returns the response trailers supplied when the body closed.
     #
+    # @return [Hash] trailing response headers
+    #
     # @rbs () -> Hash[String, String | Array[String]]
     def trailers
       @state.value[:trailers]
@@ -243,6 +273,9 @@ module Raptor
 
     # Closes the stream and invokes its callback exactly once.
     #
+    # @param reason [Symbol] why the stream closed
+    # @return [void]
+    #
     # @rbs (Symbol reason) -> void
     def finish(reason)
       callback = false
@@ -272,6 +305,11 @@ module Raptor
 
     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(bytes)
       reserved = []
@@ -285,6 +323,11 @@ module Raptor
       true
     end
 
+    # 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(bytes)
       @budgets.each { |budget| budget.release(bytes) }

data/lib/raptor/http.rb

@@ -27,6 +27,16 @@ module Raptor
       def message = "could not write response"
     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?(status)
+      (status >= 100 && status < 200) || status == 204 || status == 304
+    end
+
     # Writes `string` in full, retrying on partial writes. Bounded by
     # `timeout` so a slow client can't pin the writing thread.
     #

data/lib/raptor/http1.rb

@@ -100,6 +100,9 @@ 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(chunk)
       HttpParser.chunked_encode(String.new, chunk)
@@ -107,6 +110,9 @@ module Raptor
 
     # 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(trailers)
       normalized = trailers.each_with_object({}) do |(key, value), headers|
@@ -547,6 +553,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(socket, id, env, parse_data, body, reactor, request_count, remote_addr, url_scheme)
       rack_env = nil
@@ -566,7 +583,7 @@ module Raptor
           body.close if body.respond_to?(:close)
         else
           hijacked = headers.is_a?(Hash) && !!headers[Rack::RACK_HIJACK]
-          no_body = rack_env[Rack::REQUEST_METHOD] == "HEAD" || (status >= 100 && status < 200) || status == 204 || status == 304
+          no_body = rack_env[Rack::REQUEST_METHOD] == "HEAD" || Http.no_entity_body_status?(status)
           detached = body.is_a?(DetachedBody) && !no_body
           if detached
             chunked = rack_env[Rack::SERVER_PROTOCOL] == HTTP_11
@@ -582,7 +599,7 @@ module Raptor
               socket,
               id,
               body,
-              {chunked: chunked, keep_alive: keep_alive, request_count: request_count, remote_addr: remote_addr, url_scheme: url_scheme},
+              { chunked: chunked, keep_alive: keep_alive, request_count: request_count, remote_addr: remote_addr, url_scheme: url_scheme },
               finished
             )
           else
@@ -950,6 +967,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(socket, status, headers, chunked:, keep_alive:)
       validate_status(status)
@@ -980,7 +1004,7 @@ module Raptor
       validate_status(status)
       response_hijack = headers.is_a?(Hash) ? headers.delete(Rack::RACK_HIJACK) : nil
       headers = normalize_headers(headers)
-      no_entity_body = (status >= 100 && status < 200) || status == 204 || status == 304
+      no_entity_body = Http.no_entity_body_status?(status)
       validate_headers(headers, status, no_entity_body)
 
       headers["connection"] = keep_alive ? CONNECTION_KEEPALIVE : CONNECTION_CLOSE

data/lib/raptor/http2.rb

@@ -71,6 +71,11 @@ module Raptor
 
       # Attaches a response body that outlives its application thread.
       #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @param body [DetachedBody] the response body
+      # @param finished [Proc] called with the close reason
+      # @return [Boolean] whether the reactor accepted the body
+      #
       # @rbs (Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
       def attach_body(stream_id, body, finished)
         @reactor.attach_http2_body(@connection_id, stream_id, body, finished)
@@ -416,7 +421,6 @@ module Raptor
       end
     end
 
-    EAGER_READ_TIMEOUT = 0.001
     EAGER_READ_BUFFER_SIZE = 64 * 1024
     EAGER_MAX_ROUNDS = 8
 
@@ -997,15 +1001,15 @@ module Raptor
       end
     end
 
-    # Reads the next frame batch from `socket` within a short window, or
-    # returns nil if nothing arrives in time.
+    # Reads the next frame batch from `socket` if it has already arrived,
+    # without waiting on the shared collector thread.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
     # @return [String, nil] the bytes read, or nil if nothing was available
     #
     # @rbs (OpenSSL::SSL::SSLSocket socket) -> String?
     def eager_read_next_batch(socket)
-      return unless socket.wait_readable(EAGER_READ_TIMEOUT)
+      return unless socket.wait_readable(0)
 
       data = begin
         socket.read_nonblock(EAGER_READ_BUFFER_SIZE)
@@ -1048,6 +1052,15 @@ module Raptor
 
     # Calls the Rack app and writes its response for one stream.
     #
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
+    # @param stream_id [Integer] the HTTP/2 stream identifier
+    # @param headers [Array<Array(String, String)>] request headers
+    # @param body [String] request body
+    # @param remote_addr [String] the client IP address
+    # @return [void]
+    #
     # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
     def perform_stream_request(socket, writer, flow_control, stream_id, headers, body, remote_addr:)
       env = nil
@@ -1060,7 +1073,7 @@ module Raptor
       env = build_rack_env(headers, body, socket, writer, flow_control, stream_id, remote_addr: remote_addr)
       status, response_headers, response_body = @app.call(env)
 
-      no_body = env[Rack::REQUEST_METHOD] == "HEAD" || (status >= 100 && status < 200) || status == 204 || status == 304
+      no_body = env[Rack::REQUEST_METHOD] == "HEAD" || Http.no_entity_body_status?(status)
       if response_body.is_a?(DetachedBody) && !no_body
         finished = proc do |reason|
           error = StreamClosedError.new unless reason == :closed
@@ -1068,9 +1081,10 @@ module Raptor
           Http.call_response_finished(env, status, response_headers, error)
           flow_control.discard_stream(stream_id)
         end
-        detached = write_http2_detached_response(socket, writer, flow_control, stream_id, status, response_headers, response_body, finished) do
+        write_http2_detached_response(socket, writer, flow_control, stream_id, status, response_headers, response_body, finished) do
           response_started = true
         end
+        detached = true
         return
       end
 
@@ -1113,7 +1127,18 @@ module Raptor
 
     # Starts a detached HTTP/2 response after writing its response headers.
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, DetachedBody body, ^(Symbol) -> void finished) { () -> void } -> bool
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
+    # @param stream_id [Integer] the HTTP/2 stream identifier
+    # @param status [Integer] HTTP status code
+    # @param headers [Hash] response headers from the Rack application
+    # @param body [DetachedBody] the response body
+    # @param finished [Proc] called with the close reason
+    # @yield once the response headers are queued
+    # @return [void]
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, DetachedBody body, ^(Symbol) -> void finished) { () -> void } -> void
     def write_http2_detached_response(socket, writer, flow_control, stream_id, status, headers, body, finished)
       flow_control.check(stream_id)
       parser = Http2Parser.new
@@ -1122,7 +1147,6 @@ module Raptor
       yield
       attached = writer.attach_body(stream_id, body, finished)
       write_http2_reset_stream(socket, writer, stream_id, ERROR_REFUSED_STREAM) unless attached
-      true
     end
 
     # Writes a Rack response as HTTP/2 frames to the socket, partitioning
@@ -1145,7 +1169,7 @@ module Raptor
 
       encoded_headers = parser.encode_response_headers(status, headers)
       flow_control.check(stream_id)
-      no_body = request_method == "HEAD" || (status >= 100 && status < 200) || status == 204 || status == 304
+      no_body = request_method == "HEAD" || Http.no_entity_body_status?(status)
       if no_body
         writer.write_frames(socket, [parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers)])
         yield if block_given?