@skillcdn/console 0.4.1 → 0.4.3

package/src/plugin/definition-error.ts

@@ -0,0 +1,19 @@
+/**
+ * What `definePlugin` and its definers throw when a definition is not one the console can hold: a
+ * name that is not a key, a command named as a subcommand, more of something than the bound. It
+ * is thrown when the server module loads, so that a plugin's own tests and `console-plugin check`
+ * meet it before any console does; `problems` names every one found.
+ */
+export class PluginDefinitionError extends Error {
+  readonly problems: readonly string[];
+
+  constructor(problems: readonly string[]) {
+    super(
+      problems.length === 1
+        ? `the plugin's definition is invalid: ${problems[0]}`
+        : `the plugin's definition is invalid:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`,
+    );
+    this.name = "PluginDefinitionError";
+    this.problems = problems;
+  }
+}

package/src/plugin/limits.ts

@@ -0,0 +1,70 @@
+// How much a plugin may ask of a console (docs/specs/plugins.md, "Limits and refusals"): the
+// bounds the manifest's schema, the definers, the host and the pages hold a plugin to. One source,
+// so that `console-plugin check` says before an administrator finds out.
+
+/** A plugin's name in one language, its description, and the sentence agents read with the rules. */
+export const MAX_PLUGIN_NAME_LENGTH = 40;
+export const MAX_PLUGIN_DESCRIPTION_LENGTH = 200;
+export const MAX_PLUGIN_AGENT_NOTE_LENGTH = 200;
+/** A plugin's key, a role's, a page's, a widget's, a setting's, a collection's, a command's: `^[a-z][a-z0-9-]{1,31}$`. */
+export const MAX_PLUGIN_KEY_LENGTH = 32;
+/** How many roles, settings, pages and widgets one manifest declares. */
+export const MAX_PLUGIN_ROLES = 10;
+export const MAX_PLUGIN_SETTINGS = 50;
+export const MAX_PLUGIN_PAGES = 12;
+export const MAX_PLUGIN_WIDGETS = 4;
+/** How many collections, commands and queries together, endpoints, and indexes of one collection a server module defines. */
+export const MAX_PLUGIN_COLLECTIONS = 50;
+export const MAX_PLUGIN_OPERATIONS = 100;
+export const MAX_PLUGIN_ENDPOINTS = 20;
+export const MAX_PLUGIN_INDEXES = 8;
+/** One line about a command, a query, a job or an argument, as help prints it. */
+export const MAX_PLUGIN_ABOUT_LENGTH = 200;
+/** The options of an `enum` setting or argument. */
+export const MAX_PLUGIN_OPTIONS = 50;
+/** A record, how many a plugin keeps, and how many versions one record keeps. */
+export const MAX_PLUGIN_RECORD_BYTES = 64 * 1024;
+export const MAX_PLUGIN_RECORDS = 100_000;
+export const MAX_PLUGIN_RECORD_VERSIONS = 100;
+/** A message between the host and the parent, a query's answer, an endpoint's answer. */
+export const MAX_PLUGIN_MESSAGE_BYTES = 4 * 1024 * 1024;
+/** What an endpoint takes in. */
+export const MAX_PLUGIN_ENDPOINT_BODY_BYTES = 1024 * 1024;
+/** The words of one command line sent to `invoke`, and the characters of one word. */
+export const MAX_PLUGIN_ARGV_WORDS = 200;
+export const MAX_PLUGIN_ARGV_WORD_LENGTH = 50_000;
+/** The files one command takes at once. */
+export const MAX_PLUGIN_COMMAND_FILES = 20;
+/** An event of the plugin's own, how many are kept, and for how long. */
+export const MAX_PLUGIN_EVENT_BYTES = 16 * 1024;
+export const PLUGIN_EVENTS_KEPT = 100_000;
+export const PLUGIN_EVENT_DAYS = 90;
+/** How many records one page of a list carries at most. */
+export const PLUGIN_LIST_LIMIT = 200;
+/** How long plugin code may run: a command; a query or an endpoint; a hook; a job; `onEnable`, `onDisable` and an upgrade. */
+export const PLUGIN_COMMAND_MS = 30_000;
+export const PLUGIN_QUERY_MS = 10_000;
+export const PLUGIN_ENDPOINT_MS = 10_000;
+export const PLUGIN_HOOK_MS = 30_000;
+export const PLUGIN_JOB_MS = 5 * 60_000;
+export const PLUGIN_LIFECYCLE_MS = 10 * 60_000;
+/** A job runs no more often than this. */
+export const MIN_PLUGIN_JOB_INTERVAL_MS = 5 * 60_000;
+/** Outbound requests a minute per plugin, the bytes of an answer, and its time. */
+export const PLUGIN_OUTBOUND_PER_MINUTE = 60;
+export const MAX_PLUGIN_OUTBOUND_BYTES = 10 * 1024 * 1024;
+export const PLUGIN_OUTBOUND_MS = 10_000;
+/** Webhook requests a minute per plugin. */
+export const PLUGIN_WEBHOOKS_PER_MINUTE = 600;
+/** Lines `ctx.log` writes a minute. */
+export const PLUGIN_LOG_LINES_PER_MINUTE = 100;
+/** SQL, with `storage:sql`: a statement's time, a result's rows, the connections of the plugin's role. */
+export const PLUGIN_SQL_STATEMENT_MS = 10_000;
+export const MAX_PLUGIN_SQL_ROWS = 10_000;
+export const PLUGIN_SQL_CONNECTIONS = 4;
+/** The memory a plugin's thread may hold, in megabytes, where the deployment says nothing. */
+export const DEFAULT_PLUGIN_MEMORY_MB = 256;
+/** How tall a widget's frame may grow, in pixels. */
+export const MAX_PLUGIN_WIDGET_HEIGHT = 480;
+/** How many retries a hook gets before its event is skipped with a `plugin.failed` event. */
+export const PLUGIN_HOOK_RETRIES = 5;

package/src/plugin/load-worker.ts

@@ -0,0 +1,50 @@
+// The thread a server module is loaded in to be described (docs/specs/plugins.md, "The host" and
+// "Authoring"): hardened first, then the module imported and its default export described as
+// JSON for the parent. `console-plugin check` runs this; the host loads plugins the same way and
+// then keeps the thread. Nothing of the console is reachable from here: no database, no
+// configuration, an empty environment.
+import * as moduleApi from "node:module";
+import { pathToFileURL } from "node:url";
+import { parentPort, workerData } from "node:worker_threads";
+import { describePlugin, isPluginDefinition } from "./define.js";
+import { PluginDefinitionError } from "./definition-error.js";
+import { hardenThread } from "./sandbox.js";
+
+export interface LoadOutcome {
+  readonly ok: boolean;
+  readonly description?: unknown;
+  readonly error?: string;
+  readonly problems?: readonly string[];
+}
+
+function errorText(error: unknown): { error: string; problems?: readonly string[] } {
+  if (error instanceof PluginDefinitionError) {
+    return { error: "the definition is invalid", problems: error.problems };
+  }
+  if (error instanceof Error) {
+    const code = (error as { code?: unknown }).code;
+    return { error: typeof code === "string" ? `${code}: ${error.message}` : error.message };
+  }
+  return { error: String(error) };
+}
+
+const { file } = workerData as { file: string };
+
+let outcome: LoadOutcome;
+try {
+  if (typeof moduleApi.registerHooks !== "function") {
+    throw new Error(
+      "the host needs Node.js 24 or newer, which has module hooks that run in a thread",
+    );
+  }
+  hardenThread(moduleApi);
+  const loaded = (await import(pathToFileURL(file).href)) as { default?: unknown };
+  if (!isPluginDefinition(loaded.default)) {
+    outcome = { ok: false, error: "the default export is not what definePlugin({...}) yields" };
+  } else {
+    outcome = { ok: true, description: describePlugin(loaded.default) };
+  }
+} catch (error) {
+  outcome = { ok: false, ...errorText(error) };
+}
+parentPort?.postMessage(outcome);

package/src/plugin/load.ts

@@ -0,0 +1,82 @@
+// Loads a plugin's server module in a hardened worker thread and answers its description, or why
+// it did not load. What `console-plugin check` does to a package; the host does the same before
+// keeping the thread. Node only.
+import { Worker } from "node:worker_threads";
+import type { PluginDescription } from "./define.js";
+import { DEFAULT_PLUGIN_MEMORY_MB } from "./limits.js";
+
+export type ServerLoad =
+  | { readonly ok: true; readonly description: PluginDescription }
+  | { readonly ok: false; readonly error: string; readonly problems: readonly string[] };
+
+export interface LoadOptions {
+  /** How long the module gets to load; ten seconds unless said. */
+  readonly timeoutMs?: number;
+  /** The memory the thread may hold, in megabytes. */
+  readonly memoryMb?: number;
+}
+
+const DEFAULT_LOAD_MS = 10_000;
+
+/** The description of the server module at `file`, loaded in a thread of its own under the host's hardening. */
+export function loadServerModule(file: string, options: LoadOptions = {}): Promise<ServerLoad> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_LOAD_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (load: ServerLoad) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(load);
+      }
+    };
+    const worker = new Worker(new URL("./load-worker.js", import.meta.url), {
+      workerData: { file },
+      env: {},
+      resourceLimits: { maxOldGenerationSizeMb: options.memoryMb ?? DEFAULT_PLUGIN_MEMORY_MB },
+      stdout: true,
+      stderr: true,
+    });
+    // What the module prints while loading goes nowhere: the check speaks for itself.
+    worker.stdout.resume();
+    worker.stderr.resume();
+    const timer = setTimeout(() => {
+      settle({
+        ok: false,
+        error: `the server module did not load within ${timeoutMs} ms`,
+        problems: [],
+      });
+      void worker.terminate();
+    }, timeoutMs);
+    worker.on(
+      "message",
+      (outcome: {
+        ok: boolean;
+        description?: PluginDescription;
+        error?: string;
+        problems?: readonly string[];
+      }) => {
+        if (outcome.ok && outcome.description !== undefined) {
+          settle({ ok: true, description: outcome.description });
+        } else {
+          settle({
+            ok: false,
+            error: outcome.error ?? "the server module did not load",
+            problems: outcome.problems ?? [],
+          });
+        }
+        void worker.terminate();
+      },
+    );
+    worker.on("error", (error) => {
+      settle({ ok: false, error: error.message, problems: [] });
+    });
+    worker.on("exit", (code) => {
+      settle({
+        ok: false,
+        error: `the server module's thread ended with ${code} before describing it`,
+        problems: [],
+      });
+    });
+  });
+}