How the protocol works

1 · A tree built from metadata, not contents

Each file's hash is sha256(size : mtime-seconds), derived from stat() alone, so building the tree reads no file data. A directory's hash is the hash of its sorted child name:hash lines. This makes the whole tree a Merkle hash: two directories share a hash iff every file beneath them has identical size and timestamp. Empty directories and dotfiles are omitted, so the two sides always describe the same thing.

2 · Compare the root, then descend only where it differs

3 · Why it stays correct and cheap

• No caches anywhere. Hashes are recomputed from stat() each run, on both sides. The client is stateless; the server keeps nothing, even after a restart the recomputed hashes still match, because the upload preserved the timestamps.
• Quick-check semantics. Like rsync's default, a change is detected by a difference in size or whole-second mtime. Editing a file updates its mtime, so real edits are always caught.
• One small surface. A bearer token guards every call; there is no dashboard, login, session, or cookie to attack.
• Status codes say nothing. Every authenticated call returns 200 with an object, even "that path is absent". Anything else returns an identical 404, so a probe can't tell an API is there at all.
• Versioned, so skew is loud. The routes are /api/v1/…; a version mismatch hits the 404, then the client checks GET /api/version to say "upgrade the client" instead of failing silently.

4 · Access logs, mirrored incrementally

Caddy writes one rotating access log. The client mirrors it by timestamp, GET /api/v1/logs lists sizes and rotated-file timestamps; GET /api/v1/logs/file?which=active fetches only the newly-appended tail via an HTTP Range. A new rotated file signals the active log restarted. Filenames never cross the wire, so the server can't influence where the client writes.

The endpoints