quicsilver 0.2.0 → 0.4.0

data/lib/quicsilver/transport/configuration.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class Configuration
+      attr_reader :cert_file, :key_file, :idle_timeout_ms, :server_resumption_level, :max_concurrent_requests,
+        :max_unidirectional_streams, :stream_receive_window, :stream_receive_buffer, :connection_flow_control_window,
+        :pacing_enabled, :send_buffering_enabled, :initial_rtt_ms, :initial_window_packets, :max_ack_delay_ms,
+        :keep_alive_interval_ms, :congestion_control_algorithm, :migration_enabled,
+        :disconnect_timeout_ms, :handshake_idle_timeout_ms,
+        :max_body_size, :max_header_size, :max_header_count, :max_frame_payload_size,
+        :early_data_policy,
+        :mode
+
+      QUIC_SERVER_RESUME_AND_ZERORTT = 1
+      QUIC_SERVER_RESUME_ONLY = 2
+      QUIC_SERVER_RESUME_AND_REUSE = 3
+      QUIC_SERVER_RESUME_AND_REUSE_ZERORTT = 4
+
+      # Congestion control algorithms
+      CONGESTION_CONTROL_CUBIC = 0
+      CONGESTION_CONTROL_BBR = 1
+
+      DEFAULT_CERT_FILE = "certificates/server.crt"
+      DEFAULT_KEY_FILE = "certificates/server.key"
+      DEFAULT_ALPN = "h3"
+
+      # Flow control defaults — cross-referenced with quiche, quic-go, lsquic, RFC 9000
+      # See: https://github.com/microsoft/msquic/blob/main/docs/Settings.md
+      DEFAULT_STREAM_RECEIVE_WINDOW = 262_144       # 256KB (quiche/quic-go use 1MB, MsQuic default 64KB)
+      DEFAULT_STREAM_RECEIVE_BUFFER = 32_768        # 32KB (MsQuic default 4KB — too small for typical responses)
+      DEFAULT_CONNECTION_FLOW_CONTROL_WINDOW = 16_777_216  # 16MB - connection-wide flow control
+
+      # Throughput defaults
+      DEFAULT_PACING_ENABLED = true              # RFC 9002: MUST pace or limit bursts
+      DEFAULT_SEND_BUFFERING_ENABLED = true      # MsQuic recommended — coalesces small writes
+      DEFAULT_INITIAL_RTT_MS = 100               # MsQuic default 333ms is satellite-grade; 100ms matches Chromium
+      DEFAULT_INITIAL_WINDOW_PACKETS = 10        # Matches RFC 9002 recommendation
+      DEFAULT_MAX_ACK_DELAY_MS = 25              # Matches RFC 9000 default
+
+      # Connection management defaults
+      DEFAULT_KEEP_ALIVE_INTERVAL_MS = 0         # 0 = disabled. Set to 20000 for NAT traversal
+      DEFAULT_CONGESTION_CONTROL_ALGORITHM = CONGESTION_CONTROL_CUBIC  # CUBIC (0) or BBR (1)
+      DEFAULT_MIGRATION_ENABLED = true           # Client IP migration. Disable behind load balancers
+      DEFAULT_DISCONNECT_TIMEOUT_MS = 16_000     # How long to wait for ACK before path declared dead
+      DEFAULT_HANDSHAKE_IDLE_TIMEOUT_MS = 10_000 # Handshake timeout (separate from connection idle)
+
+      def initialize(cert_file = nil, key_file = nil, options = {})
+        @idle_timeout_ms = options.fetch(:idle_timeout_ms, 10000)
+        @server_resumption_level = options.fetch(:server_resumption_level, QUIC_SERVER_RESUME_AND_ZERORTT)
+        @max_concurrent_requests = options.fetch(:max_concurrent_requests, 100)
+        @max_unidirectional_streams = options.fetch(:max_unidirectional_streams, 10)
+        @alpn = options.fetch(:alpn, DEFAULT_ALPN)
+
+        # Flow control
+        @stream_receive_window = options.fetch(:stream_receive_window, DEFAULT_STREAM_RECEIVE_WINDOW)
+        @stream_receive_buffer = options.fetch(:stream_receive_buffer, DEFAULT_STREAM_RECEIVE_BUFFER)
+        @connection_flow_control_window = options.fetch(:connection_flow_control_window, DEFAULT_CONNECTION_FLOW_CONTROL_WINDOW)
+
+        # Throughput
+        @pacing_enabled = options.fetch(:pacing_enabled, DEFAULT_PACING_ENABLED)
+        @send_buffering_enabled = options.fetch(:send_buffering_enabled, DEFAULT_SEND_BUFFERING_ENABLED)
+        @initial_rtt_ms = options.fetch(:initial_rtt_ms, DEFAULT_INITIAL_RTT_MS)
+        @initial_window_packets = options.fetch(:initial_window_packets, DEFAULT_INITIAL_WINDOW_PACKETS)
+        @max_ack_delay_ms = options.fetch(:max_ack_delay_ms, DEFAULT_MAX_ACK_DELAY_MS)
+
+        # Connection management
+        @keep_alive_interval_ms = options.fetch(:keep_alive_interval_ms, DEFAULT_KEEP_ALIVE_INTERVAL_MS)
+        @congestion_control_algorithm = options.fetch(:congestion_control_algorithm, DEFAULT_CONGESTION_CONTROL_ALGORITHM)
+        @migration_enabled = options.fetch(:migration_enabled, DEFAULT_MIGRATION_ENABLED)
+        @disconnect_timeout_ms = options.fetch(:disconnect_timeout_ms, DEFAULT_DISCONNECT_TIMEOUT_MS)
+        @handshake_idle_timeout_ms = options.fetch(:handshake_idle_timeout_ms, DEFAULT_HANDSHAKE_IDLE_TIMEOUT_MS)
+
+        # HTTP/3 parser limits (nil = unlimited)
+        @max_body_size = options[:max_body_size]
+        @max_header_size = options[:max_header_size]
+        @max_header_count = options[:max_header_count]
+        @max_frame_payload_size = options[:max_frame_payload_size]
+
+        # 0-RTT early data policy (RFC 8470)
+        # :reject (default) — send 425 Too Early for unsafe methods on 0-RTT
+        # :allow — pass all 0-RTT requests to the Rack app with env["quicsilver.early_data"]
+        @early_data_policy = options.fetch(:early_data_policy, :reject)
+        unless %i[reject allow].include?(@early_data_policy)
+          raise ServerConfigurationError, "Invalid early_data_policy: #{@early_data_policy.inspect} (must be :reject or :allow)"
+        end
+
+        # Application interface mode:
+        # :rack (default) — app is a Rack app, auto-wrapped with Protocol::Rack::Adapter
+        # :falcon — app is a native protocol-http app, used directly
+        @mode = options.fetch(:mode, :rack)
+        unless %i[rack falcon].include?(@mode)
+          raise ServerConfigurationError, "Invalid mode: #{@mode.inspect} (must be :rack or :falcon)"
+        end
+
+        @cert_file = cert_file.nil? ? DEFAULT_CERT_FILE : cert_file
+        @key_file = key_file.nil? ? DEFAULT_KEY_FILE : key_file
+
+        unless File.exist?(@cert_file)
+          raise ServerConfigurationError, "Certificate file not found: #{@cert_file}"
+        end
+
+        unless File.exist?(@key_file)
+          raise ServerConfigurationError, "Key file not found: #{@key_file}"
+        end
+      end
+
+      # Common HTTP/3 ALPN Values:
+      # "h3" - HTTP/3 (most common)
+      # "h3-29" - HTTP/3 draft version 29
+      def alpn
+        @alpn
+      end
+
+      def to_h
+        {
+          cert_file: @cert_file,
+          key_file: @key_file,
+          idle_timeout_ms: @idle_timeout_ms,
+          server_resumption_level: @server_resumption_level,
+          max_concurrent_requests: @max_concurrent_requests,
+          max_unidirectional_streams: @max_unidirectional_streams,
+          alpn: alpn,
+          stream_receive_window: @stream_receive_window,
+          stream_receive_buffer: @stream_receive_buffer,
+          connection_flow_control_window: @connection_flow_control_window,
+          pacing_enabled: @pacing_enabled ? 1 : 0,
+          send_buffering_enabled: @send_buffering_enabled ? 1 : 0,
+          initial_rtt_ms: @initial_rtt_ms,
+          initial_window_packets: @initial_window_packets,
+          max_ack_delay_ms: @max_ack_delay_ms,
+          keep_alive_interval_ms: @keep_alive_interval_ms,
+          congestion_control_algorithm: @congestion_control_algorithm,
+          migration_enabled: @migration_enabled ? 1 : 0,
+          disconnect_timeout_ms: @disconnect_timeout_ms,
+          handshake_idle_timeout_ms: @handshake_idle_timeout_ms
+        }
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/connection.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class Connection
+      include Protocol::ControlStreamParser
+
+      # MsQuic QUIC_STATUS_INVALID_STATE (POSIX errno ETOOMANYREFS = 0x59).
+      # Stream already shut down by peer — raised by StreamSend when the
+      # client has reset or closed the stream.
+      MSQUIC_INVALID_STATE = "0x59"
+
+      attr_reader :handle, :data, :streams
+      attr_reader :control_stream_id, :qpack_encoder_stream_id, :qpack_decoder_stream_id
+      attr_reader :server_control_stream
+      attr_reader :peer_goaway_id, :local_goaway_id
+      attr_reader :stream_priorities
+
+      def initialize(handle, data, max_header_size: nil)
+        @handle = handle
+        @data = data
+        @max_header_size = max_header_size
+        @streams = {}
+        @response_buffers = {}
+        @mutex = Mutex.new
+
+        # Client's control streams (received)
+        @control_stream_id = nil
+        @qpack_encoder_stream_id = nil
+        @qpack_decoder_stream_id = nil
+
+        # Server's control stream (sent)
+        @server_control_stream = nil
+
+        @settings = {}
+        @settings_received = false
+        @peer_goaway_id = nil
+        @local_goaway_id = nil
+        @stream_priorities = {}
+      end
+
+      # === Setup (called after connection established) ===
+
+      def setup_http3_streams
+        # Control stream (required)
+        @server_control_stream = open_stream(unidirectional: true)
+        @server_control_stream.send(Protocol.build_control_stream(max_field_section_size: @max_header_size))
+
+        # QPACK encoder/decoder streams
+        [0x02, 0x03].each do |type|
+          stream = open_stream(unidirectional: true)
+          stream.send([type].pack("C"))
+        end
+
+        # GREASE unidirectional stream (RFC 9297)
+        stream = open_stream(unidirectional: true)
+        stream.send(Protocol.encode_varint(Protocol.grease_id) + "GREASE".b)
+      end
+
+      # === Stream Management ===
+
+      def add_stream(stream)
+        @streams[stream.stream_id] = stream
+      end
+
+      def get_stream(stream_id)
+        @streams[stream_id]
+      end
+
+      def remove_stream(stream_id)
+        @streams.delete(stream_id)
+      end
+
+      def track_client_stream(stream_id)
+        @streams[stream_id] = true
+      end
+
+      # === Data Handling ===
+
+      def buffer_data(stream_id, data)
+        @mutex.synchronize do
+          (@response_buffers[stream_id] ||= "".b) << data
+        end
+      end
+
+      def complete_stream(stream_id, final_data)
+        @mutex.synchronize do
+          buffer = @response_buffers.delete(stream_id)
+          (buffer || "".b) + (final_data || "".b)
+        end
+      end
+
+      # === HTTP/3 Frames ===
+
+      def send_goaway(stream_id = nil)
+        return unless @server_control_stream
+
+        stream_id ||= last_client_stream_id
+        validate_goaway_id!(stream_id)
+
+        @server_control_stream.send(Protocol.build_goaway_frame(stream_id))
+        @local_goaway_id = stream_id
+      rescue ArgumentError
+        raise  # Re-raise validation errors
+      rescue => e
+        Quicsilver.logger.error("Failed to send GOAWAY: #{e.message}")
+      end
+
+      # RFC 9114 §5.2: GOAWAY IDs MUST NOT increase from a previous value.
+      def validate_goaway_id!(stream_id)
+        if @local_goaway_id && stream_id > @local_goaway_id
+          raise ArgumentError, "GOAWAY stream ID #{stream_id} exceeds previous #{@local_goaway_id}"
+        end
+      end
+
+      # Send an informational (1xx) response before the final response.
+      # RFC 9114 §4.1: encoded as a HEADERS frame, no FIN.
+      def send_informational(stream, status, headers)
+        data = Protocol::ResponseEncoder.encode_informational(status, headers)
+        Quicsilver.send_stream(stream.stream_handle, data, false)
+      rescue RuntimeError => e
+        raise unless e.message.include?(MSQUIC_INVALID_STATE) || e.message.include?("StreamSend failed")
+        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+      end
+
+      def send_response(stream, status, headers, body, head_request: false, trailers: nil)
+        body = [] if body.nil?
+        encoder = Protocol::ResponseEncoder.new(status, headers, body, head_request: head_request, trailers: trailers)
+
+        if body.respond_to?(:to_ary)
+          Quicsilver.send_stream(stream.stream_handle, encoder.encode, true)
+        else
+          encoder.stream_encode do |frame_data, fin|
+            Quicsilver.send_stream(stream.stream_handle, frame_data, fin) unless frame_data.empty? && !fin
+          end
+        end
+      rescue RuntimeError => e
+        # Stream may have been reset by client - this is expected
+        raise unless e.message.include?(MSQUIC_INVALID_STATE) || e.message.include?("StreamSend failed")
+        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+      end
+
+      def send_error(stream, status, message)
+        body = ["#{status} #{message}"]
+        encoder = Protocol::ResponseEncoder.new(status, { "content-type" => "text/plain" }, body)
+        Quicsilver.send_stream(stream.stream_handle, encoder.encode, true)
+      rescue RuntimeError => e
+        # Stream may have been reset by client - this is expected
+        raise unless e.message.include?(MSQUIC_INVALID_STATE) || e.message.include?("StreamSend failed")
+        Quicsilver.logger.debug("Stream send failed (client likely reset): #{e.message}")
+      end
+
+      # === Control Stream Handling ===
+
+      # Process incoming data on a unidirectional stream incrementally.
+      # Called on each RECEIVE event — control streams never send FIN.
+      def receive_unidirectional_data(stream_id, data)
+        @mutex.synchronize do
+          (@response_buffers[stream_id] ||= "".b) << data
+        end
+
+        buf = @mutex.synchronize { @response_buffers[stream_id] || "".b }
+        return if buf.empty?
+
+        # First time seeing this stream: identify stream type
+        unless @uni_stream_types&.key?(stream_id)
+          @uni_stream_types ||= {}
+          stream_type, type_len = Protocol.decode_varint(buf.bytes, 0)
+          return if type_len == 0  # need more data
+
+          case stream_type
+          when 0x00 # Control stream
+            raise Protocol::FrameError, "Duplicate control stream" if @control_stream_id
+            @control_stream_id = stream_id
+            @uni_stream_types[stream_id] = :control
+            # Remove the stream type byte from the buffer
+            @mutex.synchronize { @response_buffers[stream_id] = (buf[type_len..] || "".b) }
+          when 0x01
+            raise Protocol::FrameError, "Client must not send push streams"
+          when 0x02 # QPACK encoder stream
+            raise Protocol::FrameError, "Duplicate QPACK encoder stream" if @qpack_encoder_stream_id
+            @qpack_encoder_stream_id = stream_id
+            @uni_stream_types[stream_id] = :qpack_encoder
+            @mutex.synchronize { @response_buffers[stream_id] = (buf[type_len..] || "".b) }
+          when 0x03 # QPACK decoder stream
+            raise Protocol::FrameError, "Duplicate QPACK decoder stream" if @qpack_decoder_stream_id
+            @qpack_decoder_stream_id = stream_id
+            @uni_stream_types[stream_id] = :qpack_decoder
+            @mutex.synchronize { @response_buffers[stream_id] = (buf[type_len..] || "".b) }
+          else
+            # Unknown unidirectional stream types MUST be ignored (RFC 9114 §6.2)
+            @uni_stream_types[stream_id] = :unknown
+            return
+          end
+
+          buf = @mutex.synchronize { @response_buffers[stream_id] || "".b }
+        end
+
+        stream_type = @uni_stream_types[stream_id]
+        return if buf.empty?
+
+        case stream_type
+        when :control
+          parse_control_frames(buf)
+          # Clear parsed data from buffer
+          @mutex.synchronize { @response_buffers[stream_id] = "".b }
+        when :qpack_encoder
+          validate_qpack_encoder_data(buf)
+          @mutex.synchronize { @response_buffers[stream_id] = "".b }
+        when :qpack_decoder
+          validate_qpack_decoder_data(buf)
+          @mutex.synchronize { @response_buffers[stream_id] = "".b }
+        end
+      end
+
+      def handle_unidirectional_stream(stream, fin: true)
+        stream_id = stream.stream_id
+
+        # Already known as critical stream — closure via FIN is an error
+        if fin && critical_stream?(stream_id)
+          raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+        end
+
+        data = stream.data
+        return if data.empty?
+
+        stream_type, type_len = Protocol.decode_varint(data.bytes, 0)
+        return if type_len == 0
+        payload = data[type_len..-1]
+
+        case stream_type
+        when 0x00
+          set_control_stream(stream_id, payload)
+          if fin
+            raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+          end
+        when 0x01
+          raise Protocol::FrameError, "Client must not send push streams"
+        when 0x02
+          raise Protocol::FrameError, "Duplicate QPACK encoder stream" if @qpack_encoder_stream_id
+          @qpack_encoder_stream_id = stream_id
+          if fin
+            raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+          end
+        when 0x03
+          raise Protocol::FrameError, "Duplicate QPACK decoder stream" if @qpack_decoder_stream_id
+          @qpack_decoder_stream_id = stream_id
+          if fin
+            raise Protocol::FrameError.new("Closure of critical stream", error_code: Protocol::H3_CLOSED_CRITICAL_STREAM)
+          end
+        end
+      end
+
+      def set_control_stream(stream_id, payload = nil)
+        raise Protocol::FrameError, "Duplicate control stream" if @control_stream_id
+        @control_stream_id = stream_id
+        parse_control_frames(payload) if payload && !payload.empty?
+      end
+
+      def settings
+        @settings
+      end
+
+      # Get the priority for a stream. Returns default Priority if not set.
+      def stream_priority(stream_id)
+        @stream_priorities[stream_id] || Protocol::Priority.new
+      end
+
+      # Apply priority to a QUIC stream via MsQuic.
+      # MsQuic: 0 = lowest, 0xFFFF = highest.
+      # HTTP urgency: 0 = highest, 7 = lowest.
+      # Maps urgency into evenly spaced bands across the uint16 range.
+      # The priority is queued and applied on the MsQuic event thread.
+      def apply_stream_priority(stream, priority)
+        handle = stream.respond_to?(:stream_handle) ? stream.stream_handle : nil
+        return unless handle
+        quic_priority = (7 - priority.urgency) * 0x2000
+        Quicsilver.set_stream_priority(handle, quic_priority)
+      rescue => e
+        Quicsilver.logger.debug("Failed to set stream priority: #{e.message}")
+      end
+
+      def critical_stream?(stream_id)
+        stream_id == @control_stream_id ||
+          stream_id == @qpack_encoder_stream_id ||
+          stream_id == @qpack_decoder_stream_id
+      end
+
+      # === Shutdown ===
+
+      def shutdown(error_code = 0)
+        send_goaway
+        Quicsilver.connection_shutdown(@handle, error_code, false)
+      end
+
+      private
+
+      def open_stream(unidirectional: false)
+        handle = Quicsilver.open_stream(@data, unidirectional)
+        Stream.new(handle)
+      end
+
+      def last_client_stream_id
+        @streams.keys.select { |id| (id & 0x02) == 0 }.max || 0
+      end
+
+      # Frame types forbidden on the control stream
+      FORBIDDEN_ON_CONTROL = [
+        0x00, # DATA — request streams only
+        0x01, # HEADERS — request streams only
+        0x02, # HTTP/2 PRIORITY (reserved)
+        0x05, # PUSH_PROMISE — request streams only
+        0x06, # HTTP/2 PING (reserved)
+        0x08, # HTTP/2 WINDOW_UPDATE (reserved)
+        0x09, # HTTP/2 CONTINUATION (reserved)
+      ].freeze
+
+      def on_settings_received(settings)
+        @settings.merge!(settings)
+      end
+
+      def handle_control_frame(type, payload)
+        if FORBIDDEN_ON_CONTROL.include?(type)
+          raise Protocol::FrameError, "Frame type 0x#{type.to_s(16)} not allowed on control stream"
+        end
+
+        if type == Protocol::FRAME_PRIORITY_UPDATE
+          parse_priority_update(payload)
+        end
+      end
+
+      # RFC 9218 §7: Parse PRIORITY_UPDATE frame.
+      # Payload is a stream ID varint followed by a Priority Field Value string.
+      def parse_priority_update(payload)
+        stream_id, consumed = Protocol.decode_varint(payload.bytes, 0)
+        priority_value = payload[consumed..]
+        @stream_priorities[stream_id] = Protocol::Priority.parse(priority_value)
+      end
+
+      # RFC 9204 §4.1.3: Validate QPACK encoder stream instructions.
+      # We advertise QPACK_MAX_TABLE_CAPACITY = 0, so any Set Dynamic Table Capacity
+      # instruction with value > 0 is an error.
+      def validate_qpack_encoder_data(data)
+        return if data.empty?
+        byte = data.bytes[0]
+
+        # Set Dynamic Table Capacity (001xxxxx)
+        if (byte & 0xE0) == 0x20
+          capacity, _ = Protocol.decode_varint(data.bytes, 0)
+          capacity &= 0x1F  # mask off the instruction prefix
+          # We advertised capacity 0, any non-zero is an error
+          raise Protocol::FrameError.new(
+            "Dynamic table capacity exceeds advertised maximum",
+            error_code: Protocol::QPACK_ENCODER_STREAM_ERROR
+          )
+        end
+      end
+
+      # RFC 9204 §4.4.3: Validate QPACK decoder stream instructions.
+      # Insert Count Increment of 0 is a decoder stream error.
+      def validate_qpack_decoder_data(data)
+        return if data.empty?
+        byte = data.bytes[0]
+
+        # Insert Count Increment (00xxxxxx)
+        if (byte & 0xC0) == 0x00
+          increment, _ = Protocol.decode_varint(data.bytes, 0)
+          increment &= 0x3F  # mask off prefix bits
+          if increment == 0
+            raise Protocol::FrameError.new(
+              "Insert Count Increment of 0 on decoder stream",
+              error_code: Protocol::QPACK_DECODER_STREAM_ERROR
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/event_loop.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class EventLoop
+      def initialize
+        @running = false
+        @thread = nil
+        @mutex = Mutex.new
+      end
+
+      def start
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @thread = Thread.new do
+            Quicsilver.poll while @running
+          end
+        end
+      end
+
+      def stop
+        @running = false
+        Quicsilver.wake
+        @thread&.join(2)
+      end
+
+      def join
+        @thread&.join
+      end
+    end
+  end
+
+  def self.event_loop
+    @event_loop ||= Transport::EventLoop.new.tap(&:start)
+  end
+end

data/lib/quicsilver/transport/inbound_stream.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    class InboundStream
+      attr_reader :stream_id, :is_unidirectional, :buffer
+      attr_accessor :stream_handle
+
+      def initialize(stream_id, is_unidirectional: nil)
+        @stream_id = stream_id
+        @is_unidirectional = is_unidirectional.nil? ? !bidirectional? : is_unidirectional
+        @buffer = StringIO.new.tap { |io| io.set_encoding(Encoding::ASCII_8BIT) }
+        @stream_handle = nil
+      end
+
+      def bidirectional?
+        (stream_id & 0x02) == 0
+      end
+
+      def writable?
+        !stream_handle.nil?
+      end
+
+      def append_data(data)
+        @buffer.write(data)
+      end
+
+      def data
+        @buffer.string
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/stream.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # Wraps a QUIC stream opened by Ruby code (client requests, server control streams).
+    # Encapsulates the C handle — callers use send/reset/stop_sending methods instead
+    # of passing raw pointers to Quicsilver.send_stream etc.
+    class Stream
+      attr_reader :handle
+
+      def initialize(handle)
+        @handle = handle
+      end
+
+      def send(data, fin: false)
+        Quicsilver.send_stream(@handle, data, fin)
+      end
+
+      def reset(error_code = Protocol::H3_REQUEST_CANCELLED)
+        Quicsilver.stream_reset(@handle, error_code)
+      end
+
+      def stop_sending(error_code = Protocol::H3_REQUEST_CANCELLED)
+        Quicsilver.stream_stop_sending(@handle, error_code)
+      end
+    end
+  end
+end

data/lib/quicsilver/transport/stream_event.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Transport
+    # Parses the binary data packed by the C extension for stream completion events.
+    # C packs events as:
+    #   RECEIVE_FIN:  [stream_handle(8)][payload...]
+    #   STREAM_RESET: [stream_handle(8)][error_code(8)]
+    #   STOP_SENDING: [stream_handle(8)][error_code(8)]
+    class StreamEvent
+      attr_reader :handle, :data, :error_code
+
+      def initialize(raw_data, event_type)
+        @handle = raw_data[0, 8].unpack1("Q")
+        remaining = raw_data[8..] || "".b
+
+        case event_type
+        when "RECEIVE_FIN"
+          @data = remaining
+        when "STREAM_RESET", "STOP_SENDING"
+          @error_code = remaining.unpack1("Q")
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/version.rb

@@ -1,3 +1,3 @@
 module Quicsilver
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end