`/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

[baozhoutao]

已开 draft PR #5585(分支 claude/issue-5489-route-error-outage-status)

• 前提复核成立:最新 main(c113690)上翻转断言实测 AssertionError: expected 400 to be greater than or equal to 500。
• 修法:mapDataError 终局兜底 → UNCLASSIFIED_FAULT() = 500 {error:'Internal server error', code:'INTERNAL_ERROR'}。
• 为何不复用 DATA_STORE_FAULT 的 DATABASE_ERROR:后者用在证据指名了存储故障之处(driver 的 missing-relation 措辞、looksLikeInternalErrorLeak 命中);这一支的定义性事实是没有任何证据,把处理器 TypeError 报成 DATABASE_ERROR 会把运维指向一个健康的数据库。INTERNAL_ERROR 是 standardErrorCodeForHttpStatus(500) 的取值(仓内既有目录下限),message 复用 fix(rest): a declared 5xx no longer ships its own message to the client (#5437) #5464 已在用的 INTERNAL_ERROR_MESSAGE —— 未新造第三种措辞。status 5xx + message 消毒两条硬约束都满足。
• 测绘(本单最大回归风险):给兜底加桩跑完 rest 全套(48 文件 / 719 用例),到达这一支的只有 6 个错误 —— 本单的 outage、两个 status: 502 的 ECONNREFUSED、三个 TypeError,没有一个是客户端错误。历史上唯一骑这条兜底的客户端错误家族(driver-sql filter 拒收)已由 data: unsupported-filter-operator refusal ships without error.code and leaks the [sql-driver] prefix #4436 在生产者侧迁走。
• fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224) #5487 那条用例已升格为钉 5xx + INTERNAL_ERROR。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 全程绿(其中 rest.test.ts 与 rest-4xx-message-truncation.test.ts 两条只写 not.toBe(502) 的否定断言顺手升级为正面钉住落点 —— 它们对旧的「400 + ECONNREFUSED 原文」同样成立,分不出两者)。
• 反向验证方向先判后跑:预判「普通的红」,实测 10 红 / 727 绿,且「真 4xx 一个未动」那一块一条未红。
• 测试:pnpm --filter @objectstack/rest test → 49 文件 / 737 用例全绿。rest 无 typecheck script(如实申报),代之以 check:type-check-coverage + --filter @objectstack/rest --filter @objectstack/driver-sql build,均绿。
• 界外发现:已立 mapDataError 的显式状态直通只覆盖 4xx,数据路由上一个声明了 502/503 的生产者拿不回自己的状态码(与 resolveErrorResponse 不对等) #5582(观察类 finding,无 pm:queue)—— mapDataError 的显式状态直通只覆盖 4xx,与 resolveErrorResponse 的 400–599 不对等,数据路由上声明 502/503 的生产者拿不回自己的状态码。

---

Generated by Claude Code

[baozhoutao]

ACCEPT → PR #5585(PM 会话 session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道)

验收依据:

• 信封取舍采纳 dev 的偏离:未复用 fix(rest): 缺表错误只在「缺的正是所请求对象」时才判为 unknown object (#5462) #5530 的 DATA_STORE_FAULT/DATABASE_ERROR,改用 UNCLASSIFIED_FAULT() = 500 INTERNAL_ERROR。理由成立——DATABASE_ERROR 用在证据指名存储故障之处,而这一支的定义性事实是没有任何证据,把处理器 TypeError 报成 DATABASE_ERROR 会把运维指向健康的数据库;INTERNAL_ERROR 取自 spec 的 standardErrorCodeForHttpStatus(500)、message 复用 5xx 分支现物,未新造第三种措辞。
• 本单最大风险(真 4xx 误伤)的测绘是实证的:给兜底加桩跑全套 719 用例,到达者仅 6 个且无一客户端错误;历史上唯一骑此兜底的客户端错误家族已被 data: unsupported-filter-operator refusal ships without error.code and leaks the [sql-driver] prefix #4436 生产者侧迁走;mapDataError 无第二导入方,docs 未把 400 写成契约。
• 反向验证:还原后恰红新钉 10 条,「real client errors are untouched」整块全绿,与预判一致零偏差;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 全程绿(message 纪律未回退,原文进日志沿用 logWithheldServerFault)。
• 界外:mapDataError 的显式状态直通只覆盖 4xx,数据路由上一个声明了 502/503 的生产者拿不回自己的状态码(与 resolveErrorResponse 不对等) #5582(显式状态直通只覆盖 4xx,502→500 的保真度残留)以观察类立单,本 PR 已封掉其泄漏半边——处置正确;getMetaItem 的 overlay 读用裸 catch 把「sys_metadata 不可达」吞成「该项不存在」—— GET /meta/:type/:name 在存储故障时回一个无 code 的 400「not found」 #5532 同领地另一半如实不揽。

CI 快检全绿、重检在跑无红。转 ready 挂 auto-merge,跟到 MERGED。

---

Generated by Claude Code