[PR #19] [MERGED] feat: expose snapshot rootfs image references #121

New issue

Closed

opened 2026-10-29 14:19:55 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:19:55 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/19
Author: @huajq
Created: 7/27/2026
Status: ✅ Merged
Merged: 7/29/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/snapshot-image-ref

📝 Commits (1)

a749482 feat: expose snapshot rootfs image references

📊 Changes

17 files changed (+447 additions, -86 deletions)

View changed files

📝 config/default.toml (+11 -6)
📝 config/oss_default.toml (+12 -6)
📝 crates/aenv/src/client/snapshots.rs (+28 -1)
📝 crates/aenv/src/commands/snapshot.rs (+9 -0)
📝 docs/src/concepts/snapshots.md (+32 -0)
📝 docs/src/configuration/reference.md (+8 -0)
📝 docs/src/getting-started/aenv-cli.md (+4 -0)
📝 src/api/generated/src/models.rs (+16 -0)
📝 src/api/impls/snapshots.rs (+39 -0)
📝 src/api/openapi.yml (+6 -0)
📝 src/snapshot/mod.rs (+1 -0)
📝 src/snapshot/repository/backends/common/acr/client.rs (+125 -24)
📝 src/snapshot/repository/backends/common/acr/manifest.rs (+32 -0)
📝 src/snapshot/repository/backends/common/acr/publisher.rs (+37 -41)
📝 src/snapshot/repository/backends/common/acr/source_image.rs (+25 -6)
📝 src/snapshot/types/mod.rs (+1 -1)
📝 src/snapshot/types/snapshot.rs (+61 -1)

📄 Description

Summary

Expose the existing source-registry snapshot rootfs publication as an optional imageRef in snapshot API and CLI responses.

Image publication remains part of snapshot creation and still requires the OSS snapshot backend with [snapshot.image_publish].enabled = true. This PR does not add a separate export endpoint or CLI command.

Fixes #16.

Changes

Add an optional imageRef to snapshot create, GET, and list responses.
Print the published image after aenv snapshot create.
Add an IMAGE REF column and optional JSON field to aenv snapshot list.
Select rootfs publications by their exact deterministic tag so attached-drive publications cannot be exposed accidentally.
Publish an OCI manifest and snapshot tag even when the rootfs contains only existing remote layers.
Keep remote OverlayBD layers referenced by digest without downloading or uploading them again.
Add the exact publication tag to OCI manifest annotations so otherwise identical snapshot publications receive distinct manifest digests.
Delete registry publications before discarding their persisted snapshot metadata, allowing failed cleanup to be retried.
Leave stale alias cleanup to the existing lookup/bind path to avoid races with concurrent alias rebinding.
Reject invalid persisted registry publication metadata instead of silently discarding cleanup information.
Reject HTTPS-to-HTTP registry redirects and limit redirect chains to 10 hops.
Update snapshot image publication configuration, concepts, and CLI documentation.

Compatibility

imageRef is optional and omitted when no rootfs image was published.
Existing snapshot records remain readable.
Older clients can ignore the new response field.
Standard OCI images converted to local OverlayBD layers retain the existing object-storage fallback.
No new endpoint, background task, dependency, or persistent schema migration is introduced.

Performance

Existing remote layers are referenced by digest and are not re-uploaded.
Local delta blobs retain digest-based existence checks and upload deduplication.
All-remote publication performs only registry metadata requests and a manifest PUT.
Snapshot GET/list performs only an in-memory publication lookup and does not access the registry.
Layer and config blobs remain content-addressed and shared; only manifests are publication-specific.

Testing

Validated on the remote Linux test host:

cargo test -p agentenv --lib
640 passed, 0 failed, 2 ignored

cargo test -p aenv
23 passed, 0 failed

Additional checks:

cargo clippy -p agentenv -p aenv --all-targets -- -D warnings
cargo fmt --all -- --check
git diff --check

The tests cover:

all-remote publication through the existing fake registry;
remote-only publication without layer uploads;
publication-specific manifest digests;
rootfs versus attached-drive publication selection;
optional API and CLI imageRef serialization;
invalid persisted publication metadata;
HTTPS redirect enforcement;
existing blob deduplication, chunked upload, and manifest deletion behavior.

_{🔄 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/19 **Author:** [@huajq](https://github.com/huajq) **Created:** 7/27/2026 **Status:** ✅ Merged **Merged:** 7/29/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/snapshot-image-ref` --- ### 📝 Commits (1) - [`a749482`](https://github.com/kvcache-ai/AgentENV/commit/a749482568a3dc9ec1eb2b453a81ee0693b3d4ce) feat: expose snapshot rootfs image references ### 📊 Changes **17 files changed** (+447 additions, -86 deletions) <details> <summary>View changed files</summary> 📝 `config/default.toml` (+11 -6) 📝 `config/oss_default.toml` (+12 -6) 📝 `crates/aenv/src/client/snapshots.rs` (+28 -1) 📝 `crates/aenv/src/commands/snapshot.rs` (+9 -0) 📝 `docs/src/concepts/snapshots.md` (+32 -0) 📝 `docs/src/configuration/reference.md` (+8 -0) 📝 `docs/src/getting-started/aenv-cli.md` (+4 -0) 📝 `src/api/generated/src/models.rs` (+16 -0) 📝 `src/api/impls/snapshots.rs` (+39 -0) 📝 `src/api/openapi.yml` (+6 -0) 📝 `src/snapshot/mod.rs` (+1 -0) 📝 `src/snapshot/repository/backends/common/acr/client.rs` (+125 -24) 📝 `src/snapshot/repository/backends/common/acr/manifest.rs` (+32 -0) 📝 `src/snapshot/repository/backends/common/acr/publisher.rs` (+37 -41) 📝 `src/snapshot/repository/backends/common/acr/source_image.rs` (+25 -6) 📝 `src/snapshot/types/mod.rs` (+1 -1) 📝 `src/snapshot/types/snapshot.rs` (+61 -1) </details> ### 📄 Description ## Summary Expose the existing source-registry snapshot rootfs publication as an optional `imageRef` in snapshot API and CLI responses. Image publication remains part of snapshot creation and still requires the OSS snapshot backend with `[snapshot.image_publish].enabled = true`. This PR does not add a separate export endpoint or CLI command. Fixes #16. ## Changes - Add an optional `imageRef` to snapshot create, GET, and list responses. - Print the published image after `aenv snapshot create`. - Add an `IMAGE REF` column and optional JSON field to `aenv snapshot list`. - Select rootfs publications by their exact deterministic tag so attached-drive publications cannot be exposed accidentally. - Publish an OCI manifest and snapshot tag even when the rootfs contains only existing remote layers. - Keep remote OverlayBD layers referenced by digest without downloading or uploading them again. - Add the exact publication tag to OCI manifest annotations so otherwise identical snapshot publications receive distinct manifest digests. - Delete registry publications before discarding their persisted snapshot metadata, allowing failed cleanup to be retried. - Leave stale alias cleanup to the existing lookup/bind path to avoid races with concurrent alias rebinding. - Reject invalid persisted registry publication metadata instead of silently discarding cleanup information. - Reject HTTPS-to-HTTP registry redirects and limit redirect chains to 10 hops. - Update snapshot image publication configuration, concepts, and CLI documentation. ## Compatibility - `imageRef` is optional and omitted when no rootfs image was published. - Existing snapshot records remain readable. - Older clients can ignore the new response field. - Standard OCI images converted to local OverlayBD layers retain the existing object-storage fallback. - No new endpoint, background task, dependency, or persistent schema migration is introduced. ## Performance - Existing remote layers are referenced by digest and are not re-uploaded. - Local delta blobs retain digest-based existence checks and upload deduplication. - All-remote publication performs only registry metadata requests and a manifest PUT. - Snapshot GET/list performs only an in-memory publication lookup and does not access the registry. - Layer and config blobs remain content-addressed and shared; only manifests are publication-specific. ## Testing Validated on the remote Linux test host: ```text cargo test -p agentenv --lib 640 passed, 0 failed, 2 ignored cargo test -p aenv 23 passed, 0 failed ``` Additional checks: ```text cargo clippy -p agentenv -p aenv --all-targets -- -D warnings cargo fmt --all -- --check git diff --check ``` The tests cover: - all-remote publication through the existing fake registry; - remote-only publication without layer uploads; - publication-specific manifest digests; - rootfs versus attached-drive publication selection; - optional API and CLI `imageRef` serialization; - invalid persisted publication metadata; - HTTPS redirect enforcement; - existing blob deduplication, chunked upload, and manifest deletion behavior. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:19:55 +00:00