mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-23 00:13:13 +09:00
Merge pull request #1232 from bbassie/feature/wait-for-plugin
Add waitForPlugin and load plugins concurrently
This commit is contained in:
20 files changed
+800
-411
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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
@@ -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
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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));
|
||||
}
|
||||
|
||||
|
||||
@@ -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";
|
||||
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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>;
|
||||
}
|
||||
@@ -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`);
|
||||
}
|
||||
@@ -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",
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
|
||||
@@ -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() {
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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");
|
||||
Reference in new issue
Block a user