raptor 0.20.2 → 0.21.0

data/sig/generated/raptor/http2.rbs

@@ -3,6 +3,8 @@
 module Raptor
   # Handles HTTP/2 request processing and Rack application integration.
   class Http2
+    RESPONSE_TRAILERS: ::String
+
     # Serialises concurrent frame writes on a single HTTP/2 connection so
     # exactly one thread is writing at any moment.
     class Writer
@@ -31,17 +33,24 @@ module Raptor
       def write_frames: (OpenSSL::SSL::SSLSocket socket, Array[String] frames) -> void
     end
 
-    # Tracks the peer's connection-level and per-stream receive windows so
-    # outbound `DATA` frames respect RFC 7540 section 5.2.
-    class FlowControl
-      ACQUIRE_POLL_INTERVAL: ::Float
+    class StreamClosedError < StandardError
+      # @rbs () -> String
+      def message: () -> String
+    end
 
+    # Coordinates outbound flow control and stream cancellation without
+    # polling or mutexes.
+    class FlowControl
       @connection_window: Atom
 
       @stream_windows: Atom
 
       @initial_stream_window: Atom
 
+      @cancelled_streams: Atom
+
+      @available: AtomicConditionVariable
+
       # Creates a new FlowControl with the spec-default windows.
       #
       # @return [void]
@@ -49,17 +58,16 @@ 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
 
       # Increments the connection-level send window by `increment` bytes.
       #
@@ -87,6 +95,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 +140,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 +252,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 +278,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 +326,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 +353,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 +390,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 +401,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
@@ -325,10 +484,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 +540,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.
     #

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.
@@ -54,6 +53,10 @@ module Raptor
 
     @persistent_data_timeout: Integer
 
+    @http2_keepalive_interval: Integer
+
+    @http2_keepalive_timeout: Integer
+
     @selector: NIO::Selector
 
     @queue: Queue[TCPSocket]
@@ -70,6 +73,12 @@ 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]]
+
     # Creates a new Reactor instance.
     #
     # @param http1_ractor_pool [RactorPool] ractor pool for HTTP/1.x parsing
@@ -80,10 +89,13 @@ 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.
@@ -162,6 +174,26 @@ module Raptor
     # @rbs (Integer id) -> untyped?
     def flow_control_for: (Integer id) -> untyped?
 
+    # 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
+
     # Stores an HTTP/2 connection's socket, state, writer, and flow
     # controller in the reactor's per-connection maps.
     #
@@ -170,10 +202,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) -> void
-    def attach_http2: (id: Integer, socket: TCPSocket, state: Hash[Symbol, untyped], writer: untyped, flow_control: untyped) -> 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 (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.
     #
@@ -227,6 +270,25 @@ 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
+
     # 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.21.0
 platform: ruby
 authors:
 - Joshua Young
@@ -206,7 +206,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: []