Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,10 +145,11 @@ Node 22 LTS or 24 LTS: the commands the packages ship need 22, and the browser p

### Serving archives: [`design/serving.md`](design/serving.md)

Read it before changing the Service Worker's file server (`src/sw/mount.ts`, `package-reader.ts`, `routes.ts`, `watermark-wait.ts`), how a source is read (`src/shared/source.ts`, `source-reader.ts`, `span-stream.ts`, `resilient-stream.ts`, `range.ts`, `local-header.ts`, `forward-index.ts`, `mime.ts`) or the warm (`src/jobs/warm.ts`).
Read it before changing the Service Worker's file server (`src/sw/mount.ts`, `package-reader.ts`, `routes.ts`, `watermark-wait.ts`), how a source is read (`src/shared/source.ts`, `block-cache.ts`, `source-reader.ts`, `span-stream.ts`, `resilient-stream.ts`, `range.ts`, `local-header.ts`, `forward-index.ts`, `mime.ts`) or the warm (`src/jobs/warm.ts`).

- `SourceReader` overrides `createReadable`.
- A large span over HTTP is then pulled by several connections at once.
- Small reads over HTTP go through a block cache, and a rebuilt reader finds it.
- Waiting on the watermark is bounded by a stall, not by a wall clock.
- A ranged read survives the link, and a body the server gives up on ends short.
- A body that streams holds its fetch event open.
Expand Down
1 change: 1 addition & 0 deletions design/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ packages/player/ @missing-elements/h5p-offline-player — the published
constants.ts sizes, timeouts, cache names, the version stamp
protocol.ts every message shape and the PackageRecord written to IndexedDB
source.ts probe + the three source adapters; imports no zip.js, so the element stays small
block-cache.ts 64 kB blocks under the range adapter's small reads, so an index costs a request or two, not one per piece
source-reader.ts the zip.js reader bridge — the one module besides package-reader that imports zip.js
span-stream.ts how a span is pulled: one request, or several at once over HTTP; shared by the bridge and the Jobs worker
resilient-stream.ts a ranged read that opens itself again from the byte it reached when the link goes quiet or drops
Expand Down
3 changes: 2 additions & 1 deletion design/libraries.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@ Which libraries a package plays with: the check that it has them, the sources in
top-level library — so the element asks the `libraries` sources for it, and that package plays
with the pack. The element asks for it with `deep` on `index`: at once for a picked file or a
downloaded archive, and on a host with `Range` only after the warm, reading each `library.json`
from the cache, since before it each would be two ranged requests. `needs-dependency.h5p` is
from the cache, since before it each would be a ranged request (two before the block cache, in
*Small reads over HTTP go through a block cache*). `needs-dependency.h5p` is
the fixture, laid out as an export is: its library folder first, media last.
On a host without `Range` the deep check waits for the end of the download, and the frame can
boot before then from the forward index, so the same walk decides that too (`bootsEarly` in
Expand Down
40 changes: 35 additions & 5 deletions design/serving.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Serving archives

How a package's bytes reach the H5P runtime: the Service Worker's virtual file server, how a source is read (one request, several at once, again after a stall), media that streams and media that cannot, the warm, and the index built while a download is still arriving. The code: `packages/player/src/sw/` (`mount.ts`, `package-reader.ts`, `routes.ts`, `watermark-wait.ts`), `src/shared/` (`source.ts`, `source-reader.ts`, `span-stream.ts`, `resilient-stream.ts`, `range.ts`, `local-header.ts`, `forward-index.ts`, `mime.ts`) and `src/jobs/warm.ts`.
How a package's bytes reach the H5P runtime: the Service Worker's virtual file server, how a source is read (one request, several at once, small reads from a block cache, again after a stall), media that streams and media that cannot, the warm, and the index built while a download is still arriving. The code: `packages/player/src/sw/` (`mount.ts`, `package-reader.ts`, `routes.ts`, `watermark-wait.ts`), `src/shared/` (`source.ts`, `block-cache.ts`, `source-reader.ts`, `span-stream.ts`, `resilient-stream.ts`, `range.ts`, `local-header.ts`, `forward-index.ts`, `mime.ts`) and `src/jobs/warm.ts`.

## Invariants

Expand Down Expand Up @@ -36,6 +36,35 @@ How a package's bytes reach the H5P runtime: the Service Worker's virtual file s
keeps a request's bytes as they arrive and the consumer follows it live when its turn comes,
and the window fills only after the first byte, which costs a per-connection-capped host one
round trip and nothing else. Same 40 MB at 4 Mbit/s now: first byte in under two seconds.
- **Small reads over HTTP go through a block cache, and a rebuilt reader finds it.** zip.js reads
an index in pieces, one after another: 65,557 bytes from the end to find the end-of-central-
directory record, then the directory — which in a package of a few hundred entries lies inside
those same bytes — then each entry's 30-byte local header, its extra field when it has one, and
its data. Over HTTP every piece was a request, and the reader the Service Worker builds again
after `attach-libraries` — on every load that names the pack, since the pack attaches its newer
parts — read them all again. Measured on 2026-11-04 with the demo's 1.5 MB quiz from a Lovable
site (Cloudflare in front) and from Vercel: fourteen ranged requests to `ready`, thirteen of them
small and in sequence at 0.2–0.4 s each, about 2.4 s of a 5.5 s first load; an archive zip.js
wrote, with extra fields, paid three requests an entry (#133). So `RangeHttpHandle.read` takes a
range of at most `BLOCK_CACHE_MAX_READ` from a `BlockCache`, pdf.js's design
(`ChunkedStreamManager`): blocks of `BLOCK_SIZE`, 64 kB, aligned from the start of the archive,
the missing ones fetched in one request per contiguous run, each fetched once and shared while
on its way, at most `BLOCK_CACHE_MAX_BYTES` (4 MB) held per worker, the least recently used going
first. `stream` serves a range of at most one block from it too, and a longer one the cache holds
whole, since zip.js streams an entry's data right after reading its header; anything else
streams from the network as before, so media never passes through the cache. And
`PackageReader.inflate` pulls a small entry's header and data in one read before zip.js reads
them in pieces (`blocksFor`). The cache is one per worker, made on first use so the element's
bundle does not carry it, keyed by the archive's URL, validator and
size — the package id's ingredients — so the new handle a rebuilt reader opens finds the blocks
the first one fetched; it dies with the worker, and it is never authority. The quiz now costs
four: the probe, the tail, the head and the warm. Two things left out on purpose, by the owner's
decision the same day: a whole-file download below a size, which with the cache saves one
request and needs a threshold; and rules per content type for what to fetch first, which would
tie the player to the libraries. `tests/unit/block-cache.test.ts` pins the cache,
`tests/unit/range-http-handle.test.ts` a real archive's index over a host that honours `Range`,
and `tests/browser/range-requests.test.ts` counts what a load costs at `/counted/`, a host that
writes down every request it takes.
- **Waiting on the watermark is bounded by a stall, not by a wall clock.** Inflating a few hundred
megabytes over a network legitimately takes minutes, and a request for the *tail* of such an
entry cannot be answered until it finishes: an mp4 whose `moov` index sits at the end — common,
Expand All @@ -58,8 +87,9 @@ How a package's bytes reach the H5P runtime: the Service Worker's virtual file s
handler throwing on the way and leaving its play icon on. A media element never asks again
after that. The extraction, alive throughout, finished a minute later, which is why a reload
played from cache. A host that dropped the connection did the same by a shorter path: the
fetch rejected, the job failed, same error. Three things now hold. `RangeHttpHandle.stream` —
and `read`, which goes through it — is a `resilientStream`: a request that delivers nothing for
fetch rejected, the job failed, same error. Three things now hold. Every request
`RangeHttpHandle` makes — a span for `stream`, the blocks behind `read` — is a
`resilientStream`: a request that delivers nothing for
`READ_STALL_MS`, fails, or ends early is opened again from the byte it reached, after a delay
that doubles from `READ_RETRY_DELAY_MS`, and `READ_RETRIES` consecutive attempts without a byte
fail it; the count starts over whenever bytes arrive, so a link that stalls now and then over a
Expand Down Expand Up @@ -158,8 +188,8 @@ How a package's bytes reach the H5P runtime: the Service Worker's virtual file s
the fallback with CORS-filtered headers.
- **On a host that honours `Range`, the libraries are pulled whole before the frame boots.** The
runtime reads them exhaustively at boot — every `library.json`, script and stylesheet — and an
inline entry read on demand costs two ranged requests, the 30-byte local header and then the
data. Measured against a real host (nginx in front of a store, `stream.dev.mkis.fwu.de`): a
inline entry read on demand cost two ranged requests, the 30-byte local header and then the
data (one since the block cache, or none when its block is already held). Measured against a real host (nginx in front of a store, `stream.dev.mkis.fwu.de`): a
90 MB package with 53 libraries took 136 s to `ready`, 128 of them in 156 requests for 0.54 MB,
because that host answers one client's requests roughly one at a time — eight small ranges
fired together took 4.8 to 14 s each, the same eight in sequence 0.5 to 0.7 s. Its non-media
Expand Down
5 changes: 5 additions & 0 deletions design/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,11 @@ same-origin, so every header is readable and the probe never needs its size fall
browser test pins the two lengths the same archive answers with, and the unit test covers the
fallback against headers filtered the way CORS filters them.

`/counted/<fixture>?log=<id>` is a host that honours `Range` and writes down the `Range` header of
every request it takes; `/counted/__log?log=<id>` answers them in order. `range-requests.test.ts`
counts what a load costs with it, so the requests an index read takes cannot creep back up (#133):
the id makes each load a package of its own and keeps cases apart.

`/stalling/<fixture>?rate=<bytes per second>` is a host with an outage switch: `Range` honoured, the
body paced, and `/stalling/__outage?ms=<n>&mode=silent|reset` takes it away for a while — every
response in flight goes quiet and new requests wait, or every response in flight is destroyed and
Expand Down
165 changes: 165 additions & 0 deletions packages/player/src/shared/block-cache.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
import type { ByteRange } from './range.js'

/**
* Small reads of an archive, kept in fixed blocks so that reading the same bytes again costs no
* request. pdf.js's loader is the model: it reads a document in ranges aligned to 64 kB chunk
* boundaries and fetches each chunk once (`ChunkedStreamManager`).
*
* zip.js reads an index in small pieces, one after another: 64 kB from the end to find the end of
* the central directory, then the directory, which in a package of a few hundred entries lies
* inside those same bytes, then each entry's 30-byte local header and after it the data. Over
* HTTP each piece was a request, and the reader the Service Worker builds again once libraries are
* attached read every one of them again: thirteen ranged requests in sequence before a 1.5 MB quiz
* booted (#133). Through this cache the tail and the directory are one request, a small entry's
* header and data share one, and a rebuilt reader asks for nothing.
*
* Blocks are aligned to multiples of the block size from the start of the archive, and the blocks
* a read is missing are fetched in one request per contiguous run. A block on its way is shared: a
* second read that needs it waits for that fetch instead of asking again, and a fetch that fails
* is forgotten, so the next read asks again. Once more than `maxBytes` are held the least recently
* used block goes first; a read keeps hold of the blocks it is assembling, so eviction never takes
* bytes out from under it.
*
* Nothing here is authority: the key names the bytes — the archive's URL, validator and size, the
* ingredients of its package id — and the cache dies with the worker that holds it.
*/
export class BlockCache {
/** Held blocks by `blockId`, oldest use first: a use moves a block to the end. */
private readonly blocks = new Map<string, Uint8Array>()
/** Blocks on their way, by `blockId`. */
private readonly pending = new Map<string, Promise<Uint8Array>>()
private held = 0

constructor(
private readonly blockSize: number,
private readonly maxBytes: number
) {}

/** Whether every block of `range` is held, so that reading it costs nothing. */
holds(key: string, range: ByteRange): boolean {
const last = Math.floor(range.end / this.blockSize)
for (let index = Math.floor(range.start / this.blockSize); index <= last; index += 1) {
if (!this.blocks.has(blockId(key, index))) return false
}
return true
}

/**
* The bytes of `range` in an archive of `size` bytes: from the blocks held, and for the blocks
* missing from `fetchRange`, which is asked for whole blocks, one request per contiguous run. A
* range reaching past the end of the archive is cut at the end, as a host cuts it.
*/
async read(
key: string,
size: number,
range: ByteRange,
fetchRange: (range: ByteRange) => Promise<Uint8Array>
): Promise<Uint8Array> {
const start = range.start
const end = Math.min(range.end, size - 1)
if (end < start) return new Uint8Array(0)

const first = Math.floor(start / this.blockSize)
const last = Math.floor(end / this.blockSize)

// The missing blocks, fetched by run. Nothing awaits between finding them and marking them
// pending, so two reads that start together never fetch the same block twice.
let runStart = -1
for (let index = first; index <= last + 1; index += 1) {
const id = blockId(key, index)
if (index <= last && !this.blocks.has(id) && !this.pending.has(id)) {
if (runStart < 0) runStart = index
continue
}
if (runStart >= 0) {
this.fetchRun(key, size, runStart, index - 1, fetchRange)
runStart = -1
}
}

const parts: Array<Uint8Array | Promise<Uint8Array>> = []
for (let index = first; index <= last; index += 1) {
const id = blockId(key, index)
parts.push(this.use(id) ?? this.pending.get(id)!)
}
const blocks = await Promise.all(parts)

const out = new Uint8Array(end - start + 1)
blocks.forEach((block, i) => {
const blockStart = (first + i) * this.blockSize
const from = Math.max(start, blockStart)
const to = Math.min(end, blockStart + block.length - 1)
out.set(block.subarray(from - blockStart, to - blockStart + 1), from - start)
})
return out
}

/** Forgets every block held. Blocks on their way still arrive, and are kept. */
clear(): void {
this.blocks.clear()
this.held = 0
}

/** Fetches blocks `firstIndex` to `lastIndex` in one request, each pending until it arrives. */
private fetchRun(
key: string,
size: number,
firstIndex: number,
lastIndex: number,
fetchRange: (range: ByteRange) => Promise<Uint8Array>
): void {
const start = firstIndex * this.blockSize
const end = Math.min((lastIndex + 1) * this.blockSize, size) - 1
const fetching = fetchRange({ start, end }).then((bytes) => {
// A short answer would leave a block that looks whole and is not.
if (bytes.length !== end - start + 1) {
throw new Error(`Expected ${end - start + 1} bytes at ${start}, got ${bytes.length}`)
}
return bytes
})

for (let index = firstIndex; index <= lastIndex; index += 1) {
const id = blockId(key, index)
const offset = (index - firstIndex) * this.blockSize
const block = fetching.then((bytes) => {
// A copy, so that evicting one block frees it rather than the whole run staying held.
const piece = bytes.slice(offset, Math.min(offset + this.blockSize, bytes.length))
this.keep(id, piece)
return piece
})
this.pending.set(id, block)
// Settled either way it is no longer on its way: held if it arrived, asked for again if not.
const settled = () => {
if (this.pending.get(id) === block) this.pending.delete(id)
}
block.then(settled, settled)
}
}

private use(id: string): Uint8Array | undefined {
const block = this.blocks.get(id)
if (!block) return undefined
this.blocks.delete(id)
this.blocks.set(id, block)
return block
}

private keep(id: string, block: Uint8Array): void {
const previous = this.blocks.get(id)
if (previous) {
this.held -= previous.length
this.blocks.delete(id)
}
this.blocks.set(id, block)
this.held += block.length
while (this.held > this.maxBytes) {
const [oldest, bytes] = this.blocks.entries().next().value as [string, Uint8Array]
this.held -= bytes.length
this.blocks.delete(oldest)
}
}
}

function blockId(key: string, index: number): string {
return `${index}\u0000${key}`
}
11 changes: 11 additions & 0 deletions packages/player/src/shared/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,17 @@ export const SEGMENT_CONCURRENCY = 4
/** Below this, one request is better: the overlap cannot pay back its own latency. */
export const SEGMENT_MIN_SPAN = 8 * 1024 * 1024

/**
* Small reads of an archive over HTTP go through a cache of `BLOCK_SIZE` blocks, aligned from the
* start of the archive — pdf.js's chunk size, and zip.js's own step through an index. At most
* `BLOCK_CACHE_MAX_BYTES` are held per worker, the least recently used going first. A read longer
* than `BLOCK_CACHE_MAX_READ` bypasses the cache, and so does a stream longer than one block that
* the cache does not already hold, so media never passes through it. See `block-cache.ts`.
*/
export const BLOCK_SIZE = 64 * 1024
export const BLOCK_CACHE_MAX_BYTES = 4 * 1024 * 1024
export const BLOCK_CACHE_MAX_READ = 1024 * 1024

/** Reserved chunk-store entry name for the archive itself (chunked adapter). */
export const ARCHIVE_ENTRY = '__archive__'

Expand Down
Loading
Loading