raptor 0.7.0 → 0.9.0

data/lib/raptor/http2.rb

@@ -6,7 +6,7 @@ require "stringio"
 require "atomic-ruby/atom"
 require "rack"
 
-require_relative "request"
+require_relative "http"
 require_relative "raptor_http2"
 
 module Raptor
@@ -27,12 +27,17 @@ module Raptor
       IDLE = :idle
 
       # @rbs @state: Atom
+      # @rbs @write_timeout: Integer
 
       # Creates a new Writer.
       #
-      # @rbs () -> void
-      def initialize
+      # @param write_timeout [Integer] per-write socket timeout passed through to {Http.socket_write}
+      # @return [void]
+      #
+      # @rbs (write_timeout: Integer) -> void
+      def initialize(write_timeout:)
         @state = Atom.new(IDLE)
+        @write_timeout = write_timeout
       end
 
       # Writes frames to the socket, coordinating with concurrent writers
@@ -69,7 +74,7 @@ module Raptor
           break if pending.empty?
 
           pending.each do |frame|
-            Request.socket_write(socket, frame) rescue nil
+            Http.socket_write(socket, frame, timeout: @write_timeout) rescue nil
           end
         end
       end
@@ -78,7 +83,7 @@ module Raptor
     # Per-connection outbound flow-control accounting.
     #
     # Tracks the peer's connection-level and per-stream receive windows so
-    # outbound DATA frames respect RFC 7540 §5.2. Threads dispatching stream
+    # outbound DATA frames respect RFC 7540 section 5.2. Threads dispatching stream
     # responses call `acquire` to reserve send capacity; threads applying
     # inbound WINDOW_UPDATE or SETTINGS frames call the mutating methods to
     # replenish it. The connection window and per-stream windows live in
@@ -146,9 +151,9 @@ module Raptor
           end
 
           if granted > 0
-            @stream_windows.swap do |s|
-              current = s[stream_id] || initial
-              s.merge(stream_id => current - granted)
+            @stream_windows.swap do |windows|
+              current = windows[stream_id] || initial
+              windows.merge(stream_id => current - granted)
             end
             return granted
           end
@@ -178,14 +183,14 @@ module Raptor
       # @rbs (Integer stream_id, Integer increment) -> void
       def add_stream_window(stream_id, increment)
         initial = @initial_stream_window.value
-        @stream_windows.swap do |s|
-          current = s[stream_id] || initial
-          s.merge(stream_id => current + increment)
+        @stream_windows.swap do |windows|
+          current = windows[stream_id] || initial
+          windows.merge(stream_id => current + increment)
         end
       end
 
       # Updates the peer's `SETTINGS_INITIAL_WINDOW_SIZE`. Shifts every
-      # existing stream window by the delta as required by RFC 7540 §6.9.2.
+      # existing stream window by the delta as required by RFC 7540 section 6.9.2.
       #
       # @param new_size [Integer] the peer's new initial window size
       # @return [void]
@@ -197,8 +202,8 @@ module Raptor
         delta = new_size - old
         return if delta.zero?
 
-        @stream_windows.swap do |s|
-          s.transform_values { |size| size + delta }
+        @stream_windows.swap do |windows|
+          windows.transform_values { |size| size + delta }
         end
       end
 
@@ -213,12 +218,12 @@ module Raptor
       def discard_stream(stream_id)
         return unless @stream_windows.value.key?(stream_id)
 
-        @stream_windows.swap do |s|
-          next s unless s.key?(stream_id)
+        @stream_windows.swap do |windows|
+          next windows unless windows.key?(stream_id)
 
-          new = s.dup
-          new.delete(stream_id)
-          new
+          pruned = windows.dup
+          pruned.delete(stream_id)
+          pruned
         end
       end
     end
@@ -244,34 +249,51 @@ module Raptor
 
     # @rbs @app: ^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped]
     # @rbs @server_port: Integer
+    # @rbs @write_timeout: Integer
+    # @rbs @access_log_io: IO?
     # @rbs @on_error: ^(Hash[String, untyped]?, Exception) -> void | nil
+    # @rbs @initial_settings_frame: String
+
+    # The initial server SETTINGS frame sent on every new HTTP/2 connection.
+    #
+    # @return [String] the encoded SETTINGS frame
+    attr_reader :initial_settings_frame
 
     # Creates a new Http2 handler.
     #
     # @param app [#call] the Rack application to dispatch requests to
     # @param server_port [Integer] port number used to populate SERVER_PORT in the Rack env
+    # @param connection_options [Hash] per-connection settings shared across protocols
+    # @option connection_options [Integer] :write_timeout per-write socket timeout in seconds
+    # @param http2_options [Hash] HTTP/2-specific settings
+    # @option http2_options [Integer] :max_concurrent_streams maximum HTTP/2 concurrent streams per connection
+    # @param access_log_io [IO, nil] IO to write Common Log Format access entries to, or nil to disable
     # @param on_error [#call, nil] callback invoked with (env, exception) when the Rack app raises
     # @return [void]
     #
-    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
-    def initialize(app, server_port, on_error: nil)
+    # @rbs (^(Hash[String, untyped]) -> [Integer, Hash[String, String | Array[String]], untyped] app, Integer server_port, ?connection_options: Hash[Symbol, untyped], ?http2_options: Hash[Symbol, untyped], ?access_log_io: IO?, ?on_error: ^(Hash[String, untyped]?, Exception) -> void | nil) -> void
+    def initialize(app, server_port, connection_options: {}, http2_options: {}, access_log_io: nil, on_error: nil)
       @app = app
       @server_port = server_port
+      @write_timeout = connection_options[:write_timeout] || Http::WRITE_TIMEOUT
+      @access_log_io = access_log_io
       @on_error = on_error
-    end
 
-    # Builds the initial server SETTINGS frame to send on connection establishment.
-    #
-    # @return [String] the encoded SETTINGS frame
-    #
-    # @rbs () -> String
-    def self.build_server_settings_frame
       parser = Http2Parser.new
       settings_payload = parser.build_settings(
-        max_concurrent_streams: 100,
+        max_concurrent_streams: http2_options[:max_concurrent_streams],
         initial_window_size: DEFAULT_WINDOW_SIZE
       )
-      parser.build_frame(:settings, 0, 0, settings_payload)
+      @initial_settings_frame = parser.build_frame(:settings, 0, 0, settings_payload).freeze
+    end
+
+    # Creates a per-connection {Writer} configured with the handler's write timeout.
+    #
+    # @return [Writer] a new per-connection frame writer
+    #
+    # @rbs () -> Writer
+    def create_writer
+      Writer.new(write_timeout: @write_timeout)
     end
 
     # Processes HTTP/2 frames from the connection buffer.
@@ -626,7 +648,8 @@ module Raptor
       env = build_rack_env(headers, body, remote_addr: remote_addr)
       status, response_headers, response_body = @app.call(env)
 
-      write_http2_response(socket, writer, flow_control, stream_id, status, response_headers, response_body)
+      response_size = write_http2_response(socket, writer, flow_control, stream_id, status, response_headers, response_body)
+      write_access_log(env, status, response_size, remote_addr) if @access_log_io
     rescue => error
       write_http2_error_response(socket, writer, stream_id)
 
@@ -652,9 +675,9 @@ module Raptor
     # @param status [Integer] HTTP status code
     # @param headers [Hash] response headers from the Rack application
     # @param body [Object] response body responding to each
-    # @return [void]
+    # @return [String] the response body size in bytes
     #
-    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> void
+    # @rbs (OpenSSL::SSL::SSLSocket socket, Writer writer, FlowControl flow_control, Integer stream_id, Integer status, Hash[String, String | Array[String]] headers, untyped body) -> String
     def write_http2_response(socket, writer, flow_control, stream_id, status, headers, body)
       parser = Http2Parser.new
 
@@ -673,11 +696,16 @@ module Raptor
 
       encoded_headers = parser.encode_headers(header_pairs)
       body_chunks = []
-      body.each { |chunk| body_chunks << chunk unless chunk.empty? }
+      body_bytes = 0
+      body.each do |chunk|
+        next if chunk.empty?
+        body_chunks << chunk
+        body_bytes += chunk.bytesize
+      end
 
       if body_chunks.empty?
         writer.write_frames(socket, [parser.build_frame(:headers, FLAG_END_STREAM | FLAG_END_HEADERS, stream_id, encoded_headers)])
-        return
+        return "0"
       end
 
       frames = [parser.build_frame(:headers, FLAG_END_HEADERS, stream_id, encoded_headers)]
@@ -697,6 +725,7 @@ module Raptor
       end
 
       writer.write_frames(socket, frames)
+      body_bytes.to_s
     end
 
     # Writes a 500 error response as HTTP/2 frames.
@@ -717,6 +746,20 @@ module Raptor
       )
     end
 
+    # Instance-level wrapper around {Http.write_access_log} that routes to
+    # the configured `@access_log_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 (Hash[String, untyped] env, Integer status, String size, String remote_addr) -> void
+    def write_access_log(env, status, size, remote_addr)
+      Http.write_access_log(@access_log_io, env, status, size, remote_addr)
+    end
+
     # Builds a Rack environment hash from HTTP/2 headers and body.
     #
     # Translates HTTP/2 pseudo-headers into Rack-compatible environment keys
@@ -743,9 +786,9 @@ module Raptor
           when ":authority" then env[Rack::HTTP_HOST] = value
           end
         elsif name == "content-type"
-          env["CONTENT_TYPE"] = value
+          env[Http::CONTENT_TYPE] = value
         elsif name == "content-length"
-          env["CONTENT_LENGTH"] = value
+          env[Http::CONTENT_LENGTH] = value
         else
           rack_key = "HTTP_#{name.upcase.tr("-", "_")}"
           env[rack_key] = value
@@ -763,11 +806,13 @@ module Raptor
       env[Rack::PATH_INFO] = "" unless env.key?(Rack::PATH_INFO)
       env[Rack::QUERY_STRING] = "" unless env.key?(Rack::QUERY_STRING)
 
-      if body.bytesize.positive? && !env.key?("CONTENT_LENGTH")
-        env["CONTENT_LENGTH"] = body.bytesize.to_s
+      if body.bytesize.positive? && !env.key?(Http::CONTENT_LENGTH)
+        env[Http::CONTENT_LENGTH] = body.bytesize.to_s
       end
 
-      env["REMOTE_ADDR"] = remote_addr
+      env[Http::REMOTE_ADDR] = remote_addr
+      env[Http::SERVER_SOFTWARE] = Http::SERVER_SOFTWARE_VALUE
+      env[Http::HTTP_VERSION] = SERVER_PROTOCOL
 
       populate_server_name_and_port(env)
 

data/lib/raptor/reactor.rb

@@ -14,10 +14,12 @@ module Raptor
   # the server uses for backpressure control to prevent overload.
   #
   # @example
-  #   reactor = Reactor.new(ractor_pool, thread_pool, client_options: {
-  #     first_data_timeout: 30,
-  #     chunk_data_timeout: 10
-  #   })
+  #   reactor = Reactor.new(
+  #     ractor_pool,
+  #     thread_pool,
+  #     connection_options: { first_data_timeout: 30, chunk_data_timeout: 10 },
+  #     http1_options: { persistent_data_timeout: 65 }
+  #   )
   #   reactor.run
   #   reactor.add(id: client.object_id, socket: client)
   #   # ... later
@@ -68,7 +70,9 @@ module Raptor
 
     # @rbs @thread_pool: untyped
     # @rbs @ractor_pool: untyped
-    # @rbs @client_options: Hash[Symbol, Integer]
+    # @rbs @first_data_timeout: Integer
+    # @rbs @chunk_data_timeout: Integer
+    # @rbs @persistent_data_timeout: Integer
     # @rbs @selector: NIO::Selector
     # @rbs @queue: Queue[TCPSocket]
     # @rbs @timeouts: RedBlackTree[TimeoutClient]
@@ -82,17 +86,20 @@ module Raptor
     #
     # @param ractor_pool [RactorPool] ractor pool for HTTP parsing
     # @param thread_pool [AtomicThreadPool] thread pool for application processing
-    # @param client_options [Hash] timeout configuration options
-    # @option client_options [Integer] :first_data_timeout timeout for initial data
-    # @option client_options [Integer] :chunk_data_timeout timeout for subsequent chunks
-    # @option client_options [Integer] :persistent_data_timeout timeout for keep-alive connections
+    # @param connection_options [Hash] per-connection timeout configuration
+    # @option connection_options [Integer] :first_data_timeout timeout for initial data
+    # @option connection_options [Integer] :chunk_data_timeout timeout for subsequent chunks
+    # @param http1_options [Hash] HTTP/1.1-specific configuration
+    # @option http1_options [Integer] :persistent_data_timeout timeout for keep-alive idle connections
     # @return [void]
     #
-    # @rbs (untyped ractor_pool, untyped thread_pool, client_options: Hash[Symbol, Integer]) -> void
-    def initialize(ractor_pool, thread_pool, client_options:)
+    # @rbs (untyped ractor_pool, untyped thread_pool, connection_options: Hash[Symbol, untyped], http1_options: Hash[Symbol, untyped]) -> void
+    def initialize(ractor_pool, thread_pool, connection_options:, http1_options:)
       @ractor_pool = ractor_pool
       @thread_pool = thread_pool
-      @client_options = client_options
+      @first_data_timeout = connection_options[:first_data_timeout]
+      @chunk_data_timeout = connection_options[:chunk_data_timeout]
+      @persistent_data_timeout = http1_options[:persistent_data_timeout]
 
       @selector = NIO::Selector.new
       @queue = Queue.new
@@ -354,11 +361,11 @@ module Raptor
       state = @socket_to_state[socket]
       client = TimeoutClient.new(state)
       timeout = if state[:persisted]
-        @client_options[:persistent_data_timeout]
+        @persistent_data_timeout
       elsif first_data_received?(state)
-        @client_options[:chunk_data_timeout]
+        @chunk_data_timeout
       else
-        @client_options[:first_data_timeout]
+        @first_data_timeout
       end
       client.timeout_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
       @timeouts << client

data/lib/raptor/reuseport_bpf.rb

@@ -0,0 +1,108 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "socket"
+require "uri"
+
+begin
+  require "libbpf-ruby"
+rescue LoadError
+end
+
+module Raptor
+  # Routes incoming connections across worker processes to the worker with
+  # the lowest reactor backlog.
+  #
+  # Auto-enabled on Linux when the `libbpf-ruby` gem is installed and the
+  # BPF object file has been compiled. Falls back silently to standard
+  # `SO_REUSEPORT` when either is missing. Raises when the kernel refuses
+  # the BPF program. Wraps `tcp://` bindings only; non-tcp bindings are
+  # left to the binder's shared listeners.
+  #
+  module ReuseportBPF
+    LIBBPF_LOADED = !!defined?(LibBPFRuby)
+    BPF_OBJECT_PATH = File.expand_path("../../ext/raptor_bpf/reuseport_select.bpf.o", __dir__)
+
+    # Whether the preconditions for BPF-directed reuseport are met on this
+    # platform. Does not imply that the kernel will accept the program.
+    #
+    # @return [Boolean]
+    #
+    # @rbs () -> bool
+    def self.supported?
+      LIBBPF_LOADED && File.exist?(BPF_OBJECT_PATH)
+    end
+
+    # Prepares BPF-directed routing for `worker_count` workers.
+    #
+    # Returns true when BPF-directed dispatch is active. Returns false
+    # when the platform is unsupported. Raises when the kernel refuses
+    # the program.
+    #
+    # @param worker_count [Integer] number of worker processes that will bind sockets
+    # @return [Boolean]
+    #
+    # @rbs (Integer worker_count) -> bool
+    def self.setup(worker_count)
+      return false unless supported?
+
+      @object = LibBPFRuby::Object.new(BPF_OBJECT_PATH)
+      @program_fd = @object.program_fd("select_least_loaded")
+      @socks_fd = @object.map_fd("socks")
+      @loads_fd = @object.map_fd("loads")
+
+      LibBPFRuby.map_update(@loads_fd, [0].pack("L"), [worker_count].pack("L"))
+      true
+    end
+
+    # Returns tcp listening sockets bound and registered for `worker_index`.
+    # Skips non-tcp bind URIs.
+    #
+    # @param bind_uris [Array<String>] the configured bind URIs
+    # @param worker_index [Integer] slot index for this worker in the socks map
+    # @param socket_backlog [Integer] kernel listen() queue depth
+    # @return [Array<TCPServer>] the tcp listening sockets created for this worker
+    #
+    # @rbs (Array[String] bind_uris, Integer worker_index, Integer socket_backlog) -> Array[TCPServer]
+    def self.create_worker_listeners(bind_uris, worker_index, socket_backlog)
+      @load_key = [worker_index + 1].pack("L")
+      @load_value = String.new("\x00\x00\x00\x00", encoding: Encoding::ASCII_8BIT)
+
+      bind_uris.filter_map do |bind_uri|
+        uri = URI(bind_uri)
+        next unless uri.scheme == "tcp"
+
+        host = uri.host
+        host = host[1..-2] if host&.start_with?("[")
+
+        addrinfo = Addrinfo.tcp(host, uri.port)
+        socket = Socket.new(addrinfo.afamily, Socket::SOCK_STREAM, 0)
+        socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+        socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEPORT, true)
+        socket.bind(addrinfo)
+        socket.listen(socket_backlog)
+
+        LibBPFRuby.sockmap_update(@socks_fd, [worker_index].pack("L"), socket)
+        LibBPFRuby.attach_reuseport(socket, @program_fd)
+
+        tcp_server = TCPServer.for_fd(socket.fileno)
+        socket.autoclose = false
+        tcp_server
+      end
+    end
+
+    # Publishes this worker's current backlog to the BPF map.
+    #
+    # @param backlog [Integer] the worker's current reactor backlog
+    # @return [void]
+    #
+    # @rbs (Integer backlog) -> void
+    def self.update_load(backlog)
+      @load_value.setbyte(0, backlog & 0xff)
+      @load_value.setbyte(1, (backlog >> 8) & 0xff)
+      @load_value.setbyte(2, (backlog >> 16) & 0xff)
+      @load_value.setbyte(3, (backlog >> 24) & 0xff)
+      LibBPFRuby.map_update(@loads_fd, @load_key, @load_value)
+    end
+  end
+end