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
27 changes: 22 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1128,9 +1128,13 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess
`unversioned-pack.h5p` with `pack.test.ts` pins it; the walk tries each library both ways.
**Across versions**: a record that names `mainJs` came from an element paired with the runtime
up to 0.2, and the worker still writes that document — the loader, the upgrade list in the
config — so an element from before keeps playing against an updated worker; a later boot script
given a document without the `boot` URL, a worker from before, says to update the player and
`h5p-sw.js` together. An element of this player with a runtime up to 0.2 through `assets-base`
config — so an element from before keeps playing against an updated worker. It names the
`boot` route in that document too (#49): a page from before an upgrade, still open, registers
its loads naming the loader, and on a host that serves the runtime at one path — the demo, an
embed site, any copy of `dist/` — the boot script at that path is 1.0's by then, which boots
from the route and leaves the loader's 404 alone; without the route it stopped every such load.
A later boot script given a document without the `boot` URL, a worker from before, says to
update the player and `h5p-sw.js` together. An element of this player with a runtime up to 0.2 through `assets-base`
cannot work and does not try: the peer range says which runtime it plays with.
- **A 404 from the virtual server is load-bearing.** A library's `library.json` is looked for
under the versioned folder name and then the bare one, and the first 404 is what sends the
Expand Down Expand Up @@ -1274,6 +1278,15 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess
the control channel, and on a difference calls `registration.update()` and waits for the new
worker, all bounded by `WORKER_UPDATE_TIMEOUT_MS`; offline or past it, the load goes ahead with
the worker it has. Same bytes after the update is a host's stale `h5p-sw.js`, still a warning.
Going ahead is right within a major, whose older worker serves the element, and not across
one, which it cannot: from 0.10 to 1.0, measured with the published files under the same URLs
and `h5p-sw.js` answered after four seconds, the load went ahead with the 0.10 worker, the new
one took over halfway through, and it stayed in `indexing` (#49). So for a worker of another
major the wait is `WORKER_MAJOR_UPDATE_TIMEOUT_MS`, thirty seconds; the new worker's activation,
which deletes the old major's caches, took about a second of it with four caches or 124. One
setup at a time (`workerSetup`): the element keeps its routes before it asks the version, and a
load that began during the wait — a visitor choosing another package while the first still
loads — took them as kept and went ahead with the old worker; found reviewing the fix.
`activated()` waits for the newest worker — installing, then waiting, then active — since a
changed script URL (a bundler's hash) installs a new worker beside the old active one; that
wait is bounded by the same timeout whenever an activated worker can serve, because a host's
Expand Down Expand Up @@ -2361,8 +2374,12 @@ SPA-fallback trap described above cannot happen there.
longest prefix of the page's — so a page names no current link. The footers stay in the pages:
each lists its own links. The per-page metadata — title, description, Open Graph and Twitter
tags, each written two or three times — is the obvious next candidate and has not been done.
- **Caching.** Hashed files under `/assets/` are immutable; `h5p-sw.js` is `no-cache`;
`frame-assets/` and `fixtures/` revalidate hourly. Fixtures also carry permissive CORS with
- **Caching.** Hashed files under `/assets/` are immutable; `h5p-sw.js` and `frame-assets/` are
`no-cache`; `fixtures/` revalidate hourly. `frame-assets/` was hourly, with a day of
`stale-while-revalidate`, until #49: its file names stay the same from one runtime to the next,
and after the 1.0 deploy a returning browser ran runtime 0.2.5's boot script, kept from before,
under the new worker — "Cannot read properties of undefined (reading 'H5P')" on every play for
that hour. The embed command's headers changed the same way, for `/libraries/` as well. Fixtures also carry permissive CORS with
`Range` allowed and `Content-Range` exposed, so another player instance can be pointed at them.
- **The demo plays real content; the fixtures never ship.** The player's `public/fixtures/` is the test
suite's stub library saying "Served from the archive, never extracted to disk", which is right
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,9 @@ cp -r node_modules/@missing-elements/h5p-libraries/parts public/h5p-libraries
cp node_modules/@missing-elements/h5p-libraries/libraries.txt public/h5p-libraries/
```

To upgrade, delete the folders and copy them again.
To upgrade, delete the folders and copy them again. Serve them with `Cache-Control: no-cache`, or
with no caching header at all: the file names stay the same from one version to the next, so a
copy a browser kept from before an upgrade would run against the new Service Worker.

Or load the element and the runtime from jsDelivr, and copy only the Service Worker:

Expand Down
3 changes: 2 additions & 1 deletion docs/single-worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ Routes then live under `<hostScope>h5p/`, and the element uses them instead of r
## Upgrading

- Cache names include the package major version; minor and patch updates reuse cached packages, and a worker update never invalidates them. A major starts the cache afresh, and each package is downloaded once more; saved state is kept.
- After an upgrade, the element updates its own worker before the first load (waiting up to three seconds).
- After an upgrade, the element updates its own worker before the first load, waiting up to three seconds, or up to thirty when the worker is from another major version, which cannot serve it.
- Serve the runtime's folder and a copy of the library pack revalidated (`Cache-Control: no-cache`), or under a path with the version in it, as jsDelivr's addresses are. Their file names stay the same from one version to the next, and a copy the browser kept from before an upgrade runs against the new worker: from 0.10 to 1.0, kept for an hour, it failed every play for that hour.
- Installed without a build step: re-download `h5p-sw.js` after upgrading. The element logs a warning when versions differ.
- Single-worker hosts update their own worker; offer a reload on `controllerchange`, as the demo's app does.

Expand Down
3 changes: 2 additions & 1 deletion packages/embed/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,8 @@ The headers themselves, for a host not listed:
|---|---|
| every path | `Content-Security-Policy` (the policy the command prints, with `frame-ancestors` from `--ancestors`), `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin` |
| `/h5p-sw.js` | `Cache-Control: no-cache`, so an update reaches learners on their next visit |
| `/frame-assets/*`, `/resizer.js`, `/libraries/*` | `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` |
| `/frame-assets/*`, `/libraries/*` | `Cache-Control: no-cache`: the runtime and the library pack keep their file names between versions, so a copy from before an update must not be used after it |
| `/resizer.js` | `Cache-Control: public, max-age=3600, stale-while-revalidate=86400` |

To update, run the command again with `--force` and redeploy.

Expand Down
11 changes: 9 additions & 2 deletions packages/embed/lib/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,13 @@ export function contentSecurityPolicy({ packages = null, ancestors = null, meta
/** Header rules, one set for every host format: the policy everywhere, and the caching that matters. */
function headerRules(csp) {
const revalidate = 'public, max-age=3600, stale-while-revalidate=86400'
// Asked again on every load, a 304 when nothing changed. The runtime's files keep their names
// from one version to the next, and the worker's version decides which it needs: kept for an
// hour, the runtime of the version before ran under the new worker after an update, and every
// play failed until the hour was out (0.10 to 1.0, measured, #49). The pack the same way, for
// whatever reads it with the browser's defaults: the element itself asks for its index
// revalidated and for its parts past the HTTP cache, so for it the header changes nothing.
const current = 'no-cache'
return [
{
path: '/*',
Expand All @@ -148,9 +155,9 @@ function headerRules(csp) {
},
// The worker is checked on every load, so an update reaches learners on their next visit.
{ path: '/h5p-sw.js', headers: { 'Cache-Control': 'no-cache' } },
{ path: '/frame-assets/*', headers: { 'Cache-Control': revalidate } },
{ path: '/frame-assets/*', headers: { 'Cache-Control': current } },
{ path: '/resizer.js', headers: { 'Cache-Control': revalidate } },
{ path: '/libraries/*', headers: { 'Cache-Control': revalidate } }
{ path: '/libraries/*', headers: { 'Cache-Control': current } }
]
}

Expand Down
6 changes: 5 additions & 1 deletion packages/embed/tests/build.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,13 +103,17 @@ describe('the site', () => {
const vercel = JSON.parse(await readFile(join(out, 'vercel.json'), 'utf8'))
expect(vercel.headers[0]).toEqual({ source: '/(.*)', headers: expect.arrayContaining([{ key: 'Content-Security-Policy', value: site.csp }]) })
expect(vercel.headers).toContainEqual({ source: '/h5p-sw.js', headers: [{ key: 'Cache-Control', value: 'no-cache' }] })
// The runtime and the pack keep their names between versions, so neither is kept unasked (#49).
for (const folder of ['/frame-assets/', '/libraries/']) {
expect(vercel.headers.find((rule: { source: string }) => rule.source.startsWith(folder)).headers).toEqual([{ key: 'Cache-Control', value: 'no-cache' }])
}
expect(await readFile(join(out, 'config.js'), 'utf8')).toContain('{"libraries":true,"packages":["https://cdn.example.org"],"defaultLibraries":null}')

// The three server formats say the same as the two host files, each in its own syntax.
const caddy = await readFile(join(out, 'Caddyfile'), 'utf8')
expect(caddy).toContain(`\theader Content-Security-Policy "${site.csp}"`)
expect(caddy).toContain('\theader /h5p-sw.js Cache-Control "no-cache"')
expect(caddy).toContain('\theader /frame-assets/* Cache-Control "public, max-age=3600')
expect(caddy).toContain('\theader /frame-assets/* Cache-Control "no-cache"')
const nginx = await readFile(join(out, 'nginx.conf'), 'utf8')
expect(nginx).toContain(`add_header Content-Security-Policy "${site.csp}" always;`)
expect(nginx).toContain('location = /h5p-sw.js {')
Expand Down
45 changes: 35 additions & 10 deletions packages/player/src/h5p-offline-player.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,13 @@ import { packLibrariesIn } from './shared/pack'
import {
CONTROL_TIMEOUT_MS,
LIBRARY_PACK_BASE,
MAJOR_VERSION,
PACK_INDEX_CACHE,
SAVE_INTERVAL_S,
SILENT_ANSWER_TIMEOUT_MS,
VERSION,
WARM_ENTRY,
WORKER_MAJOR_UPDATE_TIMEOUT_MS,
WORKER_UPDATE_TIMEOUT_MS
} from './shared/constants'
import {
Expand Down Expand Up @@ -306,6 +308,8 @@ export class H5PPlayerElement extends HTMLElement {
private jobs: JobsWorkerHandle | null = null
private routes: Routes | null = null
private registration: ServiceWorkerRegistration | null = null
/** The worker being found or brought up to date, while it is: every load meanwhile waits on it. */
private workerSetup: Promise<Routes> | null = null
private currentFile: File | null = null
private currentSource: SourceDescriptor | null = null
private load: AbortController | null = null
Expand Down Expand Up @@ -1366,9 +1370,22 @@ export class H5PPlayerElement extends HTMLElement {
/**
* Finds the routes, registering our own worker unless a host has already mounted the handlers
* into theirs. Registration uses an explicit `h5p/` sub-scope, so a host worker living in the
* same directory — or at `/`, for a root-placed `h5p-sw.js` — is never displaced.
* same directory — or at `/`, for a root-placed `h5p-sw.js` — is never displaced. One setup at
* a time: a load that starts while an earlier one is still bringing the worker up to the
* element's version — up to thirty seconds across a major, on a slow host — waits on that setup.
* The routes are kept before the version is asked, and a load that began meanwhile took them as
* kept and went ahead with the worker of the major before (#49, found in review).
*/
private async ensureWorker(): Promise<Routes> {
private ensureWorker(): Promise<Routes> {
if (!this.workerSetup) {
this.workerSetup = this.setUpWorker().finally(() => {
this.workerSetup = null
})
}
return this.workerSetup
}

private async setUpWorker(): Promise<Routes> {
if (this.routes && this.registration) {
if (await stillRegistered(this.registration)) return this.routes

Expand Down Expand Up @@ -1450,13 +1467,16 @@ export class H5PPlayerElement extends HTMLElement {
* into the boot, under a frame document the old version wrote. So a version that differs asks
* for the update itself and waits for it, bounded: offline, or on a slow host, the load goes
* ahead with the worker it has. A script that is still old after the update is the host's copy,
* which only the host can replace; that stays a warning.
* which only the host can replace; that stays a warning. A worker of another major cannot serve
* this element at all, so for one the load waits as long as the update takes, within
* `WORKER_MAJOR_UPDATE_TIMEOUT_MS`.
*/
private async ensureCurrentWorker(registration: ServiceWorkerRegistration): Promise<void> {
const before = await this.workerVersion()
if (before === null || before === VERSION) return

await withTimeout(updateWorker(registration), WORKER_UPDATE_TIMEOUT_MS, undefined)
const wait = majorOf(before) === MAJOR_VERSION ? WORKER_UPDATE_TIMEOUT_MS : WORKER_MAJOR_UPDATE_TIMEOUT_MS
await withTimeout(updateWorker(registration, wait), wait, undefined)
// Asked again rather than trusting what the update reported: with `skipWaiting`, a new
// worker can be active before `update()` has resolved, leaving nothing in `installing`.
warnIfDifferent((await this.workerVersion()) ?? before)
Expand Down Expand Up @@ -2052,7 +2072,7 @@ async function stillRegistered(registration: ServiceWorkerRegistration): Promise
* wait with it. A newest worker that turns redundant falls back to the one running for the same
* reason.
*/
function activated(registration: ServiceWorkerRegistration): Promise<ServiceWorker> {
function activated(registration: ServiceWorkerRegistration, wait = WORKER_UPDATE_TIMEOUT_MS): Promise<ServiceWorker> {
const running = registration.active?.state === 'activated' ? registration.active : null
const worker = registration.installing ?? registration.waiting ?? registration.active
if (!worker) return Promise.reject(new PlayerError('no-worker', 'The registration has no worker'))
Expand All @@ -2071,18 +2091,18 @@ function activated(registration: ServiceWorkerRegistration): Promise<ServiceWork
}
worker.addEventListener('statechange', onChange)
})
return running && running !== worker ? withTimeout(settled, WORKER_UPDATE_TIMEOUT_MS, running) : settled
return running && running !== worker ? withTimeout(settled, wait, running) : settled
}

/**
* Fetches the registration's script and, when its bytes changed, waits for the new worker to
* take over (`mountH5P` skips waiting). Settles without a word when nothing new was installed:
* the network failed, or the script is the same bytes as before.
* take over (`mountH5P` skips waiting), for up to `wait`. Settles without a word when nothing new
* was installed: the network failed, or the script is the same bytes as before.
*/
async function updateWorker(registration: ServiceWorkerRegistration): Promise<void> {
async function updateWorker(registration: ServiceWorkerRegistration, wait: number): Promise<void> {
try {
await registration.update()
if (registration.installing || registration.waiting) await activated(registration)
if (registration.installing || registration.waiting) await activated(registration, wait)
} catch {
// Offline, a refused script, a worker that failed to install: the running one serves.
}
Expand All @@ -2096,6 +2116,11 @@ function withTimeout<T>(promise: Promise<T>, ms: number, fallback: T): Promise<T
return Promise.race([promise, late]).finally(() => clearTimeout(timer))
}

/** A version's major, `0` of `0.10.0`; `NaN` for what is not a version, which matches no major. */
function majorOf(version: string): number {
return Number(/^(\d+)\./.exec(version)?.[1] ?? NaN)
}

function warnIfDifferent(workerVersion: string | undefined): void {
if (workerVersion && workerVersion !== VERSION) {
console.warn(
Expand Down
9 changes: 9 additions & 0 deletions packages/player/src/shared/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,15 @@ export const SAVE_INTERVAL_S = 10
*/
export const WORKER_UPDATE_TIMEOUT_MS = 3_000

/**
* The same, when the running worker is of another major. Within a major an older worker serves the
* element (docs/compatibility.md), so the load need not wait long; across one it cannot, and going
* ahead failed the load: from 0.10 to 1.0, measured with the script answered after four seconds,
* the load went ahead with the old worker, the new one took over halfway through, and it never
* left `indexing`. The new worker's activation deletes the old major's caches, about a second more.
*/
export const WORKER_MAJOR_UPDATE_TIMEOUT_MS = 30_000

/** How long the element waits for the Service Worker to answer on the control channel. */
export const CONTROL_TIMEOUT_MS = 30_000
/**
Expand Down
7 changes: 5 additions & 2 deletions packages/player/src/sw/frame-document.ts
Original file line number Diff line number Diff line change
Expand Up @@ -373,7 +373,10 @@ export function buildFrameDocument(options: FrameDocumentOptions): string {

// A runtime up to 0.2 boots through h5p-standalone's `main.bundle.js`, which the document loads
// ahead of the boot script, and takes the upgrade list from here; a later one has no such file
// and asks the `boot` route for what to load.
// and asks the `boot` route for what to load. The route is named in every document, the older
// kind too: a page from before an upgrade, still open, registers its loads naming the loader,
// and on a host that serves the runtime at one path the boot script there is the new one by now,
// which boots from the route and leaves the loader's 404 alone. A 0.2 boot script ignores it.
const loader = assets.mainJs

// A JSON block, not a script: it is data, so it needs no nonce, and the boot script proper —
Expand All @@ -382,7 +385,7 @@ export function buildFrameDocument(options: FrameDocumentOptions): string {
const bootConfig = JSON.stringify({
pkgId,
h5pJsonPath: virtualRoot,
boot: loader ? undefined : options.bootUrl,
boot: options.bootUrl,
frameJs: assets.frameJs,
frameCss: assets.frameCss,
title: options.title,
Expand Down
17 changes: 17 additions & 0 deletions packages/player/tests/browser/runtime.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,23 @@ describe('the runtime property', () => {
expect(frameDocument(player).querySelector('style')?.textContent).toContain(runtime.fonts[0].url)
})

it('plays a load that names the loader of runtime 0.2, on a host that has since upgraded', async () => {
// A page from before an upgrade, still open: its element registers its loads naming
// h5p-standalone's `main.bundle.js`, which the upgraded host no longer has, and the boot script
// at the URL it names is this runtime's by now. The worker writes the old kind of document for
// such a load, the route in it too, and this boot script boots from the route; without the
// route it stopped with "older than this runtime" (#49).
const player = createPlayer()
player.runtime = { ...runtime, mainJs: `${base}main.bundle.js` } as typeof runtime
const settled = waitForSettled(player)
player.setAttribute('src', FIXTURES.basic)

const result = await settled
if (!result.ok) expect.fail(`${result.detail.code} — ${result.detail.message}`)
const scripts = [...frameDocument(player).querySelectorAll('script[src]')].map((script) => script.getAttribute('src'))
expect(scripts).toContain(`${base}main.bundle.js`)
})

it('refuses a value missing one of the three files, since that frame would never boot', () => {
const player = createPlayer()
player.runtime = { frameJs: 'b', frameCss: 'c' } as never
Expand Down
Loading
Loading