Skip to content

Once the browser stops the worker, a reload reads the index again: keep its blocks with the package #136

Closed

Description

@alekswebnet

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 getEntries reads the tail.
  • readManifest reads h5p.json.
  • The index handler's planFromPack reads content/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.

  1. Write them once. At the end of the first index for a whole range-http reader 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 any library.json a 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.
  2. Seed the cache from them. In openReader, before PackageReader.open over range-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-libraries does 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.
  3. 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 FileEntry that inflate reads 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 exposing ETag lets 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. serveInline serves 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.

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 an ETag.
  • 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions