raptor 0.19.0 → 0.20.0

data/lib/raptor/thread_locals.rb

@@ -0,0 +1,38 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Raptor
+  # Owns Raptor's reusable per-thread values and clears application thread
+  # locals after each request.
+  #
+  module ThreadLocals
+    PRESERVED_KEYS = [
+      :raptor_http_parser,
+      :raptor_read_buffer,
+      :raptor_response_buffer,
+    ].freeze
+
+    # Returns a reusable value stored on the current thread.
+    #
+    # @return [Object]
+    #
+    # @rbs (Symbol key) { () -> untyped } -> untyped
+    def self.fetch(key)
+      thread = Thread.current
+      thread.thread_variable_get(key) || thread.thread_variable_set(key, yield)
+    end
+
+    # Clears application-owned true thread locals while retaining Raptor's
+    # reusable per-thread values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear
+      thread = Thread.current
+      thread.thread_variables.each do |key|
+        thread.thread_variable_set(key, nil) unless PRESERVED_KEYS.include?(key)
+      end
+    end
+  end
+end

data/lib/raptor/version.rb

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

data/sig/generated/raptor/cli.rbs

@@ -106,6 +106,14 @@ module Raptor
     # @rbs (String? path) -> void
     def apply_config_file: (String? path) -> void
 
+    # Applies worker and thread settings from the environment. Explicit CLI
+    # options are parsed afterwards and take precedence.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def apply_environment: () -> void
+
     # Creates the OptionParser instance with all supported command-line options.
     #
     # @return [OptionParser] configured option parser

data/sig/generated/raptor/cluster.rbs

@@ -44,27 +44,27 @@ module Raptor
     # @rbs (Integer worker_count, ?cores: Integer) -> Integer
     def self.default_http2_ractor_count: (Integer worker_count, ?cores: Integer) -> Integer
 
-    @server_port: Integer
-
-    @binder: Binder
+    @stats_file: String?
 
-    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    @control_server: ControlServer?
 
-    @launch_argv: Array[String]?
+    @pid_file: String?
 
-    @launch_command: String?
+    @stdout_file: String?
 
-    @access_log_io: IO?
+    @stderr_file: String?
 
     @access_log_file: String?
 
-    @stderr_file: String?
+    @access_log_io: IO?
 
-    @stdout_file: String?
+    @launch_command: String?
 
-    @pid_file: String?
+    @launch_argv: Array[String]?
 
-    @stats_file: String?
+    @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+
+    @binder: Binder
 
     @before_refork: Array[Proc]
 
@@ -84,6 +84,10 @@ module Raptor
 
     @http2_options: Hash[Symbol, untyped]
 
+    @http1_options: Hash[Symbol, untyped]
+
+    @connection_options: Hash[Symbol, untyped]
+
     @bpf_active: bool
 
     @resp_w: IO?
@@ -114,6 +118,8 @@ module Raptor
 
     @phase: Integer
 
+    @started_at: Float
+
     @stats: Stats
 
     @timed_out: Set[Integer]
@@ -124,12 +130,16 @@ module Raptor
 
     @app: untyped
 
-    @http1_options: Hash[Symbol, untyped]
-
-    @connection_options: Hash[Symbol, untyped]
+    @server_port: Integer
 
     @environment: String
 
+    @clean_fiber_locals: bool
+
+    @clean_thread_locals: bool
+
+    @cpu_affinity: bool
+
     @max_thread_count: (Integer | Float)?
 
     @thread_count: Integer
@@ -151,6 +161,9 @@ module Raptor
     # @option options [Integer] :workers number of worker processes
     # @option options [Integer] :threads number of threads per worker process
     # @option options [Integer, Float] :max_threads maximum number of threads per worker process, or `Float::INFINITY` for no limit
+    # @option options [Boolean] :cpu_affinity whether to pin each worker to a CPU
+    # @option options [Boolean] :clean_thread_locals whether to clear application thread locals after each request
+    # @option options [Boolean] :clean_fiber_locals whether to process each request in a fresh Fiber
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
     # @option options [String, nil] :chdir directory to change to before loading the Rack application, or nil to leave the working directory unchanged
@@ -164,10 +177,11 @@ module Raptor
     # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [Integer, Array<Integer>, nil] :refork_after request-count threshold(s) at which a warm worker is promoted to a fork source for phased refork; nil or 0 disables. Requires `PR_SET_CHILD_SUBREAPER` (Linux)
     # @option options [Array<Proc>] :before_fork procs called in the master before every worker fork
-    # @option options [Array<Proc>] :before_worker_boot procs called in each worker before it begins serving
-    # @option options [Array<Proc>] :before_worker_shutdown procs called in each worker before its graceful shutdown
+    # @option options [Array<Proc>] :before_worker_boot procs called with the worker index before it begins serving
+    # @option options [Array<Proc>] :before_worker_shutdown procs called with the worker index before its graceful shutdown
     # @option options [Array<Proc>] :before_refork procs called in a worker before it transitions to a seed
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
+    # @option options [String, nil] :control_url `unix://` URL serving cluster stats, or nil to disable
     # @option options [String, nil] :pid_file path to write the master PID to, or nil to disable
     # @option options [String, nil] :stdout_file path to redirect stdout to, reopened on SIGHUP, or nil to disable
     # @option options [String, nil] :stderr_file path to redirect stderr to, reopened on SIGHUP, or nil to disable
@@ -196,8 +210,20 @@ module Raptor
     # @rbs () -> Array[Hash[Symbol, untyped]]
     def stats: () -> Array[Hash[Symbol, untyped]]
 
+    # Returns cluster statistics for the control server.
+    # For an adaptive pool, `max_threads` is the number of threads currently
+    # running so utilization reflects the capacity available at that moment.
+    #
+    # @return [Hash] cluster statistics
+    #
+    # @rbs () -> Hash[Symbol, untyped]
+    def stats_hash: () -> Hash[Symbol, untyped]
+
     private
 
+    # @rbs (Float timestamp) -> String
+    def timestamp: (Float timestamp) -> String
+
     # Returns the inherited-FDs hash for a systemd socket-activation handoff,
     # pairing each bind URI with the FD systemd passed at the same index.
     # Returns an empty hash when the FD count doesn't match the bind count.

data/sig/generated/raptor/control_server.rbs

@@ -0,0 +1,70 @@
+# Generated from lib/raptor/control_server.rb with RBS::Inline
+
+module Raptor
+  # Serves cluster statistics over a Unix socket.
+  class ControlServer
+    MAX_REQUEST_SIZE: untyped
+
+    REQUEST_TIMEOUT: ::Integer
+
+    @running: AtomicBoolean
+
+    @thread: Thread?
+
+    @client: Atom
+
+    @server: UNIXServer?
+
+    @stats: ^() -> Hash[Symbol, untyped]
+
+    @path: String
+
+    # Creates a control server for `url` without binding it.
+    #
+    # @param url [String] `unix://` URL to listen on
+    # @yieldreturn [Hash] cluster statistics
+    # @return [void]
+    # @raise [ArgumentError] if the URL is not a Unix socket
+    #
+    # @rbs (String url) { () -> Hash[Symbol, untyped] } -> void
+    def initialize: (String url) { () -> Hash[Symbol, untyped] } -> void
+
+    # Binds the Unix socket.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def bind: () -> void
+
+    # Starts serving requests in a background thread.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def start: () -> void
+
+    # Stops serving and removes the socket.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown: () -> void
+
+    private
+
+    # @rbs () -> void
+    def remove_stale_socket: () -> void
+
+    # @rbs () -> void
+    def serve: () -> void
+
+    # @rbs (UNIXSocket client) -> void
+    def handle: (UNIXSocket client) -> void
+
+    # @rbs (UNIXSocket client) -> String?
+    def read_request: (UNIXSocket client) -> String?
+
+    # @rbs () -> void
+    def close_client: () -> void
+  end
+end

data/sig/generated/raptor/http1.rbs

@@ -16,8 +16,6 @@ module Raptor
 
     RESPONSE_BUFFER_CAPACITY: untyped
 
-    KEEPALIVE_READ_TIMEOUT: ::Float
-
     MAX_KEEPALIVE_REQUESTS: ::Integer
 
     HTTP_10: ::String
@@ -110,6 +108,10 @@ module Raptor
 
     @access_log_io: IO?
 
+    @clean_thread_locals: bool
+
+    @clean_fiber_locals: bool
+
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     @running: AtomicBoolean
@@ -127,11 +129,13 @@ module Raptor
     # @param http1_options [Hash] HTTP/1.1-specific settings
     # @option http1_options [Integer] :max_keepalive_requests maximum requests per HTTP/1.1 keep-alive connection
     # @param access_log_io [IO, nil] IO to write Common Log Format access entries to, or nil to disable
+    # @param clean_thread_locals [Boolean] whether to clear application thread locals after each request
+    # @param clean_fiber_locals [Boolean] whether to process each request in a fresh Fiber
     # @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, ?connection_options: Hash[Symbol, untyped], ?http1_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], ?http1_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?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], ?http1_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?clean_thread_locals: bool, ?clean_fiber_locals: bool, ?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], ?http1_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?clean_thread_locals: bool, ?clean_fiber_locals: bool, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
 
     # Instance-level wrapper around {Http.parser_worker} that binds this
     # handler's env template and body-size limit into the worker proc.
@@ -289,6 +293,11 @@ module Raptor
     # @rbs (TCPSocket socket, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, Integer request_count, String remote_addr, String url_scheme) -> bool
     def process_request: (TCPSocket socket, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, Integer request_count, String remote_addr, String url_scheme) -> bool
 
+    # Calls the Rack app and writes its response for one request.
+    #
+    # @rbs (TCPSocket socket, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, Integer request_count, String remote_addr, String url_scheme) -> bool
+    def perform_request: (TCPSocket socket, Hash[String, untyped] env, Hash[Symbol, untyped] parse_data, String? body, Integer request_count, String remote_addr, String url_scheme) -> bool
+
     # Handles an exception raised while processing a request. Fires the
     # `rack.response_finished` callbacks with the error, writes a 500
     # response when no bytes have gone to the socket yet, and routes the
@@ -307,8 +316,9 @@ module Raptor
     def handle_app_error: (TCPSocket socket, Hash[String, untyped]? rack_env, Integer? status, Hash[String, String | Array[String]]? headers, Exception error, response_started: bool, hijacked: bool) -> void
 
     # Reads and processes subsequent requests inline on a kept-alive
-    # connection. Falls back to the reactor when no data arrives within the
-    # timeout, the thread pool is saturated, or the request is incomplete.
+    # connection. Returns the connection to the reactor when no data is ready
+    # or a request is incomplete, and queues complete requests behind work
+    # that is already waiting.
     #
     # @param socket [TCPSocket] the client socket
     # @param id [Integer] unique client identifier

data/sig/generated/raptor/http2.rbs

@@ -152,6 +152,10 @@ module Raptor
 
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
+    @clean_fiber_locals: bool
+
+    @clean_thread_locals: bool
+
     @access_log_io: IO?
 
     @write_timeout: Integer
@@ -175,11 +179,13 @@ module Raptor
     # @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 clean_thread_locals [Boolean] whether to clear application thread locals after each request
+    # @param clean_fiber_locals [Boolean] whether to process each request in a fresh Fiber
     # @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, ?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
+    # @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?, ?clean_thread_locals: bool, ?clean_fiber_locals: bool, ?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?, ?clean_thread_locals: bool, ?clean_fiber_locals: bool, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
 
     # Creates a per-connection {Writer} configured with the handler's write timeout.
     #
@@ -304,6 +310,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 dispatch_stream_request: (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Array[[ String, String ]] headers, String body, remote_addr: String) -> void
 
+    # Calls the Rack app and writes its response for one stream.
+    #
+    # @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
+
     # 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/thread_locals.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/raptor/thread_locals.rb with RBS::Inline
+
+module Raptor
+  # Owns Raptor's reusable per-thread values and clears application thread
+  # locals after each request.
+  module ThreadLocals
+    PRESERVED_KEYS: untyped
+
+    # Returns a reusable value stored on the current thread.
+    #
+    # @return [Object]
+    #
+    # @rbs (Symbol key) { () -> untyped } -> untyped
+    def self.fetch: (Symbol key) { () -> untyped } -> untyped
+
+    # Clears application-owned true thread locals while retaining Raptor's
+    # reusable per-thread values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Joshua Young
@@ -157,6 +157,7 @@ files:
 - lib/raptor/binder.rb
 - lib/raptor/cli.rb
 - lib/raptor/cluster.rb
+- lib/raptor/control_server.rb
 - lib/raptor/http.rb
 - lib/raptor/http1.rb
 - lib/raptor/http2.rb
@@ -166,12 +167,14 @@ files:
 - lib/raptor/server.rb
 - lib/raptor/stats.rb
 - lib/raptor/systemd.rb
+- lib/raptor/thread_locals.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/control_server.rbs
 - sig/generated/raptor/http.rbs
 - sig/generated/raptor/http1.rbs
 - sig/generated/raptor/http2.rbs
@@ -181,6 +184,7 @@ files:
 - sig/generated/raptor/server.rbs
 - sig/generated/raptor/stats.rbs
 - sig/generated/raptor/systemd.rbs
+- sig/generated/raptor/thread_locals.rbs
 - sig/generated/raptor/version.rbs
 homepage: https://github.com/joshuay03/raptor
 licenses: