raptor 0.7.0 → 0.9.0

data/lib/raptor/cluster.rb

@@ -9,11 +9,13 @@ require "ractor-pool"
 
 require_relative "log"
 require_relative "binder"
-require_relative "server"
 require_relative "reactor"
-require_relative "request"
+require_relative "server"
+require_relative "reuseport_bpf"
+require_relative "http1"
 require_relative "http2"
 require_relative "stats"
+require_relative "systemd"
 
 module Raptor
   # Multi-process web server cluster with advanced concurrency architecture.
@@ -41,11 +43,13 @@ module Raptor
   #     workers: 4, ractors: 2, threads: 8,
   #     binds: ["tcp://0.0.0.0:3000"],
   #     rackup: "config.ru",
-  #     client: { first_data_timeout: 30, chunk_data_timeout: 10 }
+  #     connection: { first_data_timeout: 30, chunk_data_timeout: 10 }
   #   }
   #   Cluster.run(options)
   #
   class Cluster
+    INHERITED_FDS_ENV = "RAPTOR_INHERITED_FDS"
+
     # Convenience method to create and run a cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
@@ -56,15 +60,26 @@ module Raptor
       new(options).run
     end
 
+    # @rbs @drain_accept_queue: bool
     # @rbs @worker_count: Integer
     # @rbs @ractor_count: Integer
     # @rbs @thread_count: Integer
-    # @rbs @client_options: Hash[Symbol, Integer]
-    # @rbs @worker_timeout: Integer
+    # @rbs @environment: String
+    # @rbs @connection_options: Hash[Symbol, untyped]
+    # @rbs @http1_options: Hash[Symbol, untyped]
+    # @rbs @http2_options: Hash[Symbol, untyped]
     # @rbs @worker_boot_timeout: Integer
+    # @rbs @worker_timeout: Integer
+    # @rbs @worker_drain_timeout: Integer
     # @rbs @worker_shutdown_timeout: Integer
     # @rbs @stats_file: String?
     # @rbs @pid_file: String?
+    # @rbs @stdout_file: String?
+    # @rbs @stderr_file: String?
+    # @rbs @access_log_file: String?
+    # @rbs @access_log_io: IO?
+    # @rbs @launch_command: String?
+    # @rbs @launch_argv: Array[String]?
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
     # @rbs @binder: Binder
     # @rbs @server_port: Integer
@@ -76,6 +91,8 @@ module Raptor
     # @rbs @phase: Integer
     # @rbs @phased_restart_requested: bool
     # @rbs @phased_restarting: bool
+    # @rbs @hot_restart_requested: bool
+    # @rbs @bpf_active: bool
 
     # Creates a new Cluster with the specified configuration.
     #
@@ -85,34 +102,67 @@ module Raptor
     #
     # @param options [Hash] cluster configuration options
     # @option options [Array<String>] :binds array of bind URIs
+    # @option options [Integer] :socket_backlog kernel listen() queue depth for TCP/SSL listeners
+    # @option options [Boolean] :drain_accept_queue whether to drain the kernel accept queue on shutdown
     # @option options [Integer] :workers number of worker processes
     # @option options [Integer] :ractors number of ractors per worker process
     # @option options [Integer] :threads number of threads per worker process
     # @option options [#call] :app pre-built Rack application
     # @option options [String] :rackup path to Rack configuration file
-    # @option options [Hash] :client client configuration
-    # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
+    # @option options [String, nil] :chdir directory to change to before loading the Rack application, or nil to leave the working directory unchanged
+    # @option options [String, nil] :environment Raptor's application environment label; falls back to `$RAILS_ENV`, then `$RACK_ENV`, then `"development"`
+    # @option options [Hash] :connection per-connection settings shared across protocols
+    # @option options [Hash] :http1 HTTP/1.1-specific settings
+    # @option options [Hash] :http2 HTTP/2-specific settings
     # @option options [Integer] :worker_boot_timeout seconds to wait for a worker to finish booting before killing it
+    # @option options [Integer] :worker_timeout seconds to wait for a booted worker to check in before killing it
+    # @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 [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
     # @option options [String, nil] :pid_file path to write the master PID to, or nil to disable
-    # @option options [#call] :on_error callback invoked with (env, exception) when the Rack app raises
+    # @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
+    # @option options [String, nil] :access_log_file path to write Common Log Format access logs to, reopened on SIGHUP, or nil to disable
+    # @option options [String, nil] :launch_command path of the program to re-exec on hot restart, or nil to disable
+    # @option options [Array<String>, nil] :launch_argv command-line arguments for the hot-restart exec, or nil to disable
+    # @option options [#call, nil] :on_error callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
     # @rbs (Hash[Symbol, untyped] options) -> void
     def initialize(options)
+      @drain_accept_queue = options[:drain_accept_queue]
       @worker_count = options[:workers]
       @ractor_count = options[:ractors]
       @thread_count = options[:threads]
-      @client_options = options[:client]
-      @worker_timeout = options[:worker_timeout]
+      @environment = options[:environment] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      @connection_options = options[:connection]
+      @http1_options = options[:http1]
+      @http2_options = options[:http2]
       @worker_boot_timeout = options[:worker_boot_timeout]
+      @worker_timeout = options[:worker_timeout]
+      @worker_drain_timeout = options[:worker_drain_timeout]
       @worker_shutdown_timeout = options[:worker_shutdown_timeout]
       @stats_file = options[:stats_file]
       @pid_file = options[:pid_file]
+      @stdout_file = options[:stdout_file]
+      @stderr_file = options[:stderr_file]
+      @access_log_file = options[:access_log_file]
+      @access_log_io = nil
+      @launch_command = options[:launch_command]
+      @launch_argv = options[:launch_argv]
       @on_error = options[:on_error]
 
-      @binder = Binder.new(options[:binds])
+      Dir.chdir(options[:chdir]) if options[:chdir]
+
+      inherited_fds = if raw = ENV.delete(INHERITED_FDS_ENV)
+        JSON.parse(raw)
+      elsif (systemd_fds = Systemd.listen_fds).any?
+        Systemd.clear_listen_env
+        pair_systemd_fds(options[:binds], systemd_fds)
+      else
+        {}
+      end
+      @binder = Binder.new(options[:binds], socket_backlog: options[:socket_backlog], inherited_fds: inherited_fds)
       @server_port = @binder.server_port
       @app = options[:app] || Rack::Builder.parse_file(options[:rackup])
       log_initialization
@@ -124,14 +174,15 @@ module Raptor
       @phase = 0
       @phased_restart_requested = false
       @phased_restarting = false
+      @hot_restart_requested = false
     end
 
     # Starts the multi-process cluster and manages worker processes.
     #
     # Forks the configured number of worker processes and monitors them,
     # restarting any that exit unexpectedly or stop checking in. Handles
-    # graceful shutdown via INT or TERM signals, stats logging via USR1,
-    # and phased restart via USR2.
+    # graceful shutdown via INT or TERM signals, phased restart via USR1,
+    # and hot restart via USR2.
     #
     # Each worker process includes:
     # - 1 server thread (continuously accepts connections with backpressure control)
@@ -145,13 +196,18 @@ module Raptor
     #
     # @rbs () -> void
     def run
+      reopen_logs
+
       trap("INT") { shutdown }
       trap("TERM") { shutdown }
-      trap("USR1") { log_stats }
-      trap("USR2") { @phased_restart_requested = true }
+      trap("HUP") { reopen_logs_and_signal_workers }
+      trap("USR1") { @phased_restart_requested = true }
+      trap("USR2") { @hot_restart_requested = true }
 
       File.open(@pid_file, File::CREAT | File::EXCL | File::WRONLY) { |file| file.write(Process.pid.to_s) } if @pid_file
 
+      @bpf_active = ReuseportBPF.setup(@worker_count)
+
       @worker_count.times { |index| spawn_worker(index) }
 
       stats_file_thread = if @stats_file
@@ -162,20 +218,25 @@ module Raptor
         end
       end
 
+      Systemd.notify("READY=1\nMAINPID=#{Process.pid}")
+
       until @shutdown
         break if reap_workers == :no_children
 
+        perform_hot_restart if @hot_restart_requested
         perform_phased_restart if @phased_restart_requested && !@phased_restarting
         timeout_hung_workers
 
         sleep 0.1
       end
 
+      Systemd.notify("STOPPING=1")
       stop_workers
       stats_file_thread&.join
       File.delete(@stats_file) rescue nil if @stats_file
       File.delete(@pid_file) rescue nil if @pid_file
       @stats.unmap
+      @binder.close
     end
 
     # Returns stats for all worker processes.
@@ -190,6 +251,25 @@ module Raptor
 
     private
 
+    # Returns the inherited-FDs hash for a systemd socket-activation handoff,
+    # pairing each bind URI with the FD systemd passed at the same index.
+    # The activation is skipped (with a warning) when the FD count doesn't
+    # match the number of bind URIs.
+    #
+    # @param bind_uris [Array<String>] the configured bind URIs
+    # @param filenos [Array<Integer>] file descriptors passed by systemd
+    # @return [Hash{String => Array<Integer>}]
+    #
+    # @rbs (Array[String] bind_uris, Array[Integer] filenos) -> Hash[String, Array[Integer]]
+    def pair_systemd_fds(bind_uris, filenos)
+      if bind_uris.length != filenos.length
+        Log.warn "Ignoring socket activation: #{filenos.length} fd(s) from systemd, #{bind_uris.length} bind(s) configured"
+        return {}
+      end
+
+      bind_uris.zip(filenos).to_h { |bind_uri, fileno| [bind_uri, [fileno]] }
+    end
+
     # Forks a new worker process and registers it at the given index.
     # The worker inherits the cluster's current phase.
     #
@@ -278,7 +358,7 @@ module Raptor
     end
 
     # Replaces each worker process one at a time, waiting for the new
-    # worker to boot before moving on to the next. Triggered by SIGUSR2.
+    # worker to boot before moving on to the next.
     #
     # @return [void]
     #
@@ -315,6 +395,36 @@ module Raptor
       end
     end
 
+    # Re-execs the master process with a fresh boot of the same Raptor
+    # invocation, handing the new master its listening sockets so accepted
+    # connections continue to be served across the swap.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def perform_hot_restart
+      @hot_restart_requested = false
+
+      unless @launch_command && @launch_argv
+        Log.warn "Hot restart unavailable: launch command not captured"
+        return
+      end
+
+      Log.info "Hot restart starting"
+      monotonic_usec = (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1_000_000).to_i
+      Systemd.notify("RELOADING=1\nMONOTONIC_USEC=#{monotonic_usec}")
+      @shutdown = true
+      stop_workers
+      @binder.clear_close_on_exec
+      ENV[INHERITED_FDS_ENV] = JSON.generate(@binder.inheritable_fds)
+      File.delete(@stats_file) rescue nil if @stats_file
+      File.delete(@pid_file) rescue nil if @pid_file
+      @stats.unmap
+      $stdout.flush
+      $stderr.flush
+      exec(@launch_command, *@launch_argv)
+    end
+
     # Runs the full server stack inside a worker process.
     #
     # Sets up and coordinates the reactor, server, ractor pool, thread pool,
@@ -330,6 +440,11 @@ module Raptor
       shutdown_requested = false
       trap("INT") { shutdown_requested = true }
       trap("TERM") { shutdown_requested = true }
+      trap("HUP") { reopen_logs }
+      trap("USR1", "IGNORE")
+      trap("USR2", "IGNORE")
+
+      Raptor::CPU.pin(index) if Raptor::CPU.count >= @worker_count
 
       started_at = Process.clock_gettime(Process::CLOCK_REALTIME)
       request_count = 0
@@ -354,27 +469,64 @@ module Raptor
         @app.call(env)
       }
       thread_pool = AtomicThreadPool.new(size: @thread_count)
-      request = Request.new(counting_app, @server_port, client_options: @client_options, on_error: @on_error)
-      http2 = Http2.new(counting_app, @server_port, on_error: @on_error)
+      http1 = Http1.new(
+        counting_app,
+        @server_port,
+        connection_options: @connection_options,
+        http1_options: @http1_options,
+        access_log_io: @access_log_io,
+        on_error: @on_error
+      )
+      http2 = Http2.new(
+        counting_app,
+        @server_port,
+        connection_options: @connection_options,
+        http2_options: @http2_options,
+        access_log_io: @access_log_io,
+        on_error: @on_error
+      )
       ractor_pool = RactorPool.new(
         size: @ractor_count,
-        worker: request.http_parser_worker
+        worker: http1.http_parser_worker
       ) do |parsed_result|
         begin
           if parsed_result[:protocol] == :http2
             http2.handle_parsed_request(parsed_result, reactor, thread_pool)
           else
-            request.handle_parsed_request(parsed_result, reactor, thread_pool)
+            http1.handle_parsed_request(parsed_result, reactor, thread_pool)
           end
         rescue => error
           Log.rescued_error(error)
         end
       end
 
-      reactor = Reactor.new(ractor_pool, thread_pool, client_options: @client_options)
+      reactor = Reactor.new(
+        ractor_pool,
+        thread_pool,
+        connection_options: @connection_options,
+        http1_options: @http1_options
+      )
       reactor_thread = reactor.run
 
-      server = Server.new(@binder, reactor, thread_pool, request, client_options: @client_options)
+      worker_listeners = if @bpf_active
+        bpf_listeners = ReuseportBPF.create_worker_listeners(@binder.bind_uris, index, @binder.socket_backlog)
+        non_tcp_listeners = @binder.listeners.reject { |listener| listener.is_a?(TCPServer) }
+        bpf_listeners + non_tcp_listeners
+      else
+        @binder.listeners
+      end
+
+      server = Server.new(
+        @binder,
+        reactor,
+        thread_pool,
+        http1,
+        http2,
+        connection_options: @connection_options,
+        drain_accept_queue: @drain_accept_queue,
+        listeners: worker_listeners,
+        worker_index: (index if @bpf_active)
+      )
       server_thread = server.run
 
       Log.info "Worker #{index} booted"
@@ -412,11 +564,28 @@ module Raptor
       reactor.shutdown
       reactor_thread.join
       ractor_pool.shutdown
-      request.shutdown
-      thread_pool.shutdown
+      http1.shutdown
+      drain_thread_pool(thread_pool)
       stats_thread.join
     end
 
+    # 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(thread_pool)
+      drain = Thread.new { thread_pool.shutdown }
+      return if drain.join(@worker_drain_timeout)
+
+      Log.warn "Force-killing in-flight app threads after #{@worker_drain_timeout}s drain timeout"
+      thread_pool.instance_variable_get(:@threads).each(&:kill)
+      drain.join
+    end
+
     # Returns a human-readable description of how a process exited.
     #
     # @param status [Process::Status] the exit status of the process
@@ -454,6 +623,7 @@ module Raptor
       Log.info "Cluster initializing:"
       Log.info "├─ Version: #{VERSION}"
       Log.info "├─ Ruby Version: #{RUBY_DESCRIPTION}"
+      Log.info "├─ Environment: #{@environment}"
       Log.info "├─ Master PID: #{Process.pid}"
       Log.info "│  └─ #{@worker_count} worker process#{"es" if @worker_count > 1}"
       Log.info "│     ├─ 1 server thread"
@@ -465,20 +635,31 @@ module Raptor
       Log.info "└─ Listening on #{@binder.addresses.join(", ")}"
     end
 
-    # Logs current stats for all workers to stdout.
+    # Redirects `$stdout`, `$stderr`, and the access log to their configured
+    # paths. No-op for any stream whose target path is nil.
     #
-    # Triggered by SIGUSR1 in the master process.
+    # @return [void]
+    #
+    # @rbs () -> void
+    def reopen_logs
+      $stdout.reopen(@stdout_file, "a").sync = true if @stdout_file
+      $stderr.reopen(@stderr_file, "a").sync = true if @stderr_file
+      return unless @access_log_file
+
+      @access_log_io ||= File.open(@access_log_file, "a")
+      @access_log_io.reopen(@access_log_file, "a")
+      @access_log_io.sync = true
+    end
+
+    # Reopens the master's log files and forwards SIGHUP to each worker so
+    # they reopen their own inherited file descriptors.
     #
     # @return [void]
     #
     # @rbs () -> void
-    def log_stats
-      @stats.all.each do |stat|
-        status = stat[:booted] ? "booted" : "starting"
-        Log.info "Worker #{stat[:index]} (phase #{stat[:phase]}): pid=#{stat[:pid]}, requests=#{stat[:requests]}, " \
-                 "busy=#{stat[:busy_threads]}/#{stat[:thread_capacity]}, backlog=#{stat[:backlog]}, " \
-                 "#{status}, last_checkin=#{Time.at(stat[:last_checkin]).strftime("%H:%M:%S")}"
-      end
+    def reopen_logs_and_signal_workers
+      reopen_logs
+      @workers.values.each { |pid| Process.kill("HUP", pid) rescue nil }
     end
 
     # Writes the stats file on a 1-second interval until shutdown.

data/lib/raptor/http.rb

@@ -0,0 +1,116 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "rack"
+
+require_relative "version"
+require_relative "raptor_native"
+
+module Raptor
+  # Shared HTTP utilities used by both the HTTP/1.x and HTTP/2 handlers:
+  # Rack env keys that aren't provided by Rack itself, low-level socket
+  # writing, and Common Log Format access-log formatting.
+  #
+  module Http
+    WRITE_TIMEOUT = 5
+
+    CONTENT_LENGTH = "CONTENT_LENGTH"
+    CONTENT_TYPE = "CONTENT_TYPE"
+    HTTP_VERSION = "HTTP_VERSION"
+    REMOTE_ADDR = "REMOTE_ADDR"
+    SERVER_SOFTWARE = "SERVER_SOFTWARE"
+    SERVER_SOFTWARE_VALUE = "Raptor/#{Raptor::VERSION}".freeze
+
+    class WriteError < StandardError
+      # @rbs () -> String
+      def message = "could not write response"
+    end
+
+    # Writes `string` in full, retrying on partial writes. Bounded by
+    # `timeout` so a slow client can't pin the writing thread.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param string [String] the data to write
+    # @param timeout [Integer] seconds to wait for the socket to become writable on each partial write
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, String string, ?timeout: Integer) -> void
+    def self.socket_write(socket, string, timeout: WRITE_TIMEOUT)
+      bytes = 0
+      byte_size = string.bytesize
+
+      while bytes < byte_size
+        begin
+          bytes += socket.write_nonblock(bytes.zero? ? string : string.byteslice(bytes..-1))
+        rescue IO::WaitWritable
+          raise WriteError unless socket.wait_writable(timeout)
+          retry
+        rescue IOError
+          raise WriteError
+        end
+      end
+    end
+
+    # Writes `strings` in full via a single `writev(2)` syscall when possible,
+    # falling back to per-string writes on partial results. Bounded by
+    # `timeout` so a slow client can't pin the writing thread.
+    #
+    # @param socket [TCPSocket] the socket to write to
+    # @param strings [Array<String>] the buffers to write in order
+    # @param timeout [Integer] seconds to wait for the socket to become writable on each retry
+    # @return [void]
+    # @raise [WriteError] if the socket is not writable within the timeout or raises IOError
+    #
+    # @rbs (TCPSocket socket, Array[String] strings, ?timeout: Integer) -> void
+    def self.socket_writev(socket, strings, timeout: WRITE_TIMEOUT)
+      total = strings.sum(&:bytesize)
+      return if total.zero?
+
+      begin
+        written = Raptor::VectorIO.writev_nonblock(socket, strings)
+      rescue IO::WaitWritable
+        raise WriteError unless socket.wait_writable(timeout)
+        retry
+      rescue IOError
+        raise WriteError
+      end
+
+      return if written == total
+
+      offset = 0
+      strings.each do |string|
+        size = string.bytesize
+        if written >= offset + size
+          offset += size
+        else
+          start = written - offset
+          socket_write(socket, start.zero? ? string : string.byteslice(start..-1), timeout: timeout)
+          offset += size
+          written = offset
+        end
+      end
+    end
+
+    # Writes a Common Log Format entry to `io`. Write failures are silently
+    # ignored.
+    #
+    # @param io [IO] the destination 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 (IO io, Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def self.write_access_log(io, env, status, size, remote_addr)
+      timestamp = Time.now.strftime("%d/%b/%Y:%H:%M:%S %z")
+      method = env[Rack::REQUEST_METHOD]
+      query = env[Rack::QUERY_STRING]
+      path = query.empty? ? env[Rack::PATH_INFO] : "#{env[Rack::PATH_INFO]}?#{query}"
+      protocol = env[Rack::SERVER_PROTOCOL]
+
+      io.puts(%(#{remote_addr} - - [#{timestamp}] "#{method} #{path} #{protocol}" #{status} #{size})) rescue nil
+    end
+  end
+end