49 行
1.9 KiB
Markdown
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.
|