diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index 7318a864..500cfcc4 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -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. diff --git a/packages/controller/src/Controller.ts b/packages/controller/src/Controller.ts index 304255a5..4de1cb82 100644 --- a/packages/controller/src/Controller.ts +++ b/packages/controller/src/Controller.ts @@ -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); } } diff --git a/packages/ctl/ctl.ts b/packages/ctl/ctl.ts index a737b6ef..6e210da3 100755 --- a/packages/ctl/ctl.ts +++ b/packages/ctl/ctl.ts @@ -118,18 +118,16 @@ async function loadPlugins(pluginList: Map, hooks: CtlHooks) { lib.registerPluginPermissions(pluginInfos); lib.addPluginConfigFields(pluginInfos); - const ctlPlugins = new Set(); - 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 { diff --git a/packages/host/src/Host.ts b/packages/host/src/Host.ts index deee9e6a..1c8a40df 100644 --- a/packages/host/src/Host.ts +++ b/packages/host/src/Host.ts @@ -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); } } diff --git a/packages/host/src/Instance.ts b/packages/host/src/Instance.ts index 67d1265c..9d511d82 100644 --- a/packages/host/src/Instance.ts +++ b/packages/host/src/Instance.ts @@ -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 = {}; + 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 = {}; + for (const pluginInfo of loaded.keys()) { + this.loadedPlugins.add(pluginInfo); + plugins[pluginInfo.name] = pluginInfo.version; + } this.send(new lib.InstanceInitialisedEvent(plugins)); } diff --git a/packages/lib/browser.ts b/packages/lib/browser.ts index 5aaf6356..ce706743 100644 --- a/packages/lib/browser.ts +++ b/packages/lib/browser.ts @@ -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"; diff --git a/packages/lib/index.ts b/packages/lib/index.ts index ca6f0540..891f57b5 100644 --- a/packages/lib/index.ts +++ b/packages/lib/index.ts @@ -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"; diff --git a/packages/lib/package.json b/packages/lib/package.json index f2f56ddb..20d547af 100644 --- a/packages/lib/package.json +++ b/packages/lib/package.json @@ -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", diff --git a/packages/lib/src/PluginLoader.ts b/packages/lib/src/PluginLoader.ts new file mode 100644 index 00000000..2d178473 --- /dev/null +++ b/packages/lib/src/PluginLoader.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, + waiter: string, +}; + +export type PluginLoadOptions = { + /** 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, + /** Return failed plugins instead of throwing the first error */ + continueOnError?: boolean, +}; + +export type PluginLoadResult = { + /** What each loaded plugin's entrypoint returned, in load order */ + loaded: Map, + failed: Map, +}; + +/** + * Loads plugins concurrently and lets them wait for each other + * + * Created for one load of plugins with {@link PluginLoader.load}. + */ +export class PluginLoader { + private _apis = new Map(); + private _waiters = new Map(); + private _installed: Set; + private _enabled: Set; + /** Plugins still loading */ + private _pending: Set; + + private constructor( + private _options: PluginLoadOptions, + ) { + 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( + options: PluginLoadOptions + ): Promise> { + 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(); + const failed = new Map(); + 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, + 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(waiter: string, name: string, timeoutMs = 30_000): Promise { + 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, + pluginClass: unknown, + exportName: string, + baseClass: PluginClass, +) { + 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).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, + }); +} diff --git a/packages/lib/src/import_plugin.browser.ts b/packages/lib/src/import_plugin.browser.ts new file mode 100644 index 00000000..75d8010a --- /dev/null +++ b/packages/lib/src/import_plugin.browser.ts @@ -0,0 +1,7 @@ +import type { PluginDeclaration, PluginWebEnvInfo } from "./plugin"; + +export default async function importPlugin( + pluginInfo: PluginDeclaration, entrypoint: string +): Promise> { + return await (pluginInfo as PluginWebEnvInfo).container.get(entrypoint); +} diff --git a/packages/lib/src/import_plugin.node.ts b/packages/lib/src/import_plugin.node.ts new file mode 100644 index 00000000..87aac70c --- /dev/null +++ b/packages/lib/src/import_plugin.node.ts @@ -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> { + const packagePath = (pluginInfo as PluginNodeEnvInfo).packagePath; + return await import(pathToFileURL(path.join(path.dirname(packagePath), entrypoint)).href); +} diff --git a/packages/lib/src/loadPlugin.ts b/packages/lib/src/loadPlugin.ts deleted file mode 100644 index 7a6f0a87..00000000 --- a/packages/lib/src/loadPlugin.ts +++ /dev/null @@ -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, - module: Record -) { - 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, - Info extends PluginDeclaration ->( - pluginInfo: Info, - pluginType: PluginType, - context: PluginLoadContext, - module: Record, - 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; -} diff --git a/packages/lib/src/plugin.ts b/packages/lib/src/plugin.ts index 8e5b23db..7ec70cb2 100644 --- a/packages/lib/src/plugin.ts +++ b/packages/lib/src/plugin.ts @@ -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(name: string, timeoutMs?: number): Promise; + /** 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 */ diff --git a/packages/lib/src/plugin_loader.ts b/packages/lib/src/plugin_info.ts similarity index 71% rename from packages/lib/src/plugin_loader.ts rename to packages/lib/src/plugin_info.ts index 1832d36a..6037f585 100644 --- a/packages/lib/src/plugin_loader.ts +++ b/packages/lib/src/plugin_info.ts @@ -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, -> ( - 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, - 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`); -} diff --git a/packages/lib/tsconfig.browser.json b/packages/lib/tsconfig.browser.json index 00cf87ad..7959aa19 100644 --- a/packages/lib/tsconfig.browser.json +++ b/packages/lib/tsconfig.browser.json @@ -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", diff --git a/packages/web_ui/src/bootstrap.tsx b/packages/web_ui/src/bootstrap.tsx index b8c1b538..e2f1ef55 100644 --- a/packages/web_ui/src/bootstrap.tsx +++ b/packages/web_ui/src/bootstrap.tsx @@ -71,49 +71,36 @@ async function loadPlugins( pluginInfos: lib.PluginWebEnvInfo[], control: Control ) { - const plugins = new Map(); + 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(); + for (const [pluginInfo, api] of loaded) { + if (api instanceof WebPlugin.BaseWebPlugin) { + plugins.set(pluginInfo.name, api); + } + } return plugins; } diff --git a/test/controller/Controller.js b/test/controller/Controller.js index 7ee5915a..451b597d 100644 --- a/test/controller/Controller.js +++ b/test/controller/Controller.js @@ -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() { diff --git a/test/host/Host.test.js b/test/host/Host.test.js index 0dcdc1f9..7797bd6e 100644 --- a/test/host/Host.test.js +++ b/test/host/Host.test.js @@ -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; diff --git a/test/lib/PluginLoader.test.js b/test/lib/PluginLoader.test.js new file mode 100644 index 00000000..0aed1cb7 --- /dev/null +++ b/test/lib/PluginLoader.test.js @@ -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" + ); + }); + }); +}); diff --git a/test/lib/plugin_loader.js b/test/lib/plugin_info.js similarity index 80% rename from test/lib/plugin_loader.js rename to test/lib/plugin_info.js index ba999482..26a1102f 100644 --- a/test/lib/plugin_loader.js +++ b/test/lib/plugin_info.js @@ -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");