@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/http/gateway-http-server.js

@@ -0,0 +1,522 @@
+/**
+ * The gateway's HTTP server (ADR 0054 §2 / §3): the project's only listener.
+ *
+ * Request flow:
+ * 1. gateway-owned routes ({@link GatewayHttpServer.route} / `ws`) — health, `/auth/*`,
+ *    terminal, the merged Console event stream, package progress; gateway-owned Console RPC
+ *    (`gateway.*`, `iam.*`, `onboarding.update`) inside `POST {base}/console/request`;
+ * 2. `{base}/…` — authenticated and authorized here, then forwarded with the principal;
+ * 3. anything else (plugin webhooks, adapter reverse WebSockets, static pages) — forwarded as-is;
+ *    those routes authenticate themselves.
+ *
+ * The instance being offline never takes gateway-owned routes down: forwarded requests get
+ * `503 { code: 'instance_unavailable', state }` with `Retry-After`; an instance that does not
+ * answer in time gives `504 { code: 'instance_timeout' }`, any other bridge failure
+ * `502 { code: 'instance_error' }` (mapped from {@link InstanceTransportError}).
+ */
+import { authorizeConsoleWebSocket, auditActor, createHttpRouter, extractBearerToken, jsonResponse, normalizePath, requestMeta, TokenRegistry, } from '@zhin.js/host-http';
+import { InstanceTransportError, } from '@zhin.js/host-http/bridge';
+import { createNodeHttpListener } from '@zhin.js/host-http/node';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { databaseBusyResponse, isDatabaseBusyError } from '../database/project-database.js';
+import { GATEWAY_RPC_PREFIX } from './console-rpc.js';
+import { LOCAL_OWNER_PRINCIPAL } from './local-principal.js';
+const logger = getLogger('gateway');
+export const DEFAULT_GATEWAY_RETRY_AFTER_SECONDS = 5;
+/** Default cap on a forwarded request body (uploads go through the instance). */
+export const DEFAULT_GATEWAY_MAX_REQUEST_BODY_BYTES = 64 * 1024 * 1024;
+/** Client frames kept while the instance side of a forwarded socket is being opened. */
+const WS_PENDING_FRAME_LIMIT = 256;
+const WS_PENDING_BYTE_LIMIT = 4 * 1024 * 1024;
+const HOP_BY_HOP_HEADERS = Object.freeze([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'proxy-connection',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+/** One router, many listeners: every listener serves the same surface. */
+export class GatewayHttpServer {
+    tokenRegistry;
+    apiBase;
+    #router;
+    /**
+     * The same surface for `gateway.http.request` without a credential: a `forwarded` router that
+     * takes {@link LOCAL_OWNER_PRINCIPAL} as authenticated and still authorizes every route against
+     * the Console permission map, like the HTTP router does.
+     */
+    #localRouter;
+    #listeners;
+    #instance;
+    #retryAfter;
+    #maxBody;
+    #consoleRpc;
+    #rpcHandlers = new Set();
+    #closed = false;
+    #closeResult;
+    constructor(options) {
+        const { listeners: extra = [], ...primary } = options.http ?? {};
+        const listenerOptions = [primary, ...extra];
+        this.#instance = options.instance;
+        this.#retryAfter = String(Math.max(1, Math.round(options.retryAfterSeconds ?? DEFAULT_GATEWAY_RETRY_AFTER_SECONDS)));
+        this.#maxBody = options.maxRequestBodyBytes ?? DEFAULT_GATEWAY_MAX_REQUEST_BODY_BYTES;
+        this.#consoleRpc = options.consoleRpc;
+        this.tokenRegistry = options.tokenRegistry ?? new TokenRegistry({ primaryToken: primary.token });
+        this.apiBase = normalizePath(primary.apiBase ?? '/api');
+        const routerOptions = {
+            corsOrigins: primary.corsOrigins,
+            apiBase: this.apiBase,
+            authExemptPaths: primary.authExemptPaths,
+            tokenRegistry: this.tokenRegistry,
+            secure: primary.tls !== undefined,
+            address: () => this.address,
+            builtinRoutes: false,
+        };
+        this.#router = createHttpRouter(routerOptions);
+        this.#localRouter = createHttpRouter({ ...routerOptions, authentication: 'forwarded' });
+        for (const router of [this.#router, this.#localRouter]) {
+            router.route('GET', '/pub/health', () => this.#health(), { summary: 'Gateway health probe', tags: ['pub'] });
+            router.route('POST', `${this.apiBase}/console/request`, (request, context) => this.#consoleRequest(request, context), {
+                summary: 'Console RPC (gateway-owned types answered by the gateway, the rest forwarded)',
+                tags: ['console'],
+            });
+            // Lowest precedence: every path no gateway route claims goes to the instance.
+            router.route('ALL', '/*', (request, context) => this.#forward(request, context));
+        }
+        this.#listeners = listenerOptions.map((entry) => createNodeHttpListener({
+            host: entry.host,
+            port: entry.port,
+            tls: entry.tls,
+            trustProxy: entry.trustProxy,
+            handle: (request, info) => this.#router.handle(request, info),
+            upgrade: (request) => this.#upgrade(request),
+            onListening: (address) => {
+                logger.info(formatCompact({ op: 'gateway_listening', origin: address.origin, base: this.apiBase }));
+            },
+        }));
+    }
+    /** Registers a gateway-owned route; it takes precedence over the instance's routes. */
+    route(method, path, handler, meta) {
+        const wrapped = withDatabaseBusy(handler);
+        const unregister = [this.#router.route(method, path, wrapped, meta), this.#localRouter.route(method, path, wrapped, meta)];
+        return () => { for (const release of unregister)
+            release(); };
+    }
+    /** Registers a gateway-owned WebSocket route. */
+    ws(path, options) {
+        return this.#router.ws(path, options);
+    }
+    /**
+     * Answers further RPC types on `POST {base}/console/request` (e.g. `iam.*`); the handler checks
+     * the per-RPC permission itself. Returns an unregister function.
+     */
+    useConsoleRpc(handler) {
+        this.#rpcHandlers.add(handler);
+        return () => { this.#rpcHandlers.delete(handler); };
+    }
+    /** Whether an instance is connected and serving its route table. */
+    get instanceReady() {
+        return this.#readyTransport() !== undefined;
+    }
+    /**
+     * Forwards one request to the instance (the router already authenticated and authorized it):
+     * the instance's response, or the documented 502 / 503 / 504 / 413 gateway responses.
+     */
+    forward(request, context) {
+        return this.#forward(request, context);
+    }
+    /** Handles one request without a socket (tests, local socket bridge). */
+    handle(request, info = {}) {
+        return this.#router.handle(request, info);
+    }
+    /** Primary listener address. */
+    get address() {
+        return this.#listeners[0]?.address;
+    }
+    /** Addresses of every bound listener, primary first. */
+    get addresses() {
+        return this.#listeners.flatMap((listener) => listener.address ? [listener.address] : []);
+    }
+    async listen() {
+        if (this.#closed)
+            throw new Error('Gateway HTTP server is closed');
+        try {
+            for (const listener of this.#listeners)
+                await listener.listen();
+        }
+        catch (error) {
+            await Promise.allSettled([...this.#listeners].reverse().map((listener) => listener.close()));
+            throw error;
+        }
+        return this.#listeners[0].address;
+    }
+    close() {
+        this.#closeResult ??= (async () => {
+            this.#closed = true;
+            this.#router.close();
+            this.#localRouter.close();
+            const results = await Promise.allSettled([...this.#listeners].reverse().map((listener) => listener.close()));
+            const errors = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1)
+                throw new AggregateError(errors, 'multiple gateway listeners failed to close');
+        })();
+        return this.#closeResult;
+    }
+    #readyTransport() {
+        const transport = this.#instance.transport();
+        return transport?.ready ? transport : undefined;
+    }
+    #health() {
+        const body = {
+            success: true,
+            status: 'ok',
+            timestamp: new Date().toISOString(),
+            instance: { state: this.#instance.state(), ready: this.#readyTransport() !== undefined },
+        };
+        // Polled by the Console's instance banner: never cached.
+        return jsonResponse(200, body, { 'cache-control': 'no-store' });
+    }
+    #unavailable() {
+        return this.#instanceError(503, 'instance_unavailable', 'not-dispatched', 'The Zhin instance is not running', true);
+    }
+    /** One body shape for every forward failure (`GatewayInstanceErrorReply`, ADR 0054 §3). */
+    #instanceError(status, code, requestOutcome, error, retry) {
+        const body = { success: false, code, requestOutcome, state: this.#instance.state(), error };
+        return jsonResponse(status, body, { ...(retry ? { 'retry-after': this.#retryAfter } : {}), 'cache-control': 'no-store' });
+    }
+    async #forward(request, context) {
+        const transport = this.#readyTransport();
+        if (!transport)
+            return this.#unavailable();
+        const declared = request.headers.get('content-length');
+        if (declared !== null && Number(declared) > this.#maxBody)
+            return tooLarge();
+        const headers = new Headers(request.headers);
+        for (const name of HOP_BY_HOP_HEADERS)
+            headers.delete(name);
+        const body = request.body ? limitBody(request.body, this.#maxBody) : null;
+        const forwarded = new Request(context.url, {
+            method: request.method,
+            headers,
+            signal: request.signal,
+            ...(body ? { body, duplex: 'half' } : {}),
+        });
+        let response;
+        try {
+            response = await transport.fetch(forwarded, {
+                ...(context.principal ? { principal: context.principal } : {}),
+                ...(context.remoteAddress ? { remoteAddress: context.remoteAddress } : {}),
+            });
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                return new Response(null, { status: 499 });
+            if (error instanceof BodyLimitError || (error instanceof Error && error.cause instanceof BodyLimitError))
+                return tooLarge();
+            return this.#transportFailure(error, transport, context.url.pathname);
+        }
+        return stripHopByHop(response);
+    }
+    /** Maps a failed forward onto the documented gateway error responses (ADR 0054 §3). */
+    #transportFailure(error, transport, path) {
+        const code = error instanceof InstanceTransportError ? error.code : undefined;
+        // A transport that is no longer ready failed because the instance went away.
+        if (code === 'instance-offline' || (code === undefined && !transport.ready))
+            return this.#unavailable();
+        if (code === 'timeout') {
+            return this.#instanceError(504, 'instance_timeout', 'unknown', 'The instance did not answer in time', false);
+        }
+        if (code === 'overloaded') {
+            return this.#instanceError(502, 'instance_error', 'not-dispatched', 'The instance is overloaded', true);
+        }
+        logger.warn(formatCompact({
+            op: 'gateway_forward_failed',
+            path,
+            ...(code ? { code } : {}),
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        return this.#instanceError(502, 'instance_error', 'unknown', 'The instance failed to answer', false);
+    }
+    /**
+     * `POST {base}/console/request`: the router authenticated and authorized the route; `gateway.*`
+     * types are dispatched here (the dispatcher checks the per-RPC permission), the rest are
+     * forwarded to the instance with the body as received.
+     */
+    async #consoleRequest(request, context) {
+        const declared = request.headers.get('content-length');
+        if (declared !== null && Number(declared) > this.#maxBody)
+            return tooLarge();
+        let bytes;
+        try {
+            bytes = request.body
+                ? await new Response(limitBody(request.body, this.#maxBody)).arrayBuffer()
+                : new ArrayBuffer(0);
+        }
+        catch (error) {
+            if (request.signal.aborted)
+                return new Response(null, { status: 499 });
+            if (error instanceof BodyLimitError)
+                return tooLarge();
+            return jsonResponse(400, { success: false, code: 'invalid_body', error: 'Invalid request body' });
+        }
+        const type = peekRpcType(bytes);
+        const owner = type === undefined
+            ? undefined
+            : type.startsWith(GATEWAY_RPC_PREFIX) && this.#consoleRpc
+                ? this.#consoleRpc
+                : [...this.#rpcHandlers].find((handler) => handler.owns(type));
+        if (owner) {
+            let message;
+            try {
+                message = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                return jsonResponse(400, { success: false, code: 'invalid_body', error: 'Invalid JSON body' });
+            }
+            const claimed = typeof message === 'object' && message !== null && !Array.isArray(message)
+                && (!('claims' in owner) || typeof owner.claims !== 'function' || owner.claims(message));
+            if (claimed) {
+                try {
+                    return await owner.handle(message, context, this.tokenRegistry);
+                }
+                catch (error) {
+                    if (isDatabaseBusyError(error))
+                        return databaseBusyResponse({ requestId: message.requestId });
+                    throw error;
+                }
+            }
+        }
+        const headers = new Headers(request.headers);
+        for (const name of HOP_BY_HOP_HEADERS)
+            headers.delete(name);
+        headers.delete('content-length');
+        return this.#forward(new Request(context.url, {
+            method: request.method,
+            headers,
+            signal: request.signal,
+            body: bytes,
+        }), context);
+    }
+    /**
+     * A `{base}/…` request from the local control socket (`gateway.http.request`, ADR 0054 §6).
+     * Without `token` the socket's owner check is the authentication: the request runs as
+     * {@link LOCAL_OWNER_PRINCIPAL}. With `token` (an explicit `ZHIN_CONSOLE_TOKEN`) it is
+     * authenticated like an HTTP request with that Bearer credential and runs — and is audited — as
+     * its principal. Either way the request takes the HTTP route table: gateway-owned routes (e.g.
+     * `{base}/auth/me`), the `POST {base}/console/request` split, then the instance. Event streams
+     * cannot be carried in one socket reply; the socket handler refuses them. Only the path and query
+     * of `path` are used; paths outside `{base}` are refused.
+     */
+    async localRequest(input) {
+        const method = input.method.toUpperCase();
+        // `\` is a path separator to the URL parser: `/\evil.com/x` would name another host.
+        if (!input.path.startsWith('/') || input.path.startsWith('//') || input.path.includes('\\')) {
+            return jsonResponse(400, { success: false, code: 'invalid_input', error: 'path must be an absolute path without a host' });
+        }
+        if (input.body !== undefined && (method === 'GET' || method === 'HEAD')) {
+            return jsonResponse(400, { success: false, code: 'invalid_input', error: `${method} requests cannot have a body` });
+        }
+        const parsed = new URL(input.path, LOCAL_REQUEST_ORIGIN);
+        const url = new URL(`${parsed.pathname}${parsed.search}`, LOCAL_REQUEST_ORIGIN);
+        const pathname = normalizePath(url.pathname);
+        if (!isUnderBase(pathname, this.apiBase)) {
+            return jsonResponse(404, { success: false, code: 'not_found', error: `Only ${this.apiBase === '/' ? '/' : `${this.apiBase}/`}… is reachable over the local socket` });
+        }
+        const headers = new Headers();
+        if (input.body !== undefined)
+            headers.set('content-type', 'application/json');
+        if (input.token !== undefined)
+            headers.set('authorization', `Bearer ${input.token}`);
+        const request = new Request(url, { method, headers, ...(input.body === undefined ? {} : { body: input.body }) });
+        return input.token !== undefined
+            ? this.#router.handle(request)
+            : this.#localRouter.handle(request, { principal: LOCAL_OWNER_PRINCIPAL });
+    }
+    async #upgrade(request) {
+        const own = await this.#router.upgrade(request);
+        if (own.accepted || own.status !== 404 || this.#closed)
+            return own;
+        const transport = this.#readyTransport();
+        if (!transport)
+            return Object.freeze({ accepted: false, status: 503, headers: { 'Retry-After': this.#retryAfter } });
+        const pathname = normalizePath(request.url.pathname);
+        const routes = transport.routes().ws.filter((route) => normalizePath(route.path) === pathname);
+        if (routes.length === 0)
+            return Object.freeze({ accepted: false, status: 404 });
+        let principal;
+        if (!routes.every((route) => route.auth === 'protocol')) {
+            principal = await this.#authenticateUpgrade(request, pathname).catch(() => undefined);
+            if (!principal)
+                return Object.freeze({ accepted: false, status: 401 });
+        }
+        const info = Object.freeze({
+            url: request.url,
+            headers: request.headers,
+            ...(principal ? { principal } : {}),
+            ...(request.remoteAddress ? { remoteAddress: request.remoteAddress } : {}),
+        });
+        return Object.freeze({
+            accepted: true,
+            reject: () => undefined,
+            accept: (socket) => {
+                const peer = bufferedConnection(info, socket);
+                transport.openWebSocket(info, peer).then((opened) => {
+                    if (!opened)
+                        peer.close(1013, 'Instance unavailable');
+                }, (error) => {
+                    logger.warn(formatCompact({
+                        op: 'gateway_ws_forward_failed',
+                        path: pathname,
+                        error: error instanceof Error ? error.message : String(error),
+                    }));
+                    peer.close(1011, 'Instance unavailable');
+                });
+            },
+        });
+    }
+    async #authenticateUpgrade(request, pathname) {
+        const token = extractBearerToken(request.headers.get('authorization') ?? undefined, request.url.searchParams.get('token'));
+        const principal = await this.tokenRegistry.authenticate(token, requestMeta(request, request.remoteAddress));
+        if (!principal)
+            return undefined;
+        if (!authorizeConsoleWebSocket(principal, pathname)) {
+            const provider = this.tokenRegistry.accessProvider;
+            try {
+                provider?.audit?.({
+                    actor: auditActor(principal),
+                    action: `ws:${pathname}`,
+                    outcome: 'denied',
+                    ...(request.remoteAddress ? { ip: request.remoteAddress } : {}),
+                });
+            }
+            catch { /* audit never breaks a request */ }
+            return undefined;
+        }
+        return principal;
+    }
+}
+/** A gateway route whose database stayed locked past the retry budget answers 503 `database_busy`. */
+/** Origin of the URLs `localRequest` builds (never contacted). */
+const LOCAL_REQUEST_ORIGIN = 'http://gateway.local';
+/** `pathname` is `base` or below it (`base` may be `/`). */
+function isUnderBase(pathname, base) {
+    if (base === '/')
+        return pathname.startsWith('/');
+    return pathname === base || pathname.startsWith(`${base}/`);
+}
+function withDatabaseBusy(handler) {
+    return async (request, context) => {
+        try {
+            return await handler(request, context);
+        }
+        catch (error) {
+            if (isDatabaseBusyError(error))
+                return databaseBusyResponse();
+            throw error;
+        }
+    };
+}
+class BodyLimitError extends Error {
+}
+function tooLarge() {
+    return jsonResponse(413, { success: false, code: 'payload_too_large', requestOutcome: 'not-dispatched', error: 'Request body too large' });
+}
+function limitBody(body, max) {
+    let total = 0;
+    return body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            total += chunk.byteLength;
+            if (total > max)
+                controller.error(new BodyLimitError('Request body too large'));
+            else
+                controller.enqueue(chunk);
+        },
+    }));
+}
+function stripHopByHop(response) {
+    if (!HOP_BY_HOP_HEADERS.some((name) => response.headers.has(name)))
+        return response;
+    const headers = new Headers(response.headers);
+    for (const name of HOP_BY_HOP_HEADERS)
+        headers.delete(name);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+/**
+ * A {@link WsConnection} over the client socket that keeps client frames until the instance side
+ * subscribes (opening it is asynchronous); too many early frames close the socket (1009).
+ */
+function bufferedConnection(info, socket) {
+    const listeners = new Set();
+    let pending = [];
+    let pendingBytes = 0;
+    socket.onMessage((data) => {
+        if (pending) {
+            pending.push(data);
+            pendingBytes += typeof data === 'string' ? data.length : data.byteLength;
+            if (pending.length > WS_PENDING_FRAME_LIMIT || pendingBytes > WS_PENDING_BYTE_LIMIT) {
+                pending = [];
+                socket.close(1009, 'Too many frames before the instance accepted the socket');
+            }
+            return;
+        }
+        for (const listener of [...listeners]) {
+            try {
+                listener(data);
+            }
+            catch { /* isolate listener failures */ }
+        }
+    });
+    socket.onClose(() => {
+        pending = undefined;
+        listeners.clear();
+    });
+    return Object.freeze({
+        url: info.url,
+        headers: info.headers,
+        ...(info.principal ? { principal: info.principal } : {}),
+        ...(info.remoteAddress ? { remoteAddress: info.remoteAddress } : {}),
+        send: (data) => socket.send(data),
+        close: (code, reason) => socket.close(code, reason),
+        onMessage(listener) {
+            listeners.add(listener);
+            if (pending) {
+                const queued = pending;
+                pending = undefined;
+                queueMicrotask(() => {
+                    for (const data of queued) {
+                        for (const current of [...listeners]) {
+                            try {
+                                current(data);
+                            }
+                            catch { /* isolate listener failures */ }
+                        }
+                    }
+                });
+            }
+            return () => { listeners.delete(listener); };
+        },
+        onClose: (listener) => socket.onClose(listener),
+        get bufferedAmount() { return socket.bufferedAmount; },
+    });
+}
+/** Reads `type` from a JSON RPC envelope without failing on malformed input. */
+function peekRpcType(bytes) {
+    if (bytes.byteLength === 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(bytes));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const type = parsed.type;
+        return typeof type === 'string' ? type : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/http/local-principal.d.ts

@@ -0,0 +1,2 @@
+import type { ConsoleUserPrincipal } from '@zhin.js/host-http';
+export declare const LOCAL_OWNER_PRINCIPAL: ConsoleUserPrincipal;

package/lib/http/local-principal.js

@@ -0,0 +1,16 @@
+/**
+ * The principal of requests from the local control socket (`gateway.http.request`, ADR 0054 §6).
+ * Connecting to `.zhin/gateway.sock` requires the project owner's OS account (the socket's owner
+ * check), which the gateway treats as the Console owner. The instance sees a global owner; audit
+ * entries name it `user:local`.
+ */
+import { CONSOLE_PERMISSION_LIST } from '@zhin.js/console-protocol';
+export const LOCAL_OWNER_PRINCIPAL = Object.freeze({
+    kind: 'user',
+    userId: 'local',
+    username: 'local',
+    displayName: '本机 CLI（网关控制套接字）',
+    credentialId: 'local-socket',
+    grants: Object.freeze([Object.freeze({ role: 'owner', scope: Object.freeze({ kind: 'global' }), permissions: CONSOLE_PERMISSION_LIST })]),
+    roles: Object.freeze(['owner']),
+});

package/lib/http/plugin-switch-rpc.d.ts

@@ -0,0 +1,19 @@
+import type { GatewayPackageService } from '../packages/service.js';
+import type { GatewayRpcHandler } from './console-rpc.js';
+/** What the switch needs from the package service. */
+export type GatewayPluginSwitchPackages = Pick<GatewayPackageService, 'setEnabled'>;
+/** The root configuration as written after the transaction. */
+export interface GatewayPluginSwitchConfigRead {
+    readonly revision: string;
+    readonly document: Readonly<Record<string, unknown>>;
+}
+export interface GatewayPluginSwitchRpcOptions {
+    readonly projectRoot: string;
+    /** Undefined when the gateway manages no packages: the switch then answers 503 (never forwarded). */
+    readonly packages: GatewayPluginSwitchPackages | undefined;
+    /** Reads the root configuration (revision and document). Defaults to the project's config file. */
+    readonly readConfig?: () => Promise<GatewayPluginSwitchConfigRead>;
+}
+/** Whether the gateway answers this Console RPC message itself (the global plugin switch). */
+export declare function isGatewayPluginSwitch(message: Readonly<Record<string, unknown>>): boolean;
+export declare function createGatewayPluginSwitchRpc(options: GatewayPluginSwitchRpcOptions): GatewayRpcHandler;