diff --git a/AGENTS.md b/AGENTS.md index 539594b5..77c5c914 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/design/layout.md b/design/layout.md index 556dacb0..92a34d2d 100644 --- a/design/layout.md +++ b/design/layout.md @@ -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 diff --git a/design/libraries.md b/design/libraries.md index 1e764eed..61eb459b 100644 --- a/design/libraries.md +++ b/design/libraries.md @@ -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 diff --git a/design/serving.md b/design/serving.md index 566acfdf..44d32908 100644 --- a/design/serving.md +++ b/design/serving.md @@ -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 @@ -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, @@ -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 @@ -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 diff --git a/design/testing.md b/design/testing.md index c154f967..eb8d3f06 100644 --- a/design/testing.md +++ b/design/testing.md @@ -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/?log=` is a host that honours `Range` and writes down the `Range` header of +every request it takes; `/counted/__log?log=` 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/?rate=` is a host with an outage switch: `Range` honoured, the body paced, and `/stalling/__outage?ms=&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 diff --git a/packages/player/src/shared/block-cache.ts b/packages/player/src/shared/block-cache.ts new file mode 100644 index 00000000..5448f725 --- /dev/null +++ b/packages/player/src/shared/block-cache.ts @@ -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() + /** Blocks on their way, by `blockId`. */ + private readonly pending = new Map>() + 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 + ): Promise { + 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> = [] + 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 + ): 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}` +} diff --git a/packages/player/src/shared/constants.ts b/packages/player/src/shared/constants.ts index 5c74122b..e41b8d26 100644 --- a/packages/player/src/shared/constants.ts +++ b/packages/player/src/shared/constants.ts @@ -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__' diff --git a/packages/player/src/shared/source.ts b/packages/player/src/shared/source.ts index 1b177935..060f56d2 100644 --- a/packages/player/src/shared/source.ts +++ b/packages/player/src/shared/source.ts @@ -1,4 +1,5 @@ -import { ARCHIVE_ENTRY } from './constants.js' +import { BlockCache } from './block-cache.js' +import { ARCHIVE_ENTRY, BLOCK_CACHE_MAX_BYTES, BLOCK_CACHE_MAX_READ, BLOCK_SIZE } from './constants.js' import { ChunkStore } from './chunk-store.js' import { PlayerError, type RemoteSourceDescriptor, type SourceDescriptor } from './protocol.js' import type { ByteRange } from './range.js' @@ -184,13 +185,35 @@ async function sizeFromOpenRange(url: string, signal?: AbortSignal): Promise, readonly size: number - ) {} + ) { + this.blockKey = `${descriptor.url}\u0000${descriptor.validator ?? ''}\u0000${size}` + } /** Counts a body's bytes as they pass, without holding any of them. */ private counted(body: ReadableStream): ReadableStream { @@ -238,17 +261,47 @@ class RangeHttpHandle implements SourceHandle { return response.status === 200 ? sliceStream(body, range) : body } + /** + * A read of at most `BLOCK_CACHE_MAX_READ` — the index, a local header, a small entry — goes + * through the block cache, which fetches whole blocks and keeps them. A longer one is fetched + * as asked and kept nowhere. + */ async read(range: ByteRange): Promise { - return new Uint8Array(await new Response(await this.stream(range)).arrayBuffer()) + if (range.end - range.start + 1 > BLOCK_CACHE_MAX_READ) return this.fetchBytes(range) + return blockCache().read(this.blockKey, this.size, range, (missing) => this.fetchBytes(missing)) } /** - * Every range, streamed or read whole, goes through `resilientStream`: a request that goes - * quiet or fails is opened again from the byte it reached. That covers the segments of a large - * span, the local header a Service Worker reads before an inline entry, and the central - * directory alike — a link that drops for a moment costs a moment, not the job. + * A range of at most one block comes out of the block cache, as does a longer one the cache + * holds whole: zip.js streams an entry's data right after reading its header, and the block that + * held the header usually holds the data too. Anything else streams from the network as it is + * asked for, so a video's bytes never pass through the cache. */ async stream(range: ByteRange): Promise> { + const length = range.end - range.start + 1 + if (length <= BLOCK_SIZE || (length <= BLOCK_CACHE_MAX_READ && blockCache().holds(this.blockKey, range))) { + const bytes = await this.read(range) + return new ReadableStream({ + start(controller) { + controller.enqueue(bytes) + controller.close() + } + }) + } + return this.network(range) + } + + private async fetchBytes(range: ByteRange): Promise { + return new Uint8Array(await new Response(this.network(range)).arrayBuffer()) + } + + /** + * Every request, for a block or a span, goes through `resilientStream`: one that goes quiet or + * fails is opened again from the byte it reached. That covers the segments of a large span, the + * blocks a local header or the central directory lies in, and a warm span alike — a link that + * drops for a moment costs a moment, not the job. + */ + private network(range: ByteRange): ReadableStream { return resilientStream(range, (remaining, signal) => this.attempt(remaining, signal), { // Bytes on any request of this archive: a segment waiting its turn behind one that flows // is not a stalled link. diff --git a/packages/player/src/sw/package-reader.ts b/packages/player/src/sw/package-reader.ts index 09562d3b..587f981e 100644 --- a/packages/player/src/sw/package-reader.ts +++ b/packages/player/src/sw/package-reader.ts @@ -1,5 +1,5 @@ import { ZipReader, type Entry, type FileEntry } from '@zip.js/zip.js' -import { INLINE_MAX_SIZE, MEDIA_INLINE_MAX_SIZE, WARM_ENTRY_MAX_SIZE, WARM_GAP, WARM_MAX_BYTES } from '../shared/constants.js' +import { BLOCK_CACHE_MAX_READ, INLINE_MAX_SIZE, MEDIA_INLINE_MAX_SIZE, WARM_ENTRY_MAX_SIZE, WARM_GAP, WARM_MAX_BYTES } from '../shared/constants.js' import { indexEntryNames, normalizeEntryName } from '../shared/entry-names.js' import { extensionOf, isMediaEntry, isTextEntry } from '../shared/mime.js' import { DEFLATE, LOCAL_HEADER_FIXED_SIZE, STORED, readDataStart } from '../shared/local-header.js' @@ -825,19 +825,21 @@ export class PackageReader { /** * Inflates an entry into a stream. The stream is handed straight to `cache.put()` or to a - * `Response`, so the entry never sits in memory as a whole. + * `Response`, so the entry never sits in memory as a whole — beyond the block cache's copy of a + * small one's compressed bytes over HTTP (`blocksFor`). * * An entry from the central directory goes through zip.js. A forward entry has no zip.js object * behind it and is inflated directly: its compressed span is known from its local header, and * `DecompressionStream` does the rest — the same codec zip.js would have used. */ inflate(entry: IndexedEntry): ReadableStream { - if (!entry.zip) return this.inflateDirect(entry) + const zip = entry.zip + if (!zip) return this.inflateDirect(entry) - if (entry.zip.encrypted) { + if (zip.encrypted) { throw new PlayerError('bad-archive', `${entry.name} is encrypted`) } - const getData = entry.zip.getData + const getData = zip.getData if (!getData) { throw new PlayerError('bad-archive', `${entry.name} has no readable data`) } @@ -847,7 +849,7 @@ export class PackageReader { // zip.js pipes into that writable and aborts it itself when the inflate fails, which errors // the readable the consumer holds — this abort is only the fallback for a rejection that // never reached the stream, and it is refused while zip.js still holds the writer. - void getData.call(entry.zip, transform.writable).catch((error: unknown) => { + void this.blocksFor(entry, zip).then(() => getData.call(zip, transform.writable)).catch((error: unknown) => { // A locked writable means zip.js still holds the writer and has already errored the stream // on its way out; aborting it again is refused, in Chromium by throwing. if (transform.writable.locked) return @@ -861,6 +863,29 @@ export class PackageReader { return transform.readable } + /** + * Pulls a small entry's local header and data into the block cache in one request, before zip.js + * reads them in pieces: the header, to learn where the data starts, its extra field when it has + * one, then the data. Most small entries fit in the block their header is in anyway; this is for + * the one that runs into the next. Over HTTP only, up to `BLOCK_CACHE_MAX_READ`, and never in the + * way: a failure is left for zip.js's own reads to meet. + */ + private blocksFor(entry: IndexedEntry, zip: FileEntry): Promise { + if (this.handle.descriptor.type !== 'range-http') return Promise.resolve() + const start = zip.offset + // The central directory's name and extra lengths are the local header's in practice; a longer + // local extra field only costs zip.js's data read a block of its own. + const end = Math.min( + this.handle.size - 1, + start + LOCAL_HEADER_FIXED_SIZE + zip.rawFilename.length + zip.rawExtraField.length + entry.compressedSize - 1 + ) + if (end - start + 1 > BLOCK_CACHE_MAX_READ) return Promise.resolve() + return this.handle.read({ start, end }).then( + () => undefined, + () => undefined + ) + } + /** * Byte range of an entry's compressed data inside the archive. The central directory records * where the *local* header starts, and the local header's own name and extra fields are what diff --git a/packages/player/tests/browser/range-requests.test.ts b/packages/player/tests/browser/range-requests.test.ts new file mode 100644 index 00000000..4fa980fb --- /dev/null +++ b/packages/player/tests/browser/range-requests.test.ts @@ -0,0 +1,34 @@ +import { describe, expect, it } from 'vitest' +import '../../src/h5p-offline-player' +import { FIXTURES, play } from './utils' + +/** + * What a load costs a host that honours `Range`, counted by the host itself: `/counted/` writes + * down every request it answers. zip.js reads an index in small pieces — the tail, the central + * directory, each entry's local header and then its data — and every piece was a request; the + * reader the Service Worker builds again once libraries are attached asked for all of them again. + * A 1.5 MB quiz paid thirteen requests before it booted (#133). The block cache under small reads + * is what keeps the count down, and this keeps it from creeping back. + */ +async function rangesOf(fixture: string, attributes: Record = {}): Promise { + const log = crypto.randomUUID() + await play(`/counted/${fixture}?log=${log}`, attributes) + return (await fetch(`/counted/__log?log=${log}`)).json() +} + +describe('the requests a load costs', () => { + it('reads a small archive’s index in one request', async () => { + const ranges = await rangesOf('basic.h5p') + // The probe, the index — tail, directory and both JSON files, one block — and the warm. + expect(ranges).toHaveLength(3) + expect(ranges[0]).toBe('bytes=0-0') + }) + + it('asks for nothing again once a bundle is attached and the reader is built anew', async () => { + const ranges = await rangesOf('needs-dependency.h5p', { libraries: FIXTURES.libraries }) + // The probe, the tail, the head, and the warm: the reader built again with the bundle + // attached finds every block it reads already held. + expect(ranges).toHaveLength(4) + expect(new Set(ranges).size).toBe(ranges.length) + }) +}) diff --git a/packages/player/tests/unit/block-cache.test.ts b/packages/player/tests/unit/block-cache.test.ts new file mode 100644 index 00000000..48f7a6fb --- /dev/null +++ b/packages/player/tests/unit/block-cache.test.ts @@ -0,0 +1,154 @@ +import { describe, expect, it } from 'vitest' +import { BlockCache } from '../../src/shared/block-cache' +import type { ByteRange } from '../../src/shared/range' + +/** + * The block cache under small HTTP reads: whole blocks fetched, each once, by contiguous run, + * shared while on their way, bounded by use. Block size 16 here, so the arithmetic stays visible. + */ +const BLOCK = 16 +const SIZE = 100 +const archive = Uint8Array.from({ length: SIZE }, (_, i) => i) + +function source(options: { fail?: boolean; short?: boolean } = {}) { + const asked: ByteRange[] = [] + const waiting: Array<() => void> = [] + let held = false + const fetchRange = async (range: ByteRange) => { + asked.push(range) + if (held) await new Promise((resolve) => waiting.push(resolve)) + if (options.fail) throw new Error('link down') + const end = options.short ? range.end - 1 : range.end + return archive.slice(range.start, end + 1) + } + return { + asked, + fetchRange, + hold: () => (held = true), + release: () => waiting.splice(0).forEach((resolve) => resolve()) + } +} + +describe('BlockCache', () => { + it('returns exactly the bytes asked for, fetched as whole blocks', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange } = source() + + expect(await cache.read('a', SIZE, { start: 20, end: 40 }, fetchRange)).toEqual(archive.slice(20, 41)) + expect(asked).toEqual([{ start: 16, end: 47 }]) + }) + + it('asks for nothing when every block of a read is held', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange } = source() + + await cache.read('a', SIZE, { start: 16, end: 47 }, fetchRange) + expect(await cache.read('a', SIZE, { start: 30, end: 33 }, fetchRange)).toEqual(archive.slice(30, 34)) + expect(cache.holds('a', { start: 16, end: 47 })).toBe(true) + expect(cache.holds('a', { start: 16, end: 48 })).toBe(false) + expect(asked).toHaveLength(1) + }) + + it('fetches what a read is missing in one request per contiguous run', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange } = source() + + // Block 2 held; a read of blocks 0 to 5 misses 0–1 and 3–5. + await cache.read('a', SIZE, { start: 32, end: 32 }, fetchRange) + asked.length = 0 + expect(await cache.read('a', SIZE, { start: 0, end: 95 }, fetchRange)).toEqual(archive.slice(0, 96)) + expect(asked).toEqual([ + { start: 0, end: 31 }, + { start: 48, end: 95 } + ]) + }) + + it('cuts a read at the end of the archive, and the last block with it', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange } = source() + + expect(await cache.read('a', SIZE, { start: 90, end: 200 }, fetchRange)).toEqual(archive.slice(90, 100)) + expect(asked).toEqual([{ start: 80, end: 99 }]) + expect(await cache.read('a', SIZE, { start: 100, end: 110 }, fetchRange)).toEqual(new Uint8Array(0)) + }) + + it('lets reads that need the same block share one fetch', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange, hold, release } = source() + + hold() + const first = cache.read('a', SIZE, { start: 0, end: 5 }, fetchRange) + const second = cache.read('a', SIZE, { start: 10, end: 20 }, fetchRange) + await Promise.resolve() + release() + + expect(await first).toEqual(archive.slice(0, 6)) + expect(await second).toEqual(archive.slice(10, 21)) + // Block 0 once, for both; block 1 for the second read alone. + expect(asked).toEqual([ + { start: 0, end: 15 }, + { start: 16, end: 31 } + ]) + }) + + it('keeps nothing from a fetch that failed, so the next read asks again', async () => { + const cache = new BlockCache(BLOCK, 1024) + const failing = source({ fail: true }) + + await expect(cache.read('a', SIZE, { start: 0, end: 5 }, failing.fetchRange)).rejects.toThrow('link down') + expect(cache.holds('a', { start: 0, end: 5 })).toBe(false) + + const working = source() + expect(await cache.read('a', SIZE, { start: 0, end: 5 }, working.fetchRange)).toEqual(archive.slice(0, 6)) + expect(working.asked).toHaveLength(1) + }) + + it('refuses a short answer rather than keep a block that looks whole', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { fetchRange } = source({ short: true }) + + await expect(cache.read('a', SIZE, { start: 0, end: 5 }, fetchRange)).rejects.toThrow('Expected 16 bytes') + expect(cache.holds('a', { start: 0, end: 5 })).toBe(false) + }) + + it('holds at most its bound, the least recently used block going first', async () => { + const cache = new BlockCache(BLOCK, 3 * BLOCK) + const { asked, fetchRange } = source() + + for (const index of [0, 1, 2]) await cache.read('a', SIZE, { start: index * BLOCK, end: index * BLOCK }, fetchRange) + // Block 0 used again, so block 1 is now the oldest, and a fourth block evicts it. + await cache.read('a', SIZE, { start: 0, end: 0 }, fetchRange) + await cache.read('a', SIZE, { start: 48, end: 48 }, fetchRange) + + expect(cache.holds('a', { start: 0, end: 0 })).toBe(true) + expect(cache.holds('a', { start: 16, end: 16 })).toBe(false) + expect(cache.holds('a', { start: 32, end: 63 })).toBe(true) + expect(asked).toHaveLength(4) + }) + + it('assembles a read longer than its bound from the blocks it fetched', async () => { + const cache = new BlockCache(BLOCK, BLOCK) + const { fetchRange } = source() + + expect(await cache.read('a', SIZE, { start: 5, end: 70 }, fetchRange)).toEqual(archive.slice(5, 71)) + }) + + it('keeps the blocks of one archive apart from another', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange } = source() + + await cache.read('a', SIZE, { start: 0, end: 5 }, fetchRange) + await cache.read('b', SIZE, { start: 0, end: 5 }, fetchRange) + expect(asked).toHaveLength(2) + }) + + it('forgets everything on clear', async () => { + const cache = new BlockCache(BLOCK, 1024) + const { asked, fetchRange } = source() + + await cache.read('a', SIZE, { start: 0, end: 5 }, fetchRange) + cache.clear() + await cache.read('a', SIZE, { start: 0, end: 5 }, fetchRange) + expect(asked).toHaveLength(2) + }) +}) diff --git a/packages/player/tests/unit/range-http-handle.test.ts b/packages/player/tests/unit/range-http-handle.test.ts index 098c9462..eff37fa1 100644 --- a/packages/player/tests/unit/range-http-handle.test.ts +++ b/packages/player/tests/unit/range-http-handle.test.ts @@ -1,7 +1,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest' -import { openSource } from '../../src/shared/source' +import { BLOCK_CACHE_MAX_READ, BLOCK_SIZE } from '../../src/shared/constants' +import { forgetBlocks, openSource } from '../../src/shared/source' +import { PackageReader } from '../../src/sw/package-reader' +import { collect, manifest, zipOf } from './helpers/archives' -const SIZE = 64 * 1024 +const SIZE = 2 * 1024 * 1024 const archive = new Uint8Array(SIZE) for (let i = 0; i < SIZE; i += 1) archive[i] = i % 251 @@ -30,10 +33,29 @@ function countingBody(bytes: Uint8Array, piece = 1024) { return { stream, pulled: () => pulled, cancelled: () => cancelled } } -describe('RangeHttpHandle.read', () => { - afterEach(() => vi.unstubAllGlobals()) +/** A host that honours `Range` over `bytes`, keeping the ranges it was asked for. */ +function rangeHost(bytes: Uint8Array) { + const asked: string[] = [] + vi.stubGlobal('fetch', async (_url: string, init?: RequestInit) => { + const header = new Headers(init?.headers).get('range') ?? '' + asked.push(header) + const [, from, to] = /^bytes=(\d+)-(\d+)$/.exec(header)! + const end = Math.min(Number(to), bytes.length - 1) + return new Response(bytes.slice(Number(from), end + 1), { + status: 206, + headers: { 'content-range': `bytes ${from}-${end}/${bytes.length}` } + }) + }) + return asked +} - it('takes only the slice, and stops the transfer, when a host answers 200 to a Range request', async () => { +afterEach(() => { + vi.unstubAllGlobals() + forgetBlocks() +}) + +describe('RangeHttpHandle.read', () => { + it('takes only the blocks it needs, and stops the transfer, when a host answers 200 to a Range request', async () => { const body = countingBody(archive) vi.stubGlobal('fetch', async () => new Response(body.stream, { status: 200 })) @@ -42,19 +64,96 @@ describe('RangeHttpHandle.read', () => { await new Promise((resolve) => setTimeout(resolve, 0)) expect(bytes).toEqual(archive.subarray(range.start, range.end + 1)) - // The pipe ended at the slice and cancelled the body: `stream()` always worked this way, and + // The pipe ended at the block and cancelled the body: `stream()` always worked this way, and // `read()` buffering the whole archive instead meant four whole archives under segmenting. expect(body.cancelled()).toBe(true) expect(body.pulled()).toBeLessThan(SIZE / 2) }) it('returns a 206 body whole, since the host already cut it', async () => { - vi.stubGlobal( - 'fetch', - async () => new Response(archive.slice(range.start, range.end + 1), { status: 206 }) - ) + const asked = rangeHost(archive) const handle = await openSource('pkg', descriptor) expect(await handle.read(range)).toEqual(archive.subarray(range.start, range.end + 1)) + expect(asked).toEqual([`bytes=0-${BLOCK_SIZE - 1}`]) + }) + + it('shares its blocks with a handle opened later on the same archive', async () => { + const asked = rangeHost(archive) + + await (await openSource('pkg', descriptor)).read(range) + const again = await openSource('pkg', descriptor) + expect(await again.read({ start: 100, end: 200 })).toEqual(archive.subarray(100, 201)) + expect(asked).toHaveLength(1) + + // A republished archive at the same URL is other bytes. + await (await openSource('pkg', { ...descriptor, validator: '"v2"' })).read(range) + expect(asked).toHaveLength(2) + }) + + it('fetches a read longer than the bound as asked, and keeps none of it', async () => { + const asked = rangeHost(archive) + const handle = await openSource('pkg', descriptor) + const long = { start: 10, end: 10 + BLOCK_CACHE_MAX_READ } + + expect(await handle.read(long)).toEqual(archive.subarray(long.start, long.end + 1)) + await handle.read(long) + expect(asked).toEqual([`bytes=${long.start}-${long.end}`, `bytes=${long.start}-${long.end}`]) + }) +}) + +describe('RangeHttpHandle.stream', () => { + it('serves a range of one block from the cache, and streams a longer one from the network as asked', async () => { + const asked = rangeHost(archive) + const handle = await openSource('pkg', descriptor) + + await handle.read({ start: 0, end: 10 }) + expect(await collect(await handle.stream({ start: 100, end: 5000 }))).toEqual(archive.subarray(100, 5001)) + expect(asked).toHaveLength(1) + + const media = { start: 200_000, end: 600_000 } + expect(await collect(await handle.stream(media))).toEqual(archive.subarray(media.start, media.end + 1)) + expect(asked).toEqual([`bytes=0-${BLOCK_SIZE - 1}`, `bytes=${media.start}-${media.end}`]) + // Not kept: the cache holds index reads and small entries, not media. + await handle.stream(media).then(collect) + expect(asked).toHaveLength(3) + }) +}) + +describe('an index read over HTTP', () => { + /** + * zip.js reads an index in small pieces: the tail, the central directory inside it, then each + * entry's local header and its data. Every piece was a request, and the reader the Service + * Worker builds again once libraries are attached asked for all of them again (#133). + */ + async function quiz() { + // Entries from the start to well past the first block, so the tail and the head are apart. + const media = Uint8Array.from({ length: 300_000 }, (_, i) => (i * 7919) % 256) + return zipOf( + { + 'h5p.json': manifest('H5P.Quiz', [['H5P.Quiz', 1, 0]]), + 'H5P.Quiz-1.0/library.json': '{"machineName":"H5P.Quiz","majorVersion":1,"minorVersion":0}', + 'content/images/photo.jpg': media, + 'content/content.json': JSON.stringify({ questions: ['one', 'two', 'three'] }) + }, + { stored: ['content/images/photo.jpg'] } + ) + } + + it('costs the tail and the head, and a reader built again asks for nothing', async () => { + const bytes = await quiz() + const asked = rangeHost(bytes) + const archiveDescriptor = { type: 'range-http', url: 'https://host.example/quiz.h5p', size: bytes.length } as const + + const first = await PackageReader.open('pkg', await openSource('pkg', archiveDescriptor)) + const content = new TextDecoder().decode(await collect(first.inflate(first.get('content/content.json')!.entry))) + expect(JSON.parse(content).questions).toHaveLength(3) + // The tail (end-of-directory search and the directory, and content.json beside it) and the + // head (h5p.json): two requests, where each of those pieces was one of its own. + expect(asked).toHaveLength(2) + + const again = await PackageReader.open('pkg', await openSource('pkg', archiveDescriptor)) + await collect(again.inflate(again.get('content/content.json')!.entry)) + expect(asked).toHaveLength(2) }) }) diff --git a/packages/player/vite.plugins.ts b/packages/player/vite.plugins.ts index 05de5833..7649e363 100644 --- a/packages/player/vite.plugins.ts +++ b/packages/player/vite.plugins.ts @@ -270,22 +270,63 @@ function compressingHostHandler(dirs: readonly string[]): Connect.NextHandleFunc res.setHeader('vary', 'Accept-Encoding') if (gzip) res.setHeader('content-encoding', 'gzip') - const range = parseRangeHeader(req.headers.range, body.length) - if (range === null) { - res.setHeader('content-length', String(body.length)) - res.statusCode = 200 - return res.end(body) - } - if (range === 'unsatisfiable') { - res.setHeader('content-range', `bytes */${body.length}`) - res.statusCode = 416 - return res.end() - } - const piece = body.subarray(range.start, range.end + 1) - res.setHeader('content-length', String(piece.length)) - res.setHeader('content-range', `bytes ${range.start}-${range.end}/${body.length}`) - res.statusCode = 206 - res.end(piece) + answerRange(req.headers.range, res, body) + }, + () => noSuchFixture(res) + ) + } +} + +/** Answers `rangeHeader` from `body` as a host that honours `Range` does: 200, 206 or 416. */ +function answerRange(rangeHeader: string | undefined, res: ServerResponse, body: Buffer): void { + const range = parseRangeHeader(rangeHeader, body.length) + if (range === null) { + res.setHeader('content-length', String(body.length)) + res.statusCode = 200 + return void res.end(body) + } + if (range === 'unsatisfiable') { + res.setHeader('content-range', `bytes */${body.length}`) + res.statusCode = 416 + return void res.end() + } + const piece = body.subarray(range.start, range.end + 1) + res.setHeader('content-length', String(piece.length)) + res.setHeader('content-range', `bytes ${range.start}-${range.end}/${body.length}`) + res.statusCode = 206 + res.end(piece) +} + +/** + * A host that honours `Range` and writes down what it is asked, so a test can count what a load + * costs: `/counted/?log=` serves the archive, and `/counted/__log?log=` answers + * the `Range` header of every request it took for that id, in the order they came. The id keeps + * test cases apart, and makes each load a package of its own, with nothing cached from another. + */ +function countingHostHandler(dirs: readonly string[]): Connect.NextHandleFunction { + const prefix = '/counted/' + const logs = new Map() + + return (req, res, next) => { + const url = new URL(req.url ?? '/', 'http://localhost') + const id = url.searchParams.get('log') ?? '' + if (url.pathname === `${prefix}__log`) { + res.setHeader('content-type', 'application/json') + res.setHeader('cache-control', 'no-store') + return void res.end(JSON.stringify(logs.get(id) ?? [])) + } + const name = fixtureName(url.pathname, prefix) + if (!name) return next() + + const log = logs.get(id) ?? [] + logs.set(id, log) + log.push(req.headers.range ?? '') + archivePath(dirs, name).then((path) => readFile(path)).then( + (body) => { + res.setHeader('content-type', 'application/octet-stream') + res.setHeader('cache-control', 'no-store') + res.setHeader('accept-ranges', 'bytes') + answerRange(req.headers.range, res, body) }, () => noSuchFixture(res) ) @@ -406,6 +447,7 @@ export function noRangeFixturesPlugin(dirs: readonly string[] = [PLAYER_FIXTURES server.middlewares.use(noRangeHandler(dirs)) server.middlewares.use(compressingHostHandler(dirs)) server.middlewares.use(stallingHostHandler(dirs)) + server.middlewares.use(countingHostHandler(dirs)) } }