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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ Read it before changing the Service Worker's file server (`src/sw/mount.ts`, `pa

- `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.
- Small reads over HTTP go through a block cache, and a rebuilt reader finds it; with a validator, so does a worker started again.
- 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
24 changes: 22 additions & 2 deletions design/serving.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ 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
- **Small reads over HTTP go through a block cache, and a rebuilt reader finds it; with a validator, so does a worker started again.** 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
Expand All @@ -57,14 +57,34 @@ How a package's bytes reach the H5P runtime: the Service Worker's virtual file s
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
the first one fetched; it dies with the worker, but for the blocks an index was read from, 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.

The blocks an index was read from outlive the worker (2026-11-07, #136). Chromium stops an idle
worker after about thirty seconds, so the usual revisit found the cache empty and read the tail
and the head again, one after the other, before the worker answered anything. Measured on the
demo's quiz from a host paced to 1 MB/s with 100 ms on every request, the worker stopped
through CDP between the loads: a reload took four requests and was ready at 0.64 s. Now, at the
end of each `index` of a whole reader over HTTP, `keepIndexBlocks` writes the blocks that
reader's small reads went through (`blocksReadBy`: the index, `content.json`, whatever the load
read before the boot; the player names no file) into the package's cache, with the validator
and the size they were read under. `openReader` puts them back (`seedBlocks`) before zip.js
opens the archive, when both still match, and the same reload is the probe alone, ready at
0.21 s. Only with a validator: without one, an archive republished at the same URL keeps its
package id, and old blocks would send zip.js to the old offsets, so such a host reads the index
again. A copy that is missing, cut short or of the wrong length is read around, never trusted
(`BlockCache.seed` checks each block's length for its place), and it goes with the package's
cache when that is evicted. The bytes are kept rather than a parsed index, so zip.js stays the
only parser, and the price is one Cache API read in place of a round trip.
`tests/browser-emulated/worker-stopped.test.ts` stops the worker and counts the reload's
requests at `/counted/` with an `ETag` and without.
- **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 Down
5 changes: 4 additions & 1 deletion docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@ caching and upgrades.

- The page on `https://`, or `localhost` while developing: the player needs a Service Worker.
- CORS headers on the package host, so the page can read the `.h5p`. `Range` support is optional:
without it the archive is downloaded once and played from the cache.
without it the archive is downloaded once and played from the cache. On another origin, add
`Access-Control-Expose-Headers: ETag` (or `Last-Modified`): the player can then tell an archive
republished at the same URL from the old one, and a reload after the browser stopped its
worker reads nothing of the archive but one byte.
- A browser with Service Workers, the Cache API, IndexedDB, Web Locks and `DecompressionStream`;
[Compatibility](compatibility.md) says which are tested.

Expand Down
34 changes: 33 additions & 1 deletion packages/player/src/shared/block-cache.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,10 @@ import type { ByteRange } from './range.js'
* 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.
* ingredients of its package id — and the cache dies with the worker that holds it. The blocks
* an index was read from are the exception: kept with the package when the archive has a
* validator (`blocksOf`), and put back by the next worker (`seed`), so a worker the browser
* stopped does not read the index again (#136).
*/
export class BlockCache {
/** Held blocks by `blockId`, oldest use first: a use moves a block to the end. */
Expand Down Expand Up @@ -94,6 +97,35 @@ export class BlockCache {
return out
}

/**
* The blocks of `key` held among `indices`, in that order, for keeping beyond this worker
* (#136): a worker the browser stops takes its cache with it, and the next one read the index
* again. One not held is left out.
*/
blocksOf(key: string, indices: Iterable<number>): Array<{ index: number; bytes: Uint8Array }> {
const out: Array<{ index: number; bytes: Uint8Array }> = []
for (const index of indices) {
const bytes = this.blocks.get(blockId(key, index))
if (bytes) out.push({ index, bytes })
}
return out
}

/**
* Holds blocks of `key`, in an archive of `size` bytes, that an earlier worker read: from then
* on a read finds them as if fetched. A block of the wrong length for its place is left out,
* and so is one already held or on its way, which is as good or newer.
*/
seed(key: string, size: number, blocks: Iterable<{ index: number; bytes: Uint8Array }>): void {
for (const { index, bytes } of blocks) {
const id = blockId(key, index)
const expected = Math.min(this.blockSize, size - index * this.blockSize)
if (!Number.isInteger(index) || index < 0 || expected <= 0 || bytes.length !== expected) continue
if (this.blocks.has(id) || this.pending.has(id)) continue
this.keep(id, bytes)
}
}

/** Forgets every block held. Blocks on their way still arrive, and are kept. */
clear(): void {
this.blocks.clear()
Expand Down
73 changes: 73 additions & 0 deletions packages/player/src/shared/chunk-store.ts
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,59 @@ function forwardIndexKey(pkgId: string): string {
return `${CHUNK_KEY_ORIGIN}${pkgId}/chunk/${encodeEntry(ARCHIVE_ENTRY)}${FORWARD_INDEX_MARKER}`
}

/** Beside the package's entries, not among them: the blocks are pieces of the archive, not of an entry. */
function indexBlocksKey(pkgId: string): string {
return `${CHUNK_KEY_ORIGIN}${pkgId}/index-blocks`
}

/**
* The blocks an archive's index was read from over HTTP, kept with the package (#136), and what
* they were read under: the host's validator and the archive's size. A worker started again puts
* them back in its block cache only when both still match.
*/
export interface IndexBlocks {
validator: string
size: number
blocks: Array<{ index: number; bytes: Uint8Array }>
}

/** One body: four bytes giving the length of a JSON head, the head, then each block's bytes in turn. */
function encodeIndexBlocks({ validator, size, blocks }: IndexBlocks): Uint8Array<ArrayBuffer> {
const head = new TextEncoder().encode(
JSON.stringify({ validator, size, blocks: blocks.map(({ index, bytes }) => ({ index, length: bytes.length })) })
)
const body = new Uint8Array(4 + head.length + blocks.reduce((sum, { bytes }) => sum + bytes.length, 0))
new DataView(body.buffer).setUint32(0, head.length)
body.set(head, 4)
let at = 4 + head.length
for (const { bytes } of blocks) {
body.set(bytes, at)
at += bytes.length
}
return body
}

/** `undefined` for a body that is not what `encodeIndexBlocks` writes, whole. */
function decodeIndexBlocks(body: Uint8Array): IndexBlocks | undefined {
if (body.length < 4) return undefined
const length = new DataView(body.buffer, body.byteOffset, body.byteLength).getUint32(0)
if (4 + length > body.length) return undefined
const head = JSON.parse(new TextDecoder().decode(body.subarray(4, 4 + length))) as {
validator?: unknown
size?: unknown
blocks?: Array<{ index?: unknown; length?: unknown }>
}
if (typeof head.validator !== 'string' || typeof head.size !== 'number' || !Array.isArray(head.blocks)) return undefined
const blocks: IndexBlocks['blocks'] = []
let at = 4 + length
for (const { index, length: bytes } of head.blocks) {
if (typeof index !== 'number' || typeof bytes !== 'number' || at + bytes > body.length) return undefined
blocks.push({ index, bytes: body.slice(at, at + bytes) })
at += bytes
}
return at === body.length ? { validator: head.validator, size: head.size, blocks } : undefined
}

/** A write the browser refused for lack of space, in either spelling. */
export function isQuotaError(error: unknown): boolean {
return (
Expand Down Expand Up @@ -342,6 +395,26 @@ export class ChunkStore {
})
}

/**
* The blocks the archive's index was read from over HTTP, as a worker kept them (#136):
* `undefined` when none were kept, or what was kept does not read back whole.
*/
async getIndexBlocks(): Promise<IndexBlocks | undefined> {
const cache = await this.cache()
const response = await cache.match(indexBlocksKey(this.pkgId))
if (!response) return undefined
try {
return decodeIndexBlocks(new Uint8Array(await response.arrayBuffer()))
} catch {
return undefined
}
}

async setIndexBlocks(kept: IndexBlocks): Promise<void> {
const body = encodeIndexBlocks(kept)
await this.write(indexBlocksKey(this.pkgId), () => new Response(body, { headers: { 'content-type': 'application/octet-stream' } }))
}

/* ---------------------------------------------------------------- writing and eviction */

/**
Expand Down
40 changes: 38 additions & 2 deletions packages/player/src/shared/source.ts
Original file line number Diff line number Diff line change
Expand Up @@ -203,16 +203,50 @@ export function forgetBlocks(): void {
blocks?.clear()
}

type RangeHttpDescriptor = Extract<SourceDescriptor, { type: 'range-http' }>

/** What names an archive's bytes in the block cache: the package id's ingredients, and the size. */
function blockKeyOf(descriptor: RangeHttpDescriptor, size: number): string {
return `${descriptor.url}\u0000${descriptor.validator ?? ''}\u0000${size}`
}

/** A block of an archive, by its place: block `index` starts at `index * BLOCK_SIZE`. */
export interface KeptBlock {
index: number
bytes: Uint8Array
}

/**
* The blocks `handle`'s small reads went through, held in this worker's cache, for keeping with
* the package (#136): what the index and a load's reads before the boot needed. Only a handle over
* HTTP has any.
*/
export function blocksReadBy(handle: SourceHandle): KeptBlock[] {
return handle instanceof RangeHttpHandle ? handle.blocksRead() : []
}

/** Puts back blocks an earlier worker read of the archive at `descriptor`, `size` bytes long. */
export function seedBlocks(descriptor: RangeHttpDescriptor, size: number, kept: Iterable<KeptBlock>): void {
blockCache().seed(blockKeyOf(descriptor, size), size, kept)
}

class RangeHttpHandle implements SourceHandle {
received = 0
/** What names these bytes in the block cache: the package id's ingredients, and the size. */
private readonly blockKey: string
/** The blocks this handle's small reads went through, fetched or found held. */
private readonly used = new Set<number>()

constructor(
readonly descriptor: Extract<SourceDescriptor, { type: 'range-http' }>,
readonly descriptor: RangeHttpDescriptor,
readonly size: number
) {
this.blockKey = `${descriptor.url}\u0000${descriptor.validator ?? ''}\u0000${size}`
this.blockKey = blockKeyOf(descriptor, size)
}

/** The blocks this handle's small reads went through that the cache still holds, in archive order. */
blocksRead(): KeptBlock[] {
return blockCache().blocksOf(this.blockKey, [...this.used].sort((a, b) => a - b))
}

/** Counts a body's bytes as they pass, without holding any of them. */
Expand Down Expand Up @@ -268,6 +302,8 @@ class RangeHttpHandle implements SourceHandle {
*/
async read(range: ByteRange): Promise<Uint8Array> {
if (range.end - range.start + 1 > BLOCK_CACHE_MAX_READ) return this.fetchBytes(range)
const last = Math.floor(Math.min(range.end, this.size - 1) / BLOCK_SIZE)
for (let index = Math.floor(range.start / BLOCK_SIZE); index <= last; index += 1) this.used.add(index)
return blockCache().read(this.blockKey, this.size, range, (missing) => this.fetchBytes(missing))
}

Expand Down
61 changes: 60 additions & 1 deletion packages/player/src/sw/mount.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ import {
type WorkerReply
} from '../shared/protocol.js'
import { contentRange, parseRange, type ByteRange } from '../shared/range.js'
import { openSource } from '../shared/source.js'
import { blocksReadBy, openSource, seedBlocks, type SourceHandle } from '../shared/source.js'
import * as db from '../shared/idb.js'
import { dependenciesIn } from '../shared/content-libraries.js'
import { libraryFolderNames } from '../shared/library-folders.js'
Expand Down Expand Up @@ -176,16 +176,71 @@ class VirtualServer {
* archive without another attempt to cache them.
*/
private storageFullUntil = 0
/**
* The blocks kept with each package, or put back from it, in this worker, by their indices: an
* index that read none beyond them writes nothing.
*/
private readonly keptIndexBlocks = new Map<string, ReadonlySet<number>>()
/**
* Readers whose frame has booted. What one reads after that is the runtime's, not the index's:
* a second load in a worker still running reuses the reader, and keeps nothing more.
*/
private readonly booted = new WeakSet<PackageReader>()

constructor(
private readonly worker: ServiceWorkerGlobalScope,
private readonly routes: Routes
) {
installEvictionPolicy((pkgId) => {
for (const key of this.readers.keys()) if (key.startsWith(pkgId)) this.readers.delete(key)
this.keptIndexBlocks.delete(pkgId)
})
}

/**
* Keeps the blocks this reader's index was read from with the package (#136). The block cache
* dies with the worker, and Chromium stops an idle one after about thirty seconds, so a reload
* read the tail, `h5p.json` and `content.json` again before the first answer. Only for an
* archive over HTTP whose host gave a validator: without one, an archive republished at the same
* URL keeps its package id, and old blocks would send zip.js to the old offsets. The blocks are
* whatever this reader's small reads went through before its frame booted, the index and what
* the load read for the plan and the check; the player names no file. Written again only when a
* load read a block beyond those kept. A copy that cannot be written is no copy.
*/
private async keepIndexBlocks(reader: PackageReader): Promise<void> {
const { handle } = reader
const { descriptor } = handle
if (descriptor.type !== 'range-http' || !descriptor.validator || this.booted.has(reader)) return
const blocks = blocksReadBy(handle)
const kept = this.keptIndexBlocks.get(reader.pkgId)
if (blocks.length === 0 || (kept && blocks.every(({ index }) => kept.has(index)))) return
try {
await new ChunkStore(reader.pkgId).setIndexBlocks({ validator: descriptor.validator, size: handle.size, blocks })
this.keptIndexBlocks.set(reader.pkgId, new Set(blocks.map(({ index }) => index)))
} catch {
// Read from the network next time, as before.
}
}

/**
* Puts back the blocks an earlier worker kept for this archive, when the validator and the size
* they were read under still match the ones this load was given: zip.js then reads the index
* from memory, as a reader built again after `attach-libraries` does. A copy that is missing or
* cannot be read means a read from the network, as before; it is never the authority.
*/
private async seedIndexBlocks(pkgId: string, handle: SourceHandle): Promise<void> {
const { descriptor } = handle
if (descriptor.type !== 'range-http' || !descriptor.validator) return
try {
const kept = await new ChunkStore(pkgId).getIndexBlocks()
if (!kept || kept.validator !== descriptor.validator || kept.size !== handle.size) return
seedBlocks(descriptor, handle.size, kept.blocks)
this.keptIndexBlocks.set(pkgId, new Set(kept.blocks.map(({ index }) => index)))
} catch {
// The network answers.
}
}

/* ---------------------------------------------------------------- control channel */

async handleMessage(event: ExtendableMessageEvent): Promise<void> {
Expand Down Expand Up @@ -248,6 +303,8 @@ class VirtualServer {
mainLibrary: typeof reader.manifest.mainLibrary === 'string' ? reader.manifest.mainLibrary : undefined,
...(downgraded.length > 0 ? { downgraded } : {})
})
// After the reply, so the load does not wait on it.
if (!reader.partial) await this.keepIndexBlocks(reader)
return
}

Expand Down Expand Up @@ -415,6 +472,7 @@ class VirtualServer {
// `let`: a wait on a partial reader hands back the reader to go on with, which is a new one
// once the archive is whole, as in `serveEntry`.
let reader = await this.refresh(load, await this.reader(load))
this.booted.add(reader)
const manifest = reader.hasFallbacks ? await reader.mergedManifest() : reader.manifest
// A download that stops moving is a stall, answered with a retry as an entry's is, and not a
// library the package lacks: a lookup that found one ends the walk's waiting.
Expand Down Expand Up @@ -841,6 +899,7 @@ class VirtualServer {
}

const handle = await openSource(pkgId, record.source, file)
await this.seedIndexBlocks(pkgId, handle)

// Not held to its libraries here: an `index` does that, after any plan from the pack, and a
// bundle or a part registered to supply libraries to something else never is.
Expand Down
Loading
Loading