@cordis-tavern/ct-host-web

cordis-tavern 的 host 基础插件：提供 HTTP 服务能力。

作为基础插件对外暴露一个 node:http 服务，并给出两个 cordis 服务：

| 服务 | 可见时机 | 内容 | | --- | --- | --- | | webServer | apply 的同步段 | { hostRegister, fallbackRegister }（路由注册入口） | | host | 真正监听成功之后 | { name: 'host', server } |

要注册路由就 inject: ['webServer']；只拿服务本体用 inject: ['host']。

服务本体的端口与关闭动作在 host.server 上（即 startServer 返回的 HostServer）： ctx.host.server.port / ctx.host.server.address / ctx.host.server.close()。 host 自身只有 name 与 server 两项，没有 ctx.host.port 这种写法。

未注册任何路由（且没有注册 fallback）时，一切请求回 404。

host 同时是 bundle 里 cordis.patch.yml 的 insert[].id，与服务名不是一回事（见「装载」一节）。

配置

四键固定英文名，不做别名：

| 键 | 默认 | 说明 | | --- | --- | --- | | port | 3100 | 服务监听端口。0 表示由系统分配（startServer 会返回实际端口） | | listen | false | true → 绑 0.0.0.0 并按 listenWhitelist 过滤连接；false → 绑 ip | | ip | 127.0.0.1 | 仅 listen: false 时生效 | | listenWhitelist | ['127.0.0.1'] | 仅 listen: true 时生效。数组，支持 CIDR；显式写成 [] 表示一条连接都不接受 |

未知配置键与非法值一律抛 TypeError 并指名键名——不静默忽略。

服务启动后会自动打开系统浏览器访问 http://127.0.0.1:<port>（地址恒为 127.0.0.1，不随 listen 变化）。

路由注册

插件经服务 webServer 注册路由。服务名是 webServer，host 是 cordis.patch.yml 里 insert[].id 的取值，两者不是一回事。

// 前缀匹配：/api/user/apps、/api/user/data 都命中；/api/username 不命中（按段边界）
const dispose = ctx.webServer.hostRegister('prefix', '/api/user', (req, res) => {
  res.writeHead(200)
  res.end('ok')
})

// 精准匹配：只有整串相等才命中
ctx.webServer.hostRegister('exact', '/api/user/app.js', (req, res) => { /* ... */ })

// 兜底：全局唯一，接收一切未匹配请求
ctx.webServer.fallbackRegister((req, res) => {
  res.writeHead(404)
  res.end()
})

// 两个注册方法都返回 disposer，卸载时撤销该条注册
dispose()

• path 全局唯一（与 kind 无关）：重复注册抛错并指名冲突 path。
• fallback 全局唯一：槽位被占用后再注册抛错。
• handler 收到原生 (req, res)，req.method 由 handler 自己判断。
• 匹配只看 req.url 剥掉 ? 之前的部分；req.url 原样交给 handler。
• 没有注册 fallback 时，未匹配请求回 404。

安装

pnpm add @cordis-tavern/ct-host-web

五个 @cordis-tavern/* 内核包是 peerDependencies，由 $CT_HOME 提供（ct init 已装配）， 插件自身不携带内核副本——否则 Service / Context 会出现两份实例且静默失效。

装载

• 包名写进环境级 ct.profile：ct plugin add -p <环境名> @cordis-tavern/ct-host-web
• 包目录须落在 $CT_HOME/profile/<env>/node_modules/ 或 $CT_HOME/node_modules/
• package.json 的 ct.bundle.path → cordis.patch.yml，其 insert[] 声明 id: host 与包名

本版本的状态（诚实说明）

• 0.0.2-rc（v2：路由注册入口 webServer 与路由分发），rc 阶段。不是首次发布 —— 一期 0.0.1-alpha.3 已发布，本版在它之上新增能力，消费面无破坏性变更。
• 单元测试覆盖配置校验、CIDR 匹配、路由匹配与注册、服务起停与卸载、浏览器命令构造。
• 未做过端到端验证：尚未在真实 $CT_HOME 里装载运行过。