Compare commits

..
Author SHA1 Message Date
sneak 7cf82cc1d2 Report snapshot blobs missing from the destination in remote info (closes #425)
check / check (push) Waiting to run
remote info now counts the blobs that a manifest lists but the
destination does not hold, with their total size, and names each
snapshot that lists one, since it cannot be restored. When any blob is
missing the command exits non-zero after writing its report. --json
gives the figures in missing_blob_count, missing_blob_size and
snapshots_missing_blobs.

Model: opus-5-5
2026-11-19 06:54:34 +00:00
clawbot d747ddef3a Let snapshot remove accept a remote-only snapshot's remote key (closes #400)
check / check (push) Successful in 13m35s
snapshot remove hashed its argument into a remote key, so the remote
key that snapshot list shows for a remote-only snapshot never matched.
A remote key or a leading part of it is now resolved with
resolveSnapshotRemoteKey, as snapshot verify and snapshot restore do.

Model: opus-5-5
2026-11-17 01:18:19 +01:00
12 changed files with 276 additions and 47 deletions

No files matched your search

+12 -4
View File
@@ -468,10 +468,12 @@ destination store. Blobs are NOT touched — deleting blobs requires reading eve
remaining remote manifest (the destination store may hold snapshots this host
doesn't know about), which is what `vaultik prune` does. The command prints the
`vaultik prune` invocation to run as a follow-up only when it removed the
snapshot's metadata from the destination store, and never under `--json`. An ID
that names no snapshot in the local index or on the destination store is an
error; with `--local-only`, the snapshot must be in the local index. Local row
cleanup (files, chunks, blobs the snapshot was the last referrer for) runs
snapshot's metadata from the destination store, and never under `--json`. It
accepts the same identifiers as `snapshot restore`: a snapshot ID, or a
remote-only snapshot's remote key (or an unambiguous leading part of it). An
identifier that names no snapshot in the local index or on the destination store
is an error; with `--local-only`, the snapshot must be in the local index. Local
row cleanup (files, chunks, blobs the snapshot was the last referrer for) runs
automatically. If removing the snapshot's metadata from the destination store
fails (for example because the store is unreachable, or the local index holds
snapshots and the destination answers that it has no `vaultik-destination.txt`),
@@ -552,6 +554,12 @@ count and blob size unknown, `null` in `--json`. A file under `blobs/` whose
name is not a blob hash is not counted as a blob, since `prune` never deletes
it.
A blob that a manifest lists but the destination does not hold is reported as
missing, with a count and size. The report names each snapshot that lists a
missing blob, since that snapshot cannot be restored. The command then exits
non-zero. `--json` gives these in `missing_blob_count`, `missing_blob_size` and
`snapshots_missing_blobs`.
- `--json`: Output as JSON
**`remote nuke`**: Delete every object under `metadata/` and `blobs/` on the
+3 -1
View File
@@ -75,7 +75,9 @@ func newRemoteInfoCommand() *cobra.Command {
- Size of all snapshot metadata (per snapshot and total)
- Count and total size of all blobs
- Count and size of referenced blobs (from all manifests)
- Count and size of orphaned blobs (not referenced by any manifest)`,
- Count and size of orphaned blobs (not referenced by any manifest)
- Count and size of referenced blobs missing from remote storage, and the
snapshots that list them; the command exits non-zero when any are missing`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
// Use unified config resolution
+4 -2
View File
@@ -331,8 +331,10 @@ know about), which is what 'vaultik prune' does. The command prints the
'vaultik prune' invocation to run as a follow-up only when it removed the
snapshot's metadata from the destination store, and never under --json.
An ID that names no snapshot in the local index or on the destination
store is an error.
The snapshot may be named by its ID or by its remote key, which
'snapshot list' prints for a remote-only snapshot. An unambiguous
leading part of the key is enough. An identifier that names no snapshot
in the local index or on the destination store is an error.
Use --local-only to skip the remote half (e.g. when you want to forget a
snapshot locally without touching the destination store); the snapshot
+74 -7
View File
@@ -9,6 +9,7 @@ import (
"github.com/dustin/go-humanize"
"sneak.berlin/go/vaultik/internal/log"
"sneak.berlin/go/vaultik/internal/storage"
)
// ShowInfo displays system and configuration information
@@ -187,6 +188,9 @@ type SnapshotMetadataInfo struct {
// backup interrupted before its manifest upload leaves a directory
// without one, which prune does not treat as a snapshot.
hasManifest bool
// Hashes of the blobs the snapshot's manifest lists.
blobHashes []string
}
// RemoteInfoResult contains all remote storage information
@@ -216,6 +220,13 @@ type RemoteInfoResult struct {
OrphanedBlobCount *int `json:"orphaned_blob_count"`
OrphanedBlobSize *int64 `json:"orphaned_blob_size"`
// Blobs that a manifest lists but the destination does not hold,
// and the remote key of each snapshot whose manifest lists one.
// Those snapshots cannot be restored.
MissingBlobCount int `json:"missing_blob_count"`
MissingBlobSize int64 `json:"missing_blob_size"`
SnapshotsMissingBlobs []string `json:"snapshots_missing_blobs,omitempty"`
// Remote key of each snapshot whose manifest could not be read
UnreadableManifests []string `json:"unreadable_manifests,omitempty"`
@@ -283,19 +294,30 @@ func (v *Vaultik) RemoteInfo(jsonOutput bool) error {
"snapshots", result.TotalMetadataCount,
"total_blobs", result.TotalBlobCount,
"referenced_blobs", result.ReferencedBlobCount,
"missing_blobs", result.MissingBlobCount,
"unreadable_manifests", len(result.UnreadableManifests))
if jsonOutput {
enc := json.NewEncoder(v.Stdout)
enc.SetIndent("", " ")
return enc.Encode(result)
err = enc.Encode(result)
if err != nil {
return fmt.Errorf("encoding JSON: %w", err)
}
}
if showText {
v.printRemoteInfoTable(result)
}
// The report is written first, so the exit status adds to it.
if result.MissingBlobCount > 0 {
return fmt.Errorf("%w: %d blob(s) that snapshots list are missing; "+
"%d snapshot(s) cannot be restored", errProblemsInStorage,
result.MissingBlobCount, len(result.SnapshotsMissingBlobs))
}
return nil
}
@@ -405,6 +427,7 @@ func (v *Vaultik) collectReferencedBlobsFromManifests(
for _, blob := range manifest.Blobs {
referencedBlobs[blob.Hash] = blob.CompressedSize
blobsSize += blob.CompressedSize
info.blobHashes = append(info.blobHashes, blob.Hash)
}
info.BlobCount = &blobCount
@@ -462,6 +485,8 @@ func (v *Vaultik) scanRemoteBlobStorage(
result.TotalBlobSize += blob.Size
}
countMissingBlobs(result, referencedBlobs, allBlobs)
// A blob named only by a manifest that could not be read, or by one
// under a skipped name, would be counted as orphaned, so the orphan
// figures stay unknown.
@@ -487,6 +512,33 @@ func (v *Vaultik) scanRemoteBlobStorage(
return nil
}
// countMissingBlobs records in result the referenced blobs that
// allBlobs, the listing of the destination, does not hold, and the
// snapshots whose manifests list one of them. It reads the snapshots
// from result.Snapshots, so populateRemoteInfoResult must run first.
func countMissingBlobs(
result *RemoteInfoResult, referencedBlobs map[string]int64,
allBlobs map[string]storage.ObjectInfo,
) {
for hash, size := range referencedBlobs {
if _, present := allBlobs[hash]; !present {
result.MissingBlobCount++
result.MissingBlobSize += size
}
}
for _, info := range result.Snapshots {
for _, hash := range info.blobHashes {
if _, present := allBlobs[hash]; !present {
result.SnapshotsMissingBlobs = append(
result.SnapshotsMissingBlobs, info.SnapshotID)
break
}
}
}
}
// printRemoteInfoTable renders the human-readable remote info output
func (v *Vaultik) printRemoteInfoTable(result *RemoteInfoResult) {
const (
@@ -539,6 +591,12 @@ func (v *Vaultik) printRemoteInfoTable(result *RemoteInfoResult) {
"", "", ubytes(result.TotalMetadataSize))
}
v.printBlobStorageSummary(result)
}
// printBlobStorageSummary renders the blob storage section that ends
// the human-readable remote info output.
func (v *Vaultik) printBlobStorageSummary(result *RemoteInfoResult) {
v.stdoutf("\n=== Blob Storage ===\n")
v.stdoutf("Total blobs on remote: %s (%s)\n",
humanize.Comma(int64(result.TotalBlobCount)),
@@ -546,22 +604,31 @@ func (v *Vaultik) printRemoteInfoTable(result *RemoteInfoResult) {
v.stdoutf("Referenced by snapshots: %s (%s)\n",
humanize.Comma(int64(result.ReferencedBlobCount)),
ubytes(result.ReferencedBlobSize))
v.stdoutf("Missing from remote: %s (%s)\n",
humanize.Comma(int64(result.MissingBlobCount)),
ubytes(result.MissingBlobSize))
if result.OrphanedBlobCount == nil {
v.stdoutf("Orphaned (unreferenced): unknown "+
"(%d manifest(s) could not be read, "+
"%d manifest(s) under a non-conforming name skipped)\n",
len(result.UnreadableManifests), result.SkippedManifestCount)
} else {
v.stdoutf("Orphaned (unreferenced): %s (%s)\n",
humanize.Comma(int64(*result.OrphanedBlobCount)),
ubytes(*result.OrphanedBlobSize))
return
if *result.OrphanedBlobCount > 0 {
v.stdoutf("\nRun 'vaultik prune' to remove orphaned blobs.\n")
}
}
v.stdoutf("Orphaned (unreferenced): %s (%s)\n",
humanize.Comma(int64(*result.OrphanedBlobCount)),
ubytes(*result.OrphanedBlobSize))
if len(result.SnapshotsMissingBlobs) > 0 {
v.stdoutf("\nSnapshots that cannot be restored (blobs missing):\n")
if *result.OrphanedBlobCount > 0 {
v.stdoutf("\nRun 'vaultik prune' to remove orphaned blobs.\n")
for _, id := range result.SnapshotsMissingBlobs {
v.stdoutf(" %s\n", id)
}
}
}
+60
View File
@@ -83,6 +83,7 @@ func TestRemoteInfo_UnreadableManifestLeavesSnapshotBlobsUnknown(t *testing.T) {
env := newListEnv(t)
readableKey := env.addRemote(t, listRemoteID,
time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
addBlob(t, env.store.testStorer, testBlobHashA)
unreadableKey := snapshot.RemoteSnapshotKey(listLocalID)
require.NoError(t, env.store.Put(context.Background(),
@@ -270,6 +271,7 @@ func TestRemoteInfo_StatusLineUsesUIMarker(t *testing.T) {
env := newListEnv(t)
env.addRemote(t, listRemoteID, time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
addBlob(t, env.store.testStorer, testBlobHashA)
const statusLine = ui.Marker + " Scanning snapshot metadata...\n"
@@ -281,3 +283,61 @@ func TestRemoteInfo_StatusLineUsesUIMarker(t *testing.T) {
require.NoError(t, env.v.RemoteInfo(false))
assert.NotContains(t, env.stdout.String(), "Scanning snapshot metadata")
}
// TestRemoteInfo_ReportsBlobsMissingFromDestination checks that a blob a
// manifest lists but the destination does not hold is counted as
// missing, that the snapshot listing it is named, and that remote info
// then fails after writing its report.
func TestRemoteInfo_ReportsBlobsMissingFromDestination(t *testing.T) {
log.Initialize(log.Config{})
t.Parallel()
env := newListEnv(t)
// The first snapshot lists blob A, which is not stored. The second
// lists blob B, which is.
brokenKey := env.addRemote(t, listRemoteID,
time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
addManifest(t, env.store.testStorer, listLocalID, []string{testBlobHashB})
addBlob(t, env.store.testStorer, testBlobHashB)
const wantError = "1 blob(s) that snapshots list are missing; " +
"1 snapshot(s) cannot be restored"
err := env.v.RemoteInfo(false)
require.ErrorContains(t, err, wantError)
text := env.stdout.String()
assert.Contains(t, text, "Missing from remote: 1 (5.0 MB)")
assert.Contains(t, text, "Snapshots that cannot be restored (blobs missing):\n"+
" "+brokenKey+"\n")
assert.NotContains(t, text, snapshot.RemoteSnapshotKey(listLocalID)+"\n")
env.stdout.Reset()
require.ErrorContains(t, env.v.RemoteInfo(true), wantError)
var doc map[string]any
require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &doc))
assert.InDelta(t, 1, doc["missing_blob_count"], 0)
assert.InDelta(t, fiveMegabytes, doc["missing_blob_size"], 0)
assert.Equal(t, []any{brokenKey}, doc["snapshots_missing_blobs"])
// --quiet drops the report, not the failure.
env.stdout.Reset()
env.v.UI.SetQuiet(true)
require.ErrorContains(t, env.v.RemoteInfo(false), wantError)
assert.Empty(t, env.stdout.String())
env.v.UI.SetQuiet(false)
// With blob A stored again nothing is missing.
addBlob(t, env.store.testStorer, testBlobHashA)
env.stdout.Reset()
require.NoError(t, env.v.RemoteInfo(true))
doc = nil
require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &doc))
assert.InDelta(t, 0, doc["missing_blob_count"], 0)
assert.InDelta(t, 0, doc["missing_blob_size"], 0)
assert.NotContains(t, doc, "snapshots_missing_blobs")
}
+62
View File
@@ -472,6 +472,68 @@ func TestRemoveSnapshot_NotInLocalIndex(t *testing.T) {
assert.Contains(t, out, "Removed snapshot metadata from remote storage")
}
// TestRemoveSnapshot_ByRemoteKey checks that a snapshot only the
// destination store holds can be removed by the remote key that
// `snapshot list` shows for it, or by a leading part of that key.
func TestRemoveSnapshot_ByRemoteKey(t *testing.T) {
log.Initialize(log.Config{})
t.Parallel()
remoteKey := snapshot.RemoteSnapshotKey("snapshot-001")
for name, identifier := range map[string]string{
"full key": remoteKey,
"leading part": remoteKey[:8],
} {
t.Run(name, func(t *testing.T) {
t.Parallel()
store := newTestStorer()
addManifest(t, store, "snapshot-001", nil)
tv := vaultik.NewForTesting(store)
tv.Repositories = newLocalIndex(t)
result, err := tv.RemoveSnapshot(identifier,
&vaultik.RemoveOptions{Force: true})
require.NoError(t, err)
assert.True(t, result.RemoteRemoved)
assert.False(t, store.hasKey(remoteKeyPath("snapshot-001")))
})
}
}
// TestRemoveSnapshot_ByRemoteKeyInLocalIndex checks that a snapshot the
// local index holds, named by its remote key, is removed from the local
// index as well as from the destination store.
func TestRemoveSnapshot_ByRemoteKeyInLocalIndex(t *testing.T) {
log.Initialize(log.Config{})
t.Parallel()
store := newTestStorer()
addManifest(t, store, "snapshot-001", nil)
// A backup wrote to this destination, so it carries the marker.
require.NoError(t, store.Put(context.Background(), markerFile,
bytes.NewReader(nil)))
tv := vaultik.NewForTesting(store)
tv.Repositories = newLocalIndex(t, "snapshot-001")
result, err := tv.RemoveSnapshot(snapshot.RemoteSnapshotKey("snapshot-001"),
&vaultik.RemoveOptions{Force: true})
require.NoError(t, err)
assert.True(t, result.RemoteRemoved)
assert.False(t, store.hasKey(remoteKeyPath("snapshot-001")))
snap, err := tv.Repositories.Snapshots.GetByID(context.Background(),
"snapshot-001")
require.NoError(t, err)
assert.Nil(t, snap)
}
// TestRemoveSnapshot_NotInLocalIndexDeleteFails checks that removing a
// snapshot only the destination store holds fails when its metadata
// cannot be deleted there, under --force and under --json: nothing was
+4 -3
View File
@@ -31,9 +31,10 @@ var (
errPathsNotInSnapshot = errors.New("requested path(s) not in the snapshot")
errFilesFailedVerify = errors.New("files failed verification")
errDecryptionKeyRequired = errors.New(
"age secret key is missing; set it in the " +
"VAULTIK_AGE_SECRET_KEY environment variable or the " +
"age_secret_key config file field")
"decryption key required\n\n" +
"Set the VAULTIK_AGE_SECRET_KEY environment variable to your " +
"age private key file:\n" +
" export VAULTIK_AGE_SECRET_KEY=\"$(cat vaultik_backup_private_key.txt)\"")
// errInvalidAgeSecretKey is returned when the configured key does not
// parse as any age identity. It names the source but never the value,
// which is secret, so the message is safe to print and log.
-20
View File
@@ -106,23 +106,3 @@ func TestRestoreIdentitiesMissingKey(t *testing.T) {
_, err := v.restoreIdentities()
require.ErrorIs(t, err, errDecryptionKeyRequired)
}
// TestMissingKeyErrorsNameBothSources asserts restore and deep verify
// return the same missing-key error, whose text names both places the key
// can be set: the VAULTIK_AGE_SECRET_KEY environment variable first since
// it is preferred, then the age_secret_key config file field.
func TestMissingKeyErrorsNameBothSources(t *testing.T) {
t.Parallel()
const want = "age secret key is missing; set it in " +
"the VAULTIK_AGE_SECRET_KEY environment variable or the " +
"age_secret_key config file field"
v := &Vaultik{Config: &config.Config{}}
_, err := v.restoreIdentities()
require.EqualError(t, err, want)
err = v.RunDeepVerify("any-snapshot", &VerifyOptions{})
require.EqualError(t, err, want)
}
+42 -7
View File
@@ -1467,7 +1467,8 @@ func (v *Vaultik) RemoveSnapshot(
return result, err
}
inLocalIndex, err := v.checkSnapshotExists(snapshotID, opts.LocalOnly)
snapshotID, remoteKey, inLocalIndex, err := v.findSnapshotToRemove(
snapshotID, opts.LocalOnly)
if err != nil {
return result, err
}
@@ -1498,7 +1499,7 @@ func (v *Vaultik) RemoveSnapshot(
}
result.RemoteRemoved, err = v.removeSnapshotRemote(
snapshotID, inLocalIndex, markerErr, opts)
snapshotID, remoteKey, inLocalIndex, markerErr, opts)
if err != nil {
return result, err
}
@@ -1530,6 +1531,41 @@ func (v *Vaultik) RemoveSnapshot(
return result, nil
}
// findSnapshotToRemove returns the ID of the snapshot that identifier
// names, its remote key, and whether the local index holds it. A remote
// key, or the leading part of one, is resolved on the destination store;
// when the local index holds the snapshot with that key, its ID is
// returned, so it is removed from both.
func (v *Vaultik) findSnapshotToRemove(
identifier string, localOnly bool,
) (string, string, bool, error) {
if !isRemoteKeyOrPrefix(identifier) || localOnly {
inLocalIndex, err := v.checkSnapshotExists(identifier, localOnly)
return identifier, snapshot.RemoteSnapshotKey(identifier),
inLocalIndex, err
}
remoteKey, err := v.resolveSnapshotRemoteKey(identifier)
if err != nil {
return "", "", false, err
}
localIDs, err := v.localSnapshotIDs()
if err != nil {
return "", "", false, fmt.Errorf(
"looking up snapshot in local index: %w", err)
}
for _, id := range localIDs {
if snapshot.RemoteSnapshotKey(id) == remoteKey {
return id, remoteKey, true, nil
}
}
return identifier, remoteKey, false, nil
}
// checkSnapshotExists returns errSnapshotNotFound when the local index
// has no row for snapshotID and, unless localOnly is set, the
// destination store has no metadata for it either. inLocalIndex reports
@@ -1638,8 +1674,8 @@ func (v *Vaultik) confirmRemoveSnapshot(snapshotID string, opts *RemoveOptions)
return true
}
// removeSnapshotRemote strips the snapshot's metadata from the
// destination store. It returns true only when the delete finished
// removeSnapshotRemote strips the snapshot's metadata, under remoteKey,
// from the destination store. It returns true only when the delete finished
// without an error and removed at least one object; under LocalOnly it
// does nothing. markerErr is the result of checkDestinationMarker; when
// it is set, nothing is deleted and it is the failure. When the snapshot
@@ -1651,7 +1687,7 @@ func (v *Vaultik) confirmRemoveSnapshot(snapshotID string, opts *RemoveOptions)
// (`vaultik prune` never removes snapshot metadata that has its
// manifest).
func (v *Vaultik) removeSnapshotRemote(
snapshotID string, inLocalIndex bool, markerErr error,
snapshotID, remoteKey string, inLocalIndex bool, markerErr error,
opts *RemoveOptions,
) (bool, error) {
if opts.LocalOnly {
@@ -1665,8 +1701,7 @@ func (v *Vaultik) removeSnapshotRemote(
err := markerErr
if err == nil {
deleted, err = v.deleteRemoteSnapshotByKey(
snapshot.RemoteSnapshotKey(snapshotID))
deleted, err = v.deleteRemoteSnapshotByKey(remoteKey)
}
if err != nil && !inLocalIndex {
+1
View File
@@ -349,6 +349,7 @@ func TestSnapshotListAndPurgePrintSizesLikeRemoteInfo(t *testing.T) {
env.addRemote(t, listLocalID, start)
require.NoError(t, env.v.Repositories.Snapshots.UpdateCounts(
context.Background(), nil, listLocalID, 0, 0, 0, 0, fiveMegabytes))
addBlob(t, env.store.testStorer, testBlobHashA)
require.NoError(t, env.v.RemoteInfo(false))
assert.Contains(t, findTableRow(t, env.stdout.String(), remoteKey[:16]),
+5
View File
@@ -163,6 +163,11 @@ func (v *Vaultik) StartOperation(fn func()) func(context.Context) bool {
}
}
// CanDecrypt returns true if this Vaultik instance has decryption capabilities
func (v *Vaultik) CanDecrypt() bool {
return v.Config.AgeSecretKey != ""
}
// GetFilesystem returns the filesystem instance used by Vaultik
//
//nolint:ireturn // afero.Fs is the filesystem abstraction by design
+9 -3
View File
@@ -22,7 +22,9 @@ import (
// Sentinel errors for snapshot verification failures.
var (
errVerificationFailed = errors.New("verification failed")
errVerificationFailed = errors.New("verification failed")
errSecretKeyRequired = errors.New(
"VAULTIK_AGE_SECRET_KEY not set; required for deep verification")
errChunksOutOfOrder = errors.New("chunks out of order")
errChunkHashMismatch = errors.New("chunk hash mismatch")
errNegativeChunkLength = errors.New("chunk length is negative")
@@ -104,9 +106,13 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
Mode: "deep",
}
if !v.CanDecrypt() {
return v.deepVerifyFailure(result, opts,
errSecretKeyRequired.Error(), errSecretKeyRequired)
}
// Parse the age secret key once, the same way restore does, and reuse
// the identities for the database and every blob. A missing key fails
// here, before anything is downloaded.
// the identities for the database and every blob.
identities, err := v.restoreIdentities()
if err != nil {
return v.deepVerifyFailure(result, opts, err.Error(), err)