@aiot-nexus/plugin-sdk 1.1.1 → 2.0.1

package/dev-host/plugin-host.js

@@ -0,0 +1,418 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const path = require("path");
+
+const protocolVersion = 2;
+const operationPattern = /^[a-z][A-Za-z0-9]*(?:\.[a-z][A-Za-z0-9]*){1,4}$/;
+const implementedPermissions = new Set(["businessLog", "settings"]);
+const routeGuardPermissions = new Set(["filesystem", "udp", "serial", "dialog"]);
+const port = process.parentPort;
+
+if (!port) {
+  process.stderr.write("[nexus-plugin-dev-worker] utility process parent port is unavailable.\n");
+  process.exit(1);
+}
+
+const operations = new Map();
+const pendingHostRequests = new Map();
+let initialized = false;
+let ready = false;
+let shuttingDown = false;
+let exiting = false;
+let pluginId = "";
+let pluginDirectory = "";
+let pluginDataDirectory = "";
+let manifest;
+let hostVersion = "";
+let hostApiVersion = "";
+let pluginModule;
+let requestSequence = 0;
+
+port.on("message", function handleParentMessage(event) {
+  void handleMessage(readMessageData(event));
+});
+
+process.once("uncaughtException", function handleUncaughtException(error) {
+  failProcess(errorMessage(error));
+});
+process.once("unhandledRejection", function handleUnhandledRejection(reason) {
+  failProcess(errorMessage(reason));
+});
+
+async function handleMessage(message) {
+  if (exiting || !isRecord(message) || message.protocolVersion !== protocolVersion || typeof message.type !== "string") {
+    if (!exiting) {
+      failProcess("Plugin worker RPC message is invalid.");
+    }
+    return;
+  }
+  if (message.type === "initialize") {
+    await initialize(message);
+    return;
+  }
+  if (message.type === "hostResult") {
+    handleHostResult(message);
+    return;
+  }
+  if (message.type === "invoke") {
+    await invoke(message);
+    return;
+  }
+  if (message.type === "shutdown") {
+    await shutdown(message);
+    return;
+  }
+  failProcess("Plugin worker RPC message direction is invalid.");
+}
+
+async function initialize(message) {
+  if (initialized || shuttingDown || !isWorkerRequestId(message.requestId) || !isRecord(message.payload)) {
+    failProcess("Plugin worker initialize request is invalid.");
+    return;
+  }
+  const payload = message.payload;
+  if (typeof payload.pluginId !== "string"
+    || typeof payload.pluginDirectory !== "string"
+    || typeof payload.pluginDataDirectory !== "string"
+    || !isRecord(payload.manifest)
+    || typeof payload.hostVersion !== "string"
+    || typeof payload.hostApiVersion !== "string") {
+    failProcess("Plugin worker initialize payload is invalid.");
+    return;
+  }
+  initialized = true;
+  pluginId = payload.pluginId;
+  pluginDirectory = payload.pluginDirectory;
+  pluginDataDirectory = payload.pluginDataDirectory;
+  manifest = payload.manifest;
+  hostVersion = payload.hostVersion;
+  hostApiVersion = payload.hostApiVersion;
+  try {
+    if (typeof manifest.mainEntry !== "string" || !manifest.mainEntry) {
+      throw new Error("Plugin manifest does not declare mainEntry.");
+    }
+    const mainEntryPath = path.resolve(pluginDirectory, manifest.mainEntry);
+    pluginModule = require(mainEntryPath);
+    const activate = typeof pluginModule.activate === "function"
+      ? pluginModule.activate
+      : pluginModule.default && typeof pluginModule.default.activate === "function"
+        ? pluginModule.default.activate
+        : undefined;
+    if (activate) {
+      await activate({
+        pluginId,
+        pluginDirectory,
+        manifest,
+        host: createHostApi()
+      });
+    }
+    if (exiting || shuttingDown) {
+      return;
+    }
+    ready = true;
+    post({
+      protocolVersion,
+      type: "ready",
+      requestId: message.requestId,
+      payload: {
+        operations: Array.from(operations.keys()),
+        activatedAtUtc: new Date().toISOString()
+      }
+    });
+  } catch (error) {
+    failProcess(errorMessage(error));
+  }
+}
+
+async function invoke(message) {
+  if (!isWorkerRequestId(message.requestId) || !isRecord(message.payload)) {
+    failProcess("Plugin worker invoke request is invalid.");
+    return;
+  }
+  if (!ready || shuttingDown) {
+    sendResult(message.requestId, fail("PluginWorkerNotReady", "Plugin worker is not ready."));
+    return;
+  }
+  const payload = message.payload;
+  if (typeof payload.operation !== "string" || !isSafeOperationName(payload.operation)) {
+    sendResult(message.requestId, fail("InvalidRequest", "Plugin renderer operation name is invalid."));
+    return;
+  }
+  const handler = operations.get(payload.operation);
+  if (!handler) {
+    sendResult(message.requestId, fail("NotFound", "Plugin renderer operation was not registered.", { operation: payload.operation }));
+    return;
+  }
+  try {
+    const value = await handler({
+      pluginId,
+      surface: payload.surface,
+      contributionId: payload.contributionId,
+      operation: payload.operation,
+      input: isRecord(payload.input) ? payload.input : undefined
+    });
+    sendResult(message.requestId, normalizeResult(value));
+  } catch (error) {
+    sendResult(message.requestId, fail("UnexpectedFailure", "Plugin renderer operation failed.", {
+      pluginId,
+      operation: payload.operation,
+      message: errorMessage(error)
+    }));
+  }
+}
+
+async function shutdown(message) {
+  if (shuttingDown || !isWorkerRequestId(message.requestId)) {
+    return;
+  }
+  shuttingDown = true;
+  try {
+    const deactivate = pluginModule && (typeof pluginModule.deactivate === "function"
+      ? pluginModule.deactivate
+      : pluginModule.default && typeof pluginModule.default.deactivate === "function"
+        ? pluginModule.default.deactivate
+        : undefined);
+    if (deactivate) {
+      await deactivate(isRecord(message.payload) && typeof message.payload.reason === "string" ? message.payload.reason : "quit");
+    }
+    sendResult(message.requestId, ok(true));
+  } catch (error) {
+    sendResult(message.requestId, fail("UnexpectedFailure", "Plugin shutdown failed.", errorMessage(error)));
+  }
+  disposePendingRequests();
+  setImmediate(function exitAfterShutdown() {
+    exiting = true;
+    process.exit(0);
+  });
+}
+
+function createHostApi() {
+  function unsupported(permission) {
+    const target = {
+      permission,
+      supportState: permissionSupportState(permission),
+      describe: function describe() {
+        return requestHost("getCapabilityStatus", { permission });
+      },
+      unsupported: function unsupportedOperation(operation) {
+        return requestHost("unsupportedCapability", {
+          permission,
+          ...(typeof operation === "string" ? { operation } : {})
+        });
+      }
+    };
+    return new Proxy(target, {
+      get: function get(apiTarget, property) {
+        if (property in apiTarget) {
+          return Reflect.get(apiTarget, property);
+        }
+        if (typeof property === "symbol" || property === "then") {
+          return undefined;
+        }
+        return function callUnsupportedOperation() {
+          return apiTarget.unsupported(property);
+        };
+      }
+    });
+  }
+
+  return {
+    hostVersion,
+    hostApiVersion,
+    pluginId,
+    pluginDataDirectory,
+    hasPermission: function hasPermission(permission) {
+      return Array.isArray(manifest.permissions) && manifest.permissions.includes(permission);
+    },
+    registerRendererMethod: async function registerRendererMethod(name, handler) {
+      if (!isSafeOperationName(name) || typeof handler !== "function") {
+        return fail("InvalidRequest", "Plugin renderer operation registration is invalid.");
+      }
+      if (operations.has(name)) {
+        return fail("InvalidRequest", "Plugin renderer operation is already registered.");
+      }
+      operations.set(name, handler);
+      return ok(true);
+    },
+    getCapabilityStatus: function getCapabilityStatus(permission) {
+      return requestHost("getCapabilityStatus", { permission: typeof permission === "string" ? permission : String(permission) });
+    },
+    unsupportedCapability: function unsupportedCapability(permission, operation) {
+      return requestHost("unsupportedCapability", {
+        permission: typeof permission === "string" ? permission : String(permission),
+        ...(typeof operation === "string" ? { operation } : {})
+      });
+    },
+    log: function log(level, message, exception) {
+      return requestHost("log", { level, message, ...(exception ? { exception } : {}) });
+    },
+    getSettings: function getSettings() {
+      return requestHost("getSettings");
+    },
+    updateSettings: function updateSettings(values) {
+      return requestHost("updateSettings", { values: sanitizeJsonValue(values) });
+    },
+    filesystem: unsupported("filesystem"),
+    udp: unsupported("udp"),
+    serial: unsupported("serial"),
+    dialog: unsupported("dialog"),
+    externalProcess: unsupported("externalProcess")
+  };
+}
+
+function requestHost(method, params) {
+  if (exiting || shuttingDown) {
+    return Promise.resolve(fail("PluginWorkerExited", "Plugin worker is stopping."));
+  }
+  const requestId = pluginId + "-host-" + String(++requestSequence);
+  return new Promise(function waitForHostResult(resolve, reject) {
+    pendingHostRequests.set(requestId, { resolve, reject });
+    try {
+      post({
+        protocolVersion,
+        type: "hostRequest",
+        requestId,
+        payload: { method, ...(params ? { params: sanitizeJsonValue(params) } : {}) }
+      });
+    } catch (error) {
+      pendingHostRequests.delete(requestId);
+      reject(error);
+    }
+  });
+}
+
+function handleHostResult(message) {
+  if (!isWorkerRequestId(message.requestId) || !isNexusResult(message.result)) {
+    failProcess("Plugin worker Host API result is invalid.");
+    return;
+  }
+  const pending = pendingHostRequests.get(message.requestId);
+  if (!pending) {
+    return;
+  }
+  pendingHostRequests.delete(message.requestId);
+  pending.resolve(message.result);
+}
+
+function sendResult(requestId, result) {
+  post({ protocolVersion, type: "result", requestId, result: normalizeResult(result) });
+}
+
+function post(message) {
+  port.postMessage(message);
+}
+
+function failProcess(message) {
+  if (exiting) {
+    return;
+  }
+  exiting = true;
+  try {
+    post({ protocolVersion, type: "fatal", payload: { message: message || "Plugin worker failed." } });
+  } catch {
+    // The parent may already be gone.
+  }
+  disposePendingRequests();
+  setImmediate(function exitAfterFatal() {
+    process.exit(1);
+  });
+}
+
+function disposePendingRequests() {
+  const result = fail("PluginWorkerExited", "Plugin worker stopped.");
+  for (const pending of pendingHostRequests.values()) {
+    pending.resolve(result);
+  }
+  pendingHostRequests.clear();
+}
+
+function normalizeResult(value) {
+  if (isNexusResult(value)) {
+    if (value.ok) {
+      return ok(sanitizeJsonValue(value.value));
+    }
+    return fail(value.error.code, value.error.message, value.error.details === undefined ? undefined : sanitizeJsonValue(value.error.details));
+  }
+  return ok(sanitizeJsonValue(value));
+}
+
+function ok(value) {
+  return { ok: true, value: sanitizeJsonValue(value) };
+}
+
+function fail(code, message, details) {
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      ...(details === undefined ? {} : { details: sanitizeJsonValue(details) })
+    }
+  };
+}
+
+function isNexusResult(value) {
+  if (!isRecord(value) || typeof value.ok !== "boolean") {
+    return false;
+  }
+  return value.ok
+    ? Object.prototype.hasOwnProperty.call(value, "value")
+    : isRecord(value.error) && typeof value.error.code === "string" && typeof value.error.message === "string";
+}
+
+function isWorkerRequestId(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= 128
+    && /^[A-Za-z0-9._:-]+$/.test(value);
+}
+
+function isSafeOperationName(value) {
+  return typeof value === "string"
+    && value.length <= 80
+    && operationPattern.test(value)
+    && value.split(".").every(function isSafePart(part) {
+      return part !== "constructor" && part !== "prototype" && part !== "__proto__";
+    });
+}
+
+function permissionSupportState(permission) {
+  if (implementedPermissions.has(permission)) {
+    return "implemented";
+  }
+  if (routeGuardPermissions.has(permission)) {
+    return "routeGuard";
+  }
+  return "reserved";
+}
+
+function sanitizeJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeJsonValue);
+  }
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value)
+      .filter(function removeUndefined(entry) { return entry[1] !== undefined; })
+      .map(function sanitizeEntry(entry) { return [entry[0], sanitizeJsonValue(entry[1])]; }));
+  }
+  return null;
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readMessageData(event) {
+  return isRecord(event) && Object.prototype.hasOwnProperty.call(event, "data") ? event.data : event;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/dist/.generated/plugin-framework-version.d.ts

@@ -1,4 +1,4 @@
-export declare const PLUGIN_FRAMEWORK_VERSION = "1.0.0";
+export declare const PLUGIN_FRAMEWORK_VERSION = "2.0.0";
 export declare const PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
 export declare const PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
 export interface ParsedPluginVersion {

package/dist/.generated/plugin-framework-version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPluginFrameworkVersionCompatible = exports.comparePluginVersions = exports.parsePluginCompatibleVersion = exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = exports.PLUGIN_MANIFEST_SCHEMA_VERSION = exports.PLUGIN_FRAMEWORK_VERSION = void 0;
-exports.PLUGIN_FRAMEWORK_VERSION = "1.0.0";
+exports.PLUGIN_FRAMEWORK_VERSION = "2.0.0";
 exports.PLUGIN_MANIFEST_SCHEMA_VERSION = 1;
 exports.PLUGIN_COMPATIBLE_VERSION_PATTERN = "^(0|[1-9][0-9]*)(\\.(0|[1-9][0-9]*))?(\\.(0|[1-9][0-9]*))?$";
 function parsePluginCompatibleVersion(value) {

package/dist/src/cli/run.js

@@ -126,7 +126,7 @@ function runNexusDev(args, io) {
         const inspector = parseInspectorOption(option);
         if (inspector) {
             if (options.inspectorMode) {
-                return usageError(io, "Only one main-process inspector option can be used.");
+                return usageError(io, "Only one plugin worker inspector option can be used.");
             }
             const key = "--" + inspector.mode;
             if (seen.has(key)) {
@@ -304,7 +304,7 @@ function runDev(args, io) {
         const inspector = parseInspectorOption(option);
         if (inspector) {
             if (options.inspectorMode) {
-                return usageError(io, "Only one main-process inspector option can be used.");
+                return usageError(io, "Only one plugin worker inspector option can be used.");
             }
             const key = "--" + inspector.mode;
             if (seen.has(key)) {

package/dist/src/dev.js

@@ -52,14 +52,14 @@ function runPluginDev(options, io) {
         + "\nContribution: " + target.surface + ":" + target.contributionId
         + "\nSimulated Nexus application version: " + target.hostVersion);
     if (options.inspectorMode) {
-        io.stdout("Main process debugger: " + options.inspectorMode
+        io.stdout("Plugin worker debugger: " + options.inspectorMode
             + " on 127.0.0.1:" + String(options.inspectorPort || 9229));
     }
     const electronArgs = [];
+    electronArgs.push(target.devHostMainPath, "--plugin-package=" + target.packageDirectory, "--project-directory=" + target.projectDirectory, "--surface=" + target.surface, "--contribution-id=" + target.contributionId, "--language=" + target.language, "--theme=" + target.themeMode, "--host-version=" + target.hostVersion);
     if (options.inspectorMode) {
-        electronArgs.push("--" + options.inspectorMode + "=" + String(options.inspectorPort || 9229));
+        electronArgs.push("--worker-inspector=" + options.inspectorMode + ":" + String(options.inspectorPort || 9229));
     }
-    electronArgs.push(target.devHostMainPath, "--plugin-package=" + target.packageDirectory, "--project-directory=" + target.projectDirectory, "--surface=" + target.surface, "--contribution-id=" + target.contributionId, "--language=" + target.language, "--theme=" + target.themeMode, "--host-version=" + target.hostVersion);
     if (!options.openDevTools) {
         electronArgs.push("--no-devtools");
     }

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 import pluginManifestSchema from "../.generated/plugin-manifest.schema.json";
-export declare const PLUGIN_SDK_VERSION = "1.1.1";
+export declare const PLUGIN_SDK_VERSION = "2.0.1";
 export { pluginManifestSchema };
 export * from "../.generated/plugin-framework-version";
 export * from "./types";

package/dist/src/index.js

@@ -20,7 +20,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluginManifestSchema = exports.PLUGIN_SDK_VERSION = void 0;
 const plugin_manifest_schema_json_1 = __importDefault(require("../.generated/plugin-manifest.schema.json"));
 exports.pluginManifestSchema = plugin_manifest_schema_json_1.default;
-exports.PLUGIN_SDK_VERSION = "1.1.1";
+exports.PLUGIN_SDK_VERSION = "2.0.1";
 __exportStar(require("../.generated/plugin-framework-version"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./browser/frame-client"), exports);

package/dist/src/nexus-dev-control.d.ts

@@ -1,8 +1,7 @@
-export type NexusDevUpdateType = "rendererUpdated" | "manifestUpdated";
+export type NexusDevUpdateType = "rendererUpdated" | "manifestUpdated" | "packageUpdatePreparing" | "packageUpdated";
 export interface NexusDevUpdateResult {
     ok: boolean;
     message: string;
-    requiresRestart?: boolean;
 }
 export declare class NexusDevControlServer {
     readonly token: string;

package/dist/src/nexus-dev-control.js

@@ -30,7 +30,7 @@ const net = __importStar(require("net"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const dev_1 = require("./dev");
-const protocolVersion = 1;
+const protocolVersion = 2;
 const maximumMessageBytes = 64 * 1024;
 const requestTimeoutMs = 10000;
 class NexusDevControlServer {
@@ -114,7 +114,7 @@ class NexusDevControlServer {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pendingShutdowns.delete(requestId);
-                reject(new dev_1.PluginDevError("Nexus timed out while accepting the plugin development restart."));
+                reject(new dev_1.PluginDevError("Nexus timed out while accepting the development host shutdown."));
             }, requestTimeoutMs);
             this.pendingShutdowns.set(requestId, { resolve, reject, timer });
             this.socket?.write(JSON.stringify({ type: "shutdown", requestId }) + "\n");
@@ -239,8 +239,7 @@ class NexusDevControlServer {
             clearTimeout(pending.timer);
             pending.resolve({
                 ok: value.ok,
-                message: value.message,
-                ...(value.requiresRestart ? { requiresRestart: true } : {})
+                message: value.message
             });
             return true;
         }
@@ -342,9 +341,6 @@ function createPipePath() {
         : path.join(os.tmpdir(), "nexus-plugin-dev-" + suffix + ".sock");
 }
 function verifyHelloProof(value, token) {
-    if (value.proof === undefined) {
-        return true;
-    }
     const expected = crypto.createHmac("sha256", token)
         .update(helloProofPayload(value.protocolVersion, value.pid, value.nonce), "utf8")
         .digest("hex");
@@ -363,7 +359,7 @@ function isHelloMessage(value) {
         && value.protocolVersion === protocolVersion
         && typeof value.pid === "number" && Number.isSafeInteger(value.pid) && value.pid > 0
         && typeof value.nonce === "string" && /^[a-f0-9]{32}$/i.test(value.nonce)
-        && (value.proof === undefined || (typeof value.proof === "string" && /^[a-f0-9]{64}$/i.test(value.proof)));
+        && typeof value.proof === "string" && /^[a-f0-9]{64}$/i.test(value.proof);
 }
 function isAuthenticatedMessage(value) {
     return isRecord(value)
@@ -375,11 +371,11 @@ function isUpdateResult(value) {
     return isRecord(value)
         && value.type === "updateResult"
         && typeof value.requestId === "string"
-        && (value.updateType === "rendererUpdated" || value.updateType === "manifestUpdated")
+        && (value.updateType === "rendererUpdated" || value.updateType === "manifestUpdated" || value.updateType === "packageUpdatePreparing" || value.updateType === "packageUpdated")
         && typeof value.pluginId === "string"
         && typeof value.ok === "boolean"
         && typeof value.message === "string"
-        && (value.requiresRestart === undefined || typeof value.requiresRestart === "boolean");
+        && Object.keys(value).every((key) => key === "type" || key === "requestId" || key === "updateType" || key === "pluginId" || key === "ok" || key === "message");
 }
 function isShutdownResult(value) {
     return isRecord(value)

package/dist/src/nexus-dev.d.ts

@@ -11,10 +11,13 @@ export interface PluginNexusDevIo {
     stdout(message: string): void;
     stderr(message: string): void;
 }
-export type PluginSourceChangeKind = "renderer" | "manifest" | "restart";
+export type PluginSourceChangeKind = "renderer" | "manifest" | "package";
 export declare function runPluginNexusDev(options: PluginNexusDevOptions, io: PluginNexusDevIo): Promise<number>;
+export declare function recoverPreparedPluginPackageUpdate(transaction: {
+    rollback(): void;
+} | undefined, pluginId: string, control: Pick<NexusDevControlServer, "sendUpdate">): Promise<void>;
 export declare function classifyPluginSourceChange(projectDirectory: string, changedPath: string): PluginSourceChangeKind | undefined;
-export declare function manifestChangeRequiresRestart(previous: PluginManifest, next: PluginManifest): boolean;
+export declare function manifestChangeRequiresPackageUpdate(previous: PluginManifest, next: PluginManifest): boolean;
 export declare function mergePluginSourceChange(current: PluginSourceChangeKind | undefined, incoming: PluginSourceChangeKind): PluginSourceChangeKind;
 export declare function createNexusHostArguments(control: Pick<NexusDevControlServer, "pipePath" | "token">, target: PluginDebugTarget, options: Pick<PluginNexusDevOptions, "openDevTools" | "inspectorMode" | "inspectorPort">): string[];
 export declare function isRetryablePluginDeploymentError(error: unknown): boolean;