3D 产物上传带上退避重试，一次瞬时网络失败不再废掉整笔生成
- platform-oss：新增按前缀拼对象键的 `put_object_with_transient_retry`，与内部对象 PUT 共用同一套「可判定才重试」规则与退避（传输 / 超时 / 408 / 429 / 5xx 才重试，确定性 4xx 直接失败），body 只准备一次、每次 attempt 复用引用计数字节；重试次数或退避配置不足时按配置错误失败关闭 - api-server storage：3D 产物的模型 / 预览图 PUT 改用该入口，最多 3 次尝试、退避 250 / 500 ms（与角色动画同一口径）；模型上限 512 MiB 但实际产物远小，重试成本可控 - 新增用例：重试次数为 0 与退避不足都失败关闭；对一定解析不出的域名会真的按退避重试多次 - docs/technical：写明产物 PUT 的重试口径与「每个网络动作都要能重试」的理由
This commit is contained in:
@@ -164,6 +164,8 @@ width/height = 预览图像素尺寸
|
||||
|
||||
模型格式与体积由 `AssetObject` 承担（`content_type`、`content_length`、`content_hash`），因此不新增 `model_format`、`size_bytes`、`poly_count` 等列。两个槽位的 `content_type` 都在写入前按字节识别真实产物：模型按魔数认 GLB 的 `glTF` 头、FBX 的 `Kaydara FBX Binary` 头与 glTF 的 JSON 正文，预览按魔数认 PNG / JPEG / WebP；不直接采信 provider 返回或下载响应头声明的类型，对象键扩展名由该内容类型派生。只有字节判不出来时才采信声明值，且声明值必须落在该槽位的白名单内（模型：`model/gltf-binary`、`model/gltf+json`、`model/fbx`、`application/x-fbx`；预览：`image/png`、`image/jpeg`、`image/jpg`、`image/webp`）；两边都对不上就直接按上游内容不合法失败并退款，不做任何兜底 —— 放行 `text/plain` 这类未知类型只会落成「错的 content type + 拼出来的扩展名」。客户端不复制这份格式清单：画布只按「`assetKind=model3d` 且 `objectKey` 非空」放行，能否交给 3D 查看器由 `packages/model3d-viewer` 判定，判据依次是读接口声明的 `Content-Type`、字节魔数、地址扩展名，全判不出来即按 `unsupported-format` 报错。这里的顺序是「信任后端检测结果」：`content_type` 在后端写入前已经按字节核过，所以客户端以声明为先；字节魔数只兜住声明缺失或认不出来（例如 `application/octet-stream`）的情况，不负责纠正一个「认得出来但不对」的声明。
|
||||
|
||||
产物对象由 api-server 按固定前缀 PUT 写入、再 HEAD 复核后才登记；PUT 带退避重试（最多 3 次尝试，退避 250 / 500 ms），只对传输 / 超时 / 408 / 429 / 5xx 重试，确定性 4xx 直接失败。3D job 最多只尝试一次，一次瞬时网络失败就会废掉一笔已经计费的生成，所以这条链路上的每个网络动作都要能重试。
|
||||
|
||||
`external_generation_job.phase` 的取值集合不变，仍只允许现有两种执行阶段；阶段文案由 api-server 映射，不扩展 schema 常量。
|
||||
|
||||
## assetKind 接入清单对照
|
||||
|
||||
@@ -36,6 +36,11 @@ pub(crate) const MODEL3D_ASSET_KIND: &str = crate::editor_project::EDITOR_MODEL3
|
||||
/// `asset_object.entity_kind`：说明这个对象属于 3D 生成产物。
|
||||
const MODEL3D_OBJECT_ENTITY_KIND: &str = "model3d";
|
||||
|
||||
/// 产物 PUT 的重试预算：模型最大 512 MiB，一次瞬时网络失败就会废掉一笔已经计费的生成，
|
||||
/// 而任务本身最多只尝试一次，所以这里按与角色动画一致的口径退避重试三次。
|
||||
const MODEL3D_ARTIFACT_PUT_MAX_ATTEMPTS: usize = 3;
|
||||
const MODEL3D_ARTIFACT_PUT_RETRY_DELAYS_MS: [u64; 2] = [250, 500];
|
||||
|
||||
const MODEL3D_OBJECT_PATH_SEGMENT: &str = "model3d";
|
||||
|
||||
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
|
||||
@@ -131,7 +136,7 @@ pub(crate) async fn store_model3d_artifact(
|
||||
.ok_or_else(|| unsupported_artifact_content_type(content_type.as_str(), slot))?;
|
||||
let file_name = format!("{}.{}", slot.file_stem(), extension);
|
||||
let put_result = oss_client
|
||||
.put_object(
|
||||
.put_object_with_transient_retry(
|
||||
http_client,
|
||||
OssPutObjectRequest {
|
||||
prefix: LegacyAssetPrefix::CharacterDrafts,
|
||||
@@ -156,6 +161,8 @@ pub(crate) async fn store_model3d_artifact(
|
||||
]),
|
||||
body: bytes,
|
||||
},
|
||||
MODEL3D_ARTIFACT_PUT_MAX_ATTEMPTS,
|
||||
&MODEL3D_ARTIFACT_PUT_RETRY_DELAYS_MS,
|
||||
)
|
||||
.await
|
||||
.map_err(|error| map_oss_error(error, "aliyun-oss"))?;
|
||||
|
||||
@@ -323,6 +323,7 @@ struct PreparedHeadObject {
|
||||
target_url: reqwest::Url,
|
||||
}
|
||||
|
||||
#[derive(Clone)]
|
||||
struct PreparedPutObject {
|
||||
object_key: String,
|
||||
target_url: reqwest::Url,
|
||||
@@ -1401,6 +1402,46 @@ impl OssClient {
|
||||
result
|
||||
}
|
||||
|
||||
/// 派生对象（按前缀拼对象键）的受控重试 PUT。
|
||||
///
|
||||
/// 与 `put_internal_object_with_retry` 用同一套「可判定才重试」规则与退避：传输 / 超时 /
|
||||
/// 408 / 429 / 5xx 才重试，确定性 4xx 直接失败。body 只准备一次（引用计数字节），每次
|
||||
/// attempt 复用同一份，不做重复编码。
|
||||
///
|
||||
/// `max_attempts` 至少为 1，`retry_delays_ms` 至少提供 `max_attempts - 1` 个退避值；
|
||||
/// 参数不满足时按配置错误失败关闭，不静默降级成单次请求。
|
||||
pub async fn put_object_with_transient_retry(
|
||||
&self,
|
||||
client: &reqwest::Client,
|
||||
request: OssPutObjectRequest,
|
||||
max_attempts: usize,
|
||||
retry_delays_ms: &[u64],
|
||||
) -> Result<OssPutObjectResponse, OssError> {
|
||||
if max_attempts == 0 {
|
||||
return Err(OssError::InvalidConfig(
|
||||
"派生对象 PUT 重试次数至少为 1".to_string(),
|
||||
));
|
||||
}
|
||||
if retry_delays_ms.len() < max_attempts.saturating_sub(1) {
|
||||
return Err(OssError::InvalidConfig(
|
||||
"派生对象 PUT 重试缺少退避配置".to_string(),
|
||||
));
|
||||
}
|
||||
let prepared = self.prepare_put_object(request)?;
|
||||
let object_key = prepared.object_key.clone();
|
||||
run_internal_put_with_retry(max_attempts, retry_delays_ms, &object_key, move || {
|
||||
// 每次 attempt 复制一份准备结果（body 是引用计数的字节，不复制内容），
|
||||
// 让 future 拥有它自己的那份，避免把借用带出闭包。
|
||||
let prepared = prepared.clone();
|
||||
async move {
|
||||
self.put_object_once(client, &prepared)
|
||||
.await
|
||||
.map(|(response, _status)| response)
|
||||
}
|
||||
})
|
||||
.await
|
||||
}
|
||||
|
||||
/// 角色动画帧专用的可重试 PUT。调用方传入进程级并发限制器，单次网络 attempt
|
||||
/// 独占一个 permit，退避等待期间不会占用 permit。
|
||||
pub async fn put_object_with_retry(
|
||||
@@ -3473,6 +3514,84 @@ mod tests {
|
||||
assert_eq!(attempts.load(Ordering::SeqCst), 2);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn derived_put_retry_fails_closed_on_bad_retry_config() {
|
||||
let client = build_client();
|
||||
let http = reqwest::Client::new();
|
||||
let request = OssPutObjectRequest {
|
||||
prefix: LegacyAssetPrefix::CharacterDrafts,
|
||||
path_segments: vec!["editor".to_string(), "model3d".to_string()],
|
||||
file_name: "model.glb".to_string(),
|
||||
content_type: Some("model/gltf-binary".to_string()),
|
||||
access: OssObjectAccess::Private,
|
||||
metadata: BTreeMap::new(),
|
||||
body: MOCK_PUT_BODY.to_vec(),
|
||||
};
|
||||
|
||||
// 次数为 0 或退避不够都必须按配置错误失败，不能静默降级成单次请求。
|
||||
let error = client
|
||||
.put_object_with_transient_retry(&http, request.clone(), 0, &[])
|
||||
.await
|
||||
.expect_err("重试次数为 0 必须失败关闭");
|
||||
assert!(matches!(error, OssError::InvalidConfig(_)), "{error:?}");
|
||||
|
||||
let error = client
|
||||
.put_object_with_transient_retry(&http, request, 3, &[1])
|
||||
.await
|
||||
.expect_err("退避配置不足必须失败关闭");
|
||||
assert!(matches!(error, OssError::InvalidConfig(_)), "{error:?}");
|
||||
}
|
||||
|
||||
/// 端点的域名一定解析不出来（`.invalid` 是 RFC 2606 保留给「一定不存在」的顶级域，
|
||||
/// 前半段保留 `oss-<region>` 形状以便通过 region 解析），于是每次 attempt 都是可重试的
|
||||
/// 连接失败，而且不会真的打到任何服务端。
|
||||
fn build_unreachable_client() -> OssClient {
|
||||
OssClient::new(
|
||||
OssConfig::new(
|
||||
"genarrative-assets".to_string(),
|
||||
"oss-cn-shanghai.invalid".to_string(),
|
||||
"test-access-key-id".to_string(),
|
||||
"test-access-key-secret".to_string(),
|
||||
DEFAULT_READ_EXPIRE_SECONDS,
|
||||
DEFAULT_POST_EXPIRE_SECONDS,
|
||||
DEFAULT_POST_MAX_SIZE_BYTES,
|
||||
DEFAULT_SUCCESS_ACTION_STATUS,
|
||||
)
|
||||
.expect("OSS config should be valid"),
|
||||
)
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn derived_put_retry_repeats_transient_transport_failures() {
|
||||
let client = build_unreachable_client();
|
||||
let http = reqwest::Client::new();
|
||||
let started_at = Instant::now();
|
||||
let error = client
|
||||
.put_object_with_transient_retry(
|
||||
&http,
|
||||
OssPutObjectRequest {
|
||||
prefix: LegacyAssetPrefix::CharacterDrafts,
|
||||
path_segments: vec!["editor".to_string(), "model3d".to_string()],
|
||||
file_name: "model.glb".to_string(),
|
||||
content_type: Some("model/gltf-binary".to_string()),
|
||||
access: OssObjectAccess::Private,
|
||||
metadata: BTreeMap::new(),
|
||||
body: MOCK_PUT_BODY.to_vec(),
|
||||
},
|
||||
3,
|
||||
&[50, 50],
|
||||
)
|
||||
.await
|
||||
.expect_err("连不上的域名必须失败");
|
||||
assert!(oss_error_is_retryable(&error), "{error:?}");
|
||||
// 三次尝试之间的两段退避必须真的等过：只打一次请求不会花这么久。
|
||||
assert!(
|
||||
started_at.elapsed() >= std::time::Duration::from_millis(100),
|
||||
"退避没有生效：{:?}",
|
||||
started_at.elapsed()
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structured_log_labels_are_stable() {
|
||||
assert_eq!(
|
||||
|
||||
Reference in New Issue
Block a user