@zhin.js/host-http

Minimal HTTP and WebSocket host for Plugin Runtime. Provides httpHostToken so Adapters and Console can register path-scoped WebSocket / HTTP routes without importing Koa or the legacy @zhin.js/host-router.

Root installs the host via installResources (see basic/cli/src/plugin-runtime/http-host-installer.ts and console-host-installer.ts).

The composition root owns the process listener through ProcessHttpHost. Generation scopes receive only the HttpHost routing port: they may register HTTP/WS routes but cannot listen or close the shared server. Registrations are bound to generation admission, so candidate routes stay invisible until snapshot commit and retired routes stop matching immediately while their leases drain.

Capabilities (this slice)

• Path-scoped WebSocket upgrades (ws(path))
• HTTP route(method, path, handler, meta?) (exact + /* prefix)
• Built-in GET /pub/health and GET /pub/openapi.json
• CORS allowlist (always includes https://console.zhin.dev)
• Optional Bearer auth for /api/* when http.token / http.tokens are set (ADR 0016 scopes)
• WebSocket upgrade auth (Authorization or ?token=); demo scope limited to /sandbox
• readJsonBody() helper for JSON POST/PUT bodies (no Koa)

import { httpHostToken, type HttpHost } from '@zhin.js/host-http';

const http = context.use(httpHostToken);
const handle = http.ws('/sandbox');
handle.onConnection(({ socket, authScope }) => { /* ... */ });

http.route('GET', '/api/secure', (_req, res, _url, scope) => {
  res.writeHead(200, { 'content-type': 'application/json' });
  res.end(JSON.stringify({ scope }));
});

Config (http in Root YAML)

http:
  host: 127.0.0.1
  port: 8086
  token: ${HTTP_TOKEN}          # full scope
  tokens:
    - token: ${DEMO_TOKEN}
      scope: demo
  corsOrigins:
    - https://example.test
  base: /api                    # auth prefix

The legacy Koa @zhin.js/host-router stack and the @zhin.js/host-api management-plane plugin have been removed; the management-plane REST/RPC/SSE is now assembled by @zhin.js/cli (Console Host) on top of this package — no Host plugins need to be installed or enabled.