diff --git a/README.md b/README.md index 909cfac..833c6db 100644 --- a/README.md +++ b/README.md @@ -197,9 +197,10 @@ vaultik --version that cannot be restored when restoring, instead of aborting. Packing and storage errors while creating a snapshot (which would leave a chunk recorded but not stored) still abort the run. A run that skipped anything still - finishes but exits non-zero: `snapshot create` keeps the snapshot and counts - each file or directory it skipped as failed. A file removed during the backup - is also counted as failed but does not change the exit status. + finishes but exits `3` (see [exit status](#exit-status)): `snapshot create` + keeps the snapshot and counts each file or directory it skipped as failed. A + file removed during the backup is also counted as failed but does not change + the exit status. ### locking @@ -272,6 +273,19 @@ Every `--json` command therefore pipes on its own, with no additional flag: `vaultik snapshot list --json | jq .` and `vaultik prune --json | jq .` both work as written. +### exit status + +- `0`: the command succeeded. +- `1`: the command failed. +- `3`: `snapshot create` or `snapshot restore` finished, but `--skip-errors` + skipped files it could not read or restore. `restic backup` uses the same + status for this case. +- `130`: Ctrl-C, `SIGINT` or `SIGTERM` stopped the command. + +A cron job can page on `1` and only log `3`. A run that skipped files and also +failed in another way exits `1`. For example, a restore that skipped files and +was asked for a path the snapshot does not hold exits `1`. + ### environment variables - `VAULTIK_AGE_SECRET_KEY`: Age private key for decryption (required for @@ -345,25 +359,25 @@ In such a config, an unknown key or a value of the wrong type is refused. delete from the destination store what `prune` deletes there. By default keeps only the latest snapshot per name; use `--keep-newer-than` for a rolling window. When `--skip-errors` skipped a file or directory it could not read or - list, the prune does not run and every older snapshot is kept, since one of - them may be the only one that holds what was skipped; the command says so and - exits non-zero. When the backup found nothing in a configured path, as in the - mount point of a volume that is not mounted, the prune does not run either: - every older snapshot is kept, and the command names the path and exits - non-zero, on every run until the path holds something again. Take a path that - is empty on purpose out of the config, or remove the older snapshots by hand - with `snapshot purge`. When an earlier snapshot of the same name in the local - index found a volume mounted at or below a configured path (a directory on a - different filesystem from its parent, with an entry in it that the backup does - not exclude) and this backup does not, the prune does not run either: every - older snapshot is kept, and the command names the directory and exits - non-zero, on every run until the volume is mounted again. A backup also does - not find the volume when it finds no such entry in its directory, as when an - automounted volume cannot be mounted, or when that directory is no longer - backed up, because it is excluded or its configured path was removed. If any - of this is on purpose, as for a retired volume, remove the older snapshots by - hand with `snapshot purge`. A file removed during the backup does not stop the - prune. + list, the prune does not run and every older snapshot is kept. One of them may + be the only one that holds what was skipped. The command says so and exits + `3`. The prune does not run either when the backup found nothing in a + configured path, as in the mount point of a volume that is not mounted. Every + older snapshot is kept, and the command names the path and exits `1`, on every + run until the path holds something again. Take a path that is empty on purpose + out of the config, or remove the older snapshots by hand with + `snapshot purge`. The prune does not run either when this backup does not find + a volume that an earlier snapshot of the same name in the local index found. + The volume's mount point is a directory at or below a configured path. That + directory is on a different filesystem from its parent and holds an entry the + backup does not exclude. Every older snapshot is kept, and the command names + the directory and exits `1`, on every run until the volume is mounted again. A + backup also does not find the volume when it finds no such entry in its + directory, as when an automounted volume cannot be mounted. Nor does it find + the volume when that directory is no longer backed up, because it is excluded + or its configured path was removed. If any of this is on purpose, as for a + retired volume, remove the older snapshots by hand with `snapshot purge`. A + file removed during the backup does not stop the prune. - `--keep-newer-than `: With `--prune`, keep snapshots newer than this duration instead of only the latest (e.g. `4w`, `30d`, `6mo`, `1y`). Without `--prune`, or with a value that is not a valid duration, the command fails diff --git a/internal/cli/app.go b/internal/cli/app.go index e264bc8..9087020 100644 --- a/internal/cli/app.go +++ b/internal/cli/app.go @@ -198,7 +198,8 @@ func RunApp(ctx context.Context, app *fx.App) error { // (or, under `snapshot verify --json`, put in its document). Entry // turns it into a non-zero exit status without printing anything // further, so the error line is not doubled. It flows up from -// RunOperation through cobra to Entry. +// RunOperation through cobra to Entry, wrapping the operation's error +// so that Entry can choose the exit status from it. var errReported = errors.New("operation failed") // errInterrupted marks an operation that SIGINT or SIGTERM stopped @@ -232,8 +233,8 @@ func RunOperation( ) error { var ( mu sync.Mutex - finished bool // op returned before any interrupt cancelled it - failed bool // op finished with an error + finished bool // op returned before any interrupt cancelled it + opErr error // what op returned, when it finished ) opts.Invokes = append(opts.Invokes, @@ -258,7 +259,7 @@ func RunOperation( mu.Lock() finished = true - failed = err != nil + opErr = err mu.Unlock() } @@ -303,8 +304,8 @@ func RunOperation( switch { case !finished: return errInterrupted - case failed: - return errReported + case opErr != nil: + return fmt.Errorf("%w: %w", errReported, opErr) default: return nil } diff --git a/internal/cli/entry.go b/internal/cli/entry.go index d332071..b9d8038 100644 --- a/internal/cli/entry.go +++ b/internal/cli/entry.go @@ -9,6 +9,7 @@ import ( "sneak.berlin/go/vaultik/internal/globals" "sneak.berlin/go/vaultik/internal/ui" + "sneak.berlin/go/vaultik/internal/vaultik" ) // shortCommitLen is the number of git commit hash characters shown in @@ -20,6 +21,13 @@ const shortCommitLen = 12 // shell reports for a command stopped by Ctrl-C. const exitCodeInterrupted = 130 +// exitCodeSkippedFiles is the exit status of a `snapshot create` or +// `snapshot restore` that finished but skipped files under +// --skip-errors. It is the status `restic backup` uses for a snapshot +// that could not read some files, so a cron job can tell such a run +// from one that made no backup. +const exitCodeSkippedFiles = 3 + // Entry is the main entry point for the CLI application. // It first calls globals.FillUnsetFromBuildInfo, which fills in the // version, commit and commit date that the linker flags did not set. @@ -30,8 +38,9 @@ const exitCodeInterrupted = 130 // The banner goes to stderr because stdout carries only the output the // user asked for, such as a completion script or a `config get` value. // -// It returns the process exit code (0 on success, 130 when interrupted, -// 1 on any other error) rather than calling os.Exit, so that main's +// It returns the process exit code (0 on success, 3 when files were +// skipped, 130 when interrupted, 1 on any other error) rather than +// calling os.Exit, so that main's // deferred profile writers run before the process ends. See run in // cmd/vaultik/main.go. func Entry() int { @@ -58,6 +67,11 @@ func Entry() int { return exitCodeInterrupted } + if errors.Is(err, vaultik.ErrFilesUnreadable) || + errors.Is(err, vaultik.ErrFilesFailedRestore) { + return exitCodeSkippedFiles + } + return 1 } diff --git a/internal/cli/entry_skip_errors_exit_status_test.go b/internal/cli/entry_skip_errors_exit_status_test.go new file mode 100644 index 0000000..567a44b --- /dev/null +++ b/internal/cli/entry_skip_errors_exit_status_test.go @@ -0,0 +1,83 @@ +package cli //nolint:testpackage // shares runEntry and the hermetic config helpers + +import ( + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const flagSkipErrors = "--skip-errors" + +// TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips backs up, +// under --skip-errors, a source directory that does not exist, which the +// walk skips. The command exits with exitCodeSkippedFiles and reports +// the backup as completed, not as a failed snapshot creation. See +// https://git.eeqj.de/sneak/vaultik/issues/310 and +// https://git.eeqj.de/sneak/vaultik/issues/439. +// +//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals +func TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips(t *testing.T) { + // writeBackupConfig would create the source directory. + configPath := writeHermeticPruneConfig(t, false) + + code, stdout, stderr := runEntry(t, + flagConfig, configPath, flagSkipErrors, cmdSnapshot, cmdCreate) + + assert.Equal(t, exitCodeSkippedFiles, code) + assert.Contains(t, stdout, + "Files: 1 examined, 0 backed up, 0 unchanged, 1 failed.") + assert.NotContains(t, stdout, "Finished successfully.") + assert.Contains(t, stderr, + "Backup completed, but 1 file(s) could not be read") + assert.NotContains(t, stderr, "Snapshot creation failed") +} + +// TestEntrySnapshotRestoreSkipErrorsExitStatus backs up, deletes the +// blobs from the destination, and restores under --skip-errors, so every +// file is skipped. A restore that only skipped files exits with +// exitCodeSkippedFiles. One that was also asked for a path the snapshot +// does not hold exits 1. See +// https://git.eeqj.de/sneak/vaultik/issues/439. +// +//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals +func TestEntrySnapshotRestoreSkipErrorsExitStatus(t *testing.T) { + for _, testCase := range []struct { + name string + missingPaths []string + want int + }{ + {name: "skipped files only", want: exitCodeSkippedFiles}, + { + name: "and a path that matches nothing", + missingPaths: []string{"/no/such/path"}, + want: 1, + }, + } { + t.Run(testCase.name, func(t *testing.T) { + configPath, storeDir := writeBackupConfigWithPrivateKey(t) + + code, _, _ := runEntry(t, + flagConfig, configPath, cmdSnapshot, cmdCreate) + require.Equal(t, 0, code) + + require.NoError(t, os.RemoveAll(filepath.Join(storeDir, blobsDir))) + + // writeBackupConfig puts the source directory beside the + // config file. + sourceDir := filepath.Join(filepath.Dir(configPath), "source") + args := append([]string{ + flagConfig, configPath, flagSkipErrors, cmdSnapshot, + cmdRestore, onlySnapshotID(t, configPath), t.TempDir(), + sourceDir, + }, testCase.missingPaths...) + + code, _, stderr := runEntry(t, args...) + + assert.Equal(t, testCase.want, code) + assert.Contains(t, stderr, "1 file(s) failed to restore") + }) + } +} diff --git a/internal/cli/entry_snapshot_create_skip_errors_test.go b/internal/cli/entry_snapshot_create_skip_errors_test.go deleted file mode 100644 index e52491d..0000000 --- a/internal/cli/entry_snapshot_create_skip_errors_test.go +++ /dev/null @@ -1,30 +0,0 @@ -package cli //nolint:testpackage // shares runEntry and the hermetic config helpers - -import ( - "testing" - - "github.com/stretchr/testify/assert" -) - -// TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips backs up, -// under --skip-errors, a source directory that does not exist, which the -// walk skips. The command exits non-zero and reports the backup as -// completed, not as a failed snapshot creation. See -// https://git.eeqj.de/sneak/vaultik/issues/310. -// -//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals -func TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips(t *testing.T) { - // writeBackupConfig would create the source directory. - configPath := writeHermeticPruneConfig(t, false) - - code, stdout, stderr := runEntry(t, - flagConfig, configPath, "--skip-errors", cmdSnapshot, cmdCreate) - - assert.Equal(t, 1, code) - assert.Contains(t, stdout, - "Files: 1 examined, 0 backed up, 0 unchanged, 1 failed.") - assert.NotContains(t, stdout, "Finished successfully.") - assert.Contains(t, stderr, - "Backup completed, but 1 file(s) could not be read") - assert.NotContains(t, stderr, "Snapshot creation failed") -} diff --git a/internal/vaultik/restore.go b/internal/vaultik/restore.go index 8855aeb..c01d257 100644 --- a/internal/vaultik/restore.go +++ b/internal/vaultik/restore.go @@ -25,9 +25,13 @@ import ( "sneak.berlin/go/vaultik/internal/types" ) +// ErrFilesFailedRestore is returned when --skip-errors skipped files the +// restore could not write. Every other file was restored, so the caller +// can report it apart from a failed restore. +var ErrFilesFailedRestore = errors.New("file(s) failed to restore") + // Sentinel errors for restore failures. var ( - errFilesFailedRestore = errors.New("file(s) failed to restore") errPathsNotInSnapshot = errors.New("requested path(s) not in the snapshot") errFilesFailedVerify = errors.New("files failed verification") errDecryptionKeyRequired = errors.New( @@ -201,9 +205,9 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error { } // finishRestore prints the restore summary and the post-restore -// warnings, runs optional verification, and converts any failed-file -// count into an error. Otherwise it returns unmatchedErr, the error for -// the requested paths that matched nothing (nil when there are none). +// warnings, runs optional verification, and returns the error the +// restore ends with: one for the files --skip-errors skipped, one for +// unmatchedErr, the requested paths that matched nothing, or nil. func (v *Vaultik) finishRestore( repos *database.Repositories, files []*database.File, @@ -250,11 +254,18 @@ func (v *Vaultik) finishRestore( } } - if result.FilesFailed > 0 { - return fmt.Errorf("%d %w", result.FilesFailed, errFilesFailedRestore) + switch { + case result.FilesFailed > 0 && unmatchedErr != nil: + // A requested path that matched nothing outweighs skipped files: + // the error wraps only unmatchedErr, so the command does not exit + // as a restore that only skipped files. + return fmt.Errorf("%w; %d %s", + unmatchedErr, result.FilesFailed, ErrFilesFailedRestore.Error()) + case result.FilesFailed > 0: + return fmt.Errorf("%d %w", result.FilesFailed, ErrFilesFailedRestore) + default: + return unmatchedErr } - - return unmatchedErr } // warnIfOwnershipNotPreserved warns once if some entry restored under diff --git a/internal/vaultik/restore_sweeper_test.go b/internal/vaultik/restore_sweeper_test.go index 1f767f3..d06331f 100644 --- a/internal/vaultik/restore_sweeper_test.go +++ b/internal/vaultik/restore_sweeper_test.go @@ -80,7 +80,7 @@ func TestRestoreFreesBlobsNoPendingFileNeeds(t *testing.T) { TargetDir: restoreDir, SkipErrors: true, }) - require.ErrorIs(t, err, errFilesFailedRestore) + require.ErrorIs(t, err, ErrFilesFailedRestore) requireRestoredFiles(t, fs, restoreDir, originals) assert.LessOrEqualf(t, peak, 1, diff --git a/internal/vaultik/snapshot.go b/internal/vaultik/snapshot.go index 9bef3eb..bc54e63 100644 --- a/internal/vaultik/snapshot.go +++ b/internal/vaultik/snapshot.go @@ -49,8 +49,7 @@ var ErrFilesUnreadable = errors.New("file(s) could not be read") // prune because the scan found nothing in a configured path of a // snapshot, as in the mount point of a volume that is not mounted. The // snapshots are complete and kept, so the caller can report it apart -// from a failed backup. A run that also skipped unreadable files -// returns ErrFilesUnreadable instead. +// from a failed backup. var ErrSourcePathEmpty = errors.New("source path(s) were empty") // ErrVolumeNotMounted is returned when --prune skipped the post-backup @@ -59,8 +58,8 @@ var ErrSourcePathEmpty = errors.New("source path(s) were empty") // mounted there is not mounted, the run found no entry in it, or the // directory is no longer backed up. The snapshots are complete and // kept, so the caller can report it apart from a failed backup. A run -// that also skipped unreadable files or found a configured path empty -// returns ErrFilesUnreadable or ErrSourcePathEmpty instead. +// that also found a configured path empty returns ErrSourcePathEmpty +// instead. var ErrVolumeNotMounted = errors.New( "mount point(s) an earlier snapshot recorded were not found") @@ -243,15 +242,29 @@ func (v *Vaultik) skipPostBackupPrune( if filesUnreadable > 0 { v.UI.Warningf("Skipped the post-backup prune because %d file(s) "+ "could not be read; older snapshots are kept.", filesUnreadable) + } + var err error + + switch { + case len(emptyPaths) > 0: + err = fmt.Errorf("%d %w", len(emptyPaths), ErrSourcePathEmpty) + case len(unmountedPaths) > 0: + err = fmt.Errorf("%d %w", len(unmountedPaths), ErrVolumeNotMounted) + default: return fmt.Errorf("%d %w", filesUnreadable, ErrFilesUnreadable) } - if len(emptyPaths) > 0 { - return fmt.Errorf("%d %w", len(emptyPaths), ErrSourcePathEmpty) + // An empty path or a missing volume can mean a whole volume is not + // in the backup, which outweighs skipped files: the error wraps only + // the former, so the command does not exit as a backup that only + // skipped files. + if filesUnreadable > 0 { + return fmt.Errorf("%w; %d %s", + err, filesUnreadable, ErrFilesUnreadable.Error()) } - return fmt.Errorf("%d %w", len(unmountedPaths), ErrVolumeNotMounted) + return err } // finishCreateSnapshot ends a run whose snapshots are all complete and diff --git a/internal/vaultik/snapshot_prune_test.go b/internal/vaultik/snapshot_prune_test.go index e0e2e49..35a080b 100644 --- a/internal/vaultik/snapshot_prune_test.go +++ b/internal/vaultik/snapshot_prune_test.go @@ -176,8 +176,11 @@ func TestBackupThroughSymlinkWhoseTargetIsGoneDoesNotPrune(t *testing.T) { // A backup under --skip-errors --prune that both skipped a file it could // not read and found nothing in a configured path names the empty path -// too when it skips the prune. See -// https://git.eeqj.de/sneak/vaultik/issues/388. +// too when it skips the prune. It ends with the empty path's error, which +// names the unreadable file too but does not wrap ErrFilesUnreadable, so +// the command does not exit as a backup that only skipped files. See +// https://git.eeqj.de/sneak/vaultik/issues/388 and +// https://git.eeqj.de/sneak/vaultik/issues/439. func TestBackupWithEmptySourcePathAndUnreadableFileNamesBoth(t *testing.T) { log.Initialize(log.Config{}) t.Parallel() @@ -207,7 +210,10 @@ func TestBackupWithEmptySourcePathAndUnreadableFileNamesBoth(t *testing.T) { SkipErrors: true, Snapshots: []string{snapshotName}, }) - require.ErrorIs(t, err, vaultik.ErrFilesUnreadable) + require.ErrorIs(t, err, vaultik.ErrSourcePathEmpty) + require.NotErrorIs(t, err, vaultik.ErrFilesUnreadable) + require.EqualError(t, err, + "1 source path(s) were empty; 1 file(s) could not be read") assert.Contains(t, env.out.String(), "Skipped the post-backup prune because 1 file(s) could not be read") assert.Contains(t, env.out.String(),