raptor 0.6.0 → 0.8.0

data/lib/raptor/systemd.rb

@@ -0,0 +1,69 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "socket"
+
+module Raptor
+  # Integration with systemd's service notification protocol and
+  # socket-activation file descriptors.
+  #
+  module Systemd
+    LISTEN_FDS_START = 3
+
+    LISTEN_FDNAMES_ENV = "LISTEN_FDNAMES"
+    LISTEN_FDS_ENV = "LISTEN_FDS"
+    LISTEN_PID_ENV = "LISTEN_PID"
+    NOTIFY_SOCKET_ENV = "NOTIFY_SOCKET"
+
+    # Sends `message` to the systemd notification socket, returning true on
+    # success and false when the socket is unset or the send fails.
+    #
+    # @param message [String] notify protocol payload, e.g. "READY=1"
+    # @return [Boolean]
+    #
+    # @rbs (String message) -> bool
+    def self.notify(message)
+      socket_path = ENV[NOTIFY_SOCKET_ENV]
+      return false if socket_path.nil? || socket_path.empty?
+
+      address = if socket_path.start_with?("@")
+        Socket.pack_sockaddr_un("\0#{socket_path[1..]}")
+      else
+        Socket.pack_sockaddr_un(socket_path)
+      end
+
+      socket = Socket.new(Socket::AF_UNIX, Socket::SOCK_DGRAM, 0)
+      socket.send(message, 0, address)
+      true
+    rescue SystemCallError, IOError
+      false
+    ensure
+      socket&.close
+    end
+
+    # Returns the file descriptors passed in via socket activation, or an
+    # empty array when systemd has not exported any.
+    #
+    # @return [Array<Integer>]
+    #
+    # @rbs () -> Array[Integer]
+    def self.listen_fds
+      return [] unless ENV[LISTEN_PID_ENV]&.to_i == Process.pid
+
+      count = ENV[LISTEN_FDS_ENV]&.to_i || 0
+      Array.new(count) { |index| LISTEN_FDS_START + index }
+    end
+
+    # Clears the socket-activation environment variables so children don't
+    # act on stale values.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def self.clear_listen_env
+      ENV.delete(LISTEN_FDNAMES_ENV)
+      ENV.delete(LISTEN_FDS_ENV)
+      ENV.delete(LISTEN_PID_ENV)
+    end
+  end
+end

data/lib/raptor/version.rb

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

data/sig/generated/raptor/binder.rbs

@@ -51,10 +51,16 @@ module Raptor
       def members: () -> [ :tcp_server, :ssl_context ]
     end
 
-    @bind_uris: Array[String]
+    @uri_listeners: Hash[String, Array[TCPServer | UNIXServer | SslListener]]
 
     @listeners: Array[TCPServer | UNIXServer | SslListener]
 
+    @inherited_fds: Hash[String, Array[Integer]]
+
+    @socket_backlog: Integer
+
+    @bind_uris: Array[String]
+
     # Array of listening sockets.
     #
     # @return [Array<TCPServer, UNIXServer, SslListener>] the server sockets
@@ -64,17 +70,21 @@ module Raptor
     #
     # Parses the provided bind URIs and creates listening sockets for each one.
     # Supports tcp://, unix://, and ssl:// schemes. Localhost is expanded to
-    # all available loopback addresses (both IPv4 and IPv6).
+    # all available loopback addresses (both IPv4 and IPv6). When `inherited_fds`
+    # supplies file descriptors for a URI, the listener is reconstructed from
+    # those FDs instead of binding fresh.
     #
     # @param bind_uris [Array<String>] array of URI strings to bind to
+    # @param socket_backlog [Integer] kernel listen() queue depth for TCP/SSL listeners
+    # @param inherited_fds [Hash{String => Array<Integer>}] inherited listener FDs keyed by bind URI
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI has an unsupported scheme
     #
     # @example
     #   binder = Binder.new(["tcp://0.0.0.0:3000", "unix:///tmp/raptor.sock"])
     #
-    # @rbs (Array[String] bind_uris) -> void
-    def initialize: (Array[String] bind_uris) -> void
+    # @rbs (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
+    def initialize: (Array[String] bind_uris, ?socket_backlog: Integer, ?inherited_fds: Hash[String, Array[Integer]]) -> void
 
     # Returns the bound addresses as strings.
     #
@@ -106,9 +116,27 @@ module Raptor
     # @rbs () -> void
     def close: () -> void
 
+    # Returns the file descriptors of every listener, grouped by the bind URI
+    # they were created from. The result is the payload to hand to a successor
+    # process via the `inherited_fds:` constructor argument.
+    #
+    # @return [Hash{String => Array<Integer>}]
+    #
+    # @rbs () -> Hash[String, Array[Integer]]
+    def inheritable_fds: () -> Hash[String, Array[Integer]]
+
+    # Clears the close-on-exec flag on every listener so the file descriptors
+    # survive `Kernel.exec`.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def clear_close_on_exec: () -> void
+
     private
 
-    # Parses bind URIs and creates listening sockets.
+    # Parses bind URIs and creates listening sockets, reusing inherited file
+    # descriptors for URIs supplied in `@inherited_fds`.
     #
     # @return [void]
     # @raise [UnknownBindSchemeError] if a URI scheme is not supported
@@ -116,6 +144,26 @@ module Raptor
     # @rbs () -> void
     def parse: () -> void
 
+    # Creates fresh listeners for the given bind URI.
+    #
+    # @param bind_uri [String] the URI to bind
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @raise [UnknownBindSchemeError] if the URI scheme is not supported
+    #
+    # @rbs (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
+    def create_listeners: (String bind_uri) -> Array[TCPServer | UNIXServer | SslListener]
+
+    # Reconstructs listeners for the given bind URI from inherited file
+    # descriptors.
+    #
+    # @param bind_uri [String] the URI the FDs were bound to
+    # @param filenos [Array<Integer>] file descriptors to wrap
+    # @return [Array<TCPServer, UNIXServer, SslListener>]
+    # @raise [UnknownBindSchemeError] if the URI scheme is not supported
+    #
+    # @rbs (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+    def restore_listeners: (String bind_uri, Array[Integer] filenos) -> Array[TCPServer | UNIXServer | SslListener]
+
     # Creates TCP server sockets for the given host and port.
     #
     # @param host [String, nil] hostname or IP address to bind to
@@ -138,6 +186,16 @@ module Raptor
     # @rbs (String path) -> Array[UNIXServer]
     def create_unix_listeners: (String path) -> Array[UNIXServer]
 
+    # Registers an `at_exit` hook that removes the Unix socket file on the
+    # owning master's clean exit. Each call records the current process so
+    # forked workers won't delete a socket their master still owns.
+    #
+    # @param path [String] filesystem path of the Unix socket
+    # @return [void]
+    #
+    # @rbs (String path) -> void
+    def register_unix_socket_cleanup: (String path) -> void
+
     # Creates SSL server sockets for the given host, port, and SSL parameters.
     #
     # Wraps each TCP listener with an SSL context to produce SslListener objects.
@@ -152,6 +210,15 @@ module Raptor
     # @rbs (String? host, Integer? port, Hash[String, String] ssl_params) -> Array[SslListener]
     def create_ssl_listeners: (String? host, Integer? port, Hash[String, String] ssl_params) -> Array[SslListener]
 
+    # Builds a frozen `OpenSSL::SSL::SSLContext` configured for HTTP/2 and
+    # HTTP/1.1 ALPN negotiation.
+    #
+    # @param ssl_params [Hash<String, String>] SSL options ("cert" and "key" paths)
+    # @return [OpenSSL::SSL::SSLContext]
+    #
+    # @rbs (Hash[String, String] ssl_params) -> OpenSSL::SSL::SSLContext
+    def build_ssl_context: (Hash[String, String] ssl_params) -> OpenSSL::SSL::SSLContext
+
     # Returns all available loopback IP addresses.
     #
     # @return [Array<String>] unique loopback addresses (IPv4 and IPv6)

data/sig/generated/raptor/cli.rbs

@@ -18,6 +18,8 @@ module Raptor
   class CLI
     DEFAULT_WORKER_COUNT: untyped
 
+    NESTED_OPTION_KEYS: untyped
+
     DEFAULT_OPTIONS: untyped
 
     DEFAULT_CONFIG_PATHS: untyped
@@ -103,9 +105,6 @@ module Raptor
 
     # Loads a config file and merges it into `@options` over the defaults.
     #
-    # Top-level keys replace defaults; the nested `:client` hash is merged
-    # key-by-key so a config file does not need to restate every client option.
-    #
     # @param path [String, nil] path to the config file, or nil to no-op
     # @return [void]
     #

data/sig/generated/raptor/cluster.rbs

@@ -26,10 +26,12 @@ 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: ::String
+
     # Convenience method to create and run a cluster with the given options.
     #
     # @param options [Hash] cluster configuration options
@@ -38,13 +40,15 @@ module Raptor
     # @rbs (Hash[Symbol, untyped] options) -> void
     def self.run: (Hash[Symbol, untyped] options) -> void
 
-    @thread_count: Integer
+    @http1_options: Hash[Symbol, untyped]
 
-    @client_options: Hash[Symbol, Integer]
+    @http2_options: Hash[Symbol, untyped]
+
+    @worker_boot_timeout: Integer
 
     @worker_timeout: Integer
 
-    @worker_boot_timeout: Integer
+    @worker_drain_timeout: Integer
 
     @worker_shutdown_timeout: Integer
 
@@ -52,6 +56,18 @@ module Raptor
 
     @pid_file: String?
 
+    @stdout_file: String?
+
+    @stderr_file: String?
+
+    @access_log_file: String?
+
+    @access_log_io: IO?
+
+    @launch_command: String?
+
+    @launch_argv: Array[String]?
+
     @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
 
     @binder: Binder
@@ -74,10 +90,20 @@ module Raptor
 
     @phased_restarting: bool
 
+    @hot_restart_requested: bool
+
+    @connection_options: Hash[Symbol, untyped]
+
+    @environment: String
+
+    @thread_count: Integer
+
     @ractor_count: Integer
 
     @worker_count: Integer
 
+    @drain_accept_queue: bool
+
     # Creates a new Cluster with the specified configuration.
     #
     # Initializes the cluster with worker, ractor, and thread counts,
@@ -86,18 +112,30 @@ 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
@@ -107,8 +145,8 @@ module Raptor
     #
     # 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)
@@ -133,6 +171,18 @@ 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: (Array[String] bind_uris, Array[Integer] filenos) -> Hash[String, Array[Integer]]
+
     # Forks a new worker process and registers it at the given index.
     # The worker inherits the cluster's current phase.
     #
@@ -170,13 +220,22 @@ module Raptor
     def timeout_hung_workers: () -> void
 
     # 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]
     #
     # @rbs () -> void
     def perform_phased_restart: () -> void
 
+    # 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: () -> void
+
     # Runs the full server stack inside a worker process.
     #
     # Sets up and coordinates the reactor, server, ractor pool, thread pool,
@@ -190,6 +249,16 @@ module Raptor
     # @rbs (Integer index, Integer phase) -> void
     def run_worker: (Integer index, Integer phase) -> 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
@@ -213,14 +282,21 @@ module Raptor
     # @rbs () -> void
     def log_initialization: () -> void
 
-    # 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: () -> void
+
+    # 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: () -> void
+    def reopen_logs_and_signal_workers: () -> void
 
     # Writes the stats file on a 1-second interval until shutdown.
     #

data/sig/generated/raptor/http.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/raptor/http.rb with RBS::Inline
+
+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: ::Integer
+
+    CONTENT_LENGTH: ::String
+
+    CONTENT_TYPE: ::String
+
+    HTTP_VERSION: ::String
+
+    REMOTE_ADDR: ::String
+
+    SERVER_SOFTWARE: ::String
+
+    SERVER_SOFTWARE_VALUE: untyped
+
+    class WriteError < StandardError
+      # @rbs () -> String
+      def message: () -> String
+    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: (TCPSocket socket, String string, ?timeout: Integer) -> void
+
+    # 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 io, Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+  end
+end