raptor 0.20.2 → 0.22.0

data/sig/generated/raptor/http2.rbs

@@ -3,12 +3,14 @@
 module Raptor
   # Handles HTTP/2 request processing and Rack application integration.
   class Http2
-    # Serialises concurrent frame writes on a single HTTP/2 connection so
-    # exactly one thread is writing at any moment.
+    RESPONSE_TRAILERS: ::String
+
+    # Queues concurrent frame writes while the reactor remains the sole
+    # owner of the connection socket.
     class Writer
-      IDLE: ::Symbol
+      @reactor: Reactor?
 
-      @state: Atom
+      @connection_id: Integer?
 
       @write_timeout: Integer
 
@@ -20,27 +22,48 @@ module Raptor
       # @rbs (write_timeout: Integer) -> void
       def initialize: (write_timeout: Integer) -> void
 
-      # Writes frames to the socket, coordinating with concurrent writers
-      # so that exactly one thread is actively writing at any time.
+      # Routes subsequent frame writes through the connection's reactor.
+      #
+      # @param reactor [Reactor] the reactor that owns the connection
+      # @param connection_id [Integer] unique connection identifier
+      # @return [void]
+      #
+      # @rbs (Reactor reactor, Integer connection_id) -> void
+      def attach: (Reactor reactor, Integer connection_id) -> void
+
+      # Queues frames for the reactor to write. Before attachment, writes
+      # directly so the writer remains usable during connection setup.
       #
       # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
-      # @param frames [Array<String>] frame bytes to write in order
+      # @param frames [Array<String>, nil] 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
+      # @rbs (OpenSSL::SSL::SSLSocket socket, Array[String]? frames) -> void
+      def write_frames: (OpenSSL::SSL::SSLSocket socket, Array[String]? frames) -> void
+
+      # Attaches a response body that outlives its application thread.
+      #
+      # @rbs (Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
+      def attach_body: (Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
     end
 
-    # Tracks the peer's connection-level and per-stream receive windows so
-    # outbound `DATA` frames respect RFC 7540 section 5.2.
+    class StreamClosedError < StandardError
+      # @rbs () -> String
+      def message: () -> String
+    end
+
+    # Coordinates outbound flow control and stream cancellation without
+    # polling or mutexes.
     class FlowControl
-      ACQUIRE_POLL_INTERVAL: ::Float
+      @available: AtomicConditionVariable
 
-      @connection_window: Atom
+      @cancelled_streams: Atom
+
+      @initial_stream_window: Atom
 
       @stream_windows: Atom
 
-      @initial_stream_window: Atom
+      @connection_window: Atom
 
       # Creates a new FlowControl with the spec-default windows.
       #
@@ -49,17 +72,25 @@ module Raptor
       # @rbs () -> void
       def initialize: () -> void
 
-      # Reserves outbound capacity on the given stream, polling until at
+      # Reserves outbound capacity on the given stream, waiting until at
       # least one byte is available on both the connection and stream
-      # windows. The returned size is capped at `MAX_FRAME_SIZE`.
+      # windows. Raises when the stream or connection closes.
       #
       # @param stream_id [Integer] the HTTP/2 stream identifier
       # @param max_bytes [Integer] the largest size the caller would like to send
-      # @param end_stream [Boolean] true when this is the final frame on the stream
       # @return [Integer] the number of bytes the caller may now send
       #
-      # @rbs (Integer stream_id, Integer max_bytes, ?end_stream: bool) -> Integer
-      def acquire: (Integer stream_id, Integer max_bytes, ?end_stream: bool) -> Integer
+      # @rbs (Integer stream_id, Integer max_bytes) -> Integer
+      def acquire: (Integer stream_id, Integer max_bytes) -> Integer
+
+      # Reserves outbound capacity without waiting for a window update.
+      #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @param max_bytes [Integer] the largest size the caller would like to send
+      # @return [Integer] available bytes, or 0 when flow control is exhausted
+      #
+      # @rbs (Integer stream_id, Integer max_bytes) -> Integer
+      def try_acquire: (Integer stream_id, Integer max_bytes) -> Integer
 
       # Increments the connection-level send window by `increment` bytes.
       #
@@ -87,6 +118,30 @@ module Raptor
       # @rbs (Integer new_size) -> void
       def set_initial_stream_window: (Integer new_size) -> void
 
+      # Raises when the given stream can no longer write a response.
+      #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @return [void]
+      # @raise [StreamClosedError] if the stream or connection has closed
+      #
+      # @rbs (Integer stream_id) -> void
+      def check: (Integer stream_id) -> void
+
+      # Cancels pending and future writes for the given stream.
+      #
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @return [void]
+      #
+      # @rbs (Integer stream_id) -> void
+      def cancel_stream: (Integer stream_id) -> void
+
+      # Cancels pending and future writes for the connection.
+      #
+      # @return [void]
+      #
+      # @rbs () -> void
+      def close: () -> void
+
       # Discards any per-stream tracking for the given stream.
       #
       # @param stream_id [Integer] the HTTP/2 stream identifier
@@ -108,6 +163,100 @@ module Raptor
       def reserve_connection: (Integer capped) -> Integer
     end
 
+    # Adapts one HTTP/2 response stream to Rack's streaming body interface.
+    class ResponseStream
+      @closed: bool
+
+      @bytes_written: Integer
+
+      @parser: Http2Parser
+
+      @trailers: Hash[String, String | Array[String]]
+
+      @stream_id: Integer
+
+      @flow_control: FlowControl
+
+      @writer: Writer
+
+      @socket: OpenSSL::SSL::SSLSocket
+
+      # Returns the number of response body bytes written to the stream.
+      #
+      # @return [Integer]
+      attr_reader bytes_written: Integer
+
+      # Creates a response stream for a Rack streaming body.
+      #
+      # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+      # @param writer [Writer] frame writer for the connection
+      # @param flow_control [FlowControl] outbound flow controller
+      # @param stream_id [Integer] the HTTP/2 stream identifier
+      # @param trailers [Hash] trailing response headers populated by the Rack application
+      # @return [void]
+      #
+      # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Hash[String, String | Array[String]] trailers) -> void
+      def initialize: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Hash[String, String | Array[String]] trailers) -> void
+
+      # Streaming responses are write-only.
+      #
+      # @raise [IOError]
+      #
+      # @rbs (*untyped) -> bot
+      def read: (*untyped) -> bot
+
+      # Writes response body bytes to the stream.
+      #
+      # @param chunk [String] response body bytes
+      # @return [Integer] number of bytes written
+      #
+      # @rbs (String chunk) -> Integer
+      def write: (String chunk) -> Integer
+
+      # Writes response body bytes and returns the stream.
+      #
+      # @param chunk [String] response body bytes
+      # @return [ResponseStream]
+      #
+      # @rbs (String chunk) -> ResponseStream
+      def <<: (String chunk) -> ResponseStream
+
+      # Flushes the stream. Frame writes are already immediate.
+      #
+      # @return [ResponseStream]
+      #
+      # @rbs () -> ResponseStream
+      def flush: () -> ResponseStream
+
+      # Finishes the stream.
+      #
+      # @return [void]
+      #
+      # @rbs () -> void
+      def close: () -> void
+
+      # Closes the unsupported read side of the stream.
+      #
+      # @raise [IOError]
+      #
+      # @rbs () -> bot
+      def close_read: () -> bot
+
+      # Finishes the writable side of the stream.
+      #
+      # @return [void]
+      #
+      # @rbs () -> void
+      def close_write: () -> void
+
+      # Returns whether the stream has finished.
+      #
+      # @return [Boolean]
+      #
+      # @rbs () -> bool
+      def closed?: () -> bool
+    end
+
     EAGER_READ_TIMEOUT: ::Float
 
     EAGER_READ_BUFFER_SIZE: untyped
@@ -126,6 +275,10 @@ module Raptor
 
     ERROR_PROTOCOL_ERROR: ::Integer
 
+    ERROR_INTERNAL_ERROR: ::Integer
+
+    ERROR_REFUSED_STREAM: ::Integer
+
     DEFAULT_WINDOW_SIZE: ::Integer
 
     MAX_FRAME_SIZE: ::Integer
@@ -148,6 +301,8 @@ module Raptor
     # @rbs (Array[[String, String]] headers) -> bool
     def self.invalid_pseudo_headers?: (Array[[ String, String ]] headers) -> bool
 
+    @running: AtomicBoolean
+
     @initial_settings_frame: String
 
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
@@ -194,6 +349,15 @@ module Raptor
     # @rbs () -> Writer
     def create_writer: () -> Writer
 
+    # Stops new stream dispatch and asks clients to finish streams already
+    # handed to the application.
+    #
+    # @param reactor [Reactor] the reactor managing HTTP/2 connections
+    # @return [void]
+    #
+    # @rbs (Reactor reactor) -> void
+    def shutdown: (Reactor reactor) -> void
+
     # Returns a Ractor-safe proc that parses HTTP/2 frames from the
     # state hash's buffered bytes.
     #
@@ -212,6 +376,22 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
     def self.process_frames: (Hash[Symbol, untyped] data) -> Hash[Symbol, untyped]
 
+    # Applies one complete request header block to its stream, resetting
+    # malformed initial headers or trailers and completing valid trailers.
+    #
+    # @param streams [Hash] current open-stream map
+    # @param completed_requests [Array<Hash>] accumulator of completed stream requests
+    # @param outgoing_frames [Array<String>] accumulator of protocol response frames
+    # @param parser [Http2Parser] frame parser and encoder
+    # @param stream_id [Integer] the stream identifier
+    # @param decoded_headers [Array<Array(String, String)>] decoded header pairs
+    # @param end_stream [Boolean] whether the source frame had END_STREAM set
+    # @param trailers [Boolean] whether this is a trailing header block
+    # @return [Array(Hash, Array<Hash>)] updated streams and completed requests
+    #
+    # @rbs (Hash[Integer, Hash[Symbol, untyped]] streams, Array[Hash[Symbol, untyped]] completed_requests, Array[String] outgoing_frames, Http2Parser parser, Integer stream_id, Array[[String, String]] decoded_headers, bool end_stream, bool trailers) -> [Hash[Integer, Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]]
+    def self.complete_header_block: (Hash[Integer, Hash[Symbol, untyped]] streams, Array[Hash[Symbol, untyped]] completed_requests, Array[String] outgoing_frames, Http2Parser parser, Integer stream_id, Array[[ String, String ]] decoded_headers, bool end_stream, bool trailers) -> [ Hash[Integer, Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]] ]
+
     # Merges a decoded header block into the stream's accumulated state,
     # promoting the stream to `completed_requests` when END_STREAM is set.
     #
@@ -233,7 +413,9 @@ module Raptor
     # @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 cancelled_streams [Array<Integer>] streams reset by the peer
     # @param window_updates [Array<Array(Integer, Integer)>] inbound WINDOW_UPDATE pairs as [stream_id, increment]
+    # @param ping_acknowledgements [Array<String>] acknowledged PING payloads
     # @param peer_initial_window_size [Integer, nil] new SETTINGS_INITIAL_WINDOW_SIZE announced by the peer
     # @param connection_window [Integer] current connection flow control window
     # @param preface_received [Boolean] whether the connection preface has been received
@@ -242,8 +424,8 @@ module Raptor
     # @param close_connection [Boolean] whether the connection should be closed after writing outgoing frames
     # @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, Array[[Integer, Integer]] window_updates, Integer? peer_initial_window_size, Integer connection_window, bool preface_received, Integer last_client_stream_id, Hash[Symbol, untyped]? pending_headers, bool close_connection) -> 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, Array[[ Integer, Integer ]] window_updates, Integer? peer_initial_window_size, Integer connection_window, bool preface_received, Integer last_client_stream_id, Hash[Symbol, untyped]? pending_headers, bool close_connection) -> Hash[Symbol, untyped]
+    # @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, Array[Integer] cancelled_streams, Array[[Integer, Integer]] window_updates, Array[String] ping_acknowledgements, Integer? peer_initial_window_size, Integer connection_window, bool preface_received, Integer last_client_stream_id, Hash[Symbol, untyped]? pending_headers, bool close_connection) -> 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, Array[Integer] cancelled_streams, Array[[ Integer, Integer ]] window_updates, Array[String] ping_acknowledgements, Integer? peer_initial_window_size, Integer connection_window, bool preface_received, Integer last_client_stream_id, Hash[Symbol, untyped]? pending_headers, bool close_connection) -> Hash[Symbol, untyped]
 
     # Sends the server SETTINGS frame on a freshly negotiated HTTP/2
     # connection, then eagerly reads and parses the first client frame
@@ -315,6 +497,11 @@ module Raptor
     # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Array[[String, String]] headers, String body, remote_addr: String) -> void
     def perform_stream_request: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Array[[ String, String ]] headers, String body, remote_addr: String) -> void
 
+    # Starts a detached HTTP/2 response after writing its response headers.
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, DetachedBody body, ^(Symbol) -> void finished) { () -> void } -> bool
+    def write_http2_detached_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, DetachedBody body, ^(Symbol) -> void finished) { () -> void } -> bool
+
     # Writes a Rack response as HTTP/2 frames to the socket, partitioning
     # DATA frames through `flow_control` to fit within the peer's windows.
     #
@@ -325,10 +512,35 @@ module Raptor
     # @param status [Integer] HTTP status code
     # @param headers [Hash] response headers from the Rack application
     # @param body [Object] response body responding to each
+    # @param trailers [Hash] trailing response headers populated by the Rack application
+    # @param request_method [String] request method used to suppress HEAD response bodies
     # @return [String] the response body size in bytes
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> String
-    def write_http2_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> String
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body, trailers: Hash[String, String | Array[String]], request_method: String) ?{ () -> void } -> String
+    def write_http2_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body, trailers: Hash[String, String | Array[String]], request_method: String) ?{ () -> void } -> String
+
+    # Sends an HTTP 103 Early Hints response.
+    #
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
+    # @param stream_id [Integer] the HTTP/2 stream identifier
+    # @param hints [Hash] response headers to send as early hints
+    # @return [void]
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Hash[String, String | Array[String]] hints) -> void
+    def send_early_hints: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Hash[String, String | Array[String]] hints) -> void
+
+    # Resets one HTTP/2 stream with the given error code.
+    #
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] frame writer for the connection
+    # @param stream_id [Integer] the HTTP/2 stream identifier
+    # @param error_code [Integer] the HTTP/2 error code
+    # @return [void]
+    #
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer error_code) -> void
+    def write_http2_reset_stream: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id, Integer error_code) -> void
 
     # Writes a 500 error response as HTTP/2 frames.
     #
@@ -356,11 +568,14 @@ module Raptor
     #
     # @param headers [Array<Array(String, String)>] HTTP/2 header pairs
     # @param body [String] the request body
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] frame writer for the connection
+    # @param stream_id [Integer] the HTTP/2 stream identifier
     # @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]
+    # @rbs (Array[[String, String]] headers, String body, OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, remote_addr: String) -> Hash[String, untyped]
+    def build_rack_env: (Array[[ String, String ]] headers, String body, OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, remote_addr: String) -> Hash[String, untyped]
 
     # Populates SERVER_NAME and SERVER_PORT from the HTTP_HOST header.
     #