jbrowse-plugin-msaview 3.4.0 → 3.4.1

package/src/MsaViewPanel/runLaunch.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, test, vi } from 'vitest'
+
+import { runLaunch } from './runLaunch'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+import type { LaunchScope } from './runLaunch'
+
+/**
+ * A model that records every write, so "no model actions after abort" is
+ * assertable rather than inferred. The real thing throws on a destroyed node;
+ * here a write that should not have happened simply shows up in the log.
+ */
+function makeModel() {
+  const writes: string[] = []
+  const model = {
+    launchController: undefined as AbortController | undefined,
+    setLaunchController(arg?: AbortController) {
+      model.launchController = arg
+      writes.push(`setLaunchController:${arg ? 'set' : 'cleared'}`)
+    },
+    setProgress: (arg: string) => writes.push(`setProgress:${arg}`),
+    setError: (e: unknown) =>
+      writes.push(`setError:${e instanceof Error ? e.message : String(e)}`),
+    setRid: (arg: string) => writes.push(`setRid:${arg}`),
+    setData: () => writes.push('setData'),
+  } as unknown as JBrowsePluginMsaViewModel & {
+    launchController: AbortController | undefined
+  }
+  return { model, writes }
+}
+
+const DATA = { msa: '>a\nMK', tree: '(a);', treeMetadata: '{}' }
+
+/** run the microtask queue out so the launch's async body has finished */
+const settle = () => new Promise(res => setTimeout(res, 0))
+
+describe('a launch that finishes', () => {
+  test('applies its data, clears its params and releases the controller', async () => {
+    const { model, writes } = makeModel()
+    const onLaunched = vi.fn()
+
+    runLaunch({
+      self: model,
+      message: 'Submitting query',
+      onLaunched,
+      launch: async scope => {
+        scope.onRid('ncbiblast-1')
+        scope.onProgress('Re-checking BLAST status in... 7')
+        return DATA
+      },
+    })
+    await settle()
+
+    expect(writes).toEqual([
+      'setLaunchController:set',
+      'setProgress:Submitting query',
+      'setError:undefined',
+      'setRid:ncbiblast-1',
+      'setProgress:Re-checking BLAST status in... 7',
+      'setData',
+      'setProgress:',
+      'setLaunchController:cleared',
+    ])
+    expect(onLaunched).toHaveBeenCalled()
+  })
+})
+
+// The failure this file exists for: closing a view mid-BLAST left the poller
+// running for the job's lifetime and then writing to a destroyed
+// mobx-state-tree node, whose throw surfaced as an unhandled rejection.
+describe('a launch that is abandoned', () => {
+  async function abandonMidFlight(reject: boolean) {
+    const { model, writes } = makeModel()
+    let released!: () => void
+    const held = new Promise<void>(res => {
+      released = res
+    })
+    let captured!: LaunchScope
+
+    runLaunch({
+      self: model,
+      message: 'Submitting query',
+      onLaunched: () => {
+        throw new Error('a cancelled launch must not report success')
+      },
+      launch: async scope => {
+        captured = scope
+        await held
+        // what the network hop does once its signal is aborted: either it
+        // rejects with an AbortError, or it had already resolved and returns
+        if (reject) {
+          throw new DOMException('Aborted', 'AbortError')
+        }
+        return DATA
+      },
+    })
+    await settle()
+    const before = writes.length
+
+    model.launchController!.abort()
+    // everything the launch would still try to do after the abort
+    captured.onProgress('Re-checking BLAST status in... 3')
+    captured.onRid('ncbiblast-2')
+    captured.act(() => {
+      throw new Error('act must not run its callback after an abort')
+    })
+    released()
+    await settle()
+
+    return writes.slice(before)
+  }
+
+  test('nothing is written to the model once the abort lands', async () => {
+    expect(await abandonMidFlight(true)).toEqual([])
+  })
+
+  test('a launch that resolved anyway still applies nothing', async () => {
+    expect(await abandonMidFlight(false)).toEqual([])
+  })
+
+  test('an abort renders no error, so a cancel does not read as a failure', async () => {
+    const { model, writes } = makeModel()
+
+    runLaunch({
+      self: model,
+      message: 'Submitting query',
+      onLaunched: () => {},
+      launch: () => Promise.reject(new DOMException('Aborted', 'AbortError')),
+    })
+    await settle()
+
+    expect(writes.some(w => w.startsWith('setError:Aborted'))).toBe(false)
+  })
+})
+
+describe('a launch that fails', () => {
+  test('records the error and stops the spinner', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { model, writes } = makeModel()
+
+    runLaunch({
+      self: model,
+      message: 'Resolving orthologs',
+      onLaunched: () => {
+        throw new Error('a failed launch must not report success')
+      },
+      launch: () => Promise.reject(new Error('Only 1 ortholog(s) found')),
+    })
+    await settle()
+
+    expect(writes).toContain('setError:Only 1 ortholog(s) found')
+    expect(writes.at(-2)).toBe('setProgress:')
+  })
+})

package/src/MsaViewPanel/runLaunch.ts

@@ -0,0 +1,102 @@
+import { isAbortError } from '../utils/fetch'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+
+/**
+ * What a launch is allowed to do to the model and to the network while it runs.
+ *
+ * Every write a launch makes goes through `act`, so "nothing touches the model
+ * once the launch has been abandoned" is one rule in one place. Spreading that
+ * guard across the call sites only takes one omission to undo: an abandoned
+ * launch keeps running until its next network hop rejects, and an action on a
+ * destroyed mobx-state-tree node throws where nothing is catching.
+ */
+export interface LaunchScope {
+  /** aborts when the user cancels, and when the view is destroyed */
+  signal: AbortSignal
+  act: (fn: () => void) => void
+  onProgress: (arg: string) => void
+  /** the EBI job id, published before the first poll so the view can link out */
+  onRid: (arg: string) => void
+}
+
+interface LaunchedData {
+  msa: string
+  tree: string
+  treeMetadata: string
+}
+
+/**
+ * Run one launch attempt, owning the AbortController that ties it to the view.
+ *
+ * The controller lives on the model because two things end a launch and neither
+ * is here: the Cancel button, and the disposer `afterCreate` registers. Before
+ * it existed, closing a view mid-BLAST left the poller checking EBI for the
+ * job's lifetime and then writing to a node that was gone.
+ */
+export function runLaunch({
+  self,
+  message,
+  launch,
+  onLaunched,
+}: {
+  self: JBrowsePluginMsaViewModel
+  message: string
+  launch: (scope: LaunchScope) => Promise<LaunchedData>
+  onLaunched: () => void
+}) {
+  const controller = new AbortController()
+  const { signal } = controller
+  self.setLaunchController(controller)
+
+  const act = (fn: () => void) => {
+    if (!signal.aborted) {
+      fn()
+    }
+  }
+  const scope: LaunchScope = {
+    signal,
+    act,
+    onProgress: arg => {
+      act(() => {
+        self.setProgress(arg)
+      })
+    },
+    onRid: arg => {
+      act(() => {
+        self.setRid(arg)
+      })
+    },
+  }
+
+  void (async () => {
+    try {
+      act(() => {
+        self.setProgress(message)
+        self.setError(undefined)
+      })
+      const data = await launch(scope)
+      act(() => {
+        self.setData(data)
+        onLaunched()
+      })
+    } catch (e) {
+      // a cancel is not a failure: drawing the error panel for one would tell
+      // the user their launch broke when they are the one who stopped it
+      if (!isAbortError(e)) {
+        act(() => {
+          self.setError(e)
+        })
+        console.error(e)
+      }
+    } finally {
+      act(() => {
+        self.setProgress('')
+        // only if a later launch has not already claimed the slot
+        if (self.launchController === controller) {
+          self.setLaunchController(undefined)
+        }
+      })
+    }
+  })()
+}

package/src/MsaViewPanel/storedData.test.ts

@@ -0,0 +1,196 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { loadStoredData, storeDataToIndexedDB } from './afterCreateAutoruns'
+import {
+  generateDataStoreId,
+  retrieveMsaData,
+  storeMsaData,
+} from './msaDataStore'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+import type { MsaDataPayload } from './msaDataStore'
+
+// IndexedDB itself is msaDataStore.test.ts's subject; what is under test here is
+// which writes these two autoruns decide to make.
+vi.mock('./msaDataStore', () => ({
+  cleanupOldData: vi.fn(),
+  generateDataStoreId: vi.fn(),
+  retrieveMsaData: vi.fn(),
+  storeMsaData: vi.fn(),
+}))
+
+const mockRetrieve = vi.mocked(retrieveMsaData)
+const mockStore = vi.mocked(storeMsaData)
+const mockGenerateId = vi.mocked(generateDataStoreId)
+
+const MSA = '>a\nMK'
+const NEW_ID = 'msa-generated'
+
+function makeModel(over: Record<string, unknown> = {}) {
+  const model = {
+    dataStoreId: undefined as string | undefined,
+    rows: [] as string[][],
+    data: {} as MsaDataPayload,
+    msaFilehandle: undefined,
+    treeFilehandle: undefined,
+    isStoringData: false,
+    lastStoredData: undefined as MsaDataPayload | undefined,
+    loadingStoredData: false,
+    error: undefined as unknown,
+    setDataStoreId(arg?: string) {
+      model.dataStoreId = arg
+    },
+    setIsStoringData(arg: boolean) {
+      model.isStoringData = arg
+    },
+    setLastStoredData(arg?: MsaDataPayload) {
+      model.lastStoredData = arg
+    },
+    setLoadingStoredData(arg: boolean) {
+      model.loadingStoredData = arg
+    },
+    setError(arg: unknown) {
+      model.error = arg
+    },
+    setMSA(arg: string) {
+      model.data.msa = arg
+    },
+    setTree(arg: string) {
+      model.data.tree = arg
+    },
+    setTreeMetadata(arg: string) {
+      model.data.treeMetadata = arg
+    },
+    ...over,
+  }
+  return model as typeof model & JBrowsePluginMsaViewModel
+}
+
+const settle = () => new Promise(res => setTimeout(res, 0))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mockGenerateId.mockReturnValue(NEW_ID)
+  mockStore.mockResolvedValue(true)
+})
+
+describe('restoring a view from IndexedDB', () => {
+  test('a row that is still there is applied and recorded as stored', async () => {
+    mockRetrieve.mockResolvedValue({
+      msa: MSA,
+      tree: '(a);',
+      treeMetadata: '{}',
+    })
+    const model = makeModel({ dataStoreId: 'msa-1' })
+
+    loadStoredData(model)
+    await settle()
+
+    expect(model.data.msa).toBe(MSA)
+    expect(model.error).toBeUndefined()
+    // recorded, so the store autorun does not write the restored data straight
+    // back out again
+    expect(model.lastStoredData).toEqual({
+      msa: MSA,
+      tree: '(a);',
+      treeMetadata: '{}',
+    })
+    model.rows = [['a', 'MK']]
+    storeDataToIndexedDB(model)
+    expect(mockStore).not.toHaveBeenCalled()
+  })
+
+  // the row expires or the user clears site data, and the view used to reopen as
+  // a blank import form with no hint that anything had been lost
+  test('a row that is gone says so, in words that name the policy', async () => {
+    mockRetrieve.mockResolvedValue(undefined)
+    const model = makeModel({ dataStoreId: 'msa-1' })
+
+    loadStoredData(model)
+    await settle()
+
+    expect(model.error).toBeInstanceOf(Error)
+    expect((model.error as Error).message).toMatch(/7 days/)
+    // the id names nothing now, so it goes -- otherwise react-msaview's "Return
+    // to import form" lands straight back on this error
+    expect(model.dataStoreId).toBeUndefined()
+  })
+})
+
+describe('keeping IndexedDB up to date', () => {
+  test('the first alignment is written under a fresh id', async () => {
+    const model = makeModel({ rows: [['a', 'MK']], data: { msa: MSA } })
+
+    storeDataToIndexedDB(model)
+    await settle()
+
+    expect(mockStore).toHaveBeenCalledWith(NEW_ID, { msa: MSA })
+    expect(model.dataStoreId).toBe(NEW_ID)
+    expect(model.isStoringData).toBe(false)
+  })
+
+  // react-msaview's "calculate neighbor-joining tree" replaces data.tree long
+  // after the first write; the row used to keep the alignment's original tree
+  // forever, so a reopened session restored a picture the user had replaced
+  test('an edit after the first write updates the existing row', async () => {
+    const model = makeModel({
+      dataStoreId: 'msa-1',
+      rows: [['a', 'MK']],
+      data: { msa: MSA, tree: '(a);' },
+      lastStoredData: { msa: MSA, tree: '(a);' },
+    })
+
+    storeDataToIndexedDB(model)
+    expect(mockStore).not.toHaveBeenCalled()
+
+    model.data.tree = '(a:0.1);'
+    storeDataToIndexedDB(model)
+    await settle()
+
+    expect(mockStore).toHaveBeenCalledWith('msa-1', {
+      msa: MSA,
+      tree: '(a:0.1);',
+      treeMetadata: undefined,
+    })
+    expect(model.dataStoreId).toBe('msa-1')
+  })
+
+  // a browser that refuses IndexedDB (private mode) answers every write the same
+  // way, and the autorun reruns on its own isStoringData flag -- so a write that
+  // is not recorded as attempted is a write that retries forever
+  test('a write that fails is not retried on the same data', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockStore.mockResolvedValue(false)
+    const model = makeModel({ rows: [['a', 'MK']], data: { msa: MSA } })
+
+    storeDataToIndexedDB(model)
+    await settle()
+    expect(model.dataStoreId).toBeUndefined()
+
+    storeDataToIndexedDB(model)
+    await settle()
+    expect(mockStore).toHaveBeenCalledTimes(1)
+  })
+
+  test('a view reading from a filehandle stores nothing, since the file is the source', () => {
+    storeDataToIndexedDB(
+      makeModel({
+        rows: [['a', 'MK']],
+        data: { msa: MSA },
+        msaFilehandle: { uri: 'msa.fa', locationType: 'UriLocation' },
+      }),
+    )
+    expect(mockStore).not.toHaveBeenCalled()
+  })
+
+  test('a write already in flight is not duplicated', () => {
+    storeDataToIndexedDB(
+      makeModel({
+        rows: [['a', 'MK']],
+        data: { msa: MSA },
+        isStoringData: true,
+      }),
+    )
+    expect(mockStore).not.toHaveBeenCalled()
+  })
+})

package/src/utils/blastCache.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+import { getAllCachedResults, saveBlastResult } from './blastCache'
+
+import type { CachedBlastResult } from './blastCache'
+
+// An in-memory stand-in for the one object store this module opens. Only the
+// idb calls blastCache makes are implemented; anything else would be untested
+// scaffolding.
+const { rows } = vi.hoisted(() => ({
+  rows: new Map<string, { id: string; timestamp: number }>(),
+}))
+
+vi.mock('./idb', () => ({
+  createDbOpener: () => () =>
+    Promise.resolve({
+      put: (_store: string, value: { id: string }) => {
+        rows.set(value.id, value as { id: string; timestamp: number })
+        return Promise.resolve(value.id)
+      },
+      count: () => Promise.resolve(rows.size),
+      getAll: () => Promise.resolve([...rows.values()]),
+      transaction: () => ({
+        store: {
+          delete: (id: string) => {
+            rows.delete(id)
+            return Promise.resolve()
+          },
+        },
+        done: Promise.resolve(),
+      }),
+    }),
+}))
+
+function save(n: number) {
+  return saveBlastResult({
+    proteinSequence: `SEQ${n}`,
+    blastDatabase: 'uniprotkb_swissprot',
+    msaAlgorithm: 'clustalo',
+    msa: '>a\nMK',
+    tree: '(a);',
+    treeMetadata: '{}',
+    rid: `job-${n}`,
+  })
+}
+
+beforeEach(() => {
+  rows.clear()
+  // strictly increasing, so "oldest" is unambiguous -- 55 saves in one
+  // millisecond would otherwise all carry the same timestamp
+  let clock = 1
+  vi.spyOn(Date, 'now').mockImplementation(() => clock++)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test('a store at the cap loses nothing', async () => {
+  for (let i = 0; i < 50; i++) {
+    await save(i)
+  }
+  expect(rows.size).toBe(50)
+})
+
+// Every row holds a whole alignment and its tree, so an unbounded store grows
+// until the browser refuses writes to it and the user never learns why.
+test('going over the cap drops the oldest results and keeps the newest 50', async () => {
+  for (let i = 0; i < 55; i++) {
+    await save(i)
+  }
+  expect(rows.size).toBe(50)
+  const rids = (await getAllCachedResults()).map(
+    (r: CachedBlastResult) => r.rid,
+  )
+  expect(rids.at(0)).toBe('job-54')
+  expect(rids.at(-1)).toBe('job-5')
+})
+
+test('re-saving the same query overwrites its row rather than growing the store', async () => {
+  for (let i = 0; i < 50; i++) {
+    await save(i)
+  }
+  await save(0)
+  expect(rows.size).toBe(50)
+})

package/src/utils/blastCache.ts

@@ -6,12 +6,19 @@ import type {
   PhmmerDatabase,
   SearchProgram,
 } from '../LaunchMsaView/components/BlastQuery/consts'
-import type { DBSchema } from 'idb'
+import type { DBSchema, IDBPDatabase } from 'idb'
 
 const DB_NAME = 'jbrowse-msaview-blast-cache'
 const STORE_NAME = 'blast-results'
 const DB_VERSION = 2
 
+/**
+ * How many results the history keeps. Every row holds a whole alignment and its
+ * tree — megabytes each — so an unbounded store grows until the browser starts
+ * refusing writes to it, and the user never sees why.
+ */
+const MAX_CACHED_RESULTS = 50
+
 export interface CachedBlastResult {
   id: string
   proteinSequence: string
@@ -134,9 +141,35 @@ export async function saveBlastResult({
     geneName,
   }
   await db.put(STORE_NAME, entry)
+  await evictOldest(db)
   return entry
 }
 
+/**
+ * Drop the oldest rows until the store is back at MAX_CACHED_RESULTS.
+ *
+ * `count` first so the common save reads no values at all: without a timestamp
+ * index the oldest have to be found by loading every row, and each one is an
+ * entire alignment. Failing to evict must not fail the save — the result is
+ * already in hand and losing it to a housekeeping error would be the worse
+ * outcome.
+ */
+async function evictOldest(db: IDBPDatabase<BlastCacheDB>) {
+  try {
+    if ((await db.count(STORE_NAME)) <= MAX_CACHED_RESULTS) {
+      return
+    }
+    const all = await db.getAll(STORE_NAME)
+    const doomed = all
+      .toSorted((a, b) => a.timestamp - b.timestamp)
+      .slice(0, all.length - MAX_CACHED_RESULTS)
+    const tx = db.transaction(STORE_NAME, 'readwrite')
+    await Promise.all([...doomed.map(e => tx.store.delete(e.id)), tx.done])
+  } catch (e) {
+    console.warn('Failed to evict old BLAST cache entries:', e)
+  }
+}
+
 export async function getAllCachedResults() {
   const db = await getDB()
   const results = await db.getAll(STORE_NAME)

package/src/utils/ebiBlast.ts

@@ -64,14 +64,17 @@ export function ebiBlastResultUrl(jobId: string) {
 export async function queryEbiBlastFromJobId({
   jobId,
   onProgress,
+  signal,
 }: {
   jobId: string
   onProgress: (arg: string) => void
+  signal?: AbortSignal
 }) {
   onProgress(`Checking BLAST status for job: ${jobId}...`)
   await waitForEbiJob({
     tool: TOOL,
     jobId,
+    signal,
     onCountdown: s => {
       onProgress(`Re-checking BLAST status in... ${s}`)
     },
@@ -79,7 +82,7 @@ export async function queryEbiBlastFromJobId({
 
   const hits = normalizeEbiBlastHits(
     JSON.parse(
-      await fetchEbiResult({ tool: TOOL, jobId, type: 'json' }),
+      await fetchEbiResult({ tool: TOOL, jobId, type: 'json', signal }),
     ) as EbiBlastJson,
   )
   if (hits.length === 0) {
@@ -93,11 +96,13 @@ export async function queryEbiBlast({
   blastDatabase,
   onProgress,
   onRid,
+  signal,
 }: {
   query: string
   blastDatabase: BlastDatabase
   onProgress: (arg: string) => void
   onRid: (arg: string) => void
+  signal?: AbortSignal
 }) {
   onProgress('Submitting to EBI BLAST...')
   const jobId = await submitEbiJob({
@@ -108,7 +113,8 @@ export async function queryEbiBlast({
       database: blastDatabase,
       sequence: query,
     },
+    signal,
   })
   onRid(jobId)
-  return queryEbiBlastFromJobId({ jobId, onProgress })
+  return queryEbiBlastFromJobId({ jobId, onProgress, signal })
 }