raptor 0.20.2 → 0.22.0

data/sig/generated/raptor/reactor.rbs

@@ -1,10 +1,9 @@
 # Generated from lib/raptor/reactor.rb with RBS::Inline
 
 module Raptor
-  # Multiplexes client connections and closes them when they overrun
-  # their per-phase timeouts (first data, subsequent chunks, and
-  # keep-alive idle). Feeds ready bytes to the parser pipeline and hands
-  # completed requests back to the caller-provided handlers.
+  # Multiplexes client connections, manages connection deadlines, feeds
+  # ready bytes to the parser pipeline, and hands completed requests back
+  # to the caller-provided handlers.
   class Reactor
     # A client connection node ordered by absolute expiry time so the
     # soonest-to-expire is always at the tree's minimum.
@@ -38,27 +37,118 @@ module Raptor
       def <=>: (TimeoutClient other) -> Integer
     end
 
+    # Tracks reactor-owned output state for a connection.
+    class ConnectionIO
+      # @rbs attr_accessor offset: Integer
+      attr_accessor offset: untyped
+
+      # @rbs attr_accessor wait: Symbol?
+      attr_accessor wait: untyped
+
+      # @rbs attr_accessor reading: bool
+      attr_accessor reading: untyped
+
+      # @rbs attr_accessor closing: bool
+      attr_accessor closing: untyped
+
+      # @rbs attr_accessor monitor: NIO::Monitor?
+      attr_accessor monitor: untyped
+
+      # @rbs attr_accessor timeout: TimeoutClient?
+      attr_accessor timeout: untyped
+
+      # @rbs attr_reader output: Array[String]
+      attr_reader output: untyped
+
+      # @rbs () -> void
+      def initialize: () -> void
+
+      # @rbs () -> bool
+      def empty?: () -> bool
+    end
+
+    # 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
+
+      # @rbs attr_accessor finishing: bool
+      attr_accessor finishing: untyped
+
+      # @rbs attr_reader budget: DetachedBody::Budget
+      attr_reader budget: untyped
+
+      # @rbs attr_reader input: String
+      attr_reader input: untyped
+
+      # @rbs attr_reader state: Hash[Symbol, untyped]
+      attr_reader state: untyped
+
+      # @rbs (DetachedBody body, Hash[Symbol, untyped] state) -> void
+      def initialize: (DetachedBody body, Hash[Symbol, untyped] state) -> void
+
+      # @rbs () -> bool
+      def empty?: () -> bool
+    end
+
+    # 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
+
+      # @rbs attr_reader ready: Array[Integer]
+      attr_reader ready: untyped
+
+      # @rbs attr_reader ready_streams: Hash[Integer, bool]
+      attr_reader ready_streams: untyped
+
+      # @rbs attr_reader budget: DetachedBody::Budget
+      attr_reader budget: untyped
+
+      # @rbs () -> void
+      def initialize: () -> void
+
+      # @rbs () -> bool
+      def empty?: () -> bool
+    end
+
     CHUNK_SIZE: untyped
 
+    DETACHED_CONNECTION_BUFFER_SIZE: untyped
+
+    DETACHED_MAX_CHUNKS: ::Integer
+
+    DETACHED_MAX_FRAMES: ::Integer
+
+    DETACHED_WORKER_BUFFER_SIZE: untyped
+
     TIMEOUT_RESPONSE: ::String
 
-    @thread_pool: untyped
+    @timeouts: RedBlackTree[TimeoutClient]
 
-    @http1_ractor_pool: untyped
+    @io_queue: AtomicQueue
 
-    @http2_ractor_pool: untyped
+    @queue: Queue[TCPSocket]
 
-    @first_data_timeout: Integer
+    @selector: NIO::Selector
 
-    @chunk_data_timeout: Integer
+    @http2_keepalive_timeout: Integer
+
+    @http2_keepalive_interval: Integer
+
+    @write_timeout: Integer
 
     @persistent_data_timeout: Integer
 
-    @selector: NIO::Selector
+    @chunk_data_timeout: Integer
 
-    @queue: Queue[TCPSocket]
+    @first_data_timeout: Integer
 
-    @timeouts: RedBlackTree[TimeoutClient]
+    @http2_ractor_pool: untyped
+
+    @http1_ractor_pool: untyped
+
+    @thread_pool: untyped
 
     @id_to_socket: Hash[Integer, TCPSocket]
 
@@ -70,6 +160,22 @@ module Raptor
 
     @id_to_flow_control: Hash[Integer, untyped]
 
+    @id_to_http2_last_stream: Hash[Integer, Integer]
+
+    @id_to_http2_drain_stream: Hash[Integer, Integer]
+
+    @id_to_http2_keepalive: Hash[Integer, Hash[Symbol, untyped]]
+
+    @id_to_io: Hash[Integer, ConnectionIO]
+
+    @detached_budget: DetachedBody::Budget
+
+    @detached_count: Atom
+
+    @detached_drained: AtomicConditionVariable
+
+    @thread: Thread?
+
     # Creates a new Reactor instance.
     #
     # @param http1_ractor_pool [RactorPool] ractor pool for HTTP/1.x parsing
@@ -80,13 +186,16 @@ module Raptor
     # @option connection_options [Integer] :chunk_data_timeout timeout for subsequent chunks
     # @param http1_options [Hash] HTTP/1.1-specific configuration
     # @option http1_options [Integer] :persistent_data_timeout timeout for keep-alive idle connections
+    # @param http2_options [Hash] HTTP/2-specific configuration
+    # @option http2_options [Integer] :keepalive_interval idle time before sending a PING
+    # @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]) -> void
-    def initialize: (untyped http1_ractor_pool, untyped http2_ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> 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
 
     # Starts the reactor's main event loop in a new thread. Runs until
-    # the registration queue is closed and drained.
+    # shutdown work and pending writes are drained.
     #
     # @return [Thread] the thread running the reactor event loop
     #
@@ -162,6 +271,62 @@ module Raptor
     # @rbs (Integer id) -> untyped?
     def flow_control_for: (Integer id) -> untyped?
 
+    # Attaches a detached response body to an HTTP/1.x connection.
+    #
+    # @rbs (TCPSocket socket, Integer id, DetachedBody body, Hash[Symbol, untyped] state, ^(Symbol) -> void finished) -> bool
+    def attach_http1_body: (TCPSocket socket, Integer id, DetachedBody body, Hash[Symbol, untyped] state, ^(Symbol) -> void finished) -> bool
+
+    # Records an HTTP/2 stream before application dispatch, rejecting streams
+    # that arrived after graceful draining began.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @return [Boolean] whether the stream may be dispatched
+    #
+    # @rbs (Integer id, Integer stream_id) -> bool
+    def dispatch_http2_stream: (Integer id, Integer stream_id) -> bool
+
+    # 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
+    # @yieldreturn [String] serialized GOAWAY frame
+    # @return [void]
+    #
+    # @rbs () { (Integer stream_id) -> String } -> void
+    def drain_http2: () { (Integer stream_id) -> String } -> void
+
+    # Queues serialized HTTP/2 frames for a connection. Producers never
+    # write to the socket or wait for it to become writable.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param frames [Array<String>] frame bytes to write in order
+    # @return [void]
+    #
+    # @rbs (Integer id, Array[String] frames) -> void
+    def write_http2_frames: (Integer id, Array[String] frames) -> void
+
+    # Attaches a detached response body to an HTTP/2 stream.
+    #
+    # @rbs (Integer id, Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
+    def attach_http2_body: (Integer id, Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
+
+    # Reconsiders detached streams after an outbound window update.
+    #
+    # @rbs (Integer id) -> void
+    def resume_http2_bodies: (Integer id) -> void
+
+    # Cancels a detached response stream.
+    #
+    # @rbs (Integer id, Integer stream_id) -> void
+    def cancel_http2_body: (Integer id, Integer stream_id) -> void
+
+    # Waits for detached responses to finish, then cancels any that outlive
+    # the worker drain period.
+    #
+    # @rbs (Numeric timeout) -> void
+    def drain_detached_bodies: (Numeric timeout) -> void
+
     # Stores an HTTP/2 connection's socket, state, writer, and flow
     # controller in the reactor's per-connection maps.
     #
@@ -170,10 +335,21 @@ module Raptor
     # @param state [Hash] initial connection state
     # @param writer [Http2::Writer] per-connection frame writer
     # @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
+
+    # Records acknowledgements for server keepalive probes.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param payloads [Array<String>, nil] acknowledged PING payloads
     # @return [void]
     #
-    # @rbs (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped) -> void
-    def attach_http2: (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped) -> void
+    # @rbs (Integer id, Array[String]? payloads) -> void
+    def acknowledge_http2_ping: (Integer id, Array[String]? payloads) -> void
 
     # Registers an attached socket for future reactor-driven reads.
     #
@@ -192,8 +368,7 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] state) -> void
     def update_http2_state: (Hash[Symbol, untyped] state) -> void
 
-    # Closes the socket for the given connection and drops all reactor
-    # state associated with it.
+    # Closes a connection after writing any frames already queued for it.
     #
     # @param id [Integer] unique client identifier
     # @return [void]
@@ -219,6 +394,167 @@ module Raptor
 
     private
 
+    # Returns whether shutdown has no registrations or writes left to drain.
+    #
+    # @return [Boolean]
+    #
+    # @rbs () -> bool
+    def stopped?: () -> bool
+
+    # Handles every expired connection deadline in order.
+    #
+    # @param now [Float] current monotonic timestamp
+    # @return [void]
+    #
+    # @rbs (Float now) -> void
+    def expire_timeouts: (Float now) -> void
+
+    # Applies queued reactor-owned I/O operations.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def drain_io_queue: () -> void
+
+    # Adds a detached body to an HTTP/1.x connection.
+    #
+    # @rbs (TCPSocket socket, Integer id, DetachedBody body, Hash[Symbol, untyped] state, ^(Symbol) -> void finished) -> void
+    def attach_http1_detached_body: (TCPSocket socket, Integer id, DetachedBody body, Hash[Symbol, untyped] state, ^(Symbol) -> void finished) -> void
+
+    # Writes buffered HTTP/1.x body chunks without blocking.
+    #
+    # @rbs (Integer id) -> void
+    def flush_http1_detached_body: (Integer id) -> void
+
+    # Finishes an HTTP/1.x detached response and either reuses or closes its connection.
+    #
+    # @rbs (Integer id, Http1IO io) -> void
+    def finish_http1_detached_body: (Integer id, Http1IO io) -> void
+
+    # Cancels an HTTP/1.x detached response and closes its connection.
+    #
+    # @rbs (Integer id, Symbol reason) -> void
+    def remove_http1_detached_body: (Integer id, Symbol reason) -> void
+
+    # Adds a detached body to an HTTP/2 stream.
+    #
+    # @rbs (Integer id, Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> void
+    def attach_http2_detached_body: (Integer id, Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> void
+
+    # Marks an HTTP/2 detached stream eligible for fair scheduling.
+    #
+    # @rbs (Integer id, Integer stream_id) -> void
+    def mark_http2_detached_body_ready: (Integer id, Integer stream_id) -> void
+
+    # Marks every HTTP/2 detached stream eligible after flow-control capacity changes.
+    #
+    # @rbs (Integer id) -> void
+    def resume_http2_detached_bodies: (Integer id) -> void
+
+    # Writes HTTP/2 detached streams in round-robin order without waiting for flow control.
+    #
+    # @rbs (Integer id) -> void
+    def flush_http2_detached_bodies: (Integer id) -> void
+
+    # Finishes an HTTP/2 detached stream with DATA or trailing HEADERS.
+    #
+    # @rbs (Integer id, Integer stream_id, DetachedBody body) -> void
+    def finish_http2_detached_body: (Integer id, Integer stream_id, DetachedBody body) -> void
+
+    # Removes an HTTP/2 detached stream and schedules its close callback.
+    #
+    # @rbs (Integer id, Integer stream_id, Symbol reason) -> void
+    def remove_http2_detached_body: (Integer id, Integer stream_id, Symbol reason) -> void
+
+    # Cancels every detached response during worker shutdown.
+    #
+    # @rbs () -> void
+    def cancel_detached_bodies: () -> void
+
+    # Records one detached stream finishing.
+    #
+    # @rbs () -> void
+    def detached_body_removed: () -> void
+
+    # Closes a connection once its queued frames are written.
+    #
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
+    # @rbs (Integer id) -> void
+    def close_after_writes: (Integer id) -> void
+
+    # Immediately closes a connection and drops its reactor state.
+    #
+    # @param id [Integer] unique client 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.
+    #
+    # @param io [ConnectionIO] connection I/O state
+    # @param data [String] serialized response bytes
+    # @return [void]
+    #
+    # @rbs (ConnectionIO? io, String data) -> void
+    def queue_output: (ConnectionIO? io, String data) -> void
+
+    # Drains one connection's queued response bytes without blocking.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param io [ConnectionIO] connection I/O state
+    # @return [void]
+    #
+    # @rbs (Integer id, ConnectionIO? io) -> void
+    def flush_output: (Integer id, ConnectionIO? io) -> void
+
+    # Registers the readiness needed to continue a partial socket write.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param io [ConnectionIO] connection I/O state
+    # @param readiness [Symbol] `:read` or `:write`
+    # @return [void]
+    #
+    # @rbs (Integer id, ConnectionIO io, Symbol readiness) -> void
+    def wait_for_write: (Integer id, ConnectionIO io, Symbol readiness) -> void
+
+    # Updates selector interest for one reactor-owned connection.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param io [ConnectionIO] connection I/O state
+    # @return [void]
+    #
+    # @rbs (Integer id, ConnectionIO io) -> void
+    def update_monitor: (Integer id, ConnectionIO io) -> void
+
+    # Starts or refreshes one connection's non-blocking write deadline.
+    #
+    # @param id [Integer] unique connection identifier
+    # @param io [ConnectionIO] connection I/O state
+    # @return [void]
+    #
+    # @rbs (Integer id, ConnectionIO io) -> void
+    def track_write_timeout: (Integer id, ConnectionIO io) -> void
+
+    # Removes one connection's non-blocking write deadline.
+    #
+    # @param io [ConnectionIO, nil] connection I/O state
+    # @return [void]
+    #
+    # @rbs (ConnectionIO? io) -> void
+    def clear_write_timeout: (ConnectionIO? io) -> void
+
+    # Removes a socket from selector tracking.
+    #
+    # @param socket [TCPSocket] socket to deregister
+    # @param io [ConnectionIO, nil] connection I/O state
+    # @return [void]
+    #
+    # @rbs (TCPSocket socket, ConnectionIO? io) -> void
+    def deregister: (TCPSocket socket, ConnectionIO? io) -> void
+
     # Registers a socket with the NIO selector and sets up timeout tracking.
     #
     # @param socket [TCPSocket] the socket to register
@@ -227,6 +563,39 @@ module Raptor
     # @rbs (TCPSocket socket) -> void
     def register: (TCPSocket socket) -> void
 
+    # Adds a connection deadline to the timeout tree.
+    #
+    # @param state [Hash] client connection state
+    # @param timeout_at [Float] absolute monotonic expiry time
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] state, Float timeout_at) -> void
+    def track_timeout: (Hash[Symbol, untyped] state, Float timeout_at) -> void
+
+    # Handles an expired connection deadline, sending an HTTP/2 keepalive
+    # probe before closing the connection when its acknowledgement is late.
+    #
+    # @param client [TimeoutClient] expired client
+    # @param now [Float] current monotonic timestamp
+    # @return [void]
+    #
+    # @rbs (TimeoutClient client, Float now) -> void
+    def handle_timeout: (TimeoutClient client, Float now) -> void
+
+    # Dispatches readable and writable events without allowing application
+    # threads to take ownership of HTTP/2 sockets.
+    #
+    # @param monitor [NIO::Monitor] ready selector monitor
+    # @return [void]
+    #
+    # @rbs (NIO::Monitor monitor) -> void
+    def handle_monitor: (NIO::Monitor monitor) -> void
+
+    # Handles readiness for an HTTP/1.x detached response.
+    #
+    # @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.
     #
     # @param socket [TCPSocket] the socket that became ready

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.22.0
 platform: ruby
 authors:
 - Joshua Young
@@ -158,6 +158,7 @@ files:
 - lib/raptor/cli.rb
 - lib/raptor/cluster.rb
 - lib/raptor/control_server.rb
+- lib/raptor/detached_body.rb
 - lib/raptor/http.rb
 - lib/raptor/http1.rb
 - lib/raptor/http2.rb
@@ -175,6 +176,7 @@ files:
 - sig/generated/raptor/cli.rbs
 - sig/generated/raptor/cluster.rbs
 - sig/generated/raptor/control_server.rbs
+- sig/generated/raptor/detached_body.rbs
 - sig/generated/raptor/http.rbs
 - sig/generated/raptor/http1.rbs
 - sig/generated/raptor/http2.rbs
@@ -206,7 +208,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: "A high-performance Ruby web server (rawr \U0001F996)"
 test_files: []