8.5 KiB
Architecture and state machines
Components
- The Rust daemon exclusively owns scheduling and the local SQLite journal. CLI uses a
0600Unix socket or the sole Windows named pipe for the selected supported installation mode. - The Go API authenticates a device credential, enforces scope/quota/idempotency, accepts paged manifests, creates leases, and issues MD5-bound, conditional upload URLs for the final business key.
drosync-coordinatoratomically claims Mongo work across replicas. It plans items, verifies fencing tokens and uploaded-object ownership, finalizes receipts, reconciles tracked heads, cleans abandoned staging when present, and writes immutable release manifests.- 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 sole operation entry"] -->|"local IPC"| D
D -->|"manifest, lease, commit"| A["Go control-plane API"]
D -->|"MD5-bound conditional PUT / multipart"| B["BOS business prefix"]
A --> M["MongoDB"]
Q["drosync-coordinator"] --> M
Q -->|"verify uploaded object"| B
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.
Upload scheduling and local state
The daemon runs at most four distinct mappings, one execution per mapping. By default, process-wide semaphores bound active files and BOS PUTs at four each; a single multipart object uses at most four. Configuration can change these limits without multiplying them across mappings. Control requests and 30-second session lease heartbeats have separate capacity. Directory notifications are bounded/coalesced; temporary events cannot indefinitely postpone stable files, and failed watchers are retried.
Scanning computes the complete MD5 and per-part MD5 in one stream. Each PUT verifies the bytes actually sent before completion. Unix identity includes device/inode, ctime/mtime nanoseconds and size; only an exact identity match reuses cached digests. Windows performs a new scan hash. Old unverifiable upload journals are explicitly aborted and rescanned, rather than resumed under stale evidence.
SQLite schema 7 uses keyset scan pagination and an indexed latest-state projection. Reports look up only the files being inspected and validate their saved identity. Opening a current schema does not rerun or write schema migration; write transactions acquire their lock before reading to avoid deferred transaction upgrade races. Derived source caches are swept only after a complete successful scan.
Commit progress and counters
Waiting polls /sessions/{sessionId}/status, not the full item list. Mongo materializes progress per manifest page, with before/after invalidation, revision compare-and-swap, a 60-second freshness bound and recovery of cold caches. Hot polls read the cache; dirty-page aggregation uses the covering sessionId_page_status_action index. This is a rebuildable progress cache, not an atomic incremental counter.
The completion endpoint independently reconciles authoritative item state and persists the final counts with a guarded session transition. A cache race suppresses all-terminal hints, and aggregation errors never become successful completion. Cold reconstruction, periodic calibration and final reconciliation still cost O(N). The item list uses the separate (sessionId,id) index; the client reads final details once for local receipts.
Coordinator planning, commit, cleanup, reconcile, release and audit run in independent stages. Planning has at most 16 parallel probes. Four continuously refilled commit workers and two cleanup workers prevent a slow object from holding the whole batch. A planning claim leaves the session in planning until the complete plan is saved using its claim token.
The platform exposes paginated cloud management; the local CLI exposes paginated local diagnostics. The old platform daily report and administrator abort entry are removed. Cancellation uses the CLI and stops local work before confirming remote termination. Late API writes cannot restore a cancelled state or overwrite a committed receipt.
Deploy the API/coordinator and indexes before the 1.0.7 client. Capabilities must advertise features.sessionHeartbeat=true, features.previewSessions=true and features.credentialActivation=true, features.metadataRecovery=true, features.missingFileSkip=true; absence fails explicitly without a legacy heartbeat or item-list fallback. Control budgets are device-scoped and distinguish reads, writes and liveness requests. Errors obey Retry-After and retries preserve their idempotency key and body.
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. Session heartbeats renew only leases still owned by that session. Coordinator work also has a unique token per acquisition, periodic renewal and conditional final persistence; an expired acquisition cannot write after a later one claims the same work.
BOS publication and Mongo receipts are separate systems, not one atomic transaction. Conditional publication and reconciliation remain necessary when the network or process fails between them. Cancelling cannot undo an object whose publication already completed.
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.
Current end-to-end user workflows and remaining real-environment gates: 1.0.6 closure manual.
Authentication, preview and update recovery
Auth is daemon-owned and uses activation-v1: prepare a pending credential without revoking the current token, persist protected credential/checkpoint, activate, then clear temporary state. Activation retries of an already active token are no-ops; they cannot erase a later pending authentication. SQLite binds the exact server, credential authority, device and credential location. Cross-identity changes with mapped/active work are refused. DROSYNC_TOKEN overrides are unsupported.
Preview uses a separate journal and a server-side preview Session. Planning and metadata reads are allowed; reserve/upload/commit are rejected. Preview success requires confirmed remote abort and never replaces committed-file receipts. Loss of local records is recovered via credential/device-scoped Session discovery, not a platform admin-abort alias.
Client update v2 signs immutable artifact identity separately from rollout. Registration is insert-only; policy updates use an ownership/revision CAS. The daemon update ledger is transactional and includes a verified rollback baseline. CLI confirms target binary identity/readiness or invokes bounded verified recovery. See the update document for schema gates and first-install trust.
1.0.6 metadata, timeout and BOS recovery changes: repair and verification.
1.0.7 introduces sampled per-file progress, bounded global file/PUT concurrency, parallel source hashing, literal runtime configuration, explicit missing-source skips and cloud-verified local cleanup. See the V1.1 traceability record.