96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
# 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](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/](dart/) | Flutter, Dart server |
|
|
| C# | Planned | `csharp/` | Unity, .NET |
|
|
| Kotlin | Planned | `kotlin/` | Android |
|
|
| Swift | Planned | `swift/` | iOS, macOS |
|
|
| Python | Planned | `python/` | Server, tooling, scripting |
|
|
| Rust | Planned | `rust/` | High-performance server, embedded |
|
|
|
|
---
|
|
|
|
## Quick Start (Dart)
|
|
|
|
```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:
|
|
|
|
```bash
|
|
cd dart
|
|
dart pub global activate protoc_plugin
|
|
protoc --dart_out=lib/src/packets lib/src/packets/message_common.proto
|
|
```
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
cd dart
|
|
dart pub get
|
|
dart test
|
|
```
|