@zhin.js/host-http 1.1.17 → 1.2.1

package/src/index.ts

@@ -1,36 +1,68 @@
 export {
-  createHttpHost,
+  createHttpRouter,
   httpHostToken,
+  normalizePath,
   REMOTE_CONSOLE_ORIGIN,
   type HttpHandler,
   type HttpHost,
-  type ProcessHttpHost,
-  type HttpHostAddress,
-  type HttpHostOptions,
-  type HttpHostTlsOptions,
+  type HttpRequestInfo,
+  type HttpRouter,
+  type HttpRouterOptions,
   type HttpRouteRegistration,
+  type RouteContext,
   type WsConnection,
   type WsHandle,
   type WsRouteOptions,
+  type WsTransport,
+  type WsUpgradeDecision,
+  type WsUpgradeRequest,
+  type ListedWsRoute,
 } from './http-host.js';
-export {
-  createHttpHostGroup,
-  listHttpHostAddresses,
-} from './listener-group.js';
+export type { HttpHostAddress, HttpHostOptions, HttpHostTlsOptions } from './host-options.js';
+export { listHttpHostAddresses } from './addresses.js';
 export {
   TokenRegistry,
   extractBearerToken,
-  isDemoWebSocketPath,
   publicConsoleAccess,
   unrestrictedConsoleAccess,
   type AuthenticatedTokenPrincipal,
   type ConsoleAccess,
   type AuthScope,
-  type DynamicTokenConfig,
-  type ScopedTokenConfig,
   type TokenRegistryConfig,
 } from './token-registry.js';
+export {
+  auditActor,
+  authorizeConsoleHttp,
+  authorizeConsoleRpc,
+  authorizeConsoleWebSocket,
+  globalPermissions,
+  isUserPrincipal,
+  isExplicitConsolePrincipal,
+  pluginRpcWriteAllowed,
+  principalAllows,
+  requestMeta,
+  rpcAuditDetail,
+  rpcAuditTarget,
+  type ConsoleAccessProvider,
+  type ConsoleAuditEntry,
+  type ConsoleBootstrapPrincipal,
+  type ConsoleHttpDecision,
+  type ConsolePrincipal,
+  type ConsoleRequestMeta,
+  type ConsoleRpcDecision,
+  type ConsoleUserPrincipal,
+} from './access-control.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
+export { isLoopbackAddress, isLoopbackHost, verifyProtocolAccessToken, type ProtocolAuthRequest } from './protocol-auth.js';
+export {
+  compileTrustProxy,
+  hasForwardingHeaders,
+  parseTrustProxy,
+  resolveClientAddress,
+  TrustProxyConfigError,
+  type TrustProxyPredicate,
+  type TrustProxySetting,
+} from './trust-proxy.js';
 export {
   createConsoleEventHub,
   consoleEventHubToken,
@@ -47,11 +79,21 @@ export {
 } from './openapi.js';
 export {
   HttpBodyError,
+  readBodyBytes,
   readJsonBody,
+  readTextBody,
+  type HttpBodyReadOptions,
 } from './json-body.js';
+export {
+  createResponseStream,
+  emptyResponse,
+  jsonResponse,
+  SSE_HEADERS,
+  type HttpResponseStream,
+  type HttpResponseStreamOptions,
+} from '@zhin.js/host-http-contract';
 export {
   dispatchRuntimeConsoleRpc,
-  isDemoHttpAllowed,
   pickRpcReply,
   type RuntimeConsolePage,
   type RuntimeConsoleRpcContext,
@@ -67,7 +109,7 @@ export {
   type PluginVerificationPlan,
   type PluginConfigValidation,
 } from './console-rpc.js';
-export { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
+export { dispatchPluginConsoleRpc, PLUGIN_SWITCH_REQUIRES_GATEWAY } from './console-plugin-rpc.js';
 export {
   buildProjectFileTree,
   FILE_MANAGER_ALLOWED,

package/src/json-body.ts

@@ -1,2 +1,7 @@
-/** @deprecated Import from @zhin.js/host-http-contract in protocol hosts. */
-export { HttpBodyError, readJsonBody } from '@zhin.js/host-http-contract';
+export {
+  HttpBodyError,
+  readBodyBytes,
+  readJsonBody,
+  readTextBody,
+  type HttpBodyReadOptions,
+} from '@zhin.js/host-http-contract';

package/src/marketplace-registry.ts

@@ -56,3 +56,65 @@ export class MarketplaceRegistry {
     return plugins;
   }
 }
+
+/** npm package name grammar (optionally scoped, lower-case, URL-safe, at most 214 chars). */
+const NPM_PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u;
+
+export function isValidNpmPackageName(name: string): boolean {
+  return name.length > 0 && name.length <= 214 && NPM_PACKAGE_NAME.test(name);
+}
+
+export interface MarketplaceDetailCacheOptions<T> {
+  readonly load: (name: string) => Promise<T>;
+  readonly ttlMs: number;
+  readonly maxEntries: number;
+  readonly now?: () => number;
+}
+
+/**
+ * Per-package detail cache: TTL, bounded size (oldest entry evicted first) and
+ * coalescing of concurrent loads. Failures are not cached.
+ */
+export class MarketplaceDetailCache<T> {
+  readonly #load: (name: string) => Promise<T>;
+  readonly #ttlMs: number;
+  readonly #maxEntries: number;
+  readonly #now: () => number;
+  readonly #entries = new Map<string, { readonly value: T; readonly expiresAt: number }>();
+  readonly #inflight = new Map<string, Promise<T>>();
+
+  constructor(options: MarketplaceDetailCacheOptions<T>) {
+    this.#load = options.load;
+    this.#ttlMs = options.ttlMs;
+    this.#maxEntries = Math.max(1, options.maxEntries);
+    this.#now = options.now ?? Date.now;
+  }
+
+  get size(): number {
+    return this.#entries.size;
+  }
+
+  get(name: string): Promise<T> {
+    const cached = this.#entries.get(name);
+    if (cached && this.#now() < cached.expiresAt) return Promise.resolve(cached.value);
+    const pending = this.#inflight.get(name);
+    if (pending) return pending;
+
+    const request = this.#load(name).then((value) => {
+      this.#entries.delete(name);
+      this.#entries.set(name, { value, expiresAt: this.#now() + this.#ttlMs });
+      while (this.#entries.size > this.#maxEntries) {
+        const oldest = this.#entries.keys().next().value;
+        if (oldest === undefined) break;
+        this.#entries.delete(oldest);
+      }
+      return value;
+    });
+    this.#inflight.set(name, request);
+    const clear = () => {
+      if (this.#inflight.get(name) === request) this.#inflight.delete(name);
+    };
+    void request.then(clear, clear);
+    return request;
+  }
+}

package/src/node/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Node transport for the HTTP Host (`@zhin.js/host-http/node`): the in-process listener
+ * and the Node `http` / `ws` ↔ Web standard conversion. The only entry of this package
+ * that loads `node:http`, `node:https` or `ws`.
+ * @module @zhin.js/host-http/node
+ */
+export { createHttpHost, type ProcessHttpHost } from './server.js';
+export { createHttpHostGroup } from './listener-group.js';
+export {
+  createNodeHttpListener,
+  type NodeHttpListener,
+  type NodeHttpListenerOptions,
+} from './listener.js';
+export {
+  createNodeRequest,
+  nodeRequestHeaders,
+  writeNodeResponse,
+  wrapNodeWebSocket,
+  type NodeRequestOptions,
+  type NodeWebSocketOptions,
+} from './node-http.js';

package/src/{listener-group.ts → node/listener-group.ts}

@@ -4,22 +4,16 @@ import {
   type GenerationAdmissionBindable,
   type GenerationAdmissionGate,
 } from '@zhin.js/plugin-runtime';
-import {
-  createHttpHost,
-  type HttpHost,
-  type HttpHostAddress,
-  type HttpHostOptions,
-  type HttpRouteRegistration,
-  type ProcessHttpHost,
-  type WsHandle,
-  type WsRouteOptions,
-} from './http-host.js';
-
-const addressProvider = Symbol('HttpHostAddressProvider');
-
-interface AddressAwareHttpHost {
-  readonly [addressProvider]: () => readonly HttpHostAddress[];
-}
+import type {
+  HttpHost,
+  HttpRouteRegistration,
+  WsHandle,
+  WsRouteOptions,
+} from '../http-host.js';
+import type { HttpHostAddress, HttpHostOptions } from '../host-options.js';
+import { TokenRegistry } from '../token-registry.js';
+import { httpHostAddressProvider as addressProvider, type AddressAwareHttpHost } from '../addresses.js';
+import { createHttpHost, type ProcessHttpHost } from './server.js';
 
 type BoundHttpHost = HttpHost & GenerationAdmissionBindable<HttpHost> & AddressAwareHttpHost;
 
@@ -32,7 +26,9 @@ export function createHttpHostGroup(
   options: readonly HttpHostOptions[],
 ): ProcessHttpHost {
   if (options.length === 0) throw new Error('HttpHostGroup requires at least one listener');
-  const listeners = options.map((entry) => createHttpHost(entry));
+  // One authentication state for the whole surface: every listener sees the same sessions.
+  const tokenRegistry = options[0]!.tokenRegistry ?? new TokenRegistry({ primaryToken: options[0]!.token });
+  const listeners = options.map((entry) => createHttpHost({ ...entry, tokenRegistry }));
 
   const createSurface = (hosts: readonly HttpHost[]): BoundHttpHost => {
     const primary = hosts[0]!;
@@ -93,13 +89,6 @@ export function createHttpHostGroup(
   return Object.freeze(runtime);
 }
 
-/** Returns every bound listener, ordered primary/local first. */
-export function listHttpHostAddresses(host: HttpHost): readonly HttpHostAddress[] {
-  const provider = (host as Partial<AddressAwareHttpHost>)[addressProvider];
-  if (typeof provider === 'function') return Object.freeze([...provider.call(host)]);
-  return Object.freeze(host.address ? [host.address] : []);
-}
-
 async function closeListeners(listeners: readonly ProcessHttpHost[]): Promise<void> {
   const results = await Promise.allSettled([...listeners].reverse().map((listener) => listener.close()));
   const errors = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);

package/src/node/listener.ts

@@ -0,0 +1,265 @@
+/**
+ * One Node `http` / `https` listener that feeds a transport-independent request handler and
+ * WebSocket upgrade handler (ADR 0054 §2). The in-process Host and the management gateway
+ * both run on it.
+ */
+import {
+  createServer as createHttpServer,
+  STATUS_CODES,
+  type IncomingMessage,
+  type Server as HttpServer,
+  type ServerResponse,
+} from 'node:http';
+import {
+  createServer as createHttpsServer,
+  type Server as HttpsServer,
+  type ServerOptions as HttpsServerOptions,
+} from 'node:https';
+import type { Socket } from 'node:net';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer } from 'ws';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { HttpRequestInfo, WsUpgradeDecision, WsUpgradeRequest } from '../http-host.js';
+import type { HttpHostAddress, HttpHostTlsOptions } from '../host-options.js';
+import { compileTrustProxy, resolveClientAddress, type TrustProxySetting } from '../trust-proxy.js';
+import { createNodeRequest, nodeRequestHeaders, writeNodeResponse, wrapNodeWebSocket } from './node-http.js';
+
+const logger = getLogger('http');
+
+export interface NodeHttpListenerOptions {
+  readonly host?: string;
+  readonly port?: number;
+  /** Enables HTTPS / WSS on this listener. */
+  readonly tls?: HttpHostTlsOptions;
+  /** `http.trustProxy`: derive `remoteAddress` from forwarding headers sent by trusted peers. */
+  readonly trustProxy?: TrustProxySetting;
+  handle(request: Request, info: HttpRequestInfo): Promise<Response>;
+  upgrade(request: WsUpgradeRequest): Promise<WsUpgradeDecision>;
+  /** Called once the listener is bound, before `listen()` resolves. */
+  onListening?(address: HttpHostAddress): void;
+  /** Called after the listener closed. */
+  onClosed?(): void;
+}
+
+export interface NodeHttpListener {
+  listen(): Promise<HttpHostAddress>;
+  /** Destroys open connections (SSE, keep-alive, WebSocket) and stops listening. */
+  close(): Promise<void>;
+  readonly address: HttpHostAddress | undefined;
+  readonly secure: boolean;
+}
+
+/** A Node listener over {@link NodeHttpListenerOptions.handle} / `upgrade`. */
+export function createNodeHttpListener(options: NodeHttpListenerOptions): NodeHttpListener {
+  const host = options.host ?? '127.0.0.1';
+  const port = options.port ?? 8086;
+  const secure = options.tls !== undefined;
+  let address: HttpHostAddress | undefined;
+  let closed = false;
+  let closeResult: Promise<void> | undefined;
+  let listenResult: Promise<HttpHostAddress> | undefined;
+  const trust = compileTrustProxy(options.trustProxy);
+  const clientAddress = (request: IncomingMessage): string | undefined =>
+    resolveClientAddress(request.socket?.remoteAddress, request.headers, trust);
+
+  const handleRequest = (request: IncomingMessage, response: ServerResponse): void => {
+    void dispatch(request, response).catch((error: unknown) => {
+      logger.warn(formatCompact({
+        op: 'http_dispatch_failed',
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      if (!response.headersSent) {
+        response.writeHead(500);
+        response.end();
+      } else {
+        response.destroy();
+      }
+    });
+  };
+  const server: HttpServer | HttpsServer = secure
+    ? createHttpsServer(options.tls as HttpsServerOptions, handleRequest)
+    : createHttpServer(handleRequest);
+
+  // Track live TCP sockets so close() can destroy long-lived connections
+  // (SSE, keep-alive) that would otherwise block server.close().
+  const sockets = new Set<Socket>();
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.once('close', () => {
+      sockets.delete(socket);
+    });
+  });
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  async function dispatch(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    if (closed) {
+      response.writeHead(503);
+      response.end();
+      return;
+    }
+    let url: URL;
+    try {
+      url = new URL(request.url ?? '/', 'http://localhost');
+    } catch {
+      response.writeHead(400);
+      response.end();
+      return;
+    }
+    const abort = new AbortController();
+    response.once('close', () => {
+      if (!response.writableFinished) abort.abort(new Error('Client disconnected'));
+    });
+    let webRequest: Request;
+    try {
+      webRequest = createNodeRequest(request, { url, signal: abort.signal });
+    } catch {
+      response.writeHead(400);
+      response.end();
+      return;
+    }
+    const remoteAddress = clientAddress(request);
+    const webResponse = await options.handle(webRequest, {
+      ...(remoteAddress ? { remoteAddress } : {}),
+    });
+    await writeNodeResponse(response, webResponse);
+  }
+
+  server.on('upgrade', (request: IncomingMessage, socket: Duplex, head: Buffer) => {
+    if (closed) {
+      socket.destroy();
+      return;
+    }
+    let url: URL;
+    try {
+      url = new URL(request.url ?? '/', 'http://localhost');
+    } catch {
+      socket.destroy();
+      return;
+    }
+    const remoteAddress = clientAddress(request);
+    void options.upgrade({
+      url,
+      headers: nodeRequestHeaders(request),
+      ...(remoteAddress ? { remoteAddress } : {}),
+    }).then((decision) => {
+      if (!decision.accepted) {
+        if (decision.status !== 404) writeUpgradeRefusal(socket, decision.status, decision.headers);
+        socket.destroy();
+        return;
+      }
+      if (closed || socket.destroyed) {
+        decision.reject();
+        writeUpgradeRefusal(socket, 401);
+        socket.destroy();
+        return;
+      }
+      let accepted = false;
+      socket.once('close', () => { if (!accepted) decision.reject(); });
+      try {
+        wss.handleUpgrade(request, socket, head, (ws) => {
+          accepted = true;
+          decision.accept(wrapNodeWebSocket(ws));
+        });
+      } catch (err) {
+        decision.reject();
+        logger.warn(formatCompact({
+          op: 'ws_upgrade_failed',
+          path: url.pathname,
+          error: err instanceof Error ? err.message : String(err),
+        }));
+        try {
+          socket.destroy();
+        } catch {
+          /* already destroyed */
+        }
+      }
+    }, () => socket.destroy());
+  });
+
+  return {
+    get address() { return address; },
+    secure,
+    listen(): Promise<HttpHostAddress> {
+      if (closed) return Promise.reject(new Error('HTTP Host is closed'));
+      if (listenResult) return listenResult;
+      if (address) return Promise.resolve(address);
+      listenResult = new Promise((resolve, reject) => {
+        const onError = (error: Error): void => {
+          listenResult = undefined;
+          reject(error);
+        };
+        server.once('error', onError);
+        server.listen({ host, port }, () => {
+          server.off('error', onError);
+          if (closed) {
+            reject(new Error('HTTP Host closed before listen completed'));
+            return;
+          }
+          const bound = server.address();
+          const listenPort = typeof bound === 'object' && bound ? bound.port : port;
+          const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+          const protocol = secure ? 'https' : 'http';
+          const originHost = publicHost.includes(':') ? `[${publicHost}]` : publicHost;
+          address = Object.freeze({
+            host: publicHost, port: listenPort, protocol, secure,
+            origin: `${protocol}://${originHost}:${listenPort}`,
+          });
+          options.onListening?.(address);
+          resolve(address);
+        });
+      });
+      return listenResult;
+    },
+    close(): Promise<void> {
+      if (closeResult) return closeResult;
+      closed = true;
+      closeResult = (async () => {
+        // A pending listen must settle before deciding whether there is a
+        // listener to close. Otherwise it can bind after close has resolved.
+        await listenResult?.catch(() => undefined);
+        if (!server.listening) {
+          address = undefined;
+          return;
+        }
+        await new Promise<void>((resolve, reject) => {
+          // Long-lived connections (SSE, keep-alive, WS) never end on their own:
+          // destroy tracked sockets and terminate WS clients before close(),
+          // otherwise the close callbacks would never fire.
+          for (const socket of sockets) socket.destroy();
+          sockets.clear();
+          for (const client of wss.clients) client.terminate();
+          wss.close((wssError) => {
+            if (wssError) {
+              reject(wssError);
+              return;
+            }
+            server.close((serverError) => {
+              if (serverError) {
+                reject(serverError);
+                return;
+              }
+              address = undefined;
+              options.onClosed?.();
+              resolve();
+            });
+          });
+        });
+      })();
+      return closeResult;
+    },
+  };
+}
+
+function writeUpgradeRefusal(
+  socket: Duplex,
+  status: number,
+  headers?: Readonly<Record<string, string>>,
+): void {
+  if (socket.destroyed) return;
+  const lines = [`HTTP/1.1 ${status} ${STATUS_CODES[status] ?? ''}`.trimEnd()];
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (/^[!#$%&'*+.^_`|~0-9a-z-]+$/iu.test(name) && !/[\r\n]/u.test(value)) lines.push(`${name}: ${value}`);
+  }
+  socket.write(`${lines.join('\r\n')}\r\n\r\n`);
+}