forked from longtao.wu/droboticflow
51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# 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.
|
|
|
|
```mermaid
|
|
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.
|