Files
Netcatty/electron/plugins/runtime/runtimePeer.mjs
T
ryan-wong-coder 7a47187e37 feat(plugins): add isolated plugin host runtime (#2303)
* feat(plugins): add isolated plugin host runtime

* test(plugins): build runtime dependencies before tests

* fix(plugins): harden runtime lifecycle and recovery

* fix(plugins): harden runtime extension boundaries

* fix(plugins): enforce runtime integrity boundaries

* fix(plugins): await utility process exit

* fix(plugins): harden utility process containment

* fix(plugins): close runtime recovery gaps

* fix(plugins): harden runtime lifecycle boundaries
2026-07-19 08:22:17 +08:00

249 lines
8.4 KiB
JavaScript

import {
CancellationTokenSource,
DisposableStore,
PluginError,
pluginErrorToRpcError,
} from "@netcatty/plugin-sdk";
import { createMessagePortStreamEnvelope } from "@netcatty/plugin-contract";
const RPC_ERRORS = {
methodNotFound: -32601,
invalidParams: -32602,
internal: -32603,
cancelled: -32001,
unsupported: -32012,
};
function messageData(value) {
return value && typeof value === "object" && "data" in value ? value.data : value;
}
function createTransportAdapter(port) {
const listeners = new Set();
const handle = (event) => {
const value = messageData(event);
for (const listener of listeners) listener(value);
};
if (typeof port.addEventListener === "function") port.addEventListener("message", handle);
else port.on("message", handle);
port.start?.();
return {
post(message, transfer = []) {
port.postMessage(message, transfer);
},
onMessage(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
},
close() {
listeners.clear();
port.close?.();
},
};
}
function makeRpcFailure(id, code, message, data) {
return {
jsonrpc: "2.0",
id,
error: { code, message, ...(data === undefined ? {} : { data }) },
};
}
function cancelUnhandledStream(transport, message) {
const keys = Reflect.ownKeys(message);
if (keys.some((key) => typeof key !== "string" || (key !== "frame" && key !== "transfer"))) {
throw new TypeError("Plugin stream envelope contains unknown properties");
}
for (const key of keys) {
const descriptor = Object.getOwnPropertyDescriptor(message, key);
if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
throw new TypeError("Plugin stream envelope must contain enumerable data properties");
}
}
const envelope = createMessagePortStreamEnvelope(message.frame, message.transfer);
if (envelope.frame.kind !== "open") {
throw new Error(`Unknown incoming plugin stream: ${envelope.frame.streamId}`);
}
transport.post(createMessagePortStreamEnvelope({
streamId: envelope.frame.streamId,
sequence: 1,
kind: "cancel",
}));
}
function normalizeError(error) {
if (error instanceof PluginError) {
return pluginErrorToRpcError(error);
}
return { code: RPC_ERRORS.internal, message: "Plugin operation failed" };
}
function createHostClient(transport) {
let nextId = 0;
const pending = new Map();
function accept(message) {
if (!message || typeof message !== "object" || !Object.hasOwn(message, "id")) return false;
if (!Object.hasOwn(message, "result") && !Object.hasOwn(message, "error")) return false;
const request = pending.get(`${typeof message.id}:${String(message.id)}`);
if (!request) return false;
pending.delete(`${typeof message.id}:${String(message.id)}`);
if (message.error) {
request.reject(new PluginError(
message.error.data?.pluginCode ?? "unknown",
message.error.message,
message.error.data?.details,
));
} else request.resolve(message.result);
return true;
}
function request(method, params) {
const id = nextId;
nextId = nextId === Number.MAX_SAFE_INTEGER ? 0 : nextId + 1;
return new Promise((resolve, reject) => {
pending.set(`${typeof id}:${String(id)}`, { resolve, reject });
transport.post({ jsonrpc: "2.0", id, method, params });
});
}
function notify(method, params) {
transport.post({ jsonrpc: "2.0", method, params });
}
function close() {
const error = new PluginError("unavailable", "Plugin host disconnected");
for (const request of pending.values()) request.reject(error);
pending.clear();
}
return { accept, request, notify, close };
}
function assertStorageKey(key) {
if (typeof key !== "string" || key.length < 1 || key.length > 256 || key.includes("\0")) {
throw new PluginError("invalid_argument", "Plugin storage key is invalid");
}
return key;
}
function createPluginContext(config, client) {
const subscriptions = new DisposableStore();
const storage = {
get: (key) => client.request("storage.get", { key: assertStorageKey(key) })
.then((result) => result?.found ? result.value : undefined),
set: (key, value) => client.request("storage.set", { key: assertStorageKey(key), value })
.then(() => undefined),
delete: (key) => client.request("storage.delete", { key: assertStorageKey(key) })
.then(() => undefined),
keys: () => client.request("storage.keys", {}).then((result) => result?.keys ?? []),
};
const secrets = {
get: () => Promise.reject(new PluginError("unsupported", "Plugin secrets require the permission runtime")),
set: () => Promise.reject(new PluginError("unsupported", "Plugin secrets require the permission runtime")),
delete: () => Promise.reject(new PluginError("unsupported", "Plugin secrets require the permission runtime")),
};
const logger = Object.fromEntries(["debug", "info", "warn", "error"].map((level) => [
level,
(message, fields) => client.notify("log.write", {
level,
message: String(message).slice(0, 2_048),
...(fields === undefined ? {} : { fields }),
}),
]));
return {
pluginId: config.pluginId,
netcattyVersion: config.netcattyVersion,
apiVersion: config.apiVersion,
enabledFeatures: new Set(config.enabledFeatures),
subscriptions,
storage,
secrets,
logger,
};
}
export async function startPluginRuntime({ port, config, loadPlugin }) {
const transport = createTransportAdapter(port);
const client = createHostClient(transport);
const cancellation = new Map();
let plugin;
let context;
let activated = false;
let deactivated = false;
const pluginModule = await loadPlugin(config.entryUrl);
plugin = pluginModule?.default;
if (!plugin || typeof plugin.activate !== "function") {
throw new Error("Plugin entrypoint must default-export a plugin with activate(context)");
}
async function handleRequest(message) {
if (message.method === "plugin.initialize") {
if (context) throw new PluginError("failed_precondition", "Plugin is already initialized");
context = createPluginContext(config, client);
return {
pluginId: config.pluginId,
pluginVersion: config.pluginVersion,
apiVersion: config.apiVersion,
enabledFeatures: [...config.enabledFeatures],
};
}
if (message.method === "plugin.activate") {
if (!context) throw new PluginError("failed_precondition", "Plugin must be initialized first");
if (!activated) {
const disposable = await plugin.activate(context);
if (disposable && typeof disposable.dispose === "function") context.subscriptions.add(disposable);
activated = true;
}
return null;
}
if (message.method === "plugin.deactivate") {
if (!deactivated) {
deactivated = true;
await plugin.deactivate?.();
context?.subscriptions.dispose();
}
return null;
}
throw new PluginError("unsupported", `Unsupported host method: ${message.method}`);
}
const dispose = transport.onMessage((message) => {
if (message && typeof message === "object" && Object.hasOwn(message, "frame")) {
try { cancelUnhandledStream(transport, message); }
catch { transport.close(); }
return;
}
if (client.accept(message)) return;
if (!message || message.jsonrpc !== "2.0") return;
if (message.method === "$/cancelRequest") {
cancellation.get(message.params?.cancellationId)?.cancel();
return;
}
if (!Object.hasOwn(message, "id")) return;
const cancellationId = message.cancellationId;
const source = new CancellationTokenSource();
if (cancellationId) cancellation.set(cancellationId, source);
void handleRequest(message).then(
(result) => transport.post({ jsonrpc: "2.0", id: message.id, result }),
(error) => {
const rpcError = normalizeError(error);
transport.post(makeRpcFailure(message.id, rpcError.code, rpcError.message, rpcError.data));
},
).finally(() => {
if (cancellationId) cancellation.delete(cancellationId);
source.dispose();
});
});
return {
async dispose() {
dispose();
client.close();
for (const source of cancellation.values()) source.cancel();
cancellation.clear();
if (!deactivated) {
await plugin.deactivate?.();
context?.subscriptions.dispose();
}
transport.close();
},
};
}