Add checkEnabled and rename plugin loading files

plugins.checkEnabled(name) tells if a plugin is in the load list.
#plugin_module is renamed to #import_plugin. loadPluginMigrations moves
into PluginLoader.ts, leaving plugin_loader.ts with plugin discovery and
details, so it is renamed to plugin_info.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-11-20 22:17:12 +00:00
1 parent 68c5ea82e7
commit 47c84fc289
12 files changed
+118 -101

No files matched your search

+2 -1
View File
@@ -239,7 +239,8 @@ If the plugin is already loaded it resolves right away.
If the plugin is not installed, has load_plugin set to false, is disabled by recovery mode, or fails to load, it resolves to undefined right away.
If it times out it resolves to undefined.
In both cases a warning naming both plugins is logged.
`plugins.checkInstalled(name)` tells if a plugin is installed, use it to avoid the warning for optional plugins.
`plugins.checkInstalled(name)` tells if a plugin is installed, and `plugins.checkEnabled(name)` tells if it is being loaded alongside yours.
Use `checkEnabled` to avoid the warning for optional plugins.
Startup does not continue until every entrypoint has returned.
Two plugins awaiting each other in their entrypoints hold up startup until one of them times out.
+1 -2
View File
@@ -127,8 +127,7 @@ async function loadPlugins(pluginList: Map<string, string>, hooks: CtlHooks) {
exportName: "CtlPlugin",
baseClass: BaseCtlPlugin,
});
const ctlPlugins = new Set(loaded.keys());
return ctlPlugins;
return new Set(loaded.keys());
}
interface CtlArguments {
+1 -1
View File
@@ -23,7 +23,7 @@ export * from "./src/logging_utils.js";
export * from "./src/lua_tools.js";
export * from "./src/permissions.js";
export * from "./src/plugin.js";
export * from "./src/plugin_loader.js";
export * from "./src/plugin_info.js";
export * from "./src/PluginLoader.js";
export * from "./src/prometheus.js";
export * from "./src/schema.js";
+4 -4
View File
@@ -38,12 +38,12 @@
},
"import": "./src/zlib_sync.browser.ts"
},
"#plugin_module": {
"#import_plugin": {
"node": {
"types": "./src/plugin_module.node.ts",
"default": "./dist/node/src/plugin_module.node.js"
"types": "./src/import_plugin.node.ts",
"default": "./dist/node/src/import_plugin.node.js"
},
"import": "./src/plugin_module.browser.ts"
"import": "./src/import_plugin.browser.ts"
},
"#is_deep_strict_equal": {
"node": {
+45 -7
View File
@@ -1,8 +1,13 @@
// Shared by node and the web interface, node specifics go in #plugin_module
import importPluginModule from "#plugin_module";
// Shared by node and the web interface, node specifics go in #import_plugin
import importPlugin from "#import_plugin";
import { Config } from "./config/classes.js";
import { ControllerConfig, HostConfig, InstanceConfig } from "./config/definitions.js";
import Role from "./data/Role.js";
import { PluginError } from "./errors.js";
import type { Logger } from "./logging.js";
import type { PluginClass, PluginDeclaration, PluginLoadContext, PluginRegistry, PluginType } from "./plugin.js";
import { logger, type Logger } from "./logging.js";
import type {
MigrationHooks, PluginClass, PluginDeclaration, PluginLoadContext, PluginNodeEnvInfo, PluginRegistry, PluginType,
} from "./plugin.js";
type Waiter = {
resolve: (api: unknown) => void,
@@ -19,7 +24,7 @@ export type PluginLoadOptions<Context extends object, Info extends PluginDeclara
logger: Logger,
/** All installed plugins, used by checkInstalled */
installed: Info[],
/** Plugins to load */
/** Plugins to load, used by checkEnabled */
load: Info[],
/** Name of the deprecated class export, class exports are not accepted if unset */
exportName?: string,
@@ -43,6 +48,7 @@ export class PluginLoader<Context extends object, Info extends PluginDeclaration
private _apis = new Map<string, unknown>();
private _waiters = new Map<string, Waiter[]>();
private _installed: Set<string>;
private _enabled: Set<string>;
/** Plugins still loading */
private _pending: Set<string>;
@@ -50,7 +56,8 @@ export class PluginLoader<Context extends object, Info extends PluginDeclaration
private _options: PluginLoadOptions<Context, Info>,
) {
this._installed = new Set(_options.installed.map(pluginInfo => pluginInfo.name));
this._pending = new Set(_options.load.map(pluginInfo => pluginInfo.name));
this._enabled = new Set(_options.load.map(pluginInfo => pluginInfo.name));
this._pending = new Set(this._enabled);
}
/**
@@ -118,7 +125,7 @@ export class PluginLoader<Context extends object, Info extends PluginDeclaration
};
try {
const module = await importPluginModule(pluginInfo, entrypoint);
const module = await importPlugin(pluginInfo, entrypoint);
if (typeof module.default === "function") {
return await module.default(pluginContext) as unknown;
}
@@ -145,6 +152,7 @@ export class PluginLoader<Context extends object, Info extends PluginDeclaration
return {
waitFor: (name, timeoutMs) => this._waitFor(waiter, name, timeoutMs),
checkInstalled: name => this._installed.has(name),
checkEnabled: name => this._enabled.has(name),
};
}
@@ -224,3 +232,33 @@ async function loadPluginClass(
return plugin;
}
/**
* Load the migration entrypoints of plugins
*
* Must be called before configs and roles are loaded for the migrations
* to run on them. Loaded for every plugin, including those disabled with
* load_plugin. Also registers the plugin versions written to each config
* after the migrations run.
*
* @param pluginInfos - Plugins to load migrations for.
*/
export async function loadPluginMigrations(pluginInfos: PluginNodeEnvInfo[]) {
const hooks: MigrationHooks = {
controllerConfig: ControllerConfig.pluginMigrations,
hostConfig: HostConfig.pluginMigrations,
instanceConfig: InstanceConfig.pluginMigrations,
role: Role.pluginMigrations,
};
for (const pluginInfo of pluginInfos) {
Config.pluginVersions.set(pluginInfo.name, pluginInfo.version);
}
await PluginLoader.load({
type: "migration",
context: { hooks },
logger,
installed: pluginInfos,
load: pluginInfos,
});
}
@@ -1,6 +1,6 @@
import type { PluginDeclaration, PluginWebEnvInfo } from "./plugin";
export default async function importPluginModule(
export default async function importPlugin(
pluginInfo: PluginDeclaration, entrypoint: string
): Promise<Record<string, any>> {
return await (pluginInfo as PluginWebEnvInfo).container.get(entrypoint);
@@ -2,7 +2,7 @@ import path from "node:path";
import { pathToFileURL } from "node:url";
import type { PluginDeclaration, PluginNodeEnvInfo } from "./plugin.js";
export default async function importPluginModule(
export default async function importPlugin(
pluginInfo: PluginDeclaration, entrypoint: string
): Promise<Record<string, any>> {
const packagePath = (pluginInfo as PluginNodeEnvInfo).packagePath;
+2
View File
@@ -156,6 +156,8 @@ export interface PluginRegistry {
waitFor<T = unknown>(name: string, timeoutMs?: number): Promise<T | undefined>;
/** Check if a plugin is installed, it may still be disabled */
checkInstalled(name: string): boolean;
/** Check if a plugin is being loaded alongside this one */
checkEnabled(name: string): boolean;
}
export type PluginLoadContext<
@@ -1,7 +1,7 @@
/**
* Helpers for loading plugins in Node.js
* @module lib/plugin_loader
* Helpers for finding installed plugins and reading their info in Node.js
* @module lib/plugin_info
*/
import path from "path";
import fs from "node:fs/promises";
@@ -9,10 +9,6 @@ import { fileURLToPath, pathToFileURL } from "node:url";
import * as libErrors from "./errors.js";
import * as libPlugin from "./plugin.js";
import { logger } from "./logging.js";
import { PluginLoader } from "./PluginLoader.js";
import { Config } from "./config/classes.js";
import { ControllerConfig, HostConfig, InstanceConfig } from "./config/definitions.js";
import Role from "./data/Role.js";
import { PluginDetails } from "./data/messages_plugin.js";
import {
discoverNpmPluginPackages, findNonRegistryDirs, installedDependencies, readPackageJson, realDir, resolvePackagePath,
@@ -196,33 +192,3 @@ export async function listPluginDetails(
return plugins;
}
/**
* Load the migration entrypoints of plugins
*
* Must be called before configs and roles are loaded for the migrations
* to run on them. Loaded for every plugin, including those disabled with
* load_plugin. Also registers the plugin versions written to each config
* after the migrations run.
*
* @param pluginInfos - Plugins to load migrations for.
*/
export async function loadPluginMigrations(pluginInfos: libPlugin.PluginNodeEnvInfo[]) {
const hooks: libPlugin.MigrationHooks = {
controllerConfig: ControllerConfig.pluginMigrations,
hostConfig: HostConfig.pluginMigrations,
instanceConfig: InstanceConfig.pluginMigrations,
role: Role.pluginMigrations,
};
for (const pluginInfo of pluginInfos) {
Config.pluginVersions.set(pluginInfo.name, pluginInfo.version);
}
await PluginLoader.load({
type: "migration",
context: { hooks },
logger,
installed: pluginInfos,
load: pluginInfos,
});
}
+1 -1
View File
@@ -26,7 +26,7 @@
"./src/permissions.ts",
"./src/prometheus.ts",
"./src/PluginLoader.ts",
"./src/plugin_module.browser.ts",
"./src/import_plugin.browser.ts",
"./src/plugin.ts",
"./src/schema.ts",
"./src/subscriptions.ts",
+57
View File
@@ -211,4 +211,61 @@ describe("lib/PluginLoader", function() {
assert.equal(plugins.checkInstalled("missing"), false);
});
});
describe("plugins.checkEnabled()", function() {
it("should check the load list", async function() {
const pluginInfo = info("test", "function.js");
await load([pluginInfo], { installed: [pluginInfo, { name: "off" }] });
const { plugins } = controller.loadedWith;
assert.equal(plugins.checkEnabled("test"), true);
assert.equal(plugins.checkEnabled("off"), false);
assert.equal(plugins.checkEnabled("missing"), false);
});
});
describe("loadPluginMigrations()", function() {
const baseDir = path.resolve("temp", "test", "plugin", "migration_plugin");
before(async function() {
await fs.mkdir(baseDir, { recursive: true });
await fs.writeFile(path.join(baseDir, "migrations.js"), `
export default function(context) {
context.hooks.controllerConfig.attach(context.plugin.name, config => {
config.migratedBy = context.plugin.name;
return config;
});
}
`);
await fs.writeFile(path.join(baseDir, "throwing.js"), `
export default function() { throw new Error("load failed"); }
`);
});
afterEach(function() {
lib.ControllerConfig.pluginMigrations.clear();
lib.Config.pluginVersions.clear();
});
function migrationInfo(entrypoint) {
return {
name: "test",
version: "1.0.0",
packagePath: path.join(baseDir, "package.json"),
migrationEntrypoint: entrypoint,
};
}
it("should attach migrations from the migration entrypoint", async function() {
await lib.loadPluginMigrations([migrationInfo("migrations.js"), { name: "other" }]);
assert.deepEqual([...lib.ControllerConfig.pluginMigrations.attached], ["test"]);
assert.deepEqual(lib.ControllerConfig.pluginMigrations.reduce({}), { migratedBy: "test" });
});
it("should register the version of every plugin", async function() {
await lib.loadPluginMigrations([migrationInfo("migrations.js"), { name: "other", version: "2.0.0" }]);
assert.deepEqual([...lib.Config.pluginVersions], [["test", "1.0.0"], ["other", "2.0.0"]]);
});
it("should reject with a PluginError if the entrypoint throws", async function() {
await assert.rejects(
lib.loadPluginMigrations([migrationInfo("throwing.js")]),
err => err instanceof lib.PluginError && err.pluginName === "test"
);
});
});
});
@@ -8,7 +8,7 @@ import * as lib from "@clusterio/lib";
import { computePluginStatuses, planUpdate } from "../../packages/web_ui/src/util/plugin_status.ts";
describe("lib/plugin_loader", function() {
describe("lib/plugin_info", function() {
describe("loadPluginInfos()", function() {
let baseDir = path.join("temp", "test", "plugin");
let missingPlugin = path.join(baseDir, "missing_plugin");
@@ -121,52 +121,6 @@ describe("lib/plugin_loader", function() {
);
});
});
describe("loadPluginMigrations()", function() {
const baseDir = path.resolve("temp", "test", "plugin", "migration_plugin");
before(async function() {
await fs.mkdir(baseDir, { recursive: true });
await fs.writeFile(path.join(baseDir, "migrations.js"), `
export default function(context) {
context.hooks.controllerConfig.attach(context.plugin.name, config => {
config.migratedBy = context.plugin.name;
return config;
});
}
`);
await fs.writeFile(path.join(baseDir, "throwing.js"), `
export default function() { throw new Error("load failed"); }
`);
});
afterEach(function() {
lib.ControllerConfig.pluginMigrations.clear();
lib.Config.pluginVersions.clear();
});
function info(entrypoint) {
return {
name: "test",
version: "1.0.0",
packagePath: path.join(baseDir, "package.json"),
migrationEntrypoint: entrypoint,
};
}
it("should attach migrations from the migration entrypoint", async function() {
await lib.loadPluginMigrations([info("migrations.js"), { name: "other" }]);
assert.deepEqual([...lib.ControllerConfig.pluginMigrations.attached], ["test"]);
assert.deepEqual(lib.ControllerConfig.pluginMigrations.reduce({}), { migratedBy: "test" });
});
it("should register the version of every plugin", async function() {
await lib.loadPluginMigrations([info("migrations.js"), { name: "other", version: "2.0.0" }]);
assert.deepEqual([...lib.Config.pluginVersions], [["test", "1.0.0"], ["other", "2.0.0"]]);
});
it("should reject with a PluginError if the entrypoint throws", async function() {
await assert.rejects(
lib.loadPluginMigrations([info("throwing.js")]),
err => err instanceof lib.PluginError && err.pluginName === "test"
);
});
});
describe("loadPluginList()", async function() {
const old_cwd = process.cwd();
const baseDir = path.join("temp", "test", "plugin_list");