Add waitForPlugin and load plugins concurrently

Plugins can wait for another plugin on the same controller, host or
instance with waitForPlugin(waiter, name, timeoutMs). It resolves to what
the other plugin's entrypoint returned, or to undefined with a warning
naming both plugins if it is not loaded once loading finishes or the
timeout runs out.

Plugin entrypoints now run concurrently so a plugin can await a plugin
later in the list from its entrypoint. loadedPlugins is still filled in
plugin list order, as the instance builds its Lua module list from it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-11-19 14:24:56 +00:00
1 parent eefb4be44b
commit c8e52e7bde
12 files changed
+408 -29

No files matched your search

+28 -5
View File
@@ -77,6 +77,7 @@ export default class Controller {
hooks = new ControllerHooks(logger);
/** Plugins which are currently loaded */
loadedPlugins: Set<lib.PluginNodeEnvInfo> = new Set();
private _pluginLoader = new lib.PluginLoader(logger);
/** Latest versions of plugins on npm, as shown on the plugins page */
pluginLatestVersionCache: lib.LatestVersionCache = new Map();
@@ -1317,8 +1318,22 @@ export default class Controller {
}
}
/**
* Wait for another 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.
*/
waitForPlugin<T = unknown>(waiter: string, name: string, timeoutMs?: number) {
return this._pluginLoader.waitFor<T>(waiter, name, timeoutMs);
}
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");
@@ -1341,17 +1356,20 @@ export default class Controller {
continue;
}
toLoad.push(pluginInfo);
}
const context = { metrics, logger, controller: this };
await this._pluginLoader.load(toLoad, async pluginInfo => {
let api;
try {
await lib.loadPlugin(
api = await lib.loadPlugin(
pluginInfo,
"controller",
context,
"ControllerPlugin",
BaseControllerPlugin,
);
this.loadedPlugins.add(pluginInfo);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
@@ -1360,6 +1378,11 @@ export default class Controller {
}
logger.info(`Loaded plugin ${pluginInfo.name}`);
return api;
});
for (const pluginInfo of toLoad) {
this.loadedPlugins.add(pluginInfo);
}
}
+28 -5
View File
@@ -331,6 +331,7 @@ export default class Host extends lib.Link {
hooks = new HostHooks(logger);
/** Plugins which are currently loaded */
loadedPlugins: Set<lib.PluginNodeEnvInfo> = new Set();
private _pluginLoader = new lib.PluginLoader(logger);
/** A map from instance id to instance connection. Only present when instance is running. */
instanceConnections = new Map<number, InstanceConnection>();
@@ -487,8 +488,22 @@ export default class Host extends lib.Link {
this.handle(lib.InstanceDeleteInternalRequest, this.handleInstanceDeleteInternalRequest.bind(this));
}
/**
* Wait for another host 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 host entrypoint returned, or undefined with
* a warning logged if it did not load.
*/
waitForPlugin<T = unknown>(waiter: string, name: string, timeoutMs?: number) {
return this._pluginLoader.waitFor<T>(waiter, name, timeoutMs);
}
async loadPlugins() {
const context = { logger, host: this };
const toLoad: lib.PluginNodeEnvInfo[] = [];
for (let pluginInfo of this.pluginInfos) {
if (
!pluginInfo.hostEntrypoint && !pluginInfo.instanceEntrypoint
@@ -502,17 +517,20 @@ export default class Host extends lib.Link {
continue;
}
toLoad.push(pluginInfo);
}
const context = { logger, host: this };
await this._pluginLoader.load(toLoad, async pluginInfo => {
let api;
try {
await lib.loadPlugin(
api = await lib.loadPlugin(
pluginInfo,
"host",
context,
"HostPlugin",
BaseHostPlugin,
);
this.loadedPlugins.add(pluginInfo);
} catch (err: any) {
if (err.code === "InstallationError") {
throw err;
@@ -521,6 +539,11 @@ export default class Host extends lib.Link {
}
logger.info(`Loaded plugin ${pluginInfo.name}`);
return api;
});
for (const pluginInfo of toLoad) {
this.loadedPlugins.add(pluginInfo);
}
}
+34 -12
View File
@@ -181,6 +181,7 @@ export default class Instance extends lib.Link {
hooks: InstanceHooks;
/** Plugins which are currently loaded */
loadedPlugins: Set<lib.PluginNodeEnvInfo> = new Set();
private _pluginLoader: lib.PluginLoader;
_host: Host;
@@ -211,6 +212,7 @@ export default class Instance extends lib.Link {
this.id = this.config.get("instance.id");
this.logger = instanceLogger(instanceConfig);
this._pluginLoader = new lib.PluginLoader(this.logger);
this.hooks = new InstanceHooks(this.logger);
@@ -766,14 +768,27 @@ end`.replace(/\r?\n/g, " ");
return instance;
}
/**
* Wait for another instance 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 instance entrypoint returned, or undefined with
* a warning logged if it did not load.
*/
waitForPlugin<T = unknown>(waiter: string, name: string, timeoutMs?: number) {
return this._pluginLoader.waitFor<T>(waiter, name, timeoutMs);
}
/**
* Load the instance plugins and report the instance as initialised
*
* 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
@@ -788,26 +803,33 @@ end`.replace(/\r?\n/g, " ");
continue;
}
try {
toLoad.push(pluginInfo);
}
try {
await this._pluginLoader.load(toLoad, async pluginInfo => {
let pluginLoadStartedMs = Date.now();
await lib.loadPlugin(
const api = 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;
}
return api;
});
} catch (err) {
this.notifyExit();
await this.sendSaveListUpdate();
throw err;
}
const plugins: Record<string, string> = {};
for (const pluginInfo of toLoad) {
this.loadedPlugins.add(pluginInfo);
plugins[pluginInfo.name] = pluginInfo.version;
}
this.send(new lib.InstanceInitialisedEvent(plugins));
}
+1
View File
@@ -24,6 +24,7 @@ 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/PluginLoader.js";
export * from "./src/loadPlugin.js";
export * from "./src/prometheus.js";
export * from "./src/schema.js";
+111
View File
@@ -0,0 +1,111 @@
import { logger as defaultLogger, type Logger } from "./logging.js";
import type { PluginNodeEnvInfo } from "./plugin.js";
type Waiter = {
resolve: (api: unknown) => void,
timeout: ReturnType<typeof setTimeout>,
waiter: string,
};
/**
* Loads plugins concurrently and lets them wait for each other
*
* Owned by the object plugins are loaded into (controller, host or
* instance).
*/
export class PluginLoader {
private _apis = new Map<string, unknown>();
private _waiters = new Map<string, Waiter[]>();
private _finished = false;
constructor(
private _logger: Logger = defaultLogger,
) {}
/**
* Load plugins concurrently
*
* Waits for all loads to settle, then throws the error of the first
* plugin in the list that failed.
*
* @param pluginInfos - Plugins to load.
* @param loadPlugin - Loads one plugin and returns what its entrypoint returned.
*/
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;
}
} finally {
this._finish();
}
}
private _loaded(name: string, api: unknown) {
this._apis.set(name, api);
for (const entry of this._waiters.get(name) ?? []) {
clearTimeout(entry.timeout);
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> {
if (this._apis.has(name)) {
return Promise.resolve(this._apis.get(name) as T);
}
if (this._finished) {
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._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._logger.warn(`Plugin ${waiter} waited for plugin ${name} which is not loaded`);
}
}
+1 -1
View File
@@ -17,7 +17,7 @@ export async function loadPluginEntrypoint<
throw new Error(`Expected ${pluginType} plugin ${pluginInfo.name} to export a default function`);
}
await init(context);
return await init(context) as unknown;
}
export async function loadPluginClass<
+2 -4
View File
@@ -256,15 +256,13 @@ export async function loadPlugin<
};
if (typeof module.default === "function") {
await loadPluginEntrypoint(pluginInfo, pluginType, pluginContext, module);
return;
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`);
await loadPluginClass(pluginInfo, pluginType, pluginContext, module, exportName, baseClass);
return;
return await loadPluginClass(pluginInfo, pluginType, pluginContext, module, exportName, baseClass);
}
throw new Error(`Plugin ${pluginInfo.name} must export either a default function or ${exportName} class`);