@jbrowse/product-core 4.2.1 → 5.0.0-beta.1

package/esm/rpcWorker.d.ts

@@ -6,7 +6,33 @@ declare global {
         rpcServer?: RpcServer;
     }
 }
+type RpcFunc = (args: unknown) => Promise<unknown>;
+/**
+ * Wire the method's `statusCallback` to the status channel the driver opened
+ * for this call — and to nothing at all when it opened none.
+ *
+ * The `channel` is the driver's statement of whether anyone is listening
+ * (`WebWorkerHandle.call`), so a method run without one has to see the
+ * `undefined` its caller passed. Injecting a callback regardless made every
+ * "no statusCallback" branch in the worker unreachable: the byte reporter an
+ * adapter hands its reader, the emit `createProgressReporter` gates, and the
+ * postMessage each of those cost to reach a main-thread listener that dropped
+ * it.
+ *
+ * `channel` is transport bookkeeping and comes back OFF here, the mirror of
+ * `BaseRpcDriver.call` stripping `statusCallback` on the way out. It used to
+ * ride through into every worker method's arguments, where nothing read it and
+ * `RpcExecuteArgs<M>` did not declare it — a key the main-thread driver never
+ * adds, so the two drivers handed `execute` different bags. `rpcDriverParity`
+ * is what says so.
+ *
+ * Exported for its test and not from the package barrel: `initializeWorker` is
+ * the only thing a product's worker entry calls, and the branch here is a claim
+ * about the driver on the other side of postMessage that nothing else asserts.
+ */
+export declare function wrapForRpc(func: RpcFunc): (args: unknown) => Promise<unknown>;
 export declare function initializeWorker(corePlugins: PluginConstructor[], opts: {
     fetchESM?: (url: string) => Promise<LoadedPlugin>;
     fetchCJS?: (url: string) => Promise<LoadedPlugin>;
 }): Promise<void>;
+export {};

package/esm/rpcWorker.js

@@ -1,10 +1,15 @@
 import PluginLoader from '@jbrowse/core/PluginLoader';
 import PluginManager from '@jbrowse/core/PluginManager';
+import { setNumberGrouping, throttleStatusEmits } from '@jbrowse/core/util';
 import { RpcServer, serializeError } from '@jbrowse/core/util/librpc';
+import { setStackTraceLimit } from '@jbrowse/core/util/setStackTraceLimit';
+import { enableStaticRendering } from 'mobx-react';
+// waits for a message from the main thread containing our configuration, which
+// must be sent on boot
 function receiveConfiguration() {
     const configurationP = new Promise(resolve => {
         function listener(e) {
-            if (e.data.message === 'config') {
+            if (e.data.message === 'config' && e.data.config) {
                 resolve(e.data.config);
                 removeEventListener('message', listener);
             }
@@ -16,27 +21,79 @@ function receiveConfiguration() {
 }
 async function getPluginManager(corePlugins, opts) {
     const config = await receiveConfiguration();
+    // this realm formats its own strings — a jexl `mouseover` slot renders a
+    // tooltip against the full feature here rather than shipping it back — so it
+    // needs the main thread's display preference before any RPC method runs
+    setNumberGrouping(config.numberGrouping);
     const pluginLoader = new PluginLoader(config.plugins, opts).installGlobalReExports(self);
+    // Keep each runtime plugin's `definition` on its load record (mirroring the
+    // main thread's createPluginManager) so PluginManager populates
+    // runtimePluginDefinitions. A plugin that resolves a sibling asset from its
+    // own bundle url in the worker — e.g. GraphGenomeView's Bandage layout
+    // engine — needs its definition here, not just its instance.
+    const runtimePlugins = await pluginLoader.load(config.windowHref);
     return new PluginManager([
-        ...corePlugins.map(p => ({ plugin: p })),
-        ...(await pluginLoader.load(config.windowHref)),
-    ].map(P => new P.plugin()))
+        ...corePlugins.map(P => ({ plugin: new P() })),
+        ...runtimePlugins.map(({ plugin: P, definition }) => ({
+            plugin: new P(),
+            definition,
+        })),
+    ])
         .createPluggableElements()
         .configure();
 }
-function wrapForRpc(func) {
+/**
+ * Wire the method's `statusCallback` to the status channel the driver opened
+ * for this call — and to nothing at all when it opened none.
+ *
+ * The `channel` is the driver's statement of whether anyone is listening
+ * (`WebWorkerHandle.call`), so a method run without one has to see the
+ * `undefined` its caller passed. Injecting a callback regardless made every
+ * "no statusCallback" branch in the worker unreachable: the byte reporter an
+ * adapter hands its reader, the emit `createProgressReporter` gates, and the
+ * postMessage each of those cost to reach a main-thread listener that dropped
+ * it.
+ *
+ * `channel` is transport bookkeeping and comes back OFF here, the mirror of
+ * `BaseRpcDriver.call` stripping `statusCallback` on the way out. It used to
+ * ride through into every worker method's arguments, where nothing read it and
+ * `RpcExecuteArgs<M>` did not declare it — a key the main-thread driver never
+ * adds, so the two drivers handed `execute` different bags. `rpcDriverParity`
+ * is what says so.
+ *
+ * Exported for its test and not from the package barrel: `initializeWorker` is
+ * the only thing a product's worker entry calls, and the branch here is a claim
+ * about the driver on the other side of postMessage that nothing else asserts.
+ */
+export function wrapForRpc(func) {
     return (args) => {
-        const wrappedArgs = args;
-        const { channel, rpcDriverClassName } = wrappedArgs;
-        return func({
-            ...wrappedArgs,
-            statusCallback: (message) => {
-                self.rpcServer?.emit(channel, message);
-            },
-        }, rpcDriverClassName);
+        const { channel, ...rest } = args;
+        return func(channel === undefined
+            ? rest
+            : {
+                ...rest,
+                // thinned here rather than only where it lands: every emit costs a
+                // postMessage, a task and a clone on the main thread, which then
+                // throttles the same stream again to decide what to draw
+                statusCallback: throttleStatusEmits((message) => {
+                    self.rpcServer?.emit(channel, message);
+                }),
+            });
     };
 }
 export async function initializeWorker(corePlugins, opts) {
+    // a worker error's stack is captured here, not on the main thread, so the
+    // frame limit has to be raised in this scope to deepen it
+    setStackTraceLimit();
+    // Workers fetch data; rendering happens on the main thread, and no RPC method
+    // renders React. Kept as a guard: if plugin code ever pulls an observer into
+    // this realm, static rendering keeps it from setting up reactions that would
+    // leak here. Here rather than in each product's worker entry, where four
+    // copies meant a fifth product would silently ship without it — the plugins
+    // that could trip it are not loaded until getPluginManager below, so this is
+    // still ahead of anything that observes.
+    enableStaticRendering(true);
+    // Add global error handler to catch uncaught errors in the worker
     self.addEventListener('error', event => {
         console.error('[Worker uncaught error]', event.error || event.message);
     });
@@ -47,11 +104,35 @@ export async function initializeWorker(corePlugins, opts) {
         const pluginManager = await getPluginManager(corePlugins, opts);
         const rpcConfig = Object.fromEntries(pluginManager
             .getRpcElements()
-            .map(e => [e.name, wrapForRpc(e.execute.bind(e))]));
+            // `invoke`, not `execute`: it deserializes the arguments before handing
+            // them on, which is what makes the blob map current and the declared
+            // arg types true. MainThreadRpcDriver binds the same one.
+            .map(e => [e.name, wrapForRpc(e.invoke.bind(e))]));
         self.rpcServer = new RpcServer(rpcConfig);
         postMessage({ message: 'ready' });
     }
     catch (e) {
-        postMessage({ message: 'error', error: serializeError(e) });
+        // The boot handshake's last frame, and it must never fail to send — for the
+        // reason RpcServer.throw must not, one level worse. `serializeError` copies
+        // an error's own-enumerable properties and skips only the ones that are
+        // themselves functions, so an error carrying an object with a method on it
+        // (a `cause` that is a Response, an adapter instance) makes this postMessage
+        // throw DataCloneError. This runs floating, so that throw becomes an
+        // unhandled rejection the listener above only logs: no 'ready', no 'error',
+        // and no ErrorEvent either, since a rejected promise is not a script error.
+        // The boot promise in WebWorkerRpcDriver then never settles, and because
+        // `invalidate` hangs off its rejection, the pool hands every later caller
+        // the same pending promise — every RPC on that slot awaits forever, showing
+        // a spinner and no error, until the page is reloaded. One worker's failure
+        // to report a failure takes the whole session's worth of calls with it.
+        //
+        // deserializeError accepts a bare string, which is what makes the fallback
+        // sound: a string always clones.
+        try {
+            postMessage({ message: 'error', error: serializeError(e) });
+        }
+        catch {
+            postMessage({ message: 'error', error: `${e}` });
+        }
     }
 }

package/esm/scheduleDetachedDestroy.d.ts

@@ -0,0 +1,18 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Free a tree an action has already let go of — a superseded session, a view
+ * taken out of one, a superseded rootModel the React host has detached.
+ *
+ * A task rather than a microtask: the wait is for React to unmount the
+ * components rendering it, which happens on the re-render that the action's own
+ * reactions schedule. Deferring is acceptable here, and is not elsewhere,
+ * because the node stays alive and detached until it fires — a late read gets a
+ * live tree nobody is rendering. ADR-069.
+ *
+ * The destroy itself is not optional. `beforeDestroy` is a plugin-facing
+ * contract (jbrowse-plugin-apollo aborts its in-flight fetches there) and core's
+ * `BaseTrackModel` releases the `rpcSessionId` claim that lets
+ * `CoreFreeResources` evict a parsed adapter from the worker — so detaching and
+ * forgetting would trade a console warning for an unbounded leak.
+ */
+export declare function scheduleDetachedDestroy(node: IAnyStateTreeNode): void;

package/esm/scheduleDetachedDestroy.js

@@ -0,0 +1,24 @@
+import { destroy, isAlive } from '@jbrowse/mobx-state-tree';
+/**
+ * Free a tree an action has already let go of — a superseded session, a view
+ * taken out of one, a superseded rootModel the React host has detached.
+ *
+ * A task rather than a microtask: the wait is for React to unmount the
+ * components rendering it, which happens on the re-render that the action's own
+ * reactions schedule. Deferring is acceptable here, and is not elsewhere,
+ * because the node stays alive and detached until it fires — a late read gets a
+ * live tree nobody is rendering. ADR-069.
+ *
+ * The destroy itself is not optional. `beforeDestroy` is a plugin-facing
+ * contract (jbrowse-plugin-apollo aborts its in-flight fetches there) and core's
+ * `BaseTrackModel` releases the `rpcSessionId` claim that lets
+ * `CoreFreeResources` evict a parsed adapter from the worker — so detaching and
+ * forgetting would trade a console warning for an unbounded leak.
+ */
+export function scheduleDetachedDestroy(node) {
+    setTimeout(() => {
+        if (isAlive(node)) {
+            destroy(node);
+        }
+    }, 0);
+}

package/esm/sessionMigrations/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Migrates old session and config snapshots to be compatible with the current
+ * display type registrations. Handles display types that were removed or
+ * renamed in the v4 rendering rearchitecture.
+ *
+ * Remapped display types (see `displayTypeMap` for the band settings each one
+ * carries over):
+ *   LinearPileupDisplay → LinearAlignmentsDisplay
+ *   LinearSNPCoverageDisplay → LinearAlignmentsDisplay
+ *   LinearReadArcsDisplay → LinearAlignmentsDisplay
+ *   LinearReadCloudDisplay → LinearAlignmentsDisplay
+ *   LinearFeatureDisplay → LinearBasicDisplay
+ *
+ * Also lifts the per-instance alignments settings a v4.3.0 session persisted
+ * (`colorBySetting`, `filterBySetting`, `jexlFilters`, `trackMaxHeight`,
+ * `hideMismatchesSetting`) into the config where they now live as slots — off
+ * the nested `LinearAlignmentsDisplay` container's `PileupDisplay` /
+ * `SNPCoverageDisplay` sub-nodes and off a flat old display alike, see
+ * `extractAlignmentsInstanceSettings` — and routes the legacy per-instance
+ * `heightPreConfig` display-height prop onto the `height` config slot — see
+ * `extractInstanceHeight`.
+ */
+/**
+ * Every display-instance key a session snapshot may still carry and have
+ * honored, keyed by the display type it applies to — `*` for the ones any
+ * display gets. A snapshot carrying one of these loads correctly, so `jbrowse
+ * validate` reports it as stale rather than dead; that command reads this map
+ * (through the generated config manifest) rather than keeping a copy that could
+ * drift.
+ *
+ * Not every entry is lifted *here*. The two multi-sample variant displays lift
+ * their own `jexlFilters` in the model's `preProcessSnapshot`, because the value
+ * stays on the instance (under `jexlFiltersSetting`) rather than moving to a
+ * config slot, which is the only shape this module handles. What decides
+ * membership is whether the key still works, not which file makes it work.
+ *
+ * Keyed rather than flat because the same name means different things on
+ * different displays: `jexlFilters` is lifted for the alignments display and,
+ * differently, for the two variant ones, while on a LinearBasicDisplay — whose
+ * own prop has always been `jexlFiltersSetting` — it is simply dead, and a flat
+ * list would call that one supported.
+ */
+export declare const MIGRATED_DISPLAY_INSTANCE_KEYS: Record<string, string[]>;
+/**
+ * Walks a session snapshot and remaps old display types to their new names.
+ * Handles displays nested inside views, tracks, and sessionTracks.
+ */
+export declare function migrateSessionSnapshot(snapshot: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Walks a config snapshot and remaps old display types in track definitions.
+ * Config tracks have displays in their configuration (not in views).
+ */
+export declare function migrateConfigSnapshot(snapshot: Record<string, unknown>): Record<string, unknown>;