Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Declaring a repeated field of a non-packable type (string, bytes, message) as `packed: true` now throws
`Exception\InvalidSchema` when the type is created. It used to produce output that no parser reads correctly.
- Serializing a value that its protobuf type cannot represent now throws `Exception\ValueOutOfRange` instead of
wrapping it or writing a broken varint: `int32`/`sint32`/`sfixed32`/enum outside [-2^31, 2^31-1] (e.g.
`int32Of(2 ** 31)` used to wrap to a negative number), `uint32`/`fixed32` outside [0, 2^32-1], and
`uint64`/`fixed64` that are negative, above 2^64-1 or fractional.
- Serializing a string-backed PHP enum as a protobuf enum throws `Exception\InvalidSchema` instead of
`\InvalidArgumentException`.

### Fixed

- Negative enum numbers are encoded as 10-byte sign-extended varints, as protobuf requires. They used to be
written as a truncated varint that no parser, including this one, could read.
29 changes: 29 additions & 0 deletions src/Exception/ValueOutOfRange.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<?php

declare(strict_types=1);

namespace Thesis\Protobuf\Exception;

use BcMath\Number;
use Thesis\Protobuf\ProtobufException;

/**
* A value that the declared protobuf type cannot represent, e.g. a negative uint32 or an int32 above 2^31-1.
* Values are never wrapped or truncated silently.
*
* @api
*/
final class ValueOutOfRange extends ProtobufException
{
/**
* @param non-empty-string $type protobuf type name, e.g. "int32"
* @param non-empty-string $range the values the type accepts, e.g. "[0, 4294967295]"
*/
public function __construct(
public readonly string $type,
public readonly int|Number $value,
string $range,
) {
parent::__construct(\sprintf('Value %s is out of range for %s: expected an integer in %s.', $value, $type, $range));
}
}
61 changes: 61 additions & 0 deletions src/Internal/Serde/Range.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
<?php

declare(strict_types=1);

namespace Thesis\Protobuf\Internal\Serde;

use BcMath\Number;
use Thesis\Protobuf\Exception\ValueOutOfRange;

/**
* Range checks for the values being serialized: protobuf types narrower than a PHP int, and unsigned 64-bit
* types carried by a Number.
*
* @internal
*/
final class Range
{
private const int INT32_MIN = -2_147_483_648;
private const int INT32_MAX = 2_147_483_647;
private const int UINT32_MAX = 4_294_967_295;
private const string UINT64_MAX = '18446744073709551615';

/**
* @param non-empty-string $type
* @throws ValueOutOfRange
*/
public static function int32(int $value, string $type): int
{
if ($value < self::INT32_MIN || $value > self::INT32_MAX) {
throw new ValueOutOfRange($type, $value, \sprintf('[%d, %d]', self::INT32_MIN, self::INT32_MAX));
}

return $value;
}

/**
* @param non-empty-string $type
* @throws ValueOutOfRange
*/
public static function uint32(int $value, string $type): int
{
if ($value < 0 || $value > self::UINT32_MAX) {
throw new ValueOutOfRange($type, $value, \sprintf('[0, %d]', self::UINT32_MAX));
}

return $value;
}

/**
* @param non-empty-string $type
* @throws ValueOutOfRange
*/
public static function uint64(Number $value, string $type): Number
{
if ($value->compare(0) < 0 || $value->compare(self::UINT64_MAX) > 0 || $value->compare($value->floor()) !== 0) {
throw new ValueOutOfRange($type, $value, \sprintf('[0, %s]', self::UINT64_MAX));
}

return $value;
}
}
2 changes: 1 addition & 1 deletion src/Internal/Serde/SerdeFixed32.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ enum SerdeFixed32 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
$buffer->write(Endian\Order::Little->packUint32($value));
$buffer->write(Endian\Order::Little->packUint32(Range::uint32($value, 'fixed32')));
}

#[\Override]
Expand Down
2 changes: 1 addition & 1 deletion src/Internal/Serde/SerdeFixed64.php
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ enum SerdeFixed64 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
$buffer->write(Endian\Order::Little->packUint64($value));
$buffer->write(Endian\Order::Little->packUint64(Range::uint64($value, 'fixed64')));
}

#[\Override]
Expand Down
21 changes: 2 additions & 19 deletions src/Internal/Serde/SerdeInt32.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,25 +22,8 @@ enum SerdeInt32 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
/** @var ?Number $p32 */
static $p32;
$p32 ??= new Number(2)->pow(32);

/** @var ?Number $p64 */
static $p64;
$p64 ??= new Number(2)->pow(64);

$num = new Number($value)->mod($p32);

if ($num->compare($p32->div(2)) >= 0) {
$num -= $p32;
}

if ($num->compare(0) < 0) {
$num += $p64;
}

SerdeVarint::T->serialize($buffer, $num);
// A negative int32 is encoded as its 64-bit sign extension, exactly like an int64.
SerdeInt64::T->serialize($buffer, Range::int32($value, 'int32'));
}

#[\Override]
Expand Down
2 changes: 1 addition & 1 deletion src/Internal/Serde/SerdeSFixed32.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ enum SerdeSFixed32 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
$buffer->write(Endian\Order::Little->packInt32($value));
$buffer->write(Endian\Order::Little->packInt32(Range::int32($value, 'sfixed32')));
}

#[\Override]
Expand Down
18 changes: 2 additions & 16 deletions src/Internal/Serde/SerdeSInt32.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,22 +22,8 @@ enum SerdeSInt32 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
/** @var ?Number $p31 */
static $p31;

/** @var ?Number $p32 */
static $p32;

$p31 ??= new Number(2)->pow(31);
$p32 ??= new Number(2)->pow(32);

$num = new Number($value)->mod($p32);

if ($num->compare($p31) >= 0) {
$num -= $p32;
}

SerdeSInt64::T->serialize($buffer, (int) $num->value);
// For values in the int32 range ZigZag-64 gives the same number as ZigZag-32.
SerdeSInt64::T->serialize($buffer, Range::int32($value, 'sint32'));
}

#[\Override]
Expand Down
6 changes: 1 addition & 5 deletions src/Internal/Serde/SerdeUint32.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,7 @@ enum SerdeUint32 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
/** @var ?Number $p32 */
static $p32;
$p32 ??= new Number(2)->pow(32);

SerdeVarint::T->serialize($buffer, new Number($value)->mod($p32));
SerdeVarint::T->serialize($buffer, new Number(Range::uint32($value, 'uint32')));
}

#[\Override]
Expand Down
2 changes: 1 addition & 1 deletion src/Internal/Serde/SerdeUint64.php
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ enum SerdeUint64 implements
#[\Override]
public function serialize(WriteBuffer $buffer, mixed $value): void
{
SerdeVarint::T->serialize($buffer, $value);
SerdeVarint::T->serialize($buffer, Range::uint64($value, 'uint64'));
}

#[\Override]
Expand Down
7 changes: 4 additions & 3 deletions src/Internal/Serde/SerializeEnum.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

namespace Thesis\Protobuf\Internal\Serde;

use BcMath\Number;
use Thesis\Protobuf\Exception\InvalidSchema;
use Thesis\Protobuf\Internal\Buffer\WriteBuffer;

/**
Expand All @@ -20,9 +20,10 @@ public function serialize(WriteBuffer $buffer, mixed $value): void
{
$case = $value->value;
if (!\is_int($case)) {
throw new \InvalidArgumentException('BackedEnum should be integer.');
throw new InvalidSchema(\sprintf('Enum "%s" must be int-backed to be a protobuf enum.', $value::class));
}

SerdeVarint::T->serialize($buffer, new Number($case));
// Enum numbers are int32: a negative one is sign-extended to 64 bits.
SerdeInt64::T->serialize($buffer, Range::int32($case, 'enum'));
}
}
160 changes: 160 additions & 0 deletions tests/ValueRangeTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
<?php

declare(strict_types=1);

namespace Thesis\Protobuf;

use BcMath\Number;
use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
use Thesis\Protobuf\Exception\InvalidSchema;
use Thesis\Protobuf\Exception\ValueOutOfRange;
use Thesis\Protobuf\Internal\Serde\Range;
use Thesis\Protobuf\Internal\Serde\SerdeFixed32;
use Thesis\Protobuf\Internal\Serde\SerdeFixed64;
use Thesis\Protobuf\Internal\Serde\SerdeInt32;
use Thesis\Protobuf\Internal\Serde\SerdeSFixed32;
use Thesis\Protobuf\Internal\Serde\SerdeSInt32;
use Thesis\Protobuf\Internal\Serde\SerdeUint32;
use Thesis\Protobuf\Internal\Serde\SerdeUint64;
use Thesis\Protobuf\Internal\Serde\SerializeEnum;

#[CoversClass(ValueOutOfRange::class)]
#[CoversClass(Range::class)]
#[CoversClass(SerdeInt32::class)]
#[CoversClass(SerdeSInt32::class)]
#[CoversClass(SerdeUint32::class)]
#[CoversClass(SerdeUint64::class)]
#[CoversClass(SerdeFixed32::class)]
#[CoversClass(SerdeSFixed32::class)]
#[CoversClass(SerdeFixed64::class)]
#[CoversClass(SerializeEnum::class)]
final class ValueRangeTest extends TestCase
{
/**
* @param FieldDescriptor<*> $field
* @param non-empty-string $type
*/
#[DataProvider('provideOutOfRangeValuesAreRejectedCases')]
public function testOutOfRangeValuesAreRejected(FieldDescriptor $field, string $type, string $shown): void
{
try {
new Serializer()->serialize(message($field));
self::fail('Serialization must fail.');
} catch (ValueOutOfRange $e) {
self::assertSame($type, $e->type);
self::assertSame($shown, (string) $e->value);
self::assertStringContainsString("{$shown} is out of range for {$type}", $e->getMessage());
}
}

/**
* @return iterable<string, array{FieldDescriptor<*>, non-empty-string, string}>
*/
public static function provideOutOfRangeValuesAreRejectedCases(): iterable
{
yield 'int32 above max' => [fieldOf(1, int32Of(2 ** 31)), 'int32', '2147483648'];
yield 'int32 below min' => [fieldOf(1, int32Of(-2 ** 31 - 1)), 'int32', '-2147483649'];
yield 'sint32 above max' => [fieldOf(1, sint32Of(2 ** 31)), 'sint32', '2147483648'];
yield 'sint32 below min' => [fieldOf(1, sint32Of(-2 ** 31 - 1)), 'sint32', '-2147483649'];
yield 'sfixed32 above max' => [fieldOf(1, sfixed32Of(2 ** 31)), 'sfixed32', '2147483648'];
yield 'sfixed32 below min' => [fieldOf(1, sfixed32Of(-2 ** 31 - 1)), 'sfixed32', '-2147483649'];
yield 'uint32 negative' => [fieldOf(1, uint32Of(-1)), 'uint32', '-1'];
yield 'uint32 above max' => [fieldOf(1, uint32Of(2 ** 32)), 'uint32', '4294967296'];
yield 'fixed32 negative' => [fieldOf(1, fixed32Of(-1)), 'fixed32', '-1'];
yield 'fixed32 above max' => [fieldOf(1, fixed32Of(2 ** 32)), 'fixed32', '4294967296'];
yield 'uint64 negative' => [fieldOf(1, uint64Of(new Number(-1))), 'uint64', '-1'];
yield 'uint64 above max' => [fieldOf(1, uint64Of(new Number('18446744073709551616'))), 'uint64', '18446744073709551616'];
yield 'uint64 fractional' => [fieldOf(1, uint64Of(new Number('1.5'))), 'uint64', '1.5'];
yield 'fixed64 negative' => [fieldOf(1, fixed64Of(new Number(-1))), 'fixed64', '-1'];
yield 'fixed64 above max' => [fieldOf(1, fixed64Of(new Number('18446744073709551616'))), 'fixed64', '18446744073709551616'];
yield 'fixed64 fractional' => [fieldOf(1, fixed64Of(new Number('1.5'))), 'fixed64', '1.5'];
yield 'enum above max' => [fieldOf(1, enumOf(ValueRangeTestEnum::TooBig)), 'enum', '2147483648'];
yield 'enum below min' => [fieldOf(1, enumOf(ValueRangeTestEnum::TooSmall)), 'enum', '-2147483649'];
yield 'packed list element' => [fieldOf(1, listOf(int32T, [1, 2 ** 31], true)), 'int32', '2147483648'];
yield 'unpacked list element' => [fieldOf(1, listOf(uint32T, [1, -1], false)), 'uint32', '-1'];
yield 'map key' => [fieldOf(1, mapOf(uint32T, stringT, Map::fromArray([-1 => 'a']))), 'uint32', '-1'];
yield 'map value' => [fieldOf(1, mapOf(stringT, sint32T, Map::fromArray(['a' => 2 ** 31]))), 'sint32', '2147483648'];
}

/**
* @param FieldDescriptor<*> $field
* @param non-empty-string $hex
*/
#[DataProvider('provideBoundaryValuesAreEncodedCases')]
public function testBoundaryValuesAreEncoded(FieldDescriptor $field, string $hex): void
{
self::assertSame($hex, bin2hex(new Serializer()->serialize(message($field))));
}

/**
* @return iterable<string, array{FieldDescriptor<*>, non-empty-string}>
*/
public static function provideBoundaryValuesAreEncodedCases(): iterable
{
yield 'int32 max' => [fieldOf(1, int32Of(2 ** 31 - 1)), '08ffffffff07'];
yield 'int32 min' => [fieldOf(1, int32Of(-2 ** 31)), '0880808080f8ffffffff01'];
yield 'sint32 max' => [fieldOf(1, sint32Of(2 ** 31 - 1)), '08feffffff0f'];
yield 'sint32 min' => [fieldOf(1, sint32Of(-2 ** 31)), '08ffffffff0f'];
yield 'sfixed32 max' => [fieldOf(1, sfixed32Of(2 ** 31 - 1)), '0dffffff7f'];
yield 'sfixed32 min' => [fieldOf(1, sfixed32Of(-2 ** 31)), '0d00000080'];
yield 'uint32 max' => [fieldOf(1, uint32Of(2 ** 32 - 1)), '08ffffffff0f'];
yield 'fixed32 max' => [fieldOf(1, fixed32Of(2 ** 32 - 1)), '0dffffffff'];
yield 'uint64 max' => [fieldOf(1, uint64Of(new Number('18446744073709551615'))), '08ffffffffffffffffff01'];
yield 'uint64 integral with a scale' => [fieldOf(1, uint64Of(new Number('5.0'))), '0805'];
yield 'fixed64 max' => [fieldOf(1, fixed64Of(new Number('18446744073709551615'))), '09ffffffffffffffff'];
yield 'fixed64 integral with a scale' => [fieldOf(1, fixed64Of(new Number('5.0'))), '090500000000000000'];
yield 'enum -1 is sign-extended' => [fieldOf(1, enumOf(ValueRangeTestEnum::MinusOne)), '08ffffffffffffffffff01'];
yield 'enum int32 min' => [fieldOf(1, enumOf(ValueRangeTestEnum::Min)), '0880808080f8ffffffff01'];
yield 'enum int32 max' => [fieldOf(1, enumOf(ValueRangeTestEnum::Max)), '08ffffffff07'];
}

public function testNegativeEnumRoundTrips(): void
{
$serializer = new Serializer();
$bytes = $serializer->serialize(message(fieldOf(1, enumOf(ValueRangeTestEnum::MinusOne))));

$decoded = $serializer->deserialize(messageT(fieldT(1, enumT(ValueRangeTestEnum::class))), $bytes);

self::assertSame(ValueRangeTestEnum::MinusOne, ($decoded->fields[1] ?? null)?->value->value);
}

public function testStringBackedEnumIsRejected(): void
{
$this->expectException(InvalidSchema::class);
$this->expectExceptionMessage(\sprintf('Enum "%s" must be int-backed', ValueRangeTestStringEnum::class));

new Serializer()->serialize(message(fieldOf(1, enumOf(ValueRangeTestStringEnum::A))));
}

public function testEncoderReportsOutOfRangeValues(): void
{
$this->expectException(ValueOutOfRange::class);

Encoder\Builder::buildDefault()->encode(new ValueRangeTestMessage(2 ** 31));
}
}

enum ValueRangeTestEnum: int
{
case Zero = 0;
case MinusOne = -1;
case Min = -2147483648;
case Max = 2147483647;
case TooBig = 2147483648;
case TooSmall = -2147483649;
}

enum ValueRangeTestStringEnum: string
{
case A = 'a';
}

final readonly class ValueRangeTestMessage
{
public function __construct(
#[Reflection\Field(1, Reflection\Int32T::T)]
public int $value = 0,
) {}
}
Loading