Skip to content

Commit 55c3bb0

Browse files
author
Libra Sha256
committed
feat(media): MF-03 coverage verification and bounded async finalize
Drop fresh FastCDC boundary equality; verify sealed pages with continuous cover, per-chunk hash/length, and full oid/size. POST finalize returns 202 task status with lease/no-progress bounds and spawn_blocking disk I/O. Signed-off-by: Libra Sha256 <sha256@example.com>
1 parent d770f5c commit 55c3bb0

8 files changed

Lines changed: 1274 additions & 101 deletions

File tree

‎docs/plan/plan-20260913.md‎

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

237237
### Task MF-03:覆盖验证与有界重组
238238

239-
**Task type:** implementation。**Lifecycle / Acceptance:** pending / 空。
240-
**Description / Current evidence:** `finalize.rs:88-140`去除新鲜CDC限制;发布多布局职责拆出MF-07。
239+
**Task type:** implementation。**Lifecycle / Acceptance:** in-progress / locally-accepted。
240+
**Description / Current evidence:** 移除新鲜 CDC 边界相等;按 sealed 页/`media_entry` 流式校验;P-04a 202 任务 + GET 状态;lease/无进展有界;`spawn_blocking` 写盘。
241241
**Acceptance criteria:**
242-
- [ ] 合法非冷切布局通过重组验证。
243-
- [ ] gap/overlap/overflow/坏hash/坏长度/错误oid拒绝且不发布。
244-
- [ ] finalize按页遍历,不逐块重读pending或保留全量manifest。
245-
- [ ] 持久任务并发上限2,lease及无进展deadline有界,持续进展不受文件总时限限制。
246-
- [ ] 失败/取消temp与许可释放。
247-
- [ ] 磁盘重组不阻塞async executor。
248-
**Verification:** `source .env.test && cargo test --features fastcdc --lib ceres::lfs::media`(新增覆盖、调用计数、取消与deadline用例)。
242+
- [x] 合法非冷切布局通过重组验证。
243+
- [x] gap/overlap/overflow/坏hash/坏长度/错误oid拒绝且不发布。
244+
- [x] finalize按页遍历,不逐块重读pending或保留全量manifest。
245+
- [x] 持久任务并发上限2,lease及无进展deadline有界,持续进展不受文件总时限限制。
246+
- [x] 失败/取消temp与许可释放。
247+
- [x] 磁盘重组不阻塞async executor。
248+
**Verification:** `source .env.test && cargo test --features fastcdc --lib ceres::lfs::media`(新增覆盖、取消与deadline用例,2026-09-25)。
249249
**Dependencies:** MF-02(A/B通过)。**Implementation write set:** `src/ceres/lfs/media/{finalize,service}.rs`、`src/api/router/lfs_media.rs`(任务POST/GET)、`src/jupiter/storage/media_paging_storage.rs`(复用MF-08任务lease)、强制同步集。
250250
**Docs and compatibility impact:** FC-06验证及资源生命周期。**Rollback mode:** compensating。**Version increment:** N/A。**Release boundary:** family child。**C/D coverage from:** MF-06。**Full-suite trigger:** 继承MF-06。
251251
**Granularity:** `type=implementation; axis=bounded coverage verification; recovery=compensating; complete=yes; self-contained=yes; AC=6/8; VER=1/8; landing=3; prod-files=4; scope=M; deps=MF-02; writeset=serial; release=family child; split-from=N/A; exception=N/A`

‎docs/refactoring/fastcdc-media.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
- seal:`POST …/manifests/{id}/seal` → `{manifest_id, seal_generation, page_count}`
1818
- missing:`GET …/manifests/{id}/missing?cursor=` → `{hashes, next_cursor}`
1919
- upload:`PUT …/manifests/{id}/chunks/{hash}`(`application/octet-stream`)
20-
- finalize:`POST …/manifests/{id}/finalize`(MF-03/07 深化异步任务)
20+
- 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}`
2323

@@ -64,12 +64,15 @@
6464
- chunk 上传必须命中 pending 声明的 hash/length,并校验实际 SHA-256(≤ 256 KiB)。同 scope 同 hash 的正确对象可幂等复用;已存错误内容返回 Conflict。
6565
- 领域错误:`Invalid` / `NotFound` / `Conflict` / `Storage` / `Io` / `Json`。存储错误对外固定为 `media object store error`。
6666

67-
## Finalize / fallback(FC-06)
67+
## Finalize / fallback(FC-06 / MF-03)
6868

69-
- 同时最多 **2** 个 finalize(semaphore)。按 pending 声明的顺序逐块读取,写入临时文件并增量 SHA-256。
70-
- 校验整对象 `media_oid`/`media_size` 后,再跑一遍 `fastcdc-v2020-32k`:offset/length/hash 必须与 manifest 完全一致(冷切门;合法非冷切布局由 MF-03 放开)。
71-
- 缺失或损坏 chunk:**不**写 LFS namespace、**不**写 `lfs_objects`、**不**发布 finalized manifest;临时文件在成功和失败路径都删除。
72-
- 通过后:发布到 `lfs/{oid}`,`lfs_objects` 幂等插入,再写 `media/fastcdc-v2020-32k/{scope}/finalized/{media_oid}`。
69+
- 同时最多 **2** 个 finalize(semaphore);活跃排队上限 **128**(超限 429 + `Retry-After`)。
70+
- `POST …/manifests/{id}/finalize` **仅接受 sealed 会话**,返回 **202** `{task_id,manifest_id,state,status_url}`;`status_url` 为同前缀 `libra/media/v1/tasks/{task_id}`(客户端不得跨 origin 跟随或转发 token)。
71+
- `GET …/tasks/{task_id}` 每请求重新做 scope 认证,返回 `state/bytes_verified/pages_verified/retryable/error_code`;`complete` 另含 `oid/size`。
72+
- 验证:按 sealed 页序遍历 `media_entry`,逐块 scoped 读并校验 length/hash;连续覆盖 `media_size`;整对象 SHA-256 须等于 `media_oid`。**不**要求新鲜 FastCDC 冷切边界相等。
73+
- 磁盘写与哈希在 `spawn_blocking`;单次 I/O ≤120s、无进展 ≤10min、lease 60s(约每 20s 续租);持续进展不受整文件墙钟限制。
74+
- 缺失或损坏 chunk / gap / overlap / overflow:**不**写 LFS namespace、**不**写 `lfs_objects`、**不**发布 finalized;临时文件与 lease 在成功/失败/取消路径均释放。
75+
- 通过后:发布到 `lfs/{oid}`,`lfs_objects` 幂等插入,再写 `media/fastcdc-v2020-32k/{scope}/finalized/{media_oid}`(多布局原子发布见 MF-07)。
7376
- 已存在的 finalized 若 `manifest_id`/`media_oid` 不一致则 Conflict;重复 finalize 在内容一致时成功。
7477

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

‎src/api/router/lfs_media.rs‎

Lines changed: 133 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ use crate::{
2424
ceres::lfs::media::{
2525
chunker, finalize,
2626
protocol::{
27-
Capabilities, MAX_ENVELOPE_SIZE, ManifestPage, MediaManifest, MissingChunksResponse,
28-
SealResponse,
27+
Capabilities, FinalizeAcceptedResponse, FinalizeTaskResponse, MAX_ENVELOPE_SIZE,
28+
ManifestPage, MediaManifest, MissingChunksResponse, SealResponse,
2929
},
3030
scope::{MediaObjectKind, MediaScope},
3131
service::{MediaError, MediaService},
@@ -43,6 +43,7 @@ pub fn media_routes() -> OpenApiRouter<MonoApiServiceState> {
4343
.routes(routes!(media_seal))
4444
.routes(routes!(media_missing))
4545
.routes(routes!(media_finalize))
46+
.routes(routes!(media_get_task))
4647
.routes(routes!(media_get_manifest))
4748
.routes(routes!(media_get_chunk))
4849
.layer(DefaultBodyLimit::max(MAX_ENVELOPE_SIZE))
@@ -71,6 +72,14 @@ fn map_media_error(err: MediaError) -> Response {
7172
}
7273
MediaError::NotFound => media_json(StatusCode::NOT_FOUND, "not found"),
7374
MediaError::Conflict(msg) => media_json(StatusCode::CONFLICT, &msg),
75+
MediaError::TooManyRequests => {
76+
let mut response =
77+
media_json(StatusCode::TOO_MANY_REQUESTS, "media finalize queue full");
78+
response
79+
.headers_mut()
80+
.insert("retry-after", HeaderValue::from_static("5"));
81+
response
82+
}
7483
MediaError::Storage | MediaError::Io(_) => media_json(
7584
StatusCode::INTERNAL_SERVER_ERROR,
7685
"media object store error",
@@ -349,11 +358,12 @@ pub async fn media_upload_chunk(
349358
path = "/libra/media/v1/manifests/{manifest_id}/finalize",
350359
params(("manifest_id" = String, Path)),
351360
responses(
352-
(status = 200, description = "Finalized manifest", content_type = "application/json"),
353-
(status = 400, description = "Verification failed"),
361+
(status = 202, description = "Finalize task accepted", content_type = "application/json"),
362+
(status = 400, description = "Session not sealed or invalid"),
354363
(status = 401, description = "Missing or invalid access token"),
355364
(status = 404, description = "Pending session not found"),
356-
(status = 409, description = "Finalized identity conflict"),
365+
(status = 409, description = "Permanent finalize failure"),
366+
(status = 429, description = "Finalize queue full"),
357367
(status = 500, description = "Storage error")
358368
),
359369
tag = MEDIA_TAG
@@ -369,16 +379,47 @@ pub async fn media_finalize(
369379
Err(err) => return map_media_error(err),
370380
};
371381
let media = media_service(&state);
372-
match finalize::finalize(
373-
&media,
374-
&state.storage.lfs_service.lfs_storage,
375-
&scope,
376-
&manifest_id,
377-
&state.storage.storage_event_emitter,
382+
match finalize::enqueue_finalize(
383+
media,
384+
state.storage.lfs_service.lfs_storage.clone(),
385+
scope,
386+
manifest_id,
387+
state.storage.storage_event_emitter.clone(),
378388
)
379389
.await
380390
{
381-
Ok(published) => Json(published).into_response(),
391+
Ok(accepted) => {
392+
let mut response = Json::<FinalizeAcceptedResponse>(accepted).into_response();
393+
*response.status_mut() = StatusCode::ACCEPTED;
394+
response
395+
}
396+
Err(err) => map_media_error(err),
397+
}
398+
}
399+
400+
#[utoipa::path(
401+
get,
402+
path = "/libra/media/v1/tasks/{task_id}",
403+
params(("task_id" = String, Path)),
404+
responses(
405+
(status = 200, description = "Finalize task status", content_type = "application/json"),
406+
(status = 401, description = "Missing or invalid access token"),
407+
(status = 404, description = "Task not found in this scope")
408+
),
409+
tag = MEDIA_TAG
410+
)]
411+
pub async fn media_get_task(
412+
State(state): State<MonoApiServiceState>,
413+
AccessTokenUser(user): AccessTokenUser,
414+
repo: Option<Extension<LfsRepoContext>>,
415+
Path(task_id): Path<String>,
416+
) -> Response {
417+
let scope = match media_scope(&user, repo) {
418+
Ok(scope) => scope,
419+
Err(err) => return map_media_error(err),
420+
};
421+
match finalize::task_status(&media_service(&state), &scope, &task_id).await {
422+
Ok(status) => Json::<FinalizeTaskResponse>(status).into_response(),
382423
Err(err) => map_media_error(err),
383424
}
384425
}
@@ -499,7 +540,10 @@ mod tests {
499540
api_service::cache::GitObjectCache,
500541
lfs::{
501542
digest::LfsDigest,
502-
media::protocol::{ChunkEntry, CreatedBy, PrepareResponse},
543+
media::protocol::{
544+
ChunkEntry, CreatedBy, FinalizeAcceptedResponse, FinalizeTaskResponse,
545+
ManifestPage, PrepareResponse,
546+
},
503547
},
504548
},
505549
contract::policy::entitystore::SharedEntityStore,
@@ -518,6 +562,7 @@ mod tests {
518562
"/libra/media/v1/manifests/{manifest_id}/missing",
519563
"/libra/media/v1/manifests/{manifest_id}/chunks/{chunk_hash}",
520564
"/libra/media/v1/manifests/{manifest_id}/finalize",
565+
"/libra/media/v1/tasks/{task_id}",
521566
"/libra/media/v1/manifests/by-media/{oid}",
522567
"/libra/media/v1/manifests/by-media/{oid}/chunks/{chunk_hash}",
523568
];
@@ -1026,7 +1071,45 @@ mod tests {
10261071
.unwrap();
10271072
assert_eq!(put.status(), StatusCode::OK, "chunk upload");
10281073
}
1029-
let finalized = app
1074+
// MF-03: pages + seal before async finalize.
1075+
let pages = crate::ceres::lfs::media::protocol::split_pages(&manifest.chunks).unwrap();
1076+
for (page_no, entries) in pages.into_iter().enumerate() {
1077+
let page = ManifestPage {
1078+
page_no: page_no as u32,
1079+
entries,
1080+
};
1081+
let put_page = app
1082+
.clone()
1083+
.oneshot(with_repo(
1084+
Request::put(format!(
1085+
"/libra/media/v1/manifests/{}/pages/{}",
1086+
prepared.manifest_id, page_no
1087+
))
1088+
.header(AUTHORIZATION, format!("Bearer {alice}"))
1089+
.header(CONTENT_TYPE, MEDIA_JSON)
1090+
.body(Body::from(serde_json::to_vec(&page).unwrap()))
1091+
.unwrap(),
1092+
))
1093+
.await
1094+
.unwrap();
1095+
assert_eq!(put_page.status(), StatusCode::OK, "put page");
1096+
}
1097+
let sealed = app
1098+
.clone()
1099+
.oneshot(with_repo(
1100+
Request::post(format!(
1101+
"/libra/media/v1/manifests/{}/seal",
1102+
prepared.manifest_id
1103+
))
1104+
.header(AUTHORIZATION, format!("Bearer {alice}"))
1105+
.body(Body::empty())
1106+
.unwrap(),
1107+
))
1108+
.await
1109+
.unwrap();
1110+
assert_eq!(sealed.status(), StatusCode::OK, "seal");
1111+
1112+
let accepted = app
10301113
.clone()
10311114
.oneshot(with_repo(
10321115
Request::post(format!(
@@ -1039,7 +1122,42 @@ mod tests {
10391122
))
10401123
.await
10411124
.unwrap();
1042-
assert_eq!(finalized.status(), StatusCode::OK, "HTTP finalize 200");
1125+
assert_eq!(accepted.status(), StatusCode::ACCEPTED, "HTTP finalize 202");
1126+
let accepted: FinalizeAcceptedResponse = serde_json::from_slice(
1127+
&axum::body::to_bytes(accepted.into_body(), usize::MAX)
1128+
.await
1129+
.unwrap(),
1130+
)
1131+
.unwrap();
1132+
let status = tokio::time::timeout(Duration::from_secs(10), async {
1133+
loop {
1134+
let resp = app
1135+
.clone()
1136+
.oneshot(with_repo(
1137+
Request::get(format!("/libra/media/v1/tasks/{}", accepted.task_id))
1138+
.header(AUTHORIZATION, format!("Bearer {alice}"))
1139+
.body(Body::empty())
1140+
.unwrap(),
1141+
))
1142+
.await
1143+
.unwrap();
1144+
assert_eq!(resp.status(), StatusCode::OK);
1145+
let st: FinalizeTaskResponse = serde_json::from_slice(
1146+
&axum::body::to_bytes(resp.into_body(), usize::MAX)
1147+
.await
1148+
.unwrap(),
1149+
)
1150+
.unwrap();
1151+
if st.state == "complete" || st.state == "failed" {
1152+
return st;
1153+
}
1154+
tokio::time::sleep(Duration::from_millis(20)).await;
1155+
}
1156+
})
1157+
.await
1158+
.expect("task finish");
1159+
assert_eq!(status.state, "complete", "async finalize completes");
1160+
10431161
wh06_wait_calls(&transport, 1).await;
10441162
let bodies = transport.bodies();
10451163
assert_eq!(bodies.len(), 1, "exactly one finalized event");

0 commit comments

Comments
 (0)