raptor 0.1.0

data/lib/raptor/binder.rb

@@ -0,0 +1,249 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+
+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 = 1024
+
+    class UnknownBindSchemeError < TypeError
+      # @rbs (String scheme) -> void
+      def initialize(scheme) = super("unknown scheme: #{scheme.inspect}")
+    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.
+    #
+    SslListener = Data.define(:tcp_server, :ssl_context) do
+      # @rbs () -> TCPServer
+      def to_io = tcp_server
+
+      # @rbs () -> Addrinfo
+      def local_address = tcp_server.local_address
+
+      # @rbs () -> void
+      def close = tcp_server.close
+    end
+
+    # @rbs @bind_uris: Array[String]
+    # @rbs @listeners: Array[TCPServer | UNIXServer | SslListener]
+
+    # Array of listening sockets.
+    #
+    # @return [Array<TCPServer, UNIXServer, SslListener>] the server sockets
+    attr_reader :listeners
+
+    # 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(bind_uris)
+      @bind_uris = bind_uris
+      @listeners = nil
+      parse
+    end
+
+    # 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
+      @listeners.map do |listener|
+        case listener
+        when UNIXServer
+          listener.path
+        when SslListener
+          address = listener.local_address
+          "ssl://#{address.ip_address}:#{address.ip_port}"
+        else
+          address = listener.local_address
+          "#{address.ip_address}:#{address.ip_port}"
+        end
+      end
+    end
+
+    # 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
+      tcp_listener = @listeners.find { |listener| listener.is_a?(TCPServer) || listener.is_a?(SslListener) }
+      return 0 unless tcp_listener
+
+      tcp_listener.local_address.ip_port
+    end
+
+    # Closes all listening sockets.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def close
+      @listeners.each(&:close)
+    end
+
+    private
+
+    # Parses bind URIs and creates listening sockets.
+    #
+    # @return [void]
+    # @raise [UnknownBindSchemeError] if a URI scheme is not supported
+    #
+    # @rbs () -> void
+    def parse
+      @listeners = @bind_uris.map do |bind_uri|
+        uri = URI.parse(bind_uri)
+        case uri.scheme
+        when "tcp"
+          create_tcp_listeners(uri.host, uri.port)
+        when "unix"
+          create_unix_listeners(uri.path)
+        when "ssl"
+          create_ssl_listeners(uri.host, uri.port, URI.decode_www_form(uri.query || "").to_h)
+        else
+          raise UnknownBindSchemeError.new(uri.scheme)
+        end
+      end.tap(&:flatten!)
+    end
+
+    # 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(host, port)
+      if host == "localhost"
+        return loopback_addresses.map { |address| create_tcp_listeners(address, port) }.flatten
+      end
+
+      host = host[1..-2] if host&.start_with?("[")
+
+      tcp_server = TCPServer.new(host, port)
+      tcp_server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+      tcp_server.listen SOCKET_BACKLOG
+
+      [tcp_server]
+    end
+
+    # 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(path)
+      if File.exist?(path)
+        begin
+          UNIXSocket.new(path).close
+          raise "Socket #{path.inspect} is already in use"
+        rescue Errno::ECONNREFUSED
+          File.delete(path)
+        end
+      end
+
+      server = UNIXServer.new(path)
+      master_pid = Process.pid
+      at_exit { File.delete(path) rescue nil if Process.pid == master_pid }
+
+      [server]
+    end
+
+    # 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(host, port, ssl_params)
+      require "openssl"
+
+      tcp_servers = create_tcp_listeners(host, port)
+
+      ssl_context = OpenSSL::SSL::SSLContext.new
+      ssl_context.cert = OpenSSL::X509::Certificate.new(File.read(ssl_params["cert"]))
+      ssl_context.key = OpenSSL::PKey.read(File.read(ssl_params["key"]))
+      ssl_context.alpn_protocols = ["h2", "http/1.1"]
+      ssl_context.alpn_select_cb = ->(protocols) { protocols.include?("h2") ? "h2" : "http/1.1" }
+      ssl_context.freeze
+
+      tcp_servers.map { |tcp_server| SslListener.new(tcp_server: tcp_server, ssl_context: ssl_context) }
+    end
+
+    # Returns all available loopback IP addresses.
+    #
+    # @return [Array<String>] unique loopback addresses (IPv4 and IPv6)
+    #
+    # @rbs () -> Array[String]
+    def loopback_addresses
+      Socket.ip_address_list.filter_map do |addrinfo|
+        next unless addrinfo.ipv4_loopback? || addrinfo.ipv6_loopback?
+
+        addrinfo.ip_address
+      end.tap(&:uniq!)
+    end
+  end
+end

data/lib/raptor/cli.rb

@@ -0,0 +1,171 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "etc"
+require "json"
+require "optparse"
+
+require_relative "cluster"
+
+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 = Etc.nprocessors
+
+    DEFAULT_OPTIONS = {
+      binds: ["tcp://0.0.0.0:9292"].freeze,
+      threads: 3,
+      ractors: 1,
+      workers: DEFAULT_WORKER_COUNT,
+      rackup: "config.ru",
+      stats_file: "tmp/raptor.json",
+      client: {
+        first_data_timeout: 30,
+        chunk_data_timeout: 10,
+        persistent_data_timeout: 65,
+      },
+    }.freeze
+
+    # @rbs @command: Symbol
+    # @rbs @options: Hash[Symbol, untyped]
+    # @rbs @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(argv)
+      if argv.first == "stats"
+        argv.shift
+        @command = :stats
+      else
+        @command = :server
+      end
+      @options = DEFAULT_OPTIONS.dup
+      @options[:client] = @options[:client].dup
+      @parser = create_parser
+      @parser.parse!(argv)
+
+      @options[:rackup] = argv.first if @command == :server && argv.first
+    end
+
+    # Runs the requested command.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def run
+      @command == :stats ? run_stats : Cluster.run(@options)
+    end
+
+    private
+
+    # Reads and prints the stats file.
+    #
+    # @return [void]
+    #
+    # @rbs () -> void
+    def run_stats
+      stats_file = @options[:stats_file]
+
+      unless File.exist?(stats_file)
+        warn "No stats file at #{stats_file.inspect}. Is Raptor running?"
+        exit 1
+      end
+
+      data = JSON.parse(File.read(stats_file), symbolize_names: true)
+
+      puts "Master PID: #{data[:master_pid]}"
+      data[:workers].each_with_index do |worker, index|
+        status = worker[:booted] ? "booted" : "starting"
+        last_checkin = Time.at(worker[:last_checkin]).strftime("%H:%M:%S")
+        puts "Worker #{index}: pid=#{worker[:pid]}, requests=#{worker[:requests]}, " \
+             "backlog=#{worker[:backlog]}, #{status}, last_checkin=#{last_checkin}"
+      end
+    end
+
+    # Creates the OptionParser instance with all supported command-line options.
+    #
+    # @return [OptionParser] configured option parser
+    #
+    # @rbs () -> OptionParser
+    def create_parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: raptor [options] [rackup file]"
+
+        opts.on("-b", "--bind URI", String, "Bind address (default: tcp://0.0.0.0:9292)") do |bind|
+          if @options[:binds] == DEFAULT_OPTIONS[:binds]
+            @options[:binds] = [bind]
+          else
+            @options[:binds] << bind
+          end
+        end
+
+        opts.on("-t", "--threads NUM", Integer, "Number of threads (default: 3)") do |num|
+          @options[:threads] = num
+        end
+
+        opts.on("-r", "--ractors NUM", Integer, "Number of ractors (default: 1)") do |num|
+          @options[:ractors] = num
+        end
+
+        opts.on("-w", "--workers NUM", Integer, "Number of worker processes (default: #{DEFAULT_WORKER_COUNT})") do |num|
+          @options[:workers] = num
+        end
+
+        opts.on("--first-data-timeout SECONDS", Integer, "First data timeout in seconds (default: 30)") do |timeout|
+          @options[:client][:first_data_timeout] = timeout
+        end
+
+        opts.on("--chunk-data-timeout SECONDS", Integer, "Chunk data timeout in seconds (default: 10)") do |timeout|
+          @options[:client][:chunk_data_timeout] = timeout
+        end
+
+        opts.on("--persistent-data-timeout SECONDS", Integer, "Persistent data timeout in seconds (default: 65)") do |timeout|
+          @options[:client][:persistent_data_timeout] = timeout
+        end
+
+        opts.on("--stats-file PATH", String, "Stats file path (default: tmp/raptor.json)") do |path|
+          @options[:stats_file] = path
+        end
+
+        opts.on("--help", "Show this help") do
+          puts opts
+          exit
+        end
+
+        opts.on("-v", "--version", "Show version") do
+          puts Raptor::VERSION
+          exit
+        end
+      end
+    end
+  end
+end