@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/PluginLoader.js

@@ -1,21 +1,38 @@
-import Plugin from "./Plugin.js";
-import ReExports from "./ReExports/index.js";
-import { isElectron } from "./util/index.js";
-export function isUMDPluginDefinition(def) {
-    return ((def.umdUrl !== undefined ||
-        def.url !== undefined ||
-        def.umdLoc !== undefined) &&
-        def.name !== undefined);
-}
-export function isESMPluginDefinition(def) {
-    return (def.esmUrl !== undefined ||
-        def.esmLoc !== undefined);
+import { enableContractReports } from '@jbrowse/render-core/contractReports';
+import { setReExportRegistry } from './ReExports/registry.js';
+import { isCJSPluginDefinition, isESMPluginDefinition, isUMDPluginDefinition, maybePluginUrl, pluginDescriptionString, } from './pluginDefinitions.js';
+import { isElectron } from './util/index.js';
+import { isWebWorker } from './util/isWebWorker.js';
+/**
+ * A definition names exactly one loader. More than one is malformed — no real
+ * config declares a plugin twice — and it is the shape that lets "the url we
+ * vetted" and "the url we run" drift apart, so refuse it rather than pick a
+ * winner. That keeps them the same string by construction, instead of by every
+ * url-based inspection of a definition remembering to match loadPlugin's order.
+ */
+function assertSingleKind(def) {
+    const kinds = [
+        isCJSPluginDefinition(def) ? 'CJS' : undefined,
+        isESMPluginDefinition(def) ? 'ESM' : undefined,
+        isUMDPluginDefinition(def) ? 'UMD' : undefined,
+    ].filter(kind => kind !== undefined);
+    if (kinds.length > 1) {
+        throw new Error(`Plugin definition names more than one plugin type (${kinds.join(', ')}), refusing to load: ${JSON.stringify(def)}`);
+    }
 }
-function promisifiedLoadScript(src) {
+function promisifiedLoadScript(src, integrity) {
     return new Promise((resolve, reject) => {
         const script = document.createElement('script');
         script.type = 'text/javascript';
         script.async = true;
+        // Subresource integrity guarantees the fetched bytes match the hash the
+        // plugin store published, so a tampered or swapped artifact fails to load.
+        // crossOrigin is required for the browser to enforce integrity on a
+        // cross-origin script.
+        if (integrity) {
+            script.integrity = integrity;
+            script.crossOrigin = 'anonymous';
+        }
         script.src = src;
         script.onload = () => {
             resolve(script.src);
@@ -26,53 +43,101 @@ function promisifiedLoadScript(src) {
         document.head.append(script);
     });
 }
-async function loadScript(scriptUrl) {
-    if (!isInWebWorker()) {
-        return promisifiedLoadScript(scriptUrl);
-    }
-    if (globalThis.importScripts) {
-        await globalThis.importScripts(scriptUrl);
-        return;
-    }
-    throw new Error('cannot figure out how to load external JS scripts in this environment');
+function hasImportScripts(scope) {
+    return 'importScripts' in scope;
 }
-export function isCJSPluginDefinition(def) {
-    return def.cjsUrl !== undefined;
+// A *module* worker has importScripts on its global but throws from it — the
+// spec forbids it there, and the browser says so ("Module scripts don't support
+// importScripts"). That is the whole failure for a UMD plugin in a bundler
+// configured for module workers (Vite's `worker.format: 'es'`), and it reads as
+// a broken plugin unless named. Every other throw is the script's own — a 404,
+// or a bundle that dereferences `window` in a realm that has none — and the
+// script's words are the diagnosis, so they are kept rather than replaced.
+export function workerScriptLoadMessage(scriptUrl, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return /module script/i.test(detail)
+        ? `Failed to load ${scriptUrl} in the worker. A UMD plugin is loaded there via importScripts, which module workers do not support — either build the worker as a classic worker, or use a plugin published as ESM.`
+        : `Failed to load ${scriptUrl} in the worker: ${detail}`;
 }
-export function pluginDescriptionString(d) {
-    if (isUMDPluginDefinition(d)) {
-        return `UMD plugin ${d.name}`;
+async function loadScript(scriptUrl, integrity) {
+    const scope = globalThis;
+    if (!isWebWorker()) {
+        return promisifiedLoadScript(scriptUrl, integrity);
     }
-    else if (isESMPluginDefinition(d)) {
-        return `ESM plugin ${d.esmUrl ||
-            d.esmLoc.uri}`;
-    }
-    else if (isCJSPluginDefinition(d)) {
-        return `CJS plugin ${d.cjsUrl}`;
+    else if (hasImportScripts(scope)) {
+        try {
+            scope.importScripts(scriptUrl);
+        }
+        catch (error) {
+            throw new Error(workerScriptLoadMessage(scriptUrl, error), {
+                cause: error,
+            });
+        }
+        return;
     }
     else {
-        return 'unknown plugin';
+        throw new Error('cannot figure out how to load external JS scripts in this environment');
     }
 }
-export function pluginUrl(d) {
-    if (isUMDPluginDefinition(d)) {
-        return d.url ?? d.umdLoc?.uri ?? d.umdUrl;
+/**
+ * Resolve a plugin's url, refusing anything that isn't http(s).
+ *
+ * `base` is the JBrowse **instance's** own location, not the config that named
+ * the plugin — every product passes `window.location.href` (the embedded ones
+ * let their host override it, the RPC worker forwards the same value). That is
+ * deliberate rather than an oversight: a relative url means "a plugin shipped
+ * beside this index.html". A config that means "beside *me*" has the
+ * `umdLoc`/`esmLoc` forms instead, which carry their own `baseUri` — the one
+ * `addRelativeUris` stamps from the config's url when it is fetched.
+ *
+ * The rule only bites on Desktop, whose instance is a `file://` page, so a
+ * relative url resolves to a `file:` url that could never be fetched. Diagnose
+ * that in terms its author can act on: the raw scheme of a url they never wrote
+ * ("Cannot load plugins using protocol file:") named the symptom and nothing
+ * else, and the reader is usually looking at a third-party hub config.
+ */
+function resolvePluginUrl(spec, base) {
+    const url = new URL(spec, base);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(
+        // a spec with a scheme of its own resolved to exactly what it asked for,
+        // so there is nothing to explain beyond refusing it
+        /^[a-z][a-z0-9+.-]*:/i.test(spec)
+            ? `Cannot load plugins using protocol "${url.protocol}"`
+            : `Cannot load plugin from relative url "${spec}": it resolves against this JBrowse instance (${base}), not against the config that named it. Give it an absolute http(s) url, or use the umdLoc/esmLoc form to resolve it against the config.`);
     }
-    else if (isESMPluginDefinition(d)) {
-        return d.esmUrl ?? d.esmUri ?? d.esmLoc?.uri;
+    return url;
+}
+// A plugin served from the developer's own machine into an app built for
+// production is the one arrangement that can only be a plugin under
+// development: a shipped site serves its plugins from its own origin, and a
+// developer running the app itself from source already has a development build.
+// So it is the evidence that arms the contract channel without anything for the
+// author to know about first — which is the whole difficulty the channel had,
+// since the population it is written for is the one with nobody to ask. See
+// `@jbrowse/render-core/contractReports`.
+function armIfUnderDevelopment(def) {
+    const url = maybePluginUrl(def);
+    if (url !== undefined && servedFromThisMachine(url)) {
+        enableContractReports(`the plugin at ${url} is served from this machine`);
     }
-    else if (isCJSPluginDefinition(d)) {
-        return d.cjsUrl || d.cjsLoc.uri;
+}
+function servedFromThisMachine(url) {
+    try {
+        const { hostname, protocol } = new URL(url);
+        return ((protocol === 'http:' || protocol === 'https:') &&
+            (hostname === 'localhost' ||
+                hostname === '127.0.0.1' ||
+                hostname === '[::1]'));
     }
-    else {
-        return 'unknown url';
+    catch {
+        // a relative url is a plugin shipped beside this index.html, which is the
+        // site's own rather than one under development
+        return false;
     }
 }
-function isInWebWorker() {
-    return 'WorkerGlobalScope' in globalThis;
-}
 function addCacheBuster(url) {
-    if (!globalThis.__jbrowseCacheBuster) {
+    if (!('__jbrowseCacheBuster' in globalThis)) {
         return url;
     }
     const u = new URL(url);
@@ -86,13 +151,10 @@ export default class PluginLoader {
     constructor(defs = [], args) {
         this.fetchESM = args?.fetchESM;
         this.fetchCJS = args?.fetchCJS;
-        this.definitions = JSON.parse(JSON.stringify(defs));
+        this.definitions = structuredClone(defs);
     }
     async loadCJSPlugin(def, baseUri) {
-        const parsedUrl = new URL(def.cjsUrl, baseUri);
-        if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
-            throw new Error(`Cannot load plugins using protocol "${parsedUrl.protocol}"`);
-        }
+        const parsedUrl = resolvePluginUrl(def.cjsUrl, baseUri);
         if (!this.fetchCJS) {
             throw new Error('No fetchCJS callback provided');
         }
@@ -100,15 +162,13 @@ export default class PluginLoader {
     }
     async loadESMPlugin(def, baseUri) {
         const parsedUrl = 'esmUrl' in def
-            ? new URL(def.esmUrl, baseUri)
-            : new URL(def.esmLoc.uri, def.esmLoc.baseUri);
-        if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
-            throw new Error(`cannot load plugins using protocol "${parsedUrl.protocol}"`);
-        }
+            ? resolvePluginUrl(def.esmUrl, baseUri)
+            : resolvePluginUrl(def.esmLoc.uri, def.esmLoc.baseUri);
         if (!this.fetchESM) {
             throw new Error('No ESM fetcher installed');
         }
         const plugin = await this.fetchESM(addCacheBuster(parsedUrl.href));
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (!plugin) {
             throw new Error(`Could not load ESM plugin: ${parsedUrl}`);
         }
@@ -116,21 +176,16 @@ export default class PluginLoader {
     }
     async loadUMDPlugin(def, baseUri) {
         const parsedUrl = 'url' in def
-            ? new URL(def.url, baseUri)
+            ? resolvePluginUrl(def.url, baseUri)
             : 'umdUrl' in def
-                ? new URL(def.umdUrl, baseUri)
-                : new URL(def.umdLoc.uri, def.umdLoc.baseUri);
-        if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
-            throw new Error(`cannot load plugins using protocol "${parsedUrl.protocol}"`);
-        }
+                ? resolvePluginUrl(def.umdUrl, baseUri)
+                : resolvePluginUrl(def.umdLoc.uri, def.umdLoc.baseUri);
         const moduleName = def.name;
         const umdName = `JBrowsePlugin${moduleName}`;
-        if (typeof jest === 'undefined') {
-            await loadScript(addCacheBuster(parsedUrl.href));
-        }
-        else {
-            globalThis[umdName] = { default: Plugin };
-        }
+        // a cache buster query string would change the bytes the browser hashes for
+        // SRI, so skip it when an integrity hash is present (the url is already
+        // version-pinned and immutable, so cache-busting is unnecessary anyway)
+        await loadScript(def.integrity ? parsedUrl.href : addCacheBuster(parsedUrl.href), def.integrity);
         const plugin = globalThis[umdName];
         if (!plugin) {
             throw new Error(`Failed to load UMD bundle for ${moduleName}, ${umdName} is undefined`);
@@ -138,8 +193,13 @@ export default class PluginLoader {
         return plugin;
     }
     async loadPlugin(def, baseUri) {
+        assertSingleKind(def);
+        armIfUnderDevelopment(def);
         let plugin;
-        if (isElectron && isCJSPluginDefinition(def)) {
+        if (isCJSPluginDefinition(def)) {
+            if (!isElectron) {
+                throw new Error(`CommonJS plugin found, but not in a NodeJS environment: ${JSON.stringify(def)}`);
+            }
             plugin = await this.loadCJSPlugin(def, baseUri);
         }
         else if (isESMPluginDefinition(def)) {
@@ -148,27 +208,95 @@ export default class PluginLoader {
         else if (isUMDPluginDefinition(def)) {
             plugin = await this.loadUMDPlugin(def, baseUri);
         }
-        else if (!isElectron && isCJSPluginDefinition(def)) {
-            throw new Error(`CommonJS plugin found, but not in a NodeJS environment: ${JSON.stringify(def)}`);
-        }
         else {
             throw new Error(`Could not determine plugin type: ${JSON.stringify(def)}`);
         }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (!plugin.default) {
             throw new Error(`${pluginDescriptionString(def)} does not have a default export, cannot load`);
         }
         return plugin.default;
     }
+    reExportTarget;
+    /**
+     * Ask for the runtime ABI (`JBrowseExports`) to be published on `target`
+     * before any plugin bundle is evaluated. Records the target; the registry
+     * itself is fetched in `loadSettled` below.
+     *
+     * The split is the point. Every product calls this at startup, synchronously,
+     * whether or not the config names a plugin — so importing the registry here
+     * put it in every host's first paint. It is a ~126 KB gzipped module (see
+     * `ReExports/registry.ts` for why it cannot shrink) that only a runtime plugin
+     * can use, and loading one is async anyway.
+     */
     installGlobalReExports(target) {
-        target.JBrowseExports = Object.fromEntries(Object.entries(ReExports).map(([moduleName, module]) => {
-            return [moduleName, module];
-        }));
+        this.reExportTarget = target;
         return this;
     }
-    async load(baseUri) {
-        return Promise.all(this.definitions.map(async (definition) => ({
+    async publishReExports() {
+        const target = this.reExportTarget;
+        if (!target) {
+            return;
+        }
+        // a worker never renders: the same keys, with the UI ones stubbed, so a
+        // plugin bundle evaluates there without fetching react-dom and Material UI
+        const { default: ReExports } = isWebWorker()
+            ? await import('./ReExports/workerModules.js')
+            : await import('./ReExports/index.js');
+        target.JBrowseExports = {
+            ...ReExports,
+        };
+        // the synchronous half: `pluginManager.jbrequire(name)` is what a CJS
+        // plugin calls, and it cannot await
+        setReExportRegistry(ReExports);
+        this.reExportTarget = undefined;
+    }
+    /**
+     * Loads every definition and separates the ones that worked from the ones
+     * that didn't, instead of failing the batch on the first error.
+     *
+     * A remote config names its plugins at urls nobody re-checks — a store path
+     * that stops being republished, a bundle that needs a newer host than the one
+     * reading the config — and `load`'s all-or-nothing contract turns any of that
+     * into a dead app rather than a missing feature. That is the widest blast
+     * radius left in config loading: an unknown track/adapter/display type is
+     * already tolerated (the track is simply not usable), so the plugin url was
+     * the only field in a config that could still take a whole session down.
+     *
+     * Callers that can degrade (the apps) use this and report the failures;
+     * callers that cannot (the RPC worker, where a half-loaded plugin set would
+     * fail renders with a much worse message) keep using `load`.
+     */
+    async loadSettled(baseUri) {
+        // before the first plugin script evaluates — a UMD bundle reads
+        // `JBrowseExports` off the global at module scope
+        await this.publishReExports();
+        const results = await Promise.allSettled(this.definitions.map(async (definition) => ({
             plugin: await this.loadPlugin(definition, baseUri),
             definition,
         })));
+        const records = [];
+        const failures = [];
+        for (const [i, result] of results.entries()) {
+            if (result.status === 'fulfilled') {
+                records.push(result.value);
+            }
+            else {
+                failures.push({
+                    definition: this.definitions[i],
+                    error: result.reason,
+                });
+            }
+        }
+        return { records, failures };
+    }
+    async load(baseUri) {
+        const { records, failures } = await this.loadSettled(baseUri);
+        // rethrown by definition order rather than by which rejected first, so the
+        // error a strict caller sees doesn't depend on network timing
+        if (failures[0]) {
+            throw failures[0].error;
+        }
+        return records;
     }
 }