Add CBOR decoder with IEEE 754 float support

src/CBOR/Decoder.php

···
+<?php
+
+declare(strict_types=1);
+
+namespace SocialDept\Signal\CBOR;
+
+use RuntimeException;
+use SocialDept\Signal\Binary\Reader;
+use SocialDept\Signal\Core\CID;
+
+/**
+ * CBOR (Concise Binary Object Representation) decoder.
+ *
+ * Implements RFC 8949 CBOR with DAG-CBOR extensions for IPLD.
+ * Supports tag 42 for CID links.
+ */
+class Decoder
+{
+    private const MAJOR_TYPE_UNSIGNED = 0;
+
+    private const MAJOR_TYPE_NEGATIVE = 1;
+
+    private const MAJOR_TYPE_BYTES = 2;
+
+    private const MAJOR_TYPE_TEXT = 3;
+
+    private const MAJOR_TYPE_ARRAY = 4;
+
+    private const MAJOR_TYPE_MAP = 5;
+
+    private const MAJOR_TYPE_TAG = 6;
+
+    private const MAJOR_TYPE_SPECIAL = 7;
+
+    private const TAG_CID = 42;
+
+    private Reader $reader;
+
+    public function __construct(string $data)
+    {
+        $this->reader = new Reader($data);
+    }
+
+    /**
+     * Decode the next CBOR item.
+     *
+     * @return mixed Decoded value
+     *
+     * @throws RuntimeException If data is malformed
+     */
+    public function decode(): mixed
+    {
+        if (! $this->reader->hasMore()) {
+            throw new RuntimeException('Unexpected end of CBOR data');
+        }
+
+        $initialByte = $this->reader->readByte();
+        $majorType = $initialByte >> 5;
+        $additionalInfo = $initialByte & 0x1F;
+
+        return match ($majorType) {
+            self::MAJOR_TYPE_UNSIGNED => $this->decodeUnsigned($additionalInfo),
+            self::MAJOR_TYPE_NEGATIVE => $this->decodeNegative($additionalInfo),
+            self::MAJOR_TYPE_BYTES => $this->decodeBytes($additionalInfo),
+            self::MAJOR_TYPE_TEXT => $this->decodeText($additionalInfo),
+            self::MAJOR_TYPE_ARRAY => $this->decodeArray($additionalInfo),
+            self::MAJOR_TYPE_MAP => $this->decodeMap($additionalInfo),
+            self::MAJOR_TYPE_TAG => $this->decodeTag($additionalInfo),
+            self::MAJOR_TYPE_SPECIAL => $this->decodeSpecial($additionalInfo),
+            default => throw new RuntimeException("Unknown major type: {$majorType}"),
+        };
+    }
+
+    /**
+     * Check if there's more data to decode.
+     */
+    public function hasMore(): bool
+    {
+        return $this->reader->hasMore();
+    }
+
+    /**
+     * Get current position.
+     */
+    public function getPosition(): int
+    {
+        return $this->reader->getPosition();
+    }
+
+    /**
+     * Decode unsigned integer.
+     */
+    private function decodeUnsigned(int $additionalInfo): int
+    {
+        return $this->decodeLength($additionalInfo);
+    }
+
+    /**
+     * Decode negative integer.
+     */
+    private function decodeNegative(int $additionalInfo): int
+    {
+        $value = $this->decodeLength($additionalInfo);
+
+        return -1 - $value;
+    }
+
+    /**
+     * Decode byte string.
+     */
+    private function decodeBytes(int $additionalInfo): string
+    {
+        $length = $this->decodeLength($additionalInfo);
+
+        return $this->reader->readBytes($length);
+    }
+
+    /**
+     * Decode text string.
+     */
+    private function decodeText(int $additionalInfo): string
+    {
+        $length = $this->decodeLength($additionalInfo);
+
+        return $this->reader->readBytes($length);
+    }
+
+    /**
+     * Decode array.
+     */
+    private function decodeArray(int $additionalInfo): array
+    {
+        $length = $this->decodeLength($additionalInfo);
+        $array = [];
+
+        for ($i = 0; $i < $length; $i++) {
+            $array[] = $this->decode();
+        }
+
+        return $array;
+    }
+
+    /**
+     * Decode map (object).
+     */
+    private function decodeMap(int $additionalInfo): array
+    {
+        $length = $this->decodeLength($additionalInfo);
+        $map = [];
+
+        for ($i = 0; $i < $length; $i++) {
+            $key = $this->decode();
+            $value = $this->decode();
+
+            if (! is_string($key) && ! is_int($key)) {
+                throw new RuntimeException('Map keys must be strings or integers');
+            }
+
+            $map[$key] = $value;
+        }
+
+        return $map;
+    }
+
+    /**
+     * Decode tagged value.
+     */
+    private function decodeTag(int $additionalInfo): mixed
+    {
+        $tag = $this->decodeLength($additionalInfo);
+
+        if ($tag === self::TAG_CID) {
+            // Tag 42 = CID link (DAG-CBOR)
+            // Next item should be byte string containing CID
+            $cidBytes = $this->decode();
+
+            if (! is_string($cidBytes)) {
+                throw new RuntimeException('CID tag must be followed by byte string');
+            }
+
+            // First byte should be 0x00 for CID
+            if (ord($cidBytes[0]) !== 0x00) {
+                throw new RuntimeException('Invalid CID byte string prefix');
+            }
+
+            return CID::fromBinary(substr($cidBytes, 1));
+        }
+
+        // For other tags, just return the tagged value
+        return $this->decode();
+    }
+
+    /**
+     * Decode special values (bool, null, floats).
+     */
+    private function decodeSpecial(int $additionalInfo): mixed
+    {
+        return match ($additionalInfo) {
+            20 => false,
+            21 => true,
+            22 => null,
+            23 => throw new RuntimeException('Undefined special value'),
+            25 => $this->decodeFloat16(), // IEEE 754 Half-Precision (16-bit)
+            26 => $this->decodeFloat32(), // IEEE 754 Single-Precision (32-bit)
+            27 => $this->decodeFloat64(), // IEEE 754 Double-Precision (64-bit)
+            default => throw new RuntimeException("Unsupported special value: {$additionalInfo}"),
+        };
+    }
+
+    /**
+     * Decode IEEE 754 half-precision float (16-bit).
+     */
+    private function decodeFloat16(): float
+    {
+        $bytes = $this->reader->readBytes(2);
+        $bits = unpack('n', $bytes)[1];
+
+        // Extract sign, exponent, and mantissa
+        $sign = ($bits >> 15) & 1;
+        $exponent = ($bits >> 10) & 0x1F;
+        $mantissa = $bits & 0x3FF;
+
+        // Handle special cases
+        if ($exponent === 0) {
+            // Subnormal or zero
+            $value = $mantissa / 1024.0 * (2 ** -14);
+        } elseif ($exponent === 31) {
+            // Infinity or NaN
+            return $mantissa === 0 ? ($sign ? -INF : INF) : NAN;
+        } else {
+            // Normalized value
+            $value = (1 + $mantissa / 1024.0) * (2 ** ($exponent - 15));
+        }
+
+        return $sign ? -$value : $value;
+    }
+
+    /**
+     * Decode IEEE 754 single-precision float (32-bit).
+     */
+    private function decodeFloat32(): float
+    {
+        $bytes = $this->reader->readBytes(4);
+
+        return unpack('G', $bytes)[1]; // Big-endian float
+    }
+
+    /**
+     * Decode IEEE 754 double-precision float (64-bit).
+     */
+    private function decodeFloat64(): float
+    {
+        $bytes = $this->reader->readBytes(8);
+
+        return unpack('E', $bytes)[1]; // Big-endian double
+    }
+
+    /**
+     * Decode length/value from additional info.
+     */
+    private function decodeLength(int $additionalInfo): int
+    {
+        if ($additionalInfo < 24) {
+            return $additionalInfo;
+        }
+
+        return match ($additionalInfo) {
+            24 => $this->reader->readByte(),
+            25 => unpack('n', $this->reader->readBytes(2))[1],
+            26 => unpack('N', $this->reader->readBytes(4))[1],
+            27 => $this->readUint64(),
+            default => throw new RuntimeException("Invalid additional info: {$additionalInfo}"),
+        };
+    }
+
+    /**
+     * Read 64-bit unsigned integer.
+     */
+    private function readUint64(): int
+    {
+        $bytes = $this->reader->readBytes(8);
+        $unpacked = unpack('J', $bytes)[1];
+
+        return $unpacked;
+    }
+}

src/Core/CBOR.php

···
+<?php
+
+declare(strict_types=1);
+
+namespace SocialDept\Signal\Core;
+
+use SocialDept\Signal\CBOR\Decoder;
+
+/**
+ * CBOR facade for simple decoding operations.
+ *
+ * Provides static methods matching the interface needed by FirehoseConsumer.
+ */
+class CBOR
+{
+    /**
+     * Decode first CBOR item and return remainder.
+     *
+     * @param string $data Binary CBOR data
+     * @return array{0: mixed, 1: string} [decoded value, remaining data]
+     */
+    public static function decodeFirst(string $data): array
+    {
+        $decoder = new Decoder($data);
+        $value = $decoder->decode();
+
+        // Calculate remaining data based on decoder position
+        $position = $decoder->getPosition();
+        $remainder = substr($data, $position);
+
+        return [$value, $remainder];
+    }
+
+    /**
+     * Decode complete CBOR data.
+     *
+     * @param string $data Binary CBOR data
+     * @return mixed Decoded value
+     */
+    public static function decode(string $data): mixed
+    {
+        $decoder = new Decoder($data);
+
+        return $decoder->decode();
+    }
+
+    /**
+     * Decode all CBOR items from data.
+     *
+     * @param string $data Binary CBOR data
+     * @return array All decoded values
+     */
+    public static function decodeAll(string $data): array
+    {
+        $decoder = new Decoder($data);
+        $items = [];
+
+        while ($decoder->hasMore()) {
+            $items[] = $decoder->decode();
+        }
+
+        return $items;
+    }
+}

tests/Unit/CBORTest.php

···
+<?php
+
+declare(strict_types=1);
+
+namespace SocialDept\Signal\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use SocialDept\Signal\Core\CBOR;
+use SocialDept\Signal\Core\CID;
+
+class CBORTest extends TestCase
+{
+    public function test_decode_unsigned_integers(): void
+    {
+        // Small value (0-23)
+        $this->assertSame(0, CBOR::decode("\x00"));
+        $this->assertSame(1, CBOR::decode("\x01"));
+        $this->assertSame(23, CBOR::decode("\x17"));
+
+        // 1-byte value
+        $this->assertSame(24, CBOR::decode("\x18\x18"));
+        $this->assertSame(255, CBOR::decode("\x18\xFF"));
+
+        // 2-byte value
+        $this->assertSame(256, CBOR::decode("\x19\x01\x00"));
+        $this->assertSame(1000, CBOR::decode("\x19\x03\xE8"));
+    }
+
+    public function test_decode_negative_integers(): void
+    {
+        // -1 is encoded as 0x20 (major type 1, value 0)
+        $this->assertSame(-1, CBOR::decode("\x20"));
+
+        // -10 is encoded as 0x29 (major type 1, value 9)
+        $this->assertSame(-10, CBOR::decode("\x29"));
+
+        // -100 is encoded as 0x38 0x63 (major type 1, 1-byte value 99)
+        $this->assertSame(-100, CBOR::decode("\x38\x63"));
+    }
+
+    public function test_decode_byte_strings(): void
+    {
+        // Empty byte string
+        $this->assertSame('', CBOR::decode("\x40"));
+
+        // 4-byte string
+        $this->assertSame("\x01\x02\x03\x04", CBOR::decode("\x44\x01\x02\x03\x04"));
+    }
+
+    public function test_decode_text_strings(): void
+    {
+        // Empty text string
+        $this->assertSame('', CBOR::decode("\x60"));
+
+        // "hello"
+        $this->assertSame('hello', CBOR::decode("\x65hello"));
+
+        // "IETF"
+        $this->assertSame('IETF', CBOR::decode("\x64IETF"));
+    }
+
+    public function test_decode_arrays(): void
+    {
+        // Empty array
+        $this->assertSame([], CBOR::decode("\x80"));
+
+        // [1, 2, 3]
+        $this->assertSame([1, 2, 3], CBOR::decode("\x83\x01\x02\x03"));
+
+        // Mixed array [1, "two", 3]
+        $result = CBOR::decode("\x83\x01\x63two\x03");
+        $this->assertSame([1, 'two', 3], $result);
+    }
+
+    public function test_decode_maps(): void
+    {
+        // Empty map
+        $this->assertSame([], CBOR::decode("\xA0"));
+
+        // {"a": 1, "b": 2}
+        $result = CBOR::decode("\xA2\x61a\x01\x61b\x02");
+        $this->assertSame(['a' => 1, 'b' => 2], $result);
+    }
+
+    public function test_decode_special_values(): void
+    {
+        // false
+        $this->assertFalse(CBOR::decode("\xF4"));
+
+        // true
+        $this->assertTrue(CBOR::decode("\xF5"));
+
+        // null
+        $this->assertNull(CBOR::decode("\xF6"));
+    }
+
+    public function test_decode_first_returns_value_and_remainder(): void
+    {
+        [$value, $remainder] = CBOR::decodeFirst("\x01\x02\x03");
+
+        $this->assertSame(1, $value);
+        $this->assertSame("\x02\x03", $remainder);
+    }
+
+    public function test_decode_nested_structures(): void
+    {
+        // {"key": [1, 2, {"inner": true}]}
+        $cbor = "\xA1\x63key\x83\x01\x02\xA1\x65inner\xF5";
+        $result = CBOR::decode($cbor);
+
+        $expected = [
+            'key' => [1, 2, ['inner' => true]],
+        ];
+
+        $this->assertSame($expected, $result);
+    }
+
+    public function test_decode_cid_tag(): void
+    {
+        // Tag 42 (CID) followed by byte string with CID data
+        // CID bytes: 0x00 prefix + version + codec + multihash
+        $cidBinary = "\x01\x71\x12\x20" . str_repeat("\x00", 32); // version 1, codec 0x71, sha256, 32 zero bytes
+        $cidBytes = "\x00" . $cidBinary; // Add 0x00 prefix for CBOR tag 42
+
+        // CBOR: tag 42 (0xD8 0x2A) + byte string with 1-byte length (0x58 = major type 2, additional info 24)
+        $length = strlen($cidBytes);
+        $cbor = "\xD8\x2A\x58" . chr($length) . $cidBytes;
+
+        $result = CBOR::decode($cbor);
+
+        $this->assertInstanceOf(CID::class, $result);
+        $this->assertSame(1, $result->version);
+        $this->assertSame(0x71, $result->codec);
+    }
+}