raptor 0.25.0 → 0.27.0

data/lib/raptor/embedded.rb

@@ -0,0 +1,225 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "atomic-ruby/atom"
+require "atomic-ruby/atomic_condition_variable"
+
+require_relative "cli"
+require_relative "worker"
+
+module Raptor
+  # Serves an existing Rack application in the caller's process without
+  # installing signal handlers or changing process-wide configuration.
+  #
+  class Embedded
+    # @rbs @app: untyped
+    # @rbs @options: Hash[Symbol, untyped]
+    # @rbs @binds: Array[String]
+    # @rbs @log: bool
+    # @rbs @lifecycle_owner: Atom
+    # @rbs @lifecycle_available: AtomicConditionVariable
+    # @rbs @started: bool
+    # @rbs @stopped: bool
+    # @rbs @binder: Binder?
+    # @rbs @worker: Worker?
+
+    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(app, host: "127.0.0.1", port: 0, log: false, **options)
+      @app = app
+      @port = port
+      @log = log
+      @addresses = []
+      @options = CLI::DEFAULT_OPTIONS.merge(options)
+      CLI::NESTED_OPTION_KEYS.each do |key|
+        @options[key] = CLI::DEFAULT_OPTIONS[key].merge(options[key] || {})
+      end
+      @options[:max_threads] = CLI.parse_max_threads(@options[:max_threads], threads: @options[:threads])
+      @binds = options[:binds] || ["tcp://#{host}:#{port}"]
+      @lifecycle_owner = Atom.new(nil)
+      @lifecycle_available = AtomicConditionVariable.new
+      @started = false
+      @stopped = false
+    end
+
+    # Starts serving and returns once the request-handling stack is ready.
+    # Startup errors are raised in the calling thread.
+    #
+    # @rbs () -> Embedded
+    def start
+      with_lifecycle do
+        raise ThreadError, "server has already been started or stopped" if @started || @stopped
+
+        @started = true
+        begin
+          @binder = Binder.new(@binds, socket_backlog: @options[:socket_backlog])
+          @port = @binder.server_port
+          @addresses = @binder.addresses
+          start_worker
+        rescue
+          @stopped = true
+          @binder&.close
+          raise
+        end
+        log_initialization if @log
+      end
+
+      self
+    end
+
+    # Starts serving and waits until shutdown.
+    #
+    # @rbs () -> void
+    def run
+      start
+      join
+    end
+
+    # Drains serving work while retaining the bound listeners for resume.
+    # Connections may queue, but requests are not served while paused.
+    # Existing keep-alive connections close. Repeated pauses have no effect.
+    #
+    # Pause before master forks and resume in the parent. Close the inherited
+    # instance before other worker boot hooks, and shut down when the plugin stops.
+    #
+    # @example From a plugin's start callback
+    #   @server = Raptor::Embedded.new(app, port: 9293).start
+    #   cluster.options[:before_fork] << proc { @server.pause }
+    #   cluster.options[:after_fork] << proc { @server.resume }
+    #   cluster.options[:before_worker_boot].unshift(proc { @server.shutdown })
+    #
+    # @rbs () -> Embedded
+    def pause
+      with_lifecycle do
+        raise ThreadError, "server is not running" unless @started && !@stopped
+
+        begin
+          @worker&.shutdown(close_listeners: false)
+          @worker = nil
+        rescue
+          @stopped = true
+          @binder&.close
+          raise
+        end
+      end
+
+      self
+    end
+
+    # Resumes serving on the retained listeners. Has no effect while running.
+    # Shutdown remains terminal. Startup failures release the listeners and propagate.
+    #
+    # @rbs () -> Embedded
+    def resume
+      with_lifecycle do
+        raise ThreadError, "server has not been started or has been stopped" unless @started && !@stopped
+
+        begin
+          start_worker unless @worker
+        rescue
+          @stopped = true
+          @binder&.close
+          raise
+        end
+      end
+
+      self
+    end
+
+    # Drains requests and closes the server's sockets, threads, and Ractors.
+    # Calling shutdown more than once has no effect.
+    #
+    # @rbs () -> void
+    def shutdown
+      with_lifecycle do
+        return if @stopped
+
+        @stopped = true
+        begin
+          @worker&.shutdown
+        ensure
+          @binder&.close
+        end
+      end
+    end
+
+    # Waits across pauses until termination and propagates serving failures.
+    #
+    # @rbs () -> void
+    def join
+      started = with_lifecycle { @started }
+      raise ThreadError, "server has not been started" unless started
+
+      loop do
+        worker, stopped = with_lifecycle { [@worker, @stopped] }
+        break if stopped
+
+        if worker
+          worker.join
+          break if with_lifecycle { @worker.equal?(worker) }
+        else
+          @lifecycle_available.wait { @worker || @stopped }
+        end
+      end
+    ensure
+      shutdown if started
+    end
+
+    private
+
+    # @rbs () -> void
+    def start_worker
+      @worker = Worker.new(
+        @app,
+        listeners: @binder.listeners,
+        port: @port,
+        options: @options,
+        http1_ractors: @options[:http1][:ractors] || Cluster.default_http1_ractor_count(1),
+        http2_ractors: @options[:http2][:ractors] || Cluster.default_http2_ractor_count(1)
+      )
+      @worker.start
+    end
+
+    # @rbs () -> void
+    def log_initialization
+      environment = @options[:environment] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      thread_count = @options[:threads]
+      max_threads = @options[:max_threads]
+      thread_limit = if max_threads == Float::INFINITY
+        " (scaling, no limit)"
+      elsif max_threads > thread_count
+        " (scaling up to #{max_threads})"
+      else
+        ""
+      end
+
+      Log.info "Server initializing:"
+      Log.info "├─ Version: #{VERSION}"
+      Log.info "├─ Ruby Version: #{RUBY_DESCRIPTION}"
+      Log.info "├─ Environment: #{environment}"
+      Log.info "├─ PID: #{Process.pid}"
+      Log.info "├─ #{thread_count} worker thread#{"s" if thread_count > 1}#{thread_limit}"
+      Log.info "└─ Listening on #{@addresses.join(", ")}"
+    end
+
+    # @rbs () { () -> untyped } -> untyped
+    def with_lifecycle
+      thread = Thread.current
+      @lifecycle_available.wait do
+        @lifecycle_owner.swap { |owner| owner || thread }.equal?(thread)
+      end
+      yield
+    ensure
+      if @lifecycle_owner.value.equal?(thread)
+        @lifecycle_owner.swap { nil }
+        @lifecycle_available.broadcast
+      end
+    end
+  end
+end

data/lib/raptor/plugin.rb

@@ -53,6 +53,7 @@ module Raptor
 
     # Starts in the master before workers fork. Override to open resources
     # and append callbacks to the cluster's lifecycle hook arrays.
+    # See {Cluster#initialize} for hooks and {Embedded#pause} for fork-safe Rack listeners.
     #
     # @rbs (Cluster cluster) -> void
     def start(cluster)

data/lib/raptor/reactor.rb

@@ -263,12 +263,21 @@ module Raptor
     #
     # @rbs () -> Thread
     def run
-      Thread.new do
+      ready = AtomicConditionVariable.new
+      startup_error = nil
+      thread = Thread.new do
         Thread.current.name = "Reactor"
         @thread = Thread.current
-        selector = IO::Event::Selector.new(Fiber.current)
-        @wakeup = Fiber.new { loop { selector.transfer } }
-        @selector = selector
+        begin
+          selector = IO::Event::Selector.new(Fiber.current)
+          @wakeup = Fiber.new { loop { selector.transfer } }
+          @selector = selector
+        rescue => error
+          startup_error = error
+          ready.signal
+          next
+        end
+        ready.signal
 
         until stopped?
           begin
@@ -310,6 +319,14 @@ module Raptor
         @thread = nil
         @selector.close
       end
+
+      ready.wait { @selector || startup_error }
+      if startup_error
+        thread.join
+        raise startup_error
+      end
+
+      thread
     end
 
     # Adds a new client connection to the reactor.

data/lib/raptor/version.rb

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

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,34 +58,36 @@ 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]
 
+    @after_worker_exit: Array[Proc]
+
+    @after_worker_drain: Array[Proc]
+
     @before_worker_shutdown: Array[Proc]
 
     @before_worker_boot: Array[Proc]
 
+    @after_fork: Array[Proc]
+
     @before_fork: Array[Proc]
 
     @worker_shutdown_timeout: Integer
 
     @worker_drain_timeout: Integer
 
-    @worker_timeout: Integer
-
-    @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?
@@ -126,20 +124,18 @@ module Raptor
 
     @timed_out: Set[Integer]
 
+    @worker_indices: Hash[Integer, Integer]
+
     @workers: Hash[Integer, Integer]
 
     @shutdown: bool
 
-    @app: untyped
+    @worker_timeout: Integer
 
-    @server_port: Integer
+    @worker_boot_timeout: Integer
 
     @environment: String
 
-    @clean_fiber_locals: bool
-
-    @clean_thread_locals: bool
-
     @cpu_affinity: bool
 
     @max_thread_count: (Integer | Float)?
@@ -152,8 +148,6 @@ module Raptor
 
     @worker_count: Integer
 
-    @drain_accept_queue: bool
-
     # Returns the cluster configuration available to plugins.
     #
     # @return [Hash{Symbol => untyped}]
@@ -183,9 +177,12 @@ module Raptor
     # @option options [Integer] :worker_drain_timeout seconds a worker waits for in-flight requests during shutdown before force-killing app threads
     # @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_fork procs called in the master before each direct worker fork, not seed forks
+    # @option options [Array<Proc>] :after_fork procs called in the master after each direct fork attempt, including failures
     # @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>] :after_worker_drain procs called with the worker index after draining, before exit or seed promotion
+    # @option options [Array<Proc>] :after_worker_exit procs called in the master after reaping, with the worker index, pid, and Process::Status
     # @option options [Array<Proc>] :before_refork procs called in a worker before it transitions to a seed
     # @option options [Array<String, Symbol>] :plugins plugins to load and start in order
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
@@ -420,16 +417,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