1.9 KiB
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:
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:
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:
steadydisconnect-onceduplicate-eventsauth-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.