Tolerate optional genome load failures and explain the fatal ones

[jrobinso]

Summary

Loading a genome no longer fails when an optional part fails. A 2bit .bpt index, chrom.sizes, the alias bigBed, the alias file and cytobands are each left out with a fallback where there is one (the 2bit's internal index, chromosomes loaded on demand, the next alias source; there is always an alias source, the defaults at least). Only the sequence, a specified FASTA index, and a starting locus are required: a 2bit with an external index now supplies its first sequence name as the default locus.

Optional failures are reported to the user with what failed and its likely consequence. Readers stay UI-free: they record {kind, url, message, warning} on the genome, which the browser reports in one alert with the track failures. Parts that load lazily (cytobands, aliases) are reported as they fail, through a hook the browser sets once it has taken the genome and clears when the genome is replaced or disposed.

Fatal failures, of a genome, a session file or a track, now reject with a message written for the user instead of the raw request error (Error accessing resource: <url> status: 0). A reader that fails on a required resource throws LoadError(kind, url, cause) (js/util/loadFailure.js), and genomeLoadError, sessionLoadError and trackLoadError wrap it. The message says in one sentence which part failed and what happened to it, then the resource, then a hint where there is one, one per line:

Genome canFam4 could not be loaded: the 2bit sequence file could not be reached.
https://hgdownload.soe.ucsc.edu/goldenPath/canFam4/bigZips/canFam4x.2bit
Check that the URL is correct. The server may also be down, or may not allow access from this web page (CORS).

A request failure is explained by its status (0 is "could not be reached" with a CORS hint, 404 "was not found", 401/403 "could not be accessed"), and any other error by its message. When the part that failed is the thing being loaded (a session file, a track's file) it is said once: "The track was not found (HTTP status 404). / ". A track is named only by a configured name, since one derived from the URL would repeat it. A failed load leaves the browser unchanged, so the caller can carry on with the current genome and tracks. The original error is kept as cause.

Alerts are queued across every dialog on the page, so an alert presented while another is open waits instead of replacing it. Dialogs removed from the page or disposed of are skipped; a dialog not yet attached (a browser created in a detached div) keeps its alert until it is attached and meanwhile doesn't block others. The dialog renders line breaks and sizes itself to its message, scrolling beyond 70% of the viewport height.

Also: hub genomes are loaded through one loadHubGenomeConfig, which fails as an assembly hub failure; all 2bit reads go through buildOptions, so configured headers and tokens are sent on every request.

Test plan

• npm test (307 passing): genome tests for each optional-part failure and the alias fallbacks, fatal fasta/index/2bit/not-2bit failures, session file failures (missing, not JSON, corrupt, hub without genome), and the load-failure helpers. Tests assert on the error's kind, url and cause, not on message wording.
• npx eslint js
• Checked in a browser: bad 2bit URL via loadGenome, bad session URL, bad track URL, each showing the message above with line breaks in the igv.js alert and in igv-webapp
• Manual check of a genome with a 404 .bpt: the genome loads from the 2bit's internal index and one alert warns about the index, with the URL and the reason ("was not found (HTTP status 404)" for a same-origin 404; "could not be reached" with the CORS hint for a UCSC 404, whose response has no CORS headers)
• Manual check of a genome with a 404 chrom.sizes, alias bigBed and cytoband URL: the genome loads with chromosomes from the 2bit's index, a search by an unaliased name still resolves through the default aliases, and the ideogram draws without bands; each part alerts once, with what failed and its consequence, the URL, and "was not found (HTTP status 404)"

🤖 Generated with Claude Code