proto-socket/PROTOCOL.md

Toki Socket Protocol

Binary TCP protocol using Protocol Buffers for message framing and type-based routing. Designed for bidirectional, heterogeneous communication across languages and platforms.

---

Wire Format

┌──────────────────────────────────────────┐
│  Header  (4 bytes, big-endian int32)     │  ← PacketBase payload length
├──────────────────────────────────────────┤
│  PacketBase  (protobuf, N bytes)         │  ← typeName + nonce + data
└──────────────────────────────────────────┘

Header

• 4 bytes, big-endian signed int32
• Value: byte length of the following PacketBase protobuf payload
• Value of 0: reserved / no-op, receiver clears buffer

PacketBase

message PacketBase {
  string typeName = 1;   // fully-qualified protobuf message name
  int32  nonce    = 2;   // monotonically increasing per-connection counter
  bytes  data     = 3;   // serialized inner message bytes
}

Field	Description
typeName	GeneratedMessage.info_.qualifiedMessageName — language-agnostic routing key
nonce	Starts at 1, increments by 1 per send() call per connection
data	Protobuf-serialized bytes of the inner message

---

Built-in Messages

HeartBeat

message HeartBeat {}

Automatically handled by the framework. Applications do not need to register or handle this manually.

---

Heartbeat Lifecycle

Side A                                    Side B
  │                                          │
  │── (no activity for intervalTime) ──────▶│
  │        send(HeartBeat)                   │
  │                                          │── onHeartBeat() called
  │                                          │   send(HeartBeat) [response]
  │◀─────────────────────────────────────────│
  │  onHeartBeat() called                    │
  │  _waitingHeartbeatResponse = false       │
  │  timer reset                             │

• After any received message → heartbeat interval timer resets
• If no data received within heartbeatIntervalTime seconds → send HeartBeat
• If no response within heartbeatWaitTime seconds → onDisconnected() → dispose()
• Only the initiating side responds to HeartBeat echo (ping-pong prevention via _waitingHeartbeatResponse flag)

---

typeName Convention

Uses GeneratedMessage.info_.qualifiedMessageName on the send side. On the receive side, use the same value as the registration key.

Language	Registration key
Dart	T.toString() (equals qualified name for top-level proto messages)
C#	typeof(T).Name — verify matches proto qualified name
Kotlin	T::class.simpleName — verify matches
Swift	String(describing: T.self) — verify matches
Python	descriptor.name from MessageClass.DESCRIPTOR — verify matches
Rust	M::default().descriptor_dyn().name().to_string() (protobuf crate) — verify matches

Important: Verify typeName consistency across languages before connecting heterogeneous clients.

---

nonce

• Starts at 1 per connection
• Increments by 1 on every send() call
• Currently used as a message ID; request-response correlation can be built on top

---

Example Packet (hex)

Sending HeartBeat {}:

00 00 00 05          ← header: PacketBase length = 5 bytes
0A 09 48 65 61 72 74 42 65 61 74  ← PacketBase { typeName: "HeartBeat" }

---

Multi-language Implementations

Language	Status	Path
Dart	Available	dart/
C# (Unity)	Planned	csharp/
Kotlin	Planned	kotlin/
Swift	Planned	swift/
Python	Planned	python/
Rust	Planned	rust/

---

Proto Source

dart/lib/src/packets/message_common.proto is the canonical packet definition. All language implementations must generate bindings from this file.