Edison Jwa
7968f90f7d
tsdeclarations eval: direct codegen redundant (already via tsproto), but permission ID generation and error code enum have high value. Permission mapping: 253 TS3 permissions identified, 7 P1 for chat/moderation. Encoding verification: tsclientlib uses strict UTF-8, UCS-2 is edge case.
144 lines
6.7 KiB
Markdown
144 lines
6.7 KiB
Markdown
# tsdeclarations Code Generation Evaluation
|
||
|
||
**TODO-068** — Evaluate Messages.toml, Book.toml, Enums.toml for code generation feasibility.
|
||
|
||
---
|
||
|
||
## 1. What tsdeclarations Provides
|
||
|
||
The [ReSpeak/tsdeclarations](https://github.com/ReSpeak/tsdeclarations) repository contains machine-readable protocol data files used for code generation across the ReSpeak ecosystem:
|
||
|
||
| File | Purpose | Format |
|
||
|------|---------|--------|
|
||
| `Messages.toml` | All TS3 client↔server commands and their parameters | TOML structs with typed fields |
|
||
| `Book.toml` | State-tracking structures for server entities (Client, Channel, Server, ServerGroup, etc.) | TOML structs with typed fields |
|
||
| `Enums.toml` | Protocol enums (Codec, PermissionType, Reason, ChannelType, LicenseType, etc.) | TOML enum definitions |
|
||
| `MessagesToBook.toml` | Mappings from incoming commands to Book struct updates | TOML mapping rules |
|
||
| `BookToMessages.toml` | Functions to generate outgoing commands from Book state | TOML generation rules |
|
||
| `Errors.csv` | All TS3 error codes (hex, name, description) | CSV |
|
||
| `Permissions.csv` | All TS3 permission IDs (name, description, numeric ID) | CSV |
|
||
| `Versions.csv` | Known client version hashes (1536 entries) | CSV |
|
||
| `Badges.csv` | Known badge GUIDs and metadata | CSV |
|
||
|
||
### How ReSpeak Uses Them
|
||
|
||
The `tsclientlib` workspace consumes these via:
|
||
|
||
- **`tsproto-structs`** — build-time code generation from TOML files into Rust structs
|
||
- **`tsproto-types`** — basic TS3 types (error codes, versions, UIDs)
|
||
- **`ts-bookkeeping`** — state tracking that maps incoming messages to Book struct updates
|
||
- **`tsproto-packets`** — command parsing/serialization
|
||
|
||
Chanora already depends on `tsproto-structs`, `tsproto-types`, and `ts-bookkeeping` as git dependencies (via `chanora_protocol`).
|
||
|
||
---
|
||
|
||
## 2. Current Chanora Usage
|
||
|
||
| Component | Source | Status |
|
||
|-----------|--------|--------|
|
||
| `tsproto-types` | Git dependency (patched fork for P-256 coordinate padding) | Active |
|
||
| `tsproto-structs` | Git dependency (rev 04aa2491) | Active |
|
||
| `ts_bookkeeping` | Used in `chanora_protocol/src/adapter.rs` for event projection | Active |
|
||
| Error codes | Referenced from `Errors.csv` via `tsproto-types` | Active |
|
||
| Version hashes | Baked into `adapter.rs` from `Versions.csv` | Active |
|
||
| Permissions | **Not used** — no TS3 permission ID mapping exists in Chanora |
|
||
| `Messages.toml` | **Not directly used** — Chanora uses `ts_bookkeeping` which consumes it internally |
|
||
| `Book.toml` | **Not directly used** — consumed by `ts_bookkeeping` internally |
|
||
| `Enums.toml` | **Not directly used** — consumed by `tsproto-structs` internally |
|
||
|
||
---
|
||
|
||
## 3. Feasibility Assessment
|
||
|
||
### 3.1 Automating Protocol Struct Generation
|
||
|
||
**Verdict: Already happening indirectly via tsproto-structs/ts_bookkeeping.**
|
||
|
||
Chanora already benefits from the tsdeclarations code generation pipeline through its dependency on `tsproto-structs` and `ts_bookkeeping`. The TOML files are consumed at build time by these upstream crates, producing:
|
||
|
||
- Typed command structs (`c2s::Clientinit`, `s2c::Initserver`, etc.)
|
||
- Event mapping logic (`Event`, `PropertyId`, `PropertyValue`)
|
||
- Book state structures
|
||
|
||
Direct consumption of `Messages.toml`/`Book.toml` to generate *Chanora-specific* structs would be **redundant** with the existing `ts_bookkeeping` dependency.
|
||
|
||
### 3.2 Generating Chanora-Specific DTOs from Book.toml
|
||
|
||
**Verdict: Moderate value, moderate effort.**
|
||
|
||
The `Book.toml` defines the canonical shape of tracked entities (Client, Channel, Server, ServerGroup, ChannelGroup). Chanora currently has its own DTO types:
|
||
|
||
- `BridgeClient` / `BridgeChannel` / `BridgeSnapshot` (in `chanora_bridge/src/api.rs`)
|
||
- `ClientProfile` / `ServerSnapshot` (in `chanora_core`)
|
||
|
||
A code-gen step could auto-generate these DTOs from `Book.toml`, ensuring field parity with the protocol. However:
|
||
|
||
- Chanora's DTOs intentionally omit many protocol fields (privacy, simplicity)
|
||
- The mapping from Book fields to bridge DTOs involves business logic (e.g., `PermissionHints` gating)
|
||
- Manual DTOs are easier to evolve independently
|
||
|
||
**Recommendation:** Keep manual DTOs. Use `Book.toml` as a *reference* when adding new fields, not as a code-gen source.
|
||
|
||
### 3.3 Generating Event Types from Messages.toml
|
||
|
||
**Verdict: Low value for Chanora.**
|
||
|
||
`ts_bookkeeping` already handles the command→event mapping. Chanora's `SessionEvent` enum is a higher-level abstraction that doesn't map 1:1 to protocol commands. Auto-generating it from `Messages.toml` would require a complex mapping layer that defeats the purpose.
|
||
|
||
### 3.4 Error Code and Permission ID Generation
|
||
|
||
**Verdict: High value, low effort.**
|
||
|
||
The CSV files (`Errors.csv`, `Permissions.csv`) are simple, stable, and directly useful:
|
||
|
||
- **Errors**: Chanora already references `Errors.csv` names but hardcodes hex values. A build step could generate a `const` table.
|
||
- **Permissions**: No permission ID mapping exists yet (TODO-069). `Permissions.csv` is the canonical source.
|
||
|
||
### 3.5 Version Hash Generation
|
||
|
||
**Verdict: Already done manually; automation possible but low priority.**
|
||
|
||
Version hashes from `Versions.csv` are baked into `adapter.rs` at vendor time. A build step could auto-update them, but the list changes infrequently.
|
||
|
||
---
|
||
|
||
## 4. Recommended Approach
|
||
|
||
| Priority | Action | Effort | Value |
|
||
|----------|--------|--------|-------|
|
||
| P1 | Use `Permissions.csv` to generate a Rust permission ID constants module (see TODO-069) | 1–2 days | High |
|
||
| P2 | Use `Errors.csv` to generate a typed error code enum with `From<u16>` | 0.5 days | Medium |
|
||
| P3 | Add a CI check that diffs `tsproto-structs`/`ts_bookkeeping` against upstream tsdeclarations HEAD | 0.5 days | Medium |
|
||
| P4 | Keep `Book.toml`/`Messages.toml` as reference documentation only | 0 days | — |
|
||
|
||
### What NOT to Do
|
||
|
||
- **Do not** fork or vendor the TOML files into Chanora's build pipeline
|
||
- **Do not** auto-generate Chanora's bridge DTOs from `Book.toml`
|
||
- **Do not** auto-generate `SessionEvent` from `Messages.toml`
|
||
- **Do not** maintain a separate TOML parser — let upstream crates handle this
|
||
|
||
---
|
||
|
||
## 5. Effort Estimate
|
||
|
||
| Task | Estimate |
|
||
|------|----------|
|
||
| Permission ID constants from `Permissions.csv` | 1–2 days |
|
||
| Error code enum from `Errors.csv` | 0.5 days |
|
||
| CI upstream diff check | 0.5 days |
|
||
| **Total** | **2–3 days** |
|
||
|
||
---
|
||
|
||
## 6. Dependencies and Risks
|
||
|
||
- **Upstream stability**: `tsdeclarations` is MIT/Apache-2.0 licensed, active (94 commits), and used by `tsclientlib`. Low risk of abandonment.
|
||
- **TS5 compatibility**: The files may need updates when TS5 protocol stabilizes (TODO-058 monitors this).
|
||
- **Patched fork**: Chanora uses a patched `tsproto-types` fork for P-256 coordinate padding. Any code-gen from upstream must account for this.
|
||
|
||
---
|
||
|
||
*Created: 2026-06-11 for TODO-068*
|