Skip to content

Commit 07e12ec

Browse files
author
Libra Sha256
committed
feat(media): switch to paged protocol and algorithm namespace (MF-02)
Activate fastcdc-v2020-32k object keys, 1MiB envelopes, P-01a paging, page/seal/missing routes, and exists concurrency ≤16. Family child; no bump. Signed-off-by: Libra Sha256 <sha256@example.com>
1 parent 291a97d commit 07e12ec

15 files changed

Lines changed: 1021 additions & 167 deletions

File tree

‎docs/plan/plan-20260913.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -201,15 +201,15 @@ MF-00 no-release继承MF-06;MF-05独立patch发布。单一主代理用Libra
201201

202202
### Task MF-02:协议、容量与空间切换
203203

204-
**Task type:** implementation。**Lifecycle / Acceptance:** pending / 空。
205-
**Description / Current evidence:** `protocol.rs`与`lfs_media.rs:35-47`;`service.rs:224,308`读写包装必须分别限额。
204+
**Task type:** implementation。**Lifecycle / Acceptance:** in-progress / locally-accepted。
205+
**Description / Current evidence:** 命名空间切到 `fastcdc-v2020-32k`;1MiB envelope;分页 prepare/page/seal/missing;capabilities 对齐共享表。
206206
**Acceptance criteria:**
207-
- [ ] 分页摘要/页上传/缺块cursor通过C-02及P-01..02矩阵。
208-
- [ ] capabilities与共享表一致。
209-
- [ ] 旧Media命名空间隔离且不删除。
210-
- [ ] prepare返回唯一hash差集。
211-
- [ ] prepare的存储exists并发不超过16。
212-
**Verification:** `source .env.test && cargo test --features fastcdc --lib ceres::lfs::media::protocol`;`source .env.test && cargo test --features fastcdc lfs_media`。
207+
- [x] 分页摘要/页上传/缺块cursor通过C-02及P-01..02矩阵。
208+
- [x] capabilities与共享表一致。
209+
- [x] 旧Media命名空间隔离且不删除。
210+
- [x] prepare返回唯一hash差集。
211+
- [x] prepare的存储exists并发不超过16。
212+
**Verification:** `source .env.test && cargo test --features fastcdc --lib ceres::lfs::media::protocol` → 11 passed;`source .env.test && cargo test --features fastcdc lfs_media` → lib 11 passed (2026-09-25)。
213213
**Dependencies:** MF-08(A/B通过)。**Implementation write set:** `src/ceres/lfs/media/{protocol,service,scope}.rs`、`src/api/router/lfs_media.rs`、强制同步集。
214214
**Docs and compatibility impact:** FC容量、错误、capabilities、升级恢复同卡。**Rollback mode:** compensating。**Version increment:** N/A。**Release boundary:** family child。**C/D coverage from:** MF-06。**Full-suite trigger:** 继承MF-06。
215215
**Granularity:** `type=implementation; axis=protocol activation; recovery=compensating; complete=yes; self-contained=yes; AC=5/8; VER=2/8; landing=2; prod-files=4; scope=M; deps=MF-08; writeset=serial; release=family child; split-from=N/A; exception=N/A`

‎docs/refactoring/fastcdc-media.md‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,15 @@
66

77
- 算法:`fastcdc-v2020-32k`(`fastcdc = "=3.2.1"`,v2020,Normalization::Level1,seed=0,min/avg/max = 32/64/256 KiB)。旧 `fastcdc-v1`(512 KiB / 2 MiB / 8 MiB)命名空间保留不读写。
88
- Manifest:`version=1`,`hash_algorithm=sha256`,chunk `compression` 固定 `none` 且 `encoded_length == length`。
9-
- Canonical ID:SHA-256(小写 hex)over JSON of `(version, algorithm, hash_algorithm, media_oid, media_size, chunks)`。`created_by` 与 `fallback_oid` 不进入 identity。
10-
- 上限:最多 8192 chunks;manifest JSON ≤ 10 MiB;单 chunk ≤ 8 MiB。
9+
- Canonical ID:SHA-256(小写 hex)over JSON of `(version, algorithm, hash_algorithm, media_oid, media_size, chunks)`。`created_by` 与 `fallback_oid` 不进入 identity;分页边界不参与身份。
10+
- 容量:不设文件字节数/总 chunk 数/总 manifest 大小产品上限。单页 ≤4096 条且紧凑 entries ≤960 KiB;Media metadata 包装(摘要/页/状态)≤ **1 MiB**(`MAX_ENVELOPE_SIZE`);单 chunk ≤ 256 KiB;完整 LFS 流不受页限额。
1111
- `fallback_oid` 若存在必须等于 `media_oid`。
1212
- HTTP 形状(路由由 FC-07 注册,路径以 Libra client 为准):
1313
- capabilities:`GET <repo>.git/info/lfs/libra/media/v1/capabilities`
14-
- prepare:`POST …/manifests` → `{manifest_id, missing_chunks}`
14+
- prepare:`POST …/manifests` → `{manifest_id, missing_chunks}`(唯一 hash 差集;exists 并发 ≤16)
15+
- page:`PUT …/manifests/{id}/pages/{page_no}`
16+
- seal:`POST …/manifests/{id}/seal`
17+
- missing:`GET …/manifests/{id}/missing?cursor=…`
1518
- upload:`PUT …/manifests/{id}/chunks/{hash}`(`application/octet-stream`)
1619
- finalize:`POST …/manifests/{id}/finalize`
1720
- get:`GET …/manifests/by-media/{oid}` → `{manifest_id, manifest}`
@@ -22,7 +25,7 @@
2225
- Namespace 字符串 `media` 只追加,不改 git/lfs/log/artifact/attachment/oci。
2326
- Scope = 服务端 actor + canonical 绝对仓库路径;digest = SHA-256(`actor || 0x00 || repo`)。
2427
Actor 取 `AccessTokenUser` 的 `website_user_id`(非空)否则 `username`。请求体 actor/repository/`created_by` 不得覆盖。
25-
- Object key:`v1/{scope_digest}/{pending|chunk|manifest|finalized}/{id}`,存储路径 `media/` + key(Media 不走 3-level sharding)。
28+
- Object key:`fastcdc-v2020-32k/{scope_digest}/{pending|chunk|manifest|finalized}/{id}`,存储路径 `media/` + key(Media 不走 3-level sharding)。旧前缀 `v1/` 保留不读写、不自动删除。
2629
- 对外错误不泄漏 digest、object key 或认证信息。
2730

2831
## 持久分页状态(FC-16 / MF-08)
@@ -35,20 +38,21 @@
3538

3639
对象存储中的 sealed 页仍是权威页内容;索引可从页重建。`down` 不删除任务数据(compensating:停写后切回旧命名空间)。
3740

41+
## 生命周期(FC-05 prepare / upload / resume)
3842

39-
- `prepare` 只接受已 `validate` 的 manifest,并**强制** `fallback_oid = media_oid`。
40-
- pending 对象:`media/v1/{scope}/pending/{manifest_id}`,逻辑 TTL **24 小时**,JSON ≤ **10 MiB**。过期 session 不能继续 upload/get。
41-
- `missing_chunks` 按 scoped chunk key 检查存在性;重复 `chunk_hash` 在响应中去重(保序)。
42-
- chunk 上传必须命中 pending 声明的 hash/length,并校验实际 SHA-256(≤ 8 MiB)。同 scope 同 hash 的正确对象可幂等复用;已存错误内容返回 Conflict。
43-
- finalize 前只能通过 pending manifest 声明的 hash 读取 chunk,不能按任意 hash 取对象。
43+
- `prepare` 只接受已 `validate` 的 manifest,并**强制** `fallback_oid = media_oid`;写入 `MediaPagingStorage` pending 会话。
44+
- pending 对象:`media/fastcdc-v2020-32k/{scope}/pending/{manifest_id}`,逻辑 TTL **24 小时**,JSON ≤ **1 MiB**。过期 session 不能继续 upload/get。
45+
- `missing_chunks` / missing cursor 按 scoped chunk key 检查存在性;重复 `chunk_hash` 在响应中去重(保序);exists 并发 ≤16。
46+
- chunk 上传必须命中 pending 声明的 hash/length,并校验实际 SHA-256(≤ 256 KiB)。同 scope 同 hash 的正确对象可幂等复用;已存错误内容返回 Conflict。
47+
- finalize 前只能通过 pending/sealed 声明的 hash 读取 chunk,不能按任意 hash 取对象。
4448
- 领域错误:`Invalid` / `NotFound` / `Conflict` / `Storage` / `Io` / `Json`。存储错误对外固定为 `media object store error`。
4549

4650
## Finalize / fallback(FC-06)
4751

48-
- 同时最多 **2** 个 finalize(semaphore)。按 pending 声明的顺序逐块读取(≤8 MiB),写入临时文件并增量 SHA-256。
49-
- 校验整对象 `media_oid`/`media_size` 后,再跑一遍 `fastcdc-v1`:offset/length/hash 必须与 manifest 完全一致。
52+
- 同时最多 **2** 个 finalize(semaphore)。按 pending 声明的顺序逐块读取(≤256 KiB),写入临时文件并增量 SHA-256。
53+
- 校验整对象 `media_oid`/`media_size` 后,再跑一遍 `fastcdc-v2020-32k`:offset/length/hash 必须与 manifest 完全一致(MF-03 将改为覆盖验证、不再要求新鲜 CDC 边界)。
5054
- 缺失或损坏 chunk:**不**写 LFS namespace、**不**写 `lfs_objects`、**不**发布 finalized manifest;临时文件在成功和失败路径都删除。
51-
- 通过后:`put_stream_bounded` 发布到 `lfs/{oid}`,`lfs_objects` 以 `ON CONFLICT (oid) DO NOTHING` 幂等插入,重新读取 metadata 并确认对象存在,然后才写 `media/v1/{scope}/finalized/{media_oid}`。
55+
- 通过后:`put_stream_bounded` 发布到 `lfs/{oid}`,`lfs_objects` 以 `ON CONFLICT (oid) DO NOTHING` 幂等插入,重新读取 metadata 并确认对象存在,然后才写 `media/fastcdc-v2020-32k/{scope}/finalized/{media_oid}`。
5256
- 已存在的 finalized 若 `manifest_id`/`media_oid` 不一致则 Conflict;重复 finalize 在内容一致时成功。
5357

5458
## 出站事件(plan-20260912 / WH-06,已交付)
@@ -63,9 +67,9 @@
6367
- Feature-on 时挂在当前 LFS mount 下:逻辑前缀 `libra/media/v1`。仓库 URL `<repo>.git` 的外部路径是 `<repo>.git/info/lfs/libra/media/v1/...`;OpenAPI 登记为 `/api/v1/lfs/libra/media/v1/...`。Feature-off 不注册这些路由(运行时 404,schema 中也不出现)。
6468
- **每一条** Media 路由(含 capabilities)都要求 `AccessTokenUser`(Bearer)。不复用标准 LFS objects 的「batch 后裸 URL 可不再认证」例外。
6569
- 仓库路径取 URI 改写前保存在 `LfsRepoContext` 的原始前缀(例如 `/acme/app.git`)。缺少合法前缀 → 400。
66-
- Body 上限在 handler 前拒绝:JSON/manifest 路由 `DefaultBodyLimit` 10 MiB;chunk PUT 路由 8 MiB。另有 `Content-Length` 中间件在读 body 前返回 413。
70+
- Body 上限在 handler 前拒绝:JSON/摘要/页路由 `DefaultBodyLimit` **1 MiB**;chunk PUT 路由 **256 KiB**。另有 `Content-Length` 中间件在读 body 前返回 413。
6771
- 错误:Invalid/Json → 400,NotFound → 404,Conflict → 409,Storage/Io → 500 且 body 固定 `media object store error`。
68-
- Capabilities JSON 来自 `Capabilities::v1()`:`fastcdc-v1`、sha256、上限、`supports_batch_exists`、`supports_standard_lfs_fallback`。
72+
- Capabilities JSON 来自 `Capabilities::v1()`:`fastcdc-v2020-32k`、sha256、1 MiB envelope、`batch_exists`/`supports_batch_exists`、`range_read=false`、`standard_lfs_fallback`、`supports_manifest_id_read=true`、`manifest_paging="v1"`、`max_page_entries=4096`、`max_page_bytes=1048576`。
6973
- 普通 LFS `/objects`、`/locks`、`/objects/batch` 行为不变。
7074

7175
固定 fixture:`src/ceres/lfs/media/fixtures/`(合法 `valid_v1.json` / 空文件 `empty.json` / 非法 version 与 fallback)。`valid_v1.json` 字节 SHA-256:`20226243095e92274b3683f4c09bcd12ae35d245b073b38296a2a895c13b8c9d`。

0 commit comments

Comments
 (0)