Mirror Snapshot Sync#

Mirror snapshot sync is the mechanism by which zerobyte retroactively copies existing snapshots from a primary backup repository into a mirror repository. It was introduced in PR #755 to address the gap where snapshots created before a mirror was added were never automatically propagated.

The feature exposes two backend endpoints 1:

• GET /backups/:shortId/mirrors/:mirrorShortId/status — enumerates and compares snapshots between the source and mirror repos, returning sourceCount, mirrorCount, and a missingSnapshots list.
• POST /backups/:shortId/mirrors/:mirrorShortId/sync — accepts an optional snapshotIds array and enqueues a background copy task.

Snapshot Enumeration Logic#

Status endpoint (getMirrorSyncStatus)#

getMirrorSyncStatus in backups.service.ts drives all snapshot discovery for the dialog. The key steps:

1. Resolves the schedule and mirror repository records from the database.
2. Calls restic.snapshots() concurrently for both the source and mirror repositories, filtering by the schedule's shortId as a tag 2.
3. Builds a Set of mirror snapshot timestamps and computes missingSnapshots as the source snapshots whose time field is absent from that set 3.
4. Returns { sourceCount, mirrorCount, missingSnapshots } — each missing entry includes short_id, time, and size (from summary.total_bytes_processed).

Critical detail: snapshots are matched by timestamp (s.time), not by snapshot ID. Two snapshots are considered equivalent if their time strings are equal.

Low-level restic snapshots command#

snapshots.ts in packages/core spawns restic snapshots --repo <url> --tag <scheduleShortId> --json and parses the output against snapshotInfoSchema 4. If the exit code is non-zero, the entire call throws and the status endpoint will fail. If Zod validation fails, it also throws — both paths surface as a ResticSnapshotsCommandError 5.

The --tag filter is the sole scoping mechanism: only snapshots tagged with the schedule's shortId are returned. Snapshots created outside zerobyte, or tagged differently, are invisible to this endpoint.

Frontend Dialog#

MirrorSyncDialog (mirror-sync-dialog.tsx) fetches sync status via getMirrorSyncStatusOptions as soon as a mirror is selected 6. The query is only enabled when mirror !== null 7.

Rendering paths:

All missing snapshots are not pre-selected by default — selectedSnapshotIds starts as an empty Set and is reset whenever the active mirrorShortId changes 8. The "Sync N snapshots" button stays disabled until at least one snapshot is checked 9.

On submit, the selected short_id values are sent as snapshotIds in the POST body 10.

Sync Execution#

startMirrorSync builds a MirrorSyncExecutionPlan and hands it to commands.createMirrorSync(plan).start(). The command implementation lives in mirror-sync-command.ts.

Inside executeMirrorSync, the command:

1. Sets task phase to "preparing".
2. Resolves the snapshotIds from the task store (allowing late binding after the task is queued).
3. Calls restic.copy() with --tag <scheduleShortId> scoping and optional per-snapshot IDs.
4. Optionally applies the schedule's retention policy after copy completes.

Both manual (user-initiated via UI) and post-backup (automatic, triggered after each scheduled backup) sync paths share this command. Post-backup syncs always carry a non-empty snapshotIds array; manual syncs may omit it to copy all missing snapshots 11.

Known Bug: Dialog Shows 0 Snapshots#

Issue #1139 (open as of 2026-09-03, zerobyte v0.42): the mirror sync dialog reports "Sync 0 snapshots" even when the source repository contains snapshots.

Observed setup: source = B2/S3 bucket, mirror = iCloud via rclone. The rclone config, /dev/fuse, and CAP_SYS_ADMIN were all verified working 12. Despite this, getMirrorSyncStatus returns sourceCount: 0 (inferred from empty missingSnapshots and the greyed-out button).

Most likely root causes to investigate:

1. Tag mismatch — restic.snapshots() filters strictly by --tag <scheduleShortId>. If existing source snapshots were created before the schedule's shortId was assigned or tagged differently, they will not appear. Confirm by running restic snapshots --repo <source-url> --json directly and checking the tags field on each snapshot.

2. restic snapshots exit code > 0 on the source repo — Any non-zero exit causes getMirrorSyncStatus to throw rather than return partial results 13. Check server logs for Restic snapshots retrieval failed messages.

3. Zod schema validation failure — If restic returns snapshot JSON with an unexpected shape (e.g., a missing required field), snapshotInfoSchema.array().safeParse() fails and the endpoint throws 14. Check for Restic snapshots output validation failed in logs.

4. rclone repo not yet initialised — If the iCloud repo has never been written to, restic snapshots against it may error. This would not directly affect source snapshot enumeration but can cause the concurrent Effect.all call to fail entirely 2, returning nothing for either side.

Key Files & Entry Points#