Merge pull request #1232 from bbassie/feature/wait-for-plugin

Add waitForPlugin and load plugins concurrently
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-11-22 13:14:30 +00:00
commit 1a016372c1
20 files changed
+800 -411

No files matched your search

+30
View File
@@ -206,6 +206,9 @@ The context has the following properties:
**logger**:
Logger for this plugin, see [Logging Messages](#logging-messages).
**plugins**:
The other plugins loaded alongside this one, see [Depending on other plugins](#depending-on-other-plugins).
**controller**, **host**, **instance**, **hooks** or **control**:
The object the entrypoint is loaded for.
Controller entrypoints get `controller`, host entrypoints get `host`, instance entrypoints get both `instance` and `host`, clusterioctl entrypoints get `hooks` and web entrypoints get `control`.
@@ -216,6 +219,33 @@ An error thrown by a handler is logged and does not affect the other handlers, t
For TypeScript the context types are exported as `ControllerPluginContext`, `HostPluginContext`, `InstancePluginContext`, `CtlPluginContext` and `WebPluginContext` from their respective packages.
### Depending on other plugins
Plugins are loaded at the same time, so there is no order between them.
A plugin that uses another plugin can wait for it with `plugins.waitFor(name, timeoutMs)` from its context, `timeoutMs` defaults to 30 seconds.
It resolves to the value returned by the other plugin's entrypoint for the same controller, host, instance, clusterioctl or web interface, so a plugin that offers an API to other plugins should return it from its entrypoint.
For deprecated class based plugins it resolves to the plugin instance.
```js
export default async function({ plugins }) {
const other = await plugins.waitFor("other_plugin");
if (other) {
other.doSomething();
}
}
```
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, 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.
Use `.then` or wait from a hook instead if the other plugin may also wait on yours.
### Class based plugins
Plugins written as classes deriving from `BaseControllerPlugin`, `BaseHostPlugin`, `BaseInstancePlugin`, `BaseCtlPlugin` or `BaseWebPlugin` still load, but this way of defining plugins is deprecated and a warning is logged when such a plugin is loaded.
+14 -19
View File
@@ -1585,7 +1585,7 @@ export default class Controller {
}
async loadPlugins() {
const context = { metrics, logger, controller: this };
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of this.pluginInfos) {
try {
const manifestPath = path.posix.join(pluginInfo.requirePath, "dist", "web", "manifest.json");
@@ -1608,25 +1608,20 @@ export default class Controller {
continue;
}
try {
await lib.loadPlugin(
pluginInfo,
"controller",
context,
"ControllerPlugin",
BaseControllerPlugin,
);
toLoad.push(pluginInfo);
}
this.loadedPlugins.add(pluginInfo);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
}
throw new lib.PluginError(pluginInfo.name, err);
}
logger.info(`Loaded plugin ${pluginInfo.name}`);
const { loaded } = await lib.PluginLoader.load({
type: "controller",
context: { metrics, controller: this },
logger,
installed: this.pluginInfos,
load: toLoad,
exportName: "ControllerPlugin",
baseClass: BaseControllerPlugin,
});
for (const pluginInfo of loaded.keys()) {
this.loadedPlugins.add(pluginInfo);
}
}
+10 -12
View File
@@ -118,18 +118,16 @@ async function loadPlugins(pluginList: Map<string, string>, hooks: CtlHooks) {
lib.registerPluginPermissions(pluginInfos);
lib.addPluginConfigFields(pluginInfos);
const ctlPlugins = new Set<lib.PluginNodeEnvInfo>();
for (let pluginInfo of pluginInfos) {
if (!pluginInfo.ctlEntrypoint) {
continue;
}
const context = { hooks, logger, plugin: pluginInfo };
await lib.loadPlugin(pluginInfo, "ctl", context, "CtlPlugin", BaseCtlPlugin);
ctlPlugins.add(pluginInfo);
}
return ctlPlugins;
const { loaded } = await lib.PluginLoader.load({
type: "ctl",
context: { hooks },
logger,
installed: pluginInfos,
load: pluginInfos.filter(pluginInfo => pluginInfo.ctlEntrypoint),
exportName: "CtlPlugin",
baseClass: BaseCtlPlugin,
});
return new Set(loaded.keys());
}
interface CtlArguments {
+14 -19
View File
@@ -490,7 +490,7 @@ export default class Host extends lib.Link {
}
async loadPlugins() {
const context = { logger, host: this };
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of this.pluginInfos) {
if (
!pluginInfo.hostEntrypoint && !pluginInfo.instanceEntrypoint
@@ -504,25 +504,20 @@ export default class Host extends lib.Link {
continue;
}
try {
await lib.loadPlugin(
pluginInfo,
"host",
context,
"HostPlugin",
BaseHostPlugin,
);
toLoad.push(pluginInfo);
}
this.loadedPlugins.add(pluginInfo);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
}
throw new lib.PluginError(pluginInfo.name, err);
}
logger.info(`Loaded plugin ${pluginInfo.name}`);
const { loaded } = await lib.PluginLoader.load({
type: "host",
context: { host: this },
logger,
installed: this.pluginInfos,
load: toLoad,
exportName: "HostPlugin",
baseClass: BaseHostPlugin,
});
for (const pluginInfo of loaded.keys()) {
this.loadedPlugins.add(pluginInfo);
}
}
+24 -20
View File
@@ -804,8 +804,7 @@ end`.replace(/\r?\n/g, " ");
* Must be called once the instance is connected to the host.
*/
async loadPlugins(pluginInfos: lib.PluginNodeEnvInfo[]) {
// load plugins
const plugins: Record<string, string> = {};
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of pluginInfos) {
if (
!pluginInfo.instanceEntrypoint
@@ -820,26 +819,31 @@ end`.replace(/\r?\n/g, " ");
continue;
}
try {
let pluginLoadStartedMs = Date.now();
await lib.loadPlugin(
pluginInfo,
"instance",
{ logger: this.logger, host: this._host, instance: this },
"InstancePlugin",
BaseInstancePlugin,
);
this.loadedPlugins.add(pluginInfo);
plugins[pluginInfo.name] = pluginInfo.version;
this.logger.info(`Loaded plugin ${pluginInfo.name} in ${Date.now() - pluginLoadStartedMs}ms`);
} catch (err) {
this.notifyExit();
await this.sendSaveListUpdate();
throw err;
}
toLoad.push(pluginInfo);
}
let loaded;
try {
({ loaded } = await lib.PluginLoader.load({
type: "instance",
context: { host: this._host, instance: this },
logger: this.logger,
installed: pluginInfos,
load: toLoad,
exportName: "InstancePlugin",
baseClass: BaseInstancePlugin,
}));
} catch (err) {
this.notifyExit();
await this.sendSaveListUpdate();
throw err;
}
const plugins: Record<string, string> = {};
for (const pluginInfo of loaded.keys()) {
this.loadedPlugins.add(pluginInfo);
plugins[pluginInfo.name] = pluginInfo.version;
}
this.send(new lib.InstanceInitialisedEvent(plugins));
}
+1 -1
View File
@@ -13,7 +13,7 @@ export * from "./src/link";
export * from "./src/lua_tools";
export * from "./src/logging";
export * from "./src/permissions";
export * from "./src/loadPlugin";
export * from "./src/PluginLoader";
export * from "./src/schema";
export * from "./src/subscriptions";
+2 -2
View File
@@ -23,8 +23,8 @@ 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/loadPlugin.js";
export * from "./src/plugin_info.js";
export * from "./src/PluginLoader.js";
export * from "./src/prometheus.js";
export * from "./src/schema.js";
export * from "./src/shared_commands.js";
+7
View File
@@ -38,6 +38,13 @@
},
"import": "./src/zlib_sync.browser.ts"
},
"#import_plugin": {
"node": {
"types": "./src/import_plugin.node.ts",
"default": "./dist/node/src/import_plugin.node.js"
},
"import": "./src/import_plugin.browser.ts"
},
"#is_deep_strict_equal": {
"node": {
"types": "./src/is_deep_strict_equal.node.ts",
+264
View File
@@ -0,0 +1,264 @@
// 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 { logger, type Logger } from "./logging.js";
import type {
MigrationHooks, PluginClass, PluginDeclaration, PluginLoadContext, PluginNodeEnvInfo, PluginRegistry, PluginType,
} from "./plugin.js";
type Waiter = {
resolve: (api: unknown) => void,
timeout: ReturnType<typeof setTimeout>,
waiter: string,
};
export type PluginLoadOptions<Context extends object, Info extends PluginDeclaration> = {
/** Entrypoint to load, e.g. controller loads controllerEntrypoint */
type: PluginType,
/** Context passed to each plugin, plugin, logger and plugins are added per plugin */
context: Context | ((pluginInfo: Info) => Context),
/** Logger for warnings, plugins get a child of it */
logger: Logger,
/** All installed plugins, used by checkInstalled */
installed: Info[],
/** Plugins to load, used by checkEnabled */
load: Info[],
/** Name of the deprecated class export, class exports are not accepted if unset */
exportName?: string,
baseClass?: PluginClass<any, any>,
/** Return failed plugins instead of throwing the first error */
continueOnError?: boolean,
};
export type PluginLoadResult<Info> = {
/** What each loaded plugin's entrypoint returned, in load order */
loaded: Map<Info, unknown>,
failed: Map<Info, Error>,
};
/**
* Loads plugins concurrently and lets them wait for each other
*
* Created for one load of plugins with {@link PluginLoader.load}.
*/
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>;
private constructor(
private _options: PluginLoadOptions<Context, Info>,
) {
this._installed = new Set(_options.installed.map(pluginInfo => pluginInfo.name));
this._enabled = new Set(_options.load.map(pluginInfo => pluginInfo.name));
this._pending = new Set(this._enabled);
}
/**
* Load plugins concurrently
*
* Waits for all plugins to settle, then throws the error of the first
* plugin in the list that failed unless continueOnError is set.
* Errors are wrapped in PluginError.
*
* @param options - What to load and how.
* @returns Loaded and failed plugins.
*/
static async load<Context extends object, Info extends PluginDeclaration>(
options: PluginLoadOptions<Context, Info>
): Promise<PluginLoadResult<Info>> {
return await new PluginLoader(options)._load();
}
private async _load() {
const results = await Promise.allSettled(this._options.load.map(async pluginInfo => {
const startedMs = Date.now();
try {
const api = await this._loadPlugin(pluginInfo);
if (this._options.type !== "migration" && pluginInfo[`${this._options.type}Entrypoint`]) {
this._options.logger.info(`Loaded plugin ${pluginInfo.name} in ${Date.now() - startedMs}ms`);
}
this._settle(pluginInfo.name, true, api);
return api;
} catch (err) {
this._settle(pluginInfo.name, false);
throw err;
}
}));
const loaded = new Map<Info, unknown>();
const failed = new Map<Info, Error>();
for (const [index, result] of results.entries()) {
const pluginInfo = this._options.load[index];
if (result.status === "fulfilled") {
loaded.set(pluginInfo, result.value);
} else {
failed.set(pluginInfo, result.reason);
}
}
if (failed.size && !this._options.continueOnError) {
throw failed.values().next().value;
}
return { loaded, failed };
}
private async _loadPlugin(pluginInfo: Info) {
const { type, exportName, baseClass } = this._options;
const entrypoint = pluginInfo[`${type}Entrypoint`];
if (!entrypoint) {
return undefined;
}
const options = this._options;
const context = typeof options.context === "function" ? options.context(pluginInfo) : options.context;
const pluginContext: PluginLoadContext<Context, Info> = {
...context,
plugin: pluginInfo,
logger: options.logger.child({ plugin: pluginInfo.name }),
plugins: this._registry(pluginInfo.name),
};
try {
const module = await importPlugin(pluginInfo, entrypoint);
if (typeof module.default === "function") {
return await module.default(pluginContext) as unknown;
}
// migrate: accept plugins which export classes
if (exportName && baseClass && module[exportName]) {
pluginContext.logger.warn(`Plugin ${pluginInfo.name} is using deprecated class export`);
return await loadPluginClass(pluginInfo, pluginContext, module[exportName], exportName, baseClass);
}
throw new Error(exportName
? `Plugin ${pluginInfo.name} must export either a default function or ${exportName} class`
: `Expected ${type} plugin ${pluginInfo.name} to export a default function`
);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
}
throw new PluginError(pluginInfo.name, err);
}
}
private _registry(waiter: string): PluginRegistry {
return {
waitFor: (name, timeoutMs) => this._waitFor(waiter, name, timeoutMs),
checkInstalled: name => this._installed.has(name),
checkEnabled: name => this._enabled.has(name),
};
}
private _settle(name: string, loaded: boolean, api?: unknown) {
this._pending.delete(name);
if (loaded) {
this._apis.set(name, api);
}
for (const entry of this._waiters.get(name) ?? []) {
clearTimeout(entry.timeout);
if (!loaded) {
this._warnNotLoaded(entry.waiter, name);
}
entry.resolve(api);
}
this._waiters.delete(name);
}
private _waitFor<T>(waiter: string, name: string, timeoutMs = 30_000): Promise<T | undefined> {
if (this._apis.has(name)) {
return Promise.resolve(this._apis.get(name) as T);
}
if (!this._pending.has(name)) {
this._warnNotLoaded(waiter, name);
return Promise.resolve(undefined);
}
return new Promise(resolve => {
const entry: Waiter = {
resolve: resolve as (api: unknown) => void,
waiter,
timeout: setTimeout(() => {
const entries = this._waiters.get(name)!;
entries.splice(entries.indexOf(entry), 1);
this._options.logger.warn(
`Plugin ${waiter} timed out after ${timeoutMs}ms waiting for plugin ${name}`
);
resolve(undefined);
}, timeoutMs),
};
let entries = this._waiters.get(name);
if (!entries) {
entries = [];
this._waiters.set(name, entries);
}
entries.push(entry);
});
}
private _warnNotLoaded(waiter: string, name: string) {
this._options.logger.warn(`Plugin ${waiter} waited for plugin ${name} which is not loaded`);
}
}
async function loadPluginClass(
pluginInfo: PluginDeclaration,
context: PluginLoadContext<object, any>,
pluginClass: unknown,
exportName: string,
baseClass: PluginClass<any, any>,
) {
if (typeof pluginClass !== "function") {
throw new Error(`Expected plugin ${pluginInfo.name} to export a class named ${exportName}`);
}
if (!(pluginClass.prototype instanceof baseClass)) {
throw new Error(`Expected ${exportName} exported from ${pluginInfo.name} to extend ${baseClass.name}`);
}
const plugin = (pluginClass as PluginClass<any, any>).fromContext(context);
try {
await plugin.init();
} catch (err) {
plugin.detachHooks();
throw err;
}
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,
});
}
@@ -0,0 +1,7 @@
import type { PluginDeclaration, PluginWebEnvInfo } from "./plugin";
export default async function importPlugin(
pluginInfo: PluginDeclaration, entrypoint: string
): Promise<Record<string, any>> {
return await (pluginInfo as PluginWebEnvInfo).container.get(entrypoint);
}
+10
View File
@@ -0,0 +1,10 @@
import path from "node:path";
import { pathToFileURL } from "node:url";
import type { PluginDeclaration, PluginNodeEnvInfo } from "./plugin.js";
export default async function importPlugin(
pluginInfo: PluginDeclaration, entrypoint: string
): Promise<Record<string, any>> {
const packagePath = (pluginInfo as PluginNodeEnvInfo).packagePath;
return await import(pathToFileURL(path.join(path.dirname(packagePath), entrypoint)).href);
}
-54
View File
@@ -1,54 +0,0 @@
// Contained in its own file to allow use within web build
import type { PluginDeclaration, PluginType, PluginLoadContext, PluginClass } from "./plugin.js";
export async function loadPluginEntrypoint<
Context extends object,
Info extends PluginDeclaration
>(
pluginInfo: Info,
pluginType: PluginType,
context: PluginLoadContext<Context, Info>,
module: Record<string, unknown>
) {
const init = module.default;
if (typeof init !== "function") {
throw new Error(`Expected ${pluginType} plugin ${pluginInfo.name} to export a default function`);
}
await init(context);
}
export async function loadPluginClass<
Context extends object,
Class extends PluginClass<Context, Info>,
Info extends PluginDeclaration
>(
pluginInfo: Info,
pluginType: PluginType,
context: PluginLoadContext<Context, Info>,
module: Record<string, unknown>,
exportName: string,
baseClass: Class
) {
const pluginClass = module[exportName];
if (typeof pluginClass !== "function") {
throw new Error(`Expected ${pluginType} plugin ${pluginInfo.name} to export a class named ${exportName}`);
}
if (!(pluginClass.prototype instanceof baseClass)) {
throw new Error(`Expected ${exportName} exported from ${pluginInfo.name} to extend ${baseClass.name}`);
}
const plugin = (pluginClass as Class).fromContext(context);
try {
await plugin.init();
} catch (err) {
plugin.detachHooks();
throw err;
}
return plugin as InstanceType<Class>;
}
+19
View File
@@ -142,12 +142,31 @@ export interface PlayerEvent {
stats: PlayerStats,
}
/** Access to the other plugins loaded alongside a plugin */
export interface PluginRegistry {
/**
* Wait for another plugin to load
*
* @param name - Name of the plugin to wait for.
* @param timeoutMs - Time to wait before giving up, defaults to 30 seconds.
* @returns
* What the plugin's entrypoint returned, or undefined with a
* warning logged if it did not load.
*/
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<
Context extends object,
Info extends PluginDeclaration = PluginNodeEnvInfo
> = Context & {
logger: Logger;
plugin: Info;
plugins: PluginRegistry;
};
/** Hooks for migrating data that Clusterio stores on behalf of plugins */
@@ -1,18 +1,14 @@
/**
* 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";
import { fileURLToPath, pathToFileURL } from "node:url";
import * as libErrors from "./errors.js";
import * as libPlugin from "./plugin.js";
import { type Logger, logger } from "./logging.js";
import { loadPluginEntrypoint, loadPluginClass } from "./loadPlugin.js";
import { Config } from "./config/classes.js";
import { ControllerConfig, HostConfig, InstanceConfig } from "./config/definitions.js";
import Role from "./data/Role.js";
import { logger } from "./logging.js";
import { PluginDetails } from "./data/messages_plugin.js";
import {
discoverNpmPluginPackages, findNonRegistryDirs, installedDependencies, readPackageJson, realDir, resolvePackagePath,
@@ -196,82 +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);
if (!pluginInfo.migrationEntrypoint) {
continue;
}
try {
const module = await import(pathToFileURL(
path.join(path.dirname(pluginInfo.packagePath), pluginInfo.migrationEntrypoint)
).href);
const context: libPlugin.MigrationContext = {
hooks,
plugin: pluginInfo,
logger: logger.child({ plugin: pluginInfo.name }),
};
await loadPluginEntrypoint(pluginInfo, "migration", context, module);
} catch (err: any) {
throw new libErrors.PluginError(pluginInfo.name, err);
}
}
}
export async function loadPlugin<
Context extends { logger: Logger },
Class extends libPlugin.PluginClass<Context, libPlugin.PluginNodeEnvInfo>,
> (
pluginInfo: libPlugin.PluginNodeEnvInfo,
pluginType: libPlugin.PluginType,
context: Context,
exportName: `${string}Plugin`,
baseClass: Class,
) {
const entrypoint = `${pluginType}Entrypoint` as const;
const requirePath = pluginInfo[entrypoint];
if (!requirePath) {
return;
}
const module = await import(pathToFileURL(path.join(path.dirname(pluginInfo.packagePath), requirePath)).href);
const pluginContext: libPlugin.PluginLoadContext<Context> = {
...context,
plugin: pluginInfo,
logger: context.logger.child({ plugin: pluginInfo.name }),
};
if (typeof module.default === "function") {
await loadPluginEntrypoint(pluginInfo, pluginType, pluginContext, module);
return;
}
// migrate: accept plugins which export classes
if (module[exportName]) {
pluginContext.logger.warn(`Plugin ${pluginInfo.name} is using deprecated class export`);
await loadPluginClass(pluginInfo, pluginType, pluginContext, module, exportName, baseClass);
return;
}
throw new Error(`Plugin ${pluginInfo.name} must export either a default function or ${exportName} class`);
}
+2 -1
View File
@@ -25,7 +25,8 @@
"./src/logging.ts",
"./src/permissions.ts",
"./src/prometheus.ts",
"./src/loadPlugin.ts",
"./src/PluginLoader.ts",
"./src/import_plugin.browser.ts",
"./src/plugin.ts",
"./src/schema.ts",
"./src/subscriptions.ts",
+26 -39
View File
@@ -71,49 +71,36 @@ async function loadPlugins(
pluginInfos: lib.PluginWebEnvInfo[],
control: Control
) {
const plugins = new Map<string, WebPlugin.BaseWebPlugin>();
const { loaded, failed } = await lib.PluginLoader.load({
type: "web",
context: (pluginInfo: lib.PluginWebEnvInfo) => ({
control,
container: pluginInfo.container,
package: pluginInfo.package,
}),
logger,
installed: pluginInfos,
load: pluginInfos.filter(pluginInfo => pluginInfo.enabled && pluginInfo.webEntrypoint),
exportName: "WebPlugin",
baseClass: WebPlugin.BaseWebPlugin,
continueOnError: true,
});
for (const pluginInfo of pluginInfos) {
if (!pluginInfo.enabled || !pluginInfo.webEntrypoint) {
continue;
}
try {
const webModule = await pluginInfo.container.get(pluginInfo.webEntrypoint);
const pluginContext: WebPlugin.WebPluginContext = {
control,
plugin: pluginInfo,
container: pluginInfo.container,
package: pluginInfo.package,
logger: logger.child({ plugin: pluginInfo.name }),
};
if (typeof webModule.default === "function") {
await lib.loadPluginEntrypoint(pluginInfo, "web", pluginContext, webModule);
continue;
}
// migrate: accept plugins which export classes
if (webModule.WebPlugin) {
logger.warn(`Plugin ${pluginInfo.name} is using deprecated class hooks`);
plugins.set(pluginInfo.name, await lib.loadPluginClass(
pluginInfo, "web", pluginContext, webModule, "WebPlugin", WebPlugin.BaseWebPlugin
));
continue;
}
throw new Error(`Plugin ${pluginInfo.name} must export either a default function or WebPlugin`);
} catch (err: any) {
pluginInfo.error = `Error loading plugin: ${err.message}`;
logger.error(`Failed to load plugin ${pluginInfo.name}`);
if (err.stack) {
logger.error(err.stack);
}
for (const [pluginInfo, err] of failed) {
const cause = err instanceof lib.PluginError ? err.original : err;
pluginInfo.error = `Error loading plugin: ${cause.message}`;
logger.error(`Failed to load plugin ${pluginInfo.name}`);
if (cause.stack) {
logger.error(cause.stack);
}
}
const plugins = new Map<string, WebPlugin.BaseWebPlugin>();
for (const [pluginInfo, api] of loaded) {
if (api instanceof WebPlugin.BaseWebPlugin) {
plugins.set(pluginInfo.name, api);
}
}
return plugins;
}
+53
View File
@@ -239,6 +239,59 @@ describe("controller/src/Controller", function() {
});
});
});
describe(".loadPlugins()", function() {
const names = ["wait_early", "wait_late", "wait_off"];
let dir;
before(async function() {
addPluginConfigFields(names.map(name => ({ name, version: "1.0.0", controllerEntrypoint: "x" })));
dir = await fs.mkdtemp(path.join(os.tmpdir(), "clusterio-wait-"));
const entrypoints = {
wait_early: `export default async function({ controller, plugins }) {
controller.lateApi = await plugins.waitFor("wait_late");
controller.offApi = await plugins.waitFor("wait_off", 60_000);
}`,
wait_late: "export default function() { return { late: true }; }",
wait_off: "export default function() { return { off: true }; }",
};
for (const [name, content] of Object.entries(entrypoints)) {
await fs.mkdir(path.join(dir, name, "dist", "web"), { recursive: true });
await fs.writeFile(path.join(dir, name, "dist", "web", "manifest.json"), "{}");
await fs.writeFile(path.join(dir, name, "controller.js"), content);
}
});
after(async function() {
for (const name of Object.keys(lib.ControllerConfig.fieldDefinitions)) {
if (names.some(plugin => name.startsWith(`${plugin}.`))) {
delete lib.ControllerConfig.fieldDefinitions[name];
}
}
await fs.rm(dir, { recursive: true, force: true });
});
function pluginController(recoveryMode = false) {
const config = new ControllerConfig("controller", {
"controller.version": controllerVersion, "wait_off.load_plugin": false,
});
const infos = names.map(name => ({
name,
requirePath: path.join(dir, name),
packagePath: path.join(dir, name, "package.json"),
controllerEntrypoint: "controller.js",
}));
return new Controller({}, infos, config, false, recoveryMode);
}
it("should let plugins wait for each other", async function() {
const pluginsController = pluginController();
await pluginsController.loadPlugins();
assert.deepEqual(pluginsController.lateApi, { late: true });
assert.equal(pluginsController.offApi, undefined);
assert.deepEqual([...pluginsController.loadedPlugins].map(p => p.name), ["wait_early", "wait_late"]);
});
it("should load nothing in recovery mode", async function() {
const pluginsController = pluginController(true);
await pluginsController.loadPlugins();
assert.equal(pluginsController.loadedPlugins.size, 0);
});
});
describe(".validateExports()", function() {
let dir;
before(async function() {
+35
View File
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
import dgram from "node:dgram";
import events from "node:events";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -250,6 +251,40 @@ describe("host/src/Host", function() {
assert.equal(host.config.restartRequired, true);
});
});
describe(".loadPlugins()", function() {
let dir;
before(async function() {
lib.addPluginConfigFields([
{ name: "host_wait_early", version: "1.0.0", hostEntrypoint: "x" },
{ name: "host_wait_late", version: "1.0.0", hostEntrypoint: "x" },
]);
dir = await fs.mkdtemp(path.join(os.tmpdir(), "clusterio-host-wait-"));
await fs.writeFile(path.join(dir, "early.js"), `export default async function({ host, plugins }) {
host.lateApi = await plugins.waitFor("host_wait_late");
}`);
await fs.writeFile(path.join(dir, "late.js"), "export default function() { return { late: true }; }");
});
after(async function() {
for (const name of Object.keys(lib.HostConfig.fieldDefinitions)) {
if (name.startsWith("host_wait_")) {
delete lib.HostConfig.fieldDefinitions[name];
}
}
await fs.rm(dir, { recursive: true, force: true });
});
it("should let plugins wait for each other", async function() {
const pluginInfos = [["host_wait_early", "early.js"], ["host_wait_late", "late.js"]].map(
([name, hostEntrypoint]) => ({
name, hostEntrypoint, packagePath: path.resolve(dir, "package.json"),
})
);
const hostConfig = new lib.HostConfig("host");
const host = new Host(new HostConnector(hostConfig, pluginInfos), hostConfig, pluginInfos);
await host.loadPlugins();
assert.deepEqual(host.lateApi, { late: true });
assert.deepEqual([...host.loadedPlugins].map(p => p.name), ["host_wait_early", "host_wait_late"]);
});
});
describe(".assignFreeGamePort()", function() {
let host;
let held;
+271
View File
@@ -0,0 +1,271 @@
import assert from "node:assert/strict";
import fs from "node:fs/promises";
import path from "node:path";
import * as mock from "../mock.js";
import * as lib from "@clusterio/lib";
import { BaseControllerPlugin } from "@clusterio/controller";
describe("lib/PluginLoader", function() {
let dir;
let logger;
let controller;
before(async function() {
// Inside the repo so the class entrypoints can import @clusterio/controller
dir = path.resolve("temp", "test", "plugin_loader");
await fs.mkdir(dir, { recursive: true });
const entrypoints = {
"function.js": `export default async function(context) {
context.controller.loadedWith = context;
return { api: true };
}`,
"class.js": `import { BaseControllerPlugin } from "@clusterio/controller";
export class ControllerPlugin extends BaseControllerPlugin {
async init() { this.controller.loadedWith = this; }
async onSaveData() { }
}`,
"throwing_class.js": `import { BaseControllerPlugin } from "@clusterio/controller";
export class ControllerPlugin extends BaseControllerPlugin {
async init() { throw new Error("init failed"); }
async onSaveData() { }
}`,
"empty.js": "",
"wrong_parent.js": "export class ControllerPlugin {};\n",
"not_class.js": "export const ControllerPlugin = 1;\n",
"installation_error.js": `import { InstallationError } from "@clusterio/lib";
export default function() { throw new InstallationError("missing dependency"); }`,
"throwing.js": `export default async function({ plugin }) {
await new Promise(resolve => setTimeout(resolve, plugin.delay ?? 0));
throw new Error(\`\${plugin.name} failed\`);
}`,
// Waits for the plugin named in plugin.waitFor and returns what it got
"waiting.js": `export default async function({ plugin, plugins }) {
const got = plugin.waitFor ? await plugins.waitFor(plugin.waitFor, plugin.timeoutMs) : undefined;
return { name: plugin.name, got };
}`,
};
for (const [file, content] of Object.entries(entrypoints)) {
await fs.writeFile(path.join(dir, file), content);
}
});
after(async function() {
await fs.rm(dir, { recursive: true, force: true });
});
beforeEach(function() {
controller = new mock.MockController();
logger = new mock.MockLogger();
logger.warnings = [];
logger.warn = msg => logger.warnings.push(msg);
});
function info(name, entrypoint, extra = {}) {
return { name, packagePath: path.join(dir, "package.json"), controllerEntrypoint: entrypoint, ...extra };
}
function load(pluginInfos, options = {}) {
return lib.PluginLoader.load({
type: "controller",
context: { controller },
logger,
installed: pluginInfos,
load: pluginInfos,
exportName: "ControllerPlugin",
baseClass: BaseControllerPlugin,
...options,
});
}
async function loadOne(pluginInfo) {
const { loaded } = await load([pluginInfo]);
return loaded.get(pluginInfo);
}
describe("loading", function() {
it("should load plugins without the entrypoint as undefined", async function() {
const pluginInfo = { name: "test" };
const { loaded } = await load([pluginInfo]);
assert.deepEqual([...loaded], [[pluginInfo, undefined]]);
assert.equal(controller.loadedWith, undefined);
});
it("should call the default export with the load context", async function() {
const pluginInfo = info("test", "function.js");
assert.deepEqual(await loadOne(pluginInfo), { api: true });
assert.equal(controller.loadedWith.controller, controller);
assert.equal(controller.loadedWith.plugin, pluginInfo);
assert.equal(controller.loadedWith.logger, logger);
assert.equal(typeof controller.loadedWith.plugins.waitFor, "function");
assert.deepEqual(logger.warnings, []);
});
it("should build the context per plugin when given a function", async function() {
const pluginInfo = info("test", "function.js");
await load([pluginInfo], { context: p => ({ controller, name: p.name }) });
assert.equal(controller.loadedWith.name, "test");
});
it("should load a deprecated class export", async function() {
const pluginInfo = info("test", "class.js");
assert.equal(await loadOne(pluginInfo), controller.loadedWith);
assert(controller.loadedWith instanceof BaseControllerPlugin);
assert.equal(controller.loadedWith.info, pluginInfo);
assert.deepEqual([...controller.hooks.save.attached], ["test"]);
assert.deepEqual(logger.warnings, ["Plugin test is using deprecated class export"]);
});
it("should not accept class exports without exportName", async function() {
await assert.rejects(
load([info("test", "class.js")], { exportName: undefined }),
{ message: "PluginError: Expected controller plugin test to export a default function" },
);
});
it("should detach hooks if init throws", async function() {
await assert.rejects(
loadOne(info("test", "throwing_class.js")),
err => err instanceof lib.PluginError && err.original.message === "init failed",
);
assert.equal(controller.hooks.size, 0);
});
it("should throw if neither a function nor a class is exported", async function() {
await assert.rejects(
loadOne(info("test", "empty.js")),
{ message: "PluginError: Plugin test must export either a default function or ControllerPlugin class" },
);
});
it("should throw if the class is not a subclass of the base class", async function() {
await assert.rejects(
loadOne(info("test", "wrong_parent.js")),
{ message: "PluginError: Expected ControllerPlugin exported from test to extend BaseControllerPlugin" },
);
});
it("should throw if the class export is not a class", async function() {
await assert.rejects(
loadOne(info("test", "not_class.js")),
{ message: "PluginError: Expected plugin test to export a class named ControllerPlugin" },
);
});
it("should not wrap installation errors", async function() {
await assert.rejects(
loadOne(info("test", "installation_error.js")),
err => err instanceof lib.InstallationError,
);
});
it("should finish loading the rest before throwing the first error in list order", async function() {
const ok = info("ok", "function.js");
await assert.rejects(
load([info("a", "throwing.js", { delay: 10 }), info("b", "throwing.js"), ok]),
err => err instanceof lib.PluginError && err.pluginName === "a",
);
assert.equal(controller.loadedWith.plugin, ok);
});
it("should return failures with continueOnError", async function() {
const a = info("a", "throwing.js");
const ok = info("ok", "function.js");
const { loaded, failed } = await load([a, ok], { continueOnError: true });
assert.deepEqual([...loaded.keys()], [ok]);
assert.deepEqual([...failed.keys()], [a]);
assert(failed.get(a) instanceof lib.PluginError);
});
});
describe("plugins.waitFor()", function() {
it("should resolve to what a plugin later in the list returned", async function() {
const { loaded } = await load([info("a", "waiting.js", { waitFor: "b" }), info("b", "waiting.js")]);
const b = { name: "b", got: undefined };
assert.deepEqual([...loaded.values()], [{ name: "a", got: b }, b]);
assert.deepEqual(logger.warnings, []);
});
it("should resolve after loading finished", async function() {
const pluginInfo = info("test", "function.js");
await load([pluginInfo, info("b", "waiting.js")]);
const { plugins } = controller.loadedWith;
assert.deepEqual(await plugins.waitFor("b"), { name: "b", got: undefined });
assert.equal(await plugins.waitFor("missing"), undefined);
assert.deepEqual(logger.warnings, ["Plugin test waited for plugin missing which is not loaded"]);
});
it("should resolve undefined with a warning once loading finishes without the plugin", async function() {
const installed = [info("off", "function.js")];
const waiting = info("a", "waiting.js", { waitFor: "off", timeoutMs: 60_000 });
const { loaded } = await load([waiting], { installed });
assert.deepEqual(loaded.get(waiting), { name: "a", got: undefined });
assert.deepEqual(logger.warnings, ["Plugin a waited for plugin off which is not loaded"]);
});
it("should resolve undefined with a warning if the plugin failed", async function() {
const waiting = info("a", "waiting.js", { waitFor: "b", timeoutMs: 60_000 });
const { loaded } = await load([waiting, info("b", "throwing.js")], { continueOnError: true });
assert.deepEqual(loaded.get(waiting), { name: "a", got: undefined });
assert.deepEqual(logger.warnings, ["Plugin a waited for plugin b which is not loaded"]);
});
it("should break a wait cycle with the timeout", async function() {
const { loaded } = await load([
info("a", "waiting.js", { waitFor: "b", timeoutMs: 10 }),
info("b", "waiting.js", { waitFor: "a", timeoutMs: 60_000 }),
]);
const a = { name: "a", got: undefined };
assert.deepEqual([...loaded.values()], [a, { name: "b", got: a }]);
assert.deepEqual(logger.warnings, ["Plugin a timed out after 10ms waiting for plugin b"]);
});
});
describe("plugins.checkInstalled()", function() {
it("should check the installed list", async function() {
const pluginInfo = info("test", "function.js");
await load([pluginInfo], { installed: [pluginInfo, { name: "off" }] });
const { plugins } = controller.loadedWith;
assert.equal(plugins.checkInstalled("test"), true);
assert.equal(plugins.checkInstalled("off"), true);
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"
);
});
});
});
@@ -5,11 +5,10 @@ import { pathToFileURL } from "node:url";
import * as mock from "../mock.js";
import * as lib from "@clusterio/lib";
import { BaseControllerPlugin } from "@clusterio/controller";
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");
@@ -105,10 +104,13 @@ describe("lib/plugin_loader", function() {
assert.equal(pluginInfo.packagePath, path.join(packageDir, "package.json"));
const controller = new mock.MockController();
await lib.loadPlugin(
pluginInfo, "controller", { controller, metrics: {}, logger: new mock.MockLogger() },
"ControllerPlugin", BaseControllerPlugin,
);
await lib.PluginLoader.load({
type: "controller",
context: { controller },
logger: new mock.MockLogger(),
installed: [pluginInfo],
load: [pluginInfo],
});
assert.equal(controller.loadedNpmPlugin, true);
});
});
@@ -119,158 +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("loadPlugin()", function() {
const baseDir = path.join("temp", "test", "plugin");
const functionPlugin = path.resolve(baseDir, "function_plugin");
const classPlugin = path.resolve(baseDir, "class_plugin");
const throwingClassPlugin = path.resolve(baseDir, "throwing_class_plugin");
const missingClassPlugin = path.resolve(baseDir, "missing_class_plugin");
const wrongParentClassPlugin = path.resolve(baseDir, "wrong_parent_class_plugin");
let controller;
let logger;
let context;
before(async function() {
async function writeEntrypoint(pluginPath, content) {
await fs.mkdir(pluginPath, { recursive: true });
await fs.writeFile(path.join(pluginPath, "controller.js"), content);
}
await writeEntrypoint(functionPlugin, `
export default async function(context) {
context.controller.loadedWith = context;
}
`);
await writeEntrypoint(classPlugin, `
import { BaseControllerPlugin } from "@clusterio/controller";
export class ControllerPlugin extends BaseControllerPlugin {
async init() { this.controller.loadedWith = this; }
async onSaveData() { }
}
`);
await writeEntrypoint(throwingClassPlugin, `
import { BaseControllerPlugin } from "@clusterio/controller";
export class ControllerPlugin extends BaseControllerPlugin {
async init() { throw new Error("init failed"); }
async onSaveData() { }
}
`);
await writeEntrypoint(missingClassPlugin, "");
await writeEntrypoint(wrongParentClassPlugin, "export class ControllerPlugin {};\n");
});
beforeEach(function() {
controller = new mock.MockController();
logger = new mock.MockLogger();
logger.warnings = [];
logger.warn = msg => logger.warnings.push(msg);
context = { controller, metrics: {}, logger };
});
function info(requirePath, entrypoint = "controller.js") {
return {
name: "test",
requirePath,
packagePath: path.join(requirePath, "package.json"),
controllerEntrypoint: entrypoint,
};
}
it("should do nothing when the entrypoint is not set", async function() {
await lib.loadPlugin(
{ name: "test", requirePath: missingClassPlugin }, "controller", context,
"ControllerPlugin", BaseControllerPlugin,
);
assert.equal(controller.loadedWith, undefined);
});
it("should call the default export with the load context", async function() {
const pluginInfo = info(functionPlugin);
await lib.loadPlugin(pluginInfo, "controller", context, "ControllerPlugin", BaseControllerPlugin);
assert.equal(controller.loadedWith.controller, controller);
assert.equal(controller.loadedWith.plugin, pluginInfo);
assert.equal(controller.loadedWith.logger, logger);
assert.deepEqual(logger.warnings, []);
});
it("should load a deprecated class export", async function() {
const pluginInfo = info(classPlugin);
await lib.loadPlugin(pluginInfo, "controller", context, "ControllerPlugin", BaseControllerPlugin);
assert(controller.loadedWith instanceof BaseControllerPlugin);
assert.equal(controller.loadedWith.info, pluginInfo);
assert.deepEqual([...controller.hooks.save.attached], ["test"]);
assert.deepEqual(logger.warnings, ["Plugin test is using deprecated class export"]);
});
it("should detach hooks if init throws", async function() {
await assert.rejects(
lib.loadPlugin(
info(throwingClassPlugin), "controller", context, "ControllerPlugin", BaseControllerPlugin
),
new Error("init failed")
);
assert.equal(controller.hooks.size, 0);
});
it("should throw if neither a function nor a class is exported", async function() {
await assert.rejects(
lib.loadPlugin(
info(missingClassPlugin), "controller", context, "ControllerPlugin", BaseControllerPlugin
),
new Error("Plugin test must export either a default function or ControllerPlugin class")
);
});
it("should throw if the class is not a subclass of the base class", async function() {
await assert.rejects(
lib.loadPlugin(
info(wrongParentClassPlugin), "controller", context, "ControllerPlugin", BaseControllerPlugin
),
new Error("Expected ControllerPlugin exported from test to extend BaseControllerPlugin")
);
});
});
describe("loadPluginList()", async function() {
const old_cwd = process.cwd();
const baseDir = path.join("temp", "test", "plugin_list");