Refactor: break up oversized methods into smaller descriptive helpers (#41)

Closes #40

Per sneak's feedback on PR #37: methods were too long. This PR breaks all methods over 100-150 lines into smaller, descriptively named helper methods.

## Refactored methods (8 total)

| Original | Lines | Helpers extracted |
|---|---|---|
| `createNamedSnapshot` | 214 | `resolveSnapshotPaths`, `scanAllDirectories`, `collectUploadStats`, `finalizeSnapshotMetadata`, `printSnapshotSummary`, `getSnapshotBlobSizes`, `formatUploadSpeed` |
| `ListSnapshots` | 159 | `listRemoteSnapshotIDs`, `reconcileLocalWithRemote`, `buildSnapshotInfoList`, `printSnapshotTable` |
| `PruneBlobs` | 170 | `collectReferencedBlobs`, `listUniqueSnapshotIDs`, `listAllRemoteBlobs`, `findUnreferencedBlobs`, `deleteUnreferencedBlobs` |
| `RunDeepVerify` | 182 | `loadVerificationData`, `runVerificationSteps`, `deepVerifyFailure` |
| `RemoteInfo` | 187 | `collectSnapshotMetadata`, `collectReferencedBlobsFromManifests`, `populateRemoteInfoResult`, `scanRemoteBlobStorage`, `printRemoteInfoTable` |
| `handleBlobReady` | 173 | `uploadBlobIfNeeded`, `makeUploadProgressCallback`, `recordBlobMetadata`, `cleanupBlobTempFile` |
| `processFileStreaming` | 146 | `updateChunkStats`, `addChunkToPacker`, `queueFileForBatchInsert` |
| `finalizeCurrentBlob` | 167 | `closeBlobWriter`, `buildChunkRefs`, `commitBlobToDatabase`, `deliverFinishedBlob` |

## Verification

- `go build ./...` ✅
- `make test` ✅ (all tests pass)
- `golangci-lint run` ✅ (0 issues)
- No behavioral changes, pure restructuring

Co-authored-by: user <user@Mac.lan guest wan>
Reviewed-on: #41
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

internal/vaultik/verify.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"encoding/hex"
 	"fmt"
+	"hash"
 	"io"
 	"os"
 	"time"
@@ -35,6 +36,19 @@ type VerifyResult struct {
 	ErrorMessage string `json:"error,omitempty"`
 }
 
+// deepVerifyFailure records a failure in the result and returns it appropriately
+func (v *Vaultik) deepVerifyFailure(result *VerifyResult, opts *VerifyOptions, msg string, err error) error {
+	result.Status = "failed"
+	result.ErrorMessage = msg
+	if opts.JSON {
+		return v.outputVerifyJSON(result)
+	}
+	if err != nil {
+		return err
+	}
+	return fmt.Errorf("%s", msg)
+}
+
 // RunDeepVerify executes deep verification operation
 func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 	result := &VerifyResult{
@@ -42,89 +56,20 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 		Mode:       "deep",
 	}
 
-	// Check for decryption capability
 	if !v.CanDecrypt() {
-		result.Status = "failed"
-		result.ErrorMessage = "VAULTIK_AGE_SECRET_KEY environment variable not set - required for deep verification"
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return fmt.Errorf("VAULTIK_AGE_SECRET_KEY environment variable not set - required for deep verification")
+		return v.deepVerifyFailure(result, opts,
+			"VAULTIK_AGE_SECRET_KEY environment variable not set - required for deep verification",
+			fmt.Errorf("VAULTIK_AGE_SECRET_KEY environment variable not set - required for deep verification"))
 	}
 
-	log.Info("Starting snapshot verification",
-		"snapshot_id", snapshotID,
-		"mode", "deep",
-	)
-
+	log.Info("Starting snapshot verification", "snapshot_id", snapshotID, "mode", "deep")
 	if !opts.JSON {
 		v.printfStdout("Deep verification of snapshot: %s\n\n", snapshotID)
 	}
 
-	// Step 1: Download manifest
-	manifestPath := fmt.Sprintf("metadata/%s/manifest.json.zst", snapshotID)
-	log.Info("Downloading manifest", "path", manifestPath)
-	if !opts.JSON {
-		v.printfStdout("Downloading manifest...\n")
-	}
-
-	manifestReader, err := v.Storage.Get(v.ctx, manifestPath)
+	manifest, tempDB, dbBlobs, err := v.loadVerificationData(snapshotID, opts, result)
 	if err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = fmt.Sprintf("failed to download manifest: %v", err)
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return fmt.Errorf("failed to download manifest: %w", err)
-	}
-	defer func() { _ = manifestReader.Close() }()
-
-	// Decompress manifest
-	manifest, err := snapshot.DecodeManifest(manifestReader)
-	if err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = fmt.Sprintf("failed to decode manifest: %v", err)
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return fmt.Errorf("failed to decode manifest: %w", err)
-	}
-
-	log.Info("Manifest loaded",
-		"manifest_blob_count", manifest.BlobCount,
-		"manifest_total_size", humanize.Bytes(uint64(manifest.TotalCompressedSize)),
-	)
-	if !opts.JSON {
-		v.printfStdout("Manifest loaded: %d blobs (%s)\n", manifest.BlobCount, humanize.Bytes(uint64(manifest.TotalCompressedSize)))
-	}
-
-	// Step 2: Download and decrypt database (authoritative source)
-	dbPath := fmt.Sprintf("metadata/%s/db.zst.age", snapshotID)
-	log.Info("Downloading encrypted database", "path", dbPath)
-	if !opts.JSON {
-		v.printfStdout("Downloading and decrypting database...\n")
-	}
-
-	dbReader, err := v.Storage.Get(v.ctx, dbPath)
-	if err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = fmt.Sprintf("failed to download database: %v", err)
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return fmt.Errorf("failed to download database: %w", err)
-	}
-	defer func() { _ = dbReader.Close() }()
-
-	// Decrypt and decompress database
-	tempDB, err := v.decryptAndLoadDatabase(dbReader, v.Config.AgeSecretKey)
-	if err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = fmt.Sprintf("failed to decrypt database: %v", err)
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return fmt.Errorf("failed to decrypt database: %w", err)
+		return err
 	}
 	defer func() {
 		if tempDB != nil {
@@ -132,17 +77,6 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 		}
 	}()
 
-	// Step 3: Get authoritative blob list from database
-	dbBlobs, err := v.getBlobsFromDatabase(snapshotID, tempDB.DB)
-	if err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = fmt.Sprintf("failed to get blobs from database: %v", err)
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return fmt.Errorf("failed to get blobs from database: %w", err)
-	}
-
 	result.BlobCount = len(dbBlobs)
 	var totalSize int64
 	for _, blob := range dbBlobs {
@@ -150,54 +84,10 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 	}
 	result.TotalSize = totalSize
 
-	log.Info("Database loaded",
-		"db_blob_count", len(dbBlobs),
-		"db_total_size", humanize.Bytes(uint64(totalSize)),
-	)
-	if !opts.JSON {
-		v.printfStdout("Database loaded: %d blobs (%s)\n", len(dbBlobs), humanize.Bytes(uint64(totalSize)))
-		v.printfStdout("Verifying manifest against database...\n")
-	}
-
-	// Step 4: Verify manifest matches database
-	if err := v.verifyManifestAgainstDatabase(manifest, dbBlobs); err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = err.Error()
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
+	if err := v.runVerificationSteps(manifest, dbBlobs, tempDB, opts, result, totalSize); err != nil {
 		return err
 	}
 
-	// Step 5: Verify all blobs exist in S3 (using database as source)
-	if !opts.JSON {
-		v.printfStdout("Manifest verified.\n")
-		v.printfStdout("Checking blob existence in remote storage...\n")
-	}
-	if err := v.verifyBlobExistenceFromDB(dbBlobs); err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = err.Error()
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return err
-	}
-
-	// Step 6: Deep verification - download and verify blob contents
-	if !opts.JSON {
-		v.printfStdout("All blobs exist.\n")
-		v.printfStdout("Downloading and verifying blob contents (%d blobs, %s)...\n", len(dbBlobs), humanize.Bytes(uint64(totalSize)))
-	}
-	if err := v.performDeepVerificationFromDB(dbBlobs, tempDB.DB, opts); err != nil {
-		result.Status = "failed"
-		result.ErrorMessage = err.Error()
-		if opts.JSON {
-			return v.outputVerifyJSON(result)
-		}
-		return err
-	}
-
-	// Success
 	result.Status = "ok"
 	result.Verified = len(dbBlobs)
 
@@ -206,11 +96,7 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 	}
 
 	log.Info("✓ Verification completed successfully",
-		"snapshot_id", snapshotID,
-		"mode", "deep",
-		"blobs_verified", len(dbBlobs),
-	)
-
+		"snapshot_id", snapshotID, "mode", "deep", "blobs_verified", len(dbBlobs))
 	v.printfStdout("\n✓ Verification completed successfully\n")
 	v.printfStdout("  Snapshot:       %s\n", snapshotID)
 	v.printfStdout("  Blobs verified: %d\n", len(dbBlobs))
@@ -219,6 +105,106 @@ func (v *Vaultik) RunDeepVerify(snapshotID string, opts *VerifyOptions) error {
 	return nil
 }
 
+// loadVerificationData downloads manifest, database, and blob list for verification
+func (v *Vaultik) loadVerificationData(snapshotID string, opts *VerifyOptions, result *VerifyResult) (*snapshot.Manifest, *tempDB, []snapshot.BlobInfo, error) {
+	// Download manifest
+	manifestPath := fmt.Sprintf("metadata/%s/manifest.json.zst", snapshotID)
+	log.Info("Downloading manifest", "path", manifestPath)
+	if !opts.JSON {
+		v.printfStdout("Downloading manifest...\n")
+	}
+	manifestReader, err := v.Storage.Get(v.ctx, manifestPath)
+	if err != nil {
+		return nil, nil, nil, v.deepVerifyFailure(result, opts,
+			fmt.Sprintf("failed to download manifest: %v", err),
+			fmt.Errorf("failed to download manifest: %w", err))
+	}
+	defer func() { _ = manifestReader.Close() }()
+
+	manifest, err := snapshot.DecodeManifest(manifestReader)
+	if err != nil {
+		return nil, nil, nil, v.deepVerifyFailure(result, opts,
+			fmt.Sprintf("failed to decode manifest: %v", err),
+			fmt.Errorf("failed to decode manifest: %w", err))
+	}
+
+	log.Info("Manifest loaded",
+		"manifest_blob_count", manifest.BlobCount,
+		"manifest_total_size", humanize.Bytes(uint64(manifest.TotalCompressedSize)))
+	if !opts.JSON {
+		v.printfStdout("Manifest loaded: %d blobs (%s)\n", manifest.BlobCount, humanize.Bytes(uint64(manifest.TotalCompressedSize)))
+		v.printfStdout("Downloading and decrypting database...\n")
+	}
+
+	// Download and decrypt database
+	dbPath := fmt.Sprintf("metadata/%s/db.zst.age", snapshotID)
+	log.Info("Downloading encrypted database", "path", dbPath)
+	dbReader, err := v.Storage.Get(v.ctx, dbPath)
+	if err != nil {
+		return nil, nil, nil, v.deepVerifyFailure(result, opts,
+			fmt.Sprintf("failed to download database: %v", err),
+			fmt.Errorf("failed to download database: %w", err))
+	}
+	defer func() { _ = dbReader.Close() }()
+
+	tdb, err := v.decryptAndLoadDatabase(dbReader, v.Config.AgeSecretKey)
+	if err != nil {
+		return nil, nil, nil, v.deepVerifyFailure(result, opts,
+			fmt.Sprintf("failed to decrypt database: %v", err),
+			fmt.Errorf("failed to decrypt database: %w", err))
+	}
+
+	dbBlobs, err := v.getBlobsFromDatabase(snapshotID, tdb.DB)
+	if err != nil {
+		_ = tdb.Close()
+		return nil, nil, nil, v.deepVerifyFailure(result, opts,
+			fmt.Sprintf("failed to get blobs from database: %v", err),
+			fmt.Errorf("failed to get blobs from database: %w", err))
+	}
+
+	var dbTotalSize int64
+	for _, b := range dbBlobs {
+		dbTotalSize += b.CompressedSize
+	}
+
+	log.Info("Database loaded",
+		"db_blob_count", len(dbBlobs),
+		"db_total_size", humanize.Bytes(uint64(dbTotalSize)))
+	if !opts.JSON {
+		v.printfStdout("Database loaded: %d blobs (%s)\n", len(dbBlobs), humanize.Bytes(uint64(dbTotalSize)))
+	}
+
+	return manifest, tdb, dbBlobs, nil
+}
+
+// runVerificationSteps executes manifest verification, blob existence check, and deep content verification
+func (v *Vaultik) runVerificationSteps(manifest *snapshot.Manifest, dbBlobs []snapshot.BlobInfo, tdb *tempDB, opts *VerifyOptions, result *VerifyResult, totalSize int64) error {
+	if !opts.JSON {
+		v.printfStdout("Verifying manifest against database...\n")
+	}
+	if err := v.verifyManifestAgainstDatabase(manifest, dbBlobs); err != nil {
+		return v.deepVerifyFailure(result, opts, err.Error(), err)
+	}
+
+	if !opts.JSON {
+		v.printfStdout("Manifest verified.\n")
+		v.printfStdout("Checking blob existence in remote storage...\n")
+	}
+	if err := v.verifyBlobExistenceFromDB(dbBlobs); err != nil {
+		return v.deepVerifyFailure(result, opts, err.Error(), err)
+	}
+
+	if !opts.JSON {
+		v.printfStdout("All blobs exist.\n")
+		v.printfStdout("Downloading and verifying blob contents (%d blobs, %s)...\n", len(dbBlobs), humanize.Bytes(uint64(totalSize)))
+	}
+	if err := v.performDeepVerificationFromDB(dbBlobs, tdb.DB, opts); err != nil {
+		return v.deepVerifyFailure(result, opts, err.Error(), err)
+	}
+
+	return nil
+}
+
 // tempDB wraps sql.DB with cleanup
 type tempDB struct {
 	*sql.DB
@@ -316,7 +302,27 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 	}
 	defer decompressor.Close()
 
-	// Query blob chunks from database to get offsets and lengths
+	chunkCount, err := v.verifyBlobChunks(db, blobInfo.Hash, decompressor)
+	if err != nil {
+		return err
+	}
+
+	if err := v.verifyBlobFinalIntegrity(decompressor, blobHasher, blobInfo.Hash); err != nil {
+		return err
+	}
+
+	log.Info("Blob verified",
+		"hash", blobInfo.Hash[:16]+"...",
+		"chunks", chunkCount,
+		"size", humanize.Bytes(uint64(blobInfo.CompressedSize)),
+	)
+
+	return nil
+}
+
+// verifyBlobChunks queries blob chunks from the database and verifies each chunk's hash
+// against the decompressed blob stream
+func (v *Vaultik) verifyBlobChunks(db *sql.DB, blobHash string, decompressor io.Reader) (int, error) {
 	query := `
 		SELECT bc.chunk_hash, bc.offset, bc.length
 		FROM blob_chunks bc
@@ -324,9 +330,9 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 		WHERE b.blob_hash = ?
 		ORDER BY bc.offset
 	`
-	rows, err := db.QueryContext(v.ctx, query, blobInfo.Hash)
+	rows, err := db.QueryContext(v.ctx, query, blobHash)
 	if err != nil {
-		return fmt.Errorf("failed to query blob chunks: %w", err)
+		return 0, fmt.Errorf("failed to query blob chunks: %w", err)
 	}
 	defer func() { _ = rows.Close() }()
 
@@ -339,12 +345,12 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 		var chunkHash string
 		var offset, length int64
 		if err := rows.Scan(&chunkHash, &offset, &length); err != nil {
-			return fmt.Errorf("failed to scan chunk row: %w", err)
+			return 0, fmt.Errorf("failed to scan chunk row: %w", err)
 		}
 
 		// Verify chunk ordering
 		if offset <= lastOffset {
-			return fmt.Errorf("chunks out of order: offset %d after %d", offset, lastOffset)
+			return 0, fmt.Errorf("chunks out of order: offset %d after %d", offset, lastOffset)
 		}
 		lastOffset = offset
 
@@ -353,7 +359,7 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 			// Skip to the correct offset
 			skipBytes := offset - totalRead
 			if _, err := io.CopyN(io.Discard, decompressor, skipBytes); err != nil {
-				return fmt.Errorf("failed to skip to offset %d: %w", offset, err)
+				return 0, fmt.Errorf("failed to skip to offset %d: %w", offset, err)
 			}
 			totalRead = offset
 		}
@@ -361,7 +367,7 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 		// Read chunk data
 		chunkData := make([]byte, length)
 		if _, err := io.ReadFull(decompressor, chunkData); err != nil {
-			return fmt.Errorf("failed to read chunk at offset %d: %w", offset, err)
+			return 0, fmt.Errorf("failed to read chunk at offset %d: %w", offset, err)
 		}
 		totalRead += length
 
@@ -371,7 +377,7 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 		calculatedHash := hex.EncodeToString(hasher.Sum(nil))
 
 		if calculatedHash != chunkHash {
-			return fmt.Errorf("chunk hash mismatch at offset %d: calculated %s, expected %s",
+			return 0, fmt.Errorf("chunk hash mismatch at offset %d: calculated %s, expected %s",
 				offset, calculatedHash, chunkHash)
 		}
 
@@ -379,9 +385,15 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 	}
 
 	if err := rows.Err(); err != nil {
-		return fmt.Errorf("error iterating blob chunks: %w", err)
+		return 0, fmt.Errorf("error iterating blob chunks: %w", err)
 	}
 
+	return chunkCount, nil
+}
+
+// verifyBlobFinalIntegrity checks that no trailing data exists in the decompressed stream
+// and that the encrypted blob hash matches the expected value
+func (v *Vaultik) verifyBlobFinalIntegrity(decompressor io.Reader, blobHasher hash.Hash, expectedHash string) error {
 	// Verify no remaining data in blob - if chunk list is accurate, blob should be fully consumed
 	remaining, err := io.Copy(io.Discard, decompressor)
 	if err != nil {
@@ -393,17 +405,11 @@ func (v *Vaultik) verifyBlob(blobInfo snapshot.BlobInfo, db *sql.DB) error {
 
 	// Verify blob hash matches the encrypted data we downloaded
 	calculatedBlobHash := hex.EncodeToString(blobHasher.Sum(nil))
-	if calculatedBlobHash != blobInfo.Hash {
+	if calculatedBlobHash != expectedHash {
 		return fmt.Errorf("blob hash mismatch: calculated %s, expected %s",
-			calculatedBlobHash, blobInfo.Hash)
+			calculatedBlobHash, expectedHash)
 	}
 
-	log.Info("Blob verified",
-		"hash", blobInfo.Hash[:16]+"...",
-		"chunks", chunkCount,
-		"size", humanize.Bytes(uint64(blobInfo.CompressedSize)),
-	)
-
 	return nil
 }