AstrBot-Desktop/docs/protocol/v1/README.md

49 行
1.9 KiB
Markdown

# AstrBot Desktop Gateway Protocol v1
Status: provisional P00 contract for desktop development and the local Mock Gateway.
Compatibility with a real AstrBot Gateway must not be claimed until the server-side contract is reviewed.
## Source of truth
Rust types in `crates/desktop-protocol` are authoritative. JSON Schema files in `schemas/` are generated and checked with:
```text
cargo run -p desktop-protocol --example export_schemas -- --write
cargo run -p desktop-protocol --example export_schemas
```
Generated Schema files must not be edited manually.
## Trust boundary
An inbound `profileId` is an untrusted server hint. The Rust connection object binds each accepted event to its local `profile_id` and `companion` or `operations` slot. `serverInstanceId` must match the identity obtained from `server-info`.
The React application never connects directly to this protocol and never receives access or refresh tokens.
## Versioning
- REST prefix: `/desktop/v1`
- Envelope version: `1.0`
- Breaking wire changes require a new major REST prefix and protocol version.
- Unknown event types are reported as unsupported and safely skipped; they are not routed to the UI.
- Security-sensitive payloads reject unknown outer fields.
## Mock instances
Run each instance in a separate process when manually testing independent failure:
```text
cargo run -p mock-gateway -- --instance companion --port 43101
cargo run -p mock-gateway -- --instance operations --port 43102
```
The Mock Gateway refuses non-loopback bind addresses. It uses only runtime-generated mock credentials, has no shell/file/NAS capability, and is not a Tauri release dependency.
Available fixed scenarios:
- `steady`
- `disconnect-once`
- `duplicate-events`
- `auth-reject`
The 30-minute dual-SSE soak is an explicit local Spike acceptance run and must be recorded separately; its result is not implied by unit tests.