[PR #224] [MERGED] feat(overlaybd): seal a writable upper into a layer in place #266

New issue

Closed

opened 2026-10-29 14:21:38 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:21:38 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/224
Author: @huang-jl
Created: 8/27/2026
Status: ✅ Merged
Merged: 8/28/2026
Merged by: @yingdi-shan

Base: main ← Head: hjl/overlaybd-seal-upper

📝 Commits (2)

14a1bd5 feat(overlaybd): seal a writable upper into a layer
c00bd4b feat(overlaybd): expose the layer file-name constants

📊 Changes

2 files changed (+215 additions, -11 deletions)

View changed files

📝 storage/overlaybd/src/image/image_file.rs (+206 -9)
📝 storage/overlaybd/src/layer/layer_metadata.rs (+9 -2)

📄 Description

What

Adds ImageFile::close_seal(output_layer_path), which seals the writable upper into a self-contained layer and moves it to the given path. It appends a compact index and a trailer to the data file already on disk and renames it, so the upper becomes the layer instead of being copied into one.

Also promotes COMMIT_FILE_NAME and SEALED_FILE_NAME from pub(crate) to pub, since anything that writes a layer has to use one of those names for the result to be findable from a LayerConfig that carries only a directory.

Why

The two existing entry points both do more than sealing. create_snapshot_and_restack seals the upper and then creates a fresh upper and restacks the lowers, which is what a caller that has to keep serving needs. export_upper_as_sealed seals by compacting into a new file, which copies every byte the guest wrote.

Some callers need neither: they are done with the image and only want the upper to become a layer. For them the restack is unnecessary work and the copy is proportional to the data written — a rename does the same job.

Design and behavior changes

No changes for existing behaviors, only add extra interfaces for overlaybd crate users.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/224 **Author:** [@huang-jl](https://github.com/huang-jl) **Created:** 8/27/2026 **Status:** ✅ Merged **Merged:** 8/28/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `hjl/overlaybd-seal-upper` --- ### 📝 Commits (2) - [`14a1bd5`](https://github.com/kvcache-ai/AgentENV/commit/14a1bd50b6a495c22c82b4291c54210f03ad223a) feat(overlaybd): seal a writable upper into a layer - [`c00bd4b`](https://github.com/kvcache-ai/AgentENV/commit/c00bd4bf72efda2cf6b3ee892e9e16ffa2642ce2) feat(overlaybd): expose the layer file-name constants ### 📊 Changes **2 files changed** (+215 additions, -11 deletions) <details> <summary>View changed files</summary> 📝 `storage/overlaybd/src/image/image_file.rs` (+206 -9) 📝 `storage/overlaybd/src/layer/layer_metadata.rs` (+9 -2) </details> ### 📄 Description ## What Adds ImageFile::close_seal(output_layer_path), which seals the writable upper into a self-contained layer and moves it to the given path. It appends a compact index and a trailer to the data file already on disk and renames it, so the upper becomes the layer instead of being copied into one. Also promotes COMMIT_FILE_NAME and SEALED_FILE_NAME from pub(crate) to pub, since anything that writes a layer has to use one of those names for the result to be findable from a LayerConfig that carries only a directory. ## Why The two existing entry points both do more than sealing. create_snapshot_and_restack seals the upper and then creates a fresh upper and restacks the lowers, which is what a caller that has to keep serving needs. export_upper_as_sealed seals by compacting into a new file, which copies every byte the guest wrote. Some callers need neither: they are done with the image and only want the upper to become a layer. For them the restack is unnecessary work and the copy is proportional to the data written — a rename does the same job. ## Design and behavior changes No changes for existing behaviors, only add extra interfaces for overlaybd crate users. ## Validation  - [x] `make fmt` - [x] `make clippy` - [x] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [ ] Documentation updated - [ ] Benchmarks or performance comparison completed --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:21:38 +00:00