quicsilver 0.5.0-x86_64-linux

data/lib/quicsilver/protocol/frames.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    # HTTP/3 Frame Types (RFC 9114)
+    FRAME_DATA = 0x00
+    FRAME_HEADERS = 0x01
+    FRAME_CANCEL_PUSH = 0x03
+    FRAME_SETTINGS = 0x04
+    FRAME_PUSH_PROMISE = 0x05
+    FRAME_GOAWAY = 0x07
+    FRAME_MAX_PUSH_ID = 0x0d
+    FRAME_PRIORITY_UPDATE = 0xF0700  # RFC 9218 — request stream priority update
+
+    # Settings identifiers
+    SETTINGS_QPACK_MAX_TABLE_CAPACITY = 0x01
+    SETTINGS_QPACK_BLOCKED_STREAMS = 0x07
+    SETTINGS_ENABLE_CONNECT_PROTOCOL = 0x08  # RFC 9220
+    SETTINGS_H3_DATAGRAM = 0x33              # RFC 9297
+    SETTINGS_ENABLE_WEBTRANSPORT = 0x2b603742 # WebTransport draft-06
+    SETTINGS_WT_ENABLED = 0x2c7cf000          # WebTransport over HTTP/3
+    SETTINGS_WT_MAX_SESSIONS = 0x14e9cd29    # Legacy WebTransport session limit
+    SETTINGS_WT_INITIAL_MAX_DATA = 0x2b61
+    SETTINGS_WT_INITIAL_MAX_STREAMS_UNI = 0x2b64
+    SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI = 0x2b65
+
+    # Declaring a non-zero value for any of these is how an endpoint opts into
+    # WebTransport session flow control (draft-16 §5.1). It is a promise to
+    # implement the whole of §5, so do not advertise one until the capsules
+    # and accounting exist.
+    # The session flow control window we advertise. 16 MiB leaves room for
+    # many children above the 1 MiB each queues, and 100 streams per direction
+    # bounds concurrency without being a limit an application trips over.
+    # Both are our choice; the draft only defines the mechanism.
+    WT_INITIAL_MAX_DATA = 16 * 1024 * 1024
+    WT_INITIAL_MAX_STREAMS = 100
+
+    WT_FLOW_CONTROL_SETTINGS = [
+      SETTINGS_WT_INITIAL_MAX_DATA,
+      SETTINGS_WT_INITIAL_MAX_STREAMS_UNI,
+      SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI
+    ].freeze
+    SETTINGS_MAX_FIELD_SECTION_SIZE = 0x06   # RFC 9114 §7.2.4.1
+
+    # Frame types forbidden on request streams (RFC 9114 Section 7.2.4, 7.2.6, 7.2.7)
+    CONTROL_ONLY_FRAMES = [FRAME_CANCEL_PUSH, FRAME_SETTINGS, FRAME_GOAWAY, FRAME_MAX_PUSH_ID].freeze
+    CONTROL_ONLY_FRAME_SET = CONTROL_ONLY_FRAMES.to_h { |type| [type, true] }.freeze
+
+    # HTTP/2 frame types, reserved in HTTP/3 so that an HTTP/2 frame arriving
+    # here is rejected rather than mistaken for an extension (RFC 9114 7.2.8)
+    HTTP2_RESERVED_FRAME_SET = {0x02 => true, 0x06 => true, 0x08 => true, 0x09 => true}.freeze
+
+    # WT_STREAM is registered as a frame type to reserve the code point, but it
+    # carries no length and is only legal as the very first bytes of a request
+    # stream, where the server classifies it before any frame parsing. Anywhere
+    # else it is a connection error (draft-ietf-webtrans-http3-16 §4.3).
+    FRAME_WT_STREAM = 0x41
+    # HTTP/3 Datagram Error Code (RFC 9297 Section 5.2)
+    H3_DATAGRAM_ERROR = 0x33
+
+    # HTTP/3 Error Codes (RFC 9114 Section 8.1)
+    H3_NO_ERROR = 0x100
+    H3_GENERAL_PROTOCOL_ERROR = 0x101
+    H3_INTERNAL_ERROR = 0x102
+    H3_STREAM_CREATION_ERROR = 0x103
+    H3_CLOSED_CRITICAL_STREAM = 0x104
+    H3_FRAME_UNEXPECTED = 0x105
+    H3_FRAME_ERROR = 0x106
+    H3_EXCESSIVE_LOAD = 0x107
+    H3_ID_ERROR = 0x108
+    H3_SETTINGS_ERROR = 0x109
+    H3_MISSING_SETTINGS = 0x10a
+    H3_REQUEST_REJECTED = 0x10b
+    H3_REQUEST_CANCELLED = 0x10c
+    H3_REQUEST_INCOMPLETE = 0x10d
+    H3_MESSAGE_ERROR = 0x10e
+    H3_CONNECT_ERROR = 0x10f
+    H3_VERSION_FALLBACK = 0x110
+
+    # QPACK Error Codes (RFC 9204 Section 6)
+    QPACK_DECOMPRESSION_FAILED = 0x200
+    QPACK_ENCODER_STREAM_ERROR = 0x201
+    QPACK_DECODER_STREAM_ERROR = 0x202
+
+    # Protocol errors that carry an HTTP/3 error code for CONNECTION_CLOSE / RESET_STREAM.
+    # FrameError → connection error (CONNECTION_CLOSE)
+    # MessageError → stream error (RESET_STREAM) on request streams
+    class FrameError < Quicsilver::Error
+      attr_reader :error_code
+      # The default suits a frame that is valid but arrived somewhere it is not
+      # allowed (RFC 9114 4.1, 7.2.4), which is the common case. Anything else
+      # must pass its own code: callers that leave this implicit are asserting
+      # H3_FRAME_UNEXPECTED is correct, and the handler turns that into a
+      # connection error.
+      def initialize(msg = nil, error_code: H3_FRAME_UNEXPECTED)
+        @error_code = error_code
+        super(msg)
+      end
+    end
+
+    class MessageError < Quicsilver::Error
+      attr_reader :error_code
+      def initialize(msg = nil, error_code: H3_MESSAGE_ERROR)
+        @error_code = error_code
+        super(msg)
+      end
+    end
+
+    # QPACK Static Table Indices (RFC 9204 Appendix A)
+    STATIC_TABLE = [
+      [':authority', ''],                                      # 0
+      [':path', '/'],                                          # 1
+      ['age', '0'],                                            # 2
+      ['content-disposition', ''],                             # 3
+      ['content-length', '0'],                                 # 4
+      ['cookie', ''],                                          # 5
+      ['date', ''],                                            # 6
+      ['etag', ''],                                            # 7
+      ['if-modified-since', ''],                               # 8
+      ['if-none-match', ''],                                   # 9
+      ['last-modified', ''],                                   # 10
+      ['link', ''],                                            # 11
+      ['location', ''],                                        # 12
+      ['referer', ''],                                         # 13
+      ['set-cookie', ''],                                      # 14
+      [':method', 'CONNECT'],                                  # 15
+      [':method', 'DELETE'],                                   # 16
+      [':method', 'GET'],                                      # 17
+      [':method', 'HEAD'],                                     # 18
+      [':method', 'OPTIONS'],                                  # 19
+      [':method', 'POST'],                                     # 20
+      [':method', 'PUT'],                                      # 21
+      [':scheme', 'http'],                                     # 22
+      [':scheme', 'https'],                                    # 23
+      [':status', '103'],                                      # 24
+      [':status', '200'],                                      # 25
+      [':status', '304'],                                      # 26
+      [':status', '404'],                                      # 27
+      [':status', '503'],                                      # 28
+      ['accept', '*/*'],                                       # 29
+      ['accept', 'application/dns-message'],                   # 30
+      ['accept-encoding', 'gzip, deflate, br'],                # 31
+      ['accept-ranges', 'bytes'],                              # 32
+      ['access-control-allow-headers', 'cache-control'],       # 33
+      ['access-control-allow-headers', 'content-type'],        # 34
+      ['access-control-allow-origin', '*'],                    # 35
+      ['cache-control', 'max-age=0'],                          # 36
+      ['cache-control', 'max-age=2592000'],                    # 37
+      ['cache-control', 'max-age=604800'],                     # 38
+      ['cache-control', 'no-cache'],                           # 39
+      ['cache-control', 'no-store'],                           # 40
+      ['cache-control', 'public, max-age=31536000'],           # 41
+      ['content-encoding', 'br'],                              # 42
+      ['content-encoding', 'gzip'],                            # 43
+      ['content-type', 'application/dns-message'],             # 44
+      ['content-type', 'application/javascript'],              # 45
+      ['content-type', 'application/json'],                    # 46
+      ['content-type', 'application/x-www-form-urlencoded'],   # 47
+      ['content-type', 'image/gif'],                           # 48
+      ['content-type', 'image/jpeg'],                          # 49
+      ['content-type', 'image/png'],                           # 50
+      ['content-type', 'text/css'],                            # 51
+      ['content-type', 'text/html; charset=utf-8'],            # 52
+      ['content-type', 'text/plain'],                          # 53
+      ['content-type', 'text/plain;charset=utf-8'],            # 54
+      ['range', 'bytes=0-'],                                   # 55
+      ['strict-transport-security', 'max-age=31536000'],       # 56
+      ['strict-transport-security', 'max-age=31536000; includeSubDomains'], # 57
+      ['strict-transport-security', 'max-age=31536000; includeSubDomains; preload'], # 58
+      ['vary', 'accept-encoding'],                             # 59
+      ['vary', 'origin'],                                      # 60
+      ['x-content-type-options', 'nosniff'],                   # 61
+      ['x-xss-protection', '1; mode=block'],                   # 62
+      [':status', '100'],                                      # 63
+      [':status', '204'],                                      # 64
+      [':status', '206'],                                      # 65
+      [':status', '302'],                                      # 66
+      [':status', '400'],                                      # 67
+      [':status', '403'],                                      # 68
+      [':status', '421'],                                      # 69
+      [':status', '425'],                                      # 70
+      [':status', '500'],                                      # 71
+      ['accept-language', ''],                                 # 72
+      ['access-control-allow-credentials', 'FALSE'],           # 73
+      ['access-control-allow-credentials', 'TRUE'],            # 74
+      ['access-control-allow-headers', '*'],                   # 75
+      ['access-control-allow-methods', 'get'],                 # 76
+      ['access-control-allow-methods', 'get, post, options'],  # 77
+      ['access-control-allow-methods', 'options'],             # 78
+      ['access-control-expose-headers', 'content-length'],     # 79
+      ['access-control-request-headers', 'content-type'],      # 80
+      ['access-control-request-method', 'get'],                # 81
+      ['access-control-request-method', 'post'],               # 82
+      ['alt-svc', 'clear'],                                    # 83
+      ['authorization', ''],                                   # 84
+      ['content-security-policy', "script-src 'none'; object-src 'none'; base-uri 'none'"], # 85
+      ['early-data', '1'],                                     # 86
+      ['expect-ct', ''],                                       # 87
+      ['forwarded', ''],                                       # 88
+      ['if-range', ''],                                        # 89
+      ['origin', ''],                                          # 90
+      ['purpose', 'prefetch'],                                 # 91
+      ['server', ''],                                          # 92
+      ['timing-allow-origin', '*'],                            # 93
+      ['upgrade-insecure-requests', '1'],                      # 94
+      ['user-agent', ''],                                      # 95
+      ['x-forwarded-for', ''],                                 # 96
+      ['x-frame-options', 'deny'],                             # 97
+      ['x-frame-options', 'sameorigin']                        # 98
+    ].freeze
+
+    # Commonly used indices
+    QPACK_AUTHORITY = 0
+    QPACK_PATH = 1
+    QPACK_CONTENT_LENGTH = 4
+    QPACK_METHOD_CONNECT = 15
+    QPACK_METHOD_DELETE = 16
+    QPACK_METHOD_GET = 17
+    QPACK_METHOD_HEAD = 18
+    QPACK_METHOD_OPTIONS = 19
+    QPACK_METHOD_POST = 20
+    QPACK_METHOD_PUT = 21
+    QPACK_SCHEME_HTTP = 22
+    QPACK_SCHEME_HTTPS = 23
+    QPACK_STATUS_200 = 25
+    QPACK_STATUS_404 = 27
+    QPACK_STATUS_500 = 71
+    QPACK_STATUS_400 = 67
+    QPACK_CONTENT_TYPE_JSON = 46
+    QPACK_CONTENT_TYPE_PLAIN = 53
+
+    # Maximum stream ID for initial GOAWAY (2^62 - 4, per RFC 9114)
+    MAX_STREAM_ID = (2**62) - 4
+
+    class << self
+      # Frame types a request stream may carry. Unknown types are extensions and
+      # must be ignored (RFC 9114 9), so only the two reserved sets raise.
+      # Both the buffered parser and the streaming body reader validate here.
+      def reject_unexpected_request_frame!(type)
+        if CONTROL_ONLY_FRAME_SET.key?(type)
+          raise FrameError, "Frame type 0x#{type.to_s(16)} not allowed on request streams"
+        end
+
+        if HTTP2_RESERVED_FRAME_SET.key?(type)
+          raise FrameError.new("Reserved HTTP/2 frame type 0x#{type.to_s(16)} not allowed in HTTP/3",
+            error_code: H3_FRAME_UNEXPECTED)
+        end
+
+        # Reaching here means the stream already parsed as HTTP/3, so this
+        # WT_STREAM is not at the front of the stream (draft-16 §4.3).
+        if type == FRAME_WT_STREAM
+          raise FrameError.new("WT_STREAM is only allowed as the first bytes of a request stream",
+            error_code: H3_FRAME_ERROR)
+        end
+      end
+
+      # Precomputed varint encodings for single-byte values (0-63)
+      VARINT_SMALL = Array.new(64) { |v| [v].pack('C').freeze }.freeze
+      VARINT_MED = Array.new(16384 - 64) { |i| v = i + 64; [0x40 | (v >> 8), v & 0xFF].pack('C*').freeze }.freeze
+
+      # Cache for large varint encodings (values >= 16384)
+      VARINT_LARGE_CACHE = {}
+      VARINT_LARGE_CACHE_MAX = 256
+
+      # Encode variable-length integer
+      def encode_varint(value)
+        if value < 64
+          VARINT_SMALL[value]
+        elsif value < 16384
+          VARINT_MED[value - 64]
+        else
+          cached = VARINT_LARGE_CACHE[value]
+          return cached if cached
+
+          result = if value < 1073741824
+            [0x80 | (value >> 24), (value >> 16) & 0xFF,
+            (value >> 8) & 0xFF, value & 0xFF].pack('C*').freeze
+          else
+            [0xC0 | (value >> 56), (value >> 48) & 0xFF,
+            (value >> 40) & 0xFF, (value >> 32) & 0xFF,
+            (value >> 24) & 0xFF, (value >> 16) & 0xFF,
+            (value >> 8) & 0xFF, value & 0xFF].pack('C*').freeze
+          end
+
+          VARINT_LARGE_CACHE[value] = result if VARINT_LARGE_CACHE.size < VARINT_LARGE_CACHE_MAX
+          result
+        end
+      end
+
+      def build_settings_frame(settings = {})
+        payload = ""
+        settings.each do |id, value|
+          payload += encode_varint(id)
+          payload += encode_varint(value)
+        end
+
+        frame_type = encode_varint(FRAME_SETTINGS)
+        frame_length = encode_varint(payload.bytesize)
+
+        frame_type + frame_length + payload
+      end
+
+      # Generate a random GREASE ID (RFC 9114 §7.2.4.1): 0x1f * N + 0x21
+      def grease_id
+        31 * rand(0..20) + 33
+      end
+
+      # Has this endpoint declared intent to use session flow control? Both
+      # endpoints must, for it to be enabled.
+      def wt_flow_control_opt_in?(settings)
+        WT_FLOW_CONTROL_SETTINGS.any? { |id| settings[id].to_i > 0 }
+      end
+
+      # The SETTINGS we advertise. Kept separate from the frame so a connection
+      # can ask what it promised the peer without re-parsing the wire.
+      #
+      # @param max_field_section_size [Integer, nil] Advertise SETTINGS_MAX_FIELD_SECTION_SIZE (0x06)
+      #   to the peer (RFC 9114 §4.2.2 / §7.2.4.1). nil = don't advertise.
+      def control_stream_settings(max_field_section_size: nil, datagram_receive_enabled: true)
+        settings = {
+          SETTINGS_QPACK_MAX_TABLE_CAPACITY => 0,
+          SETTINGS_QPACK_BLOCKED_STREAMS => 0,
+          SETTINGS_ENABLE_CONNECT_PROTOCOL => 1,
+          SETTINGS_H3_DATAGRAM => datagram_receive_enabled ? 1 : 0,
+          SETTINGS_ENABLE_WEBTRANSPORT => 1,
+          SETTINGS_WT_ENABLED => 1,
+          # Declaring these enables session flow control when the peer also
+          # does (§5.1): the initial limits a session grants its peer, raised
+          # by capsules as we consume data and close streams.
+          #
+          # The data window sits well above the 1 MiB a single child stream
+          # queues, so one stream cannot exhaust a session's credit, in the
+          # same spirit as QUIC keeping its connection window above any one
+          # stream's. Both values are ours to choose; the draft defines only
+          # the mechanism.
+          SETTINGS_WT_INITIAL_MAX_DATA => WT_INITIAL_MAX_DATA,
+          SETTINGS_WT_INITIAL_MAX_STREAMS_BIDI => WT_INITIAL_MAX_STREAMS,
+          SETTINGS_WT_INITIAL_MAX_STREAMS_UNI => WT_INITIAL_MAX_STREAMS,
+          # Still one session per connection. Flow control now permits more
+          # (§5.1), but sharing a connection between sessions is a separate
+          # change.
+          SETTINGS_WT_MAX_SESSIONS => 1
+        }
+        settings[SETTINGS_MAX_FIELD_SECTION_SIZE] = max_field_section_size if max_field_section_size
+        settings
+      end
+
+      # Build control stream data.
+      def build_control_stream(max_field_section_size: nil, datagram_receive_enabled: true)
+        stream_type = [0x00].pack("C")  # Control stream type
+        settings_hash = control_stream_settings(
+          max_field_section_size: max_field_section_size,
+          datagram_receive_enabled: datagram_receive_enabled
+        )
+        settings_hash[grease_id] = grease_id  # GREASE setting (RFC 9114 §7.2.4.1)
+
+        stream_type + build_settings_frame(settings_hash)
+      end
+
+      # Build GOAWAY frame (RFC 9114 Section 7.2.6)
+      # stream_id: The last client-initiated bidirectional stream ID the server will process
+      # Build an HTTP/3 frame: varint type + varint length + payload.
+      def build_frame(type, payload)
+        payload = payload.to_s.b
+        encode_varint(type) + encode_varint(payload.bytesize) + payload
+      end
+
+      # Build a HEADERS frame from key-value pairs via QPACK.
+      def build_headers_frame(pairs, encoder: Qpack::Encoder.new)
+        build_frame(FRAME_HEADERS, encoder.encode(pairs))
+      end
+
+      def build_goaway_frame(stream_id)
+        frame_type = encode_varint(FRAME_GOAWAY)
+        payload = encode_varint(stream_id)
+        frame_length = encode_varint(payload.bytesize)
+
+        frame_type + frame_length + payload
+      end
+
+      # Cache for decode_varint_str: (object_id << 16 | offset) → [value, consumed]
+      VARINT_STR_CACHE = {}
+      VARINT_STR_CACHE_MAX = 256
+
+      # Decode variable-length integer from a String using getbyte (no array needed)
+      # Returns [value, bytes_consumed]
+      def decode_varint_str(str, offset = 0)
+        cache_key = (str.object_id << 16) | offset
+        cached = VARINT_STR_CACHE[cache_key]
+        return cached if cached
+
+        first = str.getbyte(offset)
+        return [0, 0] unless first
+
+        if first < 0x40
+          result = VARINT_DECODE_SMALL[first]
+        else
+          prefix = (first & 0xC0) >> 6
+          length = 1 << prefix
+
+          return [0, 0] if offset + length > str.bytesize
+
+          result = case prefix
+          when 0
+            [first & 0x3F, 1]
+          when 1
+            [(first & 0x3F) << 8 | str.getbyte(offset + 1), 2]
+          when 2
+            [(first & 0x3F) << 24 | str.getbyte(offset + 1) << 16 |
+            str.getbyte(offset + 2) << 8 | str.getbyte(offset + 3), 4]
+          else
+            [(first & 0x3F) << 56 | str.getbyte(offset + 1) << 48 |
+            str.getbyte(offset + 2) << 40 | str.getbyte(offset + 3) << 32 |
+            str.getbyte(offset + 4) << 24 | str.getbyte(offset + 5) << 16 |
+              str.getbyte(offset + 6) << 8 | str.getbyte(offset + 7), 8]
+          end
+        end
+
+        VARINT_STR_CACHE[cache_key] = result if VARINT_STR_CACHE.size < VARINT_STR_CACHE_MAX
+        result
+      end
+
+      # Precomputed decode results for single-byte varints (0-63)
+      VARINT_DECODE_SMALL = Array.new(64) { |v| [v, 1].freeze }.freeze
+
+      # Decode variable-length integer (RFC 9000)
+      # Returns [value, bytes_consumed]
+      def decode_varint(bytes, offset = 0)
+        first = bytes[offset]
+        return [0, 0] unless first
+
+        # Fast path for single-byte varints (most common: frame types, small lengths)
+        return VARINT_DECODE_SMALL[first] if first < 0x40
+
+        prefix = (first & 0xC0) >> 6
+        length = 1 << prefix
+        return [0, 0] if offset + length > bytes.size
+
+        case prefix
+        when 1
+          [(first & 0x3F) << 8 | bytes[offset + 1], 2]
+        when 2
+          [(first & 0x3F) << 24 | bytes[offset + 1] << 16 |
+          bytes[offset + 2] << 8 | bytes[offset + 3], 4]
+        else # 3
+          [(first & 0x3F) << 56 | bytes[offset + 1] << 48 |
+          bytes[offset + 2] << 40 | bytes[offset + 3] << 32 |
+          bytes[offset + 4] << 24 | bytes[offset + 5] << 16 |
+            bytes[offset + 6] << 8 | bytes[offset + 7], 8]
+        end
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/priority.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Quicsilver
+  module Protocol
+    # HTTP Extensible Priorities (RFC 9218).
+    #
+    # Parses the `priority` header from HTTP requests. Urgency ranges from
+    # 0 (highest) to 7 (lowest), defaulting to 3. Incremental indicates
+    # whether partial data is useful to the client (e.g. progressive images).
+    #
+    # Usage:
+    #   priority = Priority.parse("u=0, i")
+    #   priority.urgency     # => 0
+    #   priority.incremental # => true
+    #
+    #   priority = Priority.parse(nil)  # default
+    #   priority.urgency     # => 3
+    #   priority.incremental # => false
+    class Priority
+      DEFAULT_URGENCY = 3
+      MIN_URGENCY = 0
+      MAX_URGENCY = 7
+
+      attr_reader :urgency, :incremental
+
+      def initialize(urgency: DEFAULT_URGENCY, incremental: false)
+        @urgency = urgency.clamp(MIN_URGENCY, MAX_URGENCY)
+        @incremental = incremental
+      end
+
+      # Parse a priority header value (RFC 9218 §4, Structured Field Values).
+      # Returns a Priority with defaults for missing or invalid values.
+      # RFC 9218 §4: Encode as Structured Field Value.
+      # e.g. "u=0, i" or "u=5" or "u=3" (default)
+      def to_s
+        parts = []
+        parts << "u=#{@urgency}" if @urgency != DEFAULT_URGENCY
+        parts << "i" if @incremental
+        parts.empty? ? "u=#{DEFAULT_URGENCY}" : parts.join(", ")
+      end
+
+      def self.parse(value)
+        return new unless value && !value.empty?
+
+        urgency = DEFAULT_URGENCY
+        incremental = false
+
+        value.split(",").each do |param|
+          param = param.strip
+          if param.start_with?("u=")
+            urgency = param[2..].to_i
+          elsif param == "i"
+            incremental = true
+          elsif param == "i=?0"
+            incremental = false
+          elsif param == "i=?1"
+            incremental = true
+          end
+        end
+
+        new(urgency: urgency, incremental: incremental)
+      end
+    end
+  end
+end

data/lib/quicsilver/protocol/qpack/decoder.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "huffman"
+
+module Quicsilver
+  module Protocol
+    module Qpack
+      module Decoder
+        # Decode a QPACK string literal (RFC 9204 Section 4.1.2)
+        # Returns [string, bytes_consumed]
+        # String-based variant: accepts a binary String instead of byte array
+        def decode_qpack_string_from_str(data, offset)
+          first = data.getbyte(offset)
+          huffman = (first & 0x80) != 0
+
+          length = first & 0x7F
+          len_bytes = 1
+          if length == 0x7F
+            multiplier = 1
+            while offset + len_bytes < data.bytesize
+              next_byte = data.getbyte(offset + len_bytes)
+              len_bytes += 1
+              length += (next_byte & 0x7F) * multiplier
+              break if (next_byte & 0x80) == 0
+              multiplier *= 128
+            end
+          end
+
+          data_offset = offset + len_bytes
+          raw = data.byteslice(data_offset, length)
+
+          str = if huffman
+            Huffman.decode(raw) || raw
+          else
+            raw
+          end
+
+          [str, len_bytes + length]
+        end
+
+        # Byte-array variant. Results are not cached: the input is mutable, so
+        # keying on identity or object_id returns a stale decode after an
+        # in-place edit. Production decoding uses the String variant above.
+        def decode_qpack_string(bytes, offset)
+          return decode_qpack_string_from_str(bytes, offset) if bytes.is_a?(String)
+
+          first = bytes[offset]
+          huffman = (first & 0x80) != 0
+
+          # Inline 7-bit prefix integer decode to avoid method call
+          length = first & 0x7F
+          len_bytes = 1
+          if length == 0x7F
+            multiplier = 1
+            while offset + len_bytes < bytes.size
+              next_byte = bytes[offset + len_bytes]
+              len_bytes += 1
+              length += (next_byte & 0x7F) * multiplier
+              break if (next_byte & 0x80) == 0
+              multiplier *= 128
+            end
+          end
+
+          data_offset = offset + len_bytes
+          raw = bytes[data_offset, length].pack("C*")
+
+          str = if huffman
+            Huffman.decode(raw) || raw
+          else
+            raw
+          end
+
+          [str, len_bytes + length].freeze
+        end
+
+        # String-based prefix integer decoding
+        def decode_prefix_integer_str(data, offset, prefix_bits, pattern_mask)
+          max_prefix = (1 << prefix_bits) - 1
+          first_byte = data.getbyte(offset)
+          value = first_byte & max_prefix
+          bytes_consumed = 1
+
+          if value == max_prefix
+            multiplier = 1
+            loop do
+              return [value, bytes_consumed] if offset + bytes_consumed >= data.bytesize
+              next_byte = data.getbyte(offset + bytes_consumed)
+              bytes_consumed += 1
+              value += (next_byte & 0x7F) * multiplier
+              break if (next_byte & 0x80) == 0
+              multiplier *= 128
+            end
+          end
+
+          [value, bytes_consumed]
+        end
+
+        # RFC 7541 prefix integer decoding
+        # Returns [value, bytes_consumed]
+        def decode_prefix_integer(bytes, offset, prefix_bits, pattern_mask)
+          max_prefix = (1 << prefix_bits) - 1
+
+          first_byte = bytes[offset]
+          value = first_byte & max_prefix
+          bytes_consumed = 1
+
+          if value == max_prefix
+            multiplier = 1
+            loop do
+              return [value, bytes_consumed] if offset + bytes_consumed >= bytes.size
+
+              next_byte = bytes[offset + bytes_consumed]
+              bytes_consumed += 1
+
+              value += (next_byte & 0x7F) * multiplier
+              break if (next_byte & 0x80) == 0
+
+              multiplier *= 128
+            end
+          end
+
+          [value, bytes_consumed]
+        end
+      end
+    end
+  end
+end