@zhin.js/host-http 1.1.17 → 1.2.0

package/src/bridge/bridged-host.ts

@@ -0,0 +1,548 @@
+/**
+ * Instance side of the HTTP bridge (ADR 0054 §2 / §3): `BridgedHttpHost` implements the same
+ * {@link HttpHost} surface as the in-process Node server, but serves requests that the gateway
+ * forwards over the control channel. Routing, CORS, generation admission and Console
+ * authorization are the shared router's (`createHttpRouter`), running in `forwarded`
+ * authentication mode: the gateway authenticated the caller and the principal travels with the
+ * request; the router still authorizes it against the Console permission map.
+ *
+ * Console accounts live in the gateway (ADR 0054 §7): the instance never resolves a bearer. Its
+ * token registry is closed (no bootstrap token, no open Host): every grant arrives as the
+ * forwarded principal. Audit entries the instance writes go to the gateway (`audit`), the plugin
+ * permission catalog of the current generation is reported (`catalog`), and `principal-revoked`
+ * closes that user's live exchanges and sockets.
+ *
+ * Nothing here imports `node:http` or `ws`.
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  generationAdmissionBinder,
+  type GenerationAdmissionBindable,
+} from '@zhin.js/plugin-runtime';
+import {
+  createHttpRouter,
+  type HttpHost,
+  type HttpRouter,
+  type HttpRouterOptions,
+  type WsTransport,
+} from '../http-host.js';
+import type { ConsoleAccessProvider, ConsoleAuditEntry, ConsolePrincipal } from '../access-control.js';
+import { TokenRegistry } from '../token-registry.js';
+import type { HttpHostAddress } from '../host-options.js';
+import { httpHostAddressProvider, type AddressAwareHttpHost } from '../addresses.js';
+import type { RouteMeta } from '../openapi.js';
+import { CreditGate, InboundBody, ownBytes, pumpBody } from './flow.js';
+import {
+  DEFAULT_BRIDGE_LIMITS,
+  fromBridgeHeaders,
+  parseBridgePrincipal,
+  toBridgeHeaders,
+  wsMessageSize,
+  type BridgeLimits,
+  type BridgeRouteTable,
+  type GatewayToInstanceMessage,
+  type HttpRequestMessage,
+  type InstanceToGatewayMessage,
+  type WsOpenMessage,
+} from './protocol.js';
+
+const logger = getLogger('http');
+const BODYLESS_METHODS = new Set(['GET', 'HEAD']);
+/** Close code / reason used when the gateway revoked the socket's principal. */
+export const PRINCIPAL_REVOKED_CLOSE_CODE = 4401;
+
+/** What the bridged Host needs from the control channel (see `openInstanceControlChannel`). */
+export interface BridgeChannel {
+  send(message: InstanceToGatewayMessage): void;
+  onMessage(listener: (message: GatewayToInstanceMessage) => void): () => void;
+  onDisconnect(listener: () => void): () => void;
+  /** Keeps the process alive while the Host listens (see `InstanceControlChannel.hold`). */
+  hold?(): () => void;
+}
+
+export interface BridgedHttpHostOptions extends Omit<HttpRouterOptions, 'address' | 'authentication' | 'secure' | 'token' | 'tokenRegistry'> {
+  readonly channel: BridgeChannel;
+  readonly limits?: Partial<BridgeLimits>;
+}
+
+/** @public Instance HTTP Host carried by the gateway bridge. */
+export interface BridgedHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost>, AddressAwareHttpHost {
+  /**
+   * Opens the bridge: announces the route table and starts serving forwarded requests.
+   * Resolves with the gateway's primary address once the gateway announced it (else undefined).
+   */
+  listen(): Promise<HttpHostAddress | undefined>;
+  /** Ends every exchange and socket, withdraws the route table and drops all routes. */
+  close(): Promise<void>;
+  /** Route table as the gateway sees it. */
+  routeTable(): BridgeRouteTable;
+  /** Announces the table again, tagged with `generation` (call on generation commit). */
+  publishRoutes(generation?: number): void;
+  /** Open HTTP exchanges plus WebSocket connections. */
+  readonly activeStreams: number;
+  /**
+   * Called when the gateway revoked a principal (after its exchanges and sockets were closed),
+   * for state the bridge does not see (e.g. sessions keyed by user). Returns an unsubscriber.
+   */
+  onPrincipalRevoked(listener: (principalId: string) => void): () => void;
+}
+
+interface Exchange {
+  readonly abort: AbortController;
+  readonly gate: CreditGate;
+  body?: InboundBody;
+  /** User id of the forwarded principal (closed on `principal-revoked`). */
+  readonly principalId?: string;
+}
+
+interface BridgedSocket {
+  principalId?: string;
+  readonly messageListeners: Set<(data: string | Uint8Array) => void>;
+  readonly closeListeners: Set<(code: number, reason: string) => void>;
+  buffered: number;
+  closed: boolean;
+  /** Ends the socket locally and fires close listeners; `notify` also tells the gateway. */
+  finish(code: number, reason: string, notify: boolean): void;
+}
+
+export function createBridgedHttpHost(options: BridgedHttpHostOptions): BridgedHttpHost {
+  const limits: BridgeLimits = Object.freeze({ ...DEFAULT_BRIDGE_LIMITS, ...options.limits });
+  const { channel } = options;
+  let addresses: readonly HttpHostAddress[] = Object.freeze([]);
+  const tokenRegistry = new TokenRegistry();
+  const router: HttpRouter = createHttpRouter({
+    ...options,
+    tokenRegistry,
+    authentication: 'forwarded',
+    address: () => addresses[0],
+    secure: false,
+  });
+  const exchanges = new Map<string, Exchange>();
+  const sockets = new Map<string, BridgedSocket>();
+  let listening = false;
+  let closed = false;
+  let revision = 0;
+  let generation: number | undefined;
+  let lastSent: string | undefined;
+  let publishScheduled = false;
+  let closeResult: Promise<void> | undefined;
+  const disposers: Array<() => void> = [];
+  let lastCatalog: string | undefined;
+  const revokedListeners = new Set<(principalId: string) => void>();
+
+  const send = (message: InstanceToGatewayMessage): void => {
+    try { channel.send(message); } catch { /* channel gone */ }
+  };
+
+  // Closed registry: initialized (no open Host, no bootstrap token), never resolves a bearer;
+  // audit entries are written by the gateway.
+  const forwardedAccess: ConsoleAccessProvider = Object.freeze({
+    initialized: () => true,
+    authenticate: async () => null,
+    audit: (entry: ConsoleAuditEntry) => {
+      if (listening && !closed) send({ type: 'audit', payload: { entry: cloneableAudit(entry) } });
+    },
+  });
+  tokenRegistry.useAccessProvider(forwardedAccess);
+
+  /** Reports the plugin permission catalog when it changed (or always with `force`). */
+  function sendCatalog(force: boolean): void {
+    if (!listening || closed) return;
+    let pluginPermissions;
+    try {
+      pluginPermissions = JSON.parse(JSON.stringify(tokenRegistry.pluginPermissions())) as ReturnType<TokenRegistry['pluginPermissions']>;
+    } catch {
+      return;
+    }
+    const fingerprint = JSON.stringify(pluginPermissions);
+    if (!force && fingerprint === lastCatalog) return;
+    lastCatalog = fingerprint;
+    send({ type: 'catalog', payload: { pluginPermissions } });
+  }
+
+  function revokePrincipal(principalId: string): void {
+    for (const [id, exchange] of [...exchanges]) {
+      if (exchange.principalId === principalId) abortExchange(id, 'Credentials revoked', true);
+    }
+    for (const socket of [...sockets.values()]) {
+      if (socket.principalId === principalId) socket.finish(PRINCIPAL_REVOKED_CLOSE_CODE, 'Credentials revoked', true);
+    }
+    for (const listener of [...revokedListeners]) {
+      try { listener(principalId); } catch { /* listener failure stays local */ }
+    }
+  }
+
+  function routeTable(): BridgeRouteTable {
+    if (closed) {
+      return Object.freeze({ revision, ...(generation !== undefined ? { generation } : {}), apiBase: router.apiBase, http: Object.freeze([]), ws: Object.freeze([]) });
+    }
+    return Object.freeze({
+      revision,
+      ...(generation !== undefined ? { generation } : {}),
+      apiBase: router.apiBase,
+      http: Object.freeze(router.listRoutes().map((route) => {
+        const meta = cloneableMeta(route.meta);
+        return Object.freeze({ method: route.method, pattern: route.pattern, ...(meta ? { meta } : {}) });
+      })),
+      ws: router.listWsRoutes(),
+    });
+  }
+
+  function sendRoutes(force: boolean): void {
+    if (!listening) return;
+    const table = routeTable();
+    const fingerprint = JSON.stringify([table.generation, table.http, table.ws]);
+    if (!force && fingerprint === lastSent) return;
+    lastSent = fingerprint;
+    revision += 1;
+    // The catalog follows the generation: report it before the table that serves it.
+    sendCatalog(false);
+    send({ type: 'routes', payload: { table: { ...table, revision } } });
+  }
+
+  // Registration bursts (a generation registering dozens of routes) coalesce into one table.
+  const schedulePublish = (): void => {
+    if (!listening || publishScheduled) return;
+    publishScheduled = true;
+    queueMicrotask(() => {
+      publishScheduled = false;
+      sendRoutes(false);
+    });
+  };
+
+  // ---- HTTP
+
+  async function handleRequest(message: HttpRequestMessage): Promise<void> {
+    const { id, payload } = message;
+    if (exchanges.has(id) || sockets.has(id)) return;
+    if (!listening || closed || exchanges.size + sockets.size >= limits.maxStreams) {
+      send({ type: 'http.response.head', id, payload: { status: 503, headers: [], body: false } });
+      send({ type: 'http.response.end', id, payload: {} });
+      return;
+    }
+    const principal = payload.principal === undefined ? undefined : parseBridgePrincipal(payload.principal);
+    const principalId = userIdOf(principal);
+    const exchange: Exchange = {
+      abort: new AbortController(),
+      gate: new CreditGate(limits.initialCreditBytes),
+      ...(principalId ? { principalId } : {}),
+    };
+    exchanges.set(id, exchange);
+    const method = payload.method.toUpperCase();
+    if (payload.body && !BODYLESS_METHODS.has(method)) {
+      exchange.body = new InboundBody({
+        window: limits.initialCreditBytes,
+        grant: (bytes) => { if (exchanges.get(id) === exchange) send({ type: 'http.request.credit', id, payload: { bytes } }); },
+        // The gateway stops sending once the response ends; nothing to tell it now.
+        cancel: () => undefined,
+      });
+    }
+    try {
+      let request: Request;
+      try {
+        request = new Request(payload.url, {
+          method,
+          headers: fromBridgeHeaders(payload.headers),
+          signal: exchange.abort.signal,
+          ...(exchange.body ? { body: exchange.body.stream, duplex: 'half' } : {}),
+        } as RequestInit);
+      } catch {
+        sendHead(id, new Response(null, { status: 400 }));
+        send({ type: 'http.response.end', id, payload: {} });
+        return;
+      }
+      const response = await router.handle(request, {
+        ...(payload.remoteAddress ? { remoteAddress: payload.remoteAddress } : {}),
+        ...(principal ? { principal } : {}),
+      });
+      if (exchange.abort.signal.aborted) {
+        await response.body?.cancel(exchange.abort.signal.reason).catch(() => undefined);
+        return;
+      }
+      sendHead(id, response);
+      if (response.body) {
+        await pumpBody(response.body, {
+          gate: exchange.gate,
+          maxChunkBytes: limits.maxChunkBytes,
+          signal: exchange.abort.signal,
+          send: (chunk) => send({ type: 'http.response.body', id, payload: { chunk } }),
+        });
+      }
+      if (!exchange.abort.signal.aborted) send({ type: 'http.response.end', id, payload: {} });
+    } catch (error) {
+      if (!exchange.abort.signal.aborted) {
+        logger.debug(formatCompact({ op: 'bridge_response_failed', error: errorText(error) }));
+        send({ type: 'http.response.error', id, payload: { message: errorText(error).slice(0, 512) } });
+      }
+    } finally {
+      if (exchanges.get(id) === exchange) exchanges.delete(id);
+      exchange.gate.close();
+      exchange.body?.fail(new Error('Exchange finished'));
+    }
+  }
+
+  function sendHead(id: string, response: Response): void {
+    send({
+      type: 'http.response.head',
+      id,
+      payload: {
+        status: response.status,
+        ...(response.statusText ? { statusText: response.statusText.slice(0, 256) } : {}),
+        headers: toBridgeHeaders(response.headers),
+        body: response.body !== null,
+      },
+    });
+  }
+
+  function abortExchange(id: string, reason: string, notify: boolean): void {
+    const exchange = exchanges.get(id);
+    if (!exchange) return;
+    exchanges.delete(id);
+    const error = new Error(reason);
+    exchange.abort.abort(error);
+    exchange.gate.close(error);
+    exchange.body?.fail(error);
+    if (notify) send({ type: 'http.response.error', id, payload: { message: reason } });
+  }
+
+  // ---- WebSocket
+
+  async function handleWsOpen(message: WsOpenMessage): Promise<void> {
+    const { id, payload } = message;
+    if (exchanges.has(id) || sockets.has(id)) return;
+    if (!listening || closed || exchanges.size + sockets.size >= limits.maxStreams) {
+      send({ type: 'ws.rejected', id, payload: { status: 503 } });
+      return;
+    }
+    let url: URL;
+    try {
+      url = new URL(payload.url);
+    } catch {
+      send({ type: 'ws.rejected', id, payload: { status: 404 } });
+      return;
+    }
+    const principal = payload.principal === undefined ? undefined : parseBridgePrincipal(payload.principal);
+    // Reserve the id while the upgrade is decided, so a racing ws.close is not lost.
+    const socket = createSocket(id);
+    const principalId = userIdOf(principal);
+    if (principalId) socket.principalId = principalId;
+    sockets.set(id, socket);
+    const decision = await router.upgrade({
+      url,
+      headers: fromBridgeHeaders(payload.headers),
+      ...(payload.remoteAddress ? { remoteAddress: payload.remoteAddress } : {}),
+      ...(principal ? { principal } : {}),
+    }).catch(() => ({ accepted: false as const, status: 404 as const }));
+    if (!decision.accepted) {
+      sockets.delete(id);
+      if (!socket.closed) send({ type: 'ws.rejected', id, payload: { status: decision.status } });
+      return;
+    }
+    if (socket.closed || closed) {
+      sockets.delete(id);
+      decision.reject();
+      if (!socket.closed) send({ type: 'ws.rejected', id, payload: { status: 503 } });
+      return;
+    }
+    send({ type: 'ws.accepted', id, payload: {} });
+    const transport: WsTransport = {
+      send(data) {
+        if (socket.closed) return;
+        const size = wsMessageSize(data);
+        if (size > limits.maxWsMessageBytes) {
+          socket.finish(1009, 'Message too big', true);
+          return;
+        }
+        if (socket.buffered + size > limits.maxWsBufferedBytes) {
+          socket.finish(1013, 'Bridge backpressure', true);
+          return;
+        }
+        socket.buffered += size;
+        send({ type: 'ws.message', id, payload: { data: typeof data === 'string' ? data : ownBytes(data) } });
+      },
+      close(code = 1000, reason = '') {
+        socket.finish(code, reason, true);
+      },
+      onMessage(listener) {
+        socket.messageListeners.add(listener);
+        return () => { socket.messageListeners.delete(listener); };
+      },
+      onClose(listener) {
+        socket.closeListeners.add(listener);
+        return () => { socket.closeListeners.delete(listener); };
+      },
+      get bufferedAmount() { return socket.buffered; },
+    };
+    decision.accept(transport);
+  }
+
+  function createSocket(id: string): BridgedSocket {
+    const socket: BridgedSocket = {
+      messageListeners: new Set(),
+      closeListeners: new Set(),
+      buffered: 0,
+      closed: false,
+      finish(code, reason, notify) {
+        if (socket.closed) return;
+        socket.closed = true;
+        if (sockets.get(id) === socket) sockets.delete(id);
+        if (notify) send({ type: 'ws.close', id, payload: { code: sendableCloseCode(code), reason: reason.slice(0, 123) } });
+        for (const listener of [...socket.closeListeners]) {
+          try { listener(code, reason); } catch { /* listener failure stays local */ }
+        }
+        socket.closeListeners.clear();
+        socket.messageListeners.clear();
+      },
+    };
+    return socket;
+  }
+
+  function deliverWsMessage(id: string, data: string | Uint8Array): void {
+    const socket = sockets.get(id);
+    if (!socket || socket.closed) return;
+    for (const listener of [...socket.messageListeners]) {
+      try {
+        listener(data);
+      } catch (error) {
+        logger.warn(formatCompact({ op: 'ws_message_listener_failed', error: errorText(error) }));
+      }
+    }
+    send({ type: 'ws.drain', id, payload: { bytes: Math.max(1, wsMessageSize(data)) } });
+  }
+
+  // ---- channel
+
+  const onMessage = (message: GatewayToInstanceMessage): void => {
+    switch (message.type) {
+      case 'host.addresses':
+        addresses = Object.freeze(message.payload.addresses.map((address) => Object.freeze({ ...address })));
+        return;
+      case 'http.request':
+        void handleRequest(message);
+        return;
+      case 'principal-revoked':
+        revokePrincipal(message.payload.principalId);
+        return;
+      case 'http.request.body': {
+        const exchange = exchanges.get(message.id);
+        if (exchange?.body && !exchange.body.push(message.payload.chunk)) {
+          abortExchange(message.id, 'Request body exceeded the granted credit', true);
+        }
+        return;
+      }
+      case 'http.request.end':
+        exchanges.get(message.id)?.body?.end();
+        return;
+      case 'http.request.abort':
+        abortExchange(message.id, message.payload.message, false);
+        return;
+      case 'http.response.credit':
+        exchanges.get(message.id)?.gate.add(message.payload.bytes);
+        return;
+      case 'ws.open':
+        void handleWsOpen(message);
+        return;
+      case 'ws.message':
+        deliverWsMessage(message.id, message.payload.data);
+        return;
+      case 'ws.close':
+        sockets.get(message.id)?.finish(message.payload.code, message.payload.reason, false);
+        return;
+      case 'ws.drain': {
+        const socket = sockets.get(message.id);
+        if (socket) socket.buffered = Math.max(0, socket.buffered - message.payload.bytes);
+        return;
+      }
+      default:
+        return;
+    }
+  };
+
+  const onDisconnect = (): void => {
+    for (const id of [...exchanges.keys()]) abortExchange(id, 'Gateway disconnected', false);
+    for (const socket of [...sockets.values()]) socket.finish(1006, 'Gateway disconnected', false);
+  };
+
+  const host: BridgedHttpHost = {
+    [generationAdmissionBinder]: (admission) => router[generationAdmissionBinder](admission),
+    [httpHostAddressProvider]: () => addresses,
+    ws: (pathname, wsOptions) => router.ws(pathname, wsOptions),
+    route: (method, path, handler, meta) => router.route(method, path, handler, meta),
+    listRoutes: () => router.listRoutes(),
+    get address() { return addresses[0]; },
+    get tokenRegistry() { return router.tokenRegistry; },
+    get activeStreams() { return exchanges.size + sockets.size; },
+    routeTable,
+    publishRoutes(next) {
+      if (next !== undefined) generation = next;
+      sendRoutes(true);
+    },
+    onPrincipalRevoked(listener) {
+      revokedListeners.add(listener);
+      return () => { revokedListeners.delete(listener); };
+    },
+    async listen() {
+      if (closed) throw new Error('HTTP Host is closed');
+      if (!listening) {
+        listening = true;
+        disposers.push(channel.onMessage(onMessage), channel.onDisconnect(onDisconnect), router.onRoutesChanged(schedulePublish));
+        // Like a listening server, a listening bridge keeps the instance alive until close().
+        if (channel.hold) disposers.push(channel.hold());
+        sendCatalog(true);
+        sendRoutes(true);
+        logger.debug(formatCompact({ op: 'bridge_listening', routes: router.routeCount, ws: router.wsPaths.length }));
+      }
+      return addresses[0];
+    },
+    close() {
+      closeResult ??= (async () => {
+        const wasListening = listening;
+        closed = true;
+        for (const id of [...exchanges.keys()]) abortExchange(id, 'Instance stopping', wasListening);
+        for (const socket of [...sockets.values()]) socket.finish(1001, 'Instance stopping', wasListening);
+        if (wasListening) sendRoutes(true);
+        listening = false;
+        router.close();
+        for (const dispose of disposers.splice(0)) dispose();
+      })();
+      return closeResult;
+    },
+  };
+  return host;
+}
+
+/** Route meta that survives structured clone (JSON data only); otherwise dropped. */
+function cloneableMeta(meta: RouteMeta | undefined): RouteMeta | undefined {
+  if (!meta) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(meta)) as RouteMeta;
+  } catch {
+    return undefined;
+  }
+}
+
+/** User id of a forwarded user / API-token principal (what `principal-revoked` names). */
+function userIdOf(principal: ConsolePrincipal | undefined): string | undefined {
+  return principal && principal.kind !== 'bootstrap' ? principal.userId : undefined;
+}
+
+/** An audit entry that survives structured clone (JSON detail only). */
+function cloneableAudit(entry: ConsoleAuditEntry): ConsoleAuditEntry {
+  try {
+    return JSON.parse(JSON.stringify(entry)) as ConsoleAuditEntry;
+  } catch {
+    const { detail: _detail, ...rest } = entry;
+    return rest;
+  }
+}
+
+/** Close codes a peer may put on the wire; reserved ones (1005, 1006, 1015) become 1000. */
+export function sendableCloseCode(code: number): number {
+  if (!Number.isInteger(code)) return 1000;
+  if ((code >= 1000 && code <= 1003) || (code >= 1007 && code <= 1014) || (code >= 3000 && code <= 4999)) return code;
+  return 1000;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}