raptor 0.22.3 → 0.24.0

data/sig/generated/raptor/plugin.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/raptor/plugin.rb with RBS::Inline
+
+module Raptor
+  # An extension, loaded from `raptor/plugin/<name>` or
+  # registered explicitly by application code.
+  class Plugin
+    class UnknownPlugin < LoadError
+    end
+
+    self.@registry: Hash[String, singleton(Plugin)]
+
+    # Registers a plugin class under a name.
+    #
+    # @rbs (String | Symbol name, singleton(Plugin) plugin) -> void
+    def self.register: (String | Symbol name, singleton(Plugin) plugin) -> void
+
+    # Defines and registers a plugin without a named subclass.
+    #
+    # @rbs (String | Symbol name) { () -> void } -> singleton(Plugin)
+    def self.create: (String | Symbol name) { () -> void } -> singleton(Plugin)
+
+    # Loads a registered plugin, requiring its conventional path if needed.
+    #
+    # @rbs (String | Symbol name) -> Plugin
+    def self.load: (String | Symbol name) -> Plugin
+
+    @threads: Array[Thread]?
+
+    # Starts in the master before workers fork. Override to open resources
+    # and append callbacks to the cluster's lifecycle hook arrays.
+    #
+    # @rbs (Cluster cluster) -> void
+    def start: (Cluster cluster) -> void
+
+    # Stops in the master after workers exit, including before hot restart.
+    # Also called if startup fails, so resources may be only partly opened.
+    #
+    # @rbs () -> void
+    def stop: () -> void
+
+    # Runs a block on a master-owned thread. Raptor stops and joins these
+    # threads after calling `stop`; use `ensure` in the block for cleanup.
+    #
+    # @rbs () { () -> void } -> Thread
+    def in_background: () { () -> void } -> Thread
+
+    # Calls the plugin's stop callback and joins its background threads.
+    #
+    # @rbs () -> void
+    def shutdown: () -> void
+  end
+end

data/sig/generated/raptor/reactor.rbs

@@ -5,11 +5,20 @@ module Raptor
   # ready bytes to the parser pipeline, and hands completed requests back
   # to the caller-provided handlers.
   class Reactor
+    CHUNK_SIZE: untyped
+
+    DETACHED_CONNECTION_BUFFER_SIZE: untyped
+
+    DETACHED_WRITE_BATCH: ::Integer
+
+    DETACHED_WORKER_BUFFER_SIZE: untyped
+
+    TIMEOUT_RESPONSE: ::String
+
     # 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: untyped
+      attr_accessor timeout_at: Float
 
       # Returns the client connection state.
       #
@@ -39,26 +48,19 @@ module Raptor
 
     # Tracks reactor-owned output state for a connection.
     class ConnectionIO
-      # @rbs attr_accessor offset: Integer
-      attr_accessor offset: untyped
+      attr_accessor offset: Integer
 
-      # @rbs attr_accessor wait: Symbol?
-      attr_accessor wait: untyped
+      attr_accessor wait: Symbol?
 
-      # @rbs attr_accessor reading: bool
-      attr_accessor reading: untyped
+      attr_accessor reading: bool
 
-      # @rbs attr_accessor closing: bool
-      attr_accessor closing: untyped
+      attr_accessor closing: bool
 
-      # @rbs attr_accessor monitor: NIO::Monitor?
-      attr_accessor monitor: untyped
+      attr_accessor monitor: NIO::Monitor?
 
-      # @rbs attr_accessor timeout: TimeoutClient?
-      attr_accessor timeout: untyped
+      attr_accessor timeout: TimeoutClient?
 
-      # @rbs attr_reader output: Array[String]
-      attr_reader output: untyped
+      attr_reader output: Array[String]
 
       # Creates empty connection I/O state for reactor-owned writes.
       #
@@ -77,25 +79,20 @@ module Raptor
 
     # Tracks reactor-owned I/O state for an HTTP/1.x detached response.
     class Http1IO < ConnectionIO
-      # @rbs attr_accessor body: DetachedBody?
-      attr_accessor body: untyped
+      attr_accessor body: DetachedBody?
 
-      # @rbs attr_accessor finishing: bool
-      attr_accessor finishing: untyped
+      attr_accessor finishing: bool
 
-      # @rbs attr_reader budget: DetachedBody::Budget
-      attr_reader budget: untyped
+      attr_reader budget: DetachedBody::Budget
 
-      # @rbs attr_reader input: String
-      attr_reader input: untyped
+      attr_reader input: String
 
-      # @rbs attr_reader state: Hash[Symbol, untyped]
-      attr_reader state: untyped
+      attr_reader state: Hash[Symbol, untyped]
 
       # Creates I/O state for an HTTP/1.x detached response.
       #
       # @param body [DetachedBody] the response body
-      # @param state [Hash] connection state restored after the response finishes
+      # @param state [Hash] connection state restored after the response finishes, including bytes the client pipelined after the request
       # @return [void]
       #
       # @rbs (DetachedBody body, Hash[Symbol, untyped] state) -> void
@@ -111,17 +108,13 @@ module Raptor
 
     # Tracks reactor-owned I/O state for an HTTP/2 connection.
     class Http2IO < ConnectionIO
-      # @rbs attr_reader detached: Hash[Integer, DetachedBody]
-      attr_reader detached: untyped
+      attr_reader detached: Hash[Integer, DetachedBody]
 
-      # @rbs attr_reader ready: Array[Integer]
-      attr_reader ready: untyped
+      attr_reader ready: Array[Integer]
 
-      # @rbs attr_reader ready_streams: Hash[Integer, bool]
-      attr_reader ready_streams: untyped
+      attr_reader ready_streams: Hash[Integer, bool]
 
-      # @rbs attr_reader budget: DetachedBody::Budget
-      attr_reader budget: untyped
+      attr_reader budget: DetachedBody::Budget
 
       # Creates empty I/O state for an HTTP/2 connection and its detached streams.
       #
@@ -138,18 +131,6 @@ module Raptor
       def empty?: () -> bool
     end
 
-    CHUNK_SIZE: untyped
-
-    DETACHED_CONNECTION_BUFFER_SIZE: untyped
-
-    DETACHED_WRITE_BATCH: ::Integer
-
-    DETACHED_WORKER_BUFFER_SIZE: untyped
-
-    TIMEOUT_RESPONSE: ::String
-
-    @timeouts: RedBlackTree[TimeoutClient]
-
     @io_applied: AtomicConditionVariable
 
     @io_queue: AtomicQueue
@@ -162,19 +143,23 @@ module Raptor
 
     @http2_keepalive_interval: Integer
 
-    @write_timeout: Integer
-
     @persistent_data_timeout: Integer
 
+    @write_timeout: Integer
+
     @chunk_data_timeout: Integer
 
     @first_data_timeout: Integer
 
-    @http2_ractor_pool: untyped
+    @thread_pool: AtomicThreadPool
 
-    @http1_ractor_pool: untyped
+    @http2_ractor_pool: RactorPool?
 
-    @thread_pool: untyped
+    @http1_ractor_pool: RactorPool
+
+    @http1: Http1
+
+    @timeouts: RedBlackTree[TimeoutClient]
 
     @id_to_socket: Hash[Integer, TCPSocket]
 
@@ -182,9 +167,9 @@ module Raptor
 
     @id_to_timeout: Hash[Integer, TimeoutClient]
 
-    @id_to_writer: Hash[Integer, untyped]
+    @id_to_writer: Hash[Integer, Http2::Writer]
 
-    @id_to_flow_control: Hash[Integer, untyped]
+    @id_to_flow_control: Hash[Integer, Http2::FlowControl]
 
     @id_to_http2_last_stream: Hash[Integer, Integer]
 
@@ -202,8 +187,9 @@ module Raptor
 
     @thread: Thread?
 
-    # Creates a new Reactor instance.
+    # Creates a new Reactor.
     #
+    # @param http1 [Http1] the HTTP/1.1 handler that resumes idle keep-alive connections
     # @param http1_ractor_pool [RactorPool] ractor pool for HTTP/1.x parsing
     # @param http2_ractor_pool [RactorPool, nil] ractor pool for HTTP/2 parsing, or nil when no listener supports HTTP/2
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
@@ -218,8 +204,8 @@ module Raptor
     # @option http2_options [Integer] :keepalive_timeout time to await a PING acknowledgement
     # @return [void]
     #
-    # @rbs (untyped http1_ractor_pool, untyped http2_ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
-    def initialize: (untyped http1_ractor_pool, untyped http2_ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
+    # @rbs (Http1 http1, RactorPool http1_ractor_pool, RactorPool? http2_ractor_pool, AtomicThreadPool thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
+    def initialize: (Http1 http1, RactorPool http1_ractor_pool, RactorPool? http2_ractor_pool, AtomicThreadPool thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped], http2_options: Hash[Symbol, untyped]) -> void
 
     # Starts the reactor's main event loop in a new thread. Runs until
     # shutdown work and pending writes are drained.
@@ -233,7 +219,7 @@ module Raptor
     #
     # @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
+    # @option state [Integer] :id unique connection identifier
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] state) -> void
@@ -243,7 +229,7 @@ module Raptor
     # it for further I/O.
     #
     # @param state [Hash] updated client connection state
-    # @option state [Integer] :id client identifier
+    # @option state [Integer] :id unique connection identifier
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] state) -> void
@@ -253,7 +239,7 @@ module Raptor
     # 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
+    # @param id [Integer] unique connection identifier
     # @return [TCPSocket, nil] the socket associated with `id`, if any
     #
     # @rbs (Integer id) -> TCPSocket?
@@ -263,45 +249,45 @@ module Raptor
     # under the persistent-data timeout.
     #
     # @param socket [TCPSocket] the kept-alive client socket
-    # @param id [Integer] the unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param request_count [Integer] number of requests handled on this connection
-    # @param remote_addr [String] the client's remote IP address
+    # @param remote_addr [String] the client 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.
+    # Returns the socket for a given connection identifier without removing it.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [TCPSocket, nil] the socket, if found
     #
     # @rbs (Integer id) -> TCPSocket?
     def socket_for: (Integer id) -> TCPSocket?
 
-    # Returns the writer object associated with a given connection, if one
-    # was supplied when the connection was added.
+    # Returns the HTTP/2 frame writer registered by {attach_http2} for a
+    # connection.
     #
-    # @param id [Integer] unique client identifier
-    # @return [Object, nil] the writer, if found
+    # @param id [Integer] unique connection identifier
+    # @return [Http2::Writer, nil] the writer, if found
     #
-    # @rbs (Integer id) -> untyped?
-    def writer_for: (Integer id) -> untyped?
+    # @rbs (Integer id) -> Http2::Writer?
+    def writer_for: (Integer id) -> Http2::Writer?
 
-    # Returns the flow controller associated with a given connection, if
-    # one was supplied when the connection was added.
+    # Returns the HTTP/2 flow controller registered by {attach_http2} for a
+    # connection.
     #
-    # @param id [Integer] unique client identifier
-    # @return [Object, nil] the flow controller, if found
+    # @param id [Integer] unique connection identifier
+    # @return [Http2::FlowControl, nil] the flow controller, if found
     #
-    # @rbs (Integer id) -> untyped?
-    def flow_control_for: (Integer id) -> untyped?
+    # @rbs (Integer id) -> Http2::FlowControl?
+    def flow_control_for: (Integer id) -> Http2::FlowControl?
 
     # Attaches a detached response body to an HTTP/1.x connection.
     #
     # @param socket [TCPSocket] the client socket
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param body [DetachedBody] the response body
     # @param state [Hash] connection state restored once the response finishes
     # @param finished [Proc] called with the close reason
@@ -314,7 +300,7 @@ module Raptor
     # that arrived after graceful draining began.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [Boolean] whether the stream may be dispatched
     #
     # @rbs (Integer id, Integer stream_id) -> bool
@@ -323,7 +309,8 @@ module Raptor
     # Sends GOAWAY on every HTTP/2 connection and fixes the last stream each
     # connection may dispatch while existing application work drains.
     #
-    # @yieldparam stream_id [Integer] last dispatched stream identifier
+    # @yield for each HTTP/2 connection
+    # @yieldparam stream_id [Integer] the last dispatched HTTP/2 stream identifier
     # @yieldreturn [String] serialized GOAWAY frame
     # @return [void]
     #
@@ -343,7 +330,7 @@ module Raptor
     # Attaches a detached response body to an HTTP/2 stream.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param 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 body was attached
@@ -362,7 +349,7 @@ module Raptor
     # Cancels a detached response stream.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
     # @rbs (Integer id, Integer stream_id) -> void
@@ -380,17 +367,17 @@ module Raptor
     # Stores an HTTP/2 connection's socket, state, writer, and flow
     # controller in the reactor's per-connection maps.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param socket [TCPSocket] the connection socket
     # @param state [Hash] initial connection state
-    # @param writer [Http2::Writer] per-connection frame writer
+    # @param writer [Http2::Writer] frame writer for the connection
     # @param flow_control [Http2::FlowControl] per-connection outbound flow controller
     # @param ping_frame [String] serialized PING frame for keepalive probes
     # @param ping_payload [String] payload expected in the corresponding acknowledgement
     # @return [void]
     #
-    # @rbs (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped, ping_frame: String, ping_payload: String) -> void
-    def attach_http2: (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped, ping_frame: String, ping_payload: String) -> void
+    # @rbs (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: Http2::Writer, flow_control: Http2::FlowControl, ping_frame: String, ping_payload: String) -> void
+    def attach_http2: (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: Http2::Writer, flow_control: Http2::FlowControl, ping_frame: String, ping_payload: String) -> void
 
     # Records acknowledgements for server keepalive probes.
     #
@@ -403,24 +390,15 @@ module Raptor
 
     # Registers an attached socket for future reactor-driven reads.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
     def watch: (Integer id) -> void
 
-    # Updates connection state for an HTTP/2 connection and re-registers
-    # the socket for further reads.
-    #
-    # @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
-
     # Closes a connection after writing any frames already queued for it.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
@@ -469,7 +447,7 @@ module Raptor
     # Adds a detached body to an HTTP/1.x connection.
     #
     # @param socket [TCPSocket] the client socket
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param body [DetachedBody] the response body
     # @param state [Hash] connection state restored once the response finishes
     # @param finished [Proc] called with the close reason
@@ -480,7 +458,7 @@ module Raptor
 
     # Writes buffered HTTP/1.x body chunks without blocking.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
@@ -488,7 +466,7 @@ module Raptor
 
     # Finishes an HTTP/1.x detached response and either reuses or closes its connection.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param io [Http1IO] connection I/O state
     # @return [void]
     #
@@ -497,7 +475,7 @@ module Raptor
 
     # Cancels an HTTP/1.x detached response and closes its connection.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @param reason [Symbol] why the response closed
     # @return [void]
     #
@@ -507,7 +485,7 @@ module Raptor
     # Adds a detached body to an HTTP/2 stream.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param body [DetachedBody] the response body
     # @param finished [Proc] called with the close reason
     # @return [void]
@@ -518,7 +496,7 @@ module Raptor
     # Marks an HTTP/2 detached stream eligible for fair scheduling.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @return [void]
     #
     # @rbs (Integer id, Integer stream_id) -> void
@@ -543,7 +521,7 @@ module Raptor
     # Finishes an HTTP/2 detached stream with DATA or trailing HEADERS.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param body [DetachedBody] the response body
     # @return [void]
     #
@@ -553,7 +531,7 @@ module Raptor
     # Removes an HTTP/2 detached stream and schedules its close callback.
     #
     # @param id [Integer] unique connection identifier
-    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @param reason [Symbol] why the stream closed
     # @return [void]
     #
@@ -576,7 +554,7 @@ module Raptor
 
     # Closes a connection once its queued frames are written.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
@@ -584,15 +562,15 @@ module Raptor
 
     # Immediately closes a connection and drops its reactor state.
     #
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (Integer id) -> void
     def remove_connection: (Integer id) -> void
 
-    # Adds bytes to one connection and writes as much as the socket accepts.
+    # Appends bytes to one connection's pending output.
     #
-    # @param io [ConnectionIO] connection I/O state
+    # @param io [ConnectionIO, nil] connection I/O state
     # @param data [String] serialized response bytes
     # @return [void]
     #
@@ -602,7 +580,7 @@ module Raptor
     # Drains one connection's queued response bytes without blocking.
     #
     # @param id [Integer] unique connection identifier
-    # @param io [ConnectionIO] connection I/O state
+    # @param io [ConnectionIO, nil] connection I/O state
     # @return [void]
     #
     # @rbs (Integer id, ConnectionIO? io) -> void
@@ -692,13 +670,14 @@ module Raptor
     # Handles readiness for an HTTP/1.x detached response.
     #
     # @param monitor [NIO::Monitor] ready selector monitor
-    # @param id [Integer] unique client identifier
+    # @param id [Integer] unique connection identifier
     # @return [void]
     #
     # @rbs (NIO::Monitor monitor, Integer id) -> void
     def handle_http1_detached_monitor: (NIO::Monitor monitor, Integer id) -> void
 
-    # Handles socket wakeup by deregistering and queuing for processing.
+    # Deregisters a readable socket and resumes its idle keep-alive
+    # connection or queues its bytes for parsing.
     #
     # @param socket [TCPSocket] the socket that became ready
     # @return [void]
@@ -706,15 +685,25 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def wakeup!: (TCPSocket socket) -> void
 
+    # Resumes a readable keep-alive connection on an application thread,
+    # avoiding a Ractor round trip for complete requests.
+    #
+    # @param socket [TCPSocket] the readable client socket
+    # @param state [Hash] current connection state
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, Hash[Symbol, untyped] state) -> void
+    def resume_keepalive: (TCPSocket socket, Hash[Symbol, untyped] state) -> void
+
     # Reads data from a socket and either queues it for parsing or
     # returns it to the selector.
     #
     # @param socket [TCPSocket] the socket to read from and queue
     # @param state [Hash] current connection state
-    # @return [Hash, nil] updated state, if successful
+    # @return [void]
     #
-    # @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]?
+    # @rbs (TCPSocket socket, Hash[Symbol, untyped] state) -> void
+    def read_and_queue_for_parse: (TCPSocket socket, Hash[Symbol, untyped] state) -> void
 
     # Cleans up a client connection by removing it from tracking and closing the socket.
     #
@@ -724,18 +713,18 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def cleanup: (TCPSocket socket) -> void
 
-    # Returns true when the request has been fully parsed.
+    # Returns whether the request has been fully parsed.
     #
     # @param state [Hash] connection state
-    # @return [Boolean] true if the request is complete
+    # @return [Boolean]
     #
     # @rbs (Hash[Symbol, untyped] state) -> bool
     def complete?: (Hash[Symbol, untyped] state) -> bool
 
-    # Checks if any data has been received for this connection.
+    # Returns whether any data has been received for this connection.
     #
     # @param state [Hash] connection state
-    # @return [Boolean] true if first data has been received
+    # @return [Boolean]
     #
     # @rbs (Hash[Symbol, untyped] state) -> bool
     def first_data_received?: (Hash[Symbol, untyped] state) -> bool