solana-ruby-kit 8.2.0 → 8.4.0

data/lib/solana/ruby/kit/codecs/data_structures.rb

@@ -3,6 +3,38 @@
 
 module Solana::Ruby::Kit
   module Codecs
+    # A size strategy for +array_codec+ / +map_codec+ / +set_codec+ where the
+    # collection ends when the bytes at the next item position match a constant
+    # +sentinel+. Mirrors upstream's `ArrayLikeCodecSentinelSize`
+    # (`{ __kind: 'sentinel', sentinel, strategy? }`), itself a mirror of
+    # Codama's `sentinelCountNode`.
+    #
+    # Unlike a sentinel searched for in the byte stream, this one is compared at
+    # item boundaries only, so its bytes may occur *inside* an item without
+    # terminating the collection.
+    #
+    # +strategy+ controls whether the sentinel is written and required:
+    # - +:required+ (default) - written after the last item; decoding raises
+    #   +CODECS__SENTINEL_MISSING_AT_END_OF_BYTES+ if the bytes run out first.
+    # - +:optional+ - written, but decoding also stops at the end of the bytes,
+    #   to tolerate tightly sized or legacy data that lacks it.
+    # - +:omitted+ - never written; decoding stops at the end of the bytes, and
+    #   consumes the sentinel if one happens to be there.
+    #
+    # Two invariants must hold for a round trip, and - as upstream - the codec
+    # does NOT enforce them:
+    # 1. No item may *begin* with the sentinel's bytes; decoding cannot tell
+    #    such an item from the terminator and stops early.
+    # 2. Under +:optional+ / +:omitted+ the sentinel must be no wider than the
+    #    smallest possible item, or a short trailing item is silently dropped:
+    #    decoding stops once fewer bytes than the sentinel remain.
+    class SentinelSize < T::Struct
+      STRATEGIES = T.let(%i[required optional omitted].freeze, T::Array[Symbol])
+
+      const :sentinel, String
+      const :strategy, Symbol, default: :required
+    end
+
     # Data-structure codecs — mirrors @solana/codecs-data-structures.
     module DataStructures
       extend T::Sig
@@ -15,7 +47,8 @@ module Solana::Ruby::Kit
 
       # Encode/decode a fixed ordered list of named fields.
       # +fields+ is an Array of [name, codec] pairs (name can be String or Symbol).
-      # Encodes to a Hash on decode; expects a Hash for encode.
+      # Decodes to a Hash with Symbol keys. Encode takes a Hash keyed by either
+      # form, whichever way the field was named, so a decoded value re-encodes.
       sig { params(fields: T::Array[[T.any(String, Symbol), Codec]]).returns(Codec) }
       def struct_codec(fields)
         fixed = fields.all? { |_, c| c.fixed_size }
@@ -23,7 +56,11 @@ module Solana::Ruby::Kit
 
         enc = Encoder.new(fixed_size: total) do |value|
           h = T.cast(value, T::Hash[T.untyped, T.untyped])
-          fields.map { |name, codec| codec.encode(h[name] || h[name.to_s]) }.join.b
+          fields.map do |name, codec|
+            # key? rather than `h[name] || ...`, which would skip a false value.
+            key = [name, name.to_sym, name.to_s].find { |k| h.key?(k) }
+            codec.encode(key.nil? ? nil : h[key])
+          end.join.b
         end
         dec = Decoder.new(fixed_size: total) do |bytes, offset|
           result   = {}
@@ -61,55 +98,69 @@ module Solana::Ruby::Kit
         Codec.new(enc, dec)
       end
 
-      # Encode/decode a variable-length array with a u32LE length prefix.
-      # When +size+ is given the array has a fixed element count (no prefix).
-      sig { params(element_codec: Codec, size: T.nilable(Integer)).returns(Codec) }
-      def array_codec(element_codec, size: nil)
-        if size
-          fixed = element_codec.fixed_size ? size * T.must(element_codec.fixed_size) : nil
-          enc = Encoder.new(fixed_size: fixed) do |values|
-            T.cast(values, T::Array[T.untyped]).map { |v| element_codec.encode(v) }.join.b
-          end
-          dec = Decoder.new(fixed_size: fixed) do |bytes, offset|
-            result   = []
-            consumed = 0
-            size.times do
-              val, n = element_codec.decode(bytes, offset: offset + consumed)
-              result << val
-              consumed += n
-            end
-            [result, consumed]
-          end
-          Codec.new(enc, dec)
+      # Encode/decode an array, one +element_codec+ value per item. +size+
+      # picks how the item count is stored - mirrors upstream's
+      # `ArrayLikeCodecSize`:
+      #
+      # - +nil+ (default): a u32 little-endian count prefix.
+      # - a Codec, e.g. +u16_codec+ or +compact_u16_codec+: the count prefix is
+      #   written and read with that codec instead.
+      # - an Integer: a fixed item count with no prefix. Encoding an array of
+      #   any other length raises +CODECS__INVALID_NUMBER_OF_ITEMS+.
+      # - +:remainder+: no prefix; decoding reads items until the bytes run out,
+      #   so the array must be the last thing in the buffer.
+      # - a SentinelSize: no prefix; the array ends at a sentinel. See
+      #   SentinelSize for the strategies and the invariants you must uphold.
+      #
+      # When the count is a prefix and there are not enough bytes left to read
+      # it, the decoder yields an empty array rather than failing. That is
+      # deliberate: it lets a program append a collection to an existing
+      # account layout and still decode accounts written before the change.
+      # Formats that cannot accept that leniency - borsh, for one, requires the
+      # prefix to be present - can pass +require_size_prefix: true+ to make a
+      # truncated buffer raise instead. The option has no effect on the other
+      # strategies, none of which carries a prefix.
+      #
+      # +description+ names the codec in errors; it defaults to +'array'+.
+      sig do
+        params(
+          element_codec:       Codec,
+          size:                T.nilable(T.any(Integer, Symbol, Codec, SentinelSize)),
+          require_size_prefix: T::Boolean,
+          description:         T.nilable(String)
+        ).returns(Codec)
+      end
+      def array_codec(element_codec, size: nil, require_size_prefix: false, description: nil)
+        description ||= 'array'
+        case size
+        when nil          then ArrayLikeSize.prefixed(element_codec, Numbers.u32_codec, require_size_prefix)
+        when Codec        then ArrayLikeSize.prefixed(element_codec, size, require_size_prefix)
+        when Integer      then ArrayLikeSize.fixed_count(element_codec, size, description)
+        when SentinelSize then ArrayLikeSize.sentinel(element_codec, size, description)
+        when :remainder   then ArrayLikeSize.remainder(element_codec)
         else
-          prefix = Numbers.u32_codec
-          enc = Encoder.new do |values|
-            arr    = T.cast(values, T::Array[T.untyped])
-            header = prefix.encode(arr.length)
-            body   = arr.map { |v| element_codec.encode(v) }.join.b
-            header + body
-          end
-          dec = Decoder.new do |bytes, offset|
-            len, prefix_bytes = prefix.decode(bytes, offset: offset)
-            result   = []
-            consumed = prefix_bytes
-            len.times do
-              val, n = element_codec.decode(bytes, offset: offset + consumed)
-              result << val
-              consumed += n
-            end
-            [result, consumed]
-          end
-          Codec.new(enc, dec)
+          Kernel.raise ArgumentError,
+                       "Unknown array size #{size.inspect}; expected nil, a number Codec, an Integer, " \
+                       ':remainder or a SentinelSize'
         end
       end
 
       # Encode/decode a Hash.
       # Encoded as: [length prefix] + [key, value, key, value, ...]
-      sig { params(key_codec: Codec, value_codec: Codec, size: T.nilable(Integer)).returns(Codec) }
-      def map_codec(key_codec, value_codec, size: nil)
+      # See +array_codec+ for what +size+ and +require_size_prefix+ do; +size+
+      # counts entries, and a SentinelSize is compared at entry (key)
+      # boundaries.
+      sig do
+        params(
+          key_codec:           Codec,
+          value_codec:         Codec,
+          size:                T.nilable(T.any(Integer, Symbol, Codec, SentinelSize)),
+          require_size_prefix: T::Boolean
+        ).returns(Codec)
+      end
+      def map_codec(key_codec, value_codec, size: nil, require_size_prefix: false)
         pair_codec = tuple_codec([key_codec, value_codec])
-        array_codec(pair_codec, size: size).transform_decoder do |pairs|
+        array_codec(pair_codec, size: size, require_size_prefix: require_size_prefix).transform_decoder do |pairs|
           pairs.each_with_object({}) { |(k, v), h| h[k] = v }
         end.transform_encoder do |hash|
           T.cast(hash, T::Hash[T.untyped, T.untyped]).map { |k, v| [k, v] }
@@ -117,9 +168,16 @@ module Solana::Ruby::Kit
       end
 
       # Encode/decode a Set (stored as an array of unique elements).
-      sig { params(element_codec: Codec, size: T.nilable(Integer)).returns(Codec) }
-      def set_codec(element_codec, size: nil)
-        array_codec(element_codec, size: size)
+      # See +array_codec+ for what +size+ and +require_size_prefix+ do.
+      sig do
+        params(
+          element_codec:       Codec,
+          size:                T.nilable(T.any(Integer, Symbol, Codec, SentinelSize)),
+          require_size_prefix: T::Boolean
+        ).returns(Codec)
+      end
+      def set_codec(element_codec, size: nil, require_size_prefix: false)
+        array_codec(element_codec, size: size, require_size_prefix: require_size_prefix)
           .transform_encoder { |s| T.cast(s, T::Set[T.untyped]).to_a }
           .transform_decoder { |arr| Set.new(arr) }
       end
@@ -177,5 +235,146 @@ module Solana::Ruby::Kit
         Codec.new(enc, dec)
       end
     end
+
+    # The per-strategy builders behind +array_codec+ (and so +map_codec+ and
+    # +set_codec+). Call those instead. Kept out of DataStructures on purpose:
+    # everything there is re-exported as a public +Codecs.*+ helper, and these
+    # are an implementation detail.
+    module ArrayLikeSize
+      extend T::Sig
+      extend self
+
+      # A count prefix written and read with +prefix+.
+      sig { params(element_codec: Codec, prefix: Codec, require_size_prefix: T::Boolean).returns(Codec) }
+      def prefixed(element_codec, prefix, require_size_prefix)
+        enc = Encoder.new do |values|
+          arr = T.cast(values, T::Array[T.untyped])
+          prefix.encode(arr.length) + arr.map { |v| element_codec.encode(v) }.join.b
+        end
+        dec = Decoder.new do |bytes, offset|
+          # A fixed-size prefix needs all its bytes; a variable-size one (e.g.
+          # compact_u16) needs at least one, and raises for itself if the rest
+          # are missing.
+          prefix_size = prefix.fixed_size || 1
+          remaining   = [bytes.bytesize - offset, 0].max
+          if remaining < prefix_size
+            # The prefix is missing or truncated. By default that decodes to an
+            # empty collection having consumed nothing; under
+            # +require_size_prefix+ it is an error.
+            Kernel.raise SolanaError.new(
+              SolanaError::CODECS__INVALID_BYTE_LENGTH,
+              { expected: prefix_size, actual: remaining }
+            ) if require_size_prefix
+
+            next [[], 0]
+          end
+          count, consumed = prefix.decode(bytes, offset: offset)
+          result = Array.new(Kernel.Integer(count)) do
+            val, n = element_codec.decode(bytes, offset: offset + consumed)
+            consumed += n
+            val
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Exactly +count+ items and no prefix. Fixed-size when the items are - and
+      # always for a count of zero, whatever the item.
+      sig { params(element_codec: Codec, count: Integer, description: String).returns(Codec) }
+      def fixed_count(element_codec, count, description)
+        item_size = element_codec.fixed_size
+        fixed     = count.zero? ? 0 : (item_size && count * item_size)
+        enc = Encoder.new(fixed_size: fixed) do |values|
+          arr = T.cast(values, T::Array[T.untyped])
+          unless arr.length == count
+            Kernel.raise SolanaError.new(
+              SolanaError::CODECS__INVALID_NUMBER_OF_ITEMS,
+              { codec_description: description, expected: count, actual: arr.length }
+            )
+          end
+          arr.map { |v| element_codec.encode(v) }.join.b
+        end
+        dec = Decoder.new(fixed_size: fixed) do |bytes, offset|
+          consumed = 0
+          result = Array.new(count) do
+            val, n = element_codec.decode(bytes, offset: offset + consumed)
+            consumed += n
+            val
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # No prefix; decoding reads items until the bytes run out.
+      sig { params(element_codec: Codec).returns(Codec) }
+      def remainder(element_codec)
+        enc = Encoder.new do |values|
+          T.cast(values, T::Array[T.untyped]).map { |v| element_codec.encode(v) }.join.b
+        end
+        dec = Decoder.new do |bytes, offset|
+          result   = []
+          consumed = 0
+          while offset + consumed < bytes.bytesize
+            val, n = element_codec.decode(bytes, offset: offset + consumed)
+            # An item that consumes nothing would never reach the end.
+            Kernel.raise ArgumentError, 'a :remainder array item decoded zero bytes' if n.zero?
+
+            result << val
+            consumed += n
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+
+      # Ends at a sentinel instead of carrying a count. Always variable-size:
+      # the item count is only known by reading up to the sentinel.
+      sig { params(element_codec: Codec, size: SentinelSize, description: String).returns(Codec) }
+      def sentinel(element_codec, size, description)
+        sentinel = size.sentinel.b
+        strategy = size.strategy
+        # Raised at construction, as upstream does for both the encoder and the
+        # decoder: an empty sentinel matches everywhere and delimits nothing.
+        Kernel.raise SolanaError.new(SolanaError::CODECS__SENTINEL_MUST_NOT_BE_EMPTY) if sentinel.empty?
+        unless SentinelSize::STRATEGIES.include?(strategy)
+          Kernel.raise ArgumentError,
+                       "Unknown sentinel strategy #{strategy.inspect}; expected one of #{SentinelSize::STRATEGIES.inspect}"
+        end
+
+        enc = Encoder.new do |values|
+          body = T.cast(values, T::Array[T.untyped]).map { |v| element_codec.encode(v) }.join.b
+          strategy == :omitted ? body : body + sentinel
+        end
+        dec = Decoder.new do |bytes, offset|
+          result   = []
+          consumed = 0
+          Kernel.loop do
+            position = offset + consumed
+            if position + sentinel.bytesize > bytes.bytesize
+              # Not enough bytes remain to hold the sentinel.
+              if strategy == :required
+                Kernel.raise SolanaError.new(
+                  SolanaError::CODECS__SENTINEL_MISSING_AT_END_OF_BYTES,
+                  { codec_description: description, hex_sentinel: sentinel.unpack1('H*'), sentinel: sentinel }
+                )
+              end
+              break
+            end
+            if Bytes.contains_bytes?(bytes, sentinel, offset: position)
+              # The sentinel is present; consume it and stop.
+              consumed += sentinel.bytesize
+              break
+            end
+            val, n = element_codec.decode(bytes, offset: position)
+            result << val
+            consumed += n
+          end
+          [result, consumed]
+        end
+        Codec.new(enc, dec)
+      end
+    end
   end
 end

data/lib/solana/ruby/kit/codecs/numbers.rb

@@ -19,6 +19,43 @@ module Solana::Ruby::Kit
       # defeated the "directly available as Codecs.x" intent in codecs.rb.
       extend self
 
+      # ── Multi-byte integers ──────────────────────────────────────────────────
+
+      # Shared implementation behind u128 / i128 / u256 / i256.
+      #
+      # Upstream splits these values into 64-bit words because a JS `DataView`
+      # has no accessor wider than 64 bits. Ruby's Integer is arbitrary
+      # precision, so there is nothing to split: the value is shifted out one
+      # byte at a time and reassembled the same way, which keeps a single
+      # implementation correct for any +byte_count+.
+      #
+      # +signed+ selects two's-complement interpretation over +byte_count * 8+
+      # bits, so negative values round-trip.
+      sig { params(byte_count: Integer, signed: T::Boolean, endian: Symbol).returns(Codec) }
+      def big_int_codec(byte_count, signed:, endian: :little)
+        bits = byte_count * 8
+        enc = Encoder.new(fixed_size: byte_count) do |v|
+          n = Kernel.Integer(v)
+          n += (1 << bits) if signed && n.negative?
+          out = Array.new(byte_count) do
+            byte = n & 0xFF
+            n >>= 8
+            byte
+          end
+          # `out` is least-significant-byte first.
+          (endian == :little ? out : out.reverse).pack('C*')
+        end
+        dec = Decoder.new(fixed_size: byte_count) do |bytes, offset|
+          slice = bytes.b.byteslice(offset, byte_count) || ("\x00" * byte_count).b
+          arr   = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
+          arr   = arr.reverse if endian == :little
+          n     = arr.reduce(0) { |acc, byte| (acc << 8) | byte }
+          n -= (1 << bits) if signed && n >= (1 << (bits - 1))
+          [n, byte_count]
+        end
+        Codec.new(enc, dec)
+      end
+
       # ── Unsigned integers ────────────────────────────────────────────────────
 
       sig { returns(Codec) }
@@ -62,29 +99,12 @@ module Solana::Ruby::Kit
 
       sig { params(endian: Symbol).returns(Codec) }
       def u128_codec(endian: :little)
-        enc = Encoder.new(fixed_size: 16) do |v|
-          n = Kernel.Integer(v)
-          if endian == :little
-            bytes = []
-            16.times { bytes << (n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          else
-            bytes = []
-            16.times { bytes.unshift(n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          end
-        end
-        dec = Decoder.new(fixed_size: 16) do |bytes, offset|
-          slice = bytes.b.byteslice(offset, 16) || ("\x00" * 16).b
-          arr   = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
-          n = if endian == :little
-                arr.reverse.reduce(0) { |acc, b| (acc << 8) | b }
-              else
-                arr.reduce(0) { |acc, b| (acc << 8) | b }
-              end
-          [n, 16]
-        end
-        Codec.new(enc, dec)
+        big_int_codec(16, signed: false, endian: endian)
+      end
+
+      sig { params(endian: Symbol).returns(Codec) }
+      def u256_codec(endian: :little)
+        big_int_codec(32, signed: false, endian: endian)
       end
 
       # ── Signed integers ──────────────────────────────────────────────────────
@@ -130,33 +150,12 @@ module Solana::Ruby::Kit
 
       sig { params(endian: Symbol).returns(Codec) }
       def i128_codec(endian: :little)
-        enc = Encoder.new(fixed_size: 16) do |v|
-          n    = Kernel.Integer(v)
-          # Two's complement for negative numbers
-          n += (1 << 128) if n.negative?
-          if endian == :little
-            bytes = []
-            16.times { bytes << (n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          else
-            bytes = []
-            16.times { bytes.unshift(n & 0xFF); n >>= 8 }
-            bytes.pack('C*')
-          end
-        end
-        dec = Decoder.new(fixed_size: 16) do |bytes, offset|
-          slice = bytes.b.byteslice(offset, 16) || ("\x00" * 16).b
-          arr   = T.cast(T.unsafe(slice).unpack('C*'), T::Array[Integer])
-          n = if endian == :little
-                arr.reverse.reduce(0) { |acc, b| (acc << 8) | b }
-              else
-                arr.reduce(0) { |acc, b| (acc << 8) | b }
-              end
-          # Convert from unsigned to signed 128-bit
-          n -= (1 << 128) if n >= (1 << 127)
-          [n, 16]
-        end
-        Codec.new(enc, dec)
+        big_int_codec(16, signed: true, endian: endian)
+      end
+
+      sig { params(endian: Symbol).returns(Codec) }
+      def i256_codec(endian: :little)
+        big_int_codec(32, signed: true, endian: endian)
       end
 
       # ── Floating point ───────────────────────────────────────────────────────
@@ -201,21 +200,57 @@ module Solana::Ruby::Kit
           bytes.pack('C*')
         end
         dec = Decoder.new do |bytes, offset|
-          b  = bytes.b
-          n  = 0
-          shift = 0
-          consumed = 0
-          Kernel.loop do
-            byte = b.byteslice(offset + consumed, 1)&.unpack1('C') || 0
-            consumed += 1
-            n |= (byte & 0x7F) << shift
-            shift += 7
-            break if (byte & 0x80).zero?
+          b = bytes.b
+          n = 0
+          decoded = (1..3).each do |byte_count|
+            # The chain must terminate within the bytes that remain; a buffer
+            # that ends mid-chain is truncated, not an implicit zero byte.
+            remaining = b.bytesize - offset
+            if remaining < byte_count
+              Kernel.raise SolanaError.new(
+                SolanaError::CODECS__INVALID_BYTE_LENGTH,
+                { codec_description: 'shortU16', expected: byte_count, actual: [remaining, 0].max }
+              )
+            end
+
+            byte = T.must(b.getbyte(offset + byte_count - 1))
+            n |= (byte & 0x7F) << ((byte_count - 1) * 7)
+            next unless (byte & 0x80).zero?
+
+            Numbers.assert_short_u16_in_range(n)
+            break [n, byte_count]
           end
-          [n, consumed]
+          # `each` only returns its range when no byte terminated the chain.
+          next decoded if decoded.is_a?(Array)
+
+          Numbers.raise_short_u16_too_long
         end
         Codec.new(enc, dec)
       end
+
+      # Three terminated shortU16 bytes can hold up to 2^21 - 1, but only the
+      # u16 domain is valid. Shared with the wire-format readers in
+      # WalletStandard and TransactionIntrospection, which decode shortU16
+      # inline so they can raise their own truncation errors.
+      sig { params(value: Integer).void }
+      def assert_short_u16_in_range(value)
+        return if value <= 0xFFFF
+
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__NUMBER_OUT_OF_RANGE,
+          { codec_description: 'shortU16', min: 0, max: 0xFFFF, value: value }
+        )
+      end
+
+      # Raised when all three shortU16 bytes carry a continuation bit: the
+      # encoding would need a fourth byte, which the format does not allow.
+      sig { returns(T.noreturn) }
+      def raise_short_u16_too_long
+        Kernel.raise SolanaError.new(
+          SolanaError::CODECS__INVALID_BYTE_LENGTH,
+          { codec_description: 'shortU16', expected: 3, actual: 4 }
+        )
+      end
     end
   end
 end