raptor 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7a708bc4146a30fa1b03dbca5404dff1173c0b39348de9e3ae3a0330907063
-  data.tar.gz: 5db6986d6c9ca964873ec42f408d13087755b59c2517e7f942b8d2421ab88133
+  metadata.gz: 8391f9399db2e88dab106ad995a34060e6ae07f34c84825bfdcb066cd129dad4
+  data.tar.gz: 25cb3658e2aded284f302b84a1ee91d67344a5b5dd36c6c0e854381cfb4df048
 SHA512:
-  metadata.gz: 8e163192ea38a0fa01852fe9c8ea31b82ef90b7fdd8f1b2b65b04e73f49e10792ba01225644d23104b42a7c1d3f07f47c273123a36ff4e77ef6259e695f967b8
-  data.tar.gz: 90b1789fff941091795ebac8092deb97d6cdc51f915e38399bc782c05d6a101866f651d42a6183c948b99c25ab70532357c70d1090a68609cda0f6f3be46de8b
+  metadata.gz: e398237ccb391aff663c4d75e5470c0e4e0e6f6b273e26bface4cd6793691c3297053ab0a5d744deac8fd087c4f7dec0beb8426d8a762d3a089902d11dbe53e5
+  data.tar.gz: c4cfd5f7ffdcf7f970cc8c85868629bac6c6061312120c0dc2a3c64fa6431cf475bc8fbb877dce0bad3febc2bd87ccc5342e2bc9c8dad196c69306431ae91345

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-25
+
+- Add Rack handler for booting via `rackup` or `rails server`
+- Replace the HTTP/2 per-connection write mutex with a lock-free writer
+- Parse the first HTTP/1.1 request inline on the server thread
+
 ## [0.1.0] - 2026-05-22
 
 - Initial release

data/README.md

@@ -1,7 +1,8 @@
 # Raptor
 
-Raptor is a high-performance, multi-threaded, multi-process Ruby web server that leverages Ractors for parallel HTTP/1.1
-and HTTP/2 request processing, native C extensions for HTTP parsing and HPACK compression, and NIO for non-blocking I/O.
+Raptor is a high-performance, multi-threaded, multi-process Ruby Rack 3 web server that leverages Ractors for parallel
+HTTP/1.1 and HTTP/2 request processing, native C extensions for HTTP parsing and HPACK compression, and NIO for
+non-blocking I/O.
 
 ## Installation
 
@@ -52,15 +53,22 @@ Raptor Cluster initializing:
 Hello, World!%   
 ```
 
+Also works with `rackup` and `rails server`:
+
+```
+> bundle exec rackup -s raptor hello_world.ru
+> bundle exec rails server -u raptor
+```
+
 ## Benchmarks
 
 Raptor 0.1.0 vs Puma 8.0.1:
 
 | Protocol              | Raptor       | Puma         |
 | --------------------- | ------------ | ------------ |
-| HTTP/1.1              | 17.5k req/s  | 20.8k req/s  |
-| HTTP/1.1 (keep-alive) | 61.2k req/s  | 45.4k req/s  |
-| HTTP/2                | 23.4k req/s  | N/A          |
+| HTTP/1.1              | 20.3k req/s  | 20.8k req/s  |
+| HTTP/1.1 (keep-alive) | 60.9k req/s  | 45.4k req/s  |
+| HTTP/2                | 22.9k req/s  | N/A          |
 
 > Ruby 4.0.4 +YJIT, macOS Apple Silicon. 4 workers, 3 threads, 12 concurrent connections.
 

data/lib/rackup/handler/raptor.rb

@@ -0,0 +1,90 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "etc"
+
+module Rackup
+  module Handler
+    # Rack handler for booting Raptor through Rackup, `rails server`, or any
+    # other host that follows the Rack handler protocol.
+    #
+    module Raptor
+      DEFAULT_OPTIONS = {
+        Host: "0.0.0.0",
+        Port: 9292
+      }.freeze
+
+      # Boots a Raptor cluster serving the given Rack application.
+      #
+      # @param app [#call] the Rack application to serve
+      # @param options [Hash] handler options provided by Rackup or the host
+      # @yield [cluster] the cluster instance, before it starts running
+      # @return [void]
+      #
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
+      def self.run(app, **options)
+        require_relative "../../raptor/cli"
+        require_relative "../../raptor/cluster"
+
+        cluster = ::Raptor::Cluster.new(build_cluster_options(app, options))
+
+        yield cluster if block_given?
+
+        cluster.run
+      end
+
+      # Returns the handler-specific options surfaced by `rackup --help`.
+      #
+      # @return [Hash{String => String}] option spec to description mapping
+      #
+      # @rbs () -> Hash[String, String]
+      def self.valid_options
+        {
+          "Host=HOST"   => "Hostname to listen on (default: #{DEFAULT_OPTIONS[:Host]})",
+          "Port=PORT"   => "Port to listen on (default: #{DEFAULT_OPTIONS[:Port]})",
+          "Threads=NUM" => "Number of threads per worker (default: 3)",
+          "Ractors=NUM" => "Number of pipeline ractors per worker (default: 1)",
+          "Workers=NUM" => "Number of worker processes (default: nprocessors)"
+        }
+      end
+
+      # Builds a Raptor cluster options hash from Rack handler options.
+      #
+      # Options not explicitly supplied by the user (per the `:user_supplied_options`
+      # key) are treated as host-provided defaults.
+      #
+      # @param app [#call] the Rack application to serve
+      # @param options [Hash] handler options provided by Rackup or the host
+      # @return [Hash{Symbol => untyped}] cluster configuration
+      #
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+      def self.build_cluster_options(app, options)
+        defaults = DEFAULT_OPTIONS.dup
+
+        if user_supplied_options = options.delete(:user_supplied_options)
+          (options.keys - user_supplied_options).each do |key|
+            defaults[key] = options.delete(key)
+          end
+        end
+
+        host = options[:Host] || defaults[:Host]
+        port = options[:Port] || defaults[:Port]
+
+        cli_defaults = ::Raptor::CLI::DEFAULT_OPTIONS
+
+        {
+          app: app,
+          binds: ["tcp://#{host}:#{port}"],
+          threads: (options[:Threads] || cli_defaults[:threads]).to_i,
+          ractors: (options[:Ractors] || cli_defaults[:ractors]).to_i,
+          workers: (options[:Workers] || Etc.nprocessors).to_i,
+          client: cli_defaults[:client],
+          stats_file: nil
+        }
+      end
+      private_class_method :build_cluster_options
+    end
+
+    register :raptor, Raptor
+  end
+end

data/lib/raptor/cluster.rb

@@ -77,6 +77,7 @@ module Raptor
     # @option options [Integer] :ractors number of ractors per worker process
     # @option options [Integer] :workers number of worker processes
     # @option options [Array<String>] :binds array of bind URIs
+    # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
     # @option options [Hash] :client client timeout configuration
     # @return [void]
@@ -90,7 +91,7 @@ module Raptor
 
       @binder = Binder.new(options[:binds])
       @server_port = @binder.server_port
-      @app = Rack::Builder.parse_file(options[:rackup])
+      @app = options[:app] || Rack::Builder.parse_file(options[:rackup])
       log_initialization
 
       @shutdown = false
@@ -233,7 +234,7 @@ module Raptor
       reactor = Reactor.new(thread_pool, ractor_pool, client_options: @client_options)
       reactor_thread = reactor.run
 
-      server = Server.new(@binder, reactor, thread_pool)
+      server = Server.new(@binder, reactor, thread_pool, request)
       server_thread = server.run
 
       puts "[#{Process.pid}] Worker #{index} booted"

data/lib/raptor/http2.rb

@@ -3,6 +3,7 @@
 
 require "stringio"
 
+require "atomic-ruby/atom"
 require "rack"
 
 require_relative "raptor_http2"
@@ -16,6 +17,63 @@ module Raptor
   # 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.
+    #
+    class Writer
+      IDLE = :idle
+
+      # @rbs @state: Atom
+
+      # Creates a new Writer.
+      #
+      # @rbs () -> void
+      def initialize
+        @state = Atom.new(IDLE)
+      end
+
+      # Writes frames to the socket, coordinating with concurrent writers
+      # so that exactly one thread is actively writing at any time.
+      #
+      # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+      # @param frames [Array<String>] frame bytes to write in order
+      # @return [void]
+      #
+      # @rbs (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
+      def write_frames(socket, frames)
+        return if frames.nil? || frames.empty?
+
+        claimed = false
+        @state.swap do |current|
+          if current.equal?(IDLE)
+            claimed = true
+            frames
+          else
+            claimed = false
+            current + frames
+          end
+        end
+
+        return unless claimed
+
+        loop do
+          pending = nil
+          @state.swap do |current|
+            pending = current
+            current.empty? ? IDLE : []
+          end
+
+          break if pending.empty?
+
+          pending.each do |frame|
+            socket.write(frame) rescue nil
+          end
+        end
+      end
+    end
+
     FLAG_END_STREAM = 0x1
     FLAG_END_HEADERS = 0x4
     FLAG_ACK = 0x1
@@ -215,13 +273,9 @@ module Raptor
       socket = reactor.socket_for(result[:id])
       return unless socket
 
-      mutex = reactor.mutex_for(result[:id])
+      writer = reactor.writer_for(result[:id])
 
-      if result[:outgoing_frames]&.any?
-        mutex.synchronize do
-          result[:outgoing_frames].each { |frame| socket.write(frame) rescue nil }
-        end
-      end
+      writer.write_frames(socket, result[:outgoing_frames])
 
       reactor.update_http2_state(result)
 
@@ -231,7 +285,7 @@ module Raptor
 
         thread_pool << proc do
           dispatch_stream_request(
-            socket, mutex, stream_id,
+            socket, writer, stream_id,
             request[:headers], request[:body],
             remote_addr: remote_addr
           )
@@ -245,21 +299,21 @@ module Raptor
     # the response back as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @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, Mutex mutex, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
-    def dispatch_stream_request(socket, mutex, stream_id, headers, body, remote_addr:)
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
+    def dispatch_stream_request(socket, writer, stream_id, headers, body, remote_addr:)
       env = build_rack_env(headers, body, remote_addr: remote_addr)
       status, response_headers, response_body = @app.call(env)
 
-      write_http2_response(socket, mutex, stream_id, status, response_headers, response_body)
+      write_http2_response(socket, writer, stream_id, status, response_headers, response_body)
     rescue
-      write_http2_error_response(socket, mutex, stream_id)
+      write_http2_error_response(socket, writer, stream_id)
       raise
     ensure
       response_body.close if response_body.respond_to?(:close)
@@ -268,15 +322,15 @@ module Raptor
     # Writes a Rack response as HTTP/2 frames to the socket.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @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 [Object] response body responding to each
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
-    def write_http2_response(socket, mutex, stream_id, status, headers, body)
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    def write_http2_response(socket, writer, stream_id, status, headers, body)
       parser = Http2Parser.new
 
       header_pairs = [[":status", status.to_s]]
@@ -296,40 +350,38 @@ module Raptor
       body_chunks = []
       body.each { |chunk| body_chunks << chunk unless chunk.empty? }
 
-      mutex.synchronize do
-        if body_chunks.empty?
-          socket.write(parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers))
-        else
-          socket.write(parser.build_frame(:headers, FLAG_END_HEADERS, stream_id, encoded_headers))
+      frames = []
+      if body_chunks.empty?
+        frames << parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers)
+      else
+        frames << parser.build_frame(:headers, FLAG_END_HEADERS, stream_id, encoded_headers)
 
-          body_chunks.each_with_index do |chunk, index|
-            last = index == body_chunks.size - 1
-            flags = last ? FLAG_END_STREAM : 0
-            socket.write(parser.build_frame(:data, flags, stream_id, chunk))
-          end
+        last_index = body_chunks.size - 1
+        body_chunks.each_with_index do |chunk, index|
+          flags = index == last_index ? FLAG_END_STREAM : 0
+          frames << parser.build_frame(:data, flags, stream_id, chunk)
         end
       end
-    rescue IOError, Errno::EPIPE
-      # Connection closed
+
+      writer.write_frames(socket, frames)
     end
 
     # Writes a 500 error response as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id) -> void
-    def write_http2_error_response(socket, mutex, stream_id)
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
+    def write_http2_error_response(socket, writer, stream_id)
       parser = Http2Parser.new
       encoded = parser.encode_headers([[":status", "500"]])
 
-      mutex.synchronize do
-        socket.write(parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded))
-      end
-    rescue IOError, Errno::EPIPE
-      # Connection closed
+      writer.write_frames(
+        socket,
+        [parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded)]
+      )
     end
 
     # Builds a Rack environment hash from HTTP/2 headers and body.

data/lib/raptor/reactor.rb

@@ -75,7 +75,7 @@ module Raptor
     # @rbs @id_to_socket: Hash[Integer, TCPSocket]
     # @rbs @socket_to_state: Hash[TCPSocket, Hash[Symbol, untyped]]
     # @rbs @id_to_timeout: Hash[Integer, TimeoutClient]
-    # @rbs @id_to_mutex: Hash[Integer, Mutex]
+    # @rbs @id_to_writer: Hash[Integer, untyped]
 
     # Creates a new Reactor instance.
     #
@@ -100,7 +100,7 @@ module Raptor
       @id_to_socket = {}
       @socket_to_state = {}
       @id_to_timeout = {}
-      @id_to_mutex = {}
+      @id_to_writer = {}
     end
 
     # Starts the reactor's main event loop in a new thread.
@@ -162,12 +162,10 @@ module Raptor
     def add(state)
       socket = state[:socket]
       state.delete(:socket)
+      writer = state.delete(:writer)
       @id_to_socket[state[:id]] = socket
       @socket_to_state[socket] = state
-
-      if state[:protocol] == :http2
-        @id_to_mutex[state[:id]] = Mutex.new
-      end
+      @id_to_writer[state[:id]] = writer if writer
 
       read_and_queue_for_parse(socket, state)
     end
@@ -252,14 +250,16 @@ module Raptor
       @id_to_socket[id]
     end
 
-    # Returns the mutex for a given HTTP/2 connection.
+    # 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.
     #
     # @param id [Integer] unique client identifier
-    # @return [Mutex, nil] the mutex, if found
+    # @return [Object, nil] the writer, if found
     #
-    # @rbs (Integer id) -> Mutex?
-    def mutex_for(id)
-      @id_to_mutex[id]
+    # @rbs (Integer id) -> untyped?
+    def writer_for(id)
+      @id_to_writer[id]
     end
 
     # Updates connection state for an HTTP/2 connection after frame processing.
@@ -384,7 +384,7 @@ module Raptor
     def cleanup(socket)
       state = @socket_to_state.delete(socket)
       @id_to_socket.delete(state[:id])
-      @id_to_mutex.delete(state[:id])
+      @id_to_writer.delete(state[:id])
       socket.close
     end
 

data/lib/raptor/request.rb

@@ -20,7 +20,7 @@ module Raptor
   class Request
     BODY_BUFFER_THRESHOLD = 256 * 1024
     FILE_CHUNK_SIZE = 64 * 1024
-    KEEPALIVE_BUFFER_SIZE = 64 * 1024
+    READ_BUFFER_SIZE = 64 * 1024
     WRITE_TIMEOUT = 5
     KEEPALIVE_READ_TIMEOUT = 0.001
     MAX_KEEPALIVE_REQUESTS = 100
@@ -59,6 +59,35 @@ module Raptor
       def message = "could not write response"
     end
 
+    # Decodes a chunked transfer-encoded body buffer.
+    #
+    # Returns the decoded bytes and a flag indicating whether the terminating
+    # zero-length chunk was found. The decoder stops at the first unparseable
+    # boundary (incomplete CRLF) or zero-length chunk.
+    #
+    # @param buffer [String] the raw body buffer to decode
+    # @return [Array(String, Boolean)] decoded body and completion flag
+    #
+    # @rbs (String buffer) -> [String, bool]
+    def self.decode_chunked(buffer)
+      decoded = String.new
+      offset = 0
+
+      while offset < buffer.bytesize
+        crlf = buffer.index("\r\n", offset)
+        return [decoded, false] unless crlf
+
+        chunk_size = buffer.byteslice(offset, crlf - offset).to_i(16)
+        return [decoded, true] if chunk_size == 0
+
+        offset = crlf + 2
+        decoded << buffer.byteslice(offset, chunk_size)
+        offset += chunk_size + 2
+      end
+
+      [decoded, false]
+    end
+
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
 
@@ -74,6 +103,73 @@ module Raptor
       @server_port = server_port
     end
 
+    # Eagerly reads and parses the first request on a freshly accepted
+    # connection on the server thread, dispatching directly to the thread pool
+    # when complete. Falls back to the reactor when more data is needed.
+    #
+    # @param socket [TCPSocket] the freshly accepted client socket
+    # @param id [Integer] unique client identifier
+    # @param reactor [Reactor] the reactor for fallback registration
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
+    # @param remote_addr [String] client IP address
+    # @param url_scheme [String] "http" or "https"
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, Integer id, Reactor reactor, AtomicThreadPool thread_pool, String remote_addr, String url_scheme) -> void
+    def eager_accept(socket, id, reactor, thread_pool, remote_addr, url_scheme)
+      data = begin
+        socket.read_nonblock(READ_BUFFER_SIZE)
+      rescue IO::WaitReadable
+        reactor.add(
+          id: id,
+          socket: socket,
+          remote_addr: remote_addr,
+          url_scheme: url_scheme
+        )
+        return
+      rescue EOFError, IOError
+        socket.close rescue nil
+        return
+      end
+
+      buffer = String.new
+      buffer << data
+
+      while socket.respond_to?(:pending) && socket.pending > 0
+        buffer << socket.read_nonblock(socket.pending)
+      end
+
+      parser = HttpParser.new
+      env = {}
+      nread = parser.execute(env, buffer, 0)
+      parse_data = { parse_count: 1, content_length: parser.content_length }
+
+      body = nil
+      if !parser.finished?
+        fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
+        return
+      elsif parser.has_body?
+        body = buffer.byteslice(nread..-1) || ""
+
+        if env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
+          body, chunked_complete = Request.decode_chunked(body)
+          if chunked_complete
+            env.delete(HTTP_TRANSFER_ENCODING)
+          else
+            fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
+            return
+          end
+        elsif parser.content_length > body.bytesize
+          fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, 0, remote_addr, url_scheme, persisted: false)
+          return
+        end
+      end
+
+      thread_pool << proc do
+        process_client(socket, id, env, parse_data, body, reactor, thread_pool, 1, remote_addr, url_scheme)
+      end
+    end
+
     # Returns a Proc for HTTP parsing work in Ractor context.
     #
     # The returned Proc processes raw socket data through the appropriate
@@ -102,25 +198,7 @@ module Raptor
             body_buffer = data[:buffer].byteslice(nread..-1) || ""
 
             if env[HTTP_TRANSFER_ENCODING]&.include?(TRANSFER_ENCODING_CHUNKED)
-              decoded_body = String.new
-              offset = 0
-              chunked_complete = false
-
-              while offset < body_buffer.bytesize
-                crlf = body_buffer.index("\r\n", offset)
-                break unless crlf
-
-                chunk_size = body_buffer.byteslice(offset, crlf - offset).to_i(16)
-
-                if chunk_size == 0
-                  chunked_complete = true
-                  break
-                end
-
-                offset = crlf + 2
-                decoded_body << body_buffer.byteslice(offset, chunk_size)
-                offset += chunk_size + 2
-              end
+              decoded_body, chunked_complete = Raptor::Request.decode_chunked(body_buffer)
 
               if chunked_complete
                 env.delete(HTTP_TRANSFER_ENCODING)
@@ -278,7 +356,7 @@ module Raptor
         end
 
         data = begin
-          socket.read_nonblock(KEEPALIVE_BUFFER_SIZE)
+          socket.read_nonblock(READ_BUFFER_SIZE)
         rescue IO::WaitReadable
           reactor.persist(socket, id, request_count, remote_addr: remote_addr, url_scheme: url_scheme)
           return
@@ -346,8 +424,12 @@ module Raptor
       end
     end
 
-    # Re-registers a socket with the reactor for further processing
-    # when an incomplete request is received during eager keep-alive.
+    # Re-registers a socket with the reactor for further processing when
+    # an incomplete request is received during eager accept or eager keep-alive.
+    #
+    # The persisted flag selects between persistent_data_timeout (for
+    # kept-alive connections awaiting the next request) and chunk_data_timeout
+    # (for fresh connections awaiting the rest of the first request).
     #
     # @param socket [TCPSocket] the client socket
     # @param id [Integer] unique client identifier
@@ -358,21 +440,23 @@ module Raptor
     # @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"
+    # @param persisted [Boolean] whether the connection has already completed at least one request
     # @return [void]
     #
-    # @rbs (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme) -> void
-    def fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, request_count, remote_addr, url_scheme)
+    # @rbs (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme, persisted: bool) -> void
+    def fallback_to_reactor(socket, id, buffer, env, parse_data, reactor, request_count, remote_addr, url_scheme, persisted: true)
       reactor.persist(socket, id, request_count, remote_addr: remote_addr, url_scheme: url_scheme)
-      reactor.update_state(Ractor.make_shareable({
+      state = {
         id: id,
         buffer: buffer,
         env: env,
         request_count: request_count,
         parse_data: parse_data,
         remote_addr: remote_addr,
-        url_scheme: url_scheme,
-        persisted: true
-      }))
+        url_scheme: url_scheme
+      }
+      state[:persisted] = true if persisted
+      reactor.update_state(Ractor.make_shareable(state))
     end
 
     # Builds a Rack environment hash from parsed HTTP request data.

data/lib/raptor/server.rb

@@ -15,16 +15,19 @@ module Raptor
   #
   # Supports TCP, Unix domain, and SSL listeners transparently. TCP_NODELAY is
   # applied only to TCP sockets, and SSL handshakes are performed synchronously
-  # before handing the connection to the reactor.
+  # before the connection is dispatched.
   #
-  # For SSL connections, ALPN negotiation determines the protocol. HTTP/2
-  # connections are added to the reactor with initial SETTINGS and processed
-  # through the same ractor pool pipeline as HTTP/1.1 connections.
+  # For HTTP/1.1 connections the first request is parsed inline on the server
+  # thread and dispatched directly to the thread pool, falling back to the
+  # reactor only when more data is needed. For HTTP/2 connections (negotiated
+  # via ALPN) the server sends initial SETTINGS and registers the connection
+  # with the reactor for frame processing through the ractor pool.
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
   #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {})
-  #   server = Server.new(binder, reactor, thread_pool)
+  #   request = Request.new(app, 3000)
+  #   server = Server.new(binder, reactor, thread_pool, request)
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -37,6 +40,7 @@ module Raptor
     # @rbs @binder: Binder
     # @rbs @reactor: Reactor
     # @rbs @thread_pool: AtomicThreadPool
+    # @rbs @request: Request
     # @rbs @running: AtomicBoolean
 
     # Creates a new Server instance.
@@ -44,13 +48,15 @@ module Raptor
     # @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 request [Request] the HTTP/1.1 request handler
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool) -> void
-    def initialize(binder, reactor, thread_pool)
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request) -> void
+    def initialize(binder, reactor, thread_pool, request)
       @binder = binder
       @reactor = reactor
       @thread_pool = thread_pool
+      @request = request
       @running = AtomicBoolean.new(true)
     end
 
@@ -149,18 +155,21 @@ module Raptor
             socket: ssl_socket,
             remote_addr: remote_addr,
             url_scheme: HTTPS_SCHEME,
-            protocol: :http2
+            protocol: :http2,
+            writer: Http2::Writer.new
           )
 
           return
         end
       end
 
-      reactor.add(
-        id: client.object_id,
-        socket: client,
-        remote_addr: remote_addr,
-        url_scheme: url_scheme
+      @request.eager_accept(
+        client,
+        client.object_id,
+        reactor,
+        @thread_pool,
+        remote_addr,
+        url_scheme
       )
     end
   end

data/lib/raptor/version.rb

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

data/sig/generated/rackup/handler/raptor.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/rackup/handler/raptor.rb with RBS::Inline
+
+module Rackup
+  module Handler
+    # Rack handler for booting Raptor through Rackup, `rails server`, or any
+    # other host that follows the Rack handler protocol.
+    module Raptor
+      DEFAULT_OPTIONS: untyped
+
+      # Boots a Raptor cluster serving the given Rack application.
+      #
+      # @param app [#call] the Rack application to serve
+      # @param options [Hash] handler options provided by Rackup or the host
+      # @yield [cluster] the cluster instance, before it starts running
+      # @return [void]
+      #
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
+      def self.run: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
+
+      # Returns the handler-specific options surfaced by `rackup --help`.
+      #
+      # @return [Hash{String => String}] option spec to description mapping
+      #
+      # @rbs () -> Hash[String, String]
+      def self.valid_options: () -> Hash[String, String]
+
+      # Builds a Raptor cluster options hash from Rack handler options.
+      #
+      # Options not explicitly supplied by the user (per the `:user_supplied_options`
+      # key) are treated as host-provided defaults.
+      #
+      # @param app [#call] the Rack application to serve
+      # @param options [Hash] handler options provided by Rackup or the host
+      # @return [Hash{Symbol => untyped}] cluster configuration
+      #
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+      def self.build_cluster_options: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/generated/raptor/cluster.rbs

@@ -70,6 +70,7 @@ module Raptor
     # @option options [Integer] :ractors number of ractors per worker process
     # @option options [Integer] :workers number of worker processes
     # @option options [Array<String>] :binds array of bind URIs
+    # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
     # @option options [Hash] :client client timeout configuration
     # @return [void]

data/sig/generated/raptor/http2.rbs

@@ -8,6 +8,31 @@ module Raptor
   # 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.
+    class Writer
+      IDLE: ::Symbol
+
+      @state: Atom
+
+      # Creates a new Writer.
+      #
+      # @rbs () -> void
+      def initialize: () -> void
+
+      # Writes frames to the socket, coordinating with concurrent writers
+      # so that exactly one thread is actively writing at any time.
+      #
+      # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+      # @param frames [Array<String>] frame bytes to write in order
+      # @return [void]
+      #
+      # @rbs (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
+      def write_frames: (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
+    end
+
     FLAG_END_STREAM: ::Integer
 
     FLAG_END_HEADERS: ::Integer
@@ -88,38 +113,38 @@ module Raptor
     # the response back as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @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, Mutex mutex, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
-    def dispatch_stream_request: (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id, Array[[ String, String ]] headers, String body, remote_addr: String) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
+    def dispatch_stream_request: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Array[[ String, String ]] headers, String body, remote_addr: String) -> void
 
     # Writes a Rack response as HTTP/2 frames to the socket.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @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 [Object] response body responding to each
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
-    def write_http2_response: (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    def write_http2_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
 
     # Writes a 500 error response as HTTP/2 frames.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-    # @param mutex [Mutex] mutex for serializing writes to the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
     # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id) -> void
-    def write_http2_error_response: (OpenSSL::SSL::SSLSocket socket, Mutex mutex, Integer stream_id) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
+    def write_http2_error_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
 
     # Builds a Rack environment hash from HTTP/2 headers and body.
     #

data/sig/generated/raptor/reactor.rbs

@@ -55,7 +55,7 @@ module Raptor
 
     TIMEOUT_RESPONSE: ::String
 
-    @id_to_mutex: Hash[Integer, Mutex]
+    @id_to_writer: Hash[Integer, untyped]
 
     @id_to_timeout: Hash[Integer, TimeoutClient]
 
@@ -159,13 +159,15 @@ module Raptor
     # @rbs (Integer id) -> TCPSocket?
     def socket_for: (Integer id) -> TCPSocket?
 
-    # Returns the mutex for a given HTTP/2 connection.
+    # 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.
     #
     # @param id [Integer] unique client identifier
-    # @return [Mutex, nil] the mutex, if found
+    # @return [Object, nil] the writer, if found
     #
-    # @rbs (Integer id) -> Mutex?
-    def mutex_for: (Integer id) -> Mutex?
+    # @rbs (Integer id) -> untyped?
+    def writer_for: (Integer id) -> untyped?
 
     # Updates connection state for an HTTP/2 connection after frame processing.
     #

data/sig/generated/raptor/request.rbs

@@ -13,7 +13,7 @@ module Raptor
 
     FILE_CHUNK_SIZE: untyped
 
-    KEEPALIVE_BUFFER_SIZE: untyped
+    READ_BUFFER_SIZE: untyped
 
     WRITE_TIMEOUT: ::Integer
 
@@ -63,6 +63,18 @@ module Raptor
       def message: () -> String
     end
 
+    # Decodes a chunked transfer-encoded body buffer.
+    #
+    # Returns the decoded bytes and a flag indicating whether the terminating
+    # zero-length chunk was found. The decoder stops at the first unparseable
+    # boundary (incomplete CRLF) or zero-length chunk.
+    #
+    # @param buffer [String] the raw body buffer to decode
+    # @return [Array(String, Boolean)] decoded body and completion flag
+    #
+    # @rbs (String buffer) -> [String, bool]
+    def self.decode_chunked: (String buffer) -> [ String, bool ]
+
     @server_port: Integer
 
     @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
@@ -76,6 +88,21 @@ module Raptor
     # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port) -> void
     def initialize: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Integer server_port) -> void
 
+    # Eagerly reads and parses the first request on a freshly accepted
+    # connection on the server thread, dispatching directly to the thread pool
+    # when complete. Falls back to the reactor when more data is needed.
+    #
+    # @param socket [TCPSocket] the freshly accepted client socket
+    # @param id [Integer] unique client identifier
+    # @param reactor [Reactor] the reactor for fallback registration
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
+    # @param remote_addr [String] client IP address
+    # @param url_scheme [String] "http" or "https"
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, Integer id, Reactor reactor, AtomicThreadPool thread_pool, String remote_addr, String url_scheme) -> void
+    def eager_accept: (TCPSocket socket, Integer id, Reactor reactor, AtomicThreadPool thread_pool, String remote_addr, String url_scheme) -> void
+
     # Returns a Proc for HTTP parsing work in Ractor context.
     #
     # The returned Proc processes raw socket data through the appropriate
@@ -154,8 +181,12 @@ module Raptor
     # @rbs (TCPSocket socket, Integer id, Reactor reactor, AtomicThreadPool thread_pool, Integer request_count, String remote_addr, String url_scheme) -> void
     def eager_keepalive: (TCPSocket socket, Integer id, Reactor reactor, AtomicThreadPool thread_pool, Integer request_count, String remote_addr, String url_scheme) -> void
 
-    # Re-registers a socket with the reactor for further processing
-    # when an incomplete request is received during eager keep-alive.
+    # Re-registers a socket with the reactor for further processing when
+    # an incomplete request is received during eager accept or eager keep-alive.
+    #
+    # The persisted flag selects between persistent_data_timeout (for
+    # kept-alive connections awaiting the next request) and chunk_data_timeout
+    # (for fresh connections awaiting the rest of the first request).
     #
     # @param socket [TCPSocket] the client socket
     # @param id [Integer] unique client identifier
@@ -166,10 +197,11 @@ module Raptor
     # @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"
+    # @param persisted [Boolean] whether the connection has already completed at least one request
     # @return [void]
     #
-    # @rbs (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme) -> void
-    def fallback_to_reactor: (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme) -> void
+    # @rbs (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme, persisted: bool) -> void
+    def fallback_to_reactor: (TCPSocket socket, Integer id, String buffer, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, Reactor reactor, Integer request_count, String remote_addr, String url_scheme, persisted: bool) -> void
 
     # Builds a Rack environment hash from parsed HTTP request data.
     #

data/sig/generated/raptor/server.rbs

@@ -10,16 +10,19 @@ module Raptor
   #
   # Supports TCP, Unix domain, and SSL listeners transparently. TCP_NODELAY is
   # applied only to TCP sockets, and SSL handshakes are performed synchronously
-  # before handing the connection to the reactor.
+  # before the connection is dispatched.
   #
-  # For SSL connections, ALPN negotiation determines the protocol. HTTP/2
-  # connections are added to the reactor with initial SETTINGS and processed
-  # through the same ractor pool pipeline as HTTP/1.1 connections.
+  # For HTTP/1.1 connections the first request is parsed inline on the server
+  # thread and dispatched directly to the thread pool, falling back to the
+  # reactor only when more data is needed. For HTTP/2 connections (negotiated
+  # via ALPN) the server sends initial SETTINGS and registers the connection
+  # with the reactor for frame processing through the ractor pool.
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
   #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {})
-  #   server = Server.new(binder, reactor, thread_pool)
+  #   request = Request.new(app, 3000)
+  #   server = Server.new(binder, reactor, thread_pool, request)
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -36,6 +39,8 @@ module Raptor
 
     @thread_pool: AtomicThreadPool
 
+    @request: Request
+
     @running: AtomicBoolean
 
     # Creates a new Server instance.
@@ -43,10 +48,11 @@ module Raptor
     # @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 request [Request] the HTTP/1.1 request handler
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool) -> void
-    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool) -> void
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request) -> void
+    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request) -> void
 
     # Starts the server's main accept loop in a new thread.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Joshua Young
@@ -114,6 +114,7 @@ files:
 - ext/raptor_http2/extconf.rb
 - ext/raptor_http2/huffman_table.h
 - ext/raptor_http2/raptor_http2.c
+- lib/rackup/handler/raptor.rb
 - lib/raptor.rb
 - lib/raptor/binder.rb
 - lib/raptor/cli.rb
@@ -124,6 +125,7 @@ files:
 - lib/raptor/server.rb
 - lib/raptor/stats.rb
 - lib/raptor/version.rb
+- sig/generated/rackup/handler/raptor.rbs
 - sig/generated/raptor.rbs
 - sig/generated/raptor/binder.rbs
 - sig/generated/raptor/cli.rbs