tiny-forge/plans/volume-snapshot-restore/phase-1-engine-primitives.md

Phase 1: Restore engine primitives + path-safe extractor + unit tests

Status: ✅ Complete Parent plan: PLAN.md Domain: backend

Objective

Build the dangerous filesystem primitives in isolation, fully unit-tested, with NO docker/lifecycle wiring. Each is a pure function over directories + the store + a parsed manifest. No caller yet (exercised by tests so not "unused"). Zero behavior change to existing capture.

Tasks

• internal/volsnap/extract.go — safeExtractIndex(archivePath string, index int, dest string, bombCap int64) (int64, error): open the gzip tar, extract only entries under the "<index>/" prefix into dest, return bytes written. UNTRUSTED-input guards (C6):
  • zip-slip: target := filepath.Join(dest, rel); require strings.HasPrefix(filepath.Clean(target)+sep, cleanDest+sep) (or target == cleanDest); reject otherwise.
  • allow ONLY tar.TypeReg + tar.TypeDir; reject symlink/hardlink/char/block/fifo/socket with an error (never follow).
  • decompression-bomb cap: running byte counter; abort when it would exceed bombCap.
  • create parent dirs as needed; files 0o600, dirs 0o700 (data dirs; ownership is the container's concern).
  • skip manifest.json and any entry whose leading path segment ≠ index.
• internal/volsnap/restore.go (primitives only — NO orchestration):
  • archiveUncompressedSize(archivePath string, bombCap int64) (int64, error) — header-only sizing pass summing hdr.Size, enforcing bombCap (feeds C5). Per-index sizes too (map[int]int64) so C5 can check per filesystem.
  • parseManifest(snap store.VolumeSnapshot) ([]SnapshotVolume, error).
  • preflightResolve(w store.Workload, settings store.Settings, manifest []SnapshotVolume) ([]resolvedVol, error) — ALL-OR-NOTHING (C3): for every manifest volume require supportedScopes[scope] AND volume.ResolveWorkloadPath succeeds; on first failure return an error naming target+scope+reason (abort signal). resolvedVol{Index, Target, Scope, LivePath}. Reuses the SAME supportedScopes map.
  • swap helpers (C2 + R2 + R3): staging is sibling to the live dir's parent so renames are same-filesystem. stagingRoot(live string) string = filepath.Join(filepath.Dir(live), ".tf-restore-"+token). swapVolumeDir(live, tmp, old string) error = rename(live→old) then rename(tmp→live); detect EXDEV/cross-device and return a clear error WITHOUT having moved anything irreversibly (check device equivalence up-front or treat the rename error as fatal/rollback). rollbackSwaps(done []swap) error = for each completed swap in reverse, rename(live→discard), rename(old→live).
  • freeDiskBytes(path string) (uint64, error) — platform helper. Build-tag split mirroring the repo's lockfile_windows.go/lockfile_unix.go precedent: disk_unix.go (//go:build !windows, syscall.Statfs) + disk_windows.go (golang.org/x/sys/windows.GetDiskFreeSpaceEx). Production target is Linux.
• Constants: maxRestoreUncompressedBytes (decompression-bomb cap) + diskFreeSafetyMargin named consts with rationale comments.

Files to Modify/Create

• internal/volsnap/extract.go — untrusted extractor (new)
• internal/volsnap/restore.go — primitives: sizing, manifest parse, preflight, swap/rollback, free-disk (new)
• internal/volsnap/disk_unix.go, internal/volsnap/disk_windows.go — free-disk platform split (new)
• internal/volsnap/extract_test.go, internal/volsnap/restore_test.go — unit tests (new)
• go.mod — golang.org/x/sys promoted indirect→direct (already present v0.33.0)

Acceptance Criteria

• Zip-slip (../, absolute, ..\\ on win), symlink, hardlink, device, fifo entries all rejected by safeExtractIndex.
• Decompression-bomb cap aborts extraction + sizing past the cap.
• Happy-path extract round-trip restores file tree + contents byte-for-byte under dest.
• swapVolumeDir + rollbackSwaps: full and PARTIAL-swap rollback leave the original live dirs byte-identical.
• preflightResolve is all-or-nothing: one unresolvable/unsupported-scope volume → error, and the caller renames nothing.
• archiveUncompressedSize matches the real extracted total.
• go test ./internal/volsnap/..., go build ./..., go vet ./internal/... all green.

Notes

• Open the archive once per pass; on Unix an open fd survives a concurrent Delete unlink (defence against a racing snapshot delete); Windows refuses delete of an open file. Acceptable.
• safeExtractIndex writes into a caller-provided dest (the staging tmp), never directly onto the live path — the swap is a separate step (C2).

Review Checklist

• All tasks completed
• Code follows project conventions (gofmt, wrapped errors, small funcs)
• No unintended side effects (no change to Create/List/Delete)
• Build passes
• Tests pass (new + existing)

Handoff to Next Phase

Implemented files: extract.go (safeExtractIndex, stripIndexPrefix, leadingIndex, withinDir), restore.go (parseManifest, preflightResolve, archiveUncompressedSize, swap/swapVolumeDir/rollbackSwaps/stagingDirs, consts maxRestoreUncompressedBytes = 50 GiB, diskFreeHeadroomBytes = 256 MiB), disk_unix.go/disk_windows.go (freeDiskBytes). Tests in extract_test.go + restore_test.go. go.mod: x/sys → direct.

API contract for Phase 2 (Engine.Restore):

• safeExtractIndex(archivePath, index, dest, bombCap) — extracts ONE volume's subtree into a FRESH dest (uses O_EXCL); returns bytes written. Call once per resolved volume into its tmp staging dir.
• preflightResolve(w, settings, manifest) → []resolvedVol{Index,Target,Scope,LivePath}, ALL-OR-NOTHING; already rejects unsupported scopes AND negative indices. Run BEFORE Lock/StopContainers.
• stagingDirs(live, token, index) → (tmp, old) siblings of filepath.Dir(live) (same-fs ⇒ atomic rename). Use a per-restore token.
• swapVolumeDir(live, tmp, old) → (hadOld, err); self-reverts the first rename on failure (live never left missing). Collect each completed swap into []swap{live,old,tmp,hadOld} and call rollbackSwaps(done) on any later failure.
• archiveUncompressedSize(archivePath, bombCap) → (perIndex map[int]int64, total, err) for the C5 per-filesystem free-disk check. NOTE: it's a LOWER-BOUND (ignores dir/inode overhead) — treat as advisory; the staged-extract+swap is the real net.
• freeDiskBytes(path) — pass the live dir's PARENT (where tmp/old land).

Phase 2 must: extract ALL tmp dirs first, THEN swap all (shrinks the destructive window); validate each manifest index maps to an existing archive subtree (W2 — only the negative check is done so far); the disk pre-check should sum per-target-filesystem.

Review (go-reviewer, APPROVE WITH NOTES): no blockers. Addressed in-phase: W2 (negative index reject), W3 (explicit second-rename self-revert test), W4 (stagingDirs test), N1/N2/N4 (comments + sparse-type rejection test). W1 (disk estimate is lower-bound) folded into Phase 2 guidance above.