@easyai-canvas/canvas-plugin-sdk 0.1.0

package/dist/runtime/package-runtime.js

@@ -0,0 +1,361 @@
+/** Shared package transport/runtime. The platform copy is generated, never hand edited. */
+import JSZip from 'jszip';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, rm, lstat, } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fork } from 'node:child_process';
+import { ContractError, validateManifest, validateExecution, object, } from '../protocol/index.js';
+export const PLUGIN_PACKAGE_MAX_BYTES = 16 * 1024 * 1024;
+const MAX_EXPANDED_BYTES = 64 * 1024 * 1024;
+const MAX_FILES = 128;
+export function packageSha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function fail(message) {
+    throw new ContractError(message, 400, 'INVALID_PACKAGE');
+}
+function record(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function relativePath(value) {
+    if (typeof value !== 'string' ||
+        value.length > 240 ||
+        !/^[a-zA-Z0-9_.\/-]+$/.test(value) ||
+        value.split('/').some((p) => !p || p === '.' || p === '..') ||
+        /(^|\/)(node_modules|\.env[^/]*|package\.json|\.git)(\/|$)/i.test(value))
+        fail('插件文件路径无效或包含不允许的文件');
+    return value;
+}
+// Reject oversized/ambiguous central directories before JSZip allocates entries.
+function checkZipDirectory(bytes) {
+    const end = bytes.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+    if (end < 0 ||
+        end + 22 > bytes.length ||
+        end + 22 + bytes.readUInt16LE(end + 20) !== bytes.length)
+        fail('插件压缩包目录损坏');
+    const count = bytes.readUInt16LE(end + 10);
+    if (!count ||
+        count > MAX_FILES ||
+        bytes.readUInt16LE(end + 4) ||
+        bytes.readUInt16LE(end + 6))
+        fail('插件包文件数量超限或压缩格式不支持');
+    let offset = bytes.readUInt32LE(end + 16), expanded = 0;
+    const names = new Set();
+    for (let i = 0; i < count; i++) {
+        if (offset + 46 > end || bytes.readUInt32LE(offset) !== 0x02014b50)
+            fail('插件压缩包目录损坏');
+        const size = bytes.readUInt32LE(offset + 24), nameLength = bytes.readUInt16LE(offset + 28);
+        const next = offset +
+            46 +
+            nameLength +
+            bytes.readUInt16LE(offset + 30) +
+            bytes.readUInt16LE(offset + 32);
+        if (next > end || bytes.readUInt16LE(offset + 8) & 1)
+            fail('插件压缩包目录损坏或已加密');
+        const name = bytes
+            .subarray(offset + 46, offset + 46 + nameLength)
+            .toString('utf8');
+        if (names.has(name))
+            fail('插件包包含重复文件路径');
+        names.add(name);
+        expanded += size;
+        if (size > PLUGIN_PACKAGE_MAX_BYTES || expanded > MAX_EXPANDED_BYTES)
+            fail('插件解压大小超过限制');
+        offset = next;
+    }
+    if (offset !== end)
+        fail('插件压缩格式不支持');
+}
+export async function inspectPluginPackage(bytes) {
+    if (!bytes.length || bytes.length > PLUGIN_PACKAGE_MAX_BYTES)
+        fail('插件包大小超过限制');
+    checkZipDirectory(bytes);
+    const zip = await JSZip.loadAsync(bytes).catch(() => fail('插件压缩包损坏'));
+    const entries = Object.values(zip.files);
+    if (entries.length > MAX_FILES)
+        fail('插件包文件数量超过限制');
+    const files = new Map();
+    let total = 0;
+    for (const entry of entries) {
+        const original = entry.unsafeOriginalName;
+        relativePath((original ?? entry.name).replace(/\/$/, ''));
+        if (original && original !== entry.name)
+            fail('插件文件路径越界');
+        const mode = typeof entry.unixPermissions === 'string'
+            ? parseInt(entry.unixPermissions, 8)
+            : (entry.unixPermissions ?? 0);
+        if ((mode & 0o170000) === 0o120000)
+            fail('插件包不允许符号链接');
+        if (entry.dir)
+            continue;
+        const chunks = [];
+        let size = 0;
+        await new Promise((resolve, reject) => {
+            const stream = entry.nodeStream();
+            stream.on('data', (chunk) => {
+                const buffer = Buffer.from(chunk);
+                size += buffer.length;
+                total += buffer.length;
+                if (size > PLUGIN_PACKAGE_MAX_BYTES || total > MAX_EXPANDED_BYTES) {
+                    stream.destroy();
+                    reject(new ContractError('插件解压大小超过限制', 400, 'INVALID_PACKAGE'));
+                    return;
+                }
+                chunks.push(buffer);
+            });
+            stream.once('error', reject);
+            stream.once('end', resolve);
+        });
+        files.set(entry.name, Buffer.concat(chunks));
+    }
+    let d;
+    try {
+        d = JSON.parse(files.get('plugin.json')?.toString('utf8') ?? '');
+    }
+    catch {
+        fail('插件包缺少有效的 plugin.json');
+    }
+    if (!record(d) ||
+        !['easyai.plugin-package/v1', 'easyai.plugin-package/v2'].includes(d.format) ||
+        !record(d.runtime) ||
+        !record(d.ui) ||
+        !record(d.files))
+        fail('插件包格式不支持');
+    const descriptor = d;
+    descriptor.manifest = validateManifest(descriptor.manifest);
+    if (d.runtime.nodeMajor !== 22 ||
+        !Array.isArray(d.runtime.capabilities) ||
+        !d.runtime.capabilities.length ||
+        d.runtime.capabilities.some((v) => !['actions', 'queries', ...(d.format === 'easyai.plugin-package/v2' ? ['nodes'] : [])].includes(String(v))) ||
+        (d.format === 'easyai.plugin-package/v1' && descriptor.manifest.contributes.nodes?.length))
+        fail('当前包运行环境不支持所需能力');
+    if (!Array.isArray(d.runtime.queries) ||
+        d.runtime.queries.some((q) => typeof q !== 'string' || !/^[a-zA-Z][\w.-]{0,100}$/.test(q)) ||
+        new Set(d.runtime.queries).size !== d.runtime.queries.length)
+        fail('插件查询声明无效');
+    const expectedHandlers = (descriptor.manifest.contributes.nodes ?? [])
+        .filter(node => node.execution === 'remote' || node.execution === 'confirmed')
+        .map(node => node.type).sort();
+    const handlers = d.runtime.handlers ?? [];
+    if (d.format === 'easyai.plugin-package/v2' && (!Array.isArray(handlers) ||
+        handlers.some((name) => typeof name !== 'string' || !/^[a-zA-Z][\w.-]{0,100}$/.test(name)) ||
+        JSON.stringify([...handlers].sort()) !== JSON.stringify(expectedHandlers) ||
+        Boolean(descriptor.manifest.contributes.nodes?.length) !== d.runtime.capabilities.includes('nodes')))
+        fail('插件节点处理器声明无效');
+    if (!relativePath(d.runtime.entry).endsWith('.mjs') ||
+        !relativePath(d.ui.entry).endsWith('.js') ||
+        !/^[A-Za-z_$][\w$]{0,127}$/.test(d.ui.globalName))
+        fail('插件入口声明无效');
+    if (d.ui.css && !relativePath(d.ui.css).endsWith('.css'))
+        fail('插件样式入口无效');
+    if (!d.files[d.runtime.entry] ||
+        !d.files[d.ui.entry] ||
+        (d.ui.css && !d.files[d.ui.css]))
+        fail('插件包缺少声明的入口');
+    for (const [path, hash] of Object.entries(d.files)) {
+        relativePath(path);
+        if (path === 'plugin.json' ||
+            typeof hash !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(hash) ||
+            !files.has(path) ||
+            packageSha256(files.get(path)) !== hash)
+            fail('插件文件摘要校验失败');
+    }
+    for (const path of files.keys())
+        if (path !== 'plugin.json' && !d.files[path])
+            fail('插件包包含未声明文件');
+    return { digest: packageSha256(bytes), descriptor, files };
+}
+const materializations = new Map();
+export async function materializePluginPackage(pkg, root) {
+    const key = join(root, pkg.digest);
+    const pending = materializations.get(key);
+    if (pending)
+        return pending;
+    const operation = materialize(pkg, root);
+    materializations.set(key, operation);
+    try {
+        return await operation;
+    }
+    finally {
+        if (materializations.get(key) === operation)
+            materializations.delete(key);
+    }
+}
+async function materialize(pkg, root) {
+    const directory = join(root, pkg.digest);
+    async function valid() {
+        try {
+            if (!(await lstat(directory)).isDirectory())
+                return false;
+            for (const [name, content] of pkg.files) {
+                if (!(await lstat(join(directory, name))).isFile() ||
+                    packageSha256(await readFile(join(directory, name))) !==
+                        packageSha256(content))
+                    return false;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (!(await valid())) {
+        await mkdir(root, { recursive: true, mode: 0o700 });
+        const staging = join(root, `.staging-${randomUUID()}`);
+        await mkdir(staging, { mode: 0o700 });
+        try {
+            for (const [name, content] of pkg.files) {
+                const path = join(staging, name);
+                await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+                await writeFile(path, content, { mode: 0o600 });
+            }
+            if (!(await valid())) {
+                // Local cache is disposable. Move corrupt content aside before publishing
+                // the fully verified replacement, tolerating other replica-local callers.
+                const quarantine = `${directory}.invalid-${randomUUID()}`;
+                await rename(directory, quarantine).catch((error) => {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                });
+                await rm(quarantine, { recursive: true, force: true });
+            }
+            try {
+                await rename(staging, directory);
+            }
+            catch (error) {
+                if (!(await valid()))
+                    throw error;
+            }
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    }
+    return { digest: pkg.digest, descriptor: pkg.descriptor, directory };
+}
+// A short-lived, trusted-code runner. Deliberately not a security sandbox.
+const RUNNER = `
+import { pathToFileURL } from 'node:url';
+process.once('message', async ({ entry, manifest, queries, handlers, call }) => {
+  try {
+    const mod = await import(pathToFileURL(entry).href);
+    const plugin = mod.default;
+    const canonical = value => value && typeof value === 'object' ? (Array.isArray(value) ? value.map(canonical) : Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])]))) : value;
+    if (!plugin || JSON.stringify(canonical(plugin.manifest)) !== JSON.stringify(canonical(manifest))) throw Object.assign(new Error('运行模块与插件声明不一致'), { code: 'INVALID_PACKAGE' });
+    if (JSON.stringify(Object.keys(plugin.queries ?? {}).sort()) !== JSON.stringify([...queries].sort()) || JSON.stringify(Object.keys(plugin.handlers ?? {}).sort()) !== JSON.stringify([...handlers].sort())) throw Object.assign(new Error('运行模块能力与包声明不一致'), { code: 'INVALID_PACKAGE' });
+    let result;
+    if (call.operation === 'inspect') result = plugin.manifest;
+    else if (call.operation === 'query') {
+      if (!Object.hasOwn(plugin.queries ?? {}, call.name) || typeof plugin.queries[call.name] !== 'function') throw Object.assign(new Error('插件查询不存在'), { code: 'QUERY_NOT_FOUND' });
+      result = await plugin.queries[call.name](call.input, call.config, call.context);
+    } else if (call.operation === 'check') result = plugin.checkConfig ? await plugin.checkConfig(call.config) : { supported: false };
+    else if (call.operation === 'resolve') result = plugin.resolveManifest ? await plugin.resolveManifest(call.config, structuredClone(plugin.manifest)) : plugin.manifest;
+    else if (call.operation === 'execute') {
+      const handler = plugin.handlers?.[call.request?.nodeType];
+      if (typeof handler !== 'function') throw Object.assign(new Error('插件节点处理器不存在'), { code: 'HANDLER_NOT_FOUND' });
+      result = await handler(call.request, { signal: new AbortController().signal, config: call.config ?? {}, progress() {}, files: { put() { throw new Error('托管节点暂不支持文件写入'); }, readJson() { throw new Error('托管节点暂不支持文件读取'); }, info() { throw new Error('托管节点暂不支持文件查询'); }, exists() { throw new Error('托管节点暂不支持文件查询'); } } });
+    }
+    else throw new Error('不支持的插件操作');
+    const text = JSON.stringify({ ok: true, result: result ?? null });
+    if (Buffer.byteLength(text) > 1048576) throw Object.assign(new Error('插件返回内容超过限制'), { code: 'RESULT_TOO_LARGE' });
+    process.send(JSON.parse(text));
+  } catch (error) {
+    let message = error instanceof Error ? error.message : '插件查询失败';
+    for (const field of manifest.configFields ?? []) if (field.type === 'secret' && typeof call.config?.[field.key] === 'string' && call.config[field.key]) message = message.split(call.config[field.key]).join('[已隐藏]');
+    process.send({ ok: false, error: { message: message.slice(0, 500), code: typeof error.code === 'string' ? error.code.slice(0, 80) : 'PLUGIN_ERROR', status: Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 ? error.status : 502 } });
+  }
+});
+`;
+let activeCalls = 0;
+export async function invokePluginPackage(pkg, call, options = {}) {
+    if (call.operation === 'execute') {
+        const request = object(call.request, 'request');
+        const node = pkg.descriptor.manifest.contributes.nodes?.find(item => item.type === request.nodeType);
+        if (request.pluginId !== pkg.descriptor.manifest.id || !node ||
+            !['remote', 'confirmed'].includes(node.execution) ||
+            !pkg.descriptor.runtime.handlers?.includes(node.type))
+            throw new ContractError('插件节点处理器与安装包声明不匹配', 400, 'INVALID_PACKAGE');
+        call = { ...call, request: validateExecution(request, node) };
+    }
+    if (Number(process.versions.node.split('.')[0]) !==
+        pkg.descriptor.runtime.nodeMajor)
+        throw new ContractError('平台 Node 运行版本不兼容', 400, 'INVALID_PACKAGE');
+    if (options.signal?.aborted)
+        throw new ContractError('插件操作已取消', 409, 'CANCELLED');
+    const runner = join(dirname(pkg.directory), `runner-${packageSha256(RUNNER)}.mjs`);
+    const temporaryRunner = `${runner}.${randomUUID()}`;
+    await writeFile(temporaryRunner, RUNNER, { mode: 0o600 });
+    await rename(temporaryRunner, runner);
+    if (activeCalls >= 4)
+        throw new ContractError('插件正在处理其他请求，请稍后重试', 429, 'PLUGIN_BUSY');
+    activeCalls++;
+    try {
+        return await new Promise((resolve, reject) => {
+            const child = fork(runner, [], {
+                execArgv: ['--max-old-space-size=128'],
+                cwd: pkg.directory,
+                env: {
+                    NODE_ENV: 'production',
+                    ...(process.env.NODE_EXTRA_CA_CERTS
+                        ? { NODE_EXTRA_CA_CERTS: process.env.NODE_EXTRA_CA_CERTS }
+                        : {}),
+                    ...(process.env.SSL_CERT_FILE
+                        ? { SSL_CERT_FILE: process.env.SSL_CERT_FILE }
+                        : {}),
+                },
+                stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+            });
+            let settled = false;
+            const finish = (error, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', cancel);
+                const complete = () => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(value);
+                };
+                if (!child.pid || child.exitCode !== null || child.signalCode !== null)
+                    complete();
+                else {
+                    child.once('exit', complete);
+                    child.kill('SIGKILL');
+                }
+            };
+            const cancel = () => finish(new ContractError('插件操作已取消', 409, 'CANCELLED'));
+            const timer = setTimeout(() => finish(new ContractError(call.operation === 'execute'
+                ? '托管节点超过 20 秒执行限制，请使用独立服务部署'
+                : '插件查询超时，请重试', 504, 'PLUGIN_TIMEOUT')), options.timeoutMs ?? 20_000);
+            options.signal?.addEventListener('abort', cancel, { once: true });
+            if (options.signal?.aborted) {
+                cancel();
+                return;
+            }
+            child.once('error', () => finish(new ContractError('插件进程无法启动', 502, 'PLUGIN_UNAVAILABLE')));
+            child.once('exit', () => finish(new ContractError('插件进程意外退出', 502, 'PLUGIN_UNAVAILABLE')));
+            child.once('message', (message) => {
+                if (message?.ok === true)
+                    finish(undefined, message.result);
+                else
+                    finish(new ContractError(message?.error?.message ?? '插件查询失败', message?.error?.status ?? 502, message?.error?.code ?? 'PLUGIN_ERROR'));
+            });
+            child.send({
+                entry: join(pkg.directory, pkg.descriptor.runtime.entry),
+                manifest: pkg.descriptor.manifest,
+                queries: pkg.descriptor.runtime.queries,
+                handlers: pkg.descriptor.runtime.handlers ?? [],
+                call,
+            }, (error) => {
+                if (error)
+                    finish(new ContractError('插件进程通信失败', 502, 'PLUGIN_UNAVAILABLE'));
+            });
+        });
+    }
+    finally {
+        activeCalls--;
+    }
+}

package/dist/runtime/packaged-plugins.d.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from '../sdk/index.js';
+export declare function loadPackagedPlugins(paths: string[], directory: string): Promise<{
+    plugins: Plugin[];
+    presentations: Record<string, Record<string, unknown>>;
+    downloads: Record<string, {
+        bytes: Buffer;
+        digest: string;
+    }>;
+    executionEntries: Record<string, {
+        entry: string;
+        digest: string;
+        entryHash: string;
+    }>;
+}>;

package/dist/runtime/packaged-plugins.js

@@ -0,0 +1,58 @@
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { inspectPluginPackage, materializePluginPackage, invokePluginPackage, } from './package-runtime.js';
+export async function loadPackagedPlugins(paths, directory) {
+    const plugins = [];
+    const executionEntries = {};
+    const presentations = {};
+    const downloads = {};
+    for (const path of paths) {
+        const bytes = await readFile(path);
+        const inspected = await inspectPluginPackage(bytes);
+        const pkg = await materializePluginPackage(inspected, directory);
+        await invokePluginPackage(pkg, { operation: 'inspect' });
+        const { descriptor: d, digest } = pkg;
+        if (presentations[d.manifest.id])
+            throw new Error('插件包标识重复');
+        downloads[d.manifest.id] = { bytes, digest };
+        // The independent service already runs trusted plugin code in its own process.
+        // Preserve the SDK's synchronous declaration resolver there. Platform imports
+        // and all queries continue to use the bounded child runner.
+        const definition = (await import(pathToFileURL(join(pkg.directory, d.runtime.entry)).href)).default;
+        if (d.format === 'easyai.plugin-package/v2' && d.runtime.handlers?.length) {
+            executionEntries[d.manifest.id] = { entry: join(pkg.directory, d.runtime.entry), digest,
+                entryHash: d.files[d.runtime.entry] };
+        }
+        plugins.push({
+            resolveManifest: definition.resolveManifest,
+            normalizeParameters: definition.normalizeParameters,
+            ...(definition.checkConfig
+                ? {
+                    checkConfig: (config) => invokePluginPackage(pkg, { operation: 'check', config }),
+                }
+                : {}),
+            manifest: d.manifest,
+            handlers: {},
+            queries: Object.fromEntries(d.runtime.queries.map((name) => [
+                name,
+                (input, config, context, signal) => invokePluginPackage(pkg, { operation: 'query', name, input, config, context }, { signal }),
+            ])),
+        });
+        presentations[d.manifest.id] = {
+            packageDigest: digest,
+            uiBundle: {
+                url: `/packages/${digest}/${d.ui.entry}`,
+                digest: d.files[d.ui.entry],
+                globalName: d.ui.globalName,
+                ...(d.ui.css
+                    ? {
+                        cssUrl: `/packages/${digest}/${d.ui.css}`,
+                        cssDigest: d.files[d.ui.css],
+                    }
+                    : {}),
+            },
+        };
+    }
+    return { plugins, presentations, downloads, executionEntries };
+}

package/dist/runtime/plugin-config.d.ts

@@ -0,0 +1,4 @@
+import { type ConfigField } from '../protocol/index.js';
+export declare function fieldsConfig(fields: ConfigField[], previous: Record<string, unknown>, patch: Record<string, unknown>): {
+    [x: string]: unknown;
+};

package/dist/runtime/plugin-config.js

@@ -0,0 +1,31 @@
+import { ContractError } from '../protocol/index.js';
+export function fieldsConfig(fields, previous, patch) {
+    const declared = new Set(fields.map((field) => field.key));
+    const retained = Object.fromEntries(Object.entries(previous).filter(([key]) => declared.has(key)));
+    const config = {
+        ...Object.fromEntries(fields
+            .filter((f) => f.default !== undefined)
+            .map((f) => [f.key, f.default])),
+        ...retained,
+    };
+    for (const [key, value] of Object.entries(patch)) {
+        const field = fields.find((f) => f.key === key);
+        if (!field)
+            throw new ContractError(`未知配置字段 ${key}`);
+        if (value === null) {
+            delete config[key];
+            continue;
+        }
+        if ((['string', 'secret', 'select'].includes(field.type) &&
+            typeof value !== 'string') ||
+            (field.type === 'number' &&
+                (typeof value !== 'number' || !Number.isFinite(value))) ||
+            (field.type === 'boolean' && typeof value !== 'boolean'))
+            throw new ContractError(`${key} 类型错误`);
+        if (field.type === 'select' &&
+            !field.options?.some((o) => o.value === value))
+            throw new ContractError(`${key} 选项无效`);
+        config[key] = value;
+    }
+    return config;
+}

package/dist/runtime/store.d.ts

@@ -0,0 +1,48 @@
+import type { ExecutionRecord, ExecutionRequest } from '../protocol/index.js';
+export type ExecutionSnapshot = {
+    config: Record<string, unknown>;
+    release: string;
+    safeRetry: boolean;
+    maxAttempts: number;
+    packageEntry?: string;
+    packageDigest?: string;
+    packageEntryHash?: string;
+};
+export declare class RuntimeStore {
+    private db;
+    constructor(path: string);
+    syncDeployment(digest: string): void;
+    get revision(): number;
+    get instanceId(): string;
+    getPlugin(id: string): {
+        enabled: boolean;
+        config: Record<string, unknown>;
+        configVersion: number;
+    };
+    setPlugin(id: string, patch: {
+        enabled?: boolean;
+        config?: Record<string, unknown>;
+        expectedVersion?: number;
+    }): {
+        enabled: boolean;
+        config: Record<string, unknown>;
+        configVersion: number;
+    };
+    accept(request: ExecutionRequest, snapshot?: ExecutionSnapshot): {
+        created: boolean;
+        record: ExecutionRecord;
+    };
+    getSnapshot(id: string): ExecutionSnapshot;
+    getExecution(id: string): ExecutionRecord | undefined;
+    getRequest(id: string): ExecutionRequest;
+    update(id: string, patch: Partial<ExecutionRecord>): ExecutionRecord;
+    claim(id: string): ExecutionRecord | undefined;
+    requeue(id: string, error?: ExecutionRecord['error']): ExecutionRecord;
+    queued(pluginId?: string): Array<{
+        id: string;
+        request: ExecutionRequest;
+    }>;
+    list(limit?: number): ExecutionRecord[];
+    recover(): string[];
+    close(): void;
+}