# @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`
- CLI-composed runtimes additionally expose `GET /pub/ready` and full-scope `GET /api/system/readiness`; see [production probes](../../../docs/operations/production.md).
- 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)

```ts
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)

```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.

Extended Console RPC uses `src/console-rpc-extended/index.ts` as its module boundary. The dispatcher
only maps protocol method names to schedule, inbox, login, Endpoint-management, and Workroom control
handlers. Shared request parsing and generation-leased Endpoint execution live behind internal helper
ports, so adding one RPC domain does not enlarge the central dispatcher or couple unrelated domains.