73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# Versioning
|
|
|
|
Toki Socket tracks protocol compatibility separately from language package versions.
|
|
|
|
## Current Versions
|
|
|
|
- Protocol version: `0.1`
|
|
- Dart package version: see `dart/pubspec.yaml`
|
|
- Go module version: repository tag based
|
|
|
|
`0.1` is the current compatibility contract for the checked-in Dart and Go implementations. The wire format does not carry a protocol version field yet; compatibility is verified by shared proto definitions, unit tests, and cross-language tests.
|
|
|
|
## Protocol Version
|
|
|
|
The protocol version describes the wire-format and behavior contract that every language implementation must satisfy:
|
|
|
|
- TCP uses a 4-byte big-endian payload length followed by one `PacketBase` protobuf payload.
|
|
- WebSocket and WSS use one binary frame per `PacketBase` protobuf payload.
|
|
- `PacketBase.typeName` routes the inner message.
|
|
- `nonce` increments for every outbound packet on a connection.
|
|
- `responseNonce` links a response packet to the request nonce.
|
|
- Heartbeat behavior follows `PROTOCOL.md`.
|
|
|
|
Breaking protocol changes require a new major protocol version. Backward-compatible additions keep the same major protocol version but must include updated tests before release.
|
|
|
|
## Package Version
|
|
|
|
Each language implementation may publish on its own package cadence. Package versions communicate implementation releases, bug fixes, and language-specific API changes.
|
|
|
|
A package release must state which protocol version it implements. A package version bump does not imply a protocol version bump unless the wire-format or required behavior changes.
|
|
|
|
## Breaking Protocol Changes
|
|
|
|
Examples of breaking protocol changes:
|
|
|
|
- Renaming or removing `PacketBase` fields.
|
|
- Changing `typeName` from simple proto names to fully-qualified names without a compatibility path.
|
|
- Changing `nonce` or `responseNonce` semantics.
|
|
- Changing heartbeat request/response timing or echo behavior in a way that disconnects older peers.
|
|
- Changing TCP framing, byte order, max packet handling, or WebSocket binary-frame rules.
|
|
|
|
## Non-breaking Protocol Changes
|
|
|
|
Examples of non-breaking changes:
|
|
|
|
- Adding a new protobuf message type.
|
|
- Adding optional fields to application messages when older peers can ignore them.
|
|
- Adding a new language implementation that passes the existing protocol and cross-language tests.
|
|
- Tightening tests or documentation without changing wire behavior.
|
|
|
|
Backward-compatible message additions require updated parser maps and cross-language tests before release.
|
|
|
|
## nonce Overflow
|
|
|
|
`nonce` and `responseNonce` fields are protobuf `int32` values (signed 32-bit).
|
|
Overflow occurs after about 2.1 billion sends on a single connection.
|
|
|
|
Current policy:
|
|
|
|
- The protocol does not define overflow behavior. Reaching the int32 limit on a single connection is not realistic.
|
|
- Implementations do not add recovery logic for overflow.
|
|
- If overflow handling is needed in the future, the protocol version will be bumped and wrap-around behavior will be specified.
|
|
|
|
## New Language Compatibility
|
|
|
|
A new language implementation must target the current protocol version unless its README explicitly says otherwise. Before it is listed as available, it must:
|
|
|
|
- Generate protobuf bindings from the canonical schema.
|
|
- Use the same `typeName` values as Dart and Go.
|
|
- Implement TCP, TLS+TCP, WS, and WSS framing consistently where the language runtime supports them.
|
|
- Implement request-response correlation with `nonce` and `responseNonce`.
|
|
- Handle heartbeat automatically inside the client/server core.
|
|
- Pass same-language tests and cross-language tests against at least one available implementation.
|