feat: add archive client foundation

2026-07-22 14:55:02 +00:00
commit c11a7b5b5b
39 changed files with 2985 additions and 0 deletions
@@ -0,0 +1,35 @@
+# Archive Clients
+
+One Python daemon runs as either an `archive` or `cache` node for Archive
+Control. Both roles use the same code and `sodium/archive-clients` image.
+
+The current foundation provides strict TOML configuration, file-backed secrets,
+API/local root mapping, fail-fast permission and sparse-file probes, a durable
+SQLite command inbox, bounded one-writer WebSocket output, registration-first
+authentication, heartbeat handling, duplicate-command acknowledgements, and
+indefinite capped exponential reconnect with optional jitter.
+
+```bash
+archive-client --config /etc/archive-control/client.toml --check-config
+archive-client --config /etc/archive-control/client.toml --mode archive
+```
+
+`--mode` accepts only `archive` or `cache` and overrides the configured role.
+Secrets must be regular files without group/world permissions. The daemon never
+stores them in SQLite or sends the shared token after registration.
+
+This foundation currently executes heartbeat and state-snapshot commands.
+Other mutation commands are durably rejected as unsupported until their
+service and file-operation executors are added; they are never falsely
+acknowledged as accepted.
+
+Run tests and build using containers:
+
+```bash
+docker build --target test -t archive-clients-test .
+docker run --rm archive-clients-test
+docker build -t sodium/archive-clients:dev .
+```
+
+Generated bindings are pinned to archive-control-proto commit
+`4ec852014dad74606d4078b3ae1aa208c814b033`.