raptor 0.7.0 → 0.8.0

data/sig/generated/raptor/http2.rbs

@@ -17,10 +17,15 @@ module Raptor
 
       @state: Atom
 
+      @write_timeout: Integer
+
       # Creates a new Writer.
       #
-      # @rbs () -> void
-      def initialize: () -> void
+      # @param write_timeout [Integer] per-write socket timeout passed through to {Http.socket_write}
+      # @return [void]
+      #
+      # @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.
@@ -36,7 +41,7 @@ module Raptor
     # Per-connection outbound flow-control accounting.
     #
     # Tracks the peer's connection-level and per-stream receive windows so
-    # outbound DATA frames respect RFC 7540 §5.2. Threads dispatching stream
+    # outbound DATA frames respect RFC 7540 section 5.2. Threads dispatching stream
     # responses call `acquire` to reserve send capacity; threads applying
     # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
     # replenish it. The connection window and per-stream windows live in
@@ -93,7 +98,7 @@ module Raptor
       def add_stream_window: (Integer stream_id, Integer increment) -> void
 
       # Updates the peer's `SETTINGS_INITIAL_WINDOW_SIZE`. Shifts every
-      # existing stream window by the delta as required by RFC 7540 §6.9.2.
+      # existing stream window by the delta as required by RFC 7540 section 6.9.2.
       #
       # @param new_size [Integer] the peer's new initial window size
       # @return [void]
@@ -140,28 +145,44 @@ module Raptor
 
     HOP_BY_HOP_HEADERS: untyped
 
+    @initial_settings_frame: String
+
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
+    @access_log_io: IO?
+
+    @write_timeout: Integer
+
     @server_port: Integer
 
     @app: ^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ]
 
+    # The initial server SETTINGS frame sent on every new HTTP/2 connection.
+    #
+    # @return [String] the encoded SETTINGS frame
+    attr_reader initial_settings_frame: untyped
+
     # Creates a new Http2 handler.
     #
     # @param app [#call] the Rack application to dispatch requests to
     # @param server_port [Integer] port number used to populate SERVER_PORT in the Rack env
+    # @param connection_options [Hash] per-connection settings shared across protocols
+    # @option connection_options [Integer] :write_timeout per-write socket timeout in seconds
+    # @param http2_options [Hash] HTTP/2-specific settings
+    # @option http2_options [Integer] :max_concurrent_streams maximum HTTP/2 concurrent streams per connection
+    # @param access_log_io [IO, nil] IO to write Common Log Format access entries to, or nil to disable
     # @param on_error [#call, nil] callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
-    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
-    def initialize: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Integer server_port, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
+    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?connection_options: Hash[Symbol, untyped], ?http2_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
+    def initialize: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Integer server_port, ?connection_options: Hash[Symbol, untyped], ?http2_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
 
-    # Builds the initial server SETTINGS frame to send on connection establishment.
+    # Creates a per-connection {Writer} configured with the handler's write timeout.
     #
-    # @return [String] the encoded SETTINGS frame
+    # @return [Writer] a new per-connection frame writer
     #
-    # @rbs () -> String
-    def self.build_server_settings_frame: () -> String
+    # @rbs () -> Writer
+    def create_writer: () -> Writer
 
     # Processes HTTP/2 frames from the connection buffer.
     #
@@ -271,10 +292,10 @@ 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
-    # @return [void]
+    # @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) -> void
-    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) -> void
+    # @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
 
     # Writes a 500 error response as HTTP/2 frames.
     #
@@ -286,6 +307,18 @@ module Raptor
     # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
     def write_http2_error_response: (OpenSSL::SSL::SSLSocket socket, Writer writer, Integer stream_id) -> void
 
+    # Instance-level wrapper around {Http.write_access_log} that routes to
+    # the configured `@access_log_io`.
+    #
+    # @param env [Hash] the Rack environment
+    # @param status [Integer] the response status code
+    # @param size [String] the response body size in bytes, or `-` if unknown
+    # @param remote_addr [String] the client IP address
+    # @return [void]
+    #
+    # @rbs (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def write_access_log: (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+
     # Builds a Rack environment hash from HTTP/2 headers and body.
     #
     # Translates HTTP/2 pseudo-headers into Rack-compatible environment keys

data/sig/generated/raptor/reactor.rbs

@@ -10,10 +10,12 @@ module Raptor
   # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
-  #     first_data_timeout: 30,
-  #     chunk_data_timeout: 10
-  #   })
+  #   reactor = Reactor.new(
+  #     ractor_pool,
+  #     thread_pool,
+  #     connection_options: { first_data_timeout: 30, chunk_data_timeout: 10 },
+  #     http1_options: { persistent_data_timeout: 65 }
+  #   )
   #   reactor.run
   #   reactor.add(id: client.object_id, socket: client)
   #   # ... later
@@ -71,7 +73,11 @@ module Raptor
 
     @selector: NIO::Selector
 
-    @client_options: Hash[Symbol, Integer]
+    @persistent_data_timeout: Integer
+
+    @chunk_data_timeout: Integer
+
+    @first_data_timeout: Integer
 
     @ractor_pool: untyped
 
@@ -81,14 +87,15 @@ module Raptor
     #
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
-    # @param client_options [Hash] timeout configuration options
-    # @option client_options [Integer] :first_data_timeout timeout for initial data
-    # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
-    # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
+    # @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
+    # @param http1_options [Hash] HTTP/1.1-specific configuration
+    # @option http1_options [Integer] :persistent_data_timeout timeout for keep-alive idle connections
     # @return [void]
     #
-    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize: (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
+    # @rbs (untyped ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> void
+    def initialize: (untyped ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> void
 
     # Starts the reactor's main event loop in a new thread.
     #

data/sig/generated/raptor/server.rbs

@@ -14,9 +14,10 @@ module Raptor
   #
   # @example
   #   binder = Binder.new(["tcp://0.0.0.0:3000"])
-  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {})
-  #   request = Request.new(app, 3000)
-  #   server = Server.new(binder, reactor, thread_pool, request, client_options: { first_data_timeout: 30 })
+  #   reactor = Reactor.new(ractor_pool, thread_pool, connection_options: {}, http1_options: {})
+  #   http1 = Http1.new(app, 3000)
+  #   http2 = Http2.new(app, 3000)
+  #   server = Server.new(binder, reactor, thread_pool, http1, http2, connection_options: { first_data_timeout: 30 })
   #   server.run
   #   # ... later
   #   server.shutdown
@@ -35,9 +36,13 @@ module Raptor
 
     @running: AtomicBoolean
 
-    @client_options: Hash[Symbol, untyped]
+    @drain_accept_queue: bool
 
-    @request: Request
+    @first_data_timeout: Integer
+
+    @http2: Http2
+
+    @http1: Http1
 
     @thread_pool: AtomicThreadPool
 
@@ -50,12 +55,14 @@ module Raptor
     # @param binder [Binder] the binder managing listening sockets
     # @param reactor [Reactor] the reactor for handling client connections
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
-    # @param request [Request] the HTTP/1.1 request handler
-    # @param client_options [Hash] client timeout configuration, used to bound TLS handshakes
+    # @param http1 [Http1] the HTTP/1.1 handler
+    # @param http2 [Http2] the HTTP/2 handler (provides the initial SETTINGS frame)
+    # @param connection_options [Hash] per-connection timeout configuration, used to bound TLS handshakes
+    # @param drain_accept_queue [Boolean] whether to drain the kernel accept queue on shutdown
     # @return [void]
     #
-    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
-    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Request request, client_options: Hash[Symbol, untyped]) -> void
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], ?drain_accept_queue: bool) -> void
+    def initialize: (Binder binder, Reactor reactor, AtomicThreadPool thread_pool, Http1 http1, Http2 http2, connection_options: Hash[Symbol, untyped], ?drain_accept_queue: bool) -> void
 
     # Starts the server's main accept loop in a new thread.
     #
@@ -71,8 +78,9 @@ module Raptor
 
     # Gracefully shuts down the server.
     #
-    # Stops accepting new connections and closes all listening sockets.
-    # The server thread will exit after handling any in-flight accept operations.
+    # Stops accepting new connections and closes all listening sockets. When
+    # `drain_accept_queue` is enabled, dispatches every connection already in
+    # the kernel accept queue before closing the listeners.
     #
     # @return [void]
     #
@@ -81,6 +89,14 @@ module Raptor
 
     private
 
+    # Dispatches every connection already in the kernel accept queue for each
+    # listener until all are drained.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def drain_accept_queue: () -> void
+
     # Accepts a connection from the given listener and dispatches it.
     #
     # For SSL listeners the TLS handshake is offloaded to the thread pool so
@@ -90,11 +106,10 @@ module Raptor
     # follow the HTTP/1.1 path.
     #
     # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
-    # @param reactor [Reactor] the reactor to dispatch connections to
-    # @return [void]
+    # @return [Boolean] true if a connection was accepted, false if the listener had nothing to dispatch
     #
-    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
-    def accept_connection: (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
+    def accept_connection: (TCPServer | UNIXServer | Binder::SslListener listener) -> bool
 
     # Performs the TLS handshake for an accepted SSL connection and dispatches
     # it through the HTTP/2 or HTTP/1.1 path. The handshake is bounded by
@@ -103,11 +118,10 @@ module Raptor
     # @param listener [Binder::SslListener] the SSL listener that accepted the connection
     # @param tcp_client [TCPSocket] the accepted TCP socket
     # @param remote_addr [String] the client's IP address
-    # @param reactor [Reactor] the reactor to dispatch the connection to
     # @return [void]
     #
-    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
-    def dispatch_ssl_connection: (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr, Reactor reactor) -> void
+    # @rbs (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
+    def dispatch_ssl_connection: (Binder::SslListener listener, TCPSocket tcp_client, String remote_addr) -> void
 
     # Drives a non-blocking SSL handshake to completion, bounded by the
     # configured first-data timeout. Returns true on success, false on

data/sig/generated/raptor/systemd.rbs

@@ -0,0 +1,42 @@
+# Generated from lib/raptor/systemd.rb with RBS::Inline
+
+module Raptor
+  # Integration with systemd's service notification protocol and
+  # socket-activation file descriptors.
+  module Systemd
+    LISTEN_FDS_START: ::Integer
+
+    LISTEN_FDNAMES_ENV: ::String
+
+    LISTEN_FDS_ENV: ::String
+
+    LISTEN_PID_ENV: ::String
+
+    NOTIFY_SOCKET_ENV: ::String
+
+    # Sends `message` to the systemd notification socket, returning true on
+    # success and false when the socket is unset or the send fails.
+    #
+    # @param message [String] notify protocol payload, e.g. "READY=1"
+    # @return [Boolean]
+    #
+    # @rbs (String message) -> bool
+    def self.notify: (String message) -> bool
+
+    # Returns the file descriptors passed in via socket activation, or an
+    # empty array when systemd has not exported any.
+    #
+    # @return [Array<Integer>]
+    #
+    # @rbs () -> Array[Integer]
+    def self.listen_fds: () -> Array[Integer]
+
+    # Clears the socket-activation environment variables so children don't
+    # act on stale values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear_listen_env: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Joshua Young
@@ -121,24 +121,28 @@ files:
 - lib/raptor/binder.rb
 - lib/raptor/cli.rb
 - lib/raptor/cluster.rb
+- lib/raptor/http.rb
+- lib/raptor/http1.rb
 - lib/raptor/http2.rb
 - lib/raptor/log.rb
 - lib/raptor/reactor.rb
-- lib/raptor/request.rb
 - lib/raptor/server.rb
 - lib/raptor/stats.rb
+- lib/raptor/systemd.rb
 - lib/raptor/version.rb
 - sig/generated/rackup/handler/raptor.rbs
 - sig/generated/raptor.rbs
 - sig/generated/raptor/binder.rbs
 - sig/generated/raptor/cli.rbs
 - sig/generated/raptor/cluster.rbs
+- sig/generated/raptor/http.rbs
+- sig/generated/raptor/http1.rbs
 - sig/generated/raptor/http2.rbs
 - sig/generated/raptor/log.rbs
 - sig/generated/raptor/reactor.rbs
-- sig/generated/raptor/request.rbs
 - sig/generated/raptor/server.rbs
 - sig/generated/raptor/stats.rbs
+- sig/generated/raptor/systemd.rbs
 - sig/generated/raptor/version.rbs
 homepage: https://github.com/joshuay03/raptor
 licenses: