Add typed hook system for plugins

Replace invokeHook and the per plugin on* methods with AsyncHook
collections on the controller, host, instance, clusterioctl and web
control objects. Plugin entrypoints export a default function that
receives a load context and attaches handlers to the hooks it needs.
Class exports still load through fromContext with a deprecation
warning. The create templates and docs use the entrypoint function.

This is clusterio/clusterio#921 recreated on top of master after the
ESM migration and the PluginDeclaration permissions change.

Closes #730

Co-Authored-By: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
committed 2026-09-11 22:49:09 +00:00
1 parent 8c03ac15ab
commit 7122cbccf8
64 files changed
+1878 -1184

No files matched your search

+34 -39
View File
@@ -13,7 +13,7 @@ import { FactorioServer } from "./server.js";
import { SaveModule, patch } from "./patch.js";
import { exportData } from "./export.js";
import type Host from "./Host.js";
import BaseInstancePlugin from "./BaseInstancePlugin.js";
import { BaseInstancePlugin, InstanceHooks } from "./BaseInstancePlugin.js";
const scriptCommands = [
"/cheat", "/editor",
@@ -140,7 +140,6 @@ export default class Instance extends lib.Link {
* ID of this instance, equivalenet to `instance.config.get("instance.id")`.
*/
readonly id: number;
plugins: Map<string, BaseInstancePlugin>;
config: lib.InstanceConfig;
logger: lib.Logger;
server: FactorioServer;
@@ -156,6 +155,10 @@ export default class Instance extends lib.Link {
* Players currently online on the instance.
*/
playersOnline: Set<string> = new Set();
/** Hooks which plugins can attach to */
hooks: InstanceHooks;
/** Plugins which are currently loaded */
loadedPlugins: Set<lib.PluginNodeEnvInfo> = new Set();
_host: Host;
@@ -179,7 +182,6 @@ export default class Instance extends lib.Link {
this._host = host;
this._dir = dir;
this.plugins = new Map();
this.config = instanceConfig;
this.id = this.config.get("instance.id");
@@ -189,8 +191,10 @@ export default class Instance extends lib.Link {
instance_name: this.name,
});
this.hooks = new InstanceHooks(this.logger);
this._configFieldChanged = (field: string, curr: unknown, prev: unknown) => {
let hook = () => lib.invokeHook(this.plugins, "onInstanceConfigFieldChanged", field, curr, prev);
let hook = () => this.hooks.instanceConfigFieldChanged.invoke(field, curr, prev);
if (field === "factorio.shutdown_timeout") {
this.server.shutdownTimeoutMs = curr as number * 1000;
@@ -231,7 +235,7 @@ export default class Instance extends lib.Link {
this.server.on("output", (parsed, line) => {
this.logger.log("server", { message: line, instance_id: this.id, parsed });
lib.invokeHook(this.plugins, "onOutput", parsed, line);
this.hooks.output.invoke(parsed, line);
});
this.server.on("error", err => {
@@ -398,7 +402,7 @@ export default class Instance extends lib.Link {
stats,
};
this.sendTo("controller", new lib.InstancePlayerUpdateEvent("join", name, stats));
lib.invokeHook(this.plugins, "onPlayerEvent", event);
this.hooks.playerEvent.invoke(event);
}
_recordPlayerLeave(name: string, reason: string) {
@@ -419,7 +423,7 @@ export default class Instance extends lib.Link {
stats,
};
this.sendTo("controller", new lib.InstancePlayerUpdateEvent("leave", name, stats, reason));
lib.invokeHook(this.plugins, "onPlayerEvent", event);
this.hooks.playerEvent.invoke(event);
}
async handleInstanceExtractPlayersRequest() {
@@ -450,7 +454,7 @@ end`.replace(/\r?\n/g, " ");
stats,
};
this.sendTo("controller", new lib.InstancePlayerUpdateEvent("import", name, stats));
lib.invokeHook(this.plugins, "onPlayerEvent", event);
this.hooks.playerEvent.invoke(event);
count += 1;
}
this.logger.info(`Extracted data for ${count} player(s)`);
@@ -588,9 +592,7 @@ end`.replace(/\r?\n/g, " ");
}
// Notify plugins of exit
for (let pluginInstance of this.plugins.values()) {
pluginInstance.onExit();
}
this.hooks.exit.invoke();
for (let player of this.playersOnline) {
this._recordPlayerLeave(player, "server_quit");
@@ -598,21 +600,6 @@ end`.replace(/\r?\n/g, " ");
this._saveStats().catch(err => this.logger.error(`Error saving stats:\n${err.stack}`));
}
async _loadPlugin(pluginInfo: lib.PluginNodeEnvInfo, host: Host) {
let pluginLoadStartedMs = Date.now();
let InstancePluginClass = await lib.loadPluginClass(
pluginInfo.name,
path.posix.join(pluginInfo.requirePath, pluginInfo.instanceEntrypoint!),
"InstancePlugin",
BaseInstancePlugin,
);
let instancePlugin = new InstancePluginClass(pluginInfo, this, host);
this.plugins.set(pluginInfo.name, instancePlugin);
await instancePlugin.init();
this.logger.info(`Loaded plugin ${pluginInfo.name} in ${Date.now() - pluginLoadStartedMs}ms`);
}
async _loadStats() {
let instanceStats;
try {
@@ -667,6 +654,7 @@ end`.replace(/\r?\n/g, " ");
}
// load plugins
const plugins: Record<string, string> = {};
for (let pluginInfo of pluginInfos) {
if (
!pluginInfo.instanceEntrypoint
@@ -682,7 +670,18 @@ end`.replace(/\r?\n/g, " ");
}
try {
await this._loadPlugin(pluginInfo, this._host);
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();
@@ -690,10 +689,6 @@ end`.replace(/\r?\n/g, " ");
}
}
let plugins: Record<string, string> = {};
for (let [name, plugin] of this.plugins) {
plugins[name] = plugin.info.version;
}
this.send(new lib.InstanceInitialisedEvent(plugins));
}
@@ -953,8 +948,8 @@ end`.replace(/\r?\n/g, " ");
// Find plugin modules to patch in
let modules: Map<string, SaveModule> = new Map();
for (let plugin of this.plugins.values()) {
let module = await SaveModule.fromPlugin(plugin);
for (const pluginInfo of this.loadedPlugins) {
let module = await SaveModule.fromPluginInfo(pluginInfo);
if (!module) {
continue;
}
@@ -1008,7 +1003,7 @@ end`.replace(/\r?\n/g, " ");
}
await this.sendSaveListUpdate();
await lib.invokeHook(this.plugins, "onStart");
await this.hooks.start.invoke();
this.notifyStatus("running");
}
@@ -1033,7 +1028,7 @@ end`.replace(/\r?\n/g, " ");
await this.server.startScenario(scenario, seed, mapGenSettings, mapSettings);
this._watchServerLogActions();
await lib.invokeHook(this.plugins, "onStart");
await this.hooks.start.invoke();
this.notifyStatus("running");
}
@@ -1169,7 +1164,7 @@ end`.replace(/\r?\n/g, " ");
// XXX this needs more thought to it
if (this.server._state === "running") {
await lib.invokeHook(this.plugins, "onStop");
await this.hooks.stop.invoke();
await this.server.stop();
await this.sendSaveListUpdate();
} else if (
@@ -1188,17 +1183,17 @@ end`.replace(/\r?\n/g, " ");
}
async handleControllerConnectionEvent(event: lib.ControllerConnectionEvent) {
await lib.invokeHook(this.plugins, "onControllerConnectionEvent", event.event);
await this.hooks.controllerConnectionEvent.invoke(event.event);
}
async handlePrepareControllerDisconnectRequest() {
await lib.invokeHook(this.plugins, "onPrepareControllerDisconnect", this);
await this.hooks.prepareControllerDisconnect.invoke(this);
}
async handleInstanceMetricsRequest() {
let results: ReturnType<typeof lib.serializeResult>[] = [];
if (!["stopped", "stopping"].includes(this._status)) {
let pluginResults = await lib.invokeHook(this.plugins, "onMetrics");
let pluginResults = await this.hooks.metrics.collect();
for (let metricIterator of pluginResults) {
for await (let metric of metricIterator) {
results.push(lib.serializeResult(metric));