raptor 0.22.0 → 0.22.1

data/sig/generated/raptor/http2.rbs

@@ -43,6 +43,11 @@ module Raptor
 
       # Attaches a response body that outlives its application thread.
       #
+      # @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 reactor accepted the body
+      #
       # @rbs (Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
       def attach_body: (Integer stream_id, DetachedBody body, ^(Symbol) -> void finished) -> bool
     end
@@ -257,8 +262,6 @@ module Raptor
       def closed?: () -> bool
     end
 
-    EAGER_READ_TIMEOUT: ::Float
-
     EAGER_READ_BUFFER_SIZE: untyped
 
     EAGER_MAX_ROUNDS: ::Integer
@@ -468,8 +471,8 @@ module Raptor
     # @rbs (FlowControl flow_control, Hash[Symbol, untyped] result) -> void
     def apply_flow_control_updates: (FlowControl flow_control, Hash[Symbol, untyped] result) -> void
 
-    # Reads the next frame batch from `socket` within a short window, or
-    # returns nil if nothing arrives in time.
+    # Reads the next frame batch from `socket` if it has already arrived,
+    # without waiting on the shared collector thread.
     #
     # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
     # @return [String, nil] the bytes read, or nil if nothing was available
@@ -494,13 +497,33 @@ module Raptor
 
     # Calls the Rack app and writes its response for one stream.
     #
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
+    # @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, 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
+    # @param socket [OpenSSL::SSL::SSLSocket] the connection socket
+    # @param writer [Writer] lock-free frame writer for the connection
+    # @param flow_control [FlowControl] per-connection outbound flow controller
+    # @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 [DetachedBody] the response body
+    # @param finished [Proc] called with the close reason
+    # @yield once the response headers are queued
+    # @return [void]
+    #
+    # @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 } -> void
+    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 } -> void
 
     # Writes a Rack response as HTTP/2 frames to the socket, partitioning
     # DATA frames through `flow_control` to fit within the peer's windows.

data/sig/generated/raptor/reactor.rbs

@@ -60,9 +60,17 @@ module Raptor
       # @rbs attr_reader output: Array[String]
       attr_reader output: untyped
 
+      # Creates empty connection I/O state for reactor-owned writes.
+      #
+      # @return [void]
+      #
       # @rbs () -> void
       def initialize: () -> void
 
+      # Returns whether the connection has no output waiting to be written.
+      #
+      # @return [Boolean]
+      #
       # @rbs () -> bool
       def empty?: () -> bool
     end
@@ -84,9 +92,19 @@ module Raptor
       # @rbs attr_reader state: Hash[Symbol, untyped]
       attr_reader state: 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
+      # @return [void]
+      #
       # @rbs (DetachedBody body, Hash[Symbol, untyped] state) -> void
       def initialize: (DetachedBody body, Hash[Symbol, untyped] state) -> void
 
+      # Returns whether the connection has no output or detached body remaining.
+      #
+      # @return [Boolean]
+      #
       # @rbs () -> bool
       def empty?: () -> bool
     end
@@ -105,9 +123,17 @@ module Raptor
       # @rbs attr_reader budget: DetachedBody::Budget
       attr_reader budget: untyped
 
+      # Creates empty I/O state for an HTTP/2 connection and its detached streams.
+      #
+      # @return [void]
+      #
       # @rbs () -> void
       def initialize: () -> void
 
+      # Returns whether the connection has no output or detached streams remaining.
+      #
+      # @return [Boolean]
+      #
       # @rbs () -> bool
       def empty?: () -> bool
     end
@@ -116,9 +142,7 @@ module Raptor
 
     DETACHED_CONNECTION_BUFFER_SIZE: untyped
 
-    DETACHED_MAX_CHUNKS: ::Integer
-
-    DETACHED_MAX_FRAMES: ::Integer
+    DETACHED_WRITE_BATCH: ::Integer
 
     DETACHED_WORKER_BUFFER_SIZE: untyped
 
@@ -126,6 +150,8 @@ module Raptor
 
     @timeouts: RedBlackTree[TimeoutClient]
 
+    @io_applied: AtomicConditionVariable
+
     @io_queue: AtomicQueue
 
     @queue: Queue[TCPSocket]
@@ -184,6 +210,7 @@ module Raptor
     # @param connection_options [Hash] per-connection timeout configuration
     # @option connection_options [Integer] :first_data_timeout timeout for initial data
     # @option connection_options [Integer] :chunk_data_timeout timeout for subsequent chunks
+    # @option connection_options [Integer] :write_timeout timeout for non-blocking writes
     # @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
@@ -273,6 +300,13 @@ module Raptor
 
     # Attaches a detached response body to an HTTP/1.x connection.
     #
+    # @param socket [TCPSocket] the client socket
+    # @param id [Integer] unique client 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
+    # @return [Boolean] whether the body was attached
+    #
     # @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
 
@@ -308,22 +342,38 @@ 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 body [DetachedBody] the response body
+    # @param finished [Proc] called with the close reason
+    # @return [Boolean] whether the body was attached
+    #
     # @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.
     #
+    # @param id [Integer] unique connection identifier
+    # @return [void]
+    #
     # @rbs (Integer id) -> void
     def resume_http2_bodies: (Integer id) -> void
 
     # Cancels a detached response stream.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @return [void]
+    #
     # @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.
     #
+    # @param timeout [Numeric] seconds to wait before cancelling open bodies
+    # @return [void]
+    #
     # @rbs (Numeric timeout) -> void
     def drain_detached_bodies: (Numeric timeout) -> void
 
@@ -418,61 +468,109 @@ 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 body [DetachedBody] the response body
+    # @param state [Hash] connection state restored once the response finishes
+    # @param finished [Proc] called with the close reason
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique client identifier
+    # @param io [Http1IO] connection I/O state
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique client identifier
+    # @param reason [Symbol] why the response closed
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param body [DetachedBody] the response body
+    # @param finished [Proc] called with the close reason
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique connection identifier
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique connection identifier
+    # @return [void]
+    #
     # @rbs (Integer id) -> void
     def flush_http2_detached_bodies: (Integer id) -> void
 
     # 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 body [DetachedBody] the response body
+    # @return [void]
+    #
     # @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.
     #
+    # @param id [Integer] unique connection identifier
+    # @param stream_id [Integer] HTTP/2 stream identifier
+    # @param reason [Symbol] why the stream closed
+    # @return [void]
+    #
     # @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.
     #
+    # @return [void]
+    #
     # @rbs () -> void
     def cancel_detached_bodies: () -> void
 
     # Records one detached stream finishing.
     #
+    # @return [void]
+    #
     # @rbs () -> void
     def detached_body_removed: () -> void
 
@@ -593,6 +691,10 @@ module Raptor
 
     # Handles readiness for an HTTP/1.x detached response.
     #
+    # @param monitor [NIO::Monitor] ready selector monitor
+    # @param id [Integer] unique client identifier
+    # @return [void]
+    #
     # @rbs (NIO::Monitor monitor, Integer id) -> void
     def handle_http1_detached_monitor: (NIO::Monitor monitor, Integer id) -> void
 

data/sig/generated/raptor/thread_locals.rbs

@@ -8,7 +8,9 @@ module Raptor
 
     # Returns a reusable value stored on the current thread.
     #
-    # @return [Object]
+    # @param key [Symbol] thread-variable key used to cache the value
+    # @yieldreturn [Object] value to store when the key is unset
+    # @return [Object] the existing or newly stored value
     #
     # @rbs (Symbol key) { () -> untyped } -> untyped
     def self.fetch: (Symbol key) { () -> untyped } -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.22.1
 platform: ruby
 authors:
 - Joshua Young