quicsilver 0.1.0 → 0.3.0

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

@@ -0,0 +1,165 @@
+# 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
+
+        # Cache for decode_qpack_string
+        DQS_CACHE = {}        # array-content → [str, consumed]
+        DQS_OID_CACHE = {}    # object_id|offset → [str, consumed]
+        DQS_CACHE_MAX = 128
+
+        # 2-slot last-result cache for decode_qpack_string
+        DQS_LAST_A = [nil, nil, nil] # [bytes, offset, result]
+        DQS_LAST_B = [nil, nil, nil]
+
+        def decode_qpack_string(bytes, offset)
+          # 2-slot equal? fast path (covers alternating-object patterns)
+          return DQS_LAST_A[2] if bytes.equal?(DQS_LAST_A[0]) && offset == DQS_LAST_A[1]
+          return DQS_LAST_B[2] if bytes.equal?(DQS_LAST_B[0]) && offset == DQS_LAST_B[1]
+
+          # Object-id cache
+          oid_key = (bytes.object_id << 16) | offset
+          cached = DQS_OID_CACHE[oid_key]
+          if cached
+            # Rotate 2-slot cache
+            DQS_LAST_B[0], DQS_LAST_B[1], DQS_LAST_B[2] = DQS_LAST_A[0], DQS_LAST_A[1], DQS_LAST_A[2]
+            DQS_LAST_A[0], DQS_LAST_A[1], DQS_LAST_A[2] = bytes, offset, cached
+            return cached
+          end
+
+          # Dispatch to string variant if given a String
+          return decode_qpack_string_from_str(bytes, offset) if bytes.is_a?(String)
+
+          # Content-based cache for offset=0
+          if offset == 0
+            cached = DQS_CACHE[bytes]
+            if cached
+              DQS_OID_CACHE[oid_key] = cached
+              return cached
+            end
+          end
+
+          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
+
+          result = [str, len_bytes + length].freeze
+
+          # Cache for offset=0 (common case: standalone decode)
+          if offset == 0 && DQS_CACHE.size < DQS_CACHE_MAX
+            DQS_CACHE[bytes.frozen? ? bytes : bytes.dup.freeze] = result
+          end
+          DQS_OID_CACHE[oid_key] = result if DQS_OID_CACHE.size < DQS_CACHE_MAX
+
+          result
+        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

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+require_relative "huffman"
+
+module Quicsilver
+  module Protocol
+    module Qpack
+      class Encoder
+        STATIC_TABLE = Protocol::STATIC_TABLE
+
+        # Pre-built hash for O(1) static table lookups
+        STATIC_LOOKUP_FULL = {} # "name\0value" => index
+        STATIC_LOOKUP_NAME = {} # name => first_index
+
+        STATIC_TABLE.each_with_index do |(tbl_name, tbl_value), idx|
+          STATIC_LOOKUP_FULL["#{tbl_name}\0#{tbl_value}".freeze] = idx
+          STATIC_LOOKUP_NAME[tbl_name] ||= idx
+        end
+        STATIC_LOOKUP_FULL.freeze
+        STATIC_LOOKUP_NAME.freeze
+
+        PREFIX = "\x00\x00".b.freeze
+
+        FIELD_CACHE_MAX = 512
+
+        def initialize(huffman: true)
+          @huffman = huffman
+          @field_cache = {}
+          @block_cache = {}
+          @oid_cache = {}
+        end
+
+        def encode(headers)
+          # Fastest path: exact same object as last call
+          return @last_result if headers.equal?(@last_headers)
+
+          # Fast path: check object_id cache (same array object reused)
+          oid = headers.object_id
+          cached = @oid_cache[oid]
+          if cached
+            @last_headers = headers
+            @last_result = cached
+            return cached
+          end
+
+          if headers.is_a?(Array) && headers.size <= 16
+            # Content-based caching for small header sets
+            block_key = headers.map { |n, v| "#{n}\0#{v}" }.join("\x01")
+            cached_block = @block_cache[block_key]
+            if cached_block
+              @oid_cache[oid] = cached_block if @oid_cache.size < BLOCK_CACHE_MAX
+              return cached_block
+            end
+
+            result = encode_fields(headers)
+            result_frozen = result.freeze
+            if @block_cache.size < BLOCK_CACHE_MAX
+              @block_cache[block_key.freeze] = result_frozen
+            end
+            @oid_cache[oid] = result_frozen if @oid_cache.size < BLOCK_CACHE_MAX
+            return result_frozen
+          end
+
+          encode_fields(headers)
+        end
+
+        BLOCK_CACHE_MAX = 128
+
+        private def encode_fields(headers)
+          out = encode_prefix
+          headers.each do |name, value|
+            name = name.to_s
+            value = value.to_s
+            # Downcase only if needed (most HTTP/3 headers are already lowercase)
+            name = name.downcase if name =~ /[A-Z]/
+
+            cache_key = "#{name}\0#{value}"
+
+            # Check field cache
+            cached = @field_cache[cache_key]
+            if cached
+              out << cached
+              next
+            end
+
+            field_start = out.bytesize
+
+            full_idx = STATIC_LOOKUP_FULL[cache_key]
+
+            if full_idx
+              # Indexed Field Line
+              out << encode_prefixed_int(full_idx, 6, 0xC0)
+            else
+              name_idx = STATIC_LOOKUP_NAME[name]
+              if name_idx
+                # Literal with Name Reference
+                out << encode_prefixed_int(name_idx, 4, 0x50)
+                encode_str_into(out, value)
+              else
+                # Literal with Literal Name
+                encode_literal_into(out, name, value)
+              end
+            end
+
+            # Cache the encoded field bytes
+            if @field_cache.size < FIELD_CACHE_MAX
+              @field_cache[cache_key.freeze] = out.byteslice(field_start..).freeze
+            end
+          end
+          out
+        end
+
+        def lookup(name, value)
+          name = name.to_s.downcase
+          value = value.to_s
+          full_idx = STATIC_LOOKUP_FULL["#{name}\0#{value}"]
+          return [full_idx, true] if full_idx
+          name_idx = STATIC_LOOKUP_NAME[name]
+          name_idx ? [name_idx, false] : nil
+        end
+
+        def encode_prefix
+          PREFIX.dup
+        end
+
+        # Public API for encoding a single string value (used by tests/external code)
+        def encode_str(value)
+          out = "".b
+          encode_str_into(out, value.to_s)
+          out
+        end
+
+        private
+
+        # Pattern 1: Indexed Field Line (1xxxxxxx) — kept for test compatibility
+        def encode_indexed(index)
+          encode_prefixed_int(index, 6, 0xC0)
+        end
+
+        def encode_literal_into(out, name, value)
+          name_b = name.b
+          if @huffman
+            huffman_name = Huffman.encode(name_b)
+            if huffman_name.bytesize < name_b.bytesize
+              out << encode_prefixed_int(huffman_name.bytesize, 3, 0x28)
+              out << huffman_name
+              encode_str_into(out, value)
+              return
+            end
+          end
+          out << encode_prefixed_int(name_b.bytesize, 3, 0x20)
+          out << name_b
+          encode_str_into(out, value)
+        end
+
+        def encode_str_into(out, value)
+          value_b = value.b
+          if @huffman
+            huffman = Huffman.encode(value_b)
+            if huffman.bytesize < value_b.bytesize
+              out << encode_prefixed_int(huffman.bytesize, 7, 0x80)
+              out << huffman
+              return
+            end
+          end
+          out << encode_prefixed_int(value_b.bytesize, 7, 0x00)
+          out << value_b
+        end
+
+        # RFC 7541 prefix integer encoding
+        def encode_prefixed_int(value, prefix_bits, pattern)
+          max_prefix = (1 << prefix_bits) - 1
+
+          if value < max_prefix
+            (pattern | value).chr(Encoding::BINARY)
+          else
+            buf = (pattern | max_prefix).chr(Encoding::BINARY)
+            value -= max_prefix
+            while value >= 128
+              buf << ((value & 0x7F) | 0x80).chr(Encoding::BINARY)
+              value >>= 7
+            end
+            buf << value.chr(Encoding::BINARY)
+            buf
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "decoder"
+require_relative "huffman"
+
+module Quicsilver
+  module Protocol
+    module Qpack
+      # Decodes a QPACK header block into [name, value] pairs.
+      #
+      # Default implementation uses the static table only (no dynamic table).
+      # To add dynamic table support, implement a class with the same #decode interface:
+      #
+      #   class MyDynamicDecoder
+      #     def decode(payload)
+      #       # parse QPACK field lines from payload
+      #       # yield [name, value] for each decoded header
+      #     end
+      #   end
+      #
+      # Then inject it:
+      #   RequestParser.new(data, decoder: MyDynamicDecoder.new)
+      #   ResponseParser.new(data, decoder: MyDynamicDecoder.new)
+      #
+      class HeaderBlockDecoder
+        include Decoder
+
+        DECODE_CACHE_MAX = 256
+
+        # Shared default instance for parsers that don't need custom decoders
+        def self.default
+          @default ||= new
+        end
+
+        def initialize
+          @decode_cache = {}
+        end
+
+        # Decode a QPACK header block payload (RFC 9204 §4.5).
+        # Yields [name, value] for each decoded field line.
+        def decode(payload)
+          return if payload.nil? || payload.bytesize < 2
+
+          # Check cache for previously decoded payloads
+          if payload.bytesize <= 256
+            cached = @decode_cache[payload]
+            if cached
+              cached.each { |name, value| yield name, value }
+              return
+            end
+          end
+
+          headers = []
+          offset = 2 # skip required insert count + delta base prefix
+
+          while offset < payload.bytesize
+            byte = payload.getbyte(offset)
+
+            # Indexed Field Line (1Txxxxxx) — name + value from static table
+            if (byte & 0x80) == 0x80
+              index, bytes_consumed = decode_prefix_integer_str(payload, offset, 6, 0xC0)
+              offset += bytes_consumed
+
+              if index < Protocol::STATIC_TABLE.size
+                name, value = Protocol::STATIC_TABLE[index]
+                headers << [name, value]
+                yield name, value
+              else
+                raise Protocol::FrameError.new(
+                  "Invalid QPACK static table index #{index}",
+                  error_code: Protocol::QPACK_DECOMPRESSION_FAILED
+                )
+              end
+
+            # Literal with Name Reference (01NTxxxx) — name from static table, literal value
+            elsif (byte & 0xC0) == 0x40
+              index, bytes_consumed = decode_prefix_integer_str(payload, offset, 4, 0xF0)
+              offset += bytes_consumed
+
+              if index >= Protocol::STATIC_TABLE.size
+                raise Protocol::FrameError.new(
+                  "Invalid QPACK static table index #{index}",
+                  error_code: Protocol::QPACK_DECOMPRESSION_FAILED
+                )
+              end
+
+              name = Protocol::STATIC_TABLE[index][0]
+              value, consumed = decode_qpack_string_from_str(payload, offset)
+              offset += consumed
+              headers << [name, value]
+              yield name, value
+
+            # Literal with Literal Name (001NHxxx) — both name and value are literals
+            elsif (byte & 0xE0) == 0x20
+              huffman_name = (byte & 0x08) != 0
+              name_len, name_len_bytes = decode_prefix_integer_str(payload, offset, 3, 0x28)
+              offset += name_len_bytes
+              raw_name = payload.byteslice(offset, name_len)
+              name = if huffman_name
+                Huffman.decode(raw_name) || raw_name
+              else
+                raw_name
+              end
+              offset += name_len
+
+              value, consumed = decode_qpack_string_from_str(payload, offset)
+              offset += consumed
+
+              headers << [name, value]
+              yield name, value
+            else
+              break
+            end
+          end
+
+          # Cache the result
+          if payload.bytesize <= 256 && @decode_cache.size < DECODE_CACHE_MAX
+            key = payload.frozen? ? payload : payload.dup.freeze
+            @decode_cache[key] = headers.freeze
+          end
+        end
+      end
+    end
+  end
+end