[PR #426] [CLOSED] feat(image): reclaim idle source and remote caches #430

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/426
Author: @guozy18
Created: 10/23/2026
Status: ❌ Closed

Base: main ← Head: sync/image-cache-idle-eviction

📝 Commits (1)

5fba3dd feat: add idle eviction for image caches

📊 Changes

13 files changed (+362 additions, -47 deletions)

View changed files

📝 config/default.toml (+4 -0)
📝 docs/src/configuration/reference.md (+8 -0)
📝 src/cfg.rs (+11 -0)
📝 src/cfg/image.rs (+12 -0)
📝 src/deps/mod.rs (+4 -1)
📝 src/image/cache/graph.rs (+59 -0)
📝 src/image/cache/service.rs (+85 -9)
📝 src/image/cache/store.rs (+9 -1)
📝 src/orchestrator/tests.rs (+1 -1)
📝 storage/overlaybd/src/backend/cache/full_file_cache/cache_pool.rs (+81 -20)
📝 storage/overlaybd/src/backend/cache/full_file_cache/cache_store.rs (+9 -5)
📝 storage/overlaybd/src/backend/cache/tests.rs (+75 -10)
📝 storage/overlaybd/src/config.rs (+4 -0)

📄 Description

What

Reclaim idle image source configs and closed remote-file cache entries even when cache usage remains below its capacity limit. Both idle thresholds default to zero (disabled).

Why

Capacity eviction alone retains cold image data indefinitely on lightly loaded nodes. Operators can now bound its idle lifetime while retaining the cache and mmap limits already present upstream.

No linked issue. This draft implements an independently usable cache lifecycle improvement.

Scope and non-goals

Source configs backed by cache-owned local commits and closed OverlayBD cache entries. Durable snapshots and live writable storage retain their existing ownership rules.

Design and behavior changes

Source GC reuses the per-image lock, last-use recheck and fail-closed commit GC. Running, paused and operation holds continue to protect commits after a source config is evicted.
Closed-entry idle scans have their own cadence; refill/write capacity passes do not perform idle scans.
Preserve runtime disk/mmap limits, pressure-driven open-entry eviction, zero-data mapped entries, and mmap/disk accounting. Entries opened or touched after selection are rechecked before removal.

Compatibility and operations

Public API or generated protocol: no HTTP changes; adds optional OverlayBD maxIdleSecs.
Configuration or defaults: adds image.cache.gc.max_idle_secs and image.cache.remote_blocks.max_idle_secs, both 0. Existing capacity and open-entry settings remain unchanged.
Snapshot manifest, artifact layout, or storage format: unchanged.
Upgrade and rollback: opt-in policy; evicted cache data is recovered through existing resolution/refill paths. No durable data migration.
Host requirements, permissions, ports, or dependencies: unchanged.

Validation

make fmt equivalent: cargo fmt --all -- --check
make clippy equivalent: cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
Documentation updated

Commands and results:

cargo test --locked -p agentenv --lib: 1021 passed, 4 ignored
cargo test --locked -p overlaybd --lib backend::cache::: 82 passed, 1 ignored
HTTP/KVM test with 1-second GC/idle settings and a separately built server + daemon: passed
- source-config eviction while the sandbox retains its local commit
- fork, snapshot publication, snapshot launch
- pause, server shutdown/restart, resume after source eviction
- commit reclamation after sandbox deletion; sandbox/snapshot cleanup

The focused cache tests exercise idle eviction below capacity, live/paused ownership, open handles, refill after eviction, and the existing capacity/mmap cases. Full OSS/P2P and unrelated suites were not run.

Risks and reviewer notes

Short idle thresholds trade disk retention for more image resolution/download work. The source-config policy applies only when image-cache GC is enabled; running holds can keep commit bytes resident until released.

Checklist

One coherent change; no dependency on another open PR.
Original tests retained and focused regression coverage added.
No credentials or private registry information in the diff.
No generated source was hand-edited.

_{🔄 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/426 **Author:** [@guozy18](https://github.com/guozy18) **Created:** 10/23/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `sync/image-cache-idle-eviction` --- ### 📝 Commits (1) - [`5fba3dd`](https://github.com/kvcache-ai/AgentENV/commit/5fba3dd5499a18e44fdaca132cf851cd2275e2c4) feat: add idle eviction for image caches ### 📊 Changes **13 files changed** (+362 additions, -47 deletions) <details> <summary>View changed files</summary> 📝 `config/default.toml` (+4 -0) 📝 `docs/src/configuration/reference.md` (+8 -0) 📝 `src/cfg.rs` (+11 -0) 📝 `src/cfg/image.rs` (+12 -0) 📝 `src/deps/mod.rs` (+4 -1) 📝 `src/image/cache/graph.rs` (+59 -0) 📝 `src/image/cache/service.rs` (+85 -9) 📝 `src/image/cache/store.rs` (+9 -1) 📝 `src/orchestrator/tests.rs` (+1 -1) 📝 `storage/overlaybd/src/backend/cache/full_file_cache/cache_pool.rs` (+81 -20) 📝 `storage/overlaybd/src/backend/cache/full_file_cache/cache_store.rs` (+9 -5) 📝 `storage/overlaybd/src/backend/cache/tests.rs` (+75 -10) 📝 `storage/overlaybd/src/config.rs` (+4 -0) </details> ### 📄 Description ## What Reclaim idle image source configs and closed remote-file cache entries even when cache usage remains below its capacity limit. Both idle thresholds default to zero (disabled). ## Why Capacity eviction alone retains cold image data indefinitely on lightly loaded nodes. Operators can now bound its idle lifetime while retaining the cache and mmap limits already present upstream. ## Related issue No linked issue. This draft implements an independently usable cache lifecycle improvement. ## Scope and non-goals Source configs backed by cache-owned local commits and closed OverlayBD cache entries. Durable snapshots and live writable storage retain their existing ownership rules. ## Design and behavior changes - Source GC reuses the per-image lock, last-use recheck and fail-closed commit GC. Running, paused and operation holds continue to protect commits after a source config is evicted. - Closed-entry idle scans have their own cadence; refill/write capacity passes do not perform idle scans. - Preserve runtime disk/mmap limits, pressure-driven open-entry eviction, zero-data mapped entries, and mmap/disk accounting. Entries opened or touched after selection are rechecked before removal. ## Compatibility and operations - Public API or generated protocol: no HTTP changes; adds optional OverlayBD `maxIdleSecs`. - Configuration or defaults: adds `image.cache.gc.max_idle_secs` and `image.cache.remote_blocks.max_idle_secs`, both `0`. Existing capacity and open-entry settings remain unchanged. - Snapshot manifest, artifact layout, or storage format: unchanged. - Upgrade and rollback: opt-in policy; evicted cache data is recovered through existing resolution/refill paths. No durable data migration. - Host requirements, permissions, ports, or dependencies: unchanged. ## Validation - [x] `make fmt` equivalent: `cargo fmt --all -- --check` - [x] `make clippy` equivalent: `cargo clippy --locked --workspace --all-targets --all-features -- -D warnings` - [x] Documentation updated Commands and results: ```text cargo test --locked -p agentenv --lib: 1021 passed, 4 ignored cargo test --locked -p overlaybd --lib backend::cache::: 82 passed, 1 ignored HTTP/KVM test with 1-second GC/idle settings and a separately built server + daemon: passed - source-config eviction while the sandbox retains its local commit - fork, snapshot publication, snapshot launch - pause, server shutdown/restart, resume after source eviction - commit reclamation after sandbox deletion; sandbox/snapshot cleanup ``` The focused cache tests exercise idle eviction below capacity, live/paused ownership, open handles, refill after eviction, and the existing capacity/mmap cases. Full OSS/P2P and unrelated suites were not run. ## Risks and reviewer notes Short idle thresholds trade disk retention for more image resolution/download work. The source-config policy applies only when image-cache GC is enabled; running holds can keep commit bytes resident until released. ## Checklist - [x] One coherent change; no dependency on another open PR. - [x] Original tests retained and focused regression coverage added. - [x] No credentials or private registry information in the diff. - [x] No generated source was hand-edited. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

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