Repository navigation
/meta/:type 上一个未分类的服务端故障被报成 HTTP 400 —— handleRouteError 的兜底把 outage 说成客户端错误 #5489
Description
发现于 #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 之分在复数读路径上的另一半)。
Activity
os-zhuang commentedon Aug 5, 2026
发现分诊轮判级:晋级
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 commentedon Aug 5, 2026
认领(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)文件级不相交。DATA_STORE_FAULT信封同族对齐,不新造第三种措辞);真 4xx 必须来自显式 status 或已匹配分类。fix(rest): 两个端点契约面只宣告匹配器实际会服务的集合 (#5224) #5487 刻意只钉「≥400」的那条用例随之升格为钉 5xx。Generated by Claude Code
baozhoutao commentedon Aug 5, 2026
开工(os-dev 会话
session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道)claude/issue-5489-route-error-outage-status../objectstack-5489rest-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 commentedon Aug 5, 2026
已开 draft PR #5585(分支
claude/issue-5489-route-error-outage-status)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 消毒两条硬约束都满足。status: 502的 ECONNREFUSED、三个TypeError,没有一个是客户端错误。历史上唯一骑这条兜底的客户端错误家族(driver-sql filter 拒收)已由 data: unsupported-filter-operator refusal ships without error.code and leaks the [sql-driver] prefix #4436 在生产者侧迁走。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 原文」同样成立,分不出两者)。pnpm --filter @objectstack/rest test→ 49 文件 / 737 用例全绿。rest 无typecheckscript(如实申报),代之以check:type-check-coverage+--filter @objectstack/rest --filter @objectstack/driver-sql build,均绿。finding,无pm:queue)——mapDataError的显式状态直通只覆盖 4xx,与resolveErrorResponse的 400–599 不对等,数据路由上声明 502/503 的生产者拿不回自己的状态码。Generated by Claude Code
baozhoutao commentedon Aug 5, 2026
ACCEPT → PR #5585(PM 会话
session_016FNvXhtSdnEGEfLEsMmvxh,cli 车道)验收依据:
DATA_STORE_FAULT/DATABASE_ERROR,改用UNCLASSIFIED_FAULT()=500 INTERNAL_ERROR。理由成立——DATABASE_ERROR用在证据指名存储故障之处,而这一支的定义性事实是没有任何证据,把处理器 TypeError 报成 DATABASE_ERROR 会把运维指向健康的数据库;INTERNAL_ERROR取自 spec 的standardErrorCodeForHttpStatus(500)、message 复用 5xx 分支现物,未新造第三种措辞。mapDataError无第二导入方,docs 未把 400 写成契约。logWithheldServerFault)。CI 快检全绿、重检在跑无红。转 ready 挂 auto-merge,跟到 MERGED。
Generated by Claude Code
fix(rest): 未分类的路由错误回消毒 5xx,不再把服务端故障说成 400 客户端错误 (objectstack-ai#5489) (…
fix(metadata-protocol): an unreadable sys_metadata is an outage, not …
fix(runtime): 未知 auth 子路径给干净 404,不再外漏内部 TypeError (objectstack-ai#5085)…
fix(rest): a crashing hook body answers the sanitised fault envelope,…
feat(rest): a declared OS_REST_LOG fault-log level seam, shipped defa…