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

package/lib/packages/rpc.js

@@ -0,0 +1,160 @@
+/**
+ * Transport-independent dispatcher for the gateway's own RPC (`gateway.packages.*`,
+ * `gateway.instance.*`, ADR 0054 §4 / §5). The HTTP server maps envelopes onto it; the permission
+ * map in `@zhin.js/console-protocol` is checked here, then each service applies its own rules.
+ */
+import { GATEWAY_RPC, GATEWAY_RPC_PERMISSIONS, } from '@zhin.js/console-protocol';
+import { OnboardingError } from '../onboarding/errors.js';
+import { gatewayPrincipalAllows } from './authorization.js';
+import { GatewayError } from './errors.js';
+const GATEWAY_TYPES = new Set(Object.values(GATEWAY_RPC));
+const DEFAULT_LOG_LINES = 200;
+const MAX_LOG_LINES = 1_000;
+export function isGatewayRpcType(type) {
+    return typeof type === 'string' && GATEWAY_TYPES.has(type);
+}
+export function createGatewayRpcDispatcher(dependencies) {
+    return (request, principal) => dispatchGatewayRpc(request, principal, dependencies);
+}
+/** Dispatches one gateway RPC; never throws (errors become `{ ok: false }`). */
+export async function dispatchGatewayRpc(request, principal, dependencies) {
+    try {
+        const type = request?.type;
+        if (!isGatewayRpcType(type))
+            throw new GatewayError('unmapped', `RPC "${String(type ?? '').slice(0, 64)}" 未登记权限`);
+        if (!principal)
+            throw new GatewayError('forbidden', '未登录');
+        const packageMutation = type === GATEWAY_RPC.PLAN || type === GATEWAY_RPC.INSTALL;
+        // The bootstrap token reaches plan / install only, where the service limits it to database drivers.
+        const bootstrapDelegated = principal !== 'local' && principal.kind === 'bootstrap' && packageMutation;
+        if (!bootstrapDelegated && !gatewayPrincipalAllows(principal, GATEWAY_RPC_PERMISSIONS[type])) {
+            throw new GatewayError('forbidden', `缺少权限 ${GATEWAY_RPC_PERMISSIONS[type]}`);
+        }
+        const data = record(request.data);
+        return Object.freeze({ ok: true, data: await handle(type, data, principal, dependencies) });
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+async function handle(type, data, principal, deps) {
+    switch (type) {
+        case 'gateway.packages.list': return packagesOf(deps).list(principal);
+        case 'gateway.packages.plan': {
+            const operation = data.operation;
+            if (operation !== 'install' && operation !== 'uninstall' && operation !== 'update')
+                throw new GatewayError('invalid_input', 'operation 只能是 install / uninstall / update');
+            return packagesOf(deps).plan(operation, packageList(data, operation === 'update'), principal);
+        }
+        case 'gateway.packages.install':
+            return packagesOf(deps).install(packageList(data, false), {
+                principal, ...optionalBoolean(data, 'enable'), ...optionalBoolean(data, 'startInstance'),
+            });
+        case 'gateway.packages.uninstall':
+            return packagesOf(deps).uninstall(packageList(data, false), {
+                principal, ...optionalBoolean(data, 'startInstance'), ...optionalBoolean(data, 'removeDependency'),
+            });
+        case 'gateway.packages.update':
+            return packagesOf(deps).update(packageList(data, true), { principal, ...optionalBoolean(data, 'startInstance') });
+        case 'gateway.plugins.declare': {
+            if (data.config !== undefined && (!data.config || typeof data.config !== 'object' || Array.isArray(data.config))) {
+                throw new GatewayError('invalid_input', 'config 必须是对象');
+            }
+            return packagesOf(deps).declare({ package: data.package, instanceKey: data.instanceKey, config: data.config }, {
+                principal, ...optionalBoolean(data, 'startInstance'),
+            });
+        }
+        case 'gateway.plugins.enable':
+        case 'gateway.plugins.disable':
+            return packagesOf(deps).setEnabled({ plugin: data.plugin }, type === 'gateway.plugins.enable', {
+                principal, ...optionalBoolean(data, 'startInstance'),
+            });
+        case 'gateway.instance.status': return instanceStatus(instanceOf(deps).status());
+        case 'gateway.instance.logs': {
+            const lines = data.lines === undefined ? DEFAULT_LOG_LINES : data.lines;
+            if (typeof lines !== 'number' || !Number.isInteger(lines) || lines < 1 || lines > MAX_LOG_LINES) {
+                throw new GatewayError('invalid_input', `lines 必须是 1–${MAX_LOG_LINES} 的整数`);
+            }
+            const result = Object.freeze({
+                lines: Object.freeze(instanceOf(deps).logs.tail(lines).map(line => Object.freeze({ seq: line.seq, time: line.time, stream: line.stream, line: line.line }))),
+            });
+            return result;
+        }
+        case 'gateway.instance.start':
+        case 'gateway.instance.stop':
+        case 'gateway.instance.restart': {
+            const instance = instanceOf(deps);
+            // A dependency transaction owns the instance until it ends.
+            if (deps.packages?.activeTransaction)
+                throw new GatewayError('conflict', '依赖事务进行中，实例由事务停启');
+            try {
+                if (type === 'gateway.instance.start')
+                    await instance.start();
+                else if (type === 'gateway.instance.stop')
+                    await instance.stop({ reason: 'console' });
+                else
+                    await instance.restart({ reason: 'console' });
+            }
+            catch (error) {
+                throw new GatewayError('unavailable', error instanceof Error ? error.message : String(error), { cause: error });
+            }
+            return instanceStatus(instance.status());
+        }
+    }
+}
+function packagesOf(deps) {
+    if (!deps.packages)
+        throw new GatewayError('unavailable', '依赖管理不可用');
+    return deps.packages;
+}
+function instanceOf(deps) {
+    if (!deps.instance)
+        throw new GatewayError('unavailable', '网关未管理实例');
+    return deps.instance;
+}
+export function instanceStatus(status) {
+    return Object.freeze({
+        instanceId: 'default',
+        state: status.state,
+        ...(status.pid === undefined ? {} : { pid: status.pid }),
+        ...(status.startedAt === undefined ? {} : { startedAt: status.startedAt }),
+        ...(status.generation === undefined ? {} : { generation: status.generation }),
+        ...(status.protocolVersion === undefined ? {} : { protocolVersion: status.protocolVersion }),
+        lastExitCode: status.lastExitCode,
+        lastExitSignal: status.lastExitSignal,
+        ...(status.lastFailure ? { lastFailure: Object.freeze({ ...status.lastFailure }) } : {}),
+        recentRestarts: status.recentRestarts,
+    });
+}
+function record(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new GatewayError('invalid_input', 'data 必须是对象');
+    return value;
+}
+function packageList(data, allowAll) {
+    const value = data.packages;
+    if (allowAll && value === 'all')
+        return 'all';
+    if (!Array.isArray(value))
+        throw new GatewayError('invalid_input', allowAll ? 'packages 必须是数组或 "all"' : 'packages 必须是数组');
+    return value;
+}
+function optionalBoolean(data, key) {
+    const value = data[key];
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'boolean')
+        throw new GatewayError('invalid_input', `${key} 必须是布尔值`);
+    return { [key]: value };
+}
+function failure(error) {
+    const known = error instanceof GatewayError ? error
+        : error instanceof OnboardingError ? new GatewayError(error.code, error.message)
+            : undefined;
+    const code = known?.code ?? 'internal';
+    // Unexpected errors are not echoed: they may carry paths or package-manager output.
+    const message = known?.message ?? '网关内部错误';
+    return Object.freeze({ ok: false, error: Object.freeze({ code, message, status: known?.status ?? 500, ...known?.details }) });
+}

package/lib/packages/service.d.ts

@@ -0,0 +1,139 @@
+import type { GatewayAuthorizedPackage, GatewayPackageEvent, GatewayPackageList, GatewayPackageOperation, GatewayPackagePlan, GatewayPackageTransactionResult } from '@zhin.js/console-protocol';
+import { type InstallAllowlist, type MarketCatalogEntry } from '../onboarding/allowlist.js';
+import { type PackageManagerOutput } from '../onboarding/package-manager.js';
+import { type PluginManagementOptions } from '../plugin-management/workflow.js';
+import { type InstanceFailure, type InstanceState, type InstanceStatus, type InstanceStopOptions } from '../supervisor/instance-supervisor.js';
+import type { InstanceLogLine } from '../supervisor/instance-logs.js';
+import { type GatewayPackageAction, type GatewayPrincipal } from './authorization.js';
+/** The part of `InstanceSupervisor` a transaction drives. */
+export interface PackageTransactionInstance {
+    readonly state: InstanceState;
+    start(): Promise<void>;
+    stop(options?: InstanceStopOptions): Promise<void>;
+    status(): InstanceStatus;
+    on(event: 'failure', listener: (failure: InstanceFailure) => void): unknown;
+    off(event: 'failure', listener: (failure: InstanceFailure) => void): unknown;
+    readonly logs?: {
+        tail(limit?: number): readonly InstanceLogLine[];
+    };
+}
+/** The part of `PluginManagementWorkflow` (`PluginManagementPort`) a transaction uses. */
+export interface PackageWorkflowPort {
+    inspect(request: string): Promise<{
+        readonly declared: boolean;
+    }>;
+    install(spec: string, expectedRevision?: string, expectedProjectRevision?: string, options?: {
+        readonly enable?: boolean;
+    }): Promise<unknown>;
+    uninstall(request: string, expectedRevision?: string, expectedProjectRevision?: string, options?: {
+        readonly removeDependency?: boolean;
+    }): Promise<unknown>;
+    update(request: string, targetVersion: string): Promise<unknown>;
+    /** Validates a declaration without writing (throws `PluginDeclarationError`). */
+    planDeclaration?(request: string, config?: unknown, options?: {
+        readonly instanceKey?: string;
+    }): Promise<unknown>;
+    declare?(request: string, config?: unknown, options?: {
+        readonly instanceKey?: string;
+    }): Promise<unknown>;
+    /** Validates an enable / disable without writing (throws `PluginEnablementError`). */
+    planSetEnabled?(request: string, enabled: boolean): Promise<{
+        readonly packageName: string;
+        readonly instanceKey: string;
+        readonly changed: boolean;
+    }>;
+    setEnabled?(request: string, enabled: boolean): Promise<unknown>;
+}
+/**
+ * Runs the package manager with pnpm-style args (`add|remove|update|install …`), streaming output.
+ * The default spawns the project's detected manager without a shell.
+ */
+export type GatewayPackageManager = (args: readonly string[], projectRoot: string, output: PackageManagerOutput) => Promise<void>;
+export type GatewayPackageListener = (event: GatewayPackageEvent) => void;
+export interface GatewayPackageServiceOptions {
+    readonly projectRoot: string;
+    /** The supervised instance; omitted when no instance is managed (CLI without a running gateway). */
+    readonly instance?: PackageTransactionInstance;
+    readonly packageManager?: GatewayPackageManager;
+    /** Defaults to a `PluginManagementWorkflow` on the project root using {@link packageManager}. */
+    readonly workflow?: PackageWorkflowPort;
+    /** Options for the default workflow. */
+    readonly workflowOptions?: Omit<PluginManagementOptions, 'installDependencies'>;
+    /** True once an owner exists (bootstrap token refused afterwards). Default: true (deny bootstrap). */
+    readonly hasOwner?: () => boolean | Promise<boolean>;
+    /** Plugin-market entries joining the non-owner allowlist. */
+    readonly marketCatalog?: () => readonly MarketCatalogEntry[] | Promise<readonly MarketCatalogEntry[]>;
+    /** Extra policy after the built-in rules; throw to deny. */
+    readonly authorize?: (principal: GatewayPrincipal, action: GatewayPackageAction, packages: readonly GatewayAuthorizedPackage[]) => void | Promise<void>;
+    /**
+     * Time the instance gets to report `ready` after a transaction. Default 60 s
+     * (`gateway.readyTimeout`). A function is read at each start, after {@link beforeTransaction}.
+     */
+    readonly readyTimeoutMs?: number | (() => number | undefined);
+    /** Runs at the start of every transaction (the gateway re-reads `gateway.readyTimeout`). */
+    readonly beforeTransaction?: () => Promise<void>;
+    /** After `ready`, a failure within this window (crash, crash storm) fails the transaction. Default 5 s. */
+    readonly stableMs?: number;
+    readonly now?: () => number;
+}
+export interface GatewayTransactionOptions {
+    readonly principal: GatewayPrincipal | undefined;
+    /** Start the instance afterwards even when it was not running before. */
+    readonly startInstance?: boolean;
+    readonly onEvent?: GatewayPackageListener;
+}
+export interface GatewayUninstallOptions extends GatewayTransactionOptions {
+    /** Also remove the npm dependency when nothing else references it (default true). */
+    readonly removeDependency?: boolean;
+}
+export interface GatewayInstallOptions extends GatewayTransactionOptions {
+    /** Declare installed plugins in the root config (default true). */
+    readonly enable?: boolean;
+}
+export interface GatewayDeclareRequest {
+    readonly package: unknown;
+    readonly instanceKey?: unknown;
+    readonly config?: unknown;
+}
+export interface GatewaySetEnabledRequest {
+    /** A declared instance key, or the package name of a package declared exactly once. */
+    readonly plugin: unknown;
+}
+export declare const DEFAULT_PACKAGE_READY_TIMEOUT_MS = 60000;
+export declare const DEFAULT_PACKAGE_STABLE_MS = 5000;
+export declare class GatewayPackageService {
+    #private;
+    constructor(options: GatewayPackageServiceOptions);
+    /** Id of the running transaction, if any. */
+    get activeTransaction(): string | undefined;
+    /** Progress of every transaction (for `gateway.packages.progress`); returns an unsubscribe function. */
+    subscribe(listener: GatewayPackageListener): () => void;
+    allowlist(): Promise<InstallAllowlist>;
+    /** Authorizes one action; throws {@link GatewayError} (deny by default). */
+    authorize(principal: GatewayPrincipal | undefined, action: GatewayPackageAction, packages?: readonly unknown[] | 'all'): Promise<readonly GatewayAuthorizedPackage[]>;
+    /** Declared dependencies with their installed versions. */
+    list(principal: GatewayPrincipal | undefined): Promise<GatewayPackageList>;
+    /** What a transaction would do, after authorization; changes nothing. */
+    plan(operation: GatewayPackageOperation, packages: readonly unknown[] | 'all', principal: GatewayPrincipal | undefined): Promise<GatewayPackagePlan>;
+    install(packages: readonly unknown[], options: GatewayInstallOptions): Promise<GatewayPackageTransactionResult>;
+    /**
+     * `gateway.plugins.declare`: declares an installed plugin with its first configuration (schema
+     * validated before the instance is touched), then restarts the instance; a failed start rolls
+     * the configuration file back and starts the previous instance again.
+     */
+    declare(request: GatewayDeclareRequest, options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
+    /**
+     * `gateway.plugins.enable` / `gateway.plugins.disable`: rewrites `disable_plugins` for one
+     * declared instance, then restarts the instance (a failed start restores the configuration file
+     * and starts the previous instance again). Validation runs before the instance is touched; an
+     * instance already in the requested state succeeds without stopping anything or writing.
+     */
+    setEnabled(request: GatewaySetEnabledRequest, enabled: boolean, options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
+    uninstall(packages: readonly unknown[], options: GatewayUninstallOptions): Promise<GatewayPackageTransactionResult>;
+    /** Exact versions go through the workflow (verified); bare names / `'all'` run the manager's update. */
+    update(packages: readonly unknown[] | 'all', options: GatewayTransactionOptions): Promise<GatewayPackageTransactionResult>;
+    /** {@link install} / {@link uninstall} / {@link update} as an async iterator of its events. */
+    stream(operation: GatewayPackageOperation, packages: readonly unknown[] | 'all', options: GatewayInstallOptions): AsyncIterableIterator<GatewayPackageEvent> & {
+        readonly result: Promise<GatewayPackageTransactionResult>;
+    };
+}