nghttp3 0.0.1

data/lib/nghttp3/response.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Nghttp3
+  # An HTTP/3 response object
+  #
+  # Can be used for both:
+  # - Client-side: receiving response from server (populated via callbacks)
+  # - Server-side: building response to send to client
+  class Response
+    # @return [Integer] stream ID
+    attr_reader :stream_id
+
+    # @return [Integer, nil] HTTP status code
+    attr_accessor :status
+
+    # @return [Headers] response headers
+    attr_reader :headers
+
+    # @return [String, nil] response body (for simple responses)
+    attr_accessor :body
+
+    # Create a new response
+    # @param stream_id [Integer] the stream ID this response belongs to
+    # @param status [Integer, nil] HTTP status code
+    # @param headers [Hash, Headers, nil] response headers
+    # @param body [String, nil] response body
+    def initialize(stream_id:, status: nil, headers: nil, body: nil)
+      @stream_id = stream_id
+      @status = status
+      @headers = headers.is_a?(Headers) ? headers : Headers.new(headers || {})
+      @body = body
+      @body_chunks = []
+      @headers_sent = false
+      @finished = false
+    end
+
+    # Convert to NV array for low-level Connection API (server-side)
+    # @return [Array<NV>] array of NV objects for status and headers
+    def to_nv_array
+      nvs = []
+      nvs << NV.new(":status", @status.to_s) if @status
+      @headers.each { |name, value| nvs << NV.new(name, value) }
+      nvs
+    end
+
+    # Mark headers as sent (for streaming responses)
+    # @param extra_headers [Hash] additional headers to merge before sending
+    # @return [self]
+    def write_headers(extra_headers = {})
+      raise InvalidStateError, "Headers already sent" if @headers_sent
+      @headers.merge!(extra_headers) unless extra_headers.empty?
+      @headers_sent = true
+      self
+    end
+
+    # Check if headers have been sent
+    # @return [Boolean]
+    def headers_sent?
+      @headers_sent
+    end
+
+    # Write a chunk of body data (for streaming responses)
+    # @param chunk [String] body chunk to write
+    # @return [self]
+    def write(chunk)
+      raise InvalidStateError, "Response already finished" if @finished
+      @body_chunks << chunk.to_s
+      self
+    end
+
+    # Get all body chunks written so far
+    # @return [Array<String>]
+    def body_chunks
+      @body_chunks.dup
+    end
+
+    # Get combined body from chunks
+    # @return [String]
+    def body_from_chunks
+      @body_chunks.join
+    end
+
+    # Mark the response as finished
+    # @return [self]
+    def finish
+      @finished = true
+      self
+    end
+
+    # Check if the response is finished
+    # @return [Boolean]
+    def finished?
+      @finished
+    end
+
+    # Check if response has a body
+    # @return [Boolean]
+    def body?
+      (@body && !@body.empty?) || !@body_chunks.empty?
+    end
+
+    # Get the effective body (either set body or joined chunks)
+    # @return [String, nil]
+    def effective_body
+      return @body if @body && !@body.empty?
+      return nil if @body_chunks.empty?
+      body_from_chunks
+    end
+
+    # Append data to body (for client-side receiving)
+    # @param data [String] data to append
+    # @return [self]
+    def append_body(data)
+      @body ||= +""
+      @body << data
+      self
+    end
+
+    # String representation
+    def inspect
+      status_str = @status ? @status.to_s : "pending"
+      finished_str = @finished ? " finished" : ""
+      "#<#{self.class} stream_id=#{@stream_id} status=#{status_str}#{finished_str}>"
+    end
+  end
+end

data/lib/nghttp3/server.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+module Nghttp3
+  # High-level HTTP/3 server
+  #
+  # Wraps the low-level Connection API with automatic request handling,
+  # convenient response building, and stream management.
+  #
+  # @example Basic usage
+  #   server = Nghttp3::Server.new
+  #   server.bind_streams(control: 3, qpack_encoder: 7, qpack_decoder: 11)
+  #
+  #   server.on_request do |request, response|
+  #     response.status = 200
+  #     response.headers["content-type"] = "text/html"
+  #     response.body = "<h1>Hello!</h1>"
+  #   end
+  #
+  #   # Feed data from QUIC layer
+  #   server.read_stream(stream_id, received_data, fin: false)
+  #
+  #   # Pump data to QUIC layer
+  #   server.pump_writes do |stream_id, data, fin|
+  #     quic.write(stream_id, data, fin)
+  #   end
+  class Server
+    # @return [Connection] the underlying low-level connection
+    attr_reader :connection
+
+    # @return [Settings] the settings used for this server
+    attr_reader :settings
+
+    # @return [Hash{Integer => Request}] received requests by stream ID
+    attr_reader :requests
+
+    # @return [Hash{Integer => Response}] responses by stream ID
+    attr_reader :responses
+
+    # Create a new HTTP/3 server
+    # @param settings [Settings, nil] settings to use (defaults to Settings.default)
+    def initialize(settings: nil)
+      @settings = settings || Settings.default
+      @callbacks = setup_callbacks
+      @connection = Connection.server_new(@settings, @callbacks)
+      @stream_manager = StreamManager.new(is_server: true)
+      @request_handler = nil
+      @requests = {}
+      @responses = {}
+      @building_requests = {}  # Requests being built (headers not complete)
+      @streams_bound = false
+    end
+
+    # Bind control and QPACK streams
+    #
+    # Must be called before handling requests. The stream IDs should be
+    # unidirectional streams opened by the QUIC layer.
+    #
+    # @param control [Integer] control stream ID
+    # @param qpack_encoder [Integer] QPACK encoder stream ID
+    # @param qpack_decoder [Integer] QPACK decoder stream ID
+    # @return [self]
+    def bind_streams(control:, qpack_encoder:, qpack_decoder:)
+      @connection.bind_control_stream(control)
+      @connection.bind_qpack_streams(qpack_encoder, qpack_decoder)
+      @stream_manager.register_stream(control, type: :uni)
+      @stream_manager.register_stream(qpack_encoder, type: :uni)
+      @stream_manager.register_stream(qpack_decoder, type: :uni)
+      @streams_bound = true
+      self
+    end
+
+    # Check if streams are bound
+    # @return [Boolean]
+    def streams_bound?
+      @streams_bound
+    end
+
+    # Register a request handler
+    #
+    # The handler is called when a complete request is received.
+    # The handler should set response.status and response.body (or use streaming).
+    #
+    # @yield [request, response] for each incoming request
+    # @yieldparam request [Request] the incoming request
+    # @yieldparam response [Response] the response object to populate
+    # @return [self]
+    def on_request(&block)
+      @request_handler = block
+      self
+    end
+
+    # Pump pending writes to the QUIC layer
+    #
+    # @yield [stream_id, data, fin] for each pending write
+    # @yieldparam stream_id [Integer] the stream ID
+    # @yieldparam data [String] the data to write
+    # @yieldparam fin [Boolean] true if this is the final data for the stream
+    # @yieldreturn [Integer] number of bytes accepted by QUIC layer
+    # @return [self]
+    def pump_writes
+      while (result = @connection.writev_stream)
+        stream_id = result[:stream_id]
+        data = result[:data]
+        fin = result[:fin]
+
+        bytes_written = yield(stream_id, data, fin) if block_given?
+        bytes_written ||= data.bytesize
+
+        @connection.add_write_offset(stream_id, bytes_written)
+      end
+      self
+    end
+
+    # Read data from QUIC layer into HTTP/3 connection
+    # @param stream_id [Integer] stream ID
+    # @param data [String] received data
+    # @param fin [Boolean] true if this is the final data for the stream
+    # @return [Integer] number of bytes consumed
+    def read_stream(stream_id, data, fin: false)
+      @connection.read_stream(stream_id, data, fin: fin)
+    end
+
+    # Notify that bytes have been acknowledged by the peer
+    # @param stream_id [Integer] stream ID
+    # @param n [Integer] number of bytes acknowledged
+    # @return [self]
+    def add_ack_offset(stream_id, n)
+      @connection.add_ack_offset(stream_id, n)
+      self
+    end
+
+    # Close the server connection
+    # @return [nil]
+    def close
+      @connection.close
+    end
+
+    # Check if the connection is closed
+    # @return [Boolean]
+    def closed?
+      @connection.closed?
+    end
+
+    private
+
+    def setup_callbacks
+      Callbacks.new
+        .on_begin_headers { |stream_id| on_begin_headers(stream_id) }
+        .on_recv_header { |stream_id, name, value, flags| on_recv_header(stream_id, name, value, flags) }
+        .on_end_headers { |stream_id, fin| on_end_headers(stream_id, fin) }
+        .on_recv_data { |stream_id, data| on_recv_data(stream_id, data) }
+        .on_end_stream { |stream_id| on_end_stream(stream_id) }
+        .on_stream_close { |stream_id, app_error_code| on_stream_close(stream_id, app_error_code) }
+    end
+
+    def on_begin_headers(stream_id)
+      # Start building a new request
+      @building_requests[stream_id] = {
+        method: nil,
+        scheme: nil,
+        authority: nil,
+        path: nil,
+        headers: Headers.new,
+        body: nil
+      }
+      @stream_manager.register_stream(stream_id, type: :bidi)
+    end
+
+    def on_recv_header(stream_id, name, value, _flags)
+      req = @building_requests[stream_id]
+      return unless req
+
+      case name
+      when ":method"
+        req[:method] = value
+      when ":scheme"
+        req[:scheme] = value
+      when ":authority"
+        req[:authority] = value
+      when ":path"
+        req[:path] = value
+      else
+        req[:headers][name] = value
+      end
+    end
+
+    def on_end_headers(stream_id, fin)
+      # Headers complete, create immutable Request
+      req_data = @building_requests[stream_id]
+      return unless req_data
+
+      @requests[stream_id] = Request.new(
+        method: req_data[:method] || "GET",
+        scheme: req_data[:scheme] || "https",
+        authority: req_data[:authority],
+        path: req_data[:path] || "/",
+        headers: req_data[:headers]
+      )
+
+      # Create response object
+      @responses[stream_id] = Response.new(stream_id: stream_id)
+
+      # If request has no body (fin=true), process it immediately
+      process_request(stream_id) if fin
+    end
+
+    def on_recv_data(stream_id, data)
+      req_data = @building_requests[stream_id]
+      if req_data
+        req_data[:body] ||= +""
+        req_data[:body] << data
+      end
+    end
+
+    def on_end_stream(stream_id)
+      # Request complete with body
+      req_data = @building_requests.delete(stream_id)
+      if req_data && @requests[stream_id].nil?
+        # Headers weren't finalized yet, create request with body
+        @requests[stream_id] = Request.new(
+          method: req_data[:method] || "GET",
+          scheme: req_data[:scheme] || "https",
+          authority: req_data[:authority],
+          path: req_data[:path] || "/",
+          headers: req_data[:headers],
+          body: req_data[:body]
+        )
+        @responses[stream_id] ||= Response.new(stream_id: stream_id)
+      end
+
+      process_request(stream_id)
+    end
+
+    def on_stream_close(stream_id, _app_error_code)
+      @building_requests.delete(stream_id)
+      @stream_manager.close_stream(stream_id)
+    end
+
+    def process_request(stream_id)
+      request = @requests[stream_id]
+      response = @responses[stream_id]
+      return unless request && response && @request_handler
+
+      # Call the request handler
+      @request_handler.call(request, response)
+
+      # Submit the response if status is set
+      if response.status
+        @connection.submit_response(stream_id, response.to_nv_array, body: response.effective_body)
+      end
+    end
+  end
+end

data/lib/nghttp3/stream_manager.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Nghttp3
+  # Internal stream ID management
+  #
+  # HTTP/3 uses different stream ID allocation for clients and servers:
+  # - Client-initiated bidirectional streams: 0, 4, 8, 12, ...
+  # - Server-initiated bidirectional streams: 1, 5, 9, 13, ...
+  # - Client-initiated unidirectional streams: 2, 6, 10, 14, ...
+  # - Server-initiated unidirectional streams: 3, 7, 11, 15, ...
+  #
+  # @private
+  class StreamManager
+    # Stream types
+    BIDI_CLIENT = 0x00
+    BIDI_SERVER = 0x01
+    UNI_CLIENT = 0x02
+    UNI_SERVER = 0x03
+
+    def initialize(is_server:)
+      @is_server = is_server
+      # Next stream IDs by type
+      @next_bidi_stream_id = is_server ? 1 : 0
+      @next_uni_stream_id = is_server ? 3 : 2
+      # Track active streams
+      @active_streams = {}
+    end
+
+    # Allocate a new bidirectional stream ID
+    # @return [Integer] new stream ID
+    def allocate_bidi_stream_id
+      id = @next_bidi_stream_id
+      @next_bidi_stream_id += 4
+      @active_streams[id] = {type: :bidi, state: :open}
+      id
+    end
+
+    # Allocate a new unidirectional stream ID
+    # @return [Integer] new stream ID
+    def allocate_uni_stream_id
+      id = @next_uni_stream_id
+      @next_uni_stream_id += 4
+      @active_streams[id] = {type: :uni, state: :open}
+      id
+    end
+
+    # Register an externally-opened stream (e.g., from QUIC layer)
+    # @param stream_id [Integer] stream ID
+    # @param type [Symbol] :bidi or :uni
+    def register_stream(stream_id, type: :bidi)
+      @active_streams[stream_id] = {type: type, state: :open}
+    end
+
+    # Close a stream
+    # @param stream_id [Integer] stream ID to close
+    def close_stream(stream_id)
+      if @active_streams[stream_id]
+        @active_streams[stream_id][:state] = :closed
+      end
+    end
+
+    # Remove a stream from tracking
+    # @param stream_id [Integer] stream ID to remove
+    def remove_stream(stream_id)
+      @active_streams.delete(stream_id)
+    end
+
+    # Check if stream is active
+    # @param stream_id [Integer] stream ID
+    # @return [Boolean]
+    def stream_active?(stream_id)
+      @active_streams[stream_id]&.dig(:state) == :open
+    end
+
+    # Get all active stream IDs
+    # @return [Array<Integer>]
+    def active_stream_ids
+      @active_streams.select { |_, v| v[:state] == :open }.keys
+    end
+
+    # Get stream info
+    # @param stream_id [Integer] stream ID
+    # @return [Hash, nil] stream info or nil if not found
+    def stream_info(stream_id)
+      @active_streams[stream_id]&.dup
+    end
+
+    # Check if this is a client-initiated stream
+    # @param stream_id [Integer] stream ID
+    # @return [Boolean]
+    def client_initiated?(stream_id)
+      (stream_id & 0x01) == 0
+    end
+
+    # Check if this is a server-initiated stream
+    # @param stream_id [Integer] stream ID
+    # @return [Boolean]
+    def server_initiated?(stream_id)
+      (stream_id & 0x01) == 1
+    end
+
+    # Check if this is a bidirectional stream
+    # @param stream_id [Integer] stream ID
+    # @return [Boolean]
+    def bidirectional?(stream_id)
+      (stream_id & 0x02) == 0
+    end
+
+    # Check if this is a unidirectional stream
+    # @param stream_id [Integer] stream ID
+    # @return [Boolean]
+    def unidirectional?(stream_id)
+      (stream_id & 0x02) == 2
+    end
+  end
+end

data/lib/nghttp3/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Nghttp3
+  VERSION = "0.0.1"
+end

data/lib/nghttp3.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "nghttp3/version"
+require_relative "nghttp3/nghttp3"
+
+# High-level API
+require_relative "nghttp3/headers"
+require_relative "nghttp3/request"
+require_relative "nghttp3/response"
+require_relative "nghttp3/stream_manager"
+require_relative "nghttp3/client"
+require_relative "nghttp3/server"
+
+module Nghttp3
+  class Error < StandardError; end
+end

data/sig/nghttp3/callbacks.rbs

@@ -0,0 +1,30 @@
+module Nghttp3
+  class Callbacks
+    def initialize: () -> void
+
+    # Stream data callbacks
+    def on_acked_stream_data: () { (Integer stream_id, Integer datalen) -> void } -> self
+    def on_stream_close: () { (Integer stream_id, Integer app_error_code) -> void } -> self
+    def on_recv_data: () { (Integer stream_id, String data) -> void } -> self
+    def on_deferred_consume: () { (Integer stream_id, Integer consumed) -> void } -> self
+
+    # Header callbacks
+    def on_begin_headers: () { (Integer stream_id) -> void } -> self
+    def on_recv_header: () { (Integer stream_id, String name, String value, Integer flags) -> void } -> self
+    def on_end_headers: () { (Integer stream_id, bool fin) -> void } -> self
+
+    # Trailer callbacks
+    def on_begin_trailers: () { (Integer stream_id) -> void } -> self
+    def on_recv_trailer: () { (Integer stream_id, String name, String value, Integer flags) -> void } -> self
+    def on_end_trailers: () { (Integer stream_id, bool fin) -> void } -> self
+
+    # Stream control callbacks
+    def on_stop_sending: () { (Integer stream_id, Integer app_error_code) -> void } -> self
+    def on_end_stream: () { (Integer stream_id) -> void } -> self
+    def on_reset_stream: () { (Integer stream_id, Integer app_error_code) -> void } -> self
+
+    # Connection callbacks
+    def on_shutdown: () { (Integer id) -> void } -> self
+    def on_recv_settings: () { (Hash[Symbol, untyped] settings) -> void } -> self
+  end
+end

data/sig/nghttp3/client.rbs

@@ -0,0 +1,38 @@
+module Nghttp3
+  class Client
+    attr_reader connection: Connection
+    attr_reader settings: Settings
+    attr_reader responses: Hash[Integer, Response]
+    attr_reader pending_requests: Hash[Integer, Request]
+
+    def initialize: (?settings: Settings?) -> void
+
+    def bind_streams: (control: Integer, qpack_encoder: Integer, qpack_decoder: Integer) -> self
+    def streams_bound?: () -> bool
+
+    def submit: (Request request) -> Integer
+
+    def get: (String url, ?headers: Hash[String, String]) -> Integer
+    def post: (String url, ?body: String?, ?headers: Hash[String, String]) -> Integer
+    def put: (String url, ?body: String?, ?headers: Hash[String, String]) -> Integer
+    def delete: (String url, ?headers: Hash[String, String]) -> Integer
+    def head: (String url, ?headers: Hash[String, String]) -> Integer
+
+    def pump_writes: () { (Integer stream_id, String data, bool fin) -> Integer? } -> self
+    def read_stream: (Integer stream_id, String data, ?fin: bool) -> Integer
+    def add_ack_offset: (Integer stream_id, Integer n) -> self
+
+    def close: () -> nil
+    def closed?: () -> bool
+
+    private
+
+    def setup_callbacks: () -> Callbacks
+    def on_begin_headers: (Integer stream_id) -> void
+    def on_recv_header: (Integer stream_id, String name, String value, Integer flags) -> void
+    def on_end_headers: (Integer stream_id, bool fin) -> void
+    def on_recv_data: (Integer stream_id, String data) -> void
+    def on_end_stream: (Integer stream_id) -> void
+    def on_stream_close: (Integer stream_id, Integer app_error_code) -> void
+  end
+end

data/sig/nghttp3/connection.rbs

@@ -0,0 +1,85 @@
+module Nghttp3
+  class Connection
+    # Creates a new client connection
+    def self.client_new: (?Settings? settings, ?Callbacks? callbacks) -> Connection
+
+    # Creates a new server connection
+    def self.server_new: (?Settings? settings, ?Callbacks? callbacks) -> Connection
+
+    # Binds the control stream
+    def bind_control_stream: (Integer stream_id) -> self
+
+    # Binds QPACK encoder and decoder streams
+    def bind_qpack_streams: (Integer encoder_stream_id, Integer decoder_stream_id) -> self
+
+    # Closes the connection
+    def close: () -> nil
+
+    # Returns true if the connection is closed
+    def closed?: () -> bool
+
+    # Returns true if this is a server connection
+    def server?: () -> bool
+
+    # Returns true if this is a client connection
+    def client?: () -> bool
+
+    # Stream operations
+
+    # Reads data on a stream from the QUIC layer
+    def read_stream: (Integer stream_id, String data, ?fin: bool) -> Integer
+
+    # Gets stream data to send to the QUIC layer
+    def writev_stream: () -> { stream_id: Integer, fin: bool, data: String }?
+
+    # Tells the connection that n bytes have been accepted by the QUIC layer
+    def add_write_offset: (Integer stream_id, Integer n) -> self
+
+    # Tells the connection that n bytes have been acknowledged by the remote peer
+    def add_ack_offset: (Integer stream_id, Integer n) -> self
+
+    # Marks a stream as blocked due to QUIC flow control
+    def block_stream: (Integer stream_id) -> self
+
+    # Marks a stream as unblocked
+    def unblock_stream: (Integer stream_id) -> self
+
+    # Returns true if the stream is writable
+    def stream_writable?: (Integer stream_id) -> bool
+
+    # Closes the stream with the given error code
+    def close_stream: (Integer stream_id, Integer app_error_code) -> self
+
+    # Prevents any further write operations on the stream
+    def shutdown_stream_write: (Integer stream_id) -> self
+
+    # Resumes a stream that was blocked for input data
+    def resume_stream: (Integer stream_id) -> self
+
+    # HTTP operations
+
+    # Submits an HTTP request (client only)
+    def submit_request: (Integer stream_id, Array[NV] headers, ?body: String?) ?{ (Integer stream_id) -> (String | Symbol | nil) } -> self
+
+    # Submits an HTTP response (server only)
+    def submit_response: (Integer stream_id, Array[NV] headers, ?body: String?) ?{ (Integer stream_id) -> (String | Symbol | nil) } -> self
+
+    # Submits a 1xx informational response
+    def submit_info: (Integer stream_id, Array[NV] headers) -> self
+
+    # Submits trailer headers (implicitly ends the stream)
+    def submit_trailers: (Integer stream_id, Array[NV] trailers) -> self
+
+    # Signals the intention to shut down the connection gracefully
+    def submit_shutdown_notice: () -> self
+
+    # Initiates graceful shutdown
+    def shutdown: () -> self
+
+    # Associates arbitrary data with a stream
+    def set_stream_user_data: (Integer stream_id, untyped data) -> self
+
+    # Returns data associated with a stream
+    def get_stream_user_data: (Integer stream_id) -> untyped
+  end
+end