Repository navigation
Description
What happens. Since 1.4.1 (#133, #134), a reload while the Service Worker is still running costs one ranged request, the probe. But the block cache lives in the worker's memory, and Chromium stops an idle worker after about 30 seconds. The usual revisit therefore starts from nothing: the probe, then the tail (the end-of-central-directory record and the directory), then the head (h5p.json, and content/content.json for the pack's plan), one after another.
I measured this on 2026-11-05 on the Lovable site from #133, with the demo's quiz in headless Chromium. Between loads the worker was stopped with CDP's ServiceWorker.stopAllWorkers:
| Load | Ranged requests | To ready |
|---|---|---|
| First visit | 4: probe, tail, head, warm | 3.3–3.8 s |
| Reload, worker running | 1: probe | 0.6 s |
| Reload, worker stopped | 3: probe, tail, head | 1.3 s |
The two index reads take about 0.5 s of the 1.3 s. A worker the browser restarts mid-lesson reads the tail and h5p.json again before it answers its first request.
Where the reads come from. openReader (mount.ts) opens a reader from the source whenever the worker has none:
- zip.js's
getEntriesreads the tail. readManifestreadsh5p.json.- The
indexhandler'splanFromPackreadscontent/content.json(contentParams).
When the host gave a validator, the probe has just confirmed that the archive is the one these bytes came from, since the package id includes the validator. So the bytes could come from storage instead.
Proposed fix: keep the blocks the index read, with the package.
- Write them once. At the end of the first
indexfor a wholerange-httpreader whose source has a validator, write the blocks the index read into the package's chunk store. Store them with the validator and size they were read under. The forward index of a download is kept there already (setForwardIndex).- These blocks are whatever the index needed: the tail,
h5p.json,content.json, and anylibrary.jsona deep check read. The player names no file. - In practice that is two or three 64 kB blocks, never more than the cache's 4 MB.
- These blocks are whatever the index needed: the tail,
- Seed the cache from them. In
openReader, beforePackageReader.openoverrange-http: when the descriptor's validator and size match the kept ones, put the blocks into the block cache.- zip.js then reads the index from memory, as a reader rebuilt after
attach-librariesdoes today. - The fingerprint and every check run over the same bytes as before.
- A missing or unreadable copy means a read from the network, as now. The copy is a convenience, never the authority.
- zip.js then reads the index from memory, as a reader rebuilt after
- Nothing new to evict. The copy lives in the package's cache, which eviction empties along with the package.
Keep the bytes, not a parsed index. The download path does the other thing: it keeps a snapshot of entries (ForwardIndexSnapshot) and builds a reader from it (fromForwardIndex). Doing that for a whole archive would cost a second index format, which has to:
- match zip.js on zip64, duplicate names and the tolerant name validation;
- build entries without the zip.js
FileEntrythatinflatereads through; - store the fingerprint instead of computing it.
Keeping the bytes leaves zip.js as the only parser, and the price is one Cache API read in place of a network round trip.
Only with a validator. The package id is made from the URL and the validator (remotePkgId). The validator is ETag or Last-Modified, and across origins a page can read them only when the host lists them in Access-Control-Expose-Headers. readValidator says it is "usually null".
- Without a validator, an archive republished at the same URL keeps its id. A kept copy would then send zip.js to the old offsets in the new file, so such a host reads the index as it does today.
docs/setup.md's Requirements can then say that exposingETaglets the player tell a republished archive from the old one, and reload faster.- Out of scope, found while checking: the warm's whole entries already have this gap.
serveInlineserves them under the id without checking them against the index, and nothing clears a package's cache when its archive changes.
Expected results.
- A reload after the worker stopped: from 3 requests to 1, and from about 1.3 s to 0.8 s on that host.
- A worker restarted mid-lesson answers its first request without reading the index.
- First visits are unchanged, and so are hosts without a validator.
- So are a picked file and a downloaded archive, which read their index locally.
Not doing.
- Reading
h5p.jsonandcontent.jsonfrom the warm's whole copies, asreadJsondoes forlibrary.json. That saves the head read but not the tail; the kept blocks cover both. - Keeping the bytes in the
packagesrecord, as A 1.5 MB quiz costs thirteen range requests before it boots: the index is read twice, six requests each time #133 first suggested. The row is rewritten on every load (register,attach-libraries,lastPlayed) and read by the frame route, so it would carry the blocks every time.
Verification.
- A test in
tests/browser-emulated/, since stopping a worker is a CDP call. It loads a fixture from/counted/, stops the worker, loads it again, and expects the probe alone. - A second case without a validator, which expects the index to be read again.
/counted/sends no validator today, so the first case needs it to send anETag. - Unit tests for taking a key's blocks out of the cache and putting them back.
- The design rule. It goes under Small reads over HTTP go through a block cache in
design/serving.md, where "it dies with the worker" changes, plus its index line in AGENTS.md.
Activity