archive-clients/README.md

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. The state DB has an exclusive process lease plus checksummed, integrity-verified online backups with recent/daily/weekly retention. Startup probes report qBittorrent/Web API/libtorrent versions, Syncthing version/device identity, service health, and per-root hardlink/reflink/sparse support without exposing local paths to control.

The first read-only discovery layer strictly decodes v1/v2/hybrid metainfo, derives canonical resource identities and selection ranges, builds lazy content trees, and reports only safe Syncthing folders below the configured root. Renamed/noncanonical torrent paths remain visible but are marked noncanonical so later job preflight can reject them without hiding the resource.

archive-client --config /etc/archive-control/client.toml --check-config
archive-client --config /etc/archive-control/client.toml --mode archive
archive-client-backup --database /var/lib/archive-control/client.db \
  --backup-dir /var/backups/archive-control list

--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:

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.