raptor 0.1.0

data/sig/generated/raptor/http2.rbs

@@ -0,0 +1,145 @@
+# Generated from lib/raptor/http2.rb with RBS::Inline
+
+module Raptor
+  # Handles HTTP/2 request processing and Rack application integration.
+  #
+  # Http2 manages the HTTP/2 protocol lifecycle including frame processing,
+  # HPACK header compression, stream management, and response writing.
+  # It integrates with the same reactor, ractor pool, and thread pool
+  # pipeline used by HTTP/1.1 connections.
+  class Http2
+    FLAG_END_STREAM: ::Integer
+
+    FLAG_END_HEADERS: ::Integer
+
+    FLAG_ACK: ::Integer
+
+    FLAG_PRIORITY: ::Integer
+
+    SERVER_PROTOCOL: ::String
+
+    RACK_HEADER_PREFIX: ::String
+
+    HOP_BY_HOP_HEADERS: untyped
+
+    @server_port: Integer
+
+    @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
+
+    # Creates a new Http2 handler.
+    #
+    # @param app [#call] the Rack application to dispatch requests to
+    # @param server_port [Integer] port number used to populate SERVER_PORT in the Rack env
+    # @return [void]
+    #
+    # @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
+
+    # Builds the initial server SETTINGS frame to send on connection establishment.
+    #
+    # @return [String] the encoded SETTINGS frame
+    #
+    # @rbs () -> String
+    def self.build_server_settings_frame: () -> String
+
+    # Processes HTTP/2 frames from the connection buffer.
+    #
+    # Parses frames, handles HPACK decoding, tracks stream state, and returns
+    # updated connection state along with any outgoing protocol frames and
+    # completed stream requests. Ractor-safe.
+    #
+    # @param data [Hash] the connection state including buffer and HPACK table
+    # @return [Hash] updated state with outgoing_frames and completed_requests
+    #
+    # @rbs (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
+    def self.process_frames: (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
+
+    # Builds a frozen result hash from the current processing state.
+    #
+    # @param data [Hash] original connection state
+    # @param buffer [String] remaining unparsed data
+    # @param hpack_table [Array] updated HPACK dynamic table
+    # @param streams [Hash] updated stream states
+    # @param outgoing_frames [Array<String>] frames to write to the socket
+    # @param completed_requests [Array<Hash>] fully received stream requests
+    # @param connection_window [Integer] current connection flow control window
+    # @param preface_received [Boolean] whether the connection preface has been received
+    # @return [Hash] frozen result hash
+    #
+    # @rbs (Hash[Symbol, untyped] data, String buffer, Array[untyped] hpack_table, Hash[Integer, Hash[Symbol, untyped]] streams, Array[String] outgoing_frames, Array[Hash[Symbol, untyped]] completed_requests, Integer connection_window, bool preface_received) -> Hash[Symbol, untyped]
+    def self.build_result: (Hash[Symbol, untyped] data, String buffer, Array[untyped] hpack_table, Hash[Integer, Hash[Symbol, untyped]] streams, Array[String] outgoing_frames, Array[Hash[Symbol, untyped]] completed_requests, Integer connection_window, bool preface_received) -> Hash[Symbol, untyped]
+
+    # Handles a parsed HTTP/2 request from the ractor pool.
+    #
+    # Writes outgoing protocol frames to the socket, updates reactor state,
+    # and dispatches completed stream requests to the thread pool.
+    #
+    # @param result [Hash] the parsed result from the ractor pool
+    # @param reactor [Reactor] the reactor managing the connection
+    # @param thread_pool [AtomicThreadPool] thread pool for Rack app dispatch
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] result, Reactor reactor, AtomicThreadPool thread_pool) -> void
+    def handle_parsed_request: (Hash[Symbol, untyped] result, Reactor reactor, AtomicThreadPool thread_pool) -> void
+
+    private
+
+    # Dispatches a completed stream request to the Rack app and writes
+    # 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 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
+
+    # 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 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
+
+    # 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 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
+
+    # Builds a Rack environment hash from HTTP/2 headers and body.
+    #
+    # Translates HTTP/2 pseudo-headers into Rack-compatible environment keys
+    # and populates all required Rack env entries.
+    #
+    # @param headers [Array<Array(String, String)>] HTTP/2 header pairs
+    # @param body [String] the request body
+    # @param remote_addr [String] the client IP address
+    # @return [Hash] fully populated Rack environment hash
+    #
+    # @rbs (Array[[String, String]] headers, String body, remote_addr: String) -> Hash[String, untyped]
+    def build_rack_env: (Array[[ String, String ]] headers, String body, remote_addr: String) -> Hash[String, untyped]
+
+    # Populates SERVER_NAME and SERVER_PORT from the HTTP_HOST header.
+    #
+    # @param env [Hash] the Rack environment to populate
+    # @return [void]
+    #
+    # @rbs (Hash[String, untyped] env) -> void
+    def populate_server_name_and_port: (Hash[String, untyped] env) -> void
+  end
+end

data/sig/generated/raptor/reactor.rbs

@@ -0,0 +1,251 @@
+# Generated from lib/raptor/reactor.rb with RBS::Inline
+
+module Raptor
+  # High-performance I/O reactor for managing client connections and timeouts.
+  #
+  # Reactor uses NIO selectors for efficient I/O multiplexing and implements
+  # client timeouts using a red-black tree for O(log n) timeout management.
+  # It coordinates between 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.
+  #
+  # @example
+  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {
+  #     first_data_timeout: 30,
+  #     chunk_data_timeout: 10
+  #   })
+  #   reactor.run
+  #   reactor.add(id: client.object_id, socket: client)
+  #   # ... later
+  #   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.
+    class TimeoutClient < RedBlackTree::Node
+      # @rbs attr_accessor timeout_at: Float
+      attr_accessor timeout_at: untyped
+
+      # Returns the client data stored in this timeout node.
+      #
+      # @return [Hash] the client connection state data
+      #
+      # @rbs () -> Hash[Symbol, untyped]
+      def client_data: () -> Hash[Symbol, untyped]
+
+      # Calculates remaining timeout duration from the current time.
+      #
+      # @param now [Float] current monotonic timestamp
+      # @return [Float] remaining timeout in seconds, minimum 0
+      #
+      # @rbs (Float now) -> Float
+      def timeout: (Float now) -> Float
+
+      # Compares timeout nodes by their timeout_at values for tree ordering.
+      #
+      # @param other [TimeoutClient] another timeout client to compare
+      # @return [Integer] -1, 0, or 1 for ordering
+      #
+      # @rbs (TimeoutClient other) -> Integer
+      def <=>: (TimeoutClient other) -> Integer
+    end
+
+    CHUNK_SIZE: untyped
+
+    TIMEOUT_RESPONSE: ::String
+
+    @id_to_mutex: Hash[Integer, Mutex]
+
+    @id_to_timeout: Hash[Integer, TimeoutClient]
+
+    @socket_to_state: Hash[TCPSocket, Hash[Symbol, untyped]]
+
+    @id_to_socket: Hash[Integer, TCPSocket]
+
+    @timeouts: RedBlackTree[TimeoutClient]
+
+    @queue: Queue[TCPSocket]
+
+    @selector: NIO::Selector
+
+    @client_options: Hash[Symbol, Integer]
+
+    @ractor_pool: untyped
+
+    @thread_pool: 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 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: (untyped thread_pool, untyped ractor_pool, client_options: Hash[Symbol, Integer]) -> void
+
+    # Starts the reactor's main event loop in a new thread.
+    #
+    # The event loop handles I/O events, processes timeouts, manages
+    # the registration queue, and controls server connection acceptance.
+    # It continues until the queue is closed and emptied.
+    #
+    # @return [Thread] the thread running the reactor event loop
+    #
+    # @rbs () -> Thread
+    def run: () -> Thread
+
+    # Adds a new client connection to the reactor.
+    #
+    # @param state [Hash] client connection state including socket and ID
+    # @option state [TCPSocket] :socket the client socket
+    # @option state [Integer] :id unique identifier for the client
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] state) -> void
+    def add: (Hash[Symbol, untyped] state) -> void
+
+    # Updates the state of an existing client connection.
+    #
+    # Called when an incomplete HTTP request needs to be
+    # re-registered with the reactor for further processing.
+    #
+    # @param state [Hash] updated client connection state
+    # @option state [Integer] :id client identifier
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] state) -> void
+    def update_state: (Hash[Symbol, untyped] state) -> void
+
+    # 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.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [TCPSocket, nil] the removed socket, if found
+    #
+    # @rbs (Integer id) -> TCPSocket?
+    def remove: (Integer id) -> TCPSocket?
+
+    # Re-registers a kept-alive connection for the next request cycle.
+    #
+    # Called after successfully writing a response when keep-alive is active.
+    # Resets the connection state and re-queues the socket in the selector
+    # using the persistent data timeout.
+    #
+    # @param socket [TCPSocket] the kept-alive client socket
+    # @param id [Integer] the unique client identifier
+    # @param request_count [Integer] number of requests handled on this connection
+    # @param remote_addr [String] the client's remote IP address
+    # @param url_scheme [String] "http" or "https"
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, Integer id, Integer request_count, remote_addr: String, url_scheme: String) -> void
+    def persist: (TCPSocket socket, Integer id, Integer request_count, remote_addr: String, url_scheme: String) -> void
+
+    # Returns the socket for a given client identifier without removing it.
+    #
+    # Used by HTTP/2 connections where the socket remains registered across
+    # multiple stream requests.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [TCPSocket, nil] the socket, if found
+    #
+    # @rbs (Integer id) -> TCPSocket?
+    def socket_for: (Integer id) -> TCPSocket?
+
+    # Returns the mutex for a given HTTP/2 connection.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [Mutex, nil] the mutex, if found
+    #
+    # @rbs (Integer id) -> Mutex?
+    def mutex_for: (Integer id) -> Mutex?
+
+    # Updates connection state for an HTTP/2 connection after frame processing.
+    #
+    # Re-registers the socket with the selector for further reads and stores
+    # the updated HPACK table and stream states.
+    #
+    # @param state [Hash] updated connection state from the ractor pool
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] state) -> void
+    def update_http2_state: (Hash[Symbol, untyped] state) -> void
+
+    # Initiates reactor shutdown.
+    #
+    # Closes the registration queue and wakes up the selector to begin
+    # graceful shutdown process.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown: () -> void
+
+    # Returns the number of complete requests either being processed
+    # or awaiting processing.
+    #
+    # @return [Integer] number of complete requests
+    #
+    # @rbs () -> Integer
+    def backlog: () -> Integer
+
+    private
+
+    # Registers a socket with the NIO selector and sets up timeout tracking.
+    #
+    # @param socket [TCPSocket] the socket to register
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket) -> void
+    def register: (TCPSocket socket) -> void
+
+    # Handles socket wakeup by deregistering and queuing for processing.
+    #
+    # @param socket [TCPSocket] the socket that became ready
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket) -> void
+    def wakeup!: (TCPSocket socket) -> void
+
+    # Reads data from a socket and either queues it for parsing,
+    # or for selector registration.
+    #
+    # @param socket [TCPSocket] the socket to read from and queue
+    # @param state [Hash] current connection state
+    # @return [Hash, nil] updated state, if successful
+    #
+    # @rbs (TCPSocket socket, Hash[Symbol, untyped] state) -> Hash[Symbol, untyped]?
+    def read_and_queue_for_parse: (TCPSocket socket, Hash[Symbol, untyped] state) -> Hash[Symbol, untyped]?
+
+    # Cleans up a client connection by removing it from tracking and closing the socket.
+    #
+    # @param socket [TCPSocket] the socket to clean up
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket) -> void
+    def cleanup: (TCPSocket socket) -> void
+
+    # Checks if a request is complete i.e., processable.
+    #
+    # @param state [Hash] connection state
+    # @return [Boolean] true if the request is complete
+    #
+    # @rbs (Hash[Symbol, untyped] state) -> bool
+    def complete?: (Hash[Symbol, untyped] state) -> bool
+
+    # Checks if any data has been received for this connection.
+    #
+    # @param state [Hash] connection state
+    # @return [Boolean] true if first data has been received
+    #
+    # @rbs (Hash[Symbol, untyped] state) -> bool
+    def first_data_received?: (Hash[Symbol, untyped] state) -> bool
+  end
+end