观察类发现,记录于 #5090 (#5040 E3)实现期间。今天没有用户会撞上 :该类在仓内零组合点。
事实
packages/runtime/src/http-server.ts 的 HttpServer implements IHttpServer 是一个委派包装器(构造函数吃一个 IHttpServer,把 get/post/put/delete/patch/use/listen/close 转发给它)。它只转发必选成员 ,IHttpServer 上的可选成员一个都不转发:
后果的形状是一致的:消费者按契约做 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-registry plugin 只在 packages/core/examples/ 里被装配,无任何真实 composition 挂载 —— ApiEndpointRegistrationSchema 因此整面零执行 #4939 顺带:@objectstack/http-conformance 目前不对 setFallbackHandler 做任何断言(可选成员,不属其必测面),所以第二个实现该成员的适配器与 Hono 版行为分叉不会变红 —— 若走方案 1,这里是自然的守卫落点(ADR-0076 OQ#10)。
关联:#5080 (契约成员)、#5090 (Hono 侧实现 + 消费端探测)、ADR-0076 D11/OQ#10。
观察类发现,记录于 #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 刚加一个),缺口只会变宽。可能的处置(留给分诊,不预判)
ApiRegistry(ApiRegistry/api-registryplugin 只在packages/core/examples/里被装配,无任何真实 composition 挂载 ——ApiEndpointRegistrationSchema因此整面零执行 #4939)的先例适用:退役一个「从未被装配」的件比修它更长远;@objectstack/http-conformance目前不对setFallbackHandler做任何断言(可选成员,不属其必测面),所以第二个实现该成员的适配器与 Hono 版行为分叉不会变红 —— 若走方案 1,这里是自然的守卫落点(ADR-0076 OQ#10)。关联:#5080(契约成员)、#5090(Hono 侧实现 + 消费端探测)、ADR-0076 D11/OQ#10。