raptor 0.25.0 → 0.26.0

data/lib/raptor/worker.rb

@@ -0,0 +1,200 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "atomic-ruby/atomic_thread_pool"
+require "ractor-pool"
+
+require_relative "http1"
+require_relative "http2"
+require_relative "reactor"
+require_relative "server"
+
+module Raptor
+  # Runs the request-handling stack shared by forked and embedded servers.
+  #
+  class Worker
+    # @rbs @app: untyped
+    # @rbs @listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener]
+    # @rbs @port: Integer
+    # @rbs @options: Hash[Symbol, untyped]
+    # @rbs @http1_ractors: Integer
+    # @rbs @http2_ractors: Integer
+    # @rbs @access_log_io: IO?
+    # @rbs @worker_index: Integer?
+    # @rbs @stopped: bool
+    # @rbs @http1: Http1?
+    # @rbs @http2: Http2?
+    # @rbs @http1_ractor_pool: RactorPool?
+    # @rbs @http2_ractor_pool: RactorPool?
+    # @rbs @reactor_thread: Thread?
+    # @rbs @server: Server?
+    # @rbs @server_thread: Thread?
+
+    attr_reader :requests #: Integer
+    attr_reader :reactor #: Reactor?
+    attr_reader :thread_pool #: AtomicThreadPool?
+
+    # Creates a serving stack using the supplied listeners and configuration.
+    #
+    # @rbs (untyped app, listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener], port: Integer, options: Hash[Symbol, untyped], http1_ractors: Integer, http2_ractors: Integer, ?access_log_io: IO?, ?worker_index: Integer?) -> void
+    def initialize(app, listeners:, port:, options:, http1_ractors:, http2_ractors:, access_log_io: nil, worker_index: nil)
+      @app = app
+      @listeners = listeners
+      @port = port
+      @options = options
+      @http1_ractors = http1_ractors
+      @http2_ractors = http2_ractors
+      @access_log_io = access_log_io
+      @worker_index = worker_index
+      @requests = 0
+      @stopped = false
+    end
+
+    # Starts the application pool, protocol parsers, reactor, and acceptor.
+    #
+    # @rbs () -> void
+    def start
+      counting_app = ->(env) {
+        @requests += 1
+        @app.call(env)
+      }
+      @thread_pool = AtomicThreadPool.new(size: @options[:threads], max_size: @options[:max_threads])
+      @http1 = Http1.new(
+        counting_app,
+        @port,
+        connection_options: @options[:connection],
+        http1_options: @options[:http1],
+        access_log_io: @access_log_io,
+        clean_thread_locals: @options[:clean_thread_locals],
+        clean_fiber_locals: @options[:clean_fiber_locals],
+        on_error: @options[:on_error]
+      )
+      @http2 = Http2.new(
+        counting_app,
+        @port,
+        connection_options: @options[:connection],
+        http2_options: @options[:http2],
+        access_log_io: @access_log_io,
+        clean_thread_locals: @options[:clean_thread_locals],
+        clean_fiber_locals: @options[:clean_fiber_locals],
+        on_error: @options[:on_error]
+      )
+      @http1_ractor_pool = RactorPool.new(
+        size: @http1_ractors,
+        worker: @http1.parser_worker,
+        name: "HTTP/1.1"
+      ) do |parsed_result|
+        begin
+          @http1.handle_parsed_request(parsed_result, @reactor, @thread_pool)
+        rescue => error
+          Log.rescued_error(error)
+        end
+      end
+
+      if @listeners.any? { |listener| listener.is_a?(Binder::SslListener) || listener.is_a?(Binder::H2cListener) }
+        @http2_ractor_pool = RactorPool.new(
+          size: @http2_ractors,
+          worker: @http2.parser_worker,
+          name: "HTTP/2"
+        ) do |parsed_result|
+          begin
+            @http2.handle_parsed_request(parsed_result, @reactor, @thread_pool)
+          rescue => error
+            Log.rescued_error(error)
+          end
+        end
+      end
+
+      @reactor = Reactor.new(
+        @http1,
+        @http1_ractor_pool,
+        @http2_ractor_pool,
+        @thread_pool,
+        connection_options: @options[:connection],
+        http1_options: @options[:http1],
+        http2_options: @options[:http2]
+      )
+      @reactor_thread = @reactor.run
+      @server = Server.new(
+        @reactor,
+        @thread_pool,
+        @http1,
+        @http2,
+        connection_options: @options[:connection],
+        drain_accept_queue: @options[:drain_accept_queue],
+        listeners: @listeners,
+        worker_index: @worker_index
+      )
+      @server_thread = @server.run
+    rescue
+      shutdown
+      raise
+    end
+
+    # Returns whether both serving threads are still running.
+    #
+    # @rbs () -> bool
+    def running?
+      !!(@server_thread&.alive? && @reactor_thread&.alive?)
+    end
+
+    # Waits until serving stops, propagating background thread failures.
+    #
+    # @rbs () -> void
+    def join
+      @server_thread.join(0.1) while running?
+      @server_thread.value if @server_thread && !@server_thread.alive?
+      @reactor_thread.value if @reactor_thread && !@reactor_thread.alive?
+    end
+
+    # Drains requests and releases the serving threads and parser Ractors.
+    # A seed keeps its listeners open for the cluster to manage.
+    #
+    # @rbs (?close_listeners: bool) -> void
+    def shutdown(close_listeners: true)
+      return if @stopped
+
+      @stopped = true
+      begin
+        if close_listeners
+          @server&.shutdown
+        else
+          @server&.stop_accepting
+        end
+        @server_thread&.join
+      ensure
+        @http1&.shutdown
+        if @reactor_thread&.alive?
+          @http2&.shutdown(@reactor)
+          @reactor.drain_detached_bodies(@options[:worker_drain_timeout])
+        end
+        drain_thread_pool if @thread_pool
+        @reactor&.shutdown
+        begin
+          @reactor_thread&.join
+        ensure
+          @http1_ractor_pool&.shutdown
+          @http2_ractor_pool&.shutdown
+        end
+      end
+    end
+
+    private
+
+    # Waits for app work to finish within the configured drain timeout.
+    #
+    # @rbs () -> void
+    def drain_thread_pool
+      drain_thread = Thread.new do
+        Thread.current.name = "Thread Pool Drain"
+
+        @thread_pool.shutdown
+      end
+      return if drain_thread.join(@options[:worker_drain_timeout])
+
+      Log.warn "Force-killing in-flight app threads after #{@options[:worker_drain_timeout]}s drain timeout"
+      @thread_pool.instance_variable_get(:@threads).each(&:kill)
+      drain_thread.join
+    end
+  end
+end

data/sig/generated/rackup/handler/raptor.rbs

@@ -7,16 +7,16 @@ module Rackup
     module Raptor
       DEFAULT_OPTIONS: untyped
 
-      # Boots a Raptor cluster serving the given Rack application.
+      # Serves the given Rack application using the handler options.
       #
       # @param app [#call] the Rack application to serve
       # @param options [Hash] handler options provided by Rackup or the host
-      # @yield before the cluster starts running
-      # @yieldparam cluster [::Raptor::Cluster] the cluster instance
+      # @yield before the server starts running
+      # @yieldparam server [::Raptor::Cluster, ::Raptor::Embedded] the server instance
       # @return [void]
       #
-      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
-      def self.run: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, **untyped options) { (::Raptor::Cluster) -> void } -> void
+      # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, **untyped options) { (::Raptor::Cluster | ::Raptor::Embedded) -> void } -> void
+      def self.run: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, **untyped options) { (::Raptor::Cluster | ::Raptor::Embedded) -> void } -> void
 
       # Returns the handler-specific options surfaced by `rackup --help`.
       #
@@ -25,17 +25,17 @@ module Rackup
       # @rbs () -> Hash[String, String]
       def self.valid_options: () -> Hash[String, String]
 
-      # Builds a Raptor cluster options hash from Rack handler options.
+      # Builds Raptor server configuration from Rack handler options.
       #
       # Options not explicitly supplied by the user (per the `:user_supplied_options`
       # key) are treated as host-provided defaults.
       #
       # @param app [#call] the Rack application to serve
       # @param options [Hash] handler options provided by Rackup or the host
-      # @return [Hash{Symbol => untyped}] cluster configuration
+      # @return [Hash{Symbol => untyped}] server configuration
       #
       # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
-      def self.build_cluster_options: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
+      def self.build_options: (^(Hash[String, untyped]) -> [ Integer, Hash[String, String | Array[String]], untyped ] app, Hash[Symbol, untyped] options) -> Hash[Symbol, untyped]
     end
   end
 end

data/sig/generated/raptor/cli.rbs

@@ -81,6 +81,11 @@ module Raptor
 
     private
 
+    # Serves in the CLI process until interrupted or terminated.
+    #
+    # @rbs () -> void
+    def run_embedded: () -> void
+
     # Reads and prints the stats file.
     #
     # @return [void]

data/sig/generated/raptor/cluster.rbs

@@ -44,10 +44,6 @@ module Raptor
     # @rbs (Integer worker_count, ?cores: Integer) -> Integer
     def self.default_http2_ractor_count: (Integer worker_count, ?cores: Integer) -> Integer
 
-    @stats_file: String?
-
-    @control_server: ControlServer?
-
     @pid_file: String?
 
     @stdout_file: String?
@@ -62,12 +58,18 @@ module Raptor
 
     @launch_argv: Array[String]?
 
-    @on_error: (^(Hash[String, untyped]?, Exception) -> void)?
-
     @binder: Binder
 
+    @server_port: Integer
+
+    @app: untyped
+
     @plugins: Array[Plugin]
 
+    @control_server: ControlServer?
+
+    @stats_file: String?
+
     @before_refork: Array[Proc]
 
     @before_worker_shutdown: Array[Proc]
@@ -84,12 +86,6 @@ module Raptor
 
     @worker_boot_timeout: Integer
 
-    @http2_options: Hash[Symbol, untyped]
-
-    @http1_options: Hash[Symbol, untyped]
-
-    @connection_options: Hash[Symbol, untyped]
-
     @bpf_active: bool
 
     @resp_w: IO?
@@ -130,16 +126,8 @@ module Raptor
 
     @shutdown: bool
 
-    @app: untyped
-
-    @server_port: Integer
-
     @environment: String
 
-    @clean_fiber_locals: bool
-
-    @clean_thread_locals: bool
-
     @cpu_affinity: bool
 
     @max_thread_count: (Integer | Float)?
@@ -152,8 +140,6 @@ module Raptor
 
     @worker_count: Integer
 
-    @drain_accept_queue: bool
-
     # Returns the cluster configuration available to plugins.
     #
     # @return [Hash{Symbol => untyped}]
@@ -420,16 +406,6 @@ module Raptor
     # @rbs (Integer index) -> void
     def run_seed_loop: (Integer index) -> void
 
-    # Shuts down the worker's application thread pool, force-killing the
-    # underlying threads if in-flight requests have not finished within
-    # `worker_drain_timeout` seconds.
-    #
-    # @param thread_pool [AtomicThreadPool] the worker's thread pool
-    # @return [void]
-    #
-    # @rbs (AtomicThreadPool thread_pool) -> void
-    def drain_thread_pool: (AtomicThreadPool thread_pool) -> void
-
     # Returns a human-readable description of how a process exited.
     #
     # @param status [Process::Status] the exit status of the process

data/sig/generated/raptor/embedded.rbs

@@ -0,0 +1,68 @@
+# Generated from lib/raptor/embedded.rb with RBS::Inline
+
+module Raptor
+  # Serves an existing Rack application in the caller's process without
+  # installing signal handlers or changing process-wide configuration.
+  class Embedded
+    @worker: Worker?
+
+    @binder: Binder?
+
+    @stopped: bool
+
+    @started: bool
+
+    @lifecycle_available: AtomicConditionVariable
+
+    @lifecycle_owner: Atom
+
+    @log: bool
+
+    @binds: Array[String]
+
+    @options: Hash[Symbol, untyped]
+
+    @app: untyped
+
+    attr_reader port: Integer
+
+    attr_reader addresses: Array[String]
+
+    # Creates an in-process server. A port of zero selects an available port.
+    # Thread and protocol options follow the regular server configuration.
+    # Set log to report startup information.
+    #
+    # @rbs (untyped app, ?host: String, ?port: Integer, ?log: bool, **untyped options) -> void
+    def initialize: (untyped app, ?host: String, ?port: Integer, ?log: bool, **untyped options) -> void
+
+    # Starts serving and returns once the request-handling stack is ready.
+    # Startup errors are raised in the calling thread.
+    #
+    # @rbs () -> Embedded
+    def start: () -> Embedded
+
+    # Starts serving and waits until shutdown.
+    #
+    # @rbs () -> void
+    def run: () -> void
+
+    # Drains requests and closes the server's sockets, threads, and Ractors.
+    # Calling shutdown more than once has no effect.
+    #
+    # @rbs () -> void
+    def shutdown: () -> void
+
+    # Waits for termination and propagates serving thread failures.
+    #
+    # @rbs () -> void
+    def join: () -> void
+
+    private
+
+    # @rbs () -> void
+    def log_initialization: () -> void
+
+    # @rbs () { () -> untyped } -> untyped
+    def with_lifecycle: () { () -> untyped } -> untyped
+  end
+end

data/sig/generated/raptor/worker.rbs

@@ -0,0 +1,77 @@
+# Generated from lib/raptor/worker.rb with RBS::Inline
+
+module Raptor
+  # Runs the request-handling stack shared by forked and embedded servers.
+  class Worker
+    @server_thread: Thread?
+
+    @server: Server?
+
+    @reactor_thread: Thread?
+
+    @http2_ractor_pool: RactorPool?
+
+    @http1_ractor_pool: RactorPool?
+
+    @http2: Http2?
+
+    @http1: Http1?
+
+    @stopped: bool
+
+    @worker_index: Integer?
+
+    @access_log_io: IO?
+
+    @http2_ractors: Integer
+
+    @http1_ractors: Integer
+
+    @options: Hash[Symbol, untyped]
+
+    @port: Integer
+
+    @listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener]
+
+    @app: untyped
+
+    attr_reader requests: Integer
+
+    attr_reader reactor: Reactor?
+
+    attr_reader thread_pool: AtomicThreadPool?
+
+    # Creates a serving stack using the supplied listeners and configuration.
+    #
+    # @rbs (untyped app, listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener], port: Integer, options: Hash[Symbol, untyped], http1_ractors: Integer, http2_ractors: Integer, ?access_log_io: IO?, ?worker_index: Integer?) -> void
+    def initialize: (untyped app, listeners: Array[TCPServer | UNIXServer | Binder::SslListener | Binder::H2cListener], port: Integer, options: Hash[Symbol, untyped], http1_ractors: Integer, http2_ractors: Integer, ?access_log_io: IO?, ?worker_index: Integer?) -> void
+
+    # Starts the application pool, protocol parsers, reactor, and acceptor.
+    #
+    # @rbs () -> void
+    def start: () -> void
+
+    # Returns whether both serving threads are still running.
+    #
+    # @rbs () -> bool
+    def running?: () -> bool
+
+    # Waits until serving stops, propagating background thread failures.
+    #
+    # @rbs () -> void
+    def join: () -> void
+
+    # Drains requests and releases the serving threads and parser Ractors.
+    # A seed keeps its listeners open for the cluster to manage.
+    #
+    # @rbs (?close_listeners: bool) -> void
+    def shutdown: (?close_listeners: bool) -> void
+
+    private
+
+    # Waits for app work to finish within the configured drain timeout.
+    #
+    # @rbs () -> void
+    def drain_thread_pool: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Joshua Young
@@ -134,6 +134,7 @@ files:
 - ".buildkite/pipeline.yml"
 - ".dockerignore"
 - ".mise.toml"
+- AGENTS.md
 - Brewfile
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -161,6 +162,7 @@ files:
 - lib/raptor/cluster.rb
 - lib/raptor/control_server.rb
 - lib/raptor/detached_body.rb
+- lib/raptor/embedded.rb
 - lib/raptor/http.rb
 - lib/raptor/http1.rb
 - lib/raptor/http2.rb
@@ -173,6 +175,7 @@ files:
 - lib/raptor/systemd.rb
 - lib/raptor/thread_locals.rb
 - lib/raptor/version.rb
+- lib/raptor/worker.rb
 - sig/generated/rackup/handler/raptor.rbs
 - sig/generated/raptor.rbs
 - sig/generated/raptor/binder.rbs
@@ -180,6 +183,7 @@ files:
 - sig/generated/raptor/cluster.rbs
 - sig/generated/raptor/control_server.rbs
 - sig/generated/raptor/detached_body.rbs
+- sig/generated/raptor/embedded.rbs
 - sig/generated/raptor/http.rbs
 - sig/generated/raptor/http1.rbs
 - sig/generated/raptor/http2.rbs
@@ -192,6 +196,7 @@ files:
 - sig/generated/raptor/systemd.rbs
 - sig/generated/raptor/thread_locals.rbs
 - sig/generated/raptor/version.rbs
+- sig/generated/raptor/worker.rbs
 homepage: https://github.com/joshuay03/raptor
 licenses:
 - MIT