Skip to content

Support every Skir serialization format - #2

Merged
happyDemon merged 4 commits into
mainfrom
skir-rpc-protocol
Nov 9, 2026
Merged

happyDemon merged 4 commits into
mainfrom
skir-rpc-protocol

Conversation

@happyDemon

Copy link
Copy Markdown
Member

Skir declares three serialization formats: dense JSON, readable JSON and binary. The runtime only had dense JSON. This PR adds the other two, byte-for-byte compatible with the upstream TypeScript runtime (skir-client@1.0.22). Test vectors were generated by running upstream, not written by hand.

New API

  • ReadableJson::encode() / ReadableJson::toJson(): readable JSON, formatted like upstream (2-space indent, unescaped unicode, JS number formatting).
  • BinaryFormat::encode() / BinaryFormat::decode(): the binary format, including the skir header.
  • DenseJson::decode() / fromJson() now accept either JSON flavor, like upstream fromJson.

Behaviour now matching upstream (from a code review against the TS runtime)

  • Unknown enum variant numbers/names decode to UNKNOWN instead of throwing, so adding a variant on the server no longer breaks PHP clients.
  • A wrapper value for a constant variant decodes to the constant. A bare number for a wrapper variant decodes to the wrapper with its default payload.
  • null decodes to the default struct. Objects decode by field name.
  • int64/hash64 decode to int when they fit and to a digit string otherwise; garbage is rejected. int32 wraps and 64-bit values clamp like upstream on encode.
  • Strings must be strings. Dense JSON output keeps unicode unescaped.

Known gaps vs upstream (PHP constraints)

  • Invalid UTF-8 throws instead of being replaced with U+FFFD.
  • json_decode can't tell {"0":…} from a list.
  • Readable struct fields come out in field-number order, not declaration order, because Type::struct doesn't keep declaration order.

Shared logic lives in src/Internal (@internal).

Breaking (0.2.0): decoding is more permissive (enum evolution) and more strict (types).

Pairs with php-skir/server#2 and php-skir/client#2.

Add ReadableJson::encode() and ReadableJson::toJson(), matching the
upstream skir-client toJson(value, "readable") and toJsonCode(value,
"readable") output, including two-space indentation and JavaScript
number formatting.

DenseJson::decode() and DenseJson::fromJson() now accept both flavors
and follow upstream fromJson coercion: unknown enum variants and names
decode to UNKNOWN, constant/wrapper shape changes are tolerated, null
structs decode to defaults, and invalid strings, bytes and int64 values
are rejected. Dense encoding now wraps int32 values, clamps int64,
hash64 and timestamp values and writes JSON the way JSON.stringify
does.

Type traversal is shared by an internal JsonCodec. Expected values in
the tests were generated with the upstream skir-client package.
Add BinaryFormat::encode() and BinaryFormat::decode(), byte-for-byte
compatible with the upstream skir-client toBytes() and fromBytes(),
including the "skir" header, the variable-length number wires, the
UTF-16 based string length prefix sizing, struct slot trimming and
skipping of unrecognized struct slots and enum payloads.

Expected bytes in the tests were generated with the upstream
skir-client package.
Encoding cast them with (string), turning arrays into a PHP warning instead
of a SkirRuntimeException.
@happyDemon
happyDemon merged commit fe85fb5 into main Nov 9, 2026
5 checks passed
@happyDemon
happyDemon deleted the skir-rpc-protocol branch November 9, 2026 11:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant