Fail restore for a requested path that matches nothing (closes #309)

snapshot restore said nothing about a requested path that matched no
entry in the snapshot (a typo, a relative path, or a path through a
configured snapshot path that is a symlink, whose entries are stored
under the resolved directory) and exited 0, also when nothing matched
at all. Each such path is now named in a warning, and restore returns
an error after restoring the paths that do match.

Making a path through a symlink match is not part of this change.
Judgement call: when files also fail to restore, that error is the one
returned; the unmatched paths are still named.

Model: opus-5-5

README.md

@@ -372,7 +372,9 @@ on the destination in one go, use `vaultik remote nuke --force`.
   store — its remote key (or an unambiguous leading part of it) as shown
   by `snapshot list`. See
   [restoring on another machine](#restoring-on-another-machine).
-* Optional path arguments to restore specific files/directories (default: all)
+* Optional path arguments to restore specific files/directories (default: all).
+  A path that matches nothing in the snapshot is named in a warning, and the
+  command exits non-zero after restoring the paths that match
 * Preserves file permissions, timestamps, ownership (ownership requires root),
   symlinks, and empty directories
 * `--verify`: After restoring, verify every file's chunk hashes match

internal/cli/snapshot_restore.go

@@ -30,6 +30,8 @@ This command will restore files from the specified snapshot to the
 target directory.
 If no paths are specified, all files are restored.
 If paths are specified, only matching files/directories are restored.
+A path that matches nothing in the snapshot is named in a warning, and
+the command exits non-zero after restoring the paths that match.
 
 The snapshot may be named by its ID or, when restoring on a host with no
 local index, by the remote key that 'snapshot list' prints for a

internal/vaultik/restore.go

@@ -27,6 +27,7 @@ import (
 // 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(
 		"decryption key required for restore\n\n" +
@@ -149,7 +150,7 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 	repos := database.NewRepositories(tempDB)
 
 	// Step 2: Get list of files to restore
-	files, err := v.getFilesToRestore(v.ctx, repos, opts.Paths)
+	files, unmatched, err := v.getFilesToRestore(v.ctx, repos, opts.Paths)
 	if err != nil {
 		return fmt.Errorf("getting files to restore: %w", err)
 	}
@@ -158,7 +159,7 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 		log.Warn("No files found to restore")
 		v.UI.Warningf("No files found to restore.")
 
-		return nil
+		return v.reportUnmatchedPaths(unmatched)
 	}
 
 	log.Info("Found files to restore", "count", len(files))
@@ -198,14 +199,16 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 		v.UI.Duration(result.Duration),
 	)
 
-	return v.finishRestore(repos, files, opts, result)
+	return v.finishRestore(repos, files, unmatched, opts, result)
 }
 
 // finishRestore emits the post-restore warnings, runs optional
-// verification, and converts any failed-file count into an error.
+// verification, and converts any failed-file count or requested path
+// that matched nothing into an error.
 func (v *Vaultik) finishRestore(
 	repos *database.Repositories,
 	files []*database.File,
+	unmatched []string,
 	opts *RestoreOptions,
 	result *RestoreResult,
 ) error {
@@ -223,6 +226,8 @@ func (v *Vaultik) finishRestore(
 		}
 	}
 
+	unmatchedErr := v.reportUnmatchedPaths(unmatched)
+
 	// Run verification if requested
 	if opts.Verify {
 		err := v.handleRestoreVerification(repos, files, opts, result)
@@ -235,7 +240,23 @@ func (v *Vaultik) finishRestore(
 		return fmt.Errorf("%d %w", result.FilesFailed, errFilesFailedRestore)
 	}
 
-	return nil
+	return unmatchedErr
+}
+
+// reportUnmatchedPaths warns, by name, about each requested path that
+// matched nothing in the snapshot, and returns an error counting them,
+// or nil when there are none.
+func (v *Vaultik) reportUnmatchedPaths(unmatched []string) error {
+	if len(unmatched) == 0 {
+		return nil
+	}
+
+	for _, path := range unmatched {
+		log.Warn("Requested path matches nothing in the snapshot", "path", path)
+		v.UI.Warningf("%s matches nothing in the snapshot.", v.UI.Path(path))
+	}
+
+	return fmt.Errorf("%d %w", len(unmatched), errPathsNotInSnapshot)
 }
 
 // restoreIdentities parses the configured age secret key once into every
@@ -309,22 +330,11 @@ func (v *Vaultik) restoreAllFiles(
 		return nil, err
 	}
 
-	plan, unplanned, err := newRestorePlan(
-		v.ctx, repos, files, chunkToBlobMap, blobIDToHash)
+	plan, err := newRestorePlan(v.ctx, repos, files, chunkToBlobMap, blobIDToHash)
 	if err != nil {
 		return nil, fmt.Errorf("building restore plan: %w", err)
 	}
 
-	// Ranging over files rather than the map reports them in a stable order.
-	for _, file := range files {
-		if planErr, ok := unplanned[file.ID]; ok {
-			err = v.handleRestoreFileError(plan, opts, result, file, file.ID, planErr)
-			if err != nil {
-				return nil, err
-			}
-		}
-	}
-
 	filesByID, totalBytesExpected := indexRestoreFiles(files)
 
 	v.UI.Beginf("Restoring %s files (%s) to %s.",
@@ -823,27 +833,34 @@ func (v *Vaultik) materializeSnapshotDB(
 	return db, tempDir, nil
 }
 
-// getFilesToRestore returns the list of files to restore based on path filters
+// getFilesToRestore returns the list of files to restore based on path
+// filters, and the filters, as given, that matched no file.
 func (v *Vaultik) getFilesToRestore(
 	ctx context.Context, repos *database.Repositories, pathFilters []string,
-) ([]*database.File, error) {
+) ([]*database.File, []string, error) {
 	// If no filters, get all files
 	if len(pathFilters) == 0 {
-		return repos.Files.ListAll(ctx)
+		files, err := repos.Files.ListAll(ctx)
+
+		return files, nil, err
 	}
 
 	// Get files matching the path filters
-	var result []*database.File
+	var (
+		result    []*database.File
+		unmatched []string
+	)
 
 	seen := make(map[string]bool)
 
 	for _, filter := range pathFilters {
-		// Normalize the filter path
-		filter = filepath.Clean(filter)
-
-		files, err := repos.Files.ListUnderPath(ctx, filter)
+		files, err := repos.Files.ListUnderPath(ctx, filepath.Clean(filter))
 		if err != nil {
-			return nil, fmt.Errorf("listing files under %s: %w", filter, err)
+			return nil, nil, fmt.Errorf("listing files under %s: %w", filter, err)
+		}
+
+		if len(files) == 0 {
+			unmatched = append(unmatched, filter)
 		}
 
 		for _, file := range files {
@@ -854,7 +871,7 @@ func (v *Vaultik) getFilesToRestore(
 		}
 	}
 
-	return result, nil
+	return result, unmatched, nil
 }
 
 // buildChunkToBlobMap creates a mapping from chunk hash to blob information

internal/vaultik/restore_malformed_db_test.go

@@ -61,8 +61,8 @@ func craftedFile(
 }
 
 // TestRestoreShortChunkHashInNoBlob proves a file whose short chunk hash
-// has no blob_chunks row is left out of the restore plan with an error,
-// and fails the chunk write with an error.
+// has no blob_chunks row fails restore planning and the chunk write with
+// an error.
 func TestRestoreShortChunkHashInNoBlob(t *testing.T) {
 	t.Parallel()
 
@@ -77,11 +77,9 @@ func TestRestoreShortChunkHashInNoBlob(t *testing.T) {
 	chunkToBlobMap, err := v.buildChunkToBlobMap(ctx, repos)
 	require.NoError(t, err)
 
-	plan, unplanned, err := newRestorePlan(ctx, repos, []*database.File{file},
+	_, err = newRestorePlan(ctx, repos, []*database.File{file},
 		chunkToBlobMap, map[string]string{})
-	require.NoError(t, err)
-	require.ErrorIs(t, unplanned[file.ID], errPlanChunkMissing)
-	require.False(t, plan.hasPending())
+	require.ErrorIs(t, err, errPlanChunkMissing)
 
 	fileChunks, err := repos.FileChunks.GetByFileID(ctx, file.ID)
 	require.NoError(t, err)

internal/vaultik/restore_plan.go

@@ -41,25 +41,20 @@ type restorePlan struct {
 
 // newRestorePlan builds the file→blob index for the given files. Files
 // whose chunks reference no blobs (symlinks, directories) start in the
-// ready queue immediately. A file with a chunk that no blob holds cannot
-// be restored: it is left out of the plan and returned, by ID, with the
-// reason.
+// ready queue immediately.
 func newRestorePlan(
 	ctx context.Context,
 	repos *database.Repositories,
 	files []*database.File,
 	chunkToBlobMap map[string]*database.BlobChunk,
 	blobIDToHash map[string]string,
-) (*restorePlan, map[types.FileID]error, error) {
+) (*restorePlan, error) {
 	p := &restorePlan{
 		fileBlobs: make(map[types.FileID]map[string]struct{}, len(files)),
 		blobFiles: make(map[string]map[types.FileID]struct{}),
 		ready:     make([]types.FileID, 0, len(files)),
 		cached:    make(map[string]struct{}),
 	}
-	unplanned := make(map[types.FileID]error)
-
-nextFile:
 	for _, f := range files {
 		if f.IsSymlink() || f.Mode&uint32(os.ModeDir) != 0 {
 			// No chunks to fetch — restore can run immediately.
@@ -71,7 +66,7 @@ nextFile:
 
 		fileChunks, err := repos.FileChunks.GetByFileID(ctx, f.ID)
 		if err != nil {
-			return nil, nil, fmt.Errorf("planning %s: %w", f.Path, err)
+			return nil, fmt.Errorf("planning %s: %w", f.Path, err)
 		}
 
 		blobs := make(map[string]struct{})
@@ -79,18 +74,14 @@ nextFile:
 		for _, fc := range fileChunks {
 			bc, ok := chunkToBlobMap[fc.ChunkHash.String()]
 			if !ok {
-				unplanned[f.ID] = fmt.Errorf("%w: %s",
-					errPlanChunkMissing, shortHash(fc.ChunkHash.String()))
-
-				continue nextFile
+				return nil, fmt.Errorf("planning %s: %w: %s",
+					f.Path, errPlanChunkMissing, shortHash(fc.ChunkHash.String()))
 			}
 
 			hash, ok := blobIDToHash[bc.BlobID.String()]
 			if !ok {
-				unplanned[f.ID] = fmt.Errorf("%w: %s",
-					errPlanBlobIDMissing, bc.BlobID)
-
-				continue nextFile
+				return nil, fmt.Errorf("planning %s: %w: %s",
+					f.Path, errPlanBlobIDMissing, bc.BlobID)
 			}
 
 			blobs[hash] = struct{}{}
@@ -112,7 +103,7 @@ nextFile:
 		}
 	}
 
-	return p, unplanned, nil
+	return p, nil
 }
 
 // markBlobCached records that the named blob is now resident in the

internal/vaultik/restore_skip_errors_test.go

@@ -28,8 +28,7 @@ const (
 )
 
 // missingBlobBackup is a snapshot of single-chunk files spread over two
-// blobs, with one of those blobs lost: deleted from the store, or missing
-// from the snapshot metadata.
+// blobs, with one of those blobs deleted from the store.
 type missingBlobBackup struct {
 	fs         afero.Fs
 	cfg        *config.Config
@@ -38,39 +37,20 @@ type missingBlobBackup struct {
 	restoreDir string
 	// files holds the original content by source path.
 	files map[string][]byte
-	// lost holds the source paths whose chunk is in the lost blob.
+	// lost holds the source paths whose chunk is in the deleted blob.
 	lost map[string]bool
 }
 
 // TestRestoreSkipErrorsSkipsFilesOfMissingBlob restores with SkipErrors
-// after one blob of a two-blob snapshot was deleted from the store.
+// after one blob of a two-blob snapshot was deleted. Every file stored in
+// that blob must be reported as failed and left absent, every other file
+// must be restored intact, and Restore must still return an error.
 func TestRestoreSkipErrorsSkipsFilesOfMissingBlob(t *testing.T) {
 	log.Initialize(log.Config{})
 	t.Parallel()
 
 	ctx := context.Background()
-	assertRestoreSkipsLostFiles(ctx, t, backupThenDeleteOneBlob(ctx, t))
-}
-
-// TestRestoreSkipErrorsSkipsFilesWithChunkInNoBlob restores with
-// SkipErrors a snapshot whose metadata lists chunks that no blob holds, as
-// earlier backup defects left behind.
-func TestRestoreSkipErrorsSkipsFilesWithChunkInNoBlob(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	ctx := context.Background()
-	assertRestoreSkipsLostFiles(ctx, t, backupThenDropOneBlobFromMetadata(ctx, t))
-}
-
-// assertRestoreSkipsLostFiles restores backup with SkipErrors. Every file
-// stored in the lost blob must be reported as failed and left absent,
-// every other file must be restored intact, and Restore must still return
-// an error.
-func assertRestoreSkipsLostFiles(
-	ctx context.Context, t *testing.T, backup *missingBlobBackup,
-) {
-	t.Helper()
+	backup := backupThenDeleteOneBlob(ctx, t)
 
 	var out bytes.Buffer
 
@@ -92,14 +72,14 @@ func assertRestoreSkipsLostFiles(
 
 		if backup.lost[path] {
 			assert.Containsf(t, out.String(), path,
-				"%s needs the lost blob and must be reported", path)
+				"%s needs the deleted blob and must be reported", path)
 			assert.NoFileExists(t, restored)
 
 			continue
 		}
 
 		got, err := afero.ReadFile(backup.fs, restored)
-		require.NoErrorf(t, err, "%s does not need the lost blob", path)
+		require.NoErrorf(t, err, "%s does not need the deleted blob", path)
 		assert.Equalf(t, content, got, "%s restored with wrong content", path)
 	}
 }
@@ -123,30 +103,6 @@ func TestRestoreMissingBlobAbortsWithoutSkipErrors(t *testing.T) {
 	require.ErrorIs(t, err, storage.ErrNotFound)
 }
 
-// TestRestoreChunkInNoBlobAbortsWithoutSkipErrors checks that a chunk held
-// by no blob still ends the restore, before any file is written, when
-// SkipErrors is not set.
-func TestRestoreChunkInNoBlobAbortsWithoutSkipErrors(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	ctx := context.Background()
-	backup := backupThenDropOneBlobFromMetadata(ctx, t)
-
-	v := newReaderVaultik(ctx, backup.cfg, backup.storer, nil, backup.fs)
-
-	err := v.Restore(&vaultik.RestoreOptions{
-		SnapshotID: backup.snapshotID,
-		TargetDir:  backup.restoreDir,
-	})
-
-	require.ErrorContains(t, err, "chunk missing from blob map")
-
-	for path := range backup.files {
-		assert.NoFileExists(t, filepath.Join(backup.restoreDir, path))
-	}
-}
-
 // backupThenDeleteOneBlob backs up missingBlobFileCount single-chunk
 // files, then deletes from the store the blob holding the first of them.
 func backupThenDeleteOneBlob(
@@ -154,54 +110,6 @@ func backupThenDeleteOneBlob(
 ) *missingBlobBackup {
 	t.Helper()
 
-	backup, db, lostBlob := backupSingleChunkFiles(ctx, t)
-	require.NoError(t, db.Close())
-
-	require.NoError(t, backup.storer.Delete(ctx, fmt.Sprintf(
-		"blobs/%s/%s/%s", lostBlob[:2], lostBlob[2:4], lostBlob)))
-
-	return backup
-}
-
-// backupThenDropOneBlobFromMetadata backs up missingBlobFileCount
-// single-chunk files, then removes the blob holding the first of them from
-// the snapshot and exports the snapshot metadata again. The exported
-// metadata then lists chunks that no blob holds.
-func backupThenDropOneBlobFromMetadata(
-	ctx context.Context, t *testing.T,
-) *missingBlobBackup {
-	t.Helper()
-
-	backup, db, lostBlob := backupSingleChunkFiles(ctx, t)
-
-	// The uploads row refers to the blob row, so it would keep the export
-	// from deleting it.
-	for _, query := range []string{
-		"DELETE FROM snapshot_blobs WHERE blob_hash = ?",
-		"DELETE FROM uploads WHERE blob_hash = ?",
-	} {
-		_, err := db.Conn().ExecContext(ctx, query, lostBlob)
-		require.NoError(t, err)
-	}
-
-	sm := newFaultSnapshotManager(
-		backup.fs, backup.storer, backup.cfg, database.NewRepositories(db))
-	require.NoError(t,
-		sm.ExportSnapshotMetadata(ctx, db.Path(), backup.snapshotID))
-	require.NoError(t, db.Close())
-
-	return backup
-}
-
-// backupSingleChunkFiles backs up missingBlobFileCount single-chunk files.
-// It returns the backup, with lost naming the files stored in the same
-// blob as the first of them, the still open local index, and the hash of
-// that blob.
-func backupSingleChunkFiles(
-	ctx context.Context, t *testing.T,
-) (*missingBlobBackup, *database.DB, string) {
-	t.Helper()
-
 	fs := afero.NewOsFs()
 	tempDir := t.TempDir()
 	dataDir := filepath.Join(tempDir, "src")
@@ -235,11 +143,16 @@ func backupSingleChunkFiles(
 		blobOfFile[path] = blobHashOfSingleChunkFile(ctx, t, repos, path)
 	}
 
-	lostBlob := blobOfFile[filepath.Join(dataDir, "file-00.bin")]
+	require.NoError(t, db.Close())
+
+	deleted := blobOfFile[filepath.Join(dataDir, "file-00.bin")]
+	require.NoError(t, storer.Delete(ctx, fmt.Sprintf(
+		"blobs/%s/%s/%s", deleted[:2], deleted[2:4], deleted)))
+
 	lost := make(map[string]bool)
 
 	for path, hash := range blobOfFile {
-		if hash == lostBlob {
+		if hash == deleted {
 			lost[path] = true
 		}
 	}
@@ -255,7 +168,7 @@ func backupSingleChunkFiles(
 		restoreDir: filepath.Join(tempDir, "restored"),
 		files:      files,
 		lost:       lost,
-	}, db, lostBlob
+	}
 }
 
 // blobHashOfSingleChunkFile returns the hash of the blob holding the one

internal/vaultik/restore_unmatched_path_test.go

@@ -0,0 +1,142 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// These tests cover https://git.eeqj.de/sneak/vaultik/issues/309: a path
+// given to restore that matches nothing in the snapshot is named in a
+// warning and makes the restore fail, after the paths that do match are
+// restored.
+
+func TestRestoreNamesUnmatchedPathAndRestoresTheMatchingOne(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "src")
+	storeDir := filepath.Join(tempDir, "remote")
+	restoreDir := filepath.Join(tempDir, "restored")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	ctx := context.Background()
+	cfg := faultTestConfig()
+	files := writeFaultSourceTree(t, fs, dataDir)
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	db, err := database.New(ctx, dbPath)
+	require.NoError(t, err)
+
+	id := fullFaultBackup(ctx, t, fs, store, cfg,
+		database.NewRepositories(db), dataDir, dbPath, "unmatched")
+	require.NoError(t, db.Close())
+
+	matched := filepath.Join(dataDir, "small.txt")
+	unmatched := filepath.Join(dataDir, "typo.txt")
+
+	var out bytes.Buffer
+
+	v := newReaderVaultik(ctx, cfg, store, nil, fs)
+	v.UI = ui.NewWithColor(&out, false)
+
+	err = v.Restore(&vaultik.RestoreOptions{
+		SnapshotID: id,
+		TargetDir:  restoreDir,
+		Paths:      []string{matched, unmatched},
+	})
+
+	require.Error(t, err, "a path that matches nothing must fail the restore")
+	assert.Contains(t, out.String(), unmatched,
+		"the path that matches nothing must be named")
+	assert.NotContains(t, out.String(), matched,
+		"the path that matches must not be reported")
+
+	got, err := afero.ReadFile(fs, filepath.Join(restoreDir, matched))
+	require.NoError(t, err, "the path that matches must still be restored")
+	assert.Equal(t, files[matched], got)
+}
+
+// When no requested path matches, nothing is restored and each path is
+// named. One path is relative. The other goes through the symlink that
+// is the snapshot's configured path, while the entries are stored under
+// the directory the symlink points to.
+func TestRestoreNamesEveryPathWhenNothingMatches(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	const snapshotName = "linked"
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "src")
+	linkDir := filepath.Join(tempDir, "srclink")
+	storeDir := filepath.Join(tempDir, "remote")
+	restoreDir := filepath.Join(tempDir, "restored")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	ctx := context.Background()
+	writeFaultSourceTree(t, fs, dataDir)
+	require.NoError(t, os.Symlink(dataDir, linkDir))
+
+	cfg := faultTestConfig()
+	cfg.IndexPath = dbPath
+	cfg.ChunkSize = config.Size(faultChunkSize)
+	cfg.Snapshots = map[string]config.SnapshotConfig{
+		snapshotName: {Paths: []string{linkDir}},
+	}
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	db, err := database.New(ctx, dbPath)
+	require.NoError(t, err)
+
+	repos := database.NewRepositories(db)
+	v := newBackupVaultik(ctx, cfg, store, repos, db, fs)
+
+	require.NoError(t, backUp(v, snapshotName))
+
+	id := localSnapshotID(ctx, t, repos, snapshotName)
+	require.NoError(t, db.Close())
+
+	throughLink := filepath.Join(linkDir, "sub")
+	relative := strings.TrimPrefix(filepath.Join(dataDir, "small.txt"), "/")
+
+	var out bytes.Buffer
+
+	reader := newReaderVaultik(ctx, cfg, store, nil, fs)
+	reader.UI = ui.NewWithColor(&out, false)
+
+	err = reader.Restore(&vaultik.RestoreOptions{
+		SnapshotID: id,
+		TargetDir:  restoreDir,
+		Paths:      []string{throughLink, relative},
+	})
+
+	require.Error(t, err, "a restore that matches nothing must fail")
+	assert.Contains(t, out.String(), throughLink,
+		"the path through the symlink must be named")
+	assert.Contains(t, out.String(), relative,
+		"the relative path must be named")
+
+	_, err = fs.Stat(restoreDir)
+	assert.True(t, os.IsNotExist(err), "nothing must be restored")
+}