raptor 0.19.0 → 0.20.1

data/lib/raptor/cluster.rb

@@ -3,6 +3,7 @@
 
 require "concurrent/utility/processor_counter"
 require "json"
+require "time"
 
 require "atomic-ruby/atomic_thread_pool"
 require "rack/builder"
@@ -10,6 +11,7 @@ require "ractor-pool"
 
 require_relative "log"
 require_relative "binder"
+require_relative "control_server"
 require_relative "reactor"
 require_relative "server"
 require_relative "reuseport_bpf"
@@ -74,6 +76,9 @@ module Raptor
     # @rbs @http2_ractor_count: Integer
     # @rbs @thread_count: Integer
     # @rbs @max_thread_count: (Integer | Float)?
+    # @rbs @cpu_affinity: bool
+    # @rbs @clean_thread_locals: bool
+    # @rbs @clean_fiber_locals: bool
     # @rbs @environment: String
     # @rbs @connection_options: Hash[Symbol, untyped]
     # @rbs @http1_options: Hash[Symbol, untyped]
@@ -87,6 +92,7 @@ module Raptor
     # @rbs @before_worker_shutdown: Array[Proc]
     # @rbs @before_refork: Array[Proc]
     # @rbs @stats_file: String?
+    # @rbs @control_server: ControlServer?
     # @rbs @pid_file: String?
     # @rbs @stdout_file: String?
     # @rbs @stderr_file: String?
@@ -102,6 +108,7 @@ module Raptor
     # @rbs @workers: Hash[Integer, Integer]
     # @rbs @timed_out: Set[Integer]
     # @rbs @stats: Stats
+    # @rbs @started_at: Float
     # @rbs @phase: Integer
     # @rbs @phased_restart_requested: bool
     # @rbs @phased_restarting: bool
@@ -127,6 +134,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
@@ -140,10 +150,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
@@ -161,6 +172,9 @@ module Raptor
       @http2_ractor_count = options[:http2][:ractors] || self.class.default_http2_ractor_count(@worker_count)
       @thread_count = options[:threads]
       @max_thread_count = options[:max_threads]
+      @cpu_affinity = options[:cpu_affinity]
+      @clean_thread_locals = options[:clean_thread_locals]
+      @clean_fiber_locals = options[:clean_fiber_locals]
       @environment = options[:environment] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
       @connection_options = options[:connection]
       @http1_options = options[:http1]
@@ -174,6 +188,7 @@ module Raptor
       @before_worker_shutdown = Array(options[:before_worker_shutdown])
       @before_refork = Array(options[:before_refork])
       @stats_file = options[:stats_file]
+      @control_server = ControlServer.new(options[:control_url]) { stats_hash } if options[:control_url]
       @pid_file = options[:pid_file]
       @stdout_file = options[:stdout_file]
       @stderr_file = options[:stderr_file]
@@ -202,6 +217,7 @@ module Raptor
       @workers = {}
       @timed_out = Set.new
       @stats = Stats.new(@worker_count)
+      @started_at = Process.clock_gettime(Process::CLOCK_REALTIME)
       @phase = 0
       @phased_restart_requested = false
       @phased_restarting = false
@@ -247,7 +263,9 @@ module Raptor
 
       @bpf_active = ReuseportBPF.setup(@worker_count)
 
+      @control_server&.bind
       @worker_count.times { |index| spawn_worker(index) }
+      @control_server&.start
 
       stats_file_thread = if @stats_file
         Thread.new do
@@ -274,6 +292,7 @@ module Raptor
       Systemd.notify("STOPPING=1")
       stop_workers
       stats_file_thread&.join
+      @control_server&.shutdown
       File.delete(@stats_file) rescue nil if @stats_file
       File.delete(@pid_file) rescue nil if @pid_file
       @stats.unmap
@@ -291,8 +310,57 @@ module Raptor
       @stats.all
     end
 
+    # 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
+      worker_stats = @stats.all
+      worker_status = @workers.sort.map do |index, pid|
+        stat = worker_stats[index]
+        stat = {} unless stat && stat[:pid] == pid
+        capacity = stat.fetch(:thread_capacity, 0)
+        active = stat.fetch(:busy_threads, 0)
+        total_work = stat.fetch(:backlog, 0)
+
+        {
+          started_at: timestamp(stat.fetch(:started_at, 0)),
+          pid: pid,
+          index: index,
+          phase: stat.fetch(:phase, @phase),
+          booted: stat.fetch(:booted, false),
+          last_checkin: timestamp(stat.fetch(:last_checkin, 0)),
+          last_status: {
+            backlog: [total_work - active, 0].max,
+            running: capacity,
+            pool_capacity: [capacity - total_work, 0].max,
+            busy_threads: active,
+            max_threads: capacity,
+            requests_count: stat.fetch(:requests, 0),
+          },
+        }
+      end
+
+      {
+        started_at: timestamp(@started_at),
+        workers: worker_status.length,
+        phase: @phase,
+        booted_workers: worker_status.count { |worker| worker[:booted] },
+        old_workers: worker_status.count { |worker| worker[:phase] != @phase },
+        worker_status: worker_status,
+      }
+    end
+
     private
 
+    # @rbs (Float timestamp) -> String
+    def timestamp(timestamp)
+      Time.at(timestamp).utc.iso8601(6)
+    end
+
     # 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.
@@ -700,6 +768,7 @@ module Raptor
       stop_workers
       @binder.clear_close_on_exec
       ENV[INHERITED_FDS_ENV] = JSON.generate(@binder.inheritable_fds)
+      @control_server&.shutdown
       File.delete(@stats_file) rescue nil if @stats_file
       File.delete(@pid_file) rescue nil if @pid_file
       @stats.unmap
@@ -731,7 +800,7 @@ module Raptor
       trap("USR2", "IGNORE")
       trap("URG") { promote_to_seed = true } if @fork_r
 
-      Raptor::CPU.pin(index) if Raptor::CPU.count >= @worker_count
+      Raptor::CPU.pin(index) if @cpu_affinity && Raptor::CPU.count >= @worker_count
 
       started_at = Process.clock_gettime(Process::CLOCK_REALTIME)
       request_count = 0
@@ -762,6 +831,8 @@ module Raptor
         connection_options: @connection_options,
         http1_options: @http1_options,
         access_log_io: @access_log_io,
+        clean_thread_locals: @clean_thread_locals,
+        clean_fiber_locals: @clean_fiber_locals,
         on_error: @on_error
       )
       http2 = Http2.new(
@@ -770,6 +841,8 @@ module Raptor
         connection_options: @connection_options,
         http2_options: @http2_options,
         access_log_io: @access_log_io,
+        clean_thread_locals: @clean_thread_locals,
+        clean_fiber_locals: @clean_fiber_locals,
         on_error: @on_error
       )
       http1_ractor_pool = RactorPool.new(
@@ -829,7 +902,7 @@ module Raptor
       )
       server_thread = server.run
 
-      @before_worker_boot.each(&:call)
+      @before_worker_boot.each { |hook| hook.parameters.empty? ? hook.call : hook.call(index) }
 
       Log.info "Worker #{index} booted"
 
@@ -865,7 +938,7 @@ module Raptor
         @before_refork.each(&:call)
         server.stop_accepting
       else
-        @before_worker_shutdown.each(&:call)
+        @before_worker_shutdown.each { |hook| hook.parameters.empty? ? hook.call : hook.call(index) }
         server.shutdown
       end
 

data/lib/raptor/control_server.rb

@@ -0,0 +1,131 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "uri"
+
+module Raptor
+  # Serves cluster statistics over a Unix socket.
+  #
+  class ControlServer
+    # @rbs @path: String
+    # @rbs @stats: ^() -> Hash[Symbol, untyped]
+    # @rbs @server: UNIXServer?
+    # @rbs @client: UNIXSocket?
+    # @rbs @thread: Thread?
+    # @rbs @running: bool
+    # @rbs @mutex: Mutex
+
+    # 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(url, &stats)
+      uri = URI(url)
+      raise ArgumentError, "control_url must use unix://" unless uri.scheme == "unix" && !uri.path.empty?
+
+      @path = uri.path
+      @stats = stats
+      @server = nil
+      @client = nil
+      @thread = nil
+      @running = false
+      @mutex = Mutex.new
+    end
+
+    # Binds the Unix socket.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def bind
+      remove_stale_socket
+      @server = UNIXServer.new(@path)
+    end
+
+    # Starts serving requests in a background thread.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def start
+      @running = true
+      owner_pid = Process.pid
+      at_exit { File.delete(@path) rescue nil if Process.pid == owner_pid }
+
+      @thread = Thread.new do
+        Thread.current.name = "Control Server"
+
+        serve
+      end
+    end
+
+    # Stops serving and removes the socket.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown
+      @running = false
+      @mutex.synchronize do
+        @server&.close
+        @client&.close
+      end
+      @thread&.join
+      File.delete(@path) rescue nil
+    end
+
+    private
+
+    # @rbs () -> void
+    def remove_stale_socket
+      return unless File.exist?(@path)
+
+      begin
+        UNIXSocket.new(@path).close
+        raise "Socket #{@path.inspect} is already in use"
+      rescue Errno::ECONNREFUSED
+        File.delete(@path)
+      end
+    end
+
+    # @rbs () -> void
+    def serve
+      while @running
+        readable, = IO.select([@server], nil, nil, 1)
+        next unless readable
+
+        @mutex.synchronize do
+          client = @server.accept_nonblock(exception: false)
+          @client = client if client.is_a?(UNIXSocket)
+        end
+        handle(@client) if @client
+      end
+    rescue IOError, Errno::EBADF
+    end
+
+    # @rbs (UNIXSocket client) -> void
+    def handle(client)
+      request_line = client.gets
+      while line = client.gets
+        break if line == "\r\n"
+      end
+
+      if request_line&.start_with?("GET /stats ")
+        body = JSON.generate(@stats.call)
+        client.write("HTTP/1.0 200 OK\r\nContent-Type: application/json\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}")
+      else
+        client.write("HTTP/1.0 404 Not Found\r\nContent-Length: 0\r\n\r\n")
+      end
+    rescue IOError, SystemCallError
+    ensure
+      client.close rescue nil
+      @mutex.synchronize { @client = nil }
+    end
+  end
+end

data/lib/raptor/http1.rb

@@ -10,6 +10,7 @@ require "rack"
 
 require_relative "http"
 require_relative "raptor_http"
+require_relative "thread_locals"
 
 module Raptor
   # Parses HTTP/1.x requests and dispatches them to the Rack
@@ -23,8 +24,7 @@ module Raptor
     FILE_CHUNK_SIZE = 64 * 1024
     READ_BUFFER_SIZE = 64 * 1024
     RESPONSE_BUFFER_CAPACITY = 4 * 1024
-    KEEPALIVE_READ_TIMEOUT = 0.001
-    MAX_KEEPALIVE_REQUESTS = 100
+    MAX_KEEPALIVE_REQUESTS = 1000
 
     HTTP_10 = "HTTP/1.0"
     HTTP_11 = "HTTP/1.1"
@@ -168,6 +168,8 @@ module Raptor
     # @rbs @body_spool_threshold: Integer?
     # @rbs @max_keepalive_requests: Integer
     # @rbs @access_log_io: IO?
+    # @rbs @clean_thread_locals: bool
+    # @rbs @clean_fiber_locals: bool
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
     # @rbs @running: AtomicBoolean
     # @rbs @env_template: Hash[String, untyped]
@@ -183,11 +185,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(app, server_port, connection_options: {}, http1_options: {}, access_log_io: nil, on_error: nil)
+    # @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(app, server_port, connection_options: {}, http1_options: {}, access_log_io: nil, clean_thread_locals: true, clean_fiber_locals: false, on_error: nil)
       @app = app
       @server_port = server_port
       @server_port_string = server_port.to_s.freeze
@@ -196,6 +200,8 @@ module Raptor
       @body_spool_threshold = connection_options[:body_spool_threshold]
       @max_keepalive_requests = http1_options[:max_keepalive_requests] || MAX_KEEPALIVE_REQUESTS
       @access_log_io = access_log_io
+      @clean_thread_locals = clean_thread_locals
+      @clean_fiber_locals = clean_fiber_locals
       @on_error = on_error
       @running = AtomicBoolean.new(true)
       @env_template = {
@@ -373,7 +379,7 @@ module Raptor
     #
     # @rbs (TCPSocket socket) -> String
     def read_into_thread_buffer(socket)
-      buffer = (Thread.current[:raptor_read_buffer] ||= String.new(capacity: READ_BUFFER_SIZE))
+      buffer = ThreadLocals.fetch(:raptor_read_buffer) { String.new(capacity: READ_BUFFER_SIZE) }
       socket.read_nonblock(READ_BUFFER_SIZE, buffer)
 
       while socket.respond_to?(:pending) && socket.pending.positive?
@@ -392,7 +398,7 @@ module Raptor
     #
     # @rbs (String buffer) -> [Hash[String, untyped], Hash[Symbol, untyped], Integer, HttpParser]
     def parse_next_request(buffer)
-      parser = (Thread.current[:raptor_http_parser] ||= HttpParser.new)
+      parser = ThreadLocals.fetch(:raptor_http_parser) { HttpParser.new }
       parser.reset
       env = @env_template.dup
       nread = parser.execute(env, buffer, 0)
@@ -505,6 +511,19 @@ 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(socket, env, parse_data, body, request_count, remote_addr, url_scheme)
+      if @clean_fiber_locals
+        Fiber.new { perform_request(socket, env, parse_data, body, request_count, remote_addr, url_scheme) }.resume
+      else
+        perform_request(socket, env, parse_data, body, request_count, remote_addr, url_scheme)
+      end
+    ensure
+      ThreadLocals.clear if @clean_thread_locals
+    end
+
+    # 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(socket, env, parse_data, body, request_count, remote_addr, url_scheme)
       rack_env = nil
       status = nil
       headers = nil
@@ -571,8 +590,9 @@ module Raptor
     end
 
     # 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
@@ -591,7 +611,7 @@ module Raptor
           return
         end
 
-        unless socket.wait_readable(KEEPALIVE_READ_TIMEOUT)
+        unless socket.wait_readable(0)
           reactor.persist(socket, id, request_count, remote_addr: remote_addr, url_scheme: url_scheme)
           return
         end
@@ -626,7 +646,7 @@ module Raptor
 
         request_count += 1
 
-        if thread_pool.queue_size >= thread_pool.size
+        if thread_pool.queue_size.positive?
           thread_pool << proc do
             process_client(
               socket,
@@ -900,7 +920,7 @@ module Raptor
 
       response = build_status_line(http_version, status)
 
-      corked = !keep_alive
+      corked = !keep_alive && !body.respond_to?(:to_ary) && !no_body && !response_hijack
       cork_socket(socket) if corked
 
       if response_hijack
@@ -983,7 +1003,7 @@ module Raptor
     # @rbs (String http_version, Integer status) -> String
     def build_status_line(http_version, status)
       cache = http_version == HTTP_11 ? STATUS_LINE_CACHE_11 : STATUS_LINE_CACHE_10
-      response = (Thread.current[:raptor_response_buffer] ||= String.new(capacity: RESPONSE_BUFFER_CAPACITY))
+      response = ThreadLocals.fetch(:raptor_response_buffer) { String.new(capacity: RESPONSE_BUFFER_CAPACITY) }
       response.clear
       response << cache[status]
       response

data/lib/raptor/http2.rb

@@ -8,6 +8,7 @@ require "rack"
 
 require_relative "http"
 require_relative "raptor_http2"
+require_relative "thread_locals"
 
 module Raptor
   # Handles HTTP/2 request processing and Rack application integration.
@@ -267,6 +268,8 @@ module Raptor
     # @rbs @server_port: Integer
     # @rbs @write_timeout: Integer
     # @rbs @access_log_io: IO?
+    # @rbs @clean_thread_locals: bool
+    # @rbs @clean_fiber_locals: bool
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
     # @rbs @initial_settings_frame: String
 
@@ -285,15 +288,19 @@ 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(app, server_port, connection_options: {}, http2_options: {}, access_log_io: nil, on_error: nil)
+    # @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(app, server_port, connection_options: {}, http2_options: {}, access_log_io: nil, clean_thread_locals: true, clean_fiber_locals: false, on_error: nil)
       @app = app
       @server_port = server_port
       @write_timeout = connection_options[:write_timeout] || Http::WRITE_TIMEOUT
       @access_log_io = access_log_io
+      @clean_thread_locals = clean_thread_locals
+      @clean_fiber_locals = clean_fiber_locals
       @on_error = on_error
 
       parser = Http2Parser.new
@@ -730,6 +737,19 @@ 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(socket, writer, flow_control, stream_id, headers, body, remote_addr:)
+      if @clean_fiber_locals
+        Fiber.new { perform_stream_request(socket, writer, flow_control, stream_id, headers, body, remote_addr:) }.resume
+      else
+        perform_stream_request(socket, writer, flow_control, stream_id, headers, body, remote_addr:)
+      end
+    ensure
+      ThreadLocals.clear if @clean_thread_locals
+    end
+
+    # 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(socket, writer, flow_control, stream_id, headers, body, remote_addr:)
       env = build_rack_env(headers, body, remote_addr: remote_addr)
       status, response_headers, response_body = @app.call(env)
 

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.1"
 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