mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-23 00:13:13 +09:00
Load all plugin types through one short lived PluginLoader
PluginLoader.load takes the plugin type, context, export name and base class as options and is used by the controller, host, instance, ctl, web interface and migrations. Module imports go through #plugin_module so the node variant stays out of the web bundle. loadPlugin.ts and the loading half of plugin_loader.ts are merged into it. The loader lives for one load. Plugins reach it through context.plugins, with waitFor(name, timeoutMs) and checkInstalled(name), replacing the waitForPlugin methods. Waiting on a plugin that is not in the load list or failed to load settles right away, as loading can't finish while the waiting entrypoint is still running. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
7f688d2ed0
commit
c1ea4d470b
20 files changed
+500
-522
No files matched your search
@@ -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";
|
||||
|
||||
|
||||
@@ -25,7 +25,6 @@ export * from "./src/permissions.js";
|
||||
export * from "./src/plugin.js";
|
||||
export * from "./src/plugin_loader.js";
|
||||
export * from "./src/PluginLoader.js";
|
||||
export * from "./src/loadPlugin.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"
|
||||
},
|
||||
"#plugin_module": {
|
||||
"node": {
|
||||
"types": "./src/plugin_module.node.ts",
|
||||
"default": "./dist/node/src/plugin_module.node.js"
|
||||
},
|
||||
"import": "./src/plugin_module.browser.ts"
|
||||
},
|
||||
"#is_deep_strict_equal": {
|
||||
"node": {
|
||||
"types": "./src/is_deep_strict_equal.node.ts",
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
import { logger as defaultLogger, type Logger } from "./logging.js";
|
||||
import type { PluginNodeEnvInfo } from "./plugin.js";
|
||||
// Shared by node and the web interface, node specifics go in #plugin_module
|
||||
import importPluginModule from "#plugin_module";
|
||||
import { PluginError } from "./errors.js";
|
||||
import type { Logger } from "./logging.js";
|
||||
import type { PluginClass, PluginDeclaration, PluginLoadContext, PluginRegistry, PluginType } from "./plugin.js";
|
||||
|
||||
type Waiter = {
|
||||
resolve: (api: unknown) => void,
|
||||
@@ -7,80 +10,164 @@ type Waiter = {
|
||||
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 */
|
||||
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
|
||||
*
|
||||
* Owned by the object plugins are loaded into (controller, host or
|
||||
* instance).
|
||||
* Created for one load of plugins with {@link PluginLoader.load}.
|
||||
*/
|
||||
export class PluginLoader {
|
||||
export class PluginLoader<Context extends object, Info extends PluginDeclaration> {
|
||||
private _apis = new Map<string, unknown>();
|
||||
private _waiters = new Map<string, Waiter[]>();
|
||||
private _finished = false;
|
||||
private _installed: Set<string>;
|
||||
/** Plugins still loading */
|
||||
private _pending: Set<string>;
|
||||
|
||||
constructor(
|
||||
private _logger: Logger = defaultLogger,
|
||||
) {}
|
||||
private constructor(
|
||||
private _options: PluginLoadOptions<Context, Info>,
|
||||
) {
|
||||
this._installed = new Set(_options.installed.map(pluginInfo => pluginInfo.name));
|
||||
this._pending = new Set(_options.load.map(pluginInfo => pluginInfo.name));
|
||||
}
|
||||
|
||||
/**
|
||||
* Load plugins concurrently
|
||||
*
|
||||
* Waits for all loads to settle, then throws the error of the first
|
||||
* plugin in the list that failed.
|
||||
* 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 pluginInfos - Plugins to load.
|
||||
* @param loadPlugin - Loads one plugin and returns what its entrypoint returned.
|
||||
* @param options - What to load and how.
|
||||
* @returns Loaded and failed plugins.
|
||||
*/
|
||||
async load(pluginInfos: PluginNodeEnvInfo[], loadPlugin: (pluginInfo: PluginNodeEnvInfo) => Promise<unknown>) {
|
||||
try {
|
||||
const results = await Promise.allSettled(pluginInfos.map(async pluginInfo => {
|
||||
this._loaded(pluginInfo.name, await loadPlugin(pluginInfo));
|
||||
}));
|
||||
const failed = results.find(result => result.status === "rejected");
|
||||
if (failed) {
|
||||
throw failed.reason;
|
||||
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;
|
||||
}
|
||||
} finally {
|
||||
this._finish();
|
||||
}));
|
||||
|
||||
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 importPluginModule(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 _loaded(name: string, api: unknown) {
|
||||
this._apis.set(name, api);
|
||||
private _registry(waiter: string): PluginRegistry {
|
||||
return {
|
||||
waitFor: (name, timeoutMs) => this._waitFor(waiter, name, timeoutMs),
|
||||
checkInstalled: name => this._installed.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 _finish() {
|
||||
this._finished = true;
|
||||
for (const [name, entries] of this._waiters) {
|
||||
for (const entry of entries) {
|
||||
clearTimeout(entry.timeout);
|
||||
this._warnNotLoaded(entry.waiter, name);
|
||||
entry.resolve(undefined);
|
||||
}
|
||||
}
|
||||
this._waiters.clear();
|
||||
}
|
||||
|
||||
/**
|
||||
* Wait for a plugin to load
|
||||
*
|
||||
* @param waiter - Name of the plugin waiting, used in warnings.
|
||||
* @param name - Name of the plugin to wait for.
|
||||
* @param timeoutMs - Time to wait before giving up.
|
||||
* @returns
|
||||
* What the plugin's entrypoint returned, or undefined with a
|
||||
* warning logged if it did not load.
|
||||
*/
|
||||
waitFor<T = unknown>(waiter: string, name: string, timeoutMs = 30_000): Promise<T | undefined> {
|
||||
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._finished) {
|
||||
if (!this._pending.has(name)) {
|
||||
this._warnNotLoaded(waiter, name);
|
||||
return Promise.resolve(undefined);
|
||||
}
|
||||
@@ -92,7 +179,9 @@ export class PluginLoader {
|
||||
timeout: setTimeout(() => {
|
||||
const entries = this._waiters.get(name)!;
|
||||
entries.splice(entries.indexOf(entry), 1);
|
||||
this._logger.warn(`Plugin ${waiter} timed out after ${timeoutMs}ms waiting for plugin ${name}`);
|
||||
this._options.logger.warn(
|
||||
`Plugin ${waiter} timed out after ${timeoutMs}ms waiting for plugin ${name}`
|
||||
);
|
||||
resolve(undefined);
|
||||
}, timeoutMs),
|
||||
};
|
||||
@@ -106,6 +195,32 @@ export class PluginLoader {
|
||||
}
|
||||
|
||||
private _warnNotLoaded(waiter: string, name: string) {
|
||||
this._logger.warn(`Plugin ${waiter} waited for plugin ${name} which is not loaded`);
|
||||
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;
|
||||
}
|
||||
@@ -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`);
|
||||
}
|
||||
|
||||
return await init(context) as unknown;
|
||||
}
|
||||
|
||||
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,29 @@ 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;
|
||||
}
|
||||
|
||||
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 */
|
||||
|
||||
@@ -8,8 +8,8 @@ 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 { logger } from "./logging.js";
|
||||
import { PluginLoader } from "./PluginLoader.js";
|
||||
import { Config } from "./config/classes.js";
|
||||
import { ControllerConfig, HostConfig, InstanceConfig } from "./config/definitions.js";
|
||||
import Role from "./data/Role.js";
|
||||
@@ -217,59 +217,12 @@ export async function loadPluginMigrations(pluginInfos: libPlugin.PluginNodeEnvI
|
||||
|
||||
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") {
|
||||
return await loadPluginEntrypoint(pluginInfo, pluginType, pluginContext, module);
|
||||
}
|
||||
|
||||
// migrate: accept plugins which export classes
|
||||
if (module[exportName]) {
|
||||
pluginContext.logger.warn(`Plugin ${pluginInfo.name} is using deprecated class export`);
|
||||
return await loadPluginClass(pluginInfo, pluginType, pluginContext, module, exportName, baseClass);
|
||||
}
|
||||
|
||||
throw new Error(`Plugin ${pluginInfo.name} must export either a default function or ${exportName} class`);
|
||||
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 importPluginModule(
|
||||
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 importPluginModule(
|
||||
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);
|
||||
}
|
||||
@@ -25,7 +25,8 @@
|
||||
"./src/logging.ts",
|
||||
"./src/permissions.ts",
|
||||
"./src/prometheus.ts",
|
||||
"./src/loadPlugin.ts",
|
||||
"./src/PluginLoader.ts",
|
||||
"./src/plugin_module.browser.ts",
|
||||
"./src/plugin.ts",
|
||||
"./src/schema.ts",
|
||||
"./src/subscriptions.ts",
|
||||
|
||||
Reference in new issue
Block a user