Write plugins without state shared elsewhere as functions (#492)

The instance plugins of exp_groups, exp_reports, exp_roles, exp_scenario
and exp_server_ups, and the controller plugins of exp_reports and
exp_scenario, were classes only to hold their handlers. They are now
init functions with closures, like clusterio's own plugins.

The exp_roles and exp_groups controller plugins stay classes because
exp_scenario reaches their datastores through get(controller).
AutoRestart stays a class because its tests step check() with a fake
clock.

Tests spy on handle() and the hooks to call the handlers. The reports
webhook tests stub fetch instead of replacing postWebhook, and the
feature reconcile test writes the stored records to disk before start.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
BastiaanandClaude Opus 5.5 authored and GitHub committed 2026-10-13 21:50:15 +01:00
1 parent 26a801da5e
commit 68a964cf57
12 files changed
+709 -820

No files matched your search

+90 -63
View File
@@ -1,7 +1,7 @@
import t from "tap";
import * as lib from "@clusterio/lib";
import { Controller, InstanceRecord } from "@clusterio/controller";
import entrypoint, { ControllerPlugin } from "../dist/node/controller.js";
import entrypoint from "../dist/node/controller.js";
import * as messages from "../dist/node/messages.js";
import { plugin as pluginDeclaration } from "../dist/node/index.js";
@@ -24,7 +24,7 @@ const fromInstance = lib.Address.fromShorthand({ instanceId: 1 });
const fromUnknownInstance = lib.Address.fromShorthand({ instanceId: 9 });
const fromControl = lib.Address.fromShorthand({ controlId: 7 });
/** Build the plugin around a real controller, which is side effect free while not started. */
/** Run the plugin on a real controller, which is side effect free while not started, returns the handlers it registered. */
async function startPlugin(t2, { config = {} } = {}) {
const controllerConfig = new lib.ControllerConfig("controller", {
"controller.database_directory": t2.testdir(),
@@ -46,12 +46,45 @@ async function startPlugin(t2, { config = {} } = {}) {
broadcast(event);
};
const realFetch = globalThis.fetch;
globalThis.fetch = async (url, init) => {
state.posts.push({ url, body: JSON.parse(init.body) });
return state.fetchResult();
};
state.fetchResult = () => ({ ok: true, status: 200 });
t2.teardown(() => { globalThis.fetch = realFetch; });
const handlers = new Map();
const handle = controller.handle.bind(controller);
controller.handle = (Class, handler) => {
handlers.set(Class, handler);
handle(Class, handler);
};
const subscriptionHandle = controller.subscriptions.handle.bind(controller.subscriptions);
controller.subscriptions.handle = (Class, handler) => {
handlers.set(Class, handler);
subscriptionHandle(Class, handler);
};
const pluginLogger = { ...logger, warn: message => state.warnings.push(message) };
const plugin = await ControllerPlugin.fromContext({ plugin: { name: "exp_reports" }, controller, logger: pluginLogger });
plugin.postWebhook = async (url, body) => { state.posts.push({ url, body }); };
return { plugin, controller, state };
await entrypoint({ plugin: { name: "exp_reports" }, controller, logger: pluginLogger });
const request = (Request, ...args) => handlers.get(Request)(new Request(...args), fromInstance);
return {
controller,
state,
create: (playerName, reason, byPlayerName, src = fromInstance) => handlers.get(messages.ReportCreateRequest)(
new messages.ReportCreateRequest(playerName, reason, byPlayerName), src,
),
list: playerName => request(messages.ReportListRequest, playerName),
get: id => request(messages.ReportGetRequest, id),
remove: id => request(messages.ReportDeleteRequest, id),
subscription: lastRequestTimeMs => handlers.get(messages.ReportUpdatedEvent)({ lastRequestTimeMs }),
};
}
/** Let the webhook posts which are not awaited finish. */
const settle = () => new Promise(resolve => setImmediate(resolve));
t.test("entrypoint", async t2 => {
const controllerConfig = new lib.ControllerConfig("controller", { "controller.database_directory": t2.testdir() });
const controller = new Controller(logger, [], controllerConfig);
@@ -62,108 +95,102 @@ t.test("entrypoint", async t2 => {
await controller.hooks.shutdown.invoke();
});
t.test("class ControllerPlugin", t2 => {
t2.test(".handleReportCreateRequest() from an instance records the instance and the reporter", async t3 => {
const { plugin } = await startPlugin(t3);
const report = await plugin.handleReportCreateRequest(
new messages.ReportCreateRequest("bob", " griefing ", "alice"), fromInstance,
);
t.test("controller plugin", t2 => {
t2.test("ReportCreateRequest from an instance records the instance and the reporter", async t3 => {
const { create, list } = await startPlugin(t3);
const report = await create("bob", " griefing ", "alice", fromInstance);
t3.strictSame(report.playerName, "bob");
t3.strictSame(report.byPlayerName, "alice", "the reporter comes from the request");
t3.strictSame(report.reason, "griefing", "the reason is trimmed");
t3.strictSame(report.instanceName, "EXP", "the instance is named");
t3.ok(report.updatedAtMs > 0, "the report is timestamped");
t3.strictSame(plugin.listReports(), [report], "the report is stored");
t3.strictSame(await list(), [report], "the report is stored");
const unknown = await plugin.handleReportCreateRequest(
new messages.ReportCreateRequest("carol", "spam", "alice"), fromUnknownInstance,
);
const unknown = await create("carol", "spam", "alice", fromUnknownInstance);
t3.strictSame(unknown.instanceName, "9", "an unknown instance is named by its id");
});
t2.test(".handleReportCreateRequest() from the web ui uses the user of the connection", async t3 => {
const { plugin } = await startPlugin(t3);
const report = await plugin.handleReportCreateRequest(
new messages.ReportCreateRequest("bob", "griefing", "someone-else"), fromControl,
);
t2.test("ReportCreateRequest from the web ui uses the user of the connection", async t3 => {
const { create } = await startPlugin(t3);
const report = await create("bob", "griefing", "someone-else", fromControl);
t3.strictSame(report.byPlayerName, "admin", "the reporter is the connected user");
t3.strictSame(report.instanceName, "", "there is no instance");
});
t2.test(".handleReportCreateRequest() rejects reports which can not be stored", async t3 => {
const { plugin } = await startPlugin(t3);
await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "griefing", "alice"), fromInstance);
t2.test("ReportCreateRequest rejects reports which can not be stored", async t3 => {
const { create, list } = await startPlugin(t3);
await create("bob", "griefing", "alice", fromInstance);
await t3.rejects(
plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "again", "alice"), fromInstance),
create("bob", "again", "alice", fromInstance),
{ message: "alice has already reported bob" },
"a player can only report another once",
);
await t3.rejects(
plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", " ", "carol"), fromInstance),
create("bob", " ", "carol", fromInstance),
{ message: "A report needs a reason" },
"a reason is required",
);
await t3.rejects(
plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "spam", ""), fromInstance),
create("bob", "spam", "", fromInstance),
{ message: "A report needs the name of the player making it" },
"an instance must name the reporter",
);
t3.strictSame(plugin.listReports().length, 1, "nothing else was stored");
t3.strictSame((await list()).length, 1, "nothing else was stored");
});
t2.test(".handleReportListRequest() and .handleReportGetRequest() find reports", async t3 => {
const { plugin } = await startPlugin(t3);
const first = await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "griefing", "alice"), fromInstance);
await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("carol", "spam", "alice"), fromInstance);
t2.test("ReportListRequest and ReportGetRequest find reports", async t3 => {
const { create, list, get } = await startPlugin(t3);
const first = await create("bob", "griefing", "alice", fromInstance);
await create("carol", "spam", "alice", fromInstance);
t3.strictSame((await plugin.handleReportListRequest(new messages.ReportListRequest())).length, 2, "everything is listed");
t3.strictSame((await list()).length, 2, "everything is listed");
t3.strictSame(
await plugin.handleReportListRequest(new messages.ReportListRequest("bob")), [first],
await list("bob"), [first],
"a player's reports are listed",
);
t3.strictSame(await plugin.handleReportGetRequest(new messages.ReportGetRequest(first.id)), first);
t3.strictSame(await get(first.id), first);
await t3.rejects(
plugin.handleReportGetRequest(new messages.ReportGetRequest(123)),
get(123),
{ message: "Report with ID 123 does not exist" },
);
});
t2.test(".handleReportDeleteRequest() removes the report and broadcasts the deletion", async t3 => {
const { plugin, state } = await startPlugin(t3);
const report = await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "griefing", "alice"), fromInstance);
t2.test("ReportDeleteRequest removes the report and broadcasts the deletion", async t3 => {
const { create, list, remove, state } = await startPlugin(t3);
const report = await create("bob", "griefing", "alice", fromInstance);
state.broadcasts.length = 0;
await plugin.handleReportDeleteRequest(new messages.ReportDeleteRequest(report.id));
t3.strictSame(plugin.listReports(), [], "the report is gone");
await remove(report.id);
t3.strictSame(await list(), [], "the report is gone");
t3.ok(
state.broadcasts.some(event => event instanceof messages.ReportUpdatedEvent && event.updates[0].isDeleted),
"subscribers are told it was deleted",
);
await t3.rejects(
plugin.handleReportDeleteRequest(new messages.ReportDeleteRequest(report.id)),
remove(report.id),
{ message: `Report with ID ${report.id} does not exist` },
);
});
t2.test(".handleReportSubscription() replays only newer records", async t3 => {
const { plugin } = await startPlugin(t3);
const report = await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "griefing", "alice"), fromInstance);
t2.test("subscribing replays only newer records", async t3 => {
const { create, subscription } = await startPlugin(t3);
const report = await create("bob", "griefing", "alice", fromInstance);
const all = await plugin.handleReportSubscription({ lastRequestTimeMs: 0 });
const all = await subscription(0);
t3.strictSame(all.updates, [report], "everything is replayed from the start");
const none = await plugin.handleReportSubscription({ lastRequestTimeMs: report.updatedAtMs });
const none = await subscription(report.updatedAtMs);
t3.strictSame(none, null, "nothing is replayed when up to date");
});
t2.test(".sendWebhooks() posts new reports to the configured hooks", async t3 => {
const { plugin, state } = await startPlugin(t3, { config: {
t2.test("new reports are posted to the configured hooks", async t3 => {
const { create, remove, state } = await startPlugin(t3, { config: {
"exp_reports.discord_webhook_url": "https://discord.example/hook",
"exp_reports.json_webhook_url": "https://json.example/hook",
} });
const report = await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "griefing", "alice"), fromInstance);
const report = await create("bob", "griefing", "alice", fromInstance);
t3.strictSame(state.posts.map(post => post.url), ["https://discord.example/hook", "https://json.example/hook"]);
const embed = state.posts[0].body.embeds[0];
@@ -171,29 +198,29 @@ t.test("class ControllerPlugin", t2 => {
t3.strictSame(state.posts[1].body, { type: "report_created", report: report.toJSON() }, "the json hook gets the record");
state.posts.length = 0;
await plugin.handleReportDeleteRequest(new messages.ReportDeleteRequest(report.id));
await remove(report.id);
t3.strictSame(state.posts, [], "deletions are not posted");
});
t2.test(".sendWebhooks() does nothing without hooks", async t3 => {
const { plugin, state } = await startPlugin(t3);
await plugin.handleReportCreateRequest(new messages.ReportCreateRequest("bob", "griefing", "alice"), fromInstance);
t2.test("nothing is posted without hooks", async t3 => {
const { create, state } = await startPlugin(t3);
await create("bob", "griefing", "alice", fromInstance);
t3.strictSame(state.posts, []);
});
t2.test(".postWebhook() logs rather than throws when the hook fails", async t3 => {
const { plugin, state } = await startPlugin(t3);
plugin.postWebhook = ControllerPlugin.prototype.postWebhook;
t2.test("webhooks log rather than throw when the hook fails", async t3 => {
const { create, state } = await startPlugin(t3, { config: {
"exp_reports.json_webhook_url": "https://down.example/hook",
} });
const realFetch = globalThis.fetch;
globalThis.fetch = async () => { throw new Error("connection refused"); };
t3.teardown(() => { globalThis.fetch = realFetch; });
await plugin.postWebhook("https://down.example/hook", {});
state.fetchResult = () => { throw new Error("connection refused"); };
await create("bob", "griefing", "alice");
await settle();
t3.strictSame(state.warnings, ["Webhook https://down.example/hook failed: connection refused"]);
globalThis.fetch = async () => ({ ok: false, status: 404 });
await plugin.postWebhook("https://down.example/hook", {});
state.fetchResult = () => ({ ok: false, status: 404 });
await create("bob", "griefing", "carol");
await settle();
t3.strictSame(state.warnings[1], "Webhook https://down.example/hook responded with 404");
});
+30 -23
View File
@@ -1,7 +1,7 @@
import t from "tap";
import * as lib from "@clusterio/lib";
import { Instance } from "@clusterio/host";
import { InstancePlugin } from "../dist/node/instance.js";
import entrypoint from "../dist/node/instance.js";
import { plugin as pluginDeclaration } from "../dist/node/index.js";
import * as messages from "../dist/node/messages.js";
@@ -25,7 +25,7 @@ class TestConnector extends lib.BaseConnector {
const report = (id, playerName, byPlayerName) => new messages.ReportRecord(id, playerName, byPlayerName, "griefing", "EXP", 1000);
/** Build a plugin around a real running instance with spies on what leaves it. */
/** Run the plugin on a real running instance with spies on what leaves it, returns the IPC handlers it registered. */
async function startPlugin(t2, { reports = [report(1, "bob", "alice"), report(2, "bob", "carol")] } = {}) {
const instanceConfig = new lib.InstanceConfig("host");
instanceConfig.set("instance.id", 1);
@@ -37,8 +37,9 @@ async function startPlugin(t2, { reports = [report(1, "bob", "alice"), report(2,
// Spies which record the messages and commands leaving the instance
const state = { sent: [], rcons: [], failNext: null };
const ipc = new Map();
instance.server = {
handle: () => {},
handle: (name, handler) => ipc.set(name, handler),
sendRcon: async command => {
state.rcons.push(command);
return "";
@@ -63,8 +64,14 @@ async function startPlugin(t2, { reports = [report(1, "bob", "alice"), report(2,
instance.notifyStatus("running");
state.sent.length = 0;
const plugin = await InstancePlugin.fromContext({ plugin: { name: "exp_reports" }, instance, host: {}, logger });
return { plugin, instance, state };
await entrypoint({ plugin: { name: "exp_reports" }, instance, host: {}, logger });
return {
instance,
state,
createIPC: event => ipc.get("exp_reports:create")(event),
listIPC: event => ipc.get("exp_reports:list")(event),
deleteIPC: event => ipc.get("exp_reports:delete")(event),
};
}
/** The lua receiver and payload of a recorded rcon command. */
@@ -73,10 +80,10 @@ function decodeRcon(command) {
return { receiver: match[1], payload: JSON.parse(match[2]) };
}
t.test("class InstancePlugin", t2 => {
t2.test(".handleCreateIPC() creates the report and hands it to lua with the others against the player", async t3 => {
const { plugin, state } = await startPlugin(t3);
await plugin.handleCreateIPC({ player_name: "bob", by_player_name: "dave", reason: "griefing" });
t.test("instance plugin", t2 => {
t2.test("exp_reports:create creates the report and hands it to lua with the others against the player", async t3 => {
const { state, createIPC } = await startPlugin(t3);
await createIPC({ player_name: "bob", by_player_name: "dave", reason: "griefing" });
const create = state.sent.find(request => request instanceof messages.ReportCreateRequest);
t3.strictSame([create.playerName, create.byPlayerName, create.reason], ["bob", "dave", "griefing"]);
@@ -89,20 +96,20 @@ t.test("class InstancePlugin", t2 => {
t3.strictSame(payload.reports.map(other => other.by_player_name), ["alice", "carol"], "along with the existing ones");
});
t2.test(".handleCreateIPC() prints a refusal to the reporter", async t3 => {
const { plugin, state } = await startPlugin(t3);
t2.test("exp_reports:create prints a refusal to the reporter", async t3 => {
const { state, createIPC } = await startPlugin(t3);
state.failNext = new lib.RequestError("dave has already reported bob");
await plugin.handleCreateIPC({ player_name: "bob", by_player_name: "dave", reason: "griefing" });
await createIPC({ player_name: "bob", by_player_name: "dave", reason: "griefing" });
const { receiver, payload } = decodeRcon(state.rcons[0]);
t3.strictSame(receiver, "receive_error");
t3.strictSame(payload, { caller: "dave", message: "dave has already reported bob" });
});
t2.test(".handleListIPC() lists the reports for the caller", async t3 => {
const { plugin, state } = await startPlugin(t3);
await plugin.handleListIPC({ caller: "admin", player_name: "bob" });
await plugin.handleListIPC({ caller: "admin", player_name: undefined });
t2.test("exp_reports:list lists the reports for the caller", async t3 => {
const { state, listIPC } = await startPlugin(t3);
await listIPC({ caller: "admin", player_name: "bob" });
await listIPC({ caller: "admin", player_name: undefined });
const forPlayer = decodeRcon(state.rcons[0]);
t3.strictSame(forPlayer.receiver, "receive_list");
@@ -113,9 +120,9 @@ t.test("class InstancePlugin", t2 => {
t3.strictSame(forAll.payload.player_name, undefined, "no player when listing everyone");
});
t2.test(".handleDeleteIPC() deletes only the matching reports", async t3 => {
const { plugin, state } = await startPlugin(t3);
await plugin.handleDeleteIPC({ caller: "admin", player_name: "bob", by_player_name: "carol" });
t2.test("exp_reports:delete deletes only the matching reports", async t3 => {
const { state, deleteIPC } = await startPlugin(t3);
await deleteIPC({ caller: "admin", player_name: "bob", by_player_name: "carol" });
const deletes = state.sent.filter(request => request instanceof messages.ReportDeleteRequest);
t3.strictSame(deletes.map(request => request.id), [2], "only carol's report is deleted");
@@ -124,17 +131,17 @@ t.test("class InstancePlugin", t2 => {
t3.strictSame(payload, { caller: "admin", player_name: "bob", by_player_name: "carol", count: 1 });
state.sent.length = 0;
await plugin.handleDeleteIPC({ caller: "admin", player_name: "bob", by_player_name: undefined });
await deleteIPC({ caller: "admin", player_name: "bob", by_player_name: undefined });
t3.strictSame(
state.sent.filter(request => request instanceof messages.ReportDeleteRequest).length, 2,
"every report is deleted without a reporter",
);
});
t2.test(".luaSend() drops answers once the instance has stopped", async t3 => {
const { plugin, instance, state } = await startPlugin(t3);
t2.test("answers are dropped once the instance has stopped", async t3 => {
const { instance, state, listIPC } = await startPlugin(t3);
instance.notifyStatus("stopped");
await plugin.handleListIPC({ caller: "admin", player_name: undefined });
await listIPC({ caller: "admin", player_name: undefined });
t3.strictSame(state.rcons, [], "nothing is sent to a stopped instance");
});