Edison Jwa
01a4a9ed28
Add purpose, architecture, and public API summary to each crate README following chanora_resolver pattern. Update verification master plan with new evidence sources and entry/exit criteria.
53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# chanora_protocol
|
|
|
|
TeamSpeak-compatible protocol adapter. Isolates `tsclientlib` behind a typed boundary so the rest of Chanora is decoupled from the upstream library's types (SAD-067).
|
|
|
|
## Architecture
|
|
|
|
- **`adapter` module** — wraps `tsclientlib::Connection` into an async `ProtocolClient` handle. Owns the connection task, loss notifier, snapshot probe, and voice channel endpoints.
|
|
- **`dto` module** — plain-data types (`ServerSnapshot`, `ChannelInfo`, `ClientInfo`, `ClientProfile`, `ChatMessage`) containing only `String`s and primitives. No `tsclientlib` types leak out.
|
|
- **`poke_limiter`** — rate-limiter for poke messages to prevent spam.
|
|
|
|
## Public API Summary
|
|
|
|
### Types
|
|
|
|
| Type | Role |
|
|
|---|---|
|
|
| `ProtocolClient` | Async handle owning the TS3 connection task |
|
|
| `ConnectConfig` | Connection parameters: address, nickname, password, identity, timeout, resolved_address |
|
|
| `ServerSnapshot` | Full server state: channels, clients, metadata |
|
|
| `ChannelInfo` / `ClientInfo` | Channel and client DTOs |
|
|
| `ClientProfile` | Rich per-client profile (unique_id, country, ping, groups, etc.) |
|
|
| `ChatMessage` | Inbound text message with target enum |
|
|
| `MessageTarget` | Server / Channel / Client(id) / Poke(id) |
|
|
| `ProtocolDelta` | Live state changes: client joined/left/moved/updated, channel added/removed/updated |
|
|
| `ServerActivity` | Server-wide broadcast messages |
|
|
| `DisconnectReason` | UserRequested / StreamEnded / Error |
|
|
| `ProtocolError` | Typed error catalogue: Invalid, DnsFailed, Connect, Lost, Identity, Timeout, ServerRejected, FileTransfer |
|
|
| `PokeLimiter` | Rate-limiting poke sends |
|
|
|
|
### Key methods on `ProtocolClient`
|
|
|
|
- `connect(cfg)` — dial a server and return a connected client
|
|
- `snapshot()` — fetch current server state
|
|
- `client_profile(id)` — rich profile for one client
|
|
- `send_text_message(msg, target)` — send chat
|
|
- `move_to_channel(id, password)` — move to a channel
|
|
- `queue_move_to_channel(id, password)` — async move with typed error reply
|
|
- `set_muted(input, output)` — server-side mute
|
|
- `download_avatar(uid)` / `download_icon(id)` — fetch protocol-owned assets
|
|
- `voice_out()` / `take_voice_in()` — voice packet endpoints
|
|
- `take_loss_notifier()` — oneshot channel that fires on connection loss
|
|
- `snapshot_probe()` — watchdog probe handle
|
|
- `generate_identity()` — create a fresh TS3 identity string
|
|
- `disconnect()` — clean shutdown
|
|
|
|
### Re-exports
|
|
|
|
The crate deliberately re-exports `tsproto_packets::packets::{AudioData, CodecType, Direction, InAudioBuf, OutAudio, OutPacket}` — the single permitted exception so `chanora_audio` can build voice packets without a direct `tsclientlib` dependency (SAD-067 performance carve-out).
|
|
|
|
## Address resolution
|
|
|
|
`chanora_resolver` owns TeamSpeak client address resolution (SRV, TSDNS, DNS fallback). This crate feeds the resulting `SocketAddr` to `tsclientlib::Connection::build`, bypassing tsclientlib's own resolver.
|