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

package/lib/local/client.js

@@ -0,0 +1,296 @@
+/** CLI side of the local control socket (ADR 0054 §6). */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { connect } from 'node:net';
+import { gatewaySocketPath, isNamedPipe } from './paths.js';
+import { handshakeProof, LineDecoder, LOCAL_GATEWAY_RPC, MAX_LOCAL_HTTP_BODY_BYTES, MAX_LOCAL_LINE_BYTES, } from './protocol.js';
+import { readGatewayInfo } from './state-file.js';
+export class LocalGatewayClientError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'LocalGatewayClientError';
+    }
+}
+/** The gateway answered `{ ok: false }`. */
+export class LocalGatewayRpcError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status, details = {}) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'LocalGatewayRpcError';
+    }
+}
+const defaultUid = () => (typeof process.getuid === 'function' ? process.getuid() : undefined);
+export class LocalGatewayClient {
+    path;
+    #socket;
+    #pending = new Map();
+    #nextId = 1;
+    #closedError;
+    constructor(path, socket) {
+        this.path = path;
+        this.#socket = socket;
+        const decoder = new LineDecoder();
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            let lines;
+            try {
+                lines = decoder.push(chunk);
+            }
+            catch (error) {
+                this.#fail(new LocalGatewayClientError('protocol', '网关返回的数据过长', { cause: error }));
+                return;
+            }
+            for (const line of lines)
+                this.#receive(line);
+        });
+        socket.on('error', (error) => { this.#fail(new LocalGatewayClientError('unreachable', `与网关的连接出错：${error.message}`, { cause: error })); });
+        socket.on('close', () => { this.#fail(new LocalGatewayClientError('unreachable', '网关关闭了连接')); });
+    }
+    /** Connects to the project's gateway; see {@link LocalGatewayClientErrorCode} for failures. */
+    static async connect(options) {
+        const recorded = await readGatewayInfo(options.root);
+        const path = options.path ?? recorded?.socket ?? gatewaySocketPath(options.root);
+        const handshakeKey = options.handshakeKey ?? (recorded?.socket === path ? recorded.handshakeKey : undefined);
+        if (!isNamedPipe(path)) {
+            let info;
+            try {
+                info = await lstat(path);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    throw new LocalGatewayClientError('not_running', '网关未运行');
+                throw new LocalGatewayClientError('unreachable', `无法读取 ${path}：${error.message}`, { cause: error });
+            }
+            if (!info.isSocket())
+                throw new LocalGatewayClientError('protocol', `${path} 不是网关控制套接字`);
+            const uid = (options.uid ?? defaultUid)();
+            if (uid !== undefined && info.uid !== uid) {
+                throw new LocalGatewayClientError('not_owner', `${path} 属于其他用户（uid ${info.uid}），当前用户 uid ${uid}；请以启动网关的用户运行 zhin`);
+            }
+        }
+        const socket = await new Promise((resolve, reject) => {
+            const candidate = connect(path);
+            const timer = setTimeout(() => {
+                candidate.destroy();
+                reject(new LocalGatewayClientError('unreachable', `连接网关超时（${path}）`));
+            }, options.connectTimeoutMs ?? 5_000);
+            candidate.once('connect', () => { clearTimeout(timer); resolve(candidate); });
+            candidate.once('error', (error) => {
+                clearTimeout(timer);
+                if (error.code === 'ECONNREFUSED' || error.code === 'ENOENT')
+                    reject(new LocalGatewayClientError('not_running', '网关未运行（套接字已失效）', { cause: error }));
+                else if (error.code === 'EACCES' || error.code === 'EPERM')
+                    reject(new LocalGatewayClientError('not_owner', `无权访问 ${path}；请以启动网关的用户运行 zhin`, { cause: error }));
+                else
+                    reject(new LocalGatewayClientError('unreachable', `无法连接网关：${error.message}`, { cause: error }));
+            });
+        });
+        const client = new LocalGatewayClient(path, socket);
+        if (handshakeKey) {
+            try {
+                await client.#verify(handshakeKey);
+            }
+            catch (error) {
+                client.close();
+                throw error;
+            }
+        }
+        return client;
+    }
+    /**
+     * Proves the peer holds this run's handshake key. Node cannot restrict who creates a Windows
+     * named pipe, so a pipe another account created first must not receive our requests.
+     */
+    async #verify(key) {
+        const nonce = randomBytes(16).toString('hex');
+        let reply;
+        try {
+            reply = await this.request(LOCAL_GATEWAY_RPC.HELLO, { nonce }, { timeoutMs: 5_000 });
+        }
+        catch (error) {
+            throw new LocalGatewayClientError('not_owner', `${this.path} 未通过网关握手校验；它可能不是本项目的网关`, { cause: error });
+        }
+        const expected = Buffer.from(handshakeProof(key, nonce), 'hex');
+        const actual = typeof reply?.proof === 'string' && /^[0-9a-f]+$/u.test(reply.proof) ? Buffer.from(reply.proof, 'hex') : Buffer.alloc(0);
+        if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+            throw new LocalGatewayClientError('not_owner', `${this.path} 未通过网关握手校验；它可能不是本项目的网关`);
+        }
+    }
+    request(type, data, options = {}) {
+        if (this.#closedError)
+            return Promise.reject(this.#closedError);
+        const id = this.#nextId++;
+        const line = `${JSON.stringify({ id, type, ...(data === undefined ? {} : { data }) })}\n`;
+        if (Buffer.byteLength(line) > MAX_LOCAL_LINE_BYTES) {
+            return Promise.reject(new LocalGatewayClientError('protocol', `请求超过本地套接字上限（1 MiB）：${type}`));
+        }
+        return new Promise((resolve, reject) => {
+            const pending = { resolve: resolve, reject, ...(options.onEvent ? { onEvent: options.onEvent } : {}) };
+            if (options.timeoutMs !== undefined) {
+                pending.timer = setTimeout(() => {
+                    this.#pending.delete(id);
+                    reject(new LocalGatewayClientError('unreachable', `网关在 ${options.timeoutMs} ms 内没有响应 ${type}`));
+                }, options.timeoutMs);
+            }
+            this.#pending.set(id, pending);
+            this.#socket.write(line);
+        });
+    }
+    info(timeoutMs = 10_000) {
+        return this.request(LOCAL_GATEWAY_RPC.INFO, undefined, { timeoutMs });
+    }
+    close() {
+        this.#closedError ??= new LocalGatewayClientError('unreachable', '连接已关闭');
+        this.#socket.destroy();
+    }
+    #receive(text) {
+        let line;
+        try {
+            line = JSON.parse(text);
+        }
+        catch {
+            this.#fail(new LocalGatewayClientError('protocol', '网关返回了无效的 JSON'));
+            return;
+        }
+        const pending = typeof line?.id === 'number' ? this.#pending.get(line.id) : undefined;
+        if (!pending)
+            return;
+        if ('event' in line) {
+            try {
+                pending.onEvent?.(line.event);
+            }
+            catch { /* a faulty listener must not break the stream */ }
+            return;
+        }
+        this.#pending.delete(line.id);
+        clearTimeout(pending.timer);
+        if (line.ok)
+            pending.resolve(line.data);
+        else {
+            const { errors, missingEnv } = line.error;
+            pending.reject(new LocalGatewayRpcError(line.error.code, line.error.message, line.error.status, {
+                ...(Array.isArray(errors) && errors.length ? { errors } : {}),
+                ...(Array.isArray(missingEnv) && missingEnv.length ? { missingEnv } : {}),
+            }));
+        }
+    }
+    #fail(error) {
+        this.#closedError ??= error;
+        for (const [id, pending] of this.#pending) {
+            this.#pending.delete(id);
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.#socket.destroy();
+    }
+}
+/**
+ * The running gateway's info, or `undefined` when no gateway runs for `root`. Ownership and
+ * reachability problems are thrown (a caller must not fall back to working on the files then).
+ */
+export async function probeLocalGateway(options) {
+    let client;
+    try {
+        client = await LocalGatewayClient.connect(options);
+    }
+    catch (error) {
+        if (error instanceof LocalGatewayClientError && error.code === 'not_running')
+            return undefined;
+        throw error;
+    }
+    try {
+        return await client.info();
+    }
+    finally {
+        client.close();
+    }
+}
+/** The Bearer credential of `Authorization` in `headers` (a `Headers`, record or entry list). */
+export function bearerFromHeaders(headers) {
+    let value;
+    if (headers instanceof Headers)
+        value = headers.get('authorization');
+    else if (Array.isArray(headers)) {
+        value = headers.find((entry) => Array.isArray(entry) && String(entry[0]).toLowerCase() === 'authorization')?.[1];
+    }
+    else if (headers && typeof headers === 'object') {
+        value = Object.entries(headers).find(([name]) => name.toLowerCase() === 'authorization')?.[1];
+    }
+    if (typeof value !== 'string')
+        return undefined;
+    const match = /^Bearer\s+(\S+)\s*$/iu.exec(value.trim());
+    return match?.[1];
+}
+/** A JSON reply in the shape `requestPluginConsole` / `hostFetch` read. */
+function localError(status, code, error) {
+    return new Response(JSON.stringify({ success: false, code, error }), { status, headers: { 'content-type': 'application/json' } });
+}
+/**
+ * A `fetch` that sends `{base}/…` requests over the local control socket
+ * (`gateway.http.request`) instead of HTTP (ADR 0054 §6). Only the path and query of the URL are
+ * used. Without an `Authorization: Bearer` header the gateway runs the request as the local
+ * owner, so no Console token is needed; with one (an explicit `ZHIN_CONSOLE_TOKEN`), the gateway
+ * authenticates that credential and runs — and audits — the request as its principal. A gateway
+ * that is not running rejects like a refused connection (`cause.code === 'ECONNREFUSED'`).
+ */
+export function createLocalGatewayFetch(options) {
+    return async (input, init = {}) => {
+        const url = typeof input === 'string' ? new URL(input) : input;
+        const method = (init.method ?? 'GET').toUpperCase();
+        const body = typeof init.body === 'string' ? init.body : undefined;
+        const token = bearerFromHeaders(init.headers);
+        const signal = init.signal ?? undefined;
+        signal?.throwIfAborted();
+        if (body !== undefined && (method === 'GET' || method === 'HEAD')) {
+            return localError(400, 'invalid_input', 'GET 请求不能带 body');
+        }
+        if (body !== undefined && Buffer.byteLength(JSON.stringify(body)) > MAX_LOCAL_HTTP_BODY_BYTES) {
+            return localError(413, 'invalid_input', '请求体超过本地套接字上限；改用 HTTP 请求（Console API 令牌 ZHIN_CONSOLE_TOKEN，--host 指向网关地址）');
+        }
+        let client;
+        try {
+            client = await LocalGatewayClient.connect(options);
+        }
+        catch (error) {
+            if (error instanceof LocalGatewayClientError && error.code === 'not_running') {
+                throw new TypeError('fetch failed', { cause: Object.assign(new Error(error.message), { code: 'ECONNREFUSED' }) });
+            }
+            throw error;
+        }
+        const aborted = new Promise((_, reject) => {
+            if (!signal)
+                return;
+            signal.addEventListener('abort', () => { client.close(); reject(signal.reason); }, { once: true });
+        });
+        aborted.catch(() => undefined);
+        try {
+            const reply = await Promise.race([
+                client.request(LOCAL_GATEWAY_RPC.HTTP_REQUEST, {
+                    method,
+                    path: `${url.pathname}${url.search}`,
+                    ...(body === undefined ? {} : { body }),
+                    ...(token === undefined ? {} : { token }),
+                }),
+                aborted,
+            ]);
+            return new Response(reply.body === '' ? null : reply.body, { status: reply.status, headers: reply.headers });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason;
+            if (error instanceof LocalGatewayRpcError)
+                return localError(error.status, error.code, error.message);
+            throw error;
+        }
+        finally {
+            client.close();
+        }
+    };
+}

package/lib/local/handler.d.ts

@@ -0,0 +1,30 @@
+import type { GatewayRpcDispatcher } from '../packages/rpc.js';
+import type { GatewayPackageService } from '../packages/service.js';
+import type { LocalRequestHandler, LocalRequestResult } from './local-socket.js';
+import { type LocalGatewayInfoResult } from './protocol.js';
+export interface LocalRpcHandlerOptions {
+    readonly dispatch: GatewayRpcDispatcher;
+    /** Progress of package transactions is streamed to the requesting connection. */
+    readonly packages?: GatewayPackageService;
+    readonly info: () => LocalGatewayInfoResult;
+    /** Called after the `gateway.shutdown` answer was queued. */
+    readonly shutdown: () => void;
+    /** Socket-only `gateway.console.*` (Console setup and user rescue); absent without Console. */
+    readonly console?: {
+        owns(type: string): boolean;
+        handle(type: string, data: unknown): Promise<LocalRequestResult>;
+    };
+    /**
+     * `gateway.http.request`: a `{base}/…` request as the local owner, or — with `token` — as the
+     * principal that credential authenticates to; absent → `unavailable`.
+     */
+    readonly http?: (request: {
+        readonly method: string;
+        readonly path: string;
+        readonly body?: string;
+        readonly token?: string;
+    }) => Promise<Response>;
+}
+/** UTF-8 bytes `value` takes inside a JSON line (escapes included). */
+export declare function jsonEncodedBytes(value: string): number;
+export declare function createLocalRpcHandler(options: LocalRpcHandlerOptions): LocalRequestHandler;

package/lib/local/handler.js

@@ -0,0 +1,86 @@
+/** Maps local socket requests onto the gateway RPC with principal `'local'` (ADR 0054 §6). */
+import { GATEWAY_RPC } from '@zhin.js/console-protocol';
+import { LOCAL_GATEWAY_RPC, MAX_LOCAL_HTTP_BODY_BYTES } from './protocol.js';
+const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+const MAX_TOKEN_CHARS = 4096;
+const USE_HTTP = '改用 HTTP 请求（Console API 令牌 ZHIN_CONSOLE_TOKEN，--host 指向网关地址）';
+/** UTF-8 bytes `value` takes inside a JSON line (escapes included). */
+export function jsonEncodedBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value));
+}
+async function handleHttp(options, data) {
+    const invalid = (message) => ({ ok: false, error: { code: 'invalid_input', message, status: 400 } });
+    if (!options.http)
+        return { ok: false, error: { code: 'unavailable', message: '网关未提供 HTTP 转发', status: 503 } };
+    const input = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+    const { method, path, body, token } = input;
+    if (typeof method !== 'string' || !HTTP_METHODS.has(method))
+        return invalid('method 必须是 GET / POST / PUT / PATCH / DELETE');
+    // `\` is a path separator to the WHATWG URL parser (`/\evil.com/x` names a host).
+    if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || path.includes('\\') || path.length > 4096) {
+        return invalid('path 必须是以 / 开头、不含 \\ 的路径');
+    }
+    if (body !== undefined && typeof body !== 'string')
+        return invalid('body 必须是字符串');
+    if (body !== undefined && method === 'GET')
+        return invalid('GET 请求不能带 body');
+    if (typeof body === 'string' && jsonEncodedBytes(body) > MAX_LOCAL_HTTP_BODY_BYTES) {
+        return { ok: false, error: { code: 'invalid_input', message: `请求体超过本地套接字上限；${USE_HTTP}`, status: 413 } };
+    }
+    if (token !== undefined && (typeof token !== 'string' || token.length === 0 || token.length > MAX_TOKEN_CHARS))
+        return invalid('token 必须是非空字符串');
+    const response = await options.http({
+        method,
+        path,
+        ...(body === undefined ? {} : { body }),
+        ...(token === undefined ? {} : { token }),
+    });
+    // A stream (SSE) never ends: one JSON line cannot carry it.
+    if (response.headers.get('content-type')?.toLowerCase().startsWith('text/event-stream')) {
+        await response.body?.cancel().catch(() => undefined);
+        return { ok: false, error: { code: 'unavailable', message: `事件流不能经本地套接字转发；${USE_HTTP}`, status: 502 } };
+    }
+    const text = await response.text();
+    if (jsonEncodedBytes(text) > MAX_LOCAL_HTTP_BODY_BYTES) {
+        return { ok: false, error: { code: 'unavailable', message: `响应超过本地套接字上限；${USE_HTTP}`, status: 502 } };
+    }
+    const headers = {};
+    for (const name of ['content-type', 'retry-after']) {
+        const value = response.headers.get(name);
+        if (value !== null)
+            headers[name] = value;
+    }
+    const result = { status: response.status, headers, body: text };
+    return { ok: true, data: result };
+}
+const STREAMED = new Set([GATEWAY_RPC.INSTALL, GATEWAY_RPC.UNINSTALL, GATEWAY_RPC.UPDATE, GATEWAY_RPC.DECLARE]);
+export function createLocalRpcHandler(options) {
+    return async (request, emit) => {
+        if (request.type === LOCAL_GATEWAY_RPC.INFO)
+            return { ok: true, data: options.info() };
+        if (request.type === LOCAL_GATEWAY_RPC.SHUTDOWN) {
+            setImmediate(options.shutdown);
+            return { ok: true, data: { stopping: true } };
+        }
+        if (options.console?.owns(request.type))
+            return options.console.handle(request.type, request.data);
+        if (request.type === LOCAL_GATEWAY_RPC.HTTP_REQUEST)
+            return handleHttp(options, request.data);
+        // One transaction at a time: the first `start` seen after subscribing is this request's.
+        let transaction;
+        const unsubscribe = STREAMED.has(request.type)
+            ? options.packages?.subscribe((event) => {
+                if (transaction === undefined && event.type === 'start')
+                    transaction = event.id;
+                if (event.id === transaction)
+                    emit(event);
+            })
+            : undefined;
+        try {
+            return await options.dispatch({ type: request.type, data: request.data }, 'local');
+        }
+        finally {
+            unsubscribe?.();
+        }
+    };
+}

package/lib/local/local-socket.d.ts

@@ -0,0 +1,55 @@
+import type { GatewayPackageEvent } from '@zhin.js/console-protocol';
+import { type LocalGatewayError, type LocalGatewayRequest } from './protocol.js';
+export type LocalSocketErrorCode = 'in_use' | 'not_owner' | 'insecure_dir' | 'not_socket' | 'insecure_socket';
+export declare class LocalSocketError extends Error {
+    readonly code: LocalSocketErrorCode;
+    constructor(code: LocalSocketErrorCode, message: string, options?: ErrorOptions);
+}
+export interface LocalSocketSecurityOptions {
+    /** Current user id; `undefined` skips owner checks (Windows). Default `process.getuid()`. */
+    readonly uid?: () => number | undefined;
+    /** Connect probe timeout for an existing socket. Default 1 s. */
+    readonly probeTimeoutMs?: number;
+}
+export type LocalRequestResult = Readonly<{
+    ok: true;
+    data: unknown;
+}> | Readonly<{
+    ok: false;
+    error: LocalGatewayError;
+}>;
+/** Answers one request; `emit` streams events for it before the answer. */
+export type LocalRequestHandler = (request: LocalGatewayRequest, emit: (event: GatewayPackageEvent) => void) => Promise<LocalRequestResult>;
+export interface LocalControlServerOptions extends LocalSocketSecurityOptions {
+    readonly path: string;
+    /** Requests before {@link LocalControlServer.setHandler} get `unavailable`. */
+    readonly handler?: LocalRequestHandler;
+    readonly maxConnections?: number;
+    /** Key of the {@link LOCAL_GATEWAY_RPC.HELLO} handshake; without it `gateway.hello` proves nothing. */
+    readonly handshakeKey?: string;
+    /**
+     * Runs once the path is known to be free (no live gateway) and before the bind: the gateway
+     * drops a stale `.zhin/gateway.json`, so no client checks this run against an old handshake key.
+     */
+    readonly beforeListen?: () => Promise<void>;
+}
+/** Probes an existing endpoint: `live` when something accepts a connection. */
+export declare function probeLocalSocket(path: string, timeoutMs?: number): Promise<'live' | 'dead'>;
+/**
+ * Checks the socket's directory and any existing socket, removing a stale one. Throws
+ * {@link LocalSocketError} when another live gateway owns the path or ownership is wrong.
+ */
+export declare function prepareLocalSocketPath(path: string, options?: LocalSocketSecurityOptions): Promise<{
+    readonly removedStale: boolean;
+}>;
+/** The listening control server. */
+export declare class LocalControlServer {
+    #private;
+    readonly path: string;
+    private constructor();
+    /** Validates the path, removes a stale socket, then listens with mode 0600. */
+    static open(options: LocalControlServerOptions): Promise<LocalControlServer>;
+    setHandler(handler: LocalRequestHandler): void;
+    /** Stops accepting, drops connections and removes the socket file it created. */
+    close(): Promise<void>;
+}