[PR #324] fix(p2p): resolve OSS layers through digest facade #349

New issue

Open

opened 2026-10-29 14:22:30 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:22:30 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/324
Author: @WindSongShaoGe
Created: 9/28/2026
Status: 🔄 Open

Base: main ← Head: fix/p2p-digest-oss-read

📝 Commits (1)

c081818 fix(p2p): resolve OSS layers through digest facade

📊 Changes

4 files changed (+585 additions, -21 deletions)

View changed files

📝 docs/src/internals/p2p-design.md (+3 -1)
📝 src/overlaybd/p2p/facade.rs (+144 -13)
📝 storage/overlaybd/src/image/image_file.rs (+367 -6)
📝 storage/overlaybd/src/image/image_service.rs (+71 -1)

📄 Description

What

Resolve digest-only OSS snapshot layers through the P2P facade. Preserve UUID-first reads and fall back to the origin when peer opens or subsequent reads fail.

Why

PR #304 publishes layers under their committed digest, including compressed and descriptorless uploads. Consumers still only try the UUID facade before opening OSS, so layers without a UUID cannot use those providers. A successful peer open also needs origin fallback if later reads fail.

Follow-up to #304. No issue-closing claim.

Scope and non-goals

Includes the digest read route, lazy origin fallback, focused regression tests, and design documentation. The dedicated two-node full-chain test harness will be submitted separately. No publication changes, TCP_NODELAY tuning, or snapshot-format changes.

Design and behavior changes

Add /p2p-digest/{digest} using the existing canonical layer identity, descriptor validation, and bounded Range handling shared with the UUID route.
Try UUID when available, then digest, then the existing origin path for remote layers. Preserve explicit local-file behavior.
Keep direct peer HTTP reads separate from OSS and origin-cache initialization. Construct the peer client and dispatch its I/O on the service's existing pinned remote-I/O runtime.
Lazily reopen the origin with its tar/ZFile adapters after a peer read fails. Healthy peer opens and reads issue no origin requests.
Test digest hits, UUID misses followed by digest hits, missing providers, real registry-client probes/range reads, and read-time fallback for raw, compressed, and UUID-addressed layers.

Compatibility and operations

Public API or generated protocol: adds an internal loopback facade route; no public API or generated schema changes.
Configuration or defaults: unchanged.
Snapshot manifest, artifact layout, or storage format: unchanged; reuse existing layer keys and metadata.
Upgrade and rollback: deploy matching server and ublk-daemon builds. No data migration. Rolling back removes digest peer reads while retaining origin access.
Host requirements, permissions, ports, or dependencies: unchanged; reuse the existing facade listener.

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

Commands and results:

cargo test -p overlaybd --lib image::
49 passed

cargo test -p overlaybd --lib backend::registryfs_v2::tests
18 passed

cargo test -p agentenv --lib overlaybd::p2p::
26 passed

make fmt
passed

make clippy
passed (workspace, all targets/features, -D warnings)

git diff --check
passed

Negative controls: temporarily disabling digest lookup makes the digest-hit regression fail; removing read-time fallback makes the peer-loss regression fail; eagerly initializing the origin runtime makes the lazy-initialization regression fail. All mutations were reverted before the final successful checks.

Skipped checks and reasons: no aggregate capability/VM suites or two-node full-chain E2E rerun for this focused read-side change. Tests use local HTTP fixtures and mock P2P descriptors independently of publication. Historical full-chain results do not validate this exact commit. No Go/schema changes or performance benchmark.

Risks and reviewer notes

Digest probing adds a peer lookup before origin fallback. Review the lazy fallback's tar/ZFile reopening and the peer client's pinned-runtime lifecycle. The facade itself does not hold OSS credentials or perform OSS fallback. End-to-end snapshot recovery depends on both #304's publication fix and this read-side change and will be validated with the subsequent full-chain test PR.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 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/324 **Author:** [@WindSongShaoGe](https://github.com/WindSongShaoGe) **Created:** 9/28/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/p2p-digest-oss-read` --- ### 📝 Commits (1) - [`c081818`](https://github.com/kvcache-ai/AgentENV/commit/c081818586fc947fa880ddde9daf20d23102bb03) fix(p2p): resolve OSS layers through digest facade ### 📊 Changes **4 files changed** (+585 additions, -21 deletions) <details> <summary>View changed files</summary> 📝 `docs/src/internals/p2p-design.md` (+3 -1) 📝 `src/overlaybd/p2p/facade.rs` (+144 -13) 📝 `storage/overlaybd/src/image/image_file.rs` (+367 -6) 📝 `storage/overlaybd/src/image/image_service.rs` (+71 -1) </details> ### 📄 Description ## What Resolve digest-only OSS snapshot layers through the P2P facade. Preserve UUID-first reads and fall back to the origin when peer opens or subsequent reads fail. ## Why PR #304 publishes layers under their committed digest, including compressed and descriptorless uploads. Consumers still only try the UUID facade before opening OSS, so layers without a UUID cannot use those providers. A successful peer open also needs origin fallback if later reads fail. ## Related issue Follow-up to #304. No issue-closing claim. ## Scope and non-goals Includes the digest read route, lazy origin fallback, focused regression tests, and design documentation. The dedicated two-node full-chain test harness will be submitted separately. No publication changes, TCP_NODELAY tuning, or snapshot-format changes. ## Design and behavior changes - Add `/p2p-digest/{digest}` using the existing canonical layer identity, descriptor validation, and bounded Range handling shared with the UUID route. - Try UUID when available, then digest, then the existing origin path for remote layers. Preserve explicit local-file behavior. - Keep direct peer HTTP reads separate from OSS and origin-cache initialization. Construct the peer client and dispatch its I/O on the service's existing pinned remote-I/O runtime. - Lazily reopen the origin with its tar/ZFile adapters after a peer read fails. Healthy peer opens and reads issue no origin requests. - Test digest hits, UUID misses followed by digest hits, missing providers, real registry-client probes/range reads, and read-time fallback for raw, compressed, and UUID-addressed layers. ## Compatibility and operations - Public API or generated protocol: adds an internal loopback facade route; no public API or generated schema changes. - Configuration or defaults: unchanged. - Snapshot manifest, artifact layout, or storage format: unchanged; reuse existing layer keys and metadata. - Upgrade and rollback: deploy matching server and ublk-daemon builds. No data migration. Rolling back removes digest peer reads while retaining origin access. - Host requirements, permissions, ports, or dependencies: unchanged; reuse the existing facade listener. ## Validation - [x] `make fmt` - [x] `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 - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text cargo test -p overlaybd --lib image:: 49 passed cargo test -p overlaybd --lib backend::registryfs_v2::tests 18 passed cargo test -p agentenv --lib overlaybd::p2p:: 26 passed make fmt passed make clippy passed (workspace, all targets/features, -D warnings) git diff --check passed ``` Negative controls: temporarily disabling digest lookup makes the digest-hit regression fail; removing read-time fallback makes the peer-loss regression fail; eagerly initializing the origin runtime makes the lazy-initialization regression fail. All mutations were reverted before the final successful checks. Skipped checks and reasons: no aggregate capability/VM suites or two-node full-chain E2E rerun for this focused read-side change. Tests use local HTTP fixtures and mock P2P descriptors independently of publication. Historical full-chain results do not validate this exact commit. No Go/schema changes or performance benchmark. ## Risks and reviewer notes Digest probing adds a peer lookup before origin fallback. Review the lazy fallback's tar/ZFile reopening and the peer client's pinned-runtime lifecycle. The facade itself does not hold OSS credentials or perform OSS fallback. End-to-end snapshot recovery depends on both #304's publication fix and this read-side change and will be validated with the subsequent full-chain test PR. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-29 14:22:30 +00:00

bsakaguchi referenced this issue

2026-10-29 14:22:40 +00:00

[PR #347] [MERGED] feat(image): build and publish reusable images with the CLI #367

bsakaguchi referenced this issue

2026-10-29 14:22:42 +00:00

[PR #349] feat(compose): run Compose projects in isolated sandboxes #368

bsakaguchi referenced this issue

2026-10-29 14:22:42 +00:00