AstrBot-Desktop/docs/spikes/P00-07-protocol-and-mock-gateway.md
YokiiroBW 353a439b41
一些检测仍在等待运行
ci / Portable quality checks (push) Waiting to run
ci / Windows Tauri build (push) Waiting to run
docs(p00): record spike results and unresolved boundaries
2026-07-18 21:00:49 +08:00

59 行
3.4 KiB
Markdown

# P00-07: Protocol Schema and Dual Mock Gateway
- Status: Passed for the provisional desktop-v1alpha1 contract
- Date recorded: 2026-07-18
- MVP gate: Required for repeatable connection and policy tests
## Objective
Define a provisional desktop-v1alpha1 protocol and verify two independently configurable Mock Gateway instances without claiming compatibility with an unavailable real AstrBot Gateway.
## Environment
- Forgejo API and HTTP Git endpoint reachable; SSH origin remains unusable
- Real AstrBot Gateway: not connected
- Package dependencies: installed from pnpm/Cargo lockfiles
- Mock execution: two loopback instances verified
## Minimal validation implementation
The provisional schema must cover ConnectionProfile, ConnectionSlot, ConnectionState, ServerCapabilities, ClientCapabilities, ProtocolEnvelope, GatewayEvent, ToolProposal, ToolResult, DiagnosticBundle, and FileTransferPlan.
The Mock Gateway must expose health, server information, capabilities, fake authentication, SSE, proactive messages, disconnect injection, duplicate events, companion messages, and operations tool proposals. It must support two simultaneous instances with independent identity and behavior.
## Required execution
1. Validate representative valid fixtures against every schema.
2. Reject missing, unknown, malformed, oversized, and wrong-version fields as defined by policy.
3. Start two mocks on dynamic loopback ports.
4. Verify independent server_instance_id and capabilities.
5. Exercise authentication success and failure with fake values.
6. Stream normal, duplicate, delayed, disconnected, and tool-proposal events.
7. Confirm companion-origin tool proposals are rejected by the client policy boundary.
8. Record any divergence found during a later real Gateway review.
## Actual execution result
Passed for the provisional contract. The canonical Rust protocol package exports ten JSON Schemas and TypeScript types. Valid/invalid fixtures, unknown-field rejection, protocol-version checks, and schema drift checks passed.
Two independently configured loopback Mock Gateways passed health, server-info, capability, fake-auth success/failure, SSE, duplicate-event, disconnect/reconnect, proactive companion message, and operations tool-proposal tests.
Client integration tests verified local Rust-side profile binding, independent event-id deduplication, identical remote identifiers without cross-routing, and one-slot reconnect while the other slot continued. Compatibility with a real AstrBot Gateway remains explicitly unclaimed.
## Log summary
Commands: protocol contract/schema tests, Mock Gateway tests, and `cargo test --workspace`. Results: 5 protocol tests, 4 Mock Gateway integration tests, and the wider Rust suite passed. Only generated fake credentials were used.
## Known limitations
- Endpoint names, authentication fields, ACK behavior, event retention, error codes, and capability names are provisional.
- Mock success cannot prove interoperability with AstrBot.
- Loopback HTTP tests do not validate production TLS or certificate identity.
## Security impact
Schemas form the first validation boundary for untrusted remote data. Mock convenience behavior must not weaken production parsing, profile binding, role checks, or TLS validation.
## Recommendation
Version the schema explicitly, keep invalid fixtures alongside valid ones, and require a real Gateway contract review before declaring protocol compatibility.