@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/database/config.js

@@ -0,0 +1,159 @@
+/**
+ * The project `database` block as the gateway resolves it (ADR 0054 §7): the same file and
+ * driver settings as the instance's `resolveDatabaseConfig` (`@zhin.js/core`), ported here so the
+ * gateway never imports IM layers. Keep the two in step.
+ */
+import { mkdir } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { expandEnvironmentValue } from '@zhin.js/plugin-runtime';
+import { createConfigDocument } from '@zhin.js/runtime';
+import { findConfigFile } from '../project/config-file.js';
+import { loadRuntimeEnvironmentLayers } from '../project/environment.js';
+/** Project-relative default when no `database` block is configured. */
+export const DEFAULT_PROJECT_DATABASE_FILE = join('.zhin', 'data.sqlite');
+const SUPPORTED_DIALECTS = new Set(['memory', 'mongodb', 'mysql', 'pg', 'redis', 'sqlite']);
+function configurationError(path, expectation, envExample) {
+    const envHint = envExample
+        ? `若这里引用环境变量，请在项目根目录 .env 中设置 ${envExample}。`
+        : '若这里引用环境变量，请检查项目根目录 .env 中的对应变量。';
+    return new TypeError(`数据库配置 ${path} ${expectation}。${envHint}也可运行 \`zhin setup --database\` 重新配置。`);
+}
+function normalizePort(value, path, envExample) {
+    if (value === undefined)
+        return undefined;
+    const normalized = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && /^\d+$/u.test(value.trim()) ? Number(value.trim()) : Number.NaN;
+    if (!Number.isInteger(normalized) || normalized < 1 || normalized > 65535) {
+        throw configurationError(path, '必须是 1-65535 的整数，当前值为空或无效', envExample);
+    }
+    return normalized;
+}
+function normalizeOptionalText(config, key, path, envExample) {
+    if (!(key in config))
+        return;
+    const value = config[key];
+    if (typeof value !== 'string' || value.trim() === '')
+        throw configurationError(path, '不能为空', envExample);
+    config[key] = value.trim();
+}
+function normalizeRequiredText(config, key, path, envExample) {
+    if (!(key in config))
+        config[key] = undefined;
+    normalizeOptionalText(config, key, path, envExample);
+}
+function normalizeRedisDatabase(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = typeof value === 'number'
+        ? value
+        : typeof value === 'string' && /^\d+$/u.test(value.trim()) ? Number(value.trim()) : Number.NaN;
+    if (!Number.isInteger(normalized) || normalized < 0) {
+        throw configurationError('database.database', '必须是大于或等于 0 的整数', 'REDIS_DB=0');
+    }
+    return normalized;
+}
+/** Validates an expanded `database` block (port of `normalizeDatabaseHostConfig`). */
+export function normalizeProjectDatabaseConfig(input) {
+    const dialect = input.dialect;
+    if (!SUPPORTED_DIALECTS.has(dialect)) {
+        throw new TypeError(`数据库配置 database.dialect 不支持 ${JSON.stringify(dialect)}；可选值为 sqlite、mysql、pg、mongodb、redis、memory。`);
+    }
+    const config = { ...input, dialect };
+    switch (dialect) {
+        case 'mysql':
+            normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
+            normalizeOptionalText(config, 'user', 'database.user', 'DB_USER=root');
+            normalizeOptionalText(config, 'database', 'database.database', 'DB_DATABASE=zhin_bot');
+            normalizeOptionalText(config, 'uri', 'database.uri');
+            config.port = normalizePort(config.port, 'database.port', 'DB_PORT=3306');
+            if (config.port === undefined)
+                delete config.port;
+            break;
+        case 'pg':
+            normalizeOptionalText(config, 'host', 'database.host', 'DB_HOST=127.0.0.1');
+            normalizeOptionalText(config, 'user', 'database.user', 'DB_USER=postgres');
+            normalizeOptionalText(config, 'database', 'database.database', 'DB_DATABASE=zhin_bot');
+            normalizeOptionalText(config, 'connectionString', 'database.connectionString');
+            config.port = normalizePort(config.port, 'database.port', 'DB_PORT=5432');
+            if (config.port === undefined)
+                delete config.port;
+            break;
+        case 'mongodb':
+            normalizeRequiredText(config, 'url', 'database.url', 'DB_URL=mongodb://127.0.0.1:27017');
+            normalizeRequiredText(config, 'dbName', 'database.dbName', 'DB_NAME=zhin_bot');
+            if (!/^mongodb(?:\+srv)?:\/\//u.test(String(config.url)))
+                throw configurationError('database.url', '必须使用 mongodb:// 或 mongodb+srv://');
+            break;
+        case 'redis': {
+            normalizeOptionalText(config, 'url', 'database.url', 'REDIS_URL=redis://127.0.0.1:6379');
+            if (config.socket !== undefined) {
+                if (!config.socket || typeof config.socket !== 'object' || Array.isArray(config.socket))
+                    throw configurationError('database.socket', '必须是对象');
+                const socket = { ...config.socket };
+                normalizeOptionalText(socket, 'host', 'database.socket.host', 'REDIS_HOST=127.0.0.1');
+                socket.port = normalizePort(socket.port, 'database.socket.port', 'REDIS_PORT=6379');
+                if (socket.port === undefined)
+                    delete socket.port;
+                config.socket = Object.freeze(socket);
+            }
+            config.database = normalizeRedisDatabase(config.database);
+            if (config.database === undefined)
+                delete config.database;
+            break;
+        }
+        case 'sqlite':
+            if (config.filename === undefined)
+                config.filename = './data/bot.db';
+            normalizeOptionalText(config, 'filename', 'database.filename');
+            break;
+        case 'memory':
+            break;
+    }
+    return Object.freeze(config);
+}
+/**
+ * Resolves the expanded root config document's `database` block. A relative SQLite file is
+ * anchored at the project root (the instance runs with the project root as cwd, so both
+ * processes open the same file).
+ */
+export async function resolveProjectDatabaseConfig(projectRoot, document) {
+    const configured = document && typeof document === 'object' ? document.database : undefined;
+    if (configured && typeof configured === 'object' && !Array.isArray(configured)) {
+        const value = configured;
+        const normalized = normalizeProjectDatabaseConfig({ ...value, dialect: typeof value.dialect === 'string' ? value.dialect : 'sqlite' });
+        if (normalized.dialect === 'sqlite' && typeof normalized.filename === 'string' && !isSqliteMemory(normalized.filename) && !isAbsolute(normalized.filename)) {
+            return Object.freeze({ ...normalized, filename: resolve(projectRoot, normalized.filename) });
+        }
+        return normalized;
+    }
+    const filename = join(projectRoot, DEFAULT_PROJECT_DATABASE_FILE);
+    await mkdir(dirname(filename), { recursive: true });
+    return Object.freeze({ dialect: 'sqlite', filename });
+}
+/**
+ * The root config document with `${…}` expanded against process env and the project `.env`
+ * layers of `environment` (missing variables become empty, as in the instance). Only the gateway's
+ * own blocks are read from it (`database`, `console.terminal`): plugin declarations are not
+ * validated here, so a config the instance rejects still leaves the Console reachable.
+ */
+export async function loadExpandedProjectConfig(projectRoot, environment = 'development') {
+    const file = findConfigFile(projectRoot);
+    if (!file)
+        return Object.freeze({});
+    const [document, layers] = await Promise.all([
+        createConfigDocument(join(projectRoot, file)).read().then((snapshot) => snapshot.document),
+        loadRuntimeEnvironmentLayers(projectRoot, environment),
+    ]);
+    if (!document || typeof document !== 'object' || Array.isArray(document))
+        return Object.freeze({});
+    const overlay = layers.environments?.[environment];
+    return expandEnvironmentValue(document, (key) => overlay?.[key] ?? layers.base?.[key] ?? process.env[key]);
+}
+/** {@link resolveProjectDatabaseConfig} over {@link loadExpandedProjectConfig}. */
+export async function loadProjectDatabaseConfig(projectRoot, environment = 'development') {
+    return resolveProjectDatabaseConfig(projectRoot, await loadExpandedProjectConfig(projectRoot, environment));
+}
+function isSqliteMemory(filename) {
+    return filename === ':memory:' || filename.startsWith('file::memory:');
+}

package/lib/database/index.d.ts

@@ -0,0 +1,2 @@
+export * from './config.js';
+export * from './project-database.js';

package/lib/database/index.js

@@ -0,0 +1,2 @@
+export * from './config.js';
+export * from './project-database.js';

package/lib/database/project-database.d.ts

@@ -0,0 +1,31 @@
+import type { DatabaseHostModel } from '@zhin.js/plugin-runtime';
+import type { ProjectDatabaseConfig } from './config.js';
+/**
+ * How long a gateway statement retries `SQLITE_BUSY` while the instance holds the write lock
+ * (`busyRetryMs` in `@zhin.js/database`). The retry backs off asynchronously, so the gateway's
+ * event loop keeps serving requests during the wait; a synchronous `busy_timeout` would stall
+ * every request for as long as an instance transaction runs. Past the budget the request
+ * answers `503 database_busy` ({@link isDatabaseBusyError}).
+ */
+export declare const GATEWAY_SQLITE_BUSY_RETRY_MS = 5000;
+/** Seconds a `503 database_busy` asks the client to wait. */
+export declare const DATABASE_BUSY_RETRY_AFTER_SECONDS = 2;
+/** The database stayed locked by another connection for the whole retry budget. */
+export declare function isDatabaseBusyError(error: unknown): boolean;
+/** `503 { code: 'database_busy' }` with `Retry-After`. */
+export declare function databaseBusyResponse(extra?: Readonly<Record<string, unknown>>): Response;
+/** One database connection; tables are defined before {@link start}. */
+export declare class ProjectDatabase {
+    #private;
+    readonly config: ProjectDatabaseConfig;
+    constructor(config: ProjectDatabaseConfig);
+    get dialect(): string;
+    get started(): boolean;
+    define(name: string, definition: Record<string, unknown>): void;
+    tables(): readonly string[];
+    readonly models: Readonly<{
+        get: (name: string) => DatabaseHostModel | undefined;
+    }>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/lib/database/project-database.js

@@ -0,0 +1,130 @@
+/**
+ * The gateway's own connection to the project database (ADR 0054 §7). It defines and serves only
+ * the tables the gateway owns (`console_*`, ADR 0049); the instance opens the same database for
+ * everything else. SQLite runs in WAL mode (`@zhin.js/database`), so both processes can hold the
+ * file open.
+ */
+import { isSqliteBusyError, Registry } from '@zhin.js/database';
+/**
+ * How long a gateway statement retries `SQLITE_BUSY` while the instance holds the write lock
+ * (`busyRetryMs` in `@zhin.js/database`). The retry backs off asynchronously, so the gateway's
+ * event loop keeps serving requests during the wait; a synchronous `busy_timeout` would stall
+ * every request for as long as an instance transaction runs. Past the budget the request
+ * answers `503 database_busy` ({@link isDatabaseBusyError}).
+ */
+export const GATEWAY_SQLITE_BUSY_RETRY_MS = 5_000;
+/** Seconds a `503 database_busy` asks the client to wait. */
+export const DATABASE_BUSY_RETRY_AFTER_SECONDS = 2;
+/** The database stayed locked by another connection for the whole retry budget. */
+export function isDatabaseBusyError(error) {
+    for (let current = error, depth = 0; current && depth < 4; depth += 1) {
+        if (isSqliteBusyError(current))
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
+/** `503 { code: 'database_busy' }` with `Retry-After`. */
+export function databaseBusyResponse(extra = {}) {
+    return new Response(JSON.stringify({
+        success: false,
+        code: 'database_busy',
+        error: '数据库正忙，请稍后重试',
+        ...extra,
+    }), {
+        status: 503,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+            'retry-after': String(DATABASE_BUSY_RETRY_AFTER_SECONDS),
+        },
+    });
+}
+function wrapModel(model) {
+    return Object.freeze({
+        select: (...fields) => {
+            if (fields.includes('*'))
+                throw new TypeError('select() requires explicit column names');
+            const selection = model.select(...fields);
+            const chain = {
+                where: (query) => { selection.where(query); return chain; },
+                orderBy: (field, direction) => { selection.orderBy?.(field, direction); return chain; },
+                limit: (count) => { selection.limit?.(count); return chain; },
+                then: (onfulfilled, onrejected) => Promise.resolve(selection).then(onfulfilled, onrejected),
+            };
+            return chain;
+        },
+        insert: (row) => Promise.resolve(model.insert(row)),
+        delete: () => ({ where: (query) => Promise.resolve(model.delete(query)) }),
+        update: (patch) => ({ where: (query) => Promise.resolve(model.update(patch).where(query)) }),
+    });
+}
+/** One database connection; tables are defined before {@link start}. */
+export class ProjectDatabase {
+    config;
+    #db;
+    #tables = new Set();
+    #wrapped = new Map();
+    #started = false;
+    constructor(config) {
+        this.config = config;
+        const { dialect, ...connection } = config;
+        // No synchronous busy_timeout: it would block the gateway's event loop (ADR 0054 §7).
+        const options = dialect === 'sqlite' && connection.busyRetryMs === undefined
+            ? { ...connection, busyRetryMs: GATEWAY_SQLITE_BUSY_RETRY_MS }
+            : connection;
+        this.#db = Registry.create(dialect, options);
+    }
+    get dialect() {
+        return this.config.dialect;
+    }
+    get started() {
+        return this.#started;
+    }
+    define(name, definition) {
+        if (this.#started)
+            throw new Error(`Project database already started; cannot define table ${name}`);
+        if (this.#tables.has(name))
+            return;
+        this.#tables.add(name);
+        this.#db.define(name, definition);
+    }
+    tables() {
+        return [...this.#tables];
+    }
+    models = Object.freeze({
+        get: (name) => {
+            if (!this.#started)
+                return undefined;
+            const cached = this.#wrapped.get(name);
+            if (cached)
+                return cached;
+            const raw = this.#db.models.get(name);
+            if (!raw)
+                return undefined;
+            const model = wrapModel(raw);
+            this.#wrapped.set(name, model);
+            return model;
+        },
+    });
+    async start() {
+        if (this.#started)
+            return;
+        try {
+            await this.#db.start();
+        }
+        catch (error) {
+            await this.#db.stop().catch(() => undefined);
+            throw error;
+        }
+        this.#started = true;
+        this.#wrapped.clear();
+    }
+    async stop() {
+        if (!this.#started)
+            return;
+        this.#started = false;
+        this.#wrapped.clear();
+        await this.#db.stop();
+    }
+}

package/lib/database.d.ts

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/database` — the gateway's connection to the project database (ADR 0054 §7). */
+export * from './database/index.js';

package/lib/database.js

@@ -0,0 +1,2 @@
+/** `@zhin.js/gateway/database` — the gateway's connection to the project database (ADR 0054 §7). */
+export * from './database/index.js';

package/lib/http/console-rpc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Gateway-owned Console RPC on `POST {base}/console/request` (ADR 0054 §4 / §5): the Console
+ * sends `{ type, requestId?, data? }`; `gateway.*` types are answered here with the same reply
+ * envelope the instance uses (`{ success, data, type, requestId }` / `{ success: false, code,
+ * error, requestId, errors?, missingEnv? }`, see `GatewayRpcHttpErrorReply`), every other
+ * type is forwarded to the instance by the HTTP server.
+ */
+import { type RouteContext, type TokenRegistry } from '@zhin.js/host-http';
+import type { GatewayRpcDispatcher } from '../packages/rpc.js';
+/** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
+export declare const GATEWAY_RPC_PREFIX = "gateway.";
+export interface GatewayConsoleRpc {
+    handle(message: Readonly<Record<string, unknown>>, context: RouteContext, tokenRegistry: TokenRegistry): Promise<Response>;
+}
+/** Further gateway-owned RPC types (`iam.*`, `onboarding.update`), see `GatewayHttpServer.useConsoleRpc`. */
+export interface GatewayRpcHandler extends GatewayConsoleRpc {
+    owns(type: string): boolean;
+}
+export declare function createGatewayConsoleRpc(dispatch: GatewayRpcDispatcher): GatewayConsoleRpc;

package/lib/http/console-rpc.js

@@ -0,0 +1,51 @@
+/**
+ * Gateway-owned Console RPC on `POST {base}/console/request` (ADR 0054 §4 / §5): the Console
+ * sends `{ type, requestId?, data? }`; `gateway.*` types are answered here with the same reply
+ * envelope the instance uses (`{ success, data, type, requestId }` / `{ success: false, code,
+ * error, requestId, errors?, missingEnv? }`, see `GatewayRpcHttpErrorReply`), every other
+ * type is forwarded to the instance by the HTTP server.
+ */
+import { auditActor, jsonResponse, } from '@zhin.js/host-http';
+import { GATEWAY_RPC } from '@zhin.js/console-protocol';
+/** RPC types with this prefix belong to the gateway (unknown ones are refused as unmapped). */
+export const GATEWAY_RPC_PREFIX = 'gateway.';
+const READ_ONLY_TYPES = new Set([
+    GATEWAY_RPC.LIST,
+    GATEWAY_RPC.PLAN,
+    GATEWAY_RPC.STATUS,
+    GATEWAY_RPC.LOGS,
+]);
+export function createGatewayConsoleRpc(dispatch) {
+    return Object.freeze({
+        async handle(message, context, tokenRegistry) {
+            const type = typeof message.type === 'string' ? message.type : '';
+            const requestId = message.requestId;
+            const principal = context.principal;
+            const result = await dispatch({ type, data: message.data }, principal);
+            const write = !READ_ONLY_TYPES.has(type);
+            const outcome = result.ok ? 'ok' : result.error.code === 'forbidden' ? 'denied' : 'error';
+            if (write || outcome === 'denied') {
+                try {
+                    tokenRegistry.accessProvider?.audit?.({
+                        actor: auditActor(principal),
+                        action: `rpc:${type}`.slice(0, 256),
+                        outcome,
+                        ...(context.remoteAddress ? { ip: context.remoteAddress } : {}),
+                    });
+                }
+                catch { /* audit never breaks a request */ }
+            }
+            const noStore = { 'cache-control': 'no-store' };
+            if (result.ok)
+                return jsonResponse(200, { success: true, data: result.data, type, requestId }, noStore);
+            return jsonResponse(result.error.status, {
+                success: false,
+                code: result.error.code,
+                error: result.error.message,
+                requestId,
+                ...(result.error.errors ? { errors: result.error.errors } : {}),
+                ...(result.error.missingEnv ? { missingEnv: result.error.missingEnv } : {}),
+            }, noStore);
+        },
+    });
+}

package/lib/http/gateway-console.d.ts

@@ -0,0 +1,63 @@
+import { type ConsoleAuditEntry } from '@zhin.js/host-http';
+import { type ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
+import { type ProjectDatabaseConfig } from '../database/config.js';
+import { ProjectDatabase } from '../database/project-database.js';
+import { type LocalConsoleAdmin } from '../iam/local-admin.js';
+import { ConsoleIamService } from '../iam/service.js';
+import { ConsoleSetupService } from '../iam/setup-service.js';
+import { OnboardingService } from '../onboarding/service.js';
+import type { ConsoleTerminalHandle } from '../terminal/index.js';
+import type { GatewayRpcHandler } from './console-rpc.js';
+import type { GatewayHttpServer } from './gateway-http-server.js';
+/** What the Console module needs from the instance bridge (`IpcInstanceTransport` has all of it). */
+export interface GatewayConsoleInstancePort {
+    /** Plugin permission catalog the instance last reported. */
+    pluginPermissions?(): readonly ConsolePluginPermissionInfo[];
+    /** Sends `principal-revoked` (the instance closes that user's live connections). */
+    revokePrincipal?(principalId: string, reason?: string): void;
+    /** Audit entries written by the instance. */
+    onAudit?(listener: (entry: ConsoleAuditEntry) => void): () => void;
+}
+export interface GatewayConsoleOptions {
+    readonly server: GatewayHttpServer;
+    readonly projectRoot: string;
+    /** Selects `.env.<environment>` for `${…}` in `database` / `console.terminal`. Default `development`. */
+    readonly environment?: string;
+    readonly instance?: GatewayConsoleInstancePort;
+    /** Restarts the instance after the setup wizard switched databases (ADR 0054 §7). */
+    readonly restartInstance?: () => Promise<void>;
+    /** Overrides the project `database` block (tests). */
+    readonly database?: ProjectDatabaseConfig;
+    /** Overrides the project `console.terminal` block. */
+    readonly terminal?: unknown;
+    readonly onboarding?: OnboardingService;
+    /** Retry interval while the database cannot be opened. Default 10 s. */
+    readonly retryMs?: number;
+}
+export interface GatewayConsole {
+    /** Settles once the first database open attempt finished (never rejects). */
+    readonly ready: Promise<void>;
+    /** The IAM service bound to the open database; undefined when the dialect cannot hold accounts. */
+    iam(): ConsoleIamService | undefined;
+    /** The gateway's database connection (undefined before the first open). */
+    database(): ProjectDatabase | undefined;
+    readonly setup: ConsoleSetupService;
+    readonly onboarding: OnboardingService;
+    readonly terminal: ConsoleTerminalHandle;
+    /** Closes the gateway's connection and opens the configured database again (setup wizard). */
+    reopenDatabase(): Promise<void>;
+    /** Socket-only `gateway.console.*` (`zhin console init` / `zhin console user` beside the gateway). */
+    readonly localAdmin: LocalConsoleAdmin;
+    close(): Promise<void>;
+}
+export declare function startGatewayConsole(options: GatewayConsoleOptions): Promise<GatewayConsole>;
+export interface GatewayAccountRpcOptions {
+    readonly iam: () => ConsoleIamService | undefined;
+    readonly onboarding: OnboardingService;
+}
+/**
+ * `iam.*` (ADR 0049 §5) and `onboarding.update` (ADR 0053 §4) on the gateway's
+ * `POST {base}/console/request`. Authorization uses the shared permission map
+ * (`CONSOLE_RPC_PERMISSIONS`); denials and writes are audited like in the instance dispatcher.
+ */
+export declare function createGatewayAccountRpc(options: GatewayAccountRpcOptions): GatewayRpcHandler;