raptor 0.20.2 → 0.21.0

data/lib/raptor/reactor.rb

@@ -5,10 +5,9 @@ require "nio"
 require "red-black-tree"
 
 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
@@ -59,6 +58,8 @@ module Raptor
     # @rbs @first_data_timeout: Integer
     # @rbs @chunk_data_timeout: Integer
     # @rbs @persistent_data_timeout: Integer
+    # @rbs @http2_keepalive_interval: Integer
+    # @rbs @http2_keepalive_timeout: Integer
     # @rbs @selector: NIO::Selector
     # @rbs @queue: Queue[TCPSocket]
     # @rbs @timeouts: RedBlackTree[TimeoutClient]
@@ -67,6 +68,9 @@ module Raptor
     # @rbs @id_to_timeout: Hash[Integer, TimeoutClient]
     # @rbs @id_to_writer: Hash[Integer, untyped]
     # @rbs @id_to_flow_control: Hash[Integer, untyped]
+    # @rbs @id_to_http2_last_stream: Hash[Integer, Integer]
+    # @rbs @id_to_http2_drain_stream: Hash[Integer, Integer]
+    # @rbs @id_to_http2_keepalive: Hash[Integer, Hash[Symbol, untyped]]
 
     # Creates a new Reactor instance.
     #
@@ -78,16 +82,21 @@ 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(http1_ractor_pool, http2_ractor_pool, thread_pool, connection_options:, http1_options:)
+    # @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(http1_ractor_pool, http2_ractor_pool, thread_pool, connection_options:, http1_options:, http2_options:)
       @http1_ractor_pool = http1_ractor_pool
       @http2_ractor_pool = http2_ractor_pool
       @thread_pool = thread_pool
       @first_data_timeout = connection_options[:first_data_timeout]
       @chunk_data_timeout = connection_options[:chunk_data_timeout]
       @persistent_data_timeout = http1_options[:persistent_data_timeout]
+      @http2_keepalive_interval = http2_options[:keepalive_interval]
+      @http2_keepalive_timeout = http2_options[:keepalive_timeout]
 
       @selector = NIO::Selector.new
       @queue = Queue.new
@@ -98,6 +107,9 @@ module Raptor
       @id_to_timeout = {}
       @id_to_writer = {}
       @id_to_flow_control = {}
+      @id_to_http2_last_stream = {}
+      @id_to_http2_drain_stream = {}
+      @id_to_http2_keepalive = {}
     end
 
     # Starts the reactor's main event loop in a new thread. Runs until
@@ -129,12 +141,7 @@ module Raptor
               @timeouts.delete!(to_client)
               id = to_client.client_data[:id]
               @id_to_timeout.delete(id)
-              socket = @id_to_socket[id]
-              next unless socket
-
-              @selector.deregister(socket)
-              socket.write(TIMEOUT_RESPONSE) rescue nil
-              cleanup(socket)
+              handle_timeout(to_client, now)
             end
 
             until @queue.empty?
@@ -145,12 +152,16 @@ module Raptor
           end
         end
 
+        @id_to_flow_control.each_value(&:close)
         @id_to_socket.each_value { |socket| socket.close rescue nil }
         @id_to_socket.clear
         @socket_to_state.clear
         @id_to_timeout.clear
         @id_to_writer.clear
         @id_to_flow_control.clear
+        @id_to_http2_last_stream.clear
+        @id_to_http2_drain_stream.clear
+        @id_to_http2_keepalive.clear
         @timeouts.clear!
         @selector.close
       end
@@ -270,6 +281,42 @@ module Raptor
       @id_to_flow_control[id]
     end
 
+    # 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(id, stream_id)
+      if (last_stream = @id_to_http2_drain_stream[id])
+        return stream_id <= last_stream
+      end
+
+      current = @id_to_http2_last_stream[id] || 0
+      @id_to_http2_last_stream[id] = stream_id if stream_id > current
+      true
+    end
+
+    # 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
+      @id_to_flow_control.each_key do |id|
+        last_stream = @id_to_http2_last_stream[id] || 0
+        @id_to_http2_drain_stream[id] = last_stream
+        writer = @id_to_writer[id]
+        socket = @id_to_socket[id]
+        writer.write_frames(socket, [yield(last_stream)]) if writer && socket
+      end
+    end
+
     # Stores an HTTP/2 connection's socket, state, writer, and flow
     # controller in the reactor's per-connection maps.
     #
@@ -278,14 +325,34 @@ 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:, socket:, state:, writer:, flow_control:)
+    # @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:, socket:, state:, writer:, flow_control:, ping_frame:, ping_payload:)
       @id_to_socket[id] = socket
       @socket_to_state[socket] = state
       @id_to_writer[id] = writer
       @id_to_flow_control[id] = flow_control
+      @id_to_http2_last_stream[id] = 0
+      if @http2_keepalive_interval.positive?
+        @id_to_http2_keepalive[id] = {frame: ping_frame, payload: ping_payload}
+      end
+    end
+
+    # 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(id, payloads)
+      keepalive = @id_to_http2_keepalive[id]
+      return unless keepalive && payloads&.include?(keepalive[:payload])
+
+      keepalive.delete(:deadline)
     end
 
     # Registers an attached socket for future reactor-driven reads.
@@ -335,7 +402,10 @@ module Raptor
 
       @socket_to_state.delete(socket)
       @id_to_writer.delete(id)
-      @id_to_flow_control.delete(id)
+      @id_to_flow_control.delete(id)&.close
+      @id_to_http2_last_stream.delete(id)
+      @id_to_http2_drain_stream.delete(id)
+      @id_to_http2_keepalive.delete(id)
       socket.close rescue nil
     end
 
@@ -372,19 +442,65 @@ module Raptor
       @selector.register(socket, :r).value = socket
 
       state = @socket_to_state[socket]
-      client = TimeoutClient.new(state)
-      timeout = if state[:persisted]
-        @persistent_data_timeout
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      timeout_at = if state[:protocol] == :http2
+        if state[:http2_preface_received]
+          keepalive = @id_to_http2_keepalive[state[:id]]
+          keepalive && (keepalive[:deadline] || now + @http2_keepalive_interval)
+        else
+          now + @first_data_timeout
+        end
+      elsif state[:persisted]
+        now + @persistent_data_timeout
       elsif first_data_received?(state)
-        @chunk_data_timeout
+        now + @chunk_data_timeout
       else
-        @first_data_timeout
+        now + @first_data_timeout
       end
-      client.timeout_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      track_timeout(state, timeout_at) if timeout_at
+    end
+
+    # 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(state, timeout_at)
+      client = TimeoutClient.new(state)
+      client.timeout_at = timeout_at
       @timeouts << client
       @id_to_timeout[state[:id]] = client
     end
 
+    # 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(client, now)
+      state = client.client_data
+      id = state[:id]
+      socket = @id_to_socket[id]
+      return unless socket
+
+      keepalive = @id_to_http2_keepalive[id] if state[:http2_preface_received]
+      if keepalive && !keepalive[:deadline]
+        keepalive[:deadline] = now + @http2_keepalive_timeout
+        @id_to_writer[id].write_frames(socket, [keepalive[:frame]])
+        track_timeout(state, keepalive[:deadline])
+        return
+      end
+
+      @selector.deregister(socket)
+      socket.write(TIMEOUT_RESPONSE) rescue nil unless state[:protocol] == :http2
+      cleanup(socket)
+    end
+
     # Handles socket wakeup by deregistering and queuing for processing.
     #
     # @param socket [TCPSocket] the socket that became ready
@@ -395,7 +511,7 @@ module Raptor
       @selector.deregister(socket)
       state = @socket_to_state[socket]
       to_client = @id_to_timeout.delete(state[:id])
-      @timeouts.delete!(to_client)
+      @timeouts.delete!(to_client) if to_client
       read_and_queue_for_parse(socket, state)
     end
 
@@ -441,7 +557,10 @@ module Raptor
       state = @socket_to_state.delete(socket)
       @id_to_socket.delete(state[:id])
       @id_to_writer.delete(state[:id])
-      @id_to_flow_control.delete(state[:id])
+      @id_to_flow_control.delete(state[:id])&.close
+      @id_to_http2_last_stream.delete(state[:id])
+      @id_to_http2_drain_stream.delete(state[:id])
+      @id_to_http2_keepalive.delete(state[:id])
       socket.close
     end
 

data/lib/raptor/server.rb

@@ -182,6 +182,18 @@ module Raptor
         return true
       end
 
+      if listener.is_a?(Binder::H2cListener)
+        @http2.eager_accept(
+          tcp_client,
+          tcp_client.object_id,
+          @reactor,
+          @thread_pool,
+          remote_addr,
+          HTTP_SCHEME
+        )
+        return true
+      end
+
       @http1.eager_accept(
         tcp_client,
         tcp_client.object_id,

data/lib/raptor/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Raptor
-  VERSION = "0.20.2"
+  VERSION = "0.21.0"
 end

data/sig/generated/raptor/binder.rbs

@@ -1,9 +1,9 @@
 # Generated from lib/raptor/binder.rb with RBS::Inline
 
 module Raptor
-  # Binds `tcp://`, `unix://`, and `ssl://` URIs to listening sockets and
-  # holds them for the server. Reconstructs listeners from inherited file
-  # descriptors when provided (systemd socket activation, hot restart).
+  # Binds TCP, Unix, SSL, and cleartext HTTP/2 URIs to listening sockets
+  # and holds them for the server. Reconstructs listeners from inherited
+  # file descriptors when provided (systemd socket activation, hot restart).
   class Binder
     SOCKET_BACKLOG: ::Integer
 
@@ -27,9 +27,21 @@ module Raptor
       def members: () -> [ :tcp_server, :ssl_context ]
     end
 
-    @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener]]
+    # Marks a TCPServer as accepting cleartext HTTP/2 connections.
+    class H2cListener < Data
+      attr_reader tcp_server(): untyped
+
+      def self.new: (untyped tcp_server) -> instance
+                  | (tcp_server: untyped) -> instance
+
+      def self.members: () -> [ :tcp_server ]
+
+      def members: () -> [ :tcp_server ]
+    end
+
+    @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener | H2cListener]]
 
-    @listeners: Array[TCPServer | UNIXServer | SslListener]
+    @listeners: Array[TCPServer | UNIXServer | SslListener | H2cListener]
 
     @inherited_fds: Hash[String, Array[Integer]]
 
@@ -49,7 +61,7 @@ module Raptor
 
     # Returns the array of listening sockets.
     #
-    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     attr_reader listeners: untyped
 
     # Creates a new Binder and binds each URI. `localhost` expands to both
@@ -66,7 +78,8 @@ module Raptor
     def initialize: (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
 
     # Returns the bound addresses as strings: TCP as `host:port`, Unix as
-    # the socket path, SSL as `ssl://host:port`.
+    # the socket path, SSL as `ssl://host:port`, and cleartext HTTP/2 as
+    # `h2c://host:port`.
     #
     # @return [Array<String>]
     #
@@ -124,22 +137,22 @@ module Raptor
     # Creates fresh listeners for the given URI.
     #
     # @param uri [URI] the parsed bind URI
-    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
-    # @rbs (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener]
-    def create_listeners: (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener]
+    # @rbs (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener | H2cListener]
+    def create_listeners: (URI::Generic uri) -> Array[TCPServer | UNIXServer | SslListener | H2cListener]
 
     # Reconstructs listeners for the given URI from inherited file
     # descriptors.
     #
     # @param uri [URI] the parsed bind URI the FDs were bound to
     # @param filenos [Array<Integer>] file descriptors to wrap
-    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @return [Array<TCPServer, UNIXServer, SslListener, H2cListener>]
     # @raise [UnknownBindSchemeError] if the URI scheme is not supported
     #
-    # @rbs (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
-    def restore_listeners: (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    # @rbs (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener | H2cListener]
+    def restore_listeners: (URI::Generic uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener | H2cListener]
 
     # Creates TCP server sockets for the given host and port.
     #

data/sig/generated/raptor/http.rbs

@@ -61,6 +61,18 @@ module Raptor
     # @rbs (Hash[String, untyped] env_template, Integer? max_body_size) -> ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
     def self.parser_worker: (Hash[String, untyped] env_template, Integer? max_body_size) -> ^(Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
+    # Calls every `rack.response_finished` callback in reverse
+    # registration order, rescuing any that raise.
+    #
+    # @param env [Hash, nil] the Rack environment
+    # @param status [Integer, nil] the response status code
+    # @param headers [Hash, nil] the response headers
+    # @param error [Exception, nil] any error raised during processing, or nil on success
+    # @return [void]
+    #
+    # @rbs (Hash[String, untyped]? env, Integer? status, Hash[String, String | Array[String]]? headers, Exception? error) -> void
+    def self.call_response_finished: (Hash[String, untyped]? env, Integer? status, Hash[String, String | Array[String]]? headers, Exception? error) -> void
+
     # Writes a Common Log Format entry to `io`. Write failures are silently
     # ignored.
     #

data/sig/generated/raptor/http1.rbs

@@ -580,18 +580,6 @@ module Raptor
     # @rbs (TCPSocket socket, String response, untyped body, bool use_chunked) -> void
     def write_enumerable_body: (TCPSocket socket, String response, untyped body, bool use_chunked) -> void
 
-    # Calls every `rack.response_finished` callback in reverse
-    # registration order, rescuing any that raise.
-    #
-    # @param env [Hash, nil] the Rack environment
-    # @param status [Integer, nil] the response status code
-    # @param headers [Hash, nil] the response headers
-    # @param error [Exception, nil] any error raised during processing, or nil on success
-    # @return [void]
-    #
-    # @rbs (Hash[String, untyped] env, Integer? status, Hash[String, String | Array[String]]? headers, Exception? error) -> void
-    def call_response_finished: (Hash[String, untyped] env, Integer? status, Hash[String, String | Array[String]]? headers, Exception? error) -> void
-
     # Instance-level wrapper around {Http.write_access_log} that routes to
     # the configured `@access_log_io`.
     #