hyperion-rb 2.16.3 → 2.16.4

data/lib/hyperion/cli.rb

@@ -44,6 +44,7 @@ module Hyperion
       # known sharp edges (SQ inheritance, SQPOLL non-survival across
       # fork). The env var is the sanctioned way to opt in.
       apply_io_uring_env_override!(config)
+      apply_io_uring_hotpath_env_override!(config)
 
       # 2.3-B: env-var overrides for the per-conn fairness cap and the
       # TLS handshake CPU throttle. Same precedence rule as the other
@@ -186,6 +187,10 @@ module Hyperion
              'Run plain HTTP/1.1 connections under Async::Scheduler (required for hyperion-async-pg and other fiber-cooperative I/O; default off)') do |v|
           cli_opts[:async_io] = v
         end
+        o.on('--io-uring-hotpath POLICY',
+             'io_uring hot path policy (off|auto|on); default off; Linux 5.19+ only') do |v|
+          cli_opts[:io_uring_hotpath] = v.to_sym
+        end
         o.on('--max-body-bytes BYTES', Integer,
              'Maximum request body size in bytes (default 16777216 = 16 MiB)') do |n|
           cli_opts[:max_body_bytes] = n
@@ -321,6 +326,7 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
                           tls_session_cache_size: config.tls.session_cache_size,
                           tls_ktls: config.tls.ktls,
                           io_uring: config.io_uring,
+                          io_uring_hotpath: config.io_uring_hotpath,
                           max_in_flight_per_conn: config.max_in_flight_per_conn,
                           tls_handshake_rate_limit: config.tls.handshake_rate_limit,
                           preload_static_dirs: config.resolved_preload_static_dirs)
@@ -515,6 +521,23 @@ WARNING: argv is visible via `ps`; prefer --admin-token-file PATH for production
     end
     private_class_method :apply_io_uring_env_override!
 
+    # Plan #2 — env override for the hotpath gate.
+    def self.apply_io_uring_hotpath_env_override!(config)
+      raw = ENV['HYPERION_IO_URING_HOTPATH']
+      return unless raw
+
+      case raw.downcase
+      when 'off', '0', 'false' then config.io_uring_hotpath = :off
+      when 'on',  '1', 'true'  then config.io_uring_hotpath = :on
+      when 'auto'              then config.io_uring_hotpath = :auto
+      else
+        Hyperion.logger.warn do
+          { message: 'HYPERION_IO_URING_HOTPATH ignored (must be off|on|auto)', value: raw }
+        end
+      end
+    end
+    private_class_method :apply_io_uring_hotpath_env_override!
+
     # 2.3-B: shared parser for `--max-in-flight-per-conn VALUE` and
     # `HYPERION_MAX_IN_FLIGHT_PER_CONN=VALUE`. Returns either a positive
     # Integer (explicit cap) or the `:auto` sentinel which `Config#finalize!`

data/lib/hyperion/config.rb

@@ -47,6 +47,15 @@ module Hyperion
       # Default flips to :auto in 2.4 only after soak. Operators flip on
       # via `HYPERION_IO_URING={on,auto}` env var to A/B test.
       io_uring: :off,
+      # Plan #2 (perf roadmap) — io_uring hot path policy. Independent
+      # gate from the accept-only `io_uring:` above. Tri-state:
+      #   :off  — accept and read/write stay on the existing paths
+      #           (default; no behavior change in 2.18 minor cut).
+      #   :auto — engage when supported (Linux 5.19+ + buffer-ring
+      #           registration succeeds); quietly fall back otherwise.
+      #   :on   — demand it. Boot raises if unsupported.
+      # Override at runtime via `HYPERION_IO_URING_HOTPATH={off,auto,on}`.
+      io_uring_hotpath: :off,
       # 2.3-B: per-connection in-flight cap. nginx upstream keep-alive
       # pipelines many client requests through one upstream connection;
       # without this cap a single greedy upstream conn can hog the worker

data/lib/hyperion/connection.rb

@@ -76,11 +76,26 @@ module Hyperion
 
     def initialize(parser: self.class.default_parser, writer: ResponseWriter.new, thread_pool: nil,
                    log_requests: nil, max_body_bytes: MAX_BODY_BYTES, runtime: nil,
-                   max_in_flight_per_conn: nil, path_templater: nil, route_table: nil)
+                   max_in_flight_per_conn: nil, path_templater: nil, route_table: nil,
+                   io_uring_owned: false, app: nil)
       @parser         = parser
       @writer         = writer
       @thread_pool    = thread_pool
       @max_body_bytes = max_body_bytes
+      # Plan #2 Task 2.4.1 — Rack app reference for io_uring-owned connections.
+      # On the regular (non-hotpath) path the app is passed to Connection#serve
+      # as a parameter and never stored. On the io_uring hotpath, Connection#serve
+      # is never called; instead the accept fiber drives dispatch via
+      # feed_read_bytes → drive_pending_requests, which needs the app stored.
+      # Nil on non-io_uring connections; those still use the serve(socket, app)
+      # call signature.
+      @app            = app
+      # Plan #2 Task 2.3.4 — when true, this connection's reads are
+      # delivered via feed_read_bytes by the accept fiber's OP_RECV
+      # handler. read_chunk must NOT be called on io_uring-owned
+      # connections (the socket is not polled via read_nonblock on
+      # the hotpath). Default false preserves existing behaviour.
+      @io_uring_owned = io_uring_owned
       # 2.3-B: per-conn fairness cap. nil disables the check entirely
       # (the hot path stays branchless). Positive integer sets the
       # in-flight ceiling. The counter + dedup-warn flag live as ivars
@@ -1071,6 +1086,193 @@ module Hyperion
       end
     end
 
+    # Plan #2 Task 2.3.4 — hotpath recv entry point.
+    #
+    # Called by the accept fiber's OP_RECV completion handler when a
+    # multishot-recv CQE arrives carrying bytes from the kernel buffer
+    # ring.  `bytes` is a String copied from the kernel-mmaped buffer
+    # slot (one allocation per CQE); the kernel can recycle the slot the
+    # moment `ring.release_buffer(buf_id)` is called in the accept fiber
+    # (AFTER this method returns).
+    #
+    # The method appends `bytes` to the per-connection read accumulator
+    # (`@inbuf`, pre-sized once per connection), then drives the parse
+    # loop to completion.  Any complete request found is dispatched via
+    # `dispatch_request` (Rack adapter path) synchronously in the accept
+    # fiber.  Carry-over bytes (pipelined input) remain in `@inbuf` for
+    # the next CQE.
+    #
+    # Returns :need_more when no complete HTTP header block was found yet,
+    # :dispatched when at least one request was parsed and dispatched, or
+    # :eof when the buffer is empty (peer closed cleanly before sending
+    # a header).  The return value is informational; the accept fiber can
+    # use it to decide whether to dispatch or simply await more CQEs.
+    #
+    # NOTE: this method runs in the accept fiber (single-threaded, GVL
+    # held). No mutex is needed on @inbuf.
+    def feed_read_bytes(bytes)
+      @inbuf ||= String.new(capacity: INBUF_INITIAL_CAPACITY,
+                            encoding: Encoding::ASCII_8BIT)
+      @inbuf << bytes
+
+      return :eof if @inbuf.empty?
+      return :need_more unless @inbuf.include?(HEADER_TERM)
+
+      # At least one complete header block is present — drive parse + dispatch.
+      drive_pending_requests
+    end
+    public :feed_read_bytes
+
+    # Plan #2 Task 2.4.1 — parse-and-dispatch loop for io_uring-owned
+    # connections.  Called by feed_read_bytes after appending CQE bytes
+    # to @inbuf.  Mirrors the core of Connection#serve's request loop but
+    # uses @socket / @app ivars (set at accept time) instead of locals.
+    #
+    # Returns :dispatched when at least one request was fully processed,
+    # :need_more when @inbuf holds data but not a complete request yet, or
+    # :eof when @inbuf is empty after carry-over trimming.
+    #
+    # Runs in the accept fiber (single-threaded, GVL held). No mutex needed
+    # on @inbuf or any of the per-connection ivars it touches.
+    def drive_pending_requests
+      @hijacked = false unless defined?(@hijacked)
+      @last_response_was_static_inline_blocking = false \
+        unless defined?(@last_response_was_static_inline_blocking)
+
+      dispatched_any = false
+
+      loop do
+        # Fast-fail: no complete headers yet.
+        break unless @inbuf.include?(HEADER_TERM)
+
+        # Attempt to parse one request from @inbuf.  @inbuf IS the buffer
+        # (not a copy) — carry_into_inbuf! trims it in-place after parse.
+        begin
+          request, body_end = @parser.parse(@inbuf)
+        rescue ParseError => e
+          @metrics.increment(:parse_errors)
+          @logger.warn { { message: 'parse error (hotpath)', error: e.message,
+                           error_class: e.class.name } }
+          begin
+            @socket.write("HTTP/1.1 400 Bad Request\r\ncontent-length: 11\r\n" \
+                          "connection: close\r\n\r\nBad Request")
+          rescue StandardError
+            nil
+          end
+          @inbuf.clear
+          break
+        rescue UnsupportedError => e
+          @logger.warn { { message: 'unsupported request (hotpath)', error: e.message,
+                           error_class: e.class.name } }
+          begin
+            @socket.write("HTTP/1.1 501 Not Implemented\r\ncontent-length: 15\r\n" \
+                          "connection: close\r\n\r\nNot Implemented")
+          rescue StandardError
+            nil
+          end
+          @inbuf.clear
+          break
+        end
+
+        # Snapshot hijack-buffered carry BEFORE trimming @inbuf.
+        @hijack_buffered = if @inbuf.bytesize > body_end
+                             @inbuf.byteslice(body_end, @inbuf.bytesize - body_end).b
+                           else
+                             EMPTY_BIN
+                           end
+        carry_into_inbuf!(@inbuf, body_end)
+
+        peer_addr = peer_address(@socket)
+        request   = enrich_with_peer(request, peer_addr) if peer_addr && request.peer_address.nil?
+
+        @metrics.increment(:bytes_read, body_end)
+        @metrics.increment(:requests_total)
+        @metrics.increment(:requests_in_flight)
+        @metrics.increment_labeled_counter(Hyperion::Metrics::REQUESTS_DISPATCH_TOTAL,
+                                           @worker_id_label_tuple)
+
+        @response_dispatch_mode = nil
+        request_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # 2.10-D direct-dispatch fast path.
+        if @route_table && (direct_handler = @route_table.lookup(request.method, request.path))
+          dispatch_direct!(@socket, request, direct_handler, request_started_at, peer_addr)
+          dispatched_any = true
+          # keep-alive: loop to process any pipelined requests already in @inbuf.
+          next if should_keep_alive_after_direct?(request)
+
+          break
+        end
+
+        # Per-conn fairness gate (mirrors serve's logic).
+        skip_per_conn_fairness = @last_response_was_static_inline_blocking
+        unless @max_in_flight_per_conn.nil? || skip_per_conn_fairness || \
+               per_conn_admit!(@socket, peer_addr)
+          @metrics.decrement(:requests_in_flight)
+          dispatched_any = true
+          next
+        end
+
+        begin
+          status, headers, body = call_app(@app, request)
+        ensure
+          @metrics.decrement(:requests_in_flight)
+          per_conn_release! if @max_in_flight_per_conn && !skip_per_conn_fairness
+        end
+
+        # Rack hijack: app took the socket — stop processing.
+        if @hijacked
+          @logger.debug do
+            { message: 'rack hijack (hotpath)', method: request.method,
+              path: request.path, peer_addr: peer_addr }
+          end
+          body.close if body.respond_to?(:close)
+          break
+        end
+
+        keep_alive = should_keep_alive?(request, status, headers)
+        @writer.write(@socket, status, headers, body, keep_alive: keep_alive,
+                                                       dispatch_mode: @response_dispatch_mode)
+        @last_response_was_static_inline_blocking =
+          @response_dispatch_mode == :inline_blocking
+        @metrics.increment_status(status)
+        log_request(request, status, request_started_at) if @log_requests
+        observe_request_duration(request, status, request_started_at)
+        dispatched_any = true
+
+        # Stop looping if the response told the peer we're closing.
+        break unless keep_alive
+      end
+
+      if dispatched_any
+        :dispatched
+      elsif @inbuf.empty?
+        :eof
+      else
+        :need_more
+      end
+    rescue StandardError => e
+      @metrics.increment(:app_errors)
+      @logger.error do
+        { message: 'unhandled in drive_pending_requests', error: e.message,
+          error_class: e.class.name }
+      end
+      :error
+    end
+
+    # Plan #2 Task 2.3.4 — called by the accept fiber when the OP_RECV
+    # CQE result is <= 0 (peer EOF or error).  Decrements the active-
+    # connection gauge that was incremented at accept time (normally
+    # handled in Connection#serve's ensure block — that block is NOT
+    # reached for io_uring-owned connections whose lifecycle is managed
+    # entirely by the accept fiber).
+    #
+    # The socket itself is closed by the accept fiber after this returns.
+    def close_for_eof
+      @metrics.decrement(:connections_active)
+    end
+    public :close_for_eof
+
     # Read up to READ_CHUNK bytes, returning whatever's available. Unlike
     # IO#read(N) — which blocks until N bytes or EOF — read_nonblock returns
     # as soon as any data arrives, which is what we need for live HTTP
@@ -1084,6 +1286,12 @@ module Hyperion
     # against stalled peers (SO_RCVTIMEO and IO#timeout= don't reliably trip
     # readpartial on Ruby 3.3).
     def read_chunk(socket)
+      # Plan #2 Task 2.3.4 — io_uring-owned connections receive data
+      # via feed_read_bytes from the accept fiber's OP_RECV handler.
+      # read_chunk must not be called on these connections; the accept
+      # fiber never calls Connection#serve for hotpath conns.
+      raise 'BUG: read_chunk called on io_uring-owned connection' if @io_uring_owned
+
       result = socket.read_nonblock(READ_CHUNK, exception: false)
       return result if result.is_a?(String) # hot path: data was buffered, return immediately
       return nil if result.nil?             # EOF

data/lib/hyperion/http/response_writer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Hyperion
+  module Http
+    # Direct-syscall response writer for plain-TCP kernel fds.
+    #
+    # The C primitives are registered as singleton methods on this
+    # very module by `ext/hyperion_http/response_writer.c` (see
+    # `Init_hyperion_response_writer`). Surface from C:
+    #
+    #   ResponseWriter.available?            -> true | false
+    #   ResponseWriter.c_write_buffered(io, status, headers, body,
+    #                                   keep_alive, date_str) -> Integer
+    #   ResponseWriter.c_write_chunked(io, status, headers, body,
+    #                                  keep_alive, date_str)  -> Integer
+    #   ResponseWriter.c_write_buffered_via_ring(io, status, headers,
+    #                                            body, keep_alive,
+    #                                            date_str, ring_ptr)
+    #                                           -> Integer
+    #     Plan #2 seam: submits a send SQE via the io_uring crate instead
+    #     of issuing writev directly. Falls back to c_write_buffered when
+    #     the io_uring crate is not loaded (hyp_submit_send_fn == NULL
+    #     after lazy dlsym attempt). ring_ptr is the HotpathRing raw
+    #     pointer as an Integer.
+    #
+    # Operators can flip the dispatcher off at runtime with
+    # `Hyperion::Http::ResponseWriter.c_writer_available = false`
+    # (test seam / A/B rollback). Mirrors the
+    # `Hyperion::ResponseWriter.page_cache_available = false`
+    # pattern (response_writer.rb:60-65).
+    module ResponseWriter
+      class << self
+        attr_writer :c_writer_available
+
+        def c_writer_available?
+          return @c_writer_available unless @c_writer_available.nil?
+
+          @c_writer_available =
+            respond_to?(:available?) && available? &&
+            respond_to?(:c_write_buffered) &&
+            respond_to?(:c_write_chunked)
+        end
+      end
+    end
+  end
+end

data/lib/hyperion/io_uring.rb

@@ -39,7 +39,7 @@ module Hyperion
   #   * One ring per fiber that needs it (the accept fiber, optionally
   #     per-connection read fibers in a future phase).
   #   * Ring is opened lazily on first use:
-  #       Fiber.current[:hyperion_io_uring] ||=
+  #       Fiber[:hyperion_io_uring] ||=
   #         Hyperion::IOUring::Ring.new(queue_depth: 256)
   #   * Ring is closed when the fiber exits.
   #   * Workers don't share rings across fork — each child opens its own.
@@ -52,7 +52,7 @@ module Hyperion
   # 2.4 only after 6 months of soak. io_uring code in production has
   # too many sharp edges to default-on without field validation.
   module IOUring
-    EXPECTED_ABI = 1
+    EXPECTED_ABI = 2
     # Linux 5.6 stabilized IORING_OP_ACCEPT (commit 17f2fe35d080,
     # mainlined Mar 2020). 5.5 had a buggy precursor that the io-uring
     # crate refuses to use. We gate on 5.6 to match the crate's stance.
@@ -139,6 +139,123 @@ module Hyperion
       end
     end
 
+    # Plan #2 — io_uring hot path: multishot accept + multishot recv
+    # with kernel-managed buffer rings + send SQEs. One ring per
+    # worker; the accept fiber drains the unified completion queue.
+    class HotpathRing
+      DEFAULT_QUEUE_DEPTH = 1024
+      DEFAULT_N_BUFS      = 512
+      DEFAULT_BUF_SIZE    = 8192
+
+      # Layout matches the Rust `#[repr(C)] Completion` struct
+      # (hotpath.rs has a compile-time assert of size = 24):
+      #   u8 op_kind | i32 fd | i64 result | i32 buf_id | u32 flags
+      # padded to native alignment. Total: 24 bytes.
+      COMPLETION_BYTES = 24
+      MAX_BATCH        = 64
+
+      # Op-kind values must match Rust's `OpKind` enum in hotpath.rs.
+      OP_ACCEPT = 1
+      OP_RECV   = 2
+      OP_SEND   = 3
+      OP_CLOSE  = 4
+
+      def initialize(queue_depth: DEFAULT_QUEUE_DEPTH,
+                     n_bufs: DEFAULT_N_BUFS,
+                     buf_size: DEFAULT_BUF_SIZE)
+        raise Unsupported, 'io_uring hotpath not supported on this host' \
+          unless IOUring.hotpath_supported?
+
+        @ptr = IOUring.hotpath_ring_new(queue_depth, n_bufs, buf_size)
+        raise Unsupported, 'hotpath ring allocation failed' if @ptr.nil?
+
+        @completion_buf = Fiddle::Pointer.malloc(COMPLETION_BYTES * MAX_BATCH,
+                                                 Fiddle::RUBY_FREE)
+        @closed = false
+      end
+
+      def submit_accept_multishot(listener_fd)
+        rc = IOUring.hotpath_submit_accept(@ptr, listener_fd.to_i)
+        raise SystemCallError.new('hotpath submit_accept', -rc) if rc.negative?
+        nil
+      end
+
+      def submit_recv_multishot(fd)
+        rc = IOUring.hotpath_submit_recv(@ptr, fd.to_i)
+        raise SystemCallError.new('hotpath submit_recv', -rc) if rc.negative?
+        nil
+      end
+
+      def submit_send(fd, iov_ptr, iov_count)
+        rc = IOUring.hotpath_submit_send(@ptr, fd.to_i, iov_ptr, iov_count.to_i)
+        raise SystemCallError.new('hotpath submit_send', -rc) if rc.negative?
+        nil
+      end
+
+      # Drain up to MAX_BATCH completions. Yields each as a frozen
+      # Hash; returns the count yielded. Caller is responsible for
+      # `release_buffer(buf_id)` after consuming a recv buffer view.
+      #
+      # If wait_completions returns -1 (ring went unhealthy), this
+      # method returns 0 yielded and the caller must check `healthy?`
+      # to detect the state and fall back to accept4.
+      def each_completion(min_complete: 1, timeout_ms: 100)
+        n = IOUring.hotpath_wait(@ptr, min_complete, timeout_ms,
+                                 @completion_buf, MAX_BATCH)
+        return 0 if n.negative?
+
+        n.times do |i|
+          offset = i * COMPLETION_BYTES
+          op_kind = @completion_buf[offset, 1].unpack1('C')
+          fd      = @completion_buf[offset + 4, 4].unpack1('l<')
+          result  = @completion_buf[offset + 8, 8].unpack1('q<')
+          buf_id  = @completion_buf[offset + 16, 4].unpack1('l<')
+          flags   = @completion_buf[offset + 20, 4].unpack1('L<')
+          yield(op_kind: op_kind, fd: fd, result: result,
+                buf_id: buf_id, flags: flags)
+        end
+        n
+      end
+
+      def release_buffer(buf_id)
+        IOUring.hotpath_release_buf(@ptr, buf_id.to_i)
+      end
+
+      # Plan #2 Task 2.3.4 — copy `len` bytes from kernel buffer-ring
+      # slot `buf_id` into a freshly-allocated Ruby String.
+      #
+      # The caller MUST call `release_buffer(buf_id)` after this returns
+      # so the kernel can reuse the slot. One allocation per recv CQE —
+      # acceptable as a baseline; the zero-copy variant is deferred.
+      def copy_buffer(buf_id, len)
+        out = Fiddle::Pointer.malloc(len, Fiddle::RUBY_FREE)
+        rc = IOUring.hotpath_copy_buffer(@ptr, buf_id.to_i, len.to_i, out, len.to_i)
+        raise SystemCallError.new('hotpath copy_buffer', -rc) if rc.negative?
+        out.to_str(rc)
+      end
+
+      def force_unhealthy!
+        IOUring.hotpath_force_unhealthy(@ptr)
+      end
+
+      def healthy?
+        IOUring.hotpath_is_healthy(@ptr) == 1
+      end
+
+      def close
+        return if @closed
+        @closed = true
+        IOUring.hotpath_ring_free(@ptr) if @ptr && !@ptr.null?
+        @ptr = nil
+      end
+
+      def closed?
+        @closed
+      end
+
+      attr_reader :ptr
+    end
+
     class << self
       # Cached three-state result: nil = not-yet-probed, true/false = result.
       #
@@ -155,9 +272,29 @@ module Hyperion
       # specs that stub Etc.uname or RbConfig.
       def reset!
         @supported = nil
+        @hotpath_supported = nil
         @lib = nil
       end
 
+      # Plan #2 — true when (a) accept-only `supported?` true, AND
+      # (b) the kernel actually accepts pbuf-ring registration (5.19+).
+      # NOTE: this does NOT probe RecvMulti (6.0+); the Ruby caller
+      # must treat the first recv CQE failure as a feature-unavailable
+      # signal — see hotpath.rs's hyperion_io_uring_hotpath_supported
+      # doc comment for the full kernel-version matrix.
+      def hotpath_supported?
+        return @hotpath_supported unless @hotpath_supported.nil?
+        @hotpath_supported = compute_hotpath_supported
+      end
+
+      def compute_hotpath_supported
+        return false unless supported?
+        return false unless @hotpath_supported_fn
+        @hotpath_supported_fn.call.zero?
+      rescue StandardError
+        false
+      end
+
       # ---- Internal: feature gate ----
 
       def compute_supported
@@ -249,6 +386,63 @@ module Hyperion
                                          Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT,
                                          Fiddle::TYPE_VOIDP],
                                         Fiddle::TYPE_INT)
+
+        # Plan #2 — hotpath surface (5.19+ for PBUF_RING, 6.0+ for RecvMulti).
+        @hotpath_supported_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_supported'], [], Fiddle::TYPE_INT
+        )
+        @hotpath_ring_new_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_ring_new'],
+          [Fiddle::TYPE_INT, Fiddle::TYPE_SHORT, Fiddle::TYPE_INT],
+          Fiddle::TYPE_VOIDP
+        )
+        @hotpath_ring_free_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_ring_free'],
+          [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID
+        )
+        @hotpath_submit_accept_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_submit_accept_multishot'],
+          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_INT
+        )
+        @hotpath_submit_recv_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_submit_recv_multishot'],
+          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT], Fiddle::TYPE_INT
+        )
+        @hotpath_submit_send_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_submit_send'],
+          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT],
+          Fiddle::TYPE_INT
+        )
+        @hotpath_wait_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_wait_completions'],
+          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_INT,
+           Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT],
+          Fiddle::TYPE_INT
+        )
+        @hotpath_release_buf_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_release_buffer'],
+          [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SHORT], Fiddle::TYPE_VOID
+        )
+        @hotpath_force_unhealthy_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_force_unhealthy'],
+          [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID
+        )
+        @hotpath_is_healthy_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_is_healthy'],
+          [Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT
+        )
+        # Plan #2 Task 2.3.4 — one-copy buffer extraction: copies `len`
+        # bytes from kernel buffer-ring slot `buf_id` into a
+        # caller-supplied output buffer. Returns byte count or negative errno.
+        @hotpath_copy_buffer_fn = Fiddle::Function.new(
+          @lib['hyperion_io_uring_hotpath_copy_buffer'],
+          [Fiddle::TYPE_VOIDP,  # ptr
+           Fiddle::TYPE_SHORT,  # buf_id (u16)
+           Fiddle::TYPE_INT,    # len (u32)
+           Fiddle::TYPE_VOIDP,  # out_ptr
+           Fiddle::TYPE_INT],   # out_cap (u32)
+          Fiddle::TYPE_INT
+        )
         @lib
       rescue Fiddle::DLError, StandardError => e
         warn "[hyperion] IOUring failed to load (#{e.class}: #{e.message}); falling back to epoll"
@@ -259,9 +453,16 @@ module Hyperion
       def candidate_paths
         gem_lib = File.expand_path('../hyperion_io_uring', __dir__)
         ext_target = File.expand_path('../../ext/hyperion_io_uring/target/release', __dir__)
-        %w[libhyperion_io_uring.dylib libhyperion_io_uring.so].flat_map do |name|
-          [File.join(gem_lib, name), File.join(ext_target, name)]
-        end
+        # Prefer the platform-native extension first so Fiddle.dlopen doesn't
+        # accidentally pick up a cross-platform binary (e.g. a macOS .dylib
+        # rsync'd into a Linux lib dir) which causes an ArgumentError on read.
+        native, other = linux? ? %w[.so .dylib] : %w[.dylib .so]
+        [
+          File.join(gem_lib,    "libhyperion_io_uring#{native}"),
+          File.join(ext_target, "libhyperion_io_uring#{native}"),
+          File.join(gem_lib,    "libhyperion_io_uring#{other}"),
+          File.join(ext_target, "libhyperion_io_uring#{other}"),
+        ]
       end
 
       # ---- FFI wrappers ----
@@ -282,6 +483,48 @@ module Hyperion
       def ring_read(ptr, fd, buf, max, errno_buf)
         @read_fn.call(ptr, fd, buf, max, errno_buf)
       end
+
+      def hotpath_ring_new(qd, n_bufs, buf_size)
+        ptr = @hotpath_ring_new_fn.call(qd, n_bufs, buf_size)
+        ptr.null? ? nil : ptr
+      end
+
+      def hotpath_ring_free(ptr); @hotpath_ring_free_fn.call(ptr); end
+
+      def hotpath_submit_accept(ptr, fd)
+        @hotpath_submit_accept_fn.call(ptr, fd)
+      end
+
+      def hotpath_submit_recv(ptr, fd)
+        @hotpath_submit_recv_fn.call(ptr, fd)
+      end
+
+      def hotpath_submit_send(ptr, fd, iov, n)
+        @hotpath_submit_send_fn.call(ptr, fd, iov, n)
+      end
+
+      def hotpath_wait(ptr, mc, t, out, cap)
+        @hotpath_wait_fn.call(ptr, mc, t, out, cap)
+      end
+
+      def hotpath_release_buf(ptr, buf_id)
+        @hotpath_release_buf_fn.call(ptr, buf_id)
+      end
+
+      def hotpath_force_unhealthy(ptr)
+        @hotpath_force_unhealthy_fn.call(ptr)
+      end
+
+      def hotpath_is_healthy(ptr)
+        @hotpath_is_healthy_fn.call(ptr)
+      end
+
+      # Plan #2 Task 2.3.4 — copy `len` bytes from kernel buffer-ring
+      # slot `buf_id` into the caller-supplied output buffer. Returns
+      # the number of bytes written, or a negative errno on failure.
+      def hotpath_copy_buffer(ptr, buf_id, len, out_ptr, out_cap)
+        @hotpath_copy_buffer_fn.call(ptr, buf_id, len, out_ptr, out_cap)
+      end
     end
 
     # ---- Server-side helpers ----
@@ -313,5 +556,27 @@ module Hyperion
         raise ArgumentError, "io_uring must be :off, :auto, or :on (got #{policy.inspect})"
       end
     end
+
+    # Plan #2 — resolve `:off | :auto | :on` for the hotpath gate.
+    # Mirrors `resolve_policy!` semantics: `:on` raises on unsupported,
+    # `:auto` quietly falls back, `:off` returns false.
+    def self.resolve_hotpath_policy!(policy)
+      case policy
+      when :off, nil, false
+        false
+      when :auto
+        hotpath_supported?
+      when :on, true
+        unless hotpath_supported?
+          raise Unsupported,
+                'io_uring hotpath required (io_uring_hotpath: :on) but unsupported on this host ' \
+                "(linux=#{linux?}, kernel_ok=#{kernel_supports_io_uring?}, " \
+                "hotpath_supported=#{hotpath_supported?})"
+        end
+        true
+      else
+        raise ArgumentError, "io_uring_hotpath must be :off, :auto, or :on (got #{policy.inspect})"
+      end
+    end
   end
 end