anbaric-cloud-hosting 1.6.0 → 2.0.0

package/src/index.ts

@@ -38,6 +38,11 @@ export * from "./hosting/handlers/DocumentsHandler";
 export * from "./hosting/handlers/JobsHandler";
 export * from "./hosting/handlers/PagesHandler";
 export * from "./hosting/handlers/PingHandler";
+export * from "./hosting/handlers/PluginsHandler";
+export * from "./plugins/Plugin";
+export * from "./plugins/PluginBundler";
+export * from "./plugins/PluginLoader";
+export * from "./plugins/PageDirectory";
 export * from "./hosting/handlers/QueueHandler";
 export * from "./hosting/handlers/SecretsHandler";
 export * from "./hosting/handlers/StateMachinesHandler";

package/src/main.ts

@@ -18,6 +18,7 @@ import {FargateBuildLayer} from "./app-management/FargateBuildLayer";
 import {ConsumerRegistry} from "./queuing/ConsumerRegistry";
 import {Dispatcher} from "./queuing/Dispatcher";
 import {HostingServer} from "./hosting/HostingServer";
+import {PluginLoader} from "./plugins/PluginLoader";
 
 const pool = new Pool({ connectionString: process.env.ANBARIC_DATABASE_URL });
 await ensureSchema(pool);
@@ -64,9 +65,11 @@ const cliKeyStore = process.env.ANBARIC_CLI_KEY_LOOKUP_URL
 const cliAuthorizer = new CliAuthorizer(cliKeyStore);
 const tokenAuthenticator = new TokenAuthenticator(cliKeyStore, process.env.ANBARIC_TENANT);
 
+const plugins = await new PluginLoader().load(process.env.ANBARIC_PLUGINS ?? "anbaric-plugins/state-machines");
+
 const server = new HostingServer(new PostgresJobPersistence(pool), queue, registry, buildLayer,
     (collection) => new PostgresJsonStore(pool, collection), secretStore, authenticator, cliAuthorizer,
-    tokenAuthenticator, process.env.ANBARIC_TENANT, new PostgresAuditRecordStore(pool));
+    tokenAuthenticator, process.env.ANBARIC_TENANT, new PostgresAuditRecordStore(pool), plugins);
 const port = await server.listen(hostingPort);
 const internal = await server.listenInternal(internalPort);
 

package/src/plugins/PageDirectory.ts

@@ -0,0 +1,35 @@
+import {LoadedPlugin, PluginPage} from "./Plugin";
+
+/* The merged view of every page the loaded plugins register: feeds the nav
+   manifest and tells the hosting server which top-level path segments must
+   serve the dashboard ahead of the app proxy fallback. */
+class PageDirectory {
+
+    private pagesByPath = new Map<string, PluginPage>();
+
+    constructor(plugins : Array<LoadedPlugin>) {
+        for (const loaded of plugins) {
+            for (const page of loaded.plugin.pages) {
+                if (this.pagesByPath.has(page.path)) {
+                    throw new Error(`Two plugins register the page path "${page.path}"`);
+                }
+                this.pagesByPath.set(page.path, page);
+            }
+        }
+    }
+
+    get pages() : Array<PluginPage> {
+        return [...this.pagesByPath.values()]
+            .sort((left, right) => (left.navOrder ?? 100) - (right.navOrder ?? 100) || left.title.localeCompare(right.title));
+    }
+
+    get topLevelSegments() : Array<string> {
+        const segments = this.pages
+            .map(page => page.path.split("/").filter(Boolean)[0])
+            .filter((segment) : segment is string => segment !== undefined);
+        return [...new Set(segments)];
+    }
+
+}
+
+export { PageDirectory }

package/src/plugins/Plugin.ts

@@ -0,0 +1,39 @@
+type PluginComponent = (properties : any) => unknown;
+
+type PluginPage = {
+
+    path : string;
+    title : string;
+    icon? : string;
+    navOrder? : number;
+
+};
+
+type PluginWidget = {
+
+    page : string;
+    id : string;
+    title? : string;
+    position? : number;
+    component : PluginComponent;
+    data? : (parameters : Record<string, string>) => Promise<unknown>;
+
+};
+
+type Plugin = {
+
+    name : string;
+    pages : Array<PluginPage>;
+    widgets : Array<PluginWidget>;
+
+};
+
+type LoadedPlugin = {
+
+    name : string;
+    plugin : Plugin;
+    bundle : string;
+
+};
+
+export { Plugin, PluginPage, PluginWidget, PluginComponent, LoadedPlugin }

package/src/plugins/PluginBundler.ts

@@ -0,0 +1,75 @@
+import {createRequire} from "node:module";
+import {build, Plugin as EsbuildPlugin} from "esbuild";
+
+/* Compiles a plugin module twice: a browser ESM bundle whose react,
+   react-dom and design-system imports are aliased to the dashboard's
+   window.AnbaricPluginRuntime global, and a node bundle whose UI imports
+   are replaced with inert stubs so the module can be imported server-side
+   (for page metadata and widget data functions) without a DOM or CSS
+   loader. */
+class PluginBundler {
+
+    private resolve = createRequire(import.meta.url).resolve;
+
+    async bundleForBrowser(moduleName : string) : Promise<string> {
+        return this.bundle(moduleName, {
+            platform: "browser",
+            plugins: [this.replacementPlugin(browserReplacement)],
+        });
+    }
+
+    async bundleForServer(moduleName : string) : Promise<string> {
+        return this.bundle(moduleName, {
+            platform: "node",
+            packages: "external",
+            plugins: [this.replacementPlugin(serverReplacement)],
+        });
+    }
+
+    private async bundle(moduleName : string, options : object) : Promise<string> {
+        const result = await build({
+            entryPoints: [this.resolve(moduleName)],
+            bundle: true,
+            format: "esm",
+            jsx: "automatic",
+            write: false,
+            logLevel: "silent",
+            ...options,
+        });
+        return result.outputFiles[0].text;
+    }
+
+    private replacementPlugin(replacement : (path : string) => string) : EsbuildPlugin {
+        return {
+            name: "anbaric-plugin-runtime",
+            setup(pluginBuild) {
+                pluginBuild.onResolve({ filter: /^react(-dom)?(\/|$)|^@anbaric\/design-system(\/|$)/ }, resolving =>
+                    ({ path: resolving.path, namespace: "anbaric-runtime" }));
+                pluginBuild.onResolve({ filter: /\.css$/ }, resolving =>
+                    ({ path: resolving.path, namespace: "anbaric-runtime" }));
+                pluginBuild.onLoad({ filter: /.*/, namespace: "anbaric-runtime" }, loading =>
+                    ({ contents: replacement(loading.path), loader: "js" }));
+            },
+        };
+    }
+
+}
+
+const browserReplacement = (path : string) : string => {
+    if (path.endsWith(".css")) return "";
+    if (path === "react/jsx-runtime" || path === "react/jsx-dev-runtime") {
+        return "module.exports = window.AnbaricPluginRuntime.jsxRuntime;";
+    }
+    if (path === "react" || path.startsWith("react/")) {
+        return "module.exports = window.AnbaricPluginRuntime.React;";
+    }
+    if (path === "react-dom" || path.startsWith("react-dom/")) {
+        return "module.exports = window.AnbaricPluginRuntime.ReactDOM;";
+    }
+    return "module.exports = window.AnbaricPluginRuntime.DesignSystem;";
+};
+
+const serverReplacement = (path : string) : string =>
+    path.endsWith(".css") ? "" : "module.exports = {};";
+
+export { PluginBundler }

package/src/plugins/PluginLoader.ts

@@ -0,0 +1,72 @@
+import {createHash} from "node:crypto";
+import {mkdir, writeFile} from "node:fs/promises";
+import {pathToFileURL} from "node:url";
+import {LoadedPlugin, Plugin} from "./Plugin";
+import {PluginBundler} from "./PluginBundler";
+
+/* Loads the comma-separated ANBARIC_PLUGINS module list: each module is
+   compiled for the server and imported to obtain its plugin export (pages,
+   widgets, data functions), and compiled for the browser into the bundle
+   the dashboard fetches from /plugins/<name>.js. The server compilation is
+   written inside node_modules so any imports the plugin left external still
+   resolve when the module is evaluated. */
+class PluginLoader {
+
+    constructor(private bundler : PluginBundler = new PluginBundler(),
+                private cacheDirectory : string = `${process.cwd()}/node_modules/.anbaric-plugins`) {
+    }
+
+    async load(specification? : string) : Promise<Array<LoadedPlugin>> {
+        if (!specification) return [];
+        const moduleNames = specification.split(",").map(name => name.trim()).filter(Boolean);
+        const loaded = await Promise.all(moduleNames.map(moduleName => this.loadOne(moduleName)));
+        for (const plugin of loaded) {
+            if (loaded.some(other => other !== plugin && other.name === plugin.name)) {
+                throw new Error(`Two plugin modules register the plugin name "${plugin.name}"`);
+            }
+        }
+        return loaded;
+    }
+
+    private async loadOne(moduleName : string) : Promise<LoadedPlugin> {
+        const plugin = await this.importForServer(moduleName);
+        const bundle = await this.bundler.bundleForBrowser(moduleName);
+        return { name: plugin.name, plugin, bundle };
+    }
+
+    private async importForServer(moduleName : string) : Promise<Plugin> {
+        const code = await this.bundler.bundleForServer(moduleName);
+        const fileName = `${moduleName.replace(/[^a-z0-9-]+/gi, "-")}-${createHash("sha256").update(code).digest("hex").slice(0, 12)}.mjs`;
+        await mkdir(this.cacheDirectory, { recursive: true });
+        const modulePath = `${this.cacheDirectory}/${fileName}`;
+        await writeFile(modulePath, code);
+        const module = await import(pathToFileURL(modulePath).href);
+        return this.validated(moduleName, module.plugin);
+    }
+
+    private validated(moduleName : string, plugin : any) : Plugin {
+        if (!plugin || typeof plugin.name !== "string") {
+            throw new Error(`Plugin module "${moduleName}" does not export a plugin with a name`);
+        }
+        if (!Array.isArray(plugin.pages) || !Array.isArray(plugin.widgets)) {
+            throw new Error(`Plugin "${plugin.name}" must declare pages and widgets arrays`);
+        }
+        for (const page of plugin.pages) {
+            if (typeof page.path !== "string" || !page.path.startsWith("/") || typeof page.title !== "string") {
+                throw new Error(`Plugin "${plugin.name}" declares a page without a valid path and title`);
+            }
+        }
+        for (const widget of plugin.widgets) {
+            if (typeof widget.page !== "string" || typeof widget.id !== "string" || typeof widget.component !== "function") {
+                throw new Error(`Plugin "${plugin.name}" declares a widget without a page, id and component`);
+            }
+            if (widget.data !== undefined && typeof widget.data !== "function") {
+                throw new Error(`Plugin "${plugin.name}" widget "${widget.id}" has a data field that is not a function`);
+            }
+        }
+        return plugin;
+    }
+
+}
+
+export { PluginLoader }