@zhin.js/host-http 1.1.17 → 1.2.1

package/src/node/node-http.ts

@@ -0,0 +1,263 @@
+/**
+ * Node `http` / `ws` ↔ Web standard conversion (ADR 0054 §2). This module and the
+ * server built on it are the only places in `@zhin.js/host-http` that load
+ * `node:http` or `ws`; the gateway reuses them for its listener.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { WebSocket, type RawData } from 'ws';
+import type { WsTransport } from '../http-host.js';
+
+const BODYLESS_METHODS = new Set(['GET', 'HEAD']);
+
+export interface NodeRequestOptions {
+  /** Absolute request URL. */
+  readonly url: URL;
+  /** Aborted when the client goes away before the response finished. */
+  readonly signal?: AbortSignal;
+  /** Bytes buffered from the socket before reading pauses (default 64 KiB). */
+  readonly highWaterMark?: number;
+}
+
+/** Headers of a Node request as a Web `Headers` (repeated headers preserved). */
+export function nodeRequestHeaders(request: IncomingMessage): Headers {
+  const headers = new Headers();
+  const raw = request.rawHeaders;
+  for (let index = 0; index + 1 < raw.length; index += 2) {
+    const name = raw[index]!;
+    if (name.startsWith(':')) continue;
+    try {
+      headers.append(name, raw[index + 1]!);
+    } catch { /* invalid for the Fetch API: skip */ }
+  }
+  return headers;
+}
+
+/**
+ * A Web `Request` over a Node request. The body streams from the socket with
+ * backpressure; cancelling it (or reading it to the end) never destroys the
+ * socket, so the response can still be written on the same connection.
+ */
+export function createNodeRequest(request: IncomingMessage, options: NodeRequestOptions): Request {
+  const method = (request.method ?? 'GET').toUpperCase();
+  const body = BODYLESS_METHODS.has(method) ? null : nodeBodyStream(request, options.highWaterMark ?? 65_536);
+  return new Request(options.url, {
+    method,
+    headers: nodeRequestHeaders(request),
+    ...(body ? { body, duplex: 'half' } : {}),
+    ...(options.signal ? { signal: options.signal } : {}),
+  } as RequestInit);
+}
+
+function nodeBodyStream(request: IncomingMessage, highWaterMark: number): ReadableStream<Uint8Array> {
+  let settled = false;
+  let cancelled = false;
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      request.on('data', (chunk: Buffer | string) => {
+        if (cancelled) return;
+        const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        controller.enqueue(new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+        if ((controller.desiredSize ?? 0) <= 0) request.pause();
+      });
+      request.once('end', () => {
+        if (settled) return;
+        settled = true;
+        if (!cancelled) controller.close();
+      });
+      const fail = (error: Error): void => {
+        if (settled) return;
+        settled = true;
+        if (!cancelled) controller.error(error);
+      };
+      request.once('error', fail);
+      request.once('close', () => {
+        if (!request.complete) fail(new Error('Request aborted'));
+      });
+      request.pause();
+    },
+    pull() {
+      request.resume();
+    },
+    cancel() {
+      // Discard the rest instead of destroying the socket.
+      cancelled = true;
+      request.resume();
+    },
+  }, new ByteLengthQueuingStrategy({ highWaterMark }));
+}
+
+/**
+ * Writes a Web `Response` to a Node response: status, headers (`set-cookie`
+ * kept separate) and the body, honouring `drain` backpressure. A body that is
+ * immediately complete is sent with `Content-Length`; otherwise headers are
+ * flushed at once (SSE) and the body is chunked. A body stream error destroys
+ * the connection; a client disconnect cancels the body.
+ */
+export async function writeNodeResponse(target: ServerResponse, response: Response): Promise<void> {
+  target.statusCode = response.status;
+  if (response.statusText) target.statusMessage = response.statusText;
+  const cookies = response.headers.getSetCookie();
+  for (const [name, value] of response.headers) {
+    if (name === 'set-cookie') continue;
+    target.setHeader(name, value);
+  }
+  if (cookies.length > 0) target.setHeader('set-cookie', cookies);
+  const body = response.body;
+  if (!body) {
+    target.end();
+    return;
+  }
+  const reader = body.getReader();
+  let disconnected = false;
+  let cancelled: Promise<void> | undefined;
+  const onClose = (): void => {
+    if (target.writableFinished) return;
+    disconnected = true;
+    cancelled = reader.cancel(new Error('Client disconnected')).catch(() => undefined);
+  };
+  target.once('close', onClose);
+  try {
+    let read = reader.read();
+    let first = await raceImmediate(read);
+    if (first === PENDING) {
+      // Nothing to send yet (SSE): commit the headers now.
+      target.flushHeaders();
+      first = await read;
+    }
+    if (first.done) {
+      target.end();
+      return;
+    }
+    let chunk: Uint8Array = first.value;
+    read = reader.read();
+    const second = await raceImmediate(read);
+    if (second !== PENDING && second.done) {
+      target.end(chunk);
+      return;
+    }
+    for (;;) {
+      if (disconnected || target.destroyed) return;
+      if (!target.write(chunk)) await waitForDrain(target);
+      if (disconnected || target.destroyed) return;
+      const next = await read;
+      if (next.done) break;
+      chunk = next.value;
+      read = reader.read();
+    }
+    if (!target.destroyed) target.end();
+  } catch (error) {
+    if (!disconnected && !target.destroyed) target.destroy(error instanceof Error ? error : new Error(String(error)));
+  } finally {
+    target.off('close', onClose);
+    // A disconnect cancels the body: let its source finish cleaning up first.
+    await cancelled;
+    try { reader.releaseLock(); } catch { /* read still pending after disconnect */ }
+  }
+}
+
+const PENDING = Symbol('pending');
+
+/** Settles with the promise's value if it is ready before the next macrotask, else PENDING. */
+function raceImmediate<T>(promise: Promise<T>): Promise<T | typeof PENDING> {
+  return new Promise((resolve, reject) => {
+    const timer = setImmediate(() => resolve(PENDING));
+    promise.then((value) => {
+      clearImmediate(timer);
+      resolve(value);
+    }, (error: unknown) => {
+      clearImmediate(timer);
+      reject(error);
+    });
+  });
+}
+
+function waitForDrain(target: ServerResponse): Promise<void> {
+  return new Promise((resolve) => {
+    const done = (): void => {
+      target.off('drain', done);
+      target.off('close', done);
+      resolve();
+    };
+    target.once('drain', done);
+    target.once('close', done);
+  });
+}
+
+export interface NodeWebSocketOptions {
+  /** Protocol ping interval; a peer that misses one pong is terminated. 0 disables. Default 30 s. */
+  readonly keepAliveMs?: number;
+}
+
+/** A {@link WsTransport} over a `ws` server socket. */
+export function wrapNodeWebSocket(socket: WebSocket, options: NodeWebSocketOptions = {}): WsTransport {
+  const messageListeners = new Set<(data: string | Uint8Array) => void>();
+  const closeListeners = new Set<(code: number, reason: string) => void>();
+  let closedWith: { code: number; reason: string } | undefined;
+  socket.on('message', (data: RawData, isBinary: boolean) => {
+    const value = isBinary ? rawBytes(data) : rawBytes(data).toString('utf8');
+    for (const listener of [...messageListeners]) {
+      try { listener(value); } catch { /* isolate listener failures */ }
+    }
+  });
+  socket.on('error', () => { /* followed by close */ });
+  let alive = true;
+  const keepAliveMs = options.keepAliveMs ?? 30_000;
+  const timer = keepAliveMs > 0
+    ? setInterval(() => {
+      if (!alive) {
+        socket.terminate();
+        return;
+      }
+      alive = false;
+      try { socket.ping(); } catch { /* closing */ }
+    }, keepAliveMs)
+    : undefined;
+  timer?.unref?.();
+  socket.on('pong', () => { alive = true; });
+  socket.once('close', (code: number, reason: Buffer) => {
+    if (timer) clearInterval(timer);
+    closedWith = { code, reason: reason.toString('utf8') };
+    messageListeners.clear();
+    for (const listener of [...closeListeners]) {
+      try { listener(closedWith.code, closedWith.reason); } catch { /* isolate listener failures */ }
+    }
+    closeListeners.clear();
+  });
+  return {
+    send(data) {
+      if (socket.readyState !== WebSocket.OPEN) return;
+      socket.send(data);
+    },
+    close(code, reason) {
+      if (socket.readyState === WebSocket.CLOSING || socket.readyState === WebSocket.CLOSED) return;
+      try {
+        socket.close(code, reason);
+      } catch {
+        socket.terminate();
+      }
+    },
+    onMessage(listener) {
+      if (closedWith) return () => undefined;
+      messageListeners.add(listener);
+      return () => { messageListeners.delete(listener); };
+    },
+    onClose(listener) {
+      if (closedWith) {
+        const { code, reason } = closedWith;
+        queueMicrotask(() => listener(code, reason));
+        return () => undefined;
+      }
+      closeListeners.add(listener);
+      return () => { closeListeners.delete(listener); };
+    },
+    get bufferedAmount() {
+      return socket.bufferedAmount;
+    },
+  };
+}
+
+function rawBytes(data: RawData): Buffer {
+  if (Buffer.isBuffer(data)) return data;
+  if (Array.isArray(data)) return Buffer.concat(data);
+  return Buffer.from(data);
+}

package/src/node/server.ts

@@ -0,0 +1,82 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  generationAdmissionBinder,
+  type GenerationAdmissionBindable,
+} from '@zhin.js/plugin-runtime';
+import { createHttpRouter, type HttpHost } from '../http-host.js';
+import type { HttpHostAddress, HttpHostOptions } from '../host-options.js';
+import { createNodeHttpListener } from './listener.js';
+
+const logger = getLogger('http');
+
+/** @internal Process-root lifecycle and generation admission surface. */
+export interface ProcessHttpHost extends HttpHost, GenerationAdmissionBindable<HttpHost> {
+  listen(): Promise<HttpHostAddress>;
+  close(): Promise<void>;
+}
+
+/**
+ * In-process Node listener for the transport-independent router: Node requests become
+ * Web `Request`s, `Response`s are streamed back, `ws` sockets become `WsConnection`s.
+ */
+export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
+  const secure = options.tls !== undefined;
+  let closeResult: Promise<void> | undefined;
+
+  const router = createHttpRouter({
+    token: options.token,
+    corsOrigins: options.corsOrigins,
+    apiBase: options.apiBase,
+    authExemptPaths: options.authExemptPaths,
+    tokenRegistry: options.tokenRegistry,
+    secure,
+    address: () => listener.address,
+  });
+  const tokenRegistry = router.tokenRegistry;
+
+  const listener = createNodeHttpListener({
+    host: options.host,
+    port: options.port,
+    tls: options.tls,
+    trustProxy: options.trustProxy,
+    handle: (request, info) => router.handle(request, info),
+    upgrade: (request) => router.upgrade(request),
+    onListening(address) {
+      logger.info(
+        `listening ${address.origin}`
+        + ` | routes: ${router.routeCount}`
+        + ` | token: ${tokenRegistry.hasAnyToken()
+          ? tokenRegistry.primaryTokenPrefixForLog()
+          : '(none)'}`,
+      );
+      logger.debug(
+        `listen detail | cors: ${router.corsOrigins.join(',')}`
+        + ` | ws: ${router.wsPaths.join(',') || '(none)'}`,
+      );
+    },
+    onClosed() {
+      logger.debug(formatCompact({ op: 'http_host_closed' }));
+    },
+  });
+
+  const runtime: ProcessHttpHost = {
+    [generationAdmissionBinder]: (admission) => router[generationAdmissionBinder](admission),
+    ws: (pathname, wsOptions) => router.ws(pathname, wsOptions),
+    route: (method, path, handler, meta) => router.route(method, path, handler, meta),
+    listRoutes: () => router.listRoutes(),
+    get address() {
+      return listener.address;
+    },
+    get tokenRegistry() {
+      return tokenRegistry;
+    },
+    listen: () => listener.listen(),
+    close(): Promise<void> {
+      if (closeResult) return closeResult;
+      router.close();
+      closeResult = listener.close();
+      return closeResult;
+    },
+  };
+  return runtime;
+}

package/src/protocol-auth.ts

@@ -0,0 +1,52 @@
+import { timingSafeEqualString } from './timing-safe-equal.js';
+import { hasForwardingHeaders } from './trust-proxy.js';
+
+/** What a protocol credential check needs from an HTTP request or a {@link WsConnection}. */
+export interface ProtocolAuthRequest {
+  readonly headers: Headers;
+  readonly url: URL | string;
+  readonly remoteAddress?: string;
+}
+
+/** IPv4 / IPv6 / IPv4-mapped loopback peer. */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (!address) return false;
+  if (address === '::1') return true;
+  const v4 = address.startsWith('::ffff:') ? address.slice(7) : address;
+  return /^127(?:\.\d{1,3}){3}$/u.test(v4);
+}
+
+/**
+ * Whether a listen address (`http.host`) only accepts connections from this machine:
+ * `localhost`, `127.0.0.0/8`, `::1` (bracketed or not). `0.0.0.0`, `::` and any other address are
+ * reachable from the network.
+ */
+export function isLoopbackHost(host: string | undefined): boolean {
+  if (host === undefined || host === '') return true; // the listener default is 127.0.0.1
+  const bare = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+  return bare.toLowerCase() === 'localhost' || isLoopbackAddress(bare);
+}
+
+/**
+ * Access check for a plugin socket mounted with `ws(path, { auth: 'protocol' })` (adapter
+ * reverse WebSockets: OneBot, NapCat, Milky…) or a protocol webhook. With an access token the
+ * peer must present it as `Authorization: Bearer <token>` or `?access_token=<token>`
+ * (constant-time compare); without one only loopback peers are admitted, so an unconfigured
+ * socket is never public. Proxied traffic (`X-Forwarded-For` / `Forwarded` present) never counts
+ * as loopback: a same-host reverse proxy would otherwise make every client local. A {@link WsConnection} can be passed directly; for an HTTP route pass
+ * `{ headers: request.headers, url: context.url, remoteAddress: context.remoteAddress }`.
+ */
+export function verifyProtocolAccessToken(accessToken: string | undefined, request: ProtocolAuthRequest): boolean {
+  if (!accessToken) return isLoopbackAddress(request.remoteAddress) && !hasForwardingHeaders(request.headers);
+  const header = request.headers.get('authorization');
+  if (typeof header === 'string' && header.startsWith('Bearer ')
+    && timingSafeEqualString(header.slice(7).trim(), accessToken)) return true;
+  let presented: string | null = null;
+  try {
+    const url = typeof request.url === 'string' ? new URL(request.url, 'http://localhost') : request.url;
+    presented = url.searchParams.get('access_token');
+  } catch {
+    presented = null;
+  }
+  return presented !== null && timingSafeEqualString(presented, accessToken);
+}

package/src/public-api.ts

@@ -8,8 +8,10 @@ export {
   type HttpHost,
   type HttpHostAddress,
   type HttpRouteRegistration,
+  type RouteContext,
   type WsConnection,
   type WsHandle,
+  type WsRouteOptions,
 } from './http-host.js';
 export type { AuthenticatedTokenPrincipal, AuthScope } from './token-registry.js';
 export type { ListedRoute, OpenApiParameter, RouteMeta } from './openapi.js';