`/meta/:type` 上一个未分类的服务端故障被报成 HTTP 400 —— handleRouteError 的兜底把 outage 说成客户端错误

[baozhoutao]

发现于 #5224 / PR #5487 的测试编写过程,不在该单文件面内,按 Prime Directive #10 单独立项。观察类:我是用注入错误测到的,没有在真实的存储故障下复现过,严重度请分诊时判定。

事实

GET /api/v1/meta/:type 的处理器以 handleRouteError(res, error) 收尾。让它内部抛一个普通 Error('metadata store unreachable')(在 #5224 的场景里就是 matchEndpoint 按契约在存储读不到时抛的那一个 —— 它抛正是为了让 outage 不伪装成 miss,见 ADR-0110 D3),实测响应是:

HTTP 400

不是 5xx。路径是 handleRouteError → sendError → resolveErrorResponse → mapDataError,一个关键词都不匹配的错误落到 mapDataError 的终局兜底,那一支给 400。

为什么值得记一笔

• 400 是「你请求错了」。客户端据此不会重试,而一个存储不可达恰恰是应该重试的。把服务端故障标成客户端错误,会让 SDK / 前端在真出故障时做出恰好相反的决定。
• 这与 sendError 的显式状态直通覆盖 400–599,5xx 的原始驱动报错绕过全部泄漏启发式直达客户端(metadata-protocol 有活体产出方) #5437 / PR fix(rest): a declared 5xx no longer ships its own message to the client (#5437) #5464 是同一片领地(resolveErrorResponse 的状态归类),那一单刚把 5xx 的 message 收住;状态码这一侧的兜底方向没有一并看。sendError 的显式状态直通覆盖 400–599,5xx 的原始驱动报错绕过全部泄漏启发式直达客户端(metadata-protocol 有活体产出方) #5437 的分析里已经记下 mapDataError 会「把服务端故障重贴成客户端错误」,当时是作为不采用它的理由;这里是它仍在生效的那条兜底路径。
• 不是 声明式端点的两个机器可读面会说谎:runtime-authored api 行在 /meta/api 与 /openapi.json 里在场,匹配器却永远看不见(真实 boot 实测) #5224 / PR fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224) #5487 引入的:它是 /meta/:type 上任何未分类错误的既有归类。PR fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224) #5487 的用例因此只钉「请求失败、而不是返回一个集合」,并在注释里写明了不去钉 5xx —— 断言 5xx 会把别人的 bug 钉成好像已经修好。

复现

packages/rest/src/rest-endpoint-surfaces-served-only.test.ts 里那条 reports a store outage rather than an empty declaration set:把断言从 toBeGreaterThanOrEqual(400) 改成 toBeGreaterThanOrEqual(500),实测得到 expected 400 to be greater than or equal to 500。

相关:#5437 / PR #5464、#5436、ADR-0110 D3、#5108(同一条 miss vs outage 之分在复数读路径上的另一半)。

[os-zhuang]

发现分诊轮判级:晋级 pm:queue,域 domain:cli。

理由:虽以观察类立单,但缺陷具体、落点与复现均已钉死 —— mapDataError 终局兜底把未分类服务端错误发成 HTTP 400(packages/rest → domain:cli),复现是现成测试断言翻转即可。400 vs 5xx 直接决定客户端重不重试,存储故障被标成客户端错误会让 SDK 在真故障时做出相反决定,属 restore-invariant 形状(miss vs outage 之分是 ADR-0110 D3 已立的约)。过时前提检查(origin/main @ b4cdc58):packages/rest 自立单后仅落 #5530/#5487,mapDataError 的 {status: 400} 兜底仍在(rest-4xx-message-truncation.test.ts:20 注释可证),#5464 只收了 message 半边。给认领方:与 #5437/#5464 同一片领地,注意别回退其 message 纪律;#5108 是复数读路径上的同族另一半,修法宜对齐。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[baozhoutao]

认领(PM 会话 session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道)

• 分支:claude/issue-5489-route-error-outage-status
• 工作树:../objectstack-5489(os-dev 自建)
• 文件面:packages/rest/src/rest-server.ts(mapDataError 终局兜底那一支)+ 既有错误路径测试族(fix(rest): 4xx 直通截断超长 message,不再整条换成 "Request failed" (#5423) #5436/fix(rest): a declared 5xx no longer ships its own message to the client (#5437) #5464/fix(rest): 缺表错误只在「缺的正是所请求对象」时才判为 unknown object (#5462) #5530 的 pin 不得回退);不动 served-endpoints.ts 语义,与在飞 gen:openapi 的 base spec 用 7 条手写 path 描述路由面,与 rest 真实路由无任何对账 —— 漂移了不会红(#5168 的剩余那一半) #5456(rest 新增对账测试,不触 rest-server.ts)文件级不相交。
• 方向锚定分诊 18:53Z:未分类逃逸错误的终局兜底从 400 改为消毒 5xx(与 fix(rest): 缺表错误只在「缺的正是所请求对象」时才判为 unknown object (#5462) #5530 刚落的 DATA_STORE_FAULT 信封同族对齐,不新造第三种措辞);真 4xx 必须来自显式 status 或已匹配分类。fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224) #5487 刻意只钉「≥400」的那条用例随之升格为钉 5xx。

---

Generated by Claude Code

[baozhoutao]

开工(os-dev 会话 session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道)

• 分支:claude/issue-5489-route-error-outage-status
• 工作树:../objectstack-5489
• 计划:先在最新 main 复核前提(翻转 rest-endpoint-surfaces-served-only.test.ts 的 reports a store outage rather than an empty declaration set 断言到 >=500,确认实测 400);再测绘今天有哪些真实的客户端错误依赖 mapDataError 终局兜底拿 400;然后把终局兜底改为消毒 5xx,与 fix(rest): 缺表错误只在「缺的正是所请求对象」时才判为 unknown object (#5462) #5530 的 DATA_STORE_FAULT 信封同族对齐。fix(rest): 4xx 直通截断超长 message,不再整条换成 "Request failed" (#5423) #5436 / fix(rest): a declared 5xx no longer ships its own message to the client (#5437) #5464 / fix(rest): 缺表错误只在「缺的正是所请求对象」时才判为 unknown object (#5462) #5530 的 pin 全程保持绿。

---

Generated by Claude Code