AstrBot-Desktop/docs/decisions/ADR-0002-bind-profile-identity-at-rust-connection-boundary.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

2.1 KiB

ADR-0002: Bind Profile Identity at the Rust Connection Boundary

  • Status: Accepted
  • Date: 2026-07-18
  • Scope: Protocol identity, dual-instance isolation, and connection lifecycle

Context

The desktop client maintains two simultaneously active connection slots: companion and operations. A remote event can contain identifiers such as profile_id, server_instance_id, conversation_id, and message_id. The remote service is not authoritative for the local profile assignment, and conversation or message identifiers may overlap across servers.

Options considered

  1. Merge both SSE streams and route events using remote conversation_id values.
  2. Trust a remote profile_id field and route events from a shared client.
  3. Maintain one independently owned connection session per active slot and attach the selected local profile identity before events leave the Rust networking layer.

Decision

Each active slot owns an independent REST client, SSE stream, cancellation handle, retry state, Last-Event-ID cursor, and deduplication cache.

The Rust networking layer binds every accepted event to the locally selected profile_id. A remote profile_id is treated as untrusted protocol data and cannot override local routing.

Persisted or cached server data is keyed by at least profile_id, server_instance_id, and conversation_id. Message-level data additionally uses message_id where applicable.

The initial Mock Gateway protocol is explicitly provisional and identified as desktop-v1alpha1 until it is reviewed against a real AstrBot Gateway.

Rationale

  • Prevents cross-instance message and authorization confusion.
  • Allows either connection to fail, cancel, or reconnect independently.
  • Makes the operations-slot security check deterministic.
  • Preserves isolation when two servers reuse the same conversation or message IDs.

Consequences

  • Shared global retry, cursor, and deduplication state is prohibited.
  • Tests must inject identical and malicious identifiers across both mock instances.
  • A server identity change freezes local-tool eligibility until the user reconfirms it.
  • Real AstrBot compatibility remains unverified while the Gateway is unavailable.