Skip to content

perf(player): small range reads come from a block cache - #134

Merged
alekswebnet merged 2 commits into
mainfrom
perf/range-read-cache
Nov 4, 2026
Merged

alekswebnet merged 2 commits into
mainfrom
perf/range-read-cache

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Closes #133.

A 1.5 MB quiz on a host that honours Range took fourteen ranged requests to ready, thirteen of them small and one after another, at 0.2–0.4 s each on Lovable's and Vercel's CDNs. zip.js reads an index in pieces: the 64 kB tail, the central directory inside it, then each entry's local header, its extra field when it has one, and its data. Over HTTP each piece was a request, and the reader the Service Worker builds again after attach-libraries, on every load that names the pack, read all of them again.

The change

Small reads go through a cache of 64 kB blocks, on pdf.js's model (ChunkedStreamManager). No new dependency.

  • BlockCache (src/shared/block-cache.ts): blocks aligned from the start of the archive. The blocks a read is missing are fetched in one request per contiguous run, each once, and shared while on their way. A failed or short fetch is not kept. At most 4 MB is held per worker, the least recently used block going first.
  • RangeHttpHandle: read up to 1 MB goes through the cache, and so does stream for a range of one block or one the cache already holds. Everything else streams from the network as before, so media never passes through the cache. The cache is module-level and keyed by URL, validator and size, the package id's ingredients, so the handle a rebuilt reader opens finds the blocks the first one fetched.
  • PackageReader.inflate pulls a small entry's header and data in one read before zip.js reads them in pieces (blocksFor).
  • /counted/<fixture>?log=<id> on the dev server writes down every request it takes, so a test can count what a load costs.

A correction to the issue's part 2: the data position is already remembered within a reader (dataRange keeps it as a promise per entry). The two or three reads per entry were zip.js's own, inside getData, and the cache plus blocksFor covers those. Part 3, keeping the index with the package for reloads, is not in this PR.

Requests to ready, counted by the host

Load main this branch
The demo's quiz.h5p, 1.5 MB, libraries="pack" (the Lovable setup) 14 4: probe, tail, head, warm
basic.h5p 10 3
streamed.h5p 10 3
needs-dependency.h5p with a bundle attached 18 4

The warm runs in the Jobs worker, which has a cache of its own, so a small archive's single block is fetched once by each worker.

Checked

  • Unit, 381: block-cache.test.ts (alignment, runs, sharing, failure, short answers, eviction, keys) and range-http-handle.test.ts (a real zip.js archive's index over a host that honours Range costs two requests, and a reader built again costs none; a long read and a media stream are not kept).
  • Browser, 202, in Chromium, Firefox and WebKit, including range-requests.test.ts, which pins the counts above for the fixtures. The emulated project, 4, passes.
  • pnpm typecheck across the workspace.

Self-review

Read the diff again after opening the PR. One fix, in the second commit: source.ts made the cache with the module, and the element imports that module for the probe, so its bundle carried an instance it never uses. It is made on the first read now. The element still carries the cache's code, as it has always carried the three source adapters: that is a tree-shaking matter from before this PR, not changed here.

Bundle sizes, built from main and from this branch:

Bundle main this branch
h5p-player.js, the element 61.9 kB 64.1 kB
h5p-sw.js, the Service Worker 261.7 kB 264.2 kB
h5p-jobs.js, the Jobs worker 25.9 kB 28.1 kB

Checked and left as they are: the short-answer check (a 200 host's body is sliced to the range, so a block always arrives whole or the read fails); a read keeps references to the blocks it assembles, so eviction cannot take bytes out from under it; a read of a 30-byte local header now fetches its 64 kB block, once, which the Jobs worker's extraction of a large entry pays too; the warm's own reads go through the Jobs worker's copy of the cache, which lives with the tab, bounded at 4 MB.

Docs

design/serving.md has the rule, Small reads over HTTP go through a block cache, and a rebuilt reader finds it, with its line in AGENTS.md. Three statements it changes are updated: the resilient read, the warm's reason, and the deep check in libraries.md. layout.md and testing.md name the new file and the counting host.

🤖 Generated with Claude Code

alekswebnet and others added 2 commits November 5, 2026 01:17
zip.js reads an index in pieces, one after another, and over HTTP every
piece was a request: the 64 kB tail, the central directory inside it, each
entry's local header, its extra field, its data. The reader the Service
Worker builds again once libraries are attached, on every load that names
the pack, read all of them again. The demo's 1.5 MB quiz took fourteen
ranged requests to ready, thirteen of them small and in sequence.

Small reads now go through a cache of 64 kB blocks, pdf.js's design: the
blocks a read is missing are fetched in one request per run, each once,
shared while on their way, at most 4 MB held per worker. It is module-level
and keyed like the package id, so a rebuilt reader finds what the first one
fetched. A stream longer than a block goes to the network as before, so
media never passes through it. The quiz now takes four requests: the
probe, the tail, the head and the warm. basic.h5p goes from ten to three,
needs-dependency.h5p with a bundle attached from eighteen to four.

/counted/ on the dev server writes down every request it takes, and a
browser test counts what a load costs with it.

Closes #133

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Self-review of #134: source.ts made the cache with the module, and the
element imports that module for the probe, so its bundle carried an
instance it never uses. Made on the first read instead: the element is
1.7 kB smaller than with the eager instance. It still carries the cache's
code, as it has always carried the three source adapters.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@alekswebnet
alekswebnet merged commit bf054ed into main Nov 4, 2026
9 checks passed
alekswebnet added a commit that referenced this pull request Nov 4, 2026
Player 1.4.1: small range reads come from a block cache (#133, #134), a
patch, since nothing docs/compatibility.md covers changes. Embed 1.5.1
pins it exactly and ships it in every site and SCORM zip it writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
alekswebnet added a commit that referenced this pull request Nov 5, 2026
Player 1.4.1: small range reads come from a block cache (#133, #134), a
patch, since nothing docs/compatibility.md covers changes. Embed 1.5.1
pins it exactly and ships it in every site and SCORM zip it writes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A 1.5 MB quiz costs thirteen range requests before it boots: the index is read twice, six requests each time

1 participant