feat(cli): first-class fbuild cache save/restore/list/verify (#527)

[zackees]

Fixes#527.

What

A first-class fbuild cache subcommand that packs the fbuild cache into one portable .tar.zst, replacing the fragile six-path actions/cache@v4 workaround every consumer grows.

• fbuild-packages::cache_archive — engine: hand-written prost manifest (no protoc), zstd(9) tar, content-hash (not mtime) per-slice fingerprints. Slices: toolchains, platforms, packages, libraries, archives, installed, index.sqlite (default) + zccache (opt-in). save/restore/read_manifest/verify.
• fbuild cache save|restore|list|verify — thin in-process CLI (like port scan/lnk): --include/--exclude/--zstd-level/--cache-dir; list dumps the manifest, verify re-hashes every slice.

Scope

v1 is a full snapshot. Delta archives, mtime replay, and a zccache gha-cache sidecar are deferred to v2 (per the issue); the zccache store is available as a normal opt-in slice meanwhile.

Verified locally (end-to-end, real dirs)

cache save → saved 7 slice(s), 3 file(s), 28 B → … (470 B compressed)
cache list → per-slice inventory + hashes
cache verify → … VERIFIED OK
cache restore→ diff -r vs source: IDENTICAL ROUND-TRIP

8 tests green (engine round-trip / verify / include−exclude / corruption-detect / CLI layer); clippy + fmt clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a new fbuild cache command with options to save, restore, list, and verify cache archives.
  • Cache snapshots can now be packaged into a portable .tar.zst file and restored later.
  • Added archive integrity checks and manifest reporting for cache contents.

• Bug Fixes

  • Improved restore safety by rejecting unsafe archive paths and skipping unknown entries when appropriate.
  • Added verification to detect corrupted or mismatched cache data.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8763fbab-92b5-4968-8c02-c012e64eef0d

📥 Commits

Reviewing files that changed from the base of the PR and between f079d72 and 398e067.

📒 Files selected for processing (7)

• crates/fbuild-cli/src/cli/args.rs
• crates/fbuild-cli/src/cli/cache.rs
• crates/fbuild-cli/src/cli/dispatch.rs
• crates/fbuild-cli/src/cli/mod.rs
• crates/fbuild-packages/Cargo.toml
• crates/fbuild-packages/src/cache_archive.rs
• crates/fbuild-packages/src/lib.rs

---

📝 Walkthrough

Walkthrough

Adds a new "fbuild cache" CLI subcommand (save/restore/list/verify) backed by a new fbuild-packages cache_archive module that produces a manifest-based .tar.zst archive of cache slices (toolchains, platforms, packages, libraries, archives, installed, index.sqlite, optional zccache), with hash-based verification and safe restore.

Changes

Cache archive feature

Layer / File(s)	Summary
Manifest types and slice registry crates/fbuild-packages/src/cache_archive.rs	Defines format/manifest constants, the slice registry, SliceInfo/CacheManifest prost types, and internal helpers for enumerating slice files and computing stable sha256 content hashes.
Archive save/write implementation crates/fbuild-packages/src/cache_archive.rs	Adds SliceSelection, manifest construction with per-slice hashing, and deterministic tar+zstd archive writing with compression level clamping.
Manifest read and integrity verification crates/fbuild-packages/src/cache_archive.rs	Adds read_manifest to locate/decode the manifest entry and verify to re-hash payload entries per slice and compare against recorded hashes.
Archive restore implementation crates/fbuild-packages/src/cache_archive.rs	Adds restore, enforcing format-version compatibility, path-traversal rejection, unknown-slice skipping, and single-file/directory-tree replay into a target cache dir.
cache_archive test suite crates/fbuild-packages/src/cache_archive.rs	Adds tests for round-trip save/restore, manifest consistency, verify on clean archives, include/exclude selection, unknown-slice errors, and corruption detection.
CLI wiring and dependency for cache subcommand crates/fbuild-cli/src/cli/args.rs, crates/fbuild-cli/src/cli/mod.rs, crates/fbuild-cli/src/cli/dispatch.rs, crates/fbuild-packages/Cargo.toml, crates/fbuild-packages/src/lib.rs	Adds Commands::Cache variant, exports the cache and cache_archive modules, wires dispatch to run_cache, and adds the prost workspace dependency.
CacheAction implementation and output formatting crates/fbuild-cli/src/cli/cache.rs	Implements CacheAction and run_cache dispatching Save/Restore/List/Verify to cache_archive, render_saved/render_manifest output formatting, human_bytes conversion, and CLI-layer tests including a roundtrip test.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
participant CLI as fbuild CLI
participant Dispatch as dispatch::async_main
participant Cache as cache::run_cache
participant Archive as cache_archive
CLI->>Dispatch: fbuild cache save --archive out.tar.zst
Dispatch->>Cache: run_cache(CacheAction::Save)
Cache->>Archive: save(cache_dir, out_archive, selection, exclude, zstd_level)
Archive->>Archive: enumerate slices, hash content, build manifest
Archive->>Archive: write manifest + slices as tar.zst
Archive-->>Cache: CacheManifest
Cache-->>CLI: render_saved(manifest, archive size)
CLI->>Dispatch: fbuild cache verify --archive out.tar.zst
Dispatch->>Cache: run_cache(CacheAction::Verify)
Cache->>Archive: verify(archive)
Archive->>Archive: read_manifest + re-hash payload entries
Archive-->>Cache: CacheManifest (verified)
Cache-->>CLI: render_manifest(manifest, verified=true)
CLI->>Dispatch: fbuild cache restore --archive out.tar.zst
Dispatch->>Cache: run_cache(CacheAction::Restore)
Cache->>Archive: restore(archive, cache_dir)
Archive->>Archive: replay entries, skip unknown slices, reject ".." paths
Archive-->>Cache: CacheManifest
Cache-->>CLI: print restore summary

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/527-fbuild-cache-save-restore

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}