Toki Socket

Binary TCP socket protocol library for bidirectional, heterogeneous communication across languages and platforms.

Built on Protocol Buffers with a fixed 4-byte length-prefixed framing, type-based message routing, and built-in heartbeat.

---

Design Principles

• Keep the core transport layer thin and stable
• Provide only the minimum common foundation for cross-language communication5
• Standardize framing, serialization, routing, request-response correlation, and heartbeat
• Do not embed application semantics into the protocol core
• Domain-specific concerns such as auth, session, agent workflow, chat features, and game logic belong in upper-layer implementations

---

Protocol

See PROTOCOL.md for the full wire format specification.

[4-byte big-endian length] [PacketBase protobuf bytes]

---

Implementations

Language	Status	Path	Use case
Dart	Available	dart/	Flutter, Dart server
C#	Planned	csharp/	Unity, .NET
Kotlin	Planned	kotlin/	Android
Swift	Planned	swift/	iOS, macOS
Go	Planned	go/	Server, tooling, scripting
Python	Planned	python/	Server, tooling, scripting
Rust	Planned	rust/	High-performance server, embedded

---

Quick Start (Dart)

import 'package:toki_socket/toki_socket.dart';

// 1. Define your message in message_common.proto, generate with protoc

// 2. Implement a client
class MyClient extends ProtobufClient {
  MyClient(Socket socket) : super(socket, 30, 10, {
    MyMessage.getDefault().info_.qualifiedMessageName: MyMessage.fromBuffer,
  });
}

// 3. Implement a server
class MyServer extends ProtobufServer {
  MyServer() : super('0.0.0.0', 9090, (socket) => MyClient(socket));

  @override
  void onClientConnected(ProtobufClient client) {
    client.addListener<MyMessage>((msg) => print('Received: ${msg}'));
  }
}

// 4. Start
final server = MyServer();
await server.start();

// 5. Connect and send
final socket = await Socket.connect('localhost', 9090);
final client = MyClient(socket);
await client.send(MyMessage()..text = 'hello');

---

Adding Message Types

Edit dart/lib/src/packets/message_common.proto and regenerate:

cd dart
dart pub global activate protoc_plugin
protoc --dart_out=lib/src/packets lib/src/packets/message_common.proto

---

Running Tests

cd dart
dart pub get
dart test