Skip to content

feat(store): preserve sparse checkpoints in S3 - #133

Closed
neotype wants to merge 1 commit into
cocoonstack:mainfrom
neotype:feat/s3-sparse-checkpoints
Closed

neotype wants to merge 1 commit into
cocoonstack:mainfrom
neotype:feat/s3-sparse-checkpoints

Conversation

@neotype

@neotype neotype commented Sep 3, 2026

Copy link
Copy Markdown

Summary

  • add an opt-in checkpoint_store.s3.sparse format for checkpoint records
  • pack only allocated file extents into bounded 64 MiB S3 objects and reconstruct holes on fetch
  • keep dense records readable and leave sparse writes disabled by default for rolling upgrades
  • validate manifests and paths before materializing a generation

Promoted templates keep their existing digested dense representation; this change targets checkpoint/archive records whose logical raw disk size can be much larger than allocated data.

Storage format

A sparse generation stores ordinary dense files unchanged plus:

  • .sandboxd-sparse-v1/manifest.json
  • .sandboxd-sparse-v1/chunks/<path-hash>/<index>

Each chunk packs up to 64 MiB of allocated extents, avoiding one-object-per-extent explosions. meta.json remains the final commit marker. Fetch supports both old dense generations and the new manifest format.

Rollout

Deploy this reader to every sandboxd node first, then enable "sparse": true cluster-wide. Older sandboxd versions do not understand generations written in the new format.

Verification

  • go test -race ./... in sandboxd
  • GOOS=linux golangci-lint run ./...
  • static Linux/amd64 sandboxd build
  • real MinIO test with a 96 MiB logical sparse file containing a 20 MiB allocated extent, exercising multipart upload and restore

@neotype

neotype commented Sep 3, 2026

Copy link
Copy Markdown
Author

Closing this upstream proposal. We will keep the implementation internal for now.

@neotype neotype closed this Sep 3, 2026
@neotype
neotype deleted the feat/s3-sparse-checkpoints branch September 3, 2026 09:26
@CMGS

CMGS commented Oct 18, 2026

Copy link
Copy Markdown
Contributor

Thanks for this proposal. Sparse S3 checkpoints are now in main through #364: export files are split into 16 MiB SHA-256 chunks, holes are skipped with SEEK_DATA/SEEK_HOLE, all-zero chunks are never uploaded, and a fetch recreates the file at full size, writing only present chunks. It differs from this PR in two ways: chunks are deduplicated across a claim's checkpoints, archives and replicas, and the old dense layout is not kept readable (the upgrade note in docs/deploy.md covers this).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants