raptor 0.3.0 → 0.5.0

data/lib/raptor/reactor.rb

@@ -9,12 +9,12 @@ module Raptor
   #
   # Reactor uses NIO selectors for efficient I/O multiplexing and implements
   # client timeouts using a red-black tree for O(log n) timeout management.
-  # It coordinates between thread pools for blocking operations and ractor
-  # pools for CPU-intensive HTTP parsing, and provides backlog metrics
-  # that the server uses for backpressure control to prevent overload.
+  # It coordinates between ractor pools for CPU-intensive HTTP parsing and
+  # thread pools for blocking operations, and provides backlog metrics that
+  # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {
+  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
   #     first_data_timeout: 30,
   #     chunk_data_timeout: 10
   #   })
@@ -24,38 +24,38 @@ module Raptor
   #   reactor.shutdown
   #
   class Reactor
-    # Red-black tree node representing a client connection with timeout tracking.
-    #
-    # TimeoutClient extends RedBlackTree::Node to enable efficient timeout
-    # management using the tree's ordering properties.
+    # A client connection node ordered by absolute expiry time so the
+    # soonest-to-expire is always at the tree's minimum.
     #
     class TimeoutClient < RedBlackTree::Node
       # @rbs attr_accessor timeout_at: Float
       attr_accessor :timeout_at
 
-      # Returns the client data stored in this timeout node.
+      # Semantic alias for the inherited `data` slot.
       #
-      # @return [Hash] the client connection state data
+      # @return [Hash] the client connection state
       #
       # @rbs () -> Hash[Symbol, untyped]
       def client_data
         data
       end
 
-      # Calculates remaining timeout duration from the current time.
+      # Returns seconds until expiry, clamped to 0 so an already-expired
+      # client doesn't push the next selector wait into the future.
       #
       # @param now [Float] current monotonic timestamp
-      # @return [Float] remaining timeout in seconds, minimum 0
+      # @return [Float] seconds until expiry, never negative
       #
       # @rbs (Float now) -> Float
       def timeout(now)
         [timeout_at - now, 0].max
       end
 
-      # Compares timeout nodes by their timeout_at values for tree ordering.
+      # Orders nodes by `timeout_at` so the tree minimum is the next
+      # client to expire.
       #
       # @param other [TimeoutClient] another timeout client to compare
-      # @return [Integer] -1, 0, or 1 for ordering
+      # @return [Integer] -1, 0, or 1
       #
       # @rbs (TimeoutClient other) -> Integer
       def <=>(other)
@@ -76,21 +76,22 @@ module Raptor
     # @rbs @socket_to_state: Hash[TCPSocket, Hash[Symbol, untyped]]
     # @rbs @id_to_timeout: Hash[Integer, TimeoutClient]
     # @rbs @id_to_writer: Hash[Integer, untyped]
+    # @rbs @id_to_flow_control: Hash[Integer, untyped]
 
     # Creates a new Reactor instance.
     #
-    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
     # @param client_options [Hash] timeout configuration options
     # @option client_options [Integer] :first_data_timeout timeout for initial data
     # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
     # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
     # @return [void]
     #
-    # @rbs (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize(thread_pool, ractor_pool, client_options:)
-      @thread_pool = thread_pool
+    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
+    def initialize(ractor_pool, thread_pool, client_options:)
       @ractor_pool = ractor_pool
+      @thread_pool = thread_pool
       @client_options = client_options
 
       @selector = NIO::Selector.new
@@ -101,6 +102,7 @@ module Raptor
       @socket_to_state = {}
       @id_to_timeout = {}
       @id_to_writer = {}
+      @id_to_flow_control = {}
     end
 
     # Starts the reactor's main event loop in a new thread.
@@ -117,33 +119,37 @@ module Raptor
         Thread.current.name = self.class.name
 
         until @queue.closed? && @queue.empty?
-          timeout = @timeouts.min&.timeout(Process.clock_gettime(Process::CLOCK_MONOTONIC))
-          @selector.select(timeout) do |monitor|
-            wakeup!(monitor.value)
-          end
-
-          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          expired = []
-          @timeouts.traverse do |to_client|
-            break unless to_client.timeout(now) == 0
-
-            expired << to_client
-          end
-
-          expired.each do |to_client|
-            @timeouts.delete!(to_client)
-            id = to_client.client_data[:id]
-            @id_to_timeout.delete(id)
-            socket = @id_to_socket[id]
-            next unless socket
-
-            @selector.deregister(socket)
-            socket.write(TIMEOUT_RESPONSE) rescue nil
-            cleanup(socket)
-          end
-
-          until @queue.empty?
-            register(@queue.pop)
+          begin
+            timeout = @timeouts.min&.timeout(Process.clock_gettime(Process::CLOCK_MONOTONIC))
+            @selector.select(timeout) do |monitor|
+              wakeup!(monitor.value)
+            end
+
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            expired = []
+            @timeouts.traverse do |to_client|
+              break unless to_client.timeout(now) == 0
+
+              expired << to_client
+            end
+
+            expired.each do |to_client|
+              @timeouts.delete!(to_client)
+              id = to_client.client_data[:id]
+              @id_to_timeout.delete(id)
+              socket = @id_to_socket[id]
+              next unless socket
+
+              @selector.deregister(socket)
+              socket.write(TIMEOUT_RESPONSE) rescue nil
+              cleanup(socket)
+            end
+
+            until @queue.empty?
+              register(@queue.pop)
+            end
+          rescue => error
+            Log.rescued_error(error)
           end
         end
 
@@ -163,9 +169,11 @@ module Raptor
       socket = state[:socket]
       state.delete(:socket)
       writer = state.delete(:writer)
+      flow_control = state.delete(:flow_control)
       @id_to_socket[state[:id]] = socket
       @socket_to_state[socket] = state
       @id_to_writer[state[:id]] = writer if writer
+      @id_to_flow_control[state[:id]] = flow_control if flow_control
 
       read_and_queue_for_parse(socket, state)
     end
@@ -191,13 +199,12 @@ module Raptor
       socket.close
     end
 
-    # Removes a client connection from the reactor.
-    #
-    # Called when an HTTP request is complete and ready for application
-    # processing. Triggers server accept re-enabling if system capacity allows.
+    # Drops the reactor's references to a client whose parsed request
+    # has been handed off to the thread pool. The socket itself is kept
+    # open so the worker can write the response.
     #
     # @param id [Integer] unique client identifier
-    # @return [TCPSocket, nil] the removed socket, if found
+    # @return [TCPSocket, nil] the socket associated with `id`, if any
     #
     # @rbs (Integer id) -> TCPSocket?
     def remove(id)
@@ -262,6 +269,18 @@ module Raptor
       @id_to_writer[id]
     end
 
+    # Returns the flow controller associated with a given connection, if one
+    # was supplied when the connection was added. Used by HTTP/2 stream
+    # dispatchers to honour the peer's flow-control windows.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [Object, nil] the flow controller, if found
+    #
+    # @rbs (Integer id) -> untyped?
+    def flow_control_for(id)
+      @id_to_flow_control[id]
+    end
+
     # Updates connection state for an HTTP/2 connection after frame processing.
     #
     # Re-registers the socket with the selector for further reads and stores
@@ -282,10 +301,26 @@ module Raptor
       socket.close
     end
 
-    # Initiates reactor shutdown.
+    # Closes the socket for the given connection and drops all reactor state
+    # associated with it. Used to terminate HTTP/2 connections after sending
+    # a GOAWAY frame.
     #
-    # Closes the registration queue and wakes up the selector to begin
-    # graceful shutdown process.
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
+    # @rbs (Integer id) -> void
+    def close_connection(id)
+      socket = @id_to_socket.delete(id)
+      return unless socket
+
+      @socket_to_state.delete(socket)
+      @id_to_writer.delete(id)
+      @id_to_flow_control.delete(id)
+      socket.close rescue nil
+    end
+
+    # Closes the registration queue and wakes the selector so the
+    # event loop drains pending work and exits.
     #
     # @return [void]
     #
@@ -385,6 +420,7 @@ module Raptor
       state = @socket_to_state.delete(socket)
       @id_to_socket.delete(state[:id])
       @id_to_writer.delete(state[:id])
+      @id_to_flow_control.delete(state[:id])
       socket.close
     end
 

data/lib/raptor/request.rb

@@ -5,18 +5,16 @@ require "socket"
 require "stringio"
 require "tempfile"
 
+require "atomic-ruby/atomic_boolean"
 require "rack"
 
 require_relative "raptor_http"
 
 module Raptor
-  # Handles HTTP request processing and Rack application integration.
-  #
-  # Request manages the HTTP parsing pipeline using Ractors and coordinates
-  # with the reactor for connection state management. It bridges between the
-  # low-level HTTP parsing and high-level Rack application interface, handling
-  # both incomplete requests (that need more data) and complete requests
-  # (ready for application processing).
+  # Parses HTTP/1.x requests and dispatches them to the Rack
+  # application. Coordinates with the Ractor pool for parsing and
+  # with the reactor for requests that need more data before they
+  # can be handled.
   #
   class Request
     BODY_BUFFER_THRESHOLD = 256 * 1024
@@ -26,7 +24,6 @@ module Raptor
     KEEPALIVE_READ_TIMEOUT = 0.001
     MAX_KEEPALIVE_REQUESTS = 100
 
-    HTTP_SCHEME = "http"
     HTTP_10 = "HTTP/1.0"
     HTTP_11 = "HTTP/1.1"
     STATUS_LINE_CACHE_10 = Hash.new do |h, status|
@@ -39,6 +36,7 @@ module Raptor
     end
 
     STATUS_WITH_NO_ENTITY_BODY = Set.new([204, 304, *100..199]).freeze
+    BAD_REQUEST_RESPONSE = "HTTP/1.1 400 Bad Request\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
     INTERNAL_SERVER_ERROR_RESPONSE = "HTTP/1.1 500 Internal Server Error\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
     CONTENT_TOO_LARGE_RESPONSE = "HTTP/1.1 413 Content Too Large\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
 
@@ -92,11 +90,37 @@ module Raptor
       [decoded, :incomplete]
     end
 
+    # Writes `string` in full, retrying on partial writes. Bounded by
+    # `WRITE_TIMEOUT` so a slow client can't pin the writing thread.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param string [String] the data to write
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, String string) -> void
+    def self.socket_write(socket, string)
+      bytes = 0
+      byte_size = string.bytesize
+
+      while bytes < byte_size
+        begin
+          bytes += socket.write_nonblock(bytes.zero? ? string : string.byteslice(bytes..-1))
+        rescue IO::WaitWritable
+          raise WriteError unless socket.wait_writable(WRITE_TIMEOUT)
+          retry
+        rescue IOError
+          raise WriteError
+        end
+      end
+    end
+
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
     # @rbs @max_body_size: Integer?
     # @rbs @body_spool_threshold: Integer?
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    # @rbs @running: AtomicBoolean
 
     # Creates a new Request handler.
     #
@@ -115,6 +139,17 @@ module Raptor
       @max_body_size = client_options[:max_body_size]
       @body_spool_threshold = client_options[:body_spool_threshold]
       @on_error = on_error
+      @running = AtomicBoolean.new(true)
+    end
+
+    # Signals eager keep-alive loops to stop processing further requests on
+    # their connections. In-flight requests complete normally.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown
+      @running.make_false
     end
 
     # Eagerly reads and parses the first request on a freshly accepted
@@ -155,7 +190,12 @@ module Raptor
 
       parser = HttpParser.new
       env = {}
-      nread = parser.execute(env, buffer, 0)
+      nread = begin
+        parser.execute(env, buffer, 0)
+      rescue HttpParserError
+        reject_malformed(socket)
+        return
+      end
       parse_data = { parse_count: 1, content_length: parser.content_length }
 
       body = nil
@@ -210,7 +250,11 @@ module Raptor
 
         parser = Raptor::HttpParser.new
         env = {}
-        nread = parser.execute(env, data[:buffer], 0)
+        nread = begin
+          parser.execute(env, data[:buffer], 0)
+        rescue Raptor::HttpParserError
+          next Ractor.make_shareable(data.merge(complete: true, malformed: true))
+        end
         parse_data = if data[:parse_data]
           data[:parse_data].dup
         else
@@ -269,13 +313,19 @@ module Raptor
         return
       end
 
+      if parsed_request[:malformed]
+        socket = reactor.remove(parsed_request[:id])
+        reject_malformed(socket) if socket
+        return
+      end
+
       unless parsed_request[:complete]
         reactor.update_state(parsed_request)
       else
         socket = reactor.remove(parsed_request[:id])
         request_count = (parsed_request[:request_count] || 0) + 1
-        remote_addr = parsed_request[:remote_addr] || "127.0.0.1"
-        url_scheme = parsed_request[:url_scheme] || HTTP_SCHEME
+        remote_addr = parsed_request[:remote_addr] || Server::DEFAULT_REMOTE_ADDR
+        url_scheme = parsed_request[:url_scheme] || Server::HTTP_SCHEME
 
         thread_pool << proc do
           process_client(
@@ -394,6 +444,11 @@ 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(socket, id, reactor, thread_pool, request_count, remote_addr, url_scheme)
       loop do
+        unless @running.true?
+          socket.close rescue nil
+          return
+        end
+
         unless socket.wait_readable(KEEPALIVE_READ_TIMEOUT)
           reactor.persist(socket, id, request_count, remote_addr: remote_addr, url_scheme: url_scheme)
           return
@@ -418,7 +473,12 @@ module Raptor
 
         parser = HttpParser.new
         env = {}
-        nread = parser.execute(env, buffer, 0)
+        nread = begin
+          parser.execute(env, buffer, 0)
+        rescue HttpParserError
+          reject_malformed(socket)
+          return
+        end
         parse_data = { parse_count: 1, content_length: parser.content_length }
 
         body = nil
@@ -515,6 +575,18 @@ module Raptor
       socket.close rescue nil
     end
 
+    # Writes a 400 response and closes the socket. Used when the HTTP parser
+    # rejects the request line or headers.
+    #
+    # @param socket [TCPSocket] the client socket
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket) -> void
+    def reject_malformed(socket)
+      socket.write(BAD_REQUEST_RESPONSE) rescue nil
+      socket.close rescue nil
+    end
+
     # Builds a Rack environment hash from parsed HTTP request data.
     #
     # Populates all required Rack env keys including rack.* keys, REMOTE_ADDR,
@@ -529,7 +601,7 @@ module Raptor
     # @return [Hash] fully populated Rack environment hash
     #
     # @rbs (Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, TCPSocket socket, ?remote_addr: String, ?url_scheme: String) -> Hash[String, untyped]
-    def build_rack_env(env, parse_data, body, socket, remote_addr: "127.0.0.1", url_scheme: HTTP_SCHEME)
+    def build_rack_env(env, parse_data, body, socket, remote_addr: Server::DEFAULT_REMOTE_ADDR, url_scheme: Server::HTTP_SCHEME)
       env[Rack::RACK_VERSION] = Rack::VERSION
       env[Rack::RACK_URL_SCHEME] = url_scheme
       env[Rack::RACK_INPUT] = build_rack_input(body)
@@ -569,7 +641,7 @@ module Raptor
         env[Rack::SERVER_NAME] ||= host
         env[Rack::SERVER_PORT] ||= port || @server_port.to_s
       else
-        env[Rack::SERVER_NAME] ||= "localhost"
+        env[Rack::SERVER_NAME] ||= Server::DEFAULT_SERVER_NAME
         env[Rack::SERVER_PORT] ||= @server_port.to_s
       end
 
@@ -644,7 +716,7 @@ module Raptor
       end
       response << "\r\n"
 
-      socket_write(socket, response)
+      Request.socket_write(socket, response)
     end
 
     # Writes a complete HTTP response to the socket.
@@ -777,7 +849,7 @@ module Raptor
     def write_hijacked_response(socket, response, headers, response_hijack)
       response << format_headers(headers)
       response << "\r\n"
-      socket_write(socket, response)
+      Request.socket_write(socket, response)
       uncork_socket(socket)
       response_hijack.call(socket)
     end
@@ -802,7 +874,7 @@ module Raptor
 
       response << format_headers(headers)
       response << "\r\n"
-      socket_write(socket, response)
+      Request.socket_write(socket, response)
     end
 
     # Writes a complete response with a body.
@@ -824,7 +896,7 @@ module Raptor
       if body.respond_to?(:call)
         response << format_headers(headers)
         response << "\r\n"
-        socket_write(socket, response)
+        Request.socket_write(socket, response)
         uncork_socket(socket)
         body.call(socket)
         return
@@ -861,7 +933,7 @@ module Raptor
         raise TypeError, "body must respond to each, to_ary, or to_path"
       end
 
-      socket_write(socket, "0\r\n\r\n") if use_chunked
+      Request.socket_write(socket, "0\r\n\r\n") if use_chunked
     end
 
     # Calculates content length from an array or file body without consuming it.
@@ -901,15 +973,15 @@ module Raptor
     def write_file_body(socket, response, path, content_length, use_chunked)
       File.open(path, "rb") do |file|
         if use_chunked
-          socket_write(socket, response)
+          Request.socket_write(socket, response)
           while (chunk = file.read(FILE_CHUNK_SIZE))
-            socket_write(socket, "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n")
+            Request.socket_write(socket, "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n")
           end
         elsif content_length && content_length < BODY_BUFFER_THRESHOLD
           response << file.read(content_length)
-          socket_write(socket, response)
+          Request.socket_write(socket, response)
         else
-          socket_write(socket, response)
+          Request.socket_write(socket, response)
           IO.copy_stream(file, socket)
         end
       end
@@ -952,12 +1024,12 @@ module Raptor
 
       if use_chunked
         response << "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n"
-        socket_write(socket, response)
+        Request.socket_write(socket, response)
       elsif chunk.bytesize < BODY_BUFFER_THRESHOLD
-        socket_write(socket, response << chunk)
+        Request.socket_write(socket, response << chunk)
       else
-        socket_write(socket, response)
-        socket_write(socket, chunk)
+        Request.socket_write(socket, response)
+        Request.socket_write(socket, chunk)
       end
     end
 
@@ -973,13 +1045,13 @@ module Raptor
     # @rbs (TCPSocket socket, String response, Array[String] body_array, bool use_chunked) -> void
     def write_multiple_chunks(socket, response, body_array, use_chunked)
       if use_chunked
-        socket_write(socket, response)
+        Request.socket_write(socket, response)
         body_array.each do |chunk|
           raise TypeError, "body must yield String values" unless chunk.is_a?(String)
 
           next if chunk.empty?
 
-          socket_write(socket, "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n")
+          Request.socket_write(socket, "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n")
         end
       else
         body_array.each do |chunk|
@@ -987,7 +1059,7 @@ module Raptor
 
           response << chunk
         end
-        socket_write(socket, response)
+        Request.socket_write(socket, response)
       end
     end
 
@@ -1003,13 +1075,13 @@ module Raptor
     # @rbs (TCPSocket socket, String response, untyped body, bool use_chunked) -> void
     def write_enumerable_body(socket, response, body, use_chunked)
       if use_chunked
-        socket_write(socket, response)
+        Request.socket_write(socket, response)
         body.each do |chunk|
           raise TypeError, "body must yield String values" unless chunk.is_a?(String)
 
           next if chunk.empty?
 
-          socket_write(socket, "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n")
+          Request.socket_write(socket, "#{chunk.bytesize.to_s(16)}\r\n#{chunk}\r\n")
         end
       else
         body.each do |chunk|
@@ -1017,7 +1089,7 @@ module Raptor
 
           response << chunk
         end
-        socket_write(socket, response)
+        Request.socket_write(socket, response)
       end
     end
 
@@ -1090,33 +1162,6 @@ module Raptor
       end
     end
 
-    # Writes a string to the socket, retrying on partial writes and flow control blocks.
-    #
-    # Uses write_nonblock with a 5-second writable timeout to avoid blocking the
-    # thread indefinitely on slow clients.
-    #
-    # @param socket [TCPSocket] the socket to write to
-    # @param string [String] the data to write
-    # @return [void]
-    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
-    #
-    # @rbs (TCPSocket socket, String string) -> void
-    def socket_write(socket, string)
-      bytes = 0
-      byte_size = string.bytesize
-
-      while bytes < byte_size
-        begin
-          bytes += socket.write_nonblock(bytes.zero? ? string : string.byteslice(bytes..-1))
-        rescue IO::WaitWritable
-          raise WriteError unless socket.wait_writable(WRITE_TIMEOUT)
-          retry
-        rescue IOError
-          raise WriteError
-        end
-      end
-    end
-
     if Socket.const_defined?(:TCP_CORK)
       # Enables TCP_CORK on the socket to batch outgoing packets into fewer segments.
       #