Repository navigation
runtime 导出的 HttpServer 包装器静默丢弃 IHttpServer 的全部可选成员(getPort / getRawApp / setFallbackHandler) #5122
Description
观察类发现,记录于 #5090(#5040 E3)实现期间。今天没有用户会撞上:该类在仓内零组合点。
事实
packages/runtime/src/http-server.ts 的 HttpServer implements IHttpServer 是一个委派包装器(构造函数吃一个 IHttpServer,把 get/post/put/delete/patch/use/listen/close 转发给它)。它只转发必选成员,IHttpServer 上的可选成员一个都不转发:
getPort?()—— 测试与 conformance 套件靠它寻址listen(0)的临时端口;getRawApp?()—— 框架原生逃生口(cloud-connection ×2、metadata HMR 路由、cloud serverless 均 feature-detect 它);setFallbackHandler?()—— E1(#5040 执行器契约面):IMetadataService.matchEndpoint?/generateOpenApi?+IHttpServer.setFallbackHandler?可选契约方法与契约测试 #5080 新落的兜底 seam,声明式apis:端点唯一的进入通路(E3(#5040 执行器):挂载 seam ——IHttpServer.setFallbackHandler的 Hono 实现 + dispatcher 端点派发步 + 路由台账登记 #5090 实现)。
后果的形状是一致的:消费者按契约做 typeof server.X === 'function' 探测,包装器让探测恒为 false,于是能力静默缺席 —— 底层适配器明明提供了。对 setFallbackHandler 而言意味着:把 HonoHttpServer 包进 HttpServer 再注册为 http.server 的 host,其声明式端点永远 404,且没有任何一行日志说明为什么。
为什么标 finding 而不是缺陷
new HttpServer( 在本仓(含 examples)零出现;它只从 packages/runtime/src/index.ts 公开导出。所以这是「导出的公共 API 与它宣称实现的契约不符」,不是任何现网路径上的故障。真实的 host 都直接注册适配器实例。
不过它是 public API,外部 host 可以用它 —— 且随着 IHttpServer 继续长出可选成员(#5080 刚加一个),缺口只会变宽。
可能的处置(留给分诊,不预判)
- 转发可选成员(条件转发:底层有才暴露,保持 feature-detect 语义正确);
- 退役该类 —— 若它确实从未被组合过,
ApiRegistry(ApiRegistry/api-registryplugin 只在packages/core/examples/里被装配,无任何真实 composition 挂载 ——ApiEndpointRegistrationSchema因此整面零执行 #4939)的先例适用:退役一个「从未被装配」的件比修它更长远; - 顺带:
@objectstack/http-conformance目前不对setFallbackHandler做任何断言(可选成员,不属其必测面),所以第二个实现该成员的适配器与 Hono 版行为分叉不会变红 —— 若走方案 1,这里是自然的守卫落点(ADR-0076 OQ#10)。
Activity
os-zhuang commentedon Aug 4, 2026
分诊:观察类,持有(不入
pm:queue) —— 执行器车道 PMsession_01EYGdmvWP1ieZSLqvAW6uyd,2026-08-04。定级依据:仓内零组合点(
new HttpServer(零出现),今天无人可撞上,不构成现网缺陷。但它是 public API,且IHttpServer可选成员在增加(#5097 刚加了setFallbackHandler?),「探测恒 false」的静默能力缺席是真实的延迟雷。复查触发器:#5040 E7 翻转单(#5111)落地时一并裁决 —— 届时
setFallbackHandler从「结构性不可达的 seam」变为声明式端点的唯一通路,任何经此包装器的组合都会静默丢掉全部端点。E7 的 dispatcher 侧已有「探测缺席升 loud」的预留注记,本单届时三选一:转发全部可选成员 + http-conformance 守卫 / 退役该包装器(零消费者,enforce-or-remove 姿态)/ 维持并文档标注。在那之前持有。Generated by Claude Code
os-zhuang commentedon Aug 5, 2026
发现分诊轮:转
needs-user-decision(摘finding)。持有的重启条件已触发 —— E7 翻转单 #5111 已于 2026-08-04 关闭(completed),setFallbackHandler现在是声明式端点的唯一通路,经此包装器的任何组合都会静默丢掉全部端点。待裁决(此前持有评论列的三选一,现在到期):退役该包装器(推荐:
new HttpServer(仓内零组合点,#4939「从未被装配的件退役优于修」先例 + ADR-0049 enforce-or-remove 姿态)vs 转发全部可选成员 + http-conformance 守卫(保留 public API,ADR-0076 OQ#10 落点)vs 维持并文档标注。裁决后即可转pm:queue。本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
claude commentedon Aug 6, 2026
处置(2026-08-06):退回派发队列(退役)。
复核结论:runtime
HttpServer包装器零消费(new HttpServer(全仓含 examples 零命中),implements IHttpServer却丢弃全部可选成员——恢复 declared=enforced 的标准形态,#4939「从未被装配的件退役优于修」直接先例,零回滚风险。修法:删除该类与导出 + changeset 注记(#5409 已落的 warn 宣告继续兜底)。若要补 http-conformance 的
setFallbackHandler断言(ADR-0076 OQ#10),随退役 PR 顺手或另拆。量级 S。经办:PM 会话
session_01GcjbQLUQKysMU9uXB34iyv;维护者 2026-08-06 审阅决策简报后授权按建议执行(否决窗口:可评论/重开推翻)。Generated by Claude Code
os-zhuang commentedon Aug 6, 2026
【裁决落地】维护者 2026-08-06 批复全舰队决策箱评估报告(批复「同意」),本单裁定:
裁退役——runtime 导出的 HttpServer 包装器按 #4939 先例(「从未被装配的件退役优于修」)+ ADR-0049 remove 侧流程退役;仓内零组合点,现在退最便宜。不做条件转发(养一个无人用的转发面),不做「维持+文档」。
实现按 ADR-0049 remove 侧:changeset(public API 移除,cli/runtime 相应级别)+ 迁移注记(指引直接用 IHttpServer 实现);#5111 后 setFallbackHandler 已是声明式端点唯一通路的事实写进移除说明,防未来有人复刻同型包装器。
流转:摘
needs-user-decision→pm:queue,归 cli 车道。评估与落地会话:
session_01N3uGFF8teXbpgtbEJ1aYXuGenerated by Claude Code
test(spec): contracts and conversions test titles state each cited de…