droboticflow/docs/drosync/architecture.md
2026-07-28 20:43:46 +08:00

2.8 KiB

Architecture and state machines

Components

  1. The Rust daemon exclusively owns scheduling and the local SQLite journal. CLI and GUI use a 0600 Unix socket or a current-user Windows named pipe.
  2. The Go API authenticates a device credential, enforces scope/quota/idempotency, accepts paged manifests, creates leases, and issues integrity-bound staging URLs.
  3. drosync-coordinator atomically claims Mongo work across replicas. It plans items, verifies fencing tokens and staging headers, publishes conditionally, reconciles tracked heads, cleans 24-hour staging, and writes immutable release manifests.
  4. BOS contains business objects plus separate internal staging, release, and audit prefixes. Mongo contains control metadata; a million items are individual documents, never an embedded session array.

Each immutable release belongs to exactly one sync space. All source sessions must share that space, so the NDJSON manifest has one unambiguous BOS bucket and prefix context; Mongo stores the space ID, manifest key, SHA-256, counts, lifecycle state, and source session IDs.

flowchart LR
  L["Local regular files"] --> D["Rust daemon and SQLite journal"]
  C["CLI / tray GUI"] -->|"local IPC"| D
  D -->|"manifest, lease, commit"| A["Go control-plane API"]
  D -->|"MD5-bound presigned upload"| S["BOS staging prefix"]
  A --> M["MongoDB"]
  Q["drosync-coordinator"] --> M
  Q -->|"multipart copy + conditional complete"| B["BOS business prefix"]
  Q --> R["Immutable release manifest"]
  Q --> X["Reconcile and staging cleanup"]

Session state

collecting_manifest → planning → planned → running → completed | partial | conflicted

Any active state may transition to failed, aborted, or expired. A final session is immutable except for retention cleanup.

Item state

discovered → planned → reserved → uploading → uploaded → committing → committed

Planning may yield unchanged, skipped, or denied. Conditional publication may yield kept_both. Error and cancellation terminals are failed, aborted, and expired.

Lease invariant

Each logical target hash has one permanent Mongo lease document. Acquisition atomically increments a monotonic fencing token. Release clears ownership but never deletes the counter. Coordinator commit requires the exact session, item, and fencing token; an old owner can never become valid again.

Idempotency

Every write carries Idempotency-Key. The server atomically creates a request fingerprint record:

  • same key and same body after completion: replay the stored status, headers, and body;
  • same key and different body: 409 idempotency_key_reused;
  • same request still running: retryable 409 idempotency_request_in_progress;
  • server-side failure before a stable result: the record is released for retry.

Records expire after 24 hours.