raptor 0.1.0

data/lib/raptor/server.rb

@@ -0,0 +1,167 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "socket"
+
+require "atomic-ruby/atomic_boolean"
+
+module Raptor
+  # High-performance HTTP server that accepts connections and dispatches them.
+  #
+  # Server manages the main accept loop, handling incoming client connections from
+  # bound sockets. It uses IO.select for efficient polling and implements automatic
+  # load balancing by checking reactor backlog before accepting connections,
+  # providing natural backpressure based on system capacity.
+  #
+  # Supports TCP, Unix domain, and SSL listeners transparently. TCP_NODELAY is
+  # applied only to TCP sockets, and SSL handshakes are performed synchronously
+  # before handing the connection to the reactor.
+  #
+  # For SSL connections, ALPN negotiation determines the protocol. HTTP/2
+  # connections are added to the reactor with initial SETTINGS and processed
+  # through the same ractor pool pipeline as HTTP/1.1 connections.
+  #
+  # @example
+  #   binder = Binder.new(["tcp://0.0.0.0:3000"])
+  #   reactor = Reactor.new(thread_pool, ractor_pool, client_options: {})
+  #   server = Server.new(binder, reactor, thread_pool)
+  #   server.run
+  #   # ... later
+  #   server.shutdown
+  #
+  class Server
+    HTTP_SCHEME = "http"
+    HTTPS_SCHEME = "https"
+    H2_PROTOCOL = "h2"
+
+    # @rbs @binder: Binder
+    # @rbs @reactor: Reactor
+    # @rbs @thread_pool: AtomicThreadPool
+    # @rbs @running: AtomicBoolean
+
+    # Creates a new Server instance.
+    #
+    # @param binder [Binder] the binder managing listening sockets
+    # @param reactor [Reactor] the reactor for handling client connections
+    # @param thread_pool [AtomicThreadPool] thread pool for application processing
+    # @return [void]
+    #
+    # @rbs (Binder binder, Reactor reactor, AtomicThreadPool thread_pool) -> void
+    def initialize(binder, reactor, thread_pool)
+      @binder = binder
+      @reactor = reactor
+      @thread_pool = thread_pool
+      @running = AtomicBoolean.new(true)
+    end
+
+    # Starts the server's main accept loop in a new thread.
+    #
+    # The accept loop polls listening sockets for ready connections and accepts
+    # them when system capacity allows. It checks reactor backlog before accepting
+    # to prevent overload. This provides natural load balancing across multiple
+    # worker processes through backpressure control.
+    #
+    # @return [Thread] the thread running the accept loop
+    #
+    # @rbs () -> Thread
+    def run
+      Thread.new(@binder.listeners, @reactor, @running) do |server_sockets, reactor, running|
+        Thread.current.name = self.class.name
+
+        while running.true?
+          begin
+            ready_servers, _, _ = IO.select(server_sockets, nil, nil, 1)
+          rescue IOError, Errno::EBADF
+            break
+          end
+
+          next unless ready_servers
+          next if @reactor.backlog >= (@thread_pool.size * 1.2).ceil
+
+          ready_servers.each do |listener|
+            accept_connection(listener, reactor)
+          end
+        end
+      end
+    end
+
+    # Gracefully shuts down the server.
+    #
+    # Stops accepting new connections and closes all listening sockets.
+    # The server thread will exit after handling any in-flight accept operations.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown
+      @running.make_false
+      @binder.close
+    end
+
+    private
+
+    # Accepts a connection from the given listener and dispatches it.
+    #
+    # For SSL connections with h2 negotiated via ALPN, the server sends
+    # initial SETTINGS and adds the connection to the reactor as an HTTP/2
+    # connection. All other connections follow the HTTP/1.1 path.
+    #
+    # @param listener [TCPServer, UNIXServer, Binder::SslListener] the ready listener
+    # @param reactor [Reactor] the reactor to dispatch connections to
+    # @return [void]
+    #
+    # @rbs (TCPServer | UNIXServer | Binder::SslListener listener, Reactor reactor) -> void
+    def accept_connection(listener, reactor)
+      tcp_client = begin
+        listener.is_a?(Binder::SslListener) ? listener.tcp_server.accept_nonblock : listener.accept_nonblock
+      rescue IO::WaitReadable
+        return
+      end
+
+      if tcp_client.is_a?(TCPSocket)
+        tcp_client.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        remote_addr = tcp_client.remote_address.ip_address
+      else
+        remote_addr = "127.0.0.1"
+      end
+
+      url_scheme = HTTP_SCHEME
+      client = tcp_client
+
+      if listener.is_a?(Binder::SslListener)
+        url_scheme = HTTPS_SCHEME
+        begin
+          ssl_socket = OpenSSL::SSL::SSLSocket.new(tcp_client, listener.ssl_context)
+          ssl_socket.sync_close = true
+          ssl_socket.accept
+          client = ssl_socket
+        rescue OpenSSL::SSL::SSLError => error
+          warn "SSL handshake failed: #{error.message}"
+          tcp_client.close rescue nil
+          return
+        end
+
+        if ssl_socket.alpn_protocol == H2_PROTOCOL
+          ssl_socket.write(Http2.build_server_settings_frame) rescue nil
+
+          reactor.add(
+            id: ssl_socket.object_id,
+            socket: ssl_socket,
+            remote_addr: remote_addr,
+            url_scheme: HTTPS_SCHEME,
+            protocol: :http2
+          )
+
+          return
+        end
+      end
+
+      reactor.add(
+        id: client.object_id,
+        socket: client,
+        remote_addr: remote_addr,
+        url_scheme: url_scheme
+      )
+    end
+  end
+end

data/lib/raptor/stats.rb

@@ -0,0 +1,94 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "mmap-ruby"
+
+module Raptor
+  # Shared memory store for per-worker process statistics.
+  #
+  # Stats uses an anonymous mmap (MAP_ANON | MAP_SHARED) created before
+  # forking so that worker processes can write their stats and the master
+  # process can read them without any pipes or signals. Each worker is
+  # assigned a fixed-size slot in the shared region.
+  #
+  # Binary layout per slot (native byte order):
+  #   pid           uint32    4 bytes
+  #   requests      uint64    8 bytes
+  #   backlog       uint32    4 bytes
+  #   started_at    float64   8 bytes
+  #   last_checkin  float64   8 bytes
+  #   booted        uint8     1 byte
+  #                          33 bytes total
+  #
+  class Stats
+    SLOT_FORMAT = "LQLddC"
+    SLOT_SIZE = [0, 0, 0, 0.0, 0.0, 0].pack(SLOT_FORMAT).bytesize
+
+    # @rbs @num_workers: Integer
+    # @rbs @mmap: untyped
+
+    # Creates a new Stats instance backed by anonymous shared memory.
+    #
+    # Allocates a MAP_ANON | MAP_SHARED mmap region large enough for
+    # num_workers slots. Must be called before forking so that all
+    # worker processes share the same backing memory.
+    #
+    # @param num_workers [Integer] number of worker slots to allocate
+    # @return [void]
+    #
+    # @rbs (Integer num_workers) -> void
+    def initialize(num_workers)
+      @num_workers = num_workers
+      @mmap = Mmap.new(nil, length: num_workers * SLOT_SIZE, initialize: "\0")
+    end
+
+    # Writes stats for a worker slot into shared memory.
+    #
+    # @param index [Integer] slot index to write into
+    # @param pid [Integer] worker process ID
+    # @param requests [Integer] total requests handled by this worker
+    # @param backlog [Integer] current queue depth
+    # @param started_at [Float] process start time as a Unix timestamp
+    # @param last_checkin [Float] time of last stats write as a Unix timestamp
+    # @param booted [Boolean] whether the worker has finished starting
+    # @return [void]
+    #
+    # @rbs (Integer index, pid: Integer, requests: Integer, backlog: Integer, started_at: Float, last_checkin: Float, booted: bool) -> void
+    def write(index, pid:, requests:, backlog:, started_at:, last_checkin:, booted:)
+      data = [pid, requests, backlog, started_at, last_checkin, booted ? 1 : 0].pack(SLOT_FORMAT)
+      @mmap.semlock { @mmap[index * SLOT_SIZE, SLOT_SIZE] = data }
+    end
+
+    # Returns stats for all worker slots.
+    #
+    # @return [Array<Hash>] per-worker stat hashes with :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    #
+    # @rbs () -> Array[Hash[Symbol, untyped]]
+    def all
+      (0...@num_workers).map { |index| read(index) }
+    end
+
+    # Releases the shared memory mapping.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def unmap
+      @mmap.unmap
+    end
+
+    private
+
+    # Reads stats for a worker slot from shared memory.
+    #
+    # @param index [Integer] slot index to read from
+    # @return [Hash] stat hash with :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    #
+    # @rbs (Integer index) -> Hash[Symbol, untyped]
+    def read(index)
+      data = @mmap[index * SLOT_SIZE, SLOT_SIZE]
+      pid, requests, backlog, started_at, last_checkin, booted = data.unpack(SLOT_FORMAT)
+      { pid:, requests:, backlog:, started_at:, last_checkin:, booted: booted == 1 }
+    end
+  end
+end

data/lib/raptor/version.rb

@@ -0,0 +1,6 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Raptor
+  VERSION = "0.1.0"
+end

data/lib/raptor.rb

@@ -0,0 +1,13 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require_relative "raptor/version"
+
+# Main module for the Raptor web server.
+#
+# Raptor is a high-performance, multi-threaded, multi-process Ruby web server that
+# leverages Ractors for parallel HTTP/1.1 and HTTP/2 request processing, native C
+# extensions for HTTP parsing and HPACK compression, and NIO for non-blocking I/O.
+#
+module Raptor
+end

data/sig/generated/raptor/binder.rbs

@@ -0,0 +1,162 @@
+# Generated from lib/raptor/binder.rb with RBS::Inline
+
+module Raptor
+  # Manages binding to network addresses and creating listening sockets.
+  #
+  # Binder handles parsing URI bind specifications, creating TCP, Unix, and SSL
+  # server sockets, and managing socket options for optimal performance. It
+  # supports binding to multiple addresses simultaneously.
+  #
+  # @example TCP binding
+  #   binder = Binder.new(["tcp://0.0.0.0:3000", "tcp://[::1]:3000"])
+  #   puts binder.addresses #=> ["0.0.0.0:3000", "[::1]:3000"]
+  #   binder.close
+  #
+  # @example Unix socket binding
+  #   binder = Binder.new(["unix:///tmp/raptor.sock"])
+  #   puts binder.addresses #=> ["/tmp/raptor.sock"]
+  #   binder.close
+  #
+  # @example SSL binding
+  #   binder = Binder.new(["ssl://0.0.0.0:443?cert=/path/to.crt&key=/path/to.key"])
+  #   puts binder.addresses #=> ["ssl://0.0.0.0:443"]
+  #   binder.close
+  #
+  # @example Localhost binding
+  #   binder = Binder.new(["tcp://localhost:8080"])
+  #   # Binds to both IPv4 and IPv6 loopback addresses
+  class Binder
+    SOCKET_BACKLOG: ::Integer
+
+    class UnknownBindSchemeError < TypeError
+      # @rbs (String scheme) -> void
+      def initialize: (String scheme) -> void
+    end
+
+    # Wraps a TCPServer with an SSL context for accepting SSL connections.
+    #
+    # Holds both the underlying TCP server and the SSL context together so
+    # the server thread can accept a TCP connection and then perform the SSL
+    # handshake in a single coordinated step.
+    class SslListener < Data
+      attr_reader tcp_server(): untyped
+
+      attr_reader ssl_context(): untyped
+
+      def self.new: (untyped tcp_server, untyped ssl_context) -> instance
+                  | (tcp_server: untyped, ssl_context: untyped) -> instance
+
+      def self.members: () -> [ :tcp_server, :ssl_context ]
+
+      def members: () -> [ :tcp_server, :ssl_context ]
+    end
+
+    @bind_uris: Array[String]
+
+    @listeners: Array[TCPServer | UNIXServer | SslListener]
+
+    # Array of listening sockets.
+    #
+    # @return [Array<TCPServer, UNIXServer, SslListener>] the server sockets
+    attr_reader listeners: untyped
+
+    # Creates a new Binder with the specified bind URIs.
+    #
+    # 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).
+    #
+    # @param bind_uris [Array<String>] array of URI strings to bind to
+    # @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
+
+    # Returns the bound addresses as strings.
+    #
+    # TCP listeners are returned as "host:port", Unix listeners as the socket
+    # path, and SSL listeners as "ssl://host:port".
+    #
+    # @return [Array<String>] address strings for each bound listener
+    #
+    # @example
+    #   binder.addresses #=> ["127.0.0.1:3000", "/tmp/raptor.sock", "ssl://0.0.0.0:443"]
+    #
+    # @rbs () -> Array[String]
+    def addresses: () -> Array[String]
+
+    # Returns the port number of the first TCP or SSL listener.
+    #
+    # Used to populate SERVER_PORT in the Rack environment. Returns 0
+    # if no TCP or SSL listener is configured (e.g., Unix socket only).
+    #
+    # @return [Integer] the port number, or 0 if no TCP listener exists
+    #
+    # @rbs () -> Integer
+    def server_port: () -> Integer
+
+    # Closes all listening sockets.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def close: () -> void
+
+    private
+
+    # Parses bind URIs and creates listening sockets.
+    #
+    # @return [void]
+    # @raise [UnknownBindSchemeError] if a URI scheme is not supported
+    #
+    # @rbs () -> void
+    def parse: () -> void
+
+    # Creates TCP server sockets for the given host and port.
+    #
+    # @param host [String, nil] hostname or IP address to bind to
+    # @param port [Integer, nil] port number to bind to
+    # @return [Array<TCPServer>] array containing the created TCP server socket(s)
+    #
+    # @rbs (String? host, Integer? port) -> Array[TCPServer]
+    def create_tcp_listeners: (String? host, Integer? port) -> Array[TCPServer]
+
+    # Creates a Unix domain server socket at the given path.
+    #
+    # Removes stale socket files left by crashed processes (when the socket
+    # is not currently in use). Registers an at_exit hook to clean up the
+    # socket file on normal process exit.
+    #
+    # @param path [String] filesystem path for the Unix socket
+    # @return [Array<UNIXServer>] array containing the created Unix server socket
+    # @raise [RuntimeError] if the socket path is already in active use
+    #
+    # @rbs (String path) -> Array[UNIXServer]
+    def create_unix_listeners: (String path) -> Array[UNIXServer]
+
+    # Creates SSL server sockets for the given host, port, and SSL parameters.
+    #
+    # Wraps each TCP listener with an SSL context to produce SslListener objects.
+    # The ssl_params hash must include "cert" and "key" entries pointing to the
+    # certificate and private key files respectively.
+    #
+    # @param host [String, nil] hostname or IP address to bind to
+    # @param port [Integer, nil] port number to bind to
+    # @param ssl_params [Hash<String, String>] SSL options ("cert" and "key" paths)
+    # @return [Array<SslListener>] array containing the created SSL listener(s)
+    #
+    # @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]
+
+    # Returns all available loopback IP addresses.
+    #
+    # @return [Array<String>] unique loopback addresses (IPv4 and IPv6)
+    #
+    # @rbs () -> Array[String]
+    def loopback_addresses: () -> Array[String]
+  end
+end

data/sig/generated/raptor/cli.rbs

@@ -0,0 +1,71 @@
+# Generated from lib/raptor/cli.rb with RBS::Inline
+
+module Raptor
+  # Command-line interface for the Raptor web server.
+  #
+  # CLI parses command-line arguments and starts the server cluster with the
+  # specified configuration options. It supports configuring the number of
+  # workers, threads, ractors, bind addresses, and various client timeout
+  # settings.
+  #
+  # @example Basic usage
+  #   cli = Raptor::CLI.new(["config.ru", "-t", "8", "-w", "4"])
+  #   cli.run
+  #
+  # @example With custom timeouts
+  #   cli = Raptor::CLI.new(["--first-data-timeout", "60", "--threads", "8"])
+  #   cli.run
+  class CLI
+    DEFAULT_WORKER_COUNT: untyped
+
+    DEFAULT_OPTIONS: untyped
+
+    @command: Symbol
+
+    @options: Hash[Symbol, untyped]
+
+    @parser: OptionParser
+
+    # Creates a new CLI instance and parses command-line arguments.
+    #
+    # Parses the provided command-line arguments and configures the server
+    # options accordingly. A rackup file can be provided as the first
+    # positional argument (defaults to config.ru).
+    #
+    # @param argv [Array<String>] command-line arguments to parse
+    # @return [void]
+    # @raise [OptionParser::ParseError] if invalid options are provided
+    #
+    # @example With rackup file
+    #   cli = CLI.new(["my_app.ru", "-w", "4"])
+    #
+    # @example With options only
+    #   cli = CLI.new(["-t", "8", "-r", "2"])
+    #
+    # @rbs (Array[String] argv) -> void
+    def initialize: (Array[String] argv) -> void
+
+    # Runs the requested command.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def run: () -> void
+
+    private
+
+    # Reads and prints the stats file.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def run_stats: () -> void
+
+    # Creates the OptionParser instance with all supported command-line options.
+    #
+    # @return [OptionParser] configured option parser
+    #
+    # @rbs () -> OptionParser
+    def create_parser: () -> OptionParser
+  end
+end

data/sig/generated/raptor/cluster.rbs

@@ -0,0 +1,171 @@
+# Generated from lib/raptor/cluster.rb with RBS::Inline
+
+module Raptor
+  # Multi-process web server cluster with advanced concurrency architecture.
+  #
+  # Cluster manages multiple worker processes, each running a complete server
+  # stack including a reactor thread, server thread, ractor pool for HTTP
+  # parsing, and thread pool for application processing. It handles process
+  # forking, signal management, graceful shutdown, and automatic worker
+  # restart when a worker process unexpectedly exits.
+  #
+  # The architecture provides horizontal scaling through processes while
+  # maintaining efficient I/O and CPU utilization within each process through
+  # the combination of NIO reactors, ractor-based parsing, and thread pools.
+  #
+  # Flow per worker process:
+  # 1. Server continuously accepts connections but skips acceptance when backlog is high
+  # 2. Reactor manages I/O multiplexing and provides backlog metrics for load control
+  # 3. Ractor pool handles CPU-intensive HTTP parsing in parallel
+  # 4. Thread pool processes Rack applications and handles response writing
+  # 5. Natural load balancing occurs through backpressure-based acceptance control
+  #
+  # @example Basic usage
+  #   options = {
+  #     threads: 8, ractors: 2, workers: 4,
+  #     binds: ["tcp://0.0.0.0:3000"],
+  #     rackup: "config.ru",
+  #     client: { first_data_timeout: 30, chunk_data_timeout: 10 }
+  #   }
+  #   Cluster.run(options)
+  class Cluster
+    # Convenience method to create and run a cluster with the given options.
+    #
+    # @param options [Hash] cluster configuration options
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] options) -> void
+    def self.run: (Hash[Symbol, untyped] options) -> void
+
+    @stats_file: String?
+
+    @stats: Stats
+
+    @workers: Hash[Integer, Integer]
+
+    @shutdown: bool
+
+    @app: untyped
+
+    @server_port: Integer
+
+    @binder: Binder
+
+    @client_options: Hash[Symbol, Integer]
+
+    @worker_count: Integer
+
+    @ractor_count: Integer
+
+    @thread_count: Integer
+
+    # Creates a new Cluster with the specified configuration.
+    #
+    # Initializes the cluster with thread, ractor, and worker counts,
+    # sets up network binding, loads the Rack application, and prepares
+    # for multi-process operation.
+    #
+    # @param options [Hash] cluster configuration options
+    # @option options [Integer] :threads number of threads per worker process
+    # @option options [Integer] :ractors number of ractors per worker process
+    # @option options [Integer] :workers number of worker processes
+    # @option options [Array<String>] :binds array of bind URIs
+    # @option options [String] :rackup path to Rack configuration file
+    # @option options [Hash] :client client timeout configuration
+    # @return [void]
+    #
+    # @rbs (Hash[Symbol, untyped] options) -> void
+    def initialize: (Hash[Symbol, untyped] options) -> void
+
+    # Starts the multi-process cluster and manages worker processes.
+    #
+    # Forks the configured number of worker processes and monitors them,
+    # automatically restarting any that exit unexpectedly. Handles graceful
+    # shutdown via INT or TERM signals, and stats logging via USR1.
+    #
+    # Each worker process includes:
+    # - 1 server thread (continuously accepts connections with backpressure control)
+    # - 1 reactor thread (I/O multiplexing, timeout handling, backlog monitoring)
+    # - N ractor workers (parallel HTTP parsing)
+    # - 1 ractor collector thread (coordinates parsing results)
+    # - M worker threads (Rack application processing and response writing)
+    # - 1 stats thread (writes per-worker metrics to shared memory every second)
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def run: () -> void
+
+    # Returns stats for all worker processes.
+    #
+    # @return [Array<Hash>] array of per-worker stat hashes, each containing
+    #   :pid, :requests, :backlog, :started_at, :last_checkin, and :booted
+    #
+    # @rbs () -> Array[Hash[Symbol, untyped]]
+    def stats: () -> Array[Hash[Symbol, untyped]]
+
+    private
+
+    # Forks a new worker process and registers it at the given index.
+    #
+    # @param index [Integer] slot index for this worker in the stats region
+    # @return [void]
+    #
+    # @rbs (Integer index) -> void
+    def spawn_worker: (Integer index) -> void
+
+    # Runs the full server stack inside a worker process.
+    #
+    # Sets up and coordinates the reactor, server, ractor pool, thread pool,
+    # and stats thread, running until a shutdown signal is received or a
+    # critical component fails.
+    #
+    # @param index [Integer] slot index for this worker in the stats region
+    # @return [void]
+    #
+    # @rbs (Integer index) -> void
+    def run_worker: (Integer index) -> void
+
+    # Returns a human-readable description of how a process exited.
+    #
+    # @param status [Process::Status] the exit status of the process
+    # @return [String] a description of the exit reason
+    #
+    # @rbs (Process::Status status) -> String
+    def exit_description: (Process::Status status) -> String
+
+    # Initiates graceful shutdown of the cluster.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def shutdown: () -> void
+
+    # Logs cluster initialization details including architecture and bind addresses.
+    #
+    # Outputs a hierarchical view of the cluster configuration showing
+    # the master process, worker processes, and per-process thread/ractor
+    # allocation along with listening addresses.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def log_initialization: () -> void
+
+    # Logs current stats for all workers to stdout.
+    #
+    # Triggered by SIGUSR1 in the master process.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def log_stats: () -> void
+
+    # Writes the stats file on a 1-second interval until shutdown.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def write_stats_file_loop: () -> void
+  end
+end