@drift-beacon/plugin 0.1.1 → 0.2.1

package/dist/ui.js

@@ -1,13 +1,31 @@
 import { PluginError } from "./errors.js";
+import { checkedAction } from "./internal/actions.js";
 import { Collection } from "./internal/collection.js";
+import { deepFreeze } from "./internal/freeze.js";
 import { jsonEqual } from "./internal/json-equal.js";
 import { WorkspaceModels } from "./internal/models.js";
+import { commandArgumentsProblem, commandBudgetMs, eventNameProblem, samePluginStatus } from "./internal/peers.js";
 import { isUiMessage, UI_CHANNEL, } from "./internal/protocol.js";
 import { API_VERSION } from "./version.js";
 export { PluginError } from "./errors.js";
 export { API_VERSION } from "./version.js";
 const HELLO_INTERVAL_MS = 250;
 const REQUEST_TIMEOUT_MS = 10_000;
+const COMMAND_GRACE_MS = 2_000;
+const NO_PEERS = Object.freeze({
+    state: "unavailable",
+    reason: "This version of Drift Beacon doesn't share other plugins with plugin UIs",
+});
+const UNLISTED = Object.freeze({ state: "unavailable", reason: "No longer in manifest.json uses" });
+const PAGE = (() => {
+    const bytes = new Uint8Array(6);
+    if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function")
+        crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    return Array.from(bytes, (byte) => byte.toString(36).padStart(2, "0")).join("");
+})();
 let connection = null;
 export function connect(options = {}) {
     connection ??= open(options.timeoutMs ?? 10_000);
@@ -63,6 +81,7 @@ class UiClient {
     post;
     context;
     config;
+    plugin;
     rows = {
         activities: new Collection(),
         categories: new Collection(),
@@ -81,9 +100,19 @@ class UiClient {
     nextWrite = 0;
     pending = new Map();
     nextRequest = 0;
+    peersShared;
+    listed = new Set();
+    selfId;
+    peerViews = new Map();
+    peerObjects = new Map();
     constructor(welcome, post) {
         this.post = post;
         this.config = welcome.config;
+        this.plugin = welcome.plugin;
+        this.peersShared = welcome.peers !== undefined;
+        this.selfId = welcome.peers?.self ?? welcome.plugin.id;
+        if (welcome.peers)
+            this.applyPeers(welcome.peers);
         this.serverStorage = welcome.storage;
         this.storage = new Map(Object.entries(welcome.storage));
         this.models = new WorkspaceModels({
@@ -99,12 +128,10 @@ class UiClient {
         this.applyData(welcome.data);
         const apis = this.models.apis();
         const self = this;
-        const subscribe = (listeners, callback) => {
-            listeners.add(callback);
-            return () => listeners.delete(callback);
-        };
         this.context = {
-            plugin: welcome.plugin,
+            get plugin() {
+                return self.plugin;
+            },
             user: welcome.user,
             workspace: welcome.workspace,
             get config() {
@@ -117,20 +144,152 @@ class UiClient {
             storage: {
                 get: (key) => this.storage.get(key),
                 keys: () => [...this.storage.keys()],
-                set: (key, value) => this.write(key, JSON.parse(JSON.stringify(value))),
+                set: (key, value) => {
+                    if (value === undefined)
+                        return this.write(key, undefined);
+                    let plain;
+                    try {
+                        plain = JSON.parse(JSON.stringify(value));
+                    }
+                    catch {
+                        return Promise.reject(new PluginError("invalid", `Storage value for "${key}" is not JSON-compatible`));
+                    }
+                    return this.write(key, plain);
+                },
                 remove: (key) => this.write(key, undefined),
                 onChange: (callback) => subscribe(this.storageListeners, callback),
             },
+            plugins: {
+                get: (id) => this.peer(id),
+                get self() {
+                    return self.peer(self.selfId);
+                },
+            },
         };
     }
+    peer(id) {
+        const problem = this.unreachable(id);
+        if (problem)
+            throw problem;
+        const existing = this.peerObjects.get(id);
+        if (existing)
+            return existing;
+        const view = this.viewOf(id);
+        const peer = Object.freeze({
+            id,
+            get status() {
+                return view.status;
+            },
+            onStatusChange: (callback) => subscribe(view.statusListeners, callback),
+            command: (name, input, options) => this.command(id, name, input, options),
+            state: Object.freeze({
+                get: (key) => view.state.get(key),
+                keys: () => [...view.state.keys()],
+                onChange: (callback) => subscribe(view.stateListeners, callback),
+            }),
+            onEvent: (name, callback) => {
+                const invalidName = eventNameProblem(name);
+                if (invalidName)
+                    throw new PluginError("invalid", invalidName);
+                const problem = this.unreachable(id);
+                if (problem)
+                    throw problem;
+                let listeners = view.eventListeners.get(name);
+                if (!listeners) {
+                    listeners = new Set();
+                    view.eventListeners.set(name, listeners);
+                }
+                return subscribe(listeners, callback);
+            },
+        });
+        this.peerObjects.set(id, peer);
+        return peer;
+    }
+    unreachable(id) {
+        return typeof id !== "string" || (this.peersShared && !this.listed.has(id))
+            ? new PluginError("invalid", `List "${String(id)}" in manifest.json uses to reach it`)
+            : null;
+    }
+    viewOf(id) {
+        let view = this.peerViews.get(id);
+        if (!view) {
+            view = {
+                status: NO_PEERS,
+                state: new Map(),
+                statusListeners: new Set(),
+                stateListeners: new Set(),
+                eventListeners: new Map(),
+            };
+            this.peerViews.set(id, view);
+        }
+        return view;
+    }
+    applyPeers(peers) {
+        this.peersShared = true;
+        this.selfId = peers.self;
+        this.listed = new Set(Object.keys(peers.plugins));
+        const statusChanges = [];
+        const stateChanges = [];
+        const unlisted = [...this.peerViews.keys()]
+            .filter((id) => !this.listed.has(id))
+            .map((id) => [id, { status: UNLISTED, state: {} }]);
+        for (const [id, next] of [...Object.entries(peers.plugins), ...unlisted]) {
+            const view = this.viewOf(id);
+            if (!samePluginStatus(view.status, next.status)) {
+                const status = deepFreeze({ ...next.status });
+                view.status = status;
+                statusChanges.push(() => notify(view.statusListeners, (listener) => listener(status)));
+            }
+            const state = new Map(Object.entries(next.state).map(([key, value]) => [key, deepFreeze(value)]));
+            for (const key of new Set([...view.state.keys(), ...state.keys()])) {
+                if (view.state.has(key) === state.has(key) && jsonEqual(view.state.get(key), state.get(key)))
+                    continue;
+                const value = state.get(key);
+                stateChanges.push(() => notify(view.stateListeners, (listener) => listener(key, value)));
+            }
+            view.state = state;
+        }
+        for (const change of [...statusChanges, ...stateChanges])
+            change();
+    }
+    command(plugin, command, input, options) {
+        const unreachable = this.unreachable(plugin);
+        if (unreachable)
+            return Promise.reject(unreachable);
+        const problem = commandArgumentsProblem(command, input, options);
+        if (problem)
+            return Promise.reject(new PluginError("invalid", problem));
+        let plain;
+        try {
+            plain = input === undefined ? undefined : JSON.parse(JSON.stringify(input));
+        }
+        catch {
+            return Promise.reject(new PluginError("invalid", "Command input must be JSON-compatible"));
+        }
+        const timeoutMs = options?.timeoutMs;
+        return this.request({
+            method: "plugins.command",
+            params: {
+                plugin,
+                command,
+                ...(plain === undefined ? {} : { input: plain }),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            },
+        }, {
+            ms: commandBudgetMs(timeoutMs) + COMMAND_GRACE_MS,
+            error: () => new PluginError("timeout", `${plugin} didn't answer "${command}" in time; it may have run`),
+        });
+    }
     receive(message) {
         if (message.type === "welcome") {
+            this.plugin = message.plugin;
             this.receive({
                 channel: message.channel,
                 type: "state",
                 config: message.config,
                 data: message.data,
                 storage: message.storage,
+                ...(message.peers ? { peers: message.peers } : {}),
             });
             return;
         }
@@ -145,6 +304,10 @@ class UiClient {
                 pending.resolve(message.result);
             return;
         }
+        if (message.type === "event") {
+            this.applyEvent(message);
+            return;
+        }
         if (message.type !== "state")
             return;
         if (message.config)
@@ -156,8 +319,19 @@ class UiClient {
             this.writesSincePush.clear();
             this.reconcileStorage();
         }
+        if (message.peers)
+            this.applyPeers(message.peers);
         notify(this.dataListeners, (listener) => listener());
     }
+    applyEvent({ plugin, event, payload }) {
+        if (!this.listed.has(plugin))
+            return;
+        const listeners = this.peerViews.get(plugin)?.eventListeners.get(event);
+        if (!listeners?.size)
+            return;
+        const frozen = deepFreeze(payload);
+        notify(listeners, (listener) => listener(frozen));
+    }
     applyData(data) {
         const changes = this.models.update({
             activities: this.rows.activities.replace(data.activities),
@@ -193,6 +367,9 @@ class UiClient {
         return changed;
     }
     async write(key, value) {
+        const checked = checkedAction(value === undefined ? { name: "storageRemove", key } : { name: "storageSet", key, value });
+        if (checked?.ok === false)
+            throw new PluginError("invalid", checked.problem);
         const writeId = ++this.nextWrite;
         this.pendingWrites.set(key, (this.pendingWrites.get(key) ?? 0) + 1);
         this.writesSincePush.set(key, writeId);
@@ -221,26 +398,40 @@ class UiClient {
                 notify(this.dataListeners, (listener) => listener());
         }
     }
-    request(request) {
-        const id = String(++this.nextRequest);
+    request(request, timeout = {
+        ms: REQUEST_TIMEOUT_MS,
+        error: () => new PluginError("unavailable", `${request.method} timed out`),
+    }) {
+        const id = `${PAGE}-${++this.nextRequest}`;
         return new Promise((resolve, reject) => {
             this.pending.set(id, { resolve, reject });
             this.post({ channel: UI_CHANNEL, type: "request", id, ...request });
             setTimeout(() => {
                 if (!this.pending.delete(id))
                     return;
-                reject(new PluginError("unavailable", `${request.method} timed out`));
-            }, REQUEST_TIMEOUT_MS);
+                reject(timeout.error());
+            }, timeout.ms);
         });
     }
 }
+function subscribe(listeners, callback) {
+    if (typeof callback !== "function")
+        throw new PluginError("invalid", "Callback must be a function");
+    listeners.add(callback);
+    return () => listeners.delete(callback);
+}
+const logListenerError = (error) => console.error("[drift-beacon] Error in plugin listener:", error);
 function notify(listeners, call) {
-    for (const listener of listeners) {
+    for (const listener of [...listeners]) {
+        if (!listeners.has(listener))
+            continue;
         try {
-            call(listener);
+            const result = call(listener);
+            if (result && typeof result.then === "function")
+                result.then(undefined, logListenerError);
         }
         catch (error) {
-            console.error("[drift-beacon] Error in plugin listener:", error);
+            logListenerError(error);
         }
     }
 }

package/dist/version.d.ts

@@ -2,5 +2,5 @@
  * The plugin API version this SDK describes, `major.minor`. It matches the package version's
  * major and minor. Before 1.0 every minor version may break plugins.
  */
-export declare const API_VERSION = "0.1";
+export declare const API_VERSION = "0.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const API_VERSION = "0.1";
+export const API_VERSION = "0.2";

package/dist/vite.js

@@ -40,6 +40,8 @@ export function driftBeacon() {
             return { root: path.join(pkg, "ui"), base: "./", build: { outDir: path.join(dist, "ui"), emptyOutDir: true } };
         },
         configureServer(server) {
+            if (process.env.VITEST)
+                return;
             serveDev(server, devStates.get(pkg) ?? startDev(pkg, dist, manifest, manifestBytes, server.config.logger));
         },
         async writeBundle() {
@@ -90,6 +92,7 @@ function startDev(pkg, dist, manifest, bytes, logger) {
         manifest,
         manifestBytes: bytes,
         watcher: Promise.resolve(undefined),
+        idle: Promise.resolve(),
         buildId: hashDist(dist),
         uiUrl: null,
         socket: null,
@@ -110,8 +113,13 @@ async function watchMain(state) {
     const staging = path.join(state.pkg, ".drift-beacon/main-next");
     const options = { outDir: staging, minify: false, sourcemap: true, watch: {}, logLevel: "silent" };
     const watcher = (await vite.build(mainBuild(vite, state.pkg, options)));
+    let built = () => { };
     watcher.on("event", (event) => {
-        if (event.code === "BUNDLE_END") {
+        if (event.code === "START")
+            state.idle = new Promise((resolve) => (built = resolve));
+        else if (event.code === "END")
+            built();
+        else if (event.code === "BUNDLE_END") {
             try {
                 moveFiles(staging, path.join(state.dist, "main"));
                 const changed = writeDevMarker(state);
@@ -132,6 +140,7 @@ async function watchMain(state) {
             });
         }
     });
+    await new Promise((resolve) => watcher.on("event", () => resolve()));
     return watcher;
 }
 function serveDev(server, state) {
@@ -154,14 +163,13 @@ function serveDev(server, state) {
                 print(state.logger, { level: "warn", text: noServerHint(state) });
         }, HINT_DELAY_MS).unref();
     });
-    const close = server.close.bind(server);
+    const { watcher } = server;
+    const closeWatcher = watcher.close.bind(watcher);
     let open = true;
-    server.close = () => {
-        if (open) {
-            open = false;
-            release(state);
-        }
-        return close();
+    watcher.close = async () => {
+        const released = open ? release(state) : undefined;
+        open = false;
+        await Promise.all([closeWatcher(), released]);
     };
     server.ws.on("drift-beacon:hello", (data, client) => {
         if (data?.session !== state.session)
@@ -183,13 +191,15 @@ function serveDev(server, state) {
             print(state.logger, data);
     });
 }
-function release(state) {
+async function release(state) {
     if (--state.servers > 0)
         return;
     clearTimeout(state.hint);
     if (devStates.get(state.pkg) === state)
         devStates.delete(state.pkg);
-    void state.watcher.then((watcher) => watcher?.close());
+    const watcher = await state.watcher;
+    await state.idle;
+    await watcher?.close();
 }
 function updateManifest(state) {
     try {
@@ -290,8 +300,14 @@ function writeMarker(dist, { pluginId, session, uiUrl }) {
 function hashDist(dist) {
     if (!existsSync(path.join(dist, "main/index.js")))
         return null;
+    const ui = existsSync(path.join(dist, "ui"))
+        ? readdirSync(path.join(dist, "ui"), { recursive: true, withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => path.relative(dist, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"))
+            .sort()
+        : [];
     const hash = createHash("sha256");
-    for (const name of ["manifest.json", "main/index.js", "main/index.js.map", "ui/index.html"]) {
+    for (const name of ["manifest.json", "main/index.js", "main/index.js.map", ...ui]) {
         const file = path.join(dist, name);
         if (existsSync(file))
             hash.update(`${name}\0`).update(readFileSync(file));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drift-beacon/plugin",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "The Drift Beacon plugin SDK: APIs for plugin main code and UIs, the driftBeacon() Vite plugin and the dbplugin CLI",
   "license": "MIT",
   "author": {