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

+60
View File
@@ -239,6 +239,66 @@ describe("controller/src/Controller", function() {
});
});
});
describe(".waitForPlugin()", 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, plugin }) {
controller.lateApi = await controller.waitForPlugin(plugin.name, "wait_late");
}`,
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 resolve to what a plugin later in the list returned", async function() {
const pluginsController = pluginController();
await pluginsController.loadPlugins();
assert.deepEqual(pluginsController.lateApi, { late: true });
assert.deepEqual(await pluginsController.waitForPlugin("test", "wait_late"), { late: true });
});
it("should resolve undefined once loading finishes for plugins not loaded", async function() {
const pluginsController = pluginController();
const off = pluginsController.waitForPlugin("test", "wait_off", 60_000);
const missing = pluginsController.waitForPlugin("test", "missing", 60_000);
await pluginsController.loadPlugins();
assert.equal(await off, undefined);
assert.equal(await missing, undefined);
});
it("should resolve undefined once loading finishes in recovery mode", async function() {
const pluginsController = pluginController(true);
const late = pluginsController.waitForPlugin("test", "wait_late", 60_000);
await pluginsController.loadPlugins();
assert.equal(await late, undefined);
});
});
describe(".validateExports()", function() {
let dir;
before(async function() {
+36
View File
@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
import dgram from "node:dgram";
import events from "node:events";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -250,6 +251,41 @@ describe("host/src/Host", function() {
assert.equal(host.config.restartRequired, true);
});
});
describe(".waitForPlugin()", 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, plugin }) {
host.lateApi = await host.waitForPlugin(plugin.name, "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 resolve to what a host plugin later in the list returned", 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);
const missing = host.waitForPlugin("test", "missing", 60_000);
await host.loadPlugins();
assert.deepEqual(host.lateApi, { late: true });
assert.equal(await missing, undefined);
});
});
describe(".assignFreeGamePort()", function() {
let host;
let held;
+72
View File
@@ -0,0 +1,72 @@
import assert from "node:assert/strict";
import * as lib from "@clusterio/lib";
describe("lib/PluginLoader", function() {
let logger;
let loader;
beforeEach(function() {
logger = { warnings: [], warn(msg) { this.warnings.push(msg); } };
loader = new lib.PluginLoader(logger);
});
const infos = (...names) => names.map(name => ({ name }));
it("should let a plugin await a plugin later in the list while loading", async function() {
const apis = { b: { b: true } };
await loader.load(infos("a", "b"), async ({ name }) => {
if (name === "a") {
apis.a = { gotB: await loader.waitFor("a", "b") };
}
return apis[name];
});
assert.deepEqual(apis.a, { gotB: { b: true } });
assert.equal(await loader.waitFor("c", "a"), apis.a);
assert.deepEqual(logger.warnings, []);
});
it("should resolve undefined with a warning once loading finishes without the plugin", async function() {
const result = loader.waitFor("a", "b");
await loader.load(infos("c"), async () => ({}));
assert.equal(await result, undefined);
assert.equal(await loader.waitFor("a", "d"), undefined);
assert.deepEqual(logger.warnings, [
"Plugin a waited for plugin b which is not loaded",
"Plugin a waited for plugin d which is not loaded",
]);
});
it("should resolve undefined with a warning on timeout", async function() {
const result = loader.waitFor("a", "b", 10);
const other = loader.waitFor("c", "b");
assert.equal(await result, undefined);
assert.deepEqual(logger.warnings, ["Plugin a timed out after 10ms waiting for plugin b"]);
await loader.load(infos("b"), async () => "api");
assert.equal(await other, "api");
});
it("should break a wait cycle with the timeout", async function() {
const got = {};
await loader.load(infos("a", "b"), async ({ name }) => {
got[name] = await loader.waitFor(name, name === "a" ? "b" : "a", name === "a" ? 10 : 1000);
return name;
});
assert.deepEqual(got, { a: undefined, b: "a" });
assert.deepEqual(logger.warnings, ["Plugin a timed out after 10ms waiting for plugin b"]);
});
it("should finish loading the rest before throwing the first error in list order", async function() {
const loaded = [];
await assert.rejects(
loader.load(infos("a", "b", "c"), async ({ name }) => {
if (name === "a") {
await new Promise(resolve => setTimeout(resolve, 10));
throw new Error("a failed");
}
if (name === "b") {
throw new Error("b failed");
}
loaded.push(name);
return name;
}),
{ message: "a failed" },
);
assert.deepEqual(loaded, ["c"]);
assert.equal(await loader.waitFor("x", "a"), undefined);
assert.deepEqual(logger.warnings, ["Plugin x waited for plugin a which is not loaded"]);
});
});
+9 -2
View File
@@ -185,6 +185,7 @@ describe("lib/plugin_loader", function() {
await writeEntrypoint(functionPlugin, `
export default async function(context) {
context.controller.loadedWith = context;
return { api: true };
}
`);
await writeEntrypoint(classPlugin, `
@@ -231,7 +232,10 @@ describe("lib/plugin_loader", function() {
});
it("should call the default export with the load context", async function() {
const pluginInfo = info(functionPlugin);
await lib.loadPlugin(pluginInfo, "controller", context, "ControllerPlugin", BaseControllerPlugin);
const result = await lib.loadPlugin(
pluginInfo, "controller", context, "ControllerPlugin", BaseControllerPlugin,
);
assert.deepEqual(result, { api: true });
assert.equal(controller.loadedWith.controller, controller);
assert.equal(controller.loadedWith.plugin, pluginInfo);
assert.equal(controller.loadedWith.logger, logger);
@@ -239,7 +243,10 @@ describe("lib/plugin_loader", function() {
});
it("should load a deprecated class export", async function() {
const pluginInfo = info(classPlugin);
await lib.loadPlugin(pluginInfo, "controller", context, "ControllerPlugin", BaseControllerPlugin);
const result = await lib.loadPlugin(
pluginInfo, "controller", context, "ControllerPlugin", BaseControllerPlugin,
);
assert.equal(result, controller.loadedWith);
assert(controller.loadedWith instanceof BaseControllerPlugin);
assert.equal(controller.loadedWith.info, pluginInfo);
assert.deepEqual([...controller.hooks.save.attached], ["test"]);