[PR #38] [MERGED] feat: add standalone aenv-snapshot-image export tool #133

New issue

Closed

opened 2026-10-29 14:20:04 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:20:04 +00:00

Owner

📋 Pull Request Information

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

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

📝 Commits (1)

a5f6f2b feat: add standalone aenv-snapshot-image export tool

📊 Changes

20 files changed (+1409 additions, -29 deletions)

View changed files

📝 CLAUDE.md (+2 -0)
📝 Makefile (+4 -0)
📝 docs/src/concepts/snapshots.md (+27 -0)
➕ src/bin/aenv-snapshot-image.rs (+110 -0)
📝 src/image/oci_image.rs (+7 -4)
➕ src/snapshot/image_export/mod.rs (+8 -0)
➕ src/snapshot/image_export/regctl.rs (+370 -0)
➕ src/snapshot/image_export/service.rs (+649 -0)
➕ src/snapshot/image_export/target.rs (+193 -0)
📝 src/snapshot/mod.rs (+1 -0)
📝 src/snapshot/repository/backends/common/acr/manifest.rs (+11 -0)
📝 src/snapshot/repository/backends/common/acr/mod.rs (+5 -0)
📝 src/snapshot/repository/backends/common/acr/publisher.rs (+3 -14)
📝 src/snapshot/repository/backends/common/acr/source_image.rs (+4 -1)
📝 src/snapshot/repository/backends/mod.rs (+2 -2)
📝 src/snapshot/repository/backends/oss/config.rs (+1 -1)
📝 src/snapshot/repository/backends/oss/layout.rs (+2 -2)
📝 src/snapshot/repository/backends/oss/mod.rs (+4 -3)
📝 src/snapshot/repository/backends/posixfs/layout.rs (+2 -2)
📝 src/snapshot/repository/backends/posixfs/mod.rs (+4 -0)

📄 Description

Motivation

Decouple snapshot storage from image publication: a snapshot is first
committed to the POSIX/OSS repository, and can then be exported on demand
as an OverlayBD-native OCI image in a registry. Stacked on #19.

Changes

Add the standalone agentenv-snapshot-image binary
(make build-snapshot-image; not shipped in the server binary, Docker
image, or install packages).
Reads committed snapshots directly from the POSIX/OSS snapshot repository
and publishes only the rootfs (never attached drives, memory, or VM
state) as an OverlayBD-native OCI image with the existing minimal OCI
config.
All registry I/O goes through regctl: blob head/put/copy, a
cross-registry blob get | blob put child-process pipe, and
manifest head/put; authentication stays with the Docker config.
Target resolution: explicit --target-repository (default tag latest),
otherwise inferred from the canonical rootfs publication or the unique
external source repository (default tag snapshot-<snapshot-id>).
Idempotency and resource bounds: an identical manifest digest short-circuits
as reused, a different one is refused; every layer is probed with
blob head first so existing blobs are neither materialized nor
transferred; POSIX layers are validated in place, OSS layers download one
at a time with size verification. The preflight conflict check is not
atomic (documented).
No new publication state is recorded; exported images live independently
of snapshot deletion, with a warning when the selected reference is
snapshot-managed.
Supporting changes: SourceRegistryRepository::parse accepts
single-segment repositories and normalizes the default :443 port;
docs (snapshots.md) and CLAUDE.md updated.

Testing

6 key tests plus a shared fake regctl: mixed-stack end-to-end publish
(same-registry copy, managed put, cross-registry pipe), manifest
reuse/conflict, legacy publication resolved via registry truth, CLI parsing.
Linux verification: cargo test -p agentenv --lib 645 passed / 0 failed,
--bin agentenv-snapshot-image 1/0,
cargo clippy -p agentenv --all-targets -- -D warnings clean.

_{🔄 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/38 **Author:** [@huajq](https://github.com/huajq) **Created:** 7/28/2026 **Status:** ✅ Merged **Merged:** 7/29/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/snapshot-image-export` --- ### 📝 Commits (1) - [`a5f6f2b`](https://github.com/kvcache-ai/AgentENV/commit/a5f6f2be57cdfe1c341e9d4ebb373360a0c00e10) feat: add standalone aenv-snapshot-image export tool ### 📊 Changes **20 files changed** (+1409 additions, -29 deletions) <details> <summary>View changed files</summary> 📝 `CLAUDE.md` (+2 -0) 📝 `Makefile` (+4 -0) 📝 `docs/src/concepts/snapshots.md` (+27 -0) ➕ `src/bin/aenv-snapshot-image.rs` (+110 -0) 📝 `src/image/oci_image.rs` (+7 -4) ➕ `src/snapshot/image_export/mod.rs` (+8 -0) ➕ `src/snapshot/image_export/regctl.rs` (+370 -0) ➕ `src/snapshot/image_export/service.rs` (+649 -0) ➕ `src/snapshot/image_export/target.rs` (+193 -0) 📝 `src/snapshot/mod.rs` (+1 -0) 📝 `src/snapshot/repository/backends/common/acr/manifest.rs` (+11 -0) 📝 `src/snapshot/repository/backends/common/acr/mod.rs` (+5 -0) 📝 `src/snapshot/repository/backends/common/acr/publisher.rs` (+3 -14) 📝 `src/snapshot/repository/backends/common/acr/source_image.rs` (+4 -1) 📝 `src/snapshot/repository/backends/mod.rs` (+2 -2) 📝 `src/snapshot/repository/backends/oss/config.rs` (+1 -1) 📝 `src/snapshot/repository/backends/oss/layout.rs` (+2 -2) 📝 `src/snapshot/repository/backends/oss/mod.rs` (+4 -3) 📝 `src/snapshot/repository/backends/posixfs/layout.rs` (+2 -2) 📝 `src/snapshot/repository/backends/posixfs/mod.rs` (+4 -0) </details> ### 📄 Description ## Motivation Decouple snapshot storage from image publication: a snapshot is first committed to the POSIX/OSS repository, and can then be exported on demand as an OverlayBD-native OCI image in a registry. Stacked on #19. ## Changes - Add the standalone `agentenv-snapshot-image` binary (`make build-snapshot-image`; not shipped in the server binary, Docker image, or install packages). - Reads committed snapshots directly from the POSIX/OSS snapshot repository and publishes only the rootfs (never attached drives, memory, or VM state) as an OverlayBD-native OCI image with the existing minimal OCI config. - All registry I/O goes through `regctl`: `blob head/put/copy`, a cross-registry `blob get | blob put` child-process pipe, and `manifest head/put`; authentication stays with the Docker config. - Target resolution: explicit `--target-repository` (default tag `latest`), otherwise inferred from the canonical rootfs publication or the unique external source repository (default tag `snapshot-<snapshot-id>`). - Idempotency and resource bounds: an identical manifest digest short-circuits as reused, a different one is refused; every layer is probed with `blob head` first so existing blobs are neither materialized nor transferred; POSIX layers are validated in place, OSS layers download one at a time with size verification. The preflight conflict check is not atomic (documented). - No new publication state is recorded; exported images live independently of snapshot deletion, with a warning when the selected reference is snapshot-managed. - Supporting changes: `SourceRegistryRepository::parse` accepts single-segment repositories and normalizes the default `:443` port; docs (`snapshots.md`) and CLAUDE.md updated. ## Testing - 6 key tests plus a shared fake `regctl`: mixed-stack end-to-end publish (same-registry copy, managed put, cross-registry pipe), manifest reuse/conflict, legacy publication resolved via registry truth, CLI parsing. - Linux verification: `cargo test -p agentenv --lib` 645 passed / 0 failed, `--bin agentenv-snapshot-image` 1/0, `cargo clippy -p agentenv --all-targets -- -D warnings` clean. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:20:04 +00:00