Self-hosted, plugin-based server management.
TypeScript dockerhomelabpluginsrdpremote-desktopself-hostedserver-managementsftpsshterminaltermixvnc
/**
* The single-tier loader: discovery, dependency order and lifecycle.
*
* These drive the real PluginLoader against real plugin directories written
* to a temp dir, because the things worth testing here are exactly the ones a
* mock would paper over: does a manifest on disk parse, does an id collision
* get refused, does a plugin's own deactivate actually run.
*/
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import zlib from "node:zlib";
import {
PluginLoader,
assertBundledUpdate,
removeStaleStaging,
unsafeArchivePath,
} from "../../plugins/loader.js";
import { createFixturePlugin } from "./fixture-plugin.js";
vi.mock("../../database/repositories/factory.js", () => ({
createCurrentPluginStorageRepository: () => ({
get: async () => null,
set: async () => {},
delete: async () => false,
listKeys: async () => [],
}),
}));
const cleanups: Array<() => void> = [];
function tempRoot(prefix: string): string {
const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
cleanups.push(() => fs.rmSync(root, { recursive: true, force: true }));
return root;
}
/** Points the loader at `bundled` and `user` as its two discovery roots. */
function setRoots(bundled: string, user: string): void {
process.env.TERMIX_BUNDLED_PLUGINS_DIR = bundled;
process.env.DATA_DIR = user;
}
beforeEach(() => {
vi.unstubAllEnvs();
});
afterEach(() => {
delete process.env.TERMIX_BUNDLED_PLUGINS_DIR;
delete process.env.DATA_DIR;
while (cleanups.length) cleanups.pop()?.();
});
describe("PluginLoader discovery", () => {
it("loads a valid plugin directory", async () => {
const fixture = createFixturePlugin();
cleanups.push(fixture.cleanup);
const loader = new PluginLoader();
const plugin = await loader.load(fixture.dir, "bundled");
expect(plugin.id).toBe("sample-plugin");
expect(plugin.state).toBe("loaded");
expect(plugin.manifest.capabilities).toEqual(["hosts:read", "kv:own"]);
});
it("rejects a directory whose name does not match the manifest id", async () => {
const fixture = createFixturePlugin({
manifestOverrides: { id: "something-else" },
});
cleanups.push(fixture.cleanup);
const loader = new PluginLoader();
await expect(loader.load(fixture.dir, "bundled")).rejects.toThrow(
/does not match manifest id/,
);
});
it("rejects a manifest whose backend entry is missing", async () => {
const fixture = createFixturePlugin({ omitBackendEntry: true });
cleanups.push(fixture.cleanup);
const loader = new PluginLoader();
await expect(loader.load(fixture.dir, "bundled")).rejects.toThrow(
/backend entry .* is missing/,
);
});
it("skips an invalid directory and loads the rest", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({ id: "good-plugin", root: bundled });
const broken = path.join(bundled, "broken-plugin");
fs.mkdirSync(broken, { recursive: true });
fs.writeFileSync(path.join(broken, "manifest.json"), "{ not json");
setRoots(bundled, user);
const loader = new PluginLoader();
const loaded = await loader.loadAll();
expect(loaded.map((plugin) => plugin.id)).toEqual(["good-plugin"]);
});
// A plugin dropped into the data directory must never be able to take over
// an id the install already ships, or "ssh-terminal" becomes whatever the
// last person to write that folder wanted it to be.
it("refuses a user plugin that shadows a bundled id", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
const userPlugins = path.join(user, "plugins");
fs.mkdirSync(userPlugins, { recursive: true });
createFixturePlugin({ id: "ssh-terminal", root: bundled });
createFixturePlugin({
id: "ssh-terminal",
root: userPlugins,
manifestOverrides: { name: "Impostor" },
});
setRoots(bundled, user);
const loader = new PluginLoader();
const loaded = await loader.loadAll();
expect(loaded).toHaveLength(1);
expect(loaded[0].source).toBe("bundled");
expect(loaded[0].manifest.name).toBe("Sample Plugin");
});
});
describe("PluginLoader themes and skipped looks", () => {
const themed = {
capabilities: ["ui:theme", "ui:layout"],
manifestOverrides: {
contributes: {
themes: [
{
id: "paper",
label: "Paper",
mode: "light",
css: "themes/paper.css",
},
],
layouts: [{ id: "fancy", label: "Fancy" }],
},
},
};
it("loads a plugin whose theme CSS is allowed", async () => {
const fixture = createFixturePlugin(themed);
cleanups.push(fixture.cleanup);
fs.mkdirSync(path.join(fixture.dir, "themes"));
fs.writeFileSync(
path.join(fixture.dir, "themes", "paper.css"),
".paper { --background: #fff; }",
);
const plugin = await new PluginLoader().load(fixture.dir, "bundled");
expect(plugin.manifest.contributes?.themes?.[0].id).toBe("paper");
});
it("refuses a plugin whose theme CSS reaches outside", async () => {
const fixture = createFixturePlugin(themed);
cleanups.push(fixture.cleanup);
fs.mkdirSync(path.join(fixture.dir, "themes"));
fs.writeFileSync(
path.join(fixture.dir, "themes", "paper.css"),
'@import url("https://example.com/x.css");',
);
await expect(
new PluginLoader().load(fixture.dir, "bundled"),
).rejects.toThrow(/theme paper is not allowed: @import/);
});
it("refuses a plugin whose theme file is missing", async () => {
const fixture = createFixturePlugin(themed);
cleanups.push(fixture.cleanup);
await expect(
new PluginLoader().load(fixture.dir, "bundled"),
).rejects.toThrow(/theme paper file themes\/paper.css is missing/);
});
it("remembers why a layout plugin was skipped", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({
...themed,
id: "fancy-layout",
root: bundled,
manifestOverrides: {
...themed.manifestOverrides,
version: "2.0.0",
engine: { termix: ">=99.0.0", api: "1" },
},
});
setRoots(bundled, user);
const loader = new PluginLoader();
await loader.loadAll();
const [skipped] = loader.skipped();
expect(skipped).toMatchObject({
id: "fancy-layout",
version: "2.0.0",
layouts: ["fancy"],
themes: ["paper"],
});
expect(skipped.error).toMatch(/needs Termix >=99.0.0/);
});
});
describe("PluginLoader dependency resolution", () => {
async function loadAll(
specs: Array<{ id: string; manifestOverrides?: Record<string, unknown> }>,
): Promise<PluginLoader> {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
for (const spec of specs) {
createFixturePlugin({ ...spec, root: bundled });
}
setRoots(bundled, user);
const loader = new PluginLoader();
await loader.loadAll();
return loader;
}
it("orders a dependency before its dependent", async () => {
const loader = await loadAll([
{ id: "alpha", manifestOverrides: { dependencies: { beta: "^1.0.0" } } },
{ id: "beta" },
]);
const { order, blocked, cycles } = loader.resolveOrder(["alpha", "beta"]);
expect(cycles.size).toBe(0);
expect(blocked.size).toBe(0);
expect(order.indexOf("beta")).toBeLessThan(order.indexOf("alpha"));
});
it("blocks a plugin whose hard dependency is not installed", async () => {
const loader = await loadAll([
{
id: "alpha",
manifestOverrides: { dependencies: { missing: "^1.0.0" } },
},
]);
const { order, blocked } = loader.resolveOrder(["alpha"]);
expect(order).toEqual([]);
expect(blocked.get("alpha")).toMatch(/not installed/);
});
it("blocks a plugin whose dependency is present at the wrong version", async () => {
const loader = await loadAll([
{ id: "alpha", manifestOverrides: { dependencies: { beta: "^2.0.0" } } },
{ id: "beta" },
]);
const { blocked } = loader.resolveOrder(["alpha", "beta"]);
expect(blocked.get("alpha")).toMatch(/1\.0\.0 is installed/);
});
it("blocks a plugin whose dependency is installed but disabled", async () => {
const loader = await loadAll([
{ id: "alpha", manifestOverrides: { dependencies: { beta: "^1.0.0" } } },
{ id: "beta" },
]);
const { blocked } = loader.resolveOrder(["alpha"]);
expect(blocked.get("alpha")).toMatch(/not enabled/);
});
// Nothing to wait for, so this is a failure rather than a block.
it("fails every plugin in a dependency cycle", async () => {
const loader = await loadAll([
{ id: "alpha", manifestOverrides: { dependencies: { beta: "^1.0.0" } } },
{ id: "beta", manifestOverrides: { dependencies: { alpha: "^1.0.0" } } },
]);
const { order, cycles } = loader.resolveOrder(["alpha", "beta"]);
expect(order).toEqual([]);
expect(cycles.get("alpha")).toMatch(/cycle/);
expect(cycles.get("beta")).toMatch(/cycle/);
});
it("activates in dependency order and reports blocked plugins", async () => {
const marker = path.join(tempRoot("termix-order-"), "order.txt");
const record = (id: string) => `
import fs from "node:fs";
export async function activate() {
fs.appendFileSync(${JSON.stringify(marker)}, "${id}\\n");
}
`;
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({
id: "alpha",
root: bundled,
backendSource: record("alpha"),
manifestOverrides: { dependencies: { beta: "^1.0.0" } },
});
createFixturePlugin({
id: "beta",
root: bundled,
backendSource: record("beta"),
});
createFixturePlugin({
id: "gamma",
root: bundled,
manifestOverrides: { dependencies: { nowhere: "^1.0.0" } },
});
setRoots(bundled, user);
const loader = new PluginLoader();
await loader.loadAll();
const result = await loader.activateAll(["alpha", "beta", "gamma"]);
expect(result.activated).toEqual(["beta", "alpha"]);
expect(fs.readFileSync(marker, "utf8").trim().split("\n")).toEqual([
"beta",
"alpha",
]);
expect(loader.get("gamma")?.state).toBe("blocked");
expect(loader.get("gamma")?.lastError).toMatch(/not installed/);
});
});
describe("PluginLoader lifecycle", () => {
async function single(
backendSource: string,
id = "sample-plugin",
): Promise<PluginLoader> {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({ id, root: bundled, backendSource });
setRoots(bundled, user);
const loader = new PluginLoader();
await loader.loadAll();
return loader;
}
it("runs activate and then deactivate", async () => {
const marker = path.join(tempRoot("termix-life-"), "life.txt");
const loader = await single(`
import fs from "node:fs";
export async function activate() {
fs.appendFileSync(${JSON.stringify(marker)}, "up\\n");
}
export async function deactivate() {
fs.appendFileSync(${JSON.stringify(marker)}, "down\\n");
}
`);
await loader.activate("sample-plugin");
expect(loader.get("sample-plugin")?.state).toBe("active");
await loader.deactivate("sample-plugin");
expect(loader.get("sample-plugin")?.state).toBe("stopped");
expect(fs.readFileSync(marker, "utf8")).toBe("up\ndown\n");
});
it("marks a plugin failed when activate throws", async () => {
const loader = await single(`
export async function activate() {
throw new Error("no good");
}
`);
await expect(loader.activate("sample-plugin")).rejects.toThrow("no good");
expect(loader.get("sample-plugin")?.state).toBe("failed");
expect(loader.get("sample-plugin")?.lastError).toBe("no good");
});
it("rejects a backend entry with no activate export", async () => {
const loader = await single(`export const nothing = true;`);
await expect(loader.activate("sample-plugin")).rejects.toThrow(
/does not export an activate/,
);
});
// The whole point of the bag: cleanup cannot be conditional on the plugin
// behaving well on the way out.
it("disposes everything even when deactivate throws", async () => {
const marker = path.join(tempRoot("termix-dispose-"), "disposed.txt");
const loader = await single(`
import fs from "node:fs";
export async function activate(ctx) {
ctx.disposables.add(() => {
fs.appendFileSync(${JSON.stringify(marker)}, "disposed\\n");
});
}
export async function deactivate() {
throw new Error("deactivate blew up");
}
`);
await loader.activate("sample-plugin");
await loader.deactivate("sample-plugin");
expect(loader.get("sample-plugin")?.state).toBe("stopped");
expect(fs.readFileSync(marker, "utf8")).toBe("disposed\n");
});
// ESM caches the module, so the second activate runs against the same
// module object the first one did. Anything created at module scope would
// already be torn down by then.
it("supports enable, disable, enable without a restart", async () => {
const marker = path.join(tempRoot("termix-cycle-"), "cycle.txt");
const loader = await single(`
import fs from "node:fs";
let timer = null;
let server = null;
export async function activate(ctx) {
server = { closed: false };
timer = setInterval(() => {}, 1000);
ctx.disposables.add(() => {
clearInterval(timer);
server.closed = true;
fs.appendFileSync(${JSON.stringify(marker)}, "closed\\n");
});
fs.appendFileSync(${JSON.stringify(marker)}, "started\\n");
}
`);
await loader.activate("sample-plugin");
await loader.deactivate("sample-plugin");
await loader.activate("sample-plugin");
expect(loader.get("sample-plugin")?.state).toBe("active");
expect(fs.readFileSync(marker, "utf8")).toBe("started\nclosed\nstarted\n");
await loader.deactivate("sample-plugin");
});
it("disposes registrations made before activate threw", async () => {
const marker = path.join(tempRoot("termix-partial-"), "partial.txt");
const loader = await single(`
import fs from "node:fs";
export async function activate(ctx) {
ctx.disposables.add(() => {
fs.appendFileSync(${JSON.stringify(marker)}, "cleaned\\n");
});
throw new Error("halfway");
}
`);
await expect(loader.activate("sample-plugin")).rejects.toThrow("halfway");
expect(fs.readFileSync(marker, "utf8")).toBe("cleaned\n");
});
it("deactivating a plugin that never started is a no-op", async () => {
const loader = await single(`export async function activate() {}`);
await loader.deactivate("sample-plugin");
expect(loader.get("sample-plugin")?.state).toBe("stopped");
});
it("shuts plugins down in reverse activation order", async () => {
const marker = path.join(tempRoot("termix-shutdown-"), "shutdown.txt");
const record = (id: string) => `
import fs from "node:fs";
export async function activate() {}
export async function deactivate() {
fs.appendFileSync(${JSON.stringify(marker)}, "${id}\\n");
}
`;
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({
id: "alpha",
root: bundled,
backendSource: record("alpha"),
manifestOverrides: { dependencies: { beta: "^1.0.0" } },
});
createFixturePlugin({
id: "beta",
root: bundled,
backendSource: record("beta"),
});
setRoots(bundled, user);
const loader = new PluginLoader();
await loader.loadAll();
await loader.activateAll(["alpha", "beta"]);
await loader.shutdown();
// beta started first, so it stops last: a dependency outlives its
// dependents.
expect(fs.readFileSync(marker, "utf8").trim().split("\n")).toEqual([
"alpha",
"beta",
]);
});
});
describe("PluginLoader error budget", () => {
async function failing(threshold: number): Promise<PluginLoader> {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({
root: bundled,
backendSource: `export async function activate() {}`,
});
setRoots(bundled, user);
const loader = new PluginLoader({
errorThreshold: threshold,
errorWindowMs: 60_000,
});
await loader.loadAll();
await loader.activate("sample-plugin");
return loader;
}
it("marks a plugin failed once it trips the threshold", async () => {
const loader = await failing(3);
await loader.reportError("sample-plugin", new Error("one"));
await loader.reportError("sample-plugin", new Error("two"));
expect(loader.get("sample-plugin")?.state).toBe("active");
await loader.reportError("sample-plugin", new Error("three"));
expect(loader.get("sample-plugin")?.state).toBe("failed");
expect(loader.get("sample-plugin")?.lastError).toBe("three");
});
it("forgets errors that fall outside the window", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({
root: bundled,
backendSource: `export async function activate() {}`,
});
setRoots(bundled, user);
const loader = new PluginLoader({ errorThreshold: 2, errorWindowMs: 10 });
await loader.loadAll();
await loader.activate("sample-plugin");
await loader.reportError("sample-plugin", new Error("one"));
await new Promise((resolve) => setTimeout(resolve, 25));
await loader.reportError("sample-plugin", new Error("two"));
expect(loader.get("sample-plugin")?.state).toBe("active");
});
it("retry clears the budget and starts the plugin again", async () => {
const loader = await failing(1);
await loader.reportError("sample-plugin", new Error("down"));
expect(loader.get("sample-plugin")?.state).toBe("failed");
await loader.retry("sample-plugin");
expect(loader.get("sample-plugin")?.state).toBe("active");
expect(loader.get("sample-plugin")?.lastError).toBeNull();
});
});
describe("PluginLoader uninstall and pins", () => {
it("ignores the shipped copy of a bundled plugin an admin uninstalled", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({ id: "ssh-terminal", root: bundled });
createFixturePlugin({ id: "docker", root: bundled });
setRoots(bundled, user);
const loader = new PluginLoader();
loader.setUninstalled(["docker"]);
const loaded = await loader.loadAll();
expect(loaded.map((plugin) => plugin.id)).toEqual(["ssh-terminal"]);
expect(loader.bundledVersion("docker")).toBeUndefined();
expect(loader.bundledIds().has("docker")).toBe(false);
});
it("loads a downloaded copy of an uninstalled bundled id as a normal plugin", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
const userPlugins = path.join(user, "plugins");
fs.mkdirSync(userPlugins, { recursive: true });
createFixturePlugin({ id: "docker", root: bundled });
createFixturePlugin({ id: "docker", root: userPlugins });
setRoots(bundled, user);
const loader = new PluginLoader();
loader.setUninstalled(["docker"]);
const loaded = await loader.loadAll();
expect(loaded).toHaveLength(1);
expect(loaded[0].source).toBe("user");
});
it("loads the shipped copy again on reinstall", async () => {
const bundled = tempRoot("termix-bundled-");
const user = tempRoot("termix-data-");
createFixturePlugin({ id: "docker", root: bundled });
setRoots(bundled, user);
const loader = new PluginLoader();
loader.setUninstalled(["docker"]);
await loader.loadAll();
const plugin = await loader.loadBundled("docker");
expect(plugin.source).toBe("bundled");
expect(loader.get("docker")).toBe(plugin);
});
it("refuses an older signed update unless that exact version is pinned", () => {
expect(() =>
assertBundledUpdate("docker", "1.0.0", "key", "1.1.0"),
).toThrow(/not newer/);
expect(() =>
assertBundledUpdate("docker", "1.0.0", "key", "1.1.0", "0.9.0"),
).toThrow(/not newer/);
expect(() =>
assertBundledUpdate("docker", "1.0.0", "key", "1.1.0", "1.0.0"),
).not.toThrow();
expect(() =>
assertBundledUpdate("docker", "1.0.0", undefined, "1.1.0", "1.0.0"),
).toThrow(/signed/);
});
});
/** A gzipped tar with the given entry names, written by hand. */
function rawTar(names: string[]): Buffer {
const blocks: Buffer[] = [];
for (const name of names) {
const header = Buffer.alloc(512);
header.write(name, 0, 100);
header.write("0000644\0", 100);
header.write("00000000001\0", 124);
header.write(" ", 148);
header.write("0", 156);
header.write("ustar\0", 257);
header.write("00", 263);
let sum = 0;
for (const byte of header) sum += byte;
header.write(sum.toString(8).padStart(6, "0") + "\0 ", 148);
blocks.push(header, Buffer.concat([Buffer.from("x"), Buffer.alloc(511)]));
}
blocks.push(Buffer.alloc(1024));
return zlib.gzipSync(Buffer.concat(blocks));
}
describe("unsafeArchivePath", () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "termix-unsafe-"));
const write = (names: string[]) => {
const file = path.join(dir, `${names.length}-${Math.random()}.tmxplug`);
fs.writeFileSync(file, rawTar(names));
return file;
};
it("finds entries that escape the folder", async () => {
expect(
await unsafeArchivePath(write(["manifest.json", "../../etc/x"])),
).toBe("../../etc/x");
expect(await unsafeArchivePath(write(["/tmp/x"]))).not.toBeNull();
});
it("passes a normal archive", async () => {
expect(
await unsafeArchivePath(write(["manifest.json", "dist/backend.js"])),
).toBeNull();
});
});
describe("removeStaleStaging", () => {
it("removes unpack folders left by a crashed install", async () => {
const data = fs.mkdtempSync(path.join(os.tmpdir(), "termix-staging-"));
const previous = process.env.DATA_DIR;
process.env.DATA_DIR = data;
try {
const unpacked = path.join(data, "plugins", ".unpacked");
fs.mkdirSync(path.join(unpacked, ".staging-abc", "dist"), {
recursive: true,
});
fs.mkdirSync(path.join(unpacked, "serial"), { recursive: true });
await removeStaleStaging();
expect(fs.readdirSync(unpacked)).toEqual(["serial"]);
} finally {
process.env.DATA_DIR = previous;
}
});
});