proto-socket/VERSIONING.md

Versioning

Proto 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). The maximum emitted nonce is 2,147,483,647 (int32 max).

Current policy:

• Implementations start at 1 and increment by 1 on every send call, including requests and responses.
• After issuing 2,147,483,647, implementations reset the internal counter to 0; the next emitted PacketBase.nonce is 1.
• 0 is reserved and must not be emitted as PacketBase.nonce, because responseNonce == 0 means "not a response".

Changing this wrap behavior or the reserved meaning of responseNonce == 0 changes nonce semantics and requires compatibility review and cross-language boundary tests.

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.