Let plugins migrate the data core stores for them

Plugins had no way to update the config fields and permissions core stores
for them, so renaming inventory_sync needed migrations in core packages.

A plugin can now declare a migrationEntrypoint. It's loaded on the
controller and hosts before configs and roles are read, for every plugin in
the plugin list, and attaches handlers to sync hooks for the controller,
host and instance configs and roles. lib gets helpers to rename config
fields and permissions, and each config gets a hidden <plugin>.version field
set after load so migrations can tell which version saved the data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-10-14 15:33:27 +00:00
1 parent 24586a4b7c
commit aec0fc7a1e
19 files changed
+562 -7

No files matched your search

+12 -1
View File
@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
import {
ControllerConfig, Address, RequestError,
InstanceConfig, SystemInfo, Role, ModPack, AccountUpdateEvent,
addPluginConfigFields,
addPluginConfigFields, renamePermissionPrefix,
} from "@clusterio/lib";
import "../setup_logging.js";
@@ -714,6 +714,17 @@ describe("controller/src/Controller", function() {
{ permissions: ["core.instance.save.subscribe"] },
]);
});
it("runs plugin role migrations", function() {
Role.pluginMigrations.attach("test", role => (
renamePermissionPrefix(role, "old_name.", "new_name.")
));
try {
const result = Controller.migrateRoles([{ permissions: ["foo", "old_name.view"] }]);
assert.deepEqual(result, [{ permissions: ["foo", "new_name.view"] }]);
} finally {
Role.pluginMigrations.clear();
}
});
it("does nothing for upto date data", function() {
const role = new Role(
0, "n", "d", new Set("p1", "p2"), 0, false
+52
View File
@@ -0,0 +1,52 @@
import assert from "node:assert/strict";
import * as lib from "@clusterio/lib";
describe("lib/SyncHook", function() {
describe("class SyncHook", function() {
let hook;
beforeEach(function() {
hook = new lib.SyncHook();
});
it("should track attached handlers", function() {
assert.equal(hook.size, 0);
hook.attach("alpha", value => value);
hook.attach("beta", value => value);
assert.equal(hook.size, 2);
assert.deepEqual([...hook.attached], ["alpha", "beta"]);
});
it("should reject duplicate handler names", function() {
hook.attach("alpha", value => value);
assert.throws(
() => hook.attach("alpha", value => value),
new Error("Handler with name alpha is already attached")
);
});
it("should detach and clear handlers", function() {
hook.attach("alpha", value => value);
hook.attach("beta", value => value);
hook.detach("alpha");
assert.deepEqual([...hook.attached], ["beta"]);
hook.clear();
assert.equal(hook.size, 0);
});
it("should pass the value through handlers in attach order", function() {
hook.attach("alpha", value => [...value, "alpha"]);
hook.attach("beta", value => [...value, "beta"]);
assert.deepEqual(hook.reduce([]), ["alpha", "beta"]);
});
it("should return the value unchanged with no handlers", function() {
const value = {};
assert.equal(hook.reduce(value), value);
});
it("should rethrow errors as a PluginError named after the handler", function() {
hook.attach("alpha", () => { throw new Error("failed"); });
assert.throws(
() => hook.reduce(1),
err => err instanceof lib.PluginError && err.pluginName === "alpha" && err.original.message === "failed"
);
});
});
});
+65
View File
@@ -45,4 +45,69 @@ describe("lib/config/definitions/migrations", function() {
describe("Ctl Config", function() {
});
describe("Plugin migrations", function() {
const pluginInfo = {
name: "test_plugin",
version: "1.2.0",
instanceEntrypoint: "instance.js",
instanceConfigFields: {
"test_plugin.delay": { type: "number", initialValue: 1 },
},
};
before(function() {
lib.addPluginConfigFields([pluginInfo]);
});
afterEach(function() {
lib.InstanceConfig.pluginMigrations.clear();
});
after(function() {
for (const Config of [lib.ControllerConfig, lib.HostConfig, lib.InstanceConfig]) {
for (const name of Object.keys(Config.fieldDefinitions)) {
if (name.startsWith("test_plugin.")) {
delete Config.fieldDefinitions[name];
}
}
}
});
it("should run attached migrations on load", function() {
lib.InstanceConfig.pluginMigrations.attach("test_plugin", config => (
lib.renameConfigPrefix(config, "old_plugin.", "test_plugin.")
));
const config = lib.InstanceConfig.fromJSON({
"old_plugin.load_plugin": false,
"old_plugin.delay": 5,
}, "controller");
assert.equal(config.get("test_plugin.load_plugin"), false);
assert.equal(config.get("test_plugin.delay"), 5);
assert.equal(config.toJSON()["old_plugin.delay"], undefined);
});
it("should run plugin migrations after core migrations", function() {
lib.InstanceConfig.pluginMigrations.attach("test_plugin", config => {
assert.equal(config["factorio.sync_adminlist"], "enabled");
return config;
});
lib.InstanceConfig.fromJSON({ "factorio.sync_adminlist": true }, "controller");
});
it("should give migrations the version the config was saved with", function() {
let seen;
lib.InstanceConfig.pluginMigrations.attach("test_plugin", config => {
seen = config["test_plugin.version"];
return config;
});
const config = lib.InstanceConfig.fromJSON({ "test_plugin.version": "1.1.0" }, "controller");
assert.equal(seen, "1.1.0");
assert.equal(config.get("test_plugin.version"), "1.1.0");
});
it("should default the version of new configs to the loaded plugin version", function() {
const config = new lib.InstanceConfig("controller");
assert.equal(config.get("test_plugin.version"), "1.2.0");
});
it("should update versions with setPluginVersions", function() {
const config = lib.InstanceConfig.fromJSON({ "test_plugin.version": "1.1.0" }, "controller");
assert.equal(lib.setPluginVersions(config, [pluginInfo]), true);
assert.equal(config.get("test_plugin.version"), "1.2.0");
assert.equal(lib.setPluginVersions(config, [pluginInfo]), false);
});
});
});
+50
View File
@@ -0,0 +1,50 @@
import assert from "node:assert/strict";
import * as lib from "@clusterio/lib";
describe("lib/migrations", function() {
describe("renameConfigField()", function() {
it("should move the value to the new name", function() {
const config = { "foo.bar": 1, "foo.other": 2 };
assert.equal(lib.renameConfigField(config, "foo.bar", "foo.bar_baz"), config);
assert.deepEqual(config, { "foo.bar_baz": 1, "foo.other": 2 });
});
it("should keep an existing value under the new name", function() {
const config = { "foo.bar": 1, "foo.bar_baz": 2 };
lib.renameConfigField(config, "foo.bar", "foo.bar_baz");
assert.deepEqual(config, { "foo.bar_baz": 2 });
});
it("should do nothing if the old name is missing", function() {
const config = { "foo.bar_baz": 2 };
lib.renameConfigField(config, "foo.bar", "foo.bar_baz");
assert.deepEqual(config, { "foo.bar_baz": 2 });
});
});
describe("renameConfigPrefix()", function() {
it("should rename all fields with the prefix", function() {
const config = { "old.load_plugin": false, "old.value": 1, "old_other.value": 2 };
lib.renameConfigPrefix(config, "old.", "new.");
assert.deepEqual(config, { "new.load_plugin": false, "new.value": 1, "old_other.value": 2 });
});
});
describe("renamePermission()", function() {
it("should rename the permission", function() {
const role = { permissions: ["foo.run", "foo.view"] };
assert.equal(lib.renamePermission(role, "foo.run", "foo.frobnicate"), role);
assert.deepEqual(role.permissions, ["foo.frobnicate", "foo.view"]);
});
it("should not duplicate a permission the role already has", function() {
const role = { permissions: ["foo.run", "foo.frobnicate"] };
lib.renamePermission(role, "foo.run", "foo.frobnicate");
assert.deepEqual(role.permissions, ["foo.frobnicate"]);
});
});
describe("renamePermissionPrefix()", function() {
it("should rename all permissions with the prefix", function() {
const role = { permissions: ["old.view", "old_other.view", "core.admin"] };
lib.renamePermissionPrefix(role, "old.", "new.");
assert.deepEqual(role.permissions, ["new.view", "old_other.view", "core.admin"]);
});
});
});
+40
View File
@@ -110,6 +110,46 @@ describe("lib/plugin_loader", function() {
);
});
});
describe("loadPluginMigrations()", function() {
const baseDir = path.resolve("temp", "test", "plugin", "migration_plugin");
before(async function() {
await fs.mkdir(baseDir, { recursive: true });
await fs.writeFile(path.join(baseDir, "migrations.js"), `
export default function(context) {
context.hooks.controllerConfig.attach(context.plugin.name, config => {
config.migratedBy = context.plugin.name;
return config;
});
}
`);
await fs.writeFile(path.join(baseDir, "throwing.js"), `
export default function() { throw new Error("load failed"); }
`);
});
afterEach(function() {
lib.ControllerConfig.pluginMigrations.clear();
});
function info(entrypoint) {
return {
name: "test",
packagePath: path.join(baseDir, "package.json"),
migrationEntrypoint: entrypoint,
};
}
it("should attach migrations from the migration entrypoint", async function() {
await lib.loadPluginMigrations([info("migrations.js"), { name: "other" }]);
assert.deepEqual([...lib.ControllerConfig.pluginMigrations.attached], ["test"]);
assert.deepEqual(lib.ControllerConfig.pluginMigrations.reduce({}), { migratedBy: "test" });
});
it("should reject with a PluginError if the entrypoint throws", async function() {
await assert.rejects(
lib.loadPluginMigrations([info("throwing.js")]),
err => err instanceof lib.PluginError && err.pluginName === "test"
);
});
});
describe("loadPlugin()", function() {
const baseDir = path.join("temp", "test", "plugin");
const functionPlugin = path.resolve(baseDir, "function_plugin");