Skip to content

Commit 339da97

Browse files
author
Libra Sha256
committed
feat(media): MF-04 fixed-id reads and bounded membership cache
Pin layout reads to finalized/{id} summary, covering pages, and hash-verified chunks; share a ≤128MiB LRU membership cache with per-request scope and pending TTL checks. Signed-off-by: Libra Sha256 <sha256@example.com>
1 parent 95a61fd commit 339da97

8 files changed

Lines changed: 1265 additions & 46 deletions

File tree

‎docs/plan/plan-20260913.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -279,15 +279,15 @@ source .env.test && cargo test --features fastcdc --test integration_fastcdc_lib
279279

280280
### Task MF-04:固定id读取及有界成员缓存
281281

282-
**Task type:** implementation。**Lifecycle / Acceptance:** pending / 空。
283-
**Description / Current evidence:** `lfs_media.rs`读取路由和`service.rs:129,172`重复加载;提供固定id摘要、覆盖页和块读取,页缓存只是性能优化,持久offset索引避免范围查询全量扫描。
282+
**Task type:** implementation。**Lifecycle / Acceptance:** locally-accepted / locally-accepted。
283+
**Description / Current evidence:** 固定 id 摘要/覆盖页/块读取与 ≤128MiB 成员缓存已落地;pending TTL 缓存命中仍强制;跨 scope 拒绝矩阵与损坏块校验已测。
284284
**Acceptance criteria:**
285-
- [ ] 新路由读取immutable布局,与by-media变动无关。
286-
- [ ] 跨actor/repo/非成员hash拒绝矩阵通过。
287-
- [ ] pending TTL在缓存命中时仍有效。
288-
- [ ] C-05字节容量、驱逐及两会话计数通过。
289-
- [ ] 损坏存储块返回失败,不能提供未校验payload。
290-
**Verification:** `source .env.test && cargo test --features fastcdc lfs_media`;`source .env.test && cargo test --features fastcdc --lib ceres::lfs::media`。
285+
- [x] 新路由读取immutable布局,与by-media变动无关。
286+
- [x] 跨actor/repo/非成员hash拒绝矩阵通过。
287+
- [x] pending TTL在缓存命中时仍有效。
288+
- [x] C-05字节容量、驱逐及两会话计数通过。
289+
- [x] 损坏存储块返回失败,不能提供未校验payload。
290+
**Verification:** `source .env.test && cargo test --features fastcdc lfs_media`;`source .env.test && cargo test --features fastcdc --lib ceres::lfs::media`(2026-09-25)。
291291
**Dependencies:** MF-07(A/B通过)。**Implementation write set:** `src/api/router/lfs_media.rs`、`src/ceres/lfs/media/{service,protocol,mod,membership_cache}.rs`(cache新)、强制同步集。
292292
**Docs and compatibility impact:** FC固定id路由、capability、scope与缓存语义。**Rollback mode:** compensating。**Version increment:** N/A。**Release boundary:** family child。**C/D coverage from:** MF-06。**Full-suite trigger:** 继承MF-06。
293293
**Granularity:** `type=implementation; axis=pinned layout reads; recovery=compensating; complete=yes; self-contained=yes; AC=5/8; VER=2/8; landing=2; prod-files=5; scope=M; deps=MF-07; writeset=serial; release=family child; split-from=N/A; exception=N/A`

‎docs/refactoring/fastcdc-media.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@
2020
- finalize:`POST …/manifests/{id}/finalize` → 202 任务(MF-03);`GET …/tasks/{task_id}` 轮询
2121
- get:`GET …/manifests/by-media/{oid}` → `{manifest_id, manifest}`
2222
- chunk download:`GET …/manifests/by-media/{oid}/chunks/{hash}`
23+
- fixed-id summary:`GET …/finalized/{manifest_id}` → `ManifestSummary`
24+
- fixed-id pages:`GET …/finalized/{manifest_id}/pages`
25+
- fixed-id chunk:`GET …/finalized/{manifest_id}/chunks/{hash}`
2326

2427
## Capabilities(共享表)
2528

@@ -59,6 +62,13 @@
5962

6063
`prepare` 在对象存储写入 pending 的同时 `upsert_pending_session`;`put_page` / `seal` / `missing` 走 `MediaPagingStorage` + page blob。
6164

65+
## 固定 id 读取与成员缓存(FC-04 / MF-04)
66+
67+
- `GET …/finalized/{manifest_id}` → `ManifestSummary`(不可变布局;与 by-media 当前发现无关)。
68+
- `GET …/finalized/{manifest_id}/pages`:顺序分页(`cursor`)或覆盖查询(`offset`+`length` 启动,后续 cursor 绑定该范围)。响应含 `page_no`、绝对 `offset_start`/`offset_end`、entries 与 `next_cursor`;单页包装 ≤1 MiB。
69+
- `GET …/finalized/{manifest_id}/chunks/{hash}`:仅当 hash 属于该 id 的 finalized 布局;跨 actor/repo/非成员统一 404;存储块必须重新校验 SHA-256,损坏返回 409,不得返回未校验 payload。
70+
- 成员/页索引缓存(`membership_cache`)按 `(scope_digest, manifest_id)` 计费,总计 ≤**128 MiB**(含索引开销);满后 LRU 驱逐,不拒绝大文件。缓存不跨 scope;pending TTL 在缓存命中时仍逐请求检查(R-MF-04)。
71+
6272
## Prepare / chunk(FC-05)
6373

6474
- `prepare` 只接受已 `validate` 的 manifest(≤1 MiB 包装),并**强制** `fallback_oid = media_oid`;按 P-01a 计算 `page_count`。
@@ -82,7 +92,7 @@
8292
4. 可替换发现 `media/…/manifest/{media_oid}`(by-media;任一完整已发布布局可成为当前值,无需胜者 CAS);
8393
5. 仅在本调用**新写入**不可变记录且已可读后发 `lfs.media.finalized`。
8494
- 同 oid、不同合法布局(不同 `manifest_id`)可并发成功;同 id 重试返回等价 canonical 身份(`created_by` 不参与比较)。不得暴露半 JSON / 错 id。
85-
- `GET …/manifests/by-media/{oid}` 只返回会话已 `finalized` 的完整 `ManifestResponse`。固定 id HTTP 路由见 MF-04;此前可通过存储直读 `finalized/{manifest_id}`。
95+
- `GET …/manifests/by-media/{oid}` 只返回会话已 `finalized` 的完整 `ManifestResponse`。固定 id HTTP 路由见上文「固定 id 读取」;immutable 记录仍可通过存储直读 `finalized/{manifest_id}`。
8696
- 不支持原子完整对象 PUT 的后端必须对 `put_metadata_atomic` 返回明确错误,禁止退化为边写边可见。
8797

8898
## 出站事件(plan-20260912 / WH-06,已交付)

0 commit comments

Comments
 (0)