From f2b33bfbe5d15d8159ca1e2a703c8dbd5aa40625 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Thu, 29 Oct 2026 13:16:49 +0200 Subject: [PATCH 1/2] feat: play content made for a newer library minor than any source has, on the newest older one (#85) h5p.com gets a library's new minor weeks before the hub serves it, and the pack follows the hub, so content made there can name a version no source has. Such a package was refused, or, when a question inside it was the newer one, booted without that question's library and died with "Cannot read properties of undefined (reading 'on')". The element now tries every source for the version named, as before, and only then switches the load to the newest older minor of the same major, never across one: `downgrade-libraries`, on by default, `off` to refuse as before. The switch is kept with the load's settings, and a reader of an archive still arriving ignores it. The deep index's walk also starts from the sub-content `content.json` names, wherever a source has that library's major, so a newer question is missing there and gets the older minor; a library no source has at its major plays as before. `libraryBundle.downgraded` and a console warning name each library played older. The verifier warns and reports them (`--no-downgrade-libraries` refuses), the embed page passes `&downgrade-libraries=off` through, and the demo's player page has an Older if needed switch. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 58 ++++++- apps/demo/demo/player-page.js | 49 ++++-- apps/demo/index.html | 10 +- docs/api.md | 3 +- docs/compatibility.md | 6 +- docs/libraries.md | 20 +++ docs/troubleshooting.md | 1 + docs/verify.md | 4 +- packages/embed/README.md | 1 + packages/embed/site/embed.js | 8 +- packages/embed/tests/site.test.ts | 19 ++- packages/player/scripts/build-fixtures.mjs | 8 +- packages/player/scripts/lib/fixture-names.mjs | 2 + packages/player/src/h5p-offline-player.ts | 64 ++++++-- packages/player/src/shared/protocol.ts | 37 ++++- packages/player/src/sw/mount.ts | 52 +++--- packages/player/src/sw/pack-plan.ts | 27 +++- packages/player/src/sw/package-reader.ts | 152 ++++++++++++++---- packages/player/tests/browser/pack.test.ts | 48 ++++++ .../player/tests/browser/untrusted.test.ts | 15 +- packages/player/tests/browser/utils.ts | 4 + .../tests/unit/library-versions.test.ts | 16 ++ .../player/tests/unit/merged-manifest.test.ts | 37 +++++ packages/player/tests/unit/pack-plan.test.ts | 37 +++++ packages/verify/README.md | 4 +- packages/verify/bin/h5p-verify.mjs | 12 +- packages/verify/lib/page.html | 1 + packages/verify/lib/preview.html | 2 + packages/verify/lib/preview.mjs | 3 + packages/verify/lib/verify.mjs | 13 +- packages/verify/tests/verify.test.ts | 11 +- 31 files changed, 628 insertions(+), 96 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 59b36167..ffab1fb0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -804,7 +804,9 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess Embed adds a separate origin on top. `tests/browser/untrusted.test.ts` plays `untrusted.h5p`, whose own copy of the fixture content type marks the frame, against the bundle and then trusted, checks each content type and the - header, injects scripts, reads the policy, and refuses `untrusted-newer.h5p` with `carried`. It + header, injects scripts, reads the policy, plays `untrusted-newer.h5p` on the bundle's older + minor (see *Content written for a newer minor than any source has*) and, with + `downgrade-libraries="off"`, refuses it with `carried`. It plays `untrusted-markup.h5p`, a form, a script, a handler, a `javascript:` link and a field the semantics do not name, at the top and in sub-content, through the fixture content type's `.html()`, untrusted and trusted, and refuses it against `libraries-without-semantics.h5p`; the @@ -1206,6 +1208,53 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess the demo's bundled page), or the element's `pack` on a site built with `--no-libraries` where jsDelivr is allowed. A source that fails outright is passed over while another remains; only the last one's failure is the load's. +- **Content written for a newer minor than any source has plays at the newest older one** + (2026-10-29, #85). H5P Group's October release put library minors on h5p.com weeks before the + hub served them, and the pack follows the hub, so content made there can name a version nothing + here has. Measured that day with the demo's quiz relabelled: a content-only export was refused + naming its main library; one whose sub-content was newer booted and died with "Cannot read + properties of undefined (reading 'on')", nothing drawn and no library named, since nothing checks + sub-content before the boot; an untrusted export carrying its own newer copy was refused with + `carried`. The owner's rule: what can play, plays. So `resolveLibraryFolder` takes `downgrade`, + and with it a dependency nothing satisfies is served from the newest older minor of the same + major, never across a major. Four choices in it. **Strict first**: `index()` in the element tries + every source for the version named, as before, and only when the last leaves something missing + does it switch the load, with an `attach-libraries` carrying `downgrade: true`, and index again, + offering the pack with `downgrade` so that `planPack` supplies its older part (unless the package + carries, or a source provides, one at least as new). So a later source with the version named + wins over an earlier one with an older version, which `pack.test.ts` holds with a bundle at 1.0 + before the pack at 1.2. **Kept with the load**: the switch is `LoadSettings.downgrade`, so a + worker started again serves the folders the frame booted with; the next load starts strict. + **Never while arriving**: a partial reader ignores it (`downgrades`), since a package on a host + without `Range` may still be bringing its own copy, and a frame booted early on the older one + would keep it. **From the parameters too**: the deep index's walk (`checkDependencies`) starts + from the sub-content `content.json` names as well as from the manifest, wherever a source has + that library's major: an attached archive, or the pack on offer. A stripped export's `h5p.json` + names its main library alone and the merged manifest drops what nothing answers for, so the + first cut, which walked the manifest only, never saw a question newer than the pack. It played + the main library and left the question's library unloaded: the demo's formulas quiz with + MultiChoice 1.17 still died as above, which the player page's check by hand found. Missing there + now, it goes to the next source and then to the older minor; `newer-child.h5p` in + `pack.test.ts` is that shape. A library no source has at its major still plays as before, + dropped from the manifest, its sub-content removed by the content check when untrusted, so an + old export's retired question type is not refused for it. The walk names each dependency + served from a versioned folder below the minor asked; the element puts them on + `libraryBundle.downgraded` and + warns in the console, the verifier makes each a warning and `report.downgraded` + (`--no-downgrade-libraries` refuses instead), the player page shows it with an Older if needed + switch, and the embed page passes `&downgrade-libraries=off` through. One thing follows for the + pages that ask before a package's own code runs: untrusted, a package carrying a newer minor than + the pack's now plays on the pack's, so they ask only for a library no source has at its major, or + with the switch off. The embed's `site.test.ts` plays its Question Set 1.99 package both ways. + The runtime needed nothing: the content upgrade runs steps only upward (`isUpgrade`), so the + parameters play as written, the main library is named at the version served, and a + sub-content's string keeps the version it names, which the worker answers from the older folder. + What it costs, counted over the pack the same day: 119 of the 469 minor bumps in its libraries' + history came with an upgrade step, a change of shape the older code does not read; the others + only add. Not done: the SCORM writer stays strict, refusing such a package when the zip is + written; and a sub-content library no source has at any minor of its major still fails at + runtime, unnamed, when played trusted. `downgrade-libraries="off"` refuses as before, and now + names a newer question's library too, where it booted without it. - **The element says what it is playing: `source`, `metadata`, `libraryBundle`.** Added on 2026-10-09 for the package check an embedding site shows under its preview: the probe's classification and size (`currentSource`, exposed as a copy), the manifest's metadata plus `mainLibrary` (new on @@ -2043,8 +2092,9 @@ ours runs a server. for a part the zip lacks. What neither the package nor the pack supplies is refused when the zip is written, by the walk the player makes (`servingFolder` mirrors `reachableFolder`, the walk `missingDependencies`), run over the package without the folders a part replaces and over the - parts. The walk starts from the sub-content the parameters name as well, which the player would - find missing only when the runtime reached it. So a gap shows up when the teacher writes the zip, + parts. The walk starts from the sub-content the parameters name as well, which the player found + missing only when the runtime reached it until #85, and since then finds at index only where a + source has the library's major. So a gap shows up when the teacher writes the zip, not when a learner opens it. Measured: the demo's formulas quiz, a stripped export, took 11 parts, 4 MB, 2.8 MB of it MathDisplay; its full exports took none. In Moodle 4.5 the formulas zip reached `ready`, fetched exactly those 11 parts and the index, and typeset its LaTeX. @@ -3094,6 +3144,8 @@ deliberate additions to it, not drift: at all (`hub` meant the pack until it went before 1.0). Since 0.10 the pack is split, a package downloads only the parts it needs, and the pack's newer versions play in place of the older ones a package carries: the design plays what a package carries. +- Content written for a newer minor than any source has plays at the newest older one, once every + source has been tried. The design refuses what is not reachable. - Content written for an older minor than the one served is upgraded in the frame with the libraries' own steps. The design serves what a package carries; a bundle that serves newer minors needs the step the platforms take when they install one. diff --git a/apps/demo/demo/player-page.js b/apps/demo/demo/player-page.js index 2932b49a..6d295c5d 100644 --- a/apps/demo/demo/player-page.js +++ b/apps/demo/demo/player-page.js @@ -18,6 +18,7 @@ const bar = document.querySelector('#progress') const message = document.querySelector('#message') const log = document.querySelector('#log') const refreshToggle = document.querySelector('#refresh') +const downgradeToggle = document.querySelector('#downgrade') const confirmBox = document.querySelector('#confirm-src') const modeNote = document.querySelector('#mode-note') const modeTag = document.querySelector('#mode-tag') @@ -119,15 +120,29 @@ player.addEventListener('progress', (event) => { player.addEventListener('ready', () => { bar.hidden = true const refreshed = player.libraryBundle?.refreshed ?? [] - modeTag.textContent = player.untrusted - ? "Untrusted · libraries from this site's pack · content checked" - : refreshed.length > 0 - ? `Trusted · ${refreshed.length === 1 ? 'one library' : `${refreshed.length} libraries`} at the pack's newer version` - : player.libraryBundle - ? "Trusted · its own libraries, the rest from this site's pack" - : 'Trusted · its own libraries' + const downgraded = player.libraryBundle?.downgraded ?? [] + const libraries = (count) => (count === 1 ? 'one library' : `${count} libraries`) + modeTag.textContent = + (player.untrusted + ? "Untrusted · libraries from this site's pack · content checked" + : refreshed.length > 0 + ? `Trusted · ${libraries(refreshed.length)} at the pack's newer version` + : player.libraryBundle + ? "Trusted · its own libraries, the rest from this site's pack" + : 'Trusted · its own libraries') + (downgraded.length > 0 ? ` · ${libraries(downgraded.length)} older than the content` : '') write(`mode ${modeTag.textContent}`) for (const { library, from, to } of refreshed) write(`refreshed ${library} ${from} → ${to}`) + for (const { library, from, to } of downgraded) write(`older ${library} ${to}, made for ${from}`) + // Made for a version this site's pack has not got yet, and played at its older one: most of the + // time all of it works, but what the newer version added is not there, so the visitor is told. + if (downgraded.length > 0) { + show( + "Made for newer library versions than this site's pack has, so it plays at older ones: " + + `${downgraded.map(({ library, from, to }) => `${library} ${from} at ${to}`).join(', ')}. ` + + 'What the newer versions added is left out. Turn off Older if needed to refuse such packages instead.', + 'warning' + ) + } // The build every statement will name in `context.revision`. On a host without Range the frame // can boot before the index that yields it, and the statements wait for it instead. if (player.revision) write(`revision ${player.revision}`) @@ -241,10 +256,15 @@ const REFRESH_NOTES = { on: ' Where the pack has a newer version of a library the package carries, that version plays.', off: ' The libraries the package carries play as exported.' } +const DOWNGRADE_NOTES = { + on: ' Content made for a newer version than anything here has plays at the newest older one, without what the newer version added.', + off: ' Content made for a newer version than anything here has is refused.' +} const playsUntrusted = () => form.elements.mode.value === 'untrusted' const describeMode = () => { const mode = form.elements.mode.value - modeNote.textContent = NOTES[mode] + (mode === 'trusted' ? REFRESH_NOTES[refreshToggle.checked ? 'on' : 'off'] : '') + modeNote.textContent = + NOTES[mode] + (mode === 'trusted' ? REFRESH_NOTES[refreshToggle.checked ? 'on' : 'off'] : '') + DOWNGRADE_NOTES[downgradeToggle.checked ? 'on' : 'off'] // Untrusted, none of the package's own libraries play, so there is nothing to refresh. refreshToggle.disabled = mode === 'untrusted' } @@ -259,7 +279,12 @@ const applyMode = () => { player.untrusted = untrusted if (refreshToggle.checked) player.removeAttribute('refresh-libraries') else player.setAttribute('refresh-libraries', 'off') - return untrusted ? ' (untrusted: none of its own code runs)' : refreshToggle.checked ? '' : ' (libraries as exported)' + if (downgradeToggle.checked) player.removeAttribute('downgrade-libraries') + else player.setAttribute('downgrade-libraries', 'off') + return ( + (untrusted ? ' (untrusted: none of its own code runs)' : refreshToggle.checked ? '' : ' (libraries as exported)') + + (downgradeToggle.checked ? '' : ' (no older versions)') + ) } /** Plays a package at a URL, in the switch's mode. */ @@ -322,6 +347,12 @@ refreshToggle.addEventListener('change', () => { reload?.() }) +// And content made for a newer version than the pack has: played at its older one, or refused. +downgradeToggle.addEventListener('change', () => { + describeMode() + reload?.() +}) + // A sample marked `data-untrusted` plays as data against this site's bundle: a content-only // export, as h5p.com and h5p.org make them, the way a site plays a package it did not make. The // others play in whichever mode the switch is in. diff --git a/apps/demo/index.html b/apps/demo/index.html index 1f8e3270..e673630d 100644 --- a/apps/demo/index.html +++ b/apps/demo/index.html @@ -114,9 +114,10 @@

Self-hosted H5P in one web component

Choose file - +
@@ -125,6 +126,9 @@

Self-hosted H5P in one web component

+
+ +

The package's own scripts run on this site. What it lacks comes from this site's library pack.

diff --git a/docs/api.md b/docs/api.md index 5b99f43e..1f69e91c 100644 --- a/docs/api.md +++ b/docs/api.md @@ -18,6 +18,7 @@ meaning, and a new error `code` or `progress` phase can only be added. | `pack-base` | attribute | Where `pack` is: the folder of a copy of `@missing-elements/h5p-libraries`' `parts/` on your site. Default: jsDelivr, at the version this release pins | | `pack` | property | The `pack` export of `@missing-elements/h5p-libraries`, as a bundler emits it; wins over `pack-base`. Set before `src` | | `refresh-libraries` | attribute | `off` plays the libraries a package carries as exported, and `pack` only fills gaps. Default: the pack's newer versions play | +| `downgrade-libraries` | attribute | `off` refuses content made for a newer minor version of a library than any source has. Default: once every source has been tried for that version, the newest older minor of the same major plays it, reported in `libraryBundle.downgraded` and the console | | `untrusted` | attribute, property | Plays a package you did not make as data: its own library folders are ignored and the libraries come from `libraries` (default `pack`), `content/` serves only H5P's own file types, and the frame's script policy names exact paths. Its content is checked against each library's `semantics.json`, as the H5P CMS plugins check it. A package that needs its own copy of a library is refused, with `missingLibraries.carried` set | | `allow-origins` | attribute | Extra origins for the frame's CSP, space separated | | `frame`, `copyright`, `export`, `icon`, `embed` | attribute | Show the H5P action bar and its buttons. `export` needs `download-url` or a package URL, `embed` needs `embed-code` | @@ -37,7 +38,7 @@ meaning, and a new error `code` or `progress` phase can only be added. | `pkgId`, `revision` | read-only | The loaded package's id and build fingerprint | | `source` | read-only | `{ type: 'range-http' \| 'chunked' \| 'file', size, … }` | | `metadata` | read-only | `h5p.json`'s metadata plus `mainLibrary` | -| `libraryBundle` | read-only | `{ url, origin, fromCache, refreshed? }` for what supplied libraries: for the pack, `refreshed` lists the libraries the package carries that played at the pack's version, `{ library, from, to }` | +| `libraryBundle` | read-only | `{ url, origin, fromCache, refreshed?, downgraded? }` for what supplied libraries: for the pack, `refreshed` lists the libraries the package carries that played at the pack's version, `{ library, from, to }`; `downgraded` the libraries the content names at a newer minor than any source has, which played at an older one, `{ library, from, to }` with `from` the version named, such as `1.17`, and `to` the one played, such as `1.16.27` | | `scope` | read-only | The Service Worker scope | ## Methods diff --git a/docs/compatibility.md b/docs/compatibility.md index fb5595cd..481fc4a3 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -75,8 +75,10 @@ always plays a package against the same libraries. The pin moves in a minor rele patch: with `pack`, a library a package carries plays at the pack's newer version, so a new pack changes what packages that carry their libraries play, and their `revision`, and a learner's state saved against the build before starts over. Libraries move to newer minors, and content written -for an older minor is brought up by the libraries' own upgrade steps. A pack that drops a content -type or a library major the one before carried comes only with a player major. +for an older minor is brought up by the libraries' own upgrade steps. Content written for a newer +minor than any source has plays at the newest older one unless `downgrade-libraries="off"`, and +plays at the newer one once a pack has it. A pack that drops a content type or a library major the +one before carried comes only with a player major. What is covered of the pack itself: the `pack` export, `parts/` with its `index.json` and one `.h5p` per library, and `libraries.h5p`, the whole pack as one file. diff --git a/docs/libraries.md b/docs/libraries.md index 3b4c85fe..949d95eb 100644 --- a/docs/libraries.md +++ b/docs/libraries.md @@ -47,6 +47,26 @@ with ([Which build a learner completed](revision.md)), and a learner's state sav build before starts over, once, with H5P's own "content has changed" dialog. A pack release that changes none of a package's libraries changes nothing for it. +## Content newer than the pack + +h5p.com gets a library's new minor version before the H5P hub serves it, and the pack follows the +hub, so for a few weeks content made on h5p.com can name a version no source has. The player +then plays it at the newest older minor of the same major that a source has: Question Set 1.21 +for content made with 1.22, Multiple Choice 1.16 for a question in it made with 1.17. It does so +only after every source in `libraries` has been tried for the version named, so a later source +that has it wins over an earlier one with an older version, and never across a major. + +Most minor versions only add fields, which the older code ignores, so the content plays without +what the newer version added. Some move or rename fields: of the 469 minor bumps in the history of +the pack's libraries, 119 came with an upgrade step, which is how H5P marks such a change. There +the older code does not find what moved, and a part can be missing or drawn wrong. Played +`untrusted`, the content is still checked against the older version's fields. + +`libraryBundle.downgraded` and the `ready` event's detail list each library played older, +`{ library, from, to }`, and the console says so. `downgrade-libraries="off"` refuses such a +package instead, naming the version it needs. A package that carries the newer version itself +plays it, trusted, and needs none of this. + ## On your own hosting The pack is found in one of three places: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d868672d..d91c918d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -23,6 +23,7 @@ | No copyright button with `frame copyright` | `h5p.json` names no licence, `U`, or one H5P does not know (such as `MIT`) | Give `h5p.json` a licence H5P knows (CC BY, CC0 1.0, GNU GPL, PD, C, …) | | Formulas show as raw LaTeX, `\(…\)` or `$$…$$` | The package lacks `H5P.MathDisplay`, and no library bundle is attached: the player adds the bundle's MathDisplay to content with formulas, as the H5P plugins do, but attaches a bundle only to a package that lacks libraries or plays `untrusted` | Play it `untrusted`, or add `H5P.MathDisplay-1.0/` to the archive and `H5P.MathDisplay` to `preloadedDependencies`. The pack carries MathDisplay 1.0.50, which renders with MathJax from its own folder, offline too | | "This package is missing 1 of its libraries" for a package that carries every library its `h5p.json` names | One of its libraries asks, in its own `library.json`, for a version the package does not carry, usually an old export | Set `libraries="pack"`: the pack supplies it | +| Console: "played at an older version than the content names" | The content was made for a newer minor version of a library than any source has, usually on h5p.com just after a release the pack has not caught up with. It plays at the newest older minor, without what the newer version added | Most content plays as made. Where a part is missing or drawn wrong, re-export it with its libraries and play it trusted, if you trust where it came from, or wait for the pack. `downgrade-libraries="off"` refuses such a package instead. [Content newer than the pack](libraries.md#content-newer-than-the-pack) | | A video shows nothing for a long time, then plays (often the first of several) | The mp4 is deflated in the zip *and* not faststart, so it plays nothing until its last byte; videos are extracted one at a time | Normalize the package; until then, `preload="auto"` starts the transfer early | | A video never starts after the host stays down for minutes | The player retries a silent or dropped link for a few minutes, then fails the entry with an `error` event | Reload once the host is back | | `error: runtime`, content blank | Content type threw — usually a library missing from the archive, or a script blocked by the frame CSP | Check the console inside the frame; report the archive | diff --git a/docs/verify.md b/docs/verify.md index 5de534a2..0142920b 100644 --- a/docs/verify.md +++ b/docs/verify.md @@ -13,7 +13,9 @@ the content drew something. With `--untrusted` it plays the package as a site th it will, [untrusted](untrusted.md), against the library pack, and lists as warnings what the content check removes from each field: markup, attributes and styles by name, fields, values. With `--libraries pack`, or a copy of the pack's `parts/`, it plays a library the package carries -at the pack's newer version, as a site with the pack will, and says which. It is meant as the last step of a pipeline that generates or +at the pack's newer version, as a site with the pack will, and says which. Content made for a +newer minor version than any source has plays at the newest older one, as the player does by +default, with a warning for each library; `--no-downgrade-libraries` fails it instead. It is meant as the last step of a pipeline that generates or rewrites packages; the skill in `skills/h5p-verify/` tells an agent when to run it and how to read the result. diff --git a/packages/embed/README.md b/packages/embed/README.md index f38d8cef..86f708e2 100644 --- a/packages/embed/README.md +++ b/packages/embed/README.md @@ -83,6 +83,7 @@ To update, run the command again with `--force` and redeploy. | `src=` | The package, required: an `http` or `https` URL, or a path on the player domain. Encode `&`, `#`, `+`, `%` and spaces | | `libraries=pack`, `` or `none` | Where libraries come from; several are tried in order. `pack` is this domain's copy, or jsDelivr's without one: a package gets the libraries it lacks from it, and those it carries at the pack's newer versions. `none` turns off `--default-libraries` | | `refresh-libraries=off` | Play the libraries a package carries as exported; `pack` then only fills gaps | +| `downgrade-libraries=off` | Refuse content made for a newer version of a library than any source has, instead of playing it at the newest older one | | `frame`, `copyright`, `export`, `icon`, `reporting` | H5P's action bar and its buttons | | `fullscreen=off` | No fullscreen button | | `preload=auto` | Start fetching media at once | diff --git a/packages/embed/site/embed.js b/packages/embed/site/embed.js index 88403900..8cecda5a 100644 --- a/packages/embed/site/embed.js +++ b/packages/embed/site/embed.js @@ -5,7 +5,7 @@ * `h5p-embed` was told when it wrote the site, and the demo's `/embed` with the demo's copy of the * library pack. * - * ?src=[&libraries=pack| …|none][&refresh-libraries=off][&preload=auto] + * ?src=[&libraries=pack| …|none][&refresh-libraries=off][&downgrade-libraries=off][&preload=auto] * [&xapi=][&frame][©right][&export][&icon][&reporting][&fullscreen=off] * [&activity-id=][&custom-css=][&lang=] * @@ -311,7 +311,8 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null, * The element's display options, by their attribute names, for the embedding page to ask for: * `&frame©right&export` shows H5P's action bar with those buttons, `&fullscreen=off` takes * that one away, `&refresh-libraries=off` plays a package's own libraries even where the pack - * has newer ones, `&activity-id=` names the statements' object and `&custom-css=` restyles the + * has newer ones, `&downgrade-libraries=off` refuses content made for a newer version of a + * library than any source has, `&activity-id=` names the statements' object and `&custom-css=` restyles the * content to the embedding site's taste. `&lang=` is the embedding page's language, which this * page cannot read across origins: H5P's own buttons and dialogs follow it for a package that * does not name its own language, and follow the content's where it does. Not `custom-js`, @@ -326,6 +327,9 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null, // The pack's newer versions of the libraries a package carries, unless the embedding page // needs the package exactly as exported. if (params.get('refresh-libraries') === 'off') player.setAttribute('refresh-libraries', 'off') + // Content made for a newer version than any source has plays at the older one, unless the + // embedding page would rather have it refused. + if (params.get('downgrade-libraries') === 'off') player.setAttribute('downgrade-libraries', 'off') for (const name of ['activity-id', 'custom-css']) { const value = params.get(name)?.trim() if (value) player.setAttribute(name, value) diff --git a/packages/embed/tests/site.test.ts b/packages/embed/tests/site.test.ts index ceee2706..03df89f1 100644 --- a/packages/embed/tests/site.test.ts +++ b/packages/embed/tests/site.test.ts @@ -102,7 +102,8 @@ async function strippedQuiz(path: string) { /** * The quiz made against a Question Set newer than the pack's: played untrusted, its own copy is - * withheld and nothing else supplies it, so it plays only with its own code. + * withheld and nothing else supplies that version, so it plays at the pack's older one, or, with + * `downgrade-libraries=off`, only with its own code. */ async function ownCodeQuiz(path: string) { const reader = new ZipReader(new BlobReader(new Blob([await readFile(quiz)]))) @@ -381,9 +382,23 @@ describe('a written site, framed from another site', () => { await page.close() }) - it('asks before playing a package from elsewhere that needs its own code, and plays it trusted on the click', async () => { + it('plays a package from elsewhere made for a newer minor than the pack has at the older one, with no question', async () => { const page = await browser.newPage() await page.goto(`${asking.origin}/?src=${embedding.origin}/own-code.h5p`) + await page.waitForFunction(() => (document.querySelector('h5p-player') as unknown as { state: string }).state === 'ready', null, { timeout: 60_000 }) + expect(await untrusted(page)).toBe(true) + expect(await page.evaluate(() => document.querySelector('#notice button'))).toBeNull() + const downgraded = await page.evaluate( + () => (document.querySelector('h5p-player') as unknown as { libraryBundle: { downgraded?: { library: string; from: string; to: string }[] } }).libraryBundle.downgraded + ) + expect(downgraded).toEqual([{ library: 'H5P.QuestionSet', from: '1.99', to: expect.stringMatching(/^1\.21\./) }]) + await page.close() + }) + + it('asks before playing a package from elsewhere that needs its own code, and plays it trusted on the click', async () => { + const page = await browser.newPage() + // `downgrade-libraries=off` passed through: the pack's older Question Set would play it otherwise. + await page.goto(`${asking.origin}/?src=${embedding.origin}/own-code.h5p&downgrade-libraries=off`) await page.waitForSelector('#notice button', { timeout: 60_000 }) expect(await page.textContent('#notice')).toContain(`This package from ${new URL(embedding.origin).host} plays only with its own scripts.`) await page.click('#notice button') diff --git a/packages/player/scripts/build-fixtures.mjs b/packages/player/scripts/build-fixtures.mjs index fa54243a..f2de8142 100644 --- a/packages/player/scripts/build-fixtures.mjs +++ b/packages/player/scripts/build-fixtures.mjs @@ -481,7 +481,13 @@ for (const [name, minor, content] of [ // The versions the bundle serves: nothing to run. ['upgrade-1.2.h5p', '2', { message: 'Written for 1.2', child: offlineChild('1.1', 'Child written for 1.1') }], // The first step throws: played as written. - ['upgrade-fails.h5p', '0', { message: 'Written for 1.0', failUpgrade: true, child: offlineChild('1.0', 'Child written for 1.0') }] + ['upgrade-fails.h5p', '0', { message: 'Written for 1.0', failUpgrade: true, child: offlineChild('1.0', 'Child written for 1.0') }], + // A minor ahead of everything the bundle and the pack serve, the sub-content too: played at their + // newest older minor, with no step run, or refused with `downgrade-libraries="off"` (#85). + ['upgrade-1.3.h5p', '3', { message: 'Written for 1.3', child: offlineChild('1.2', 'Child written for 1.2') }], + // The content type at the version served, its sub-content a minor ahead: named only in the + // parameters, as a stripped export from h5p.com names a question type newer than the pack's. + ['newer-child.h5p', '2', { message: 'Written for 1.2', child: offlineChild('1.2', 'Child written for 1.2') }] ]) { built.push([ name, diff --git a/packages/player/scripts/lib/fixture-names.mjs b/packages/player/scripts/lib/fixture-names.mjs index d5806af6..cd53cd8e 100644 --- a/packages/player/scripts/lib/fixture-names.mjs +++ b/packages/player/scripts/lib/fixture-names.mjs @@ -31,6 +31,8 @@ export const GENERATED_FIXTURES = [ 'upgrade-1.1.h5p', 'upgrade-1.2.h5p', 'upgrade-fails.h5p', + 'upgrade-1.3.h5p', + 'newer-child.h5p', 'unversioned.h5p', 'unversioned-pack.h5p', 'corrupt.h5p', diff --git a/packages/player/src/h5p-offline-player.ts b/packages/player/src/h5p-offline-player.ts index e2f4bbee..5da0a456 100644 --- a/packages/player/src/h5p-offline-player.ts +++ b/packages/player/src/h5p-offline-player.ts @@ -20,6 +20,7 @@ import { } from './shared/constants.js' import { PlayerError, + type DowngradedLibrary, type ErrorCode, type LibrarySource, type MissingLibraries, @@ -188,16 +189,19 @@ export type PackageSource = SourceDescriptor * copy downloaded earlier rather than fetched now. `fromCache` is what a page needs for "nothing * left this origin": a bundle on the page's own origin, or one served from cache, meant no * request to a third party. `refreshed`, for the pack: the libraries the package carries that - * played at the pack's newer version. + * played at the pack's newer version. `downgraded`: the libraries the content names at a newer + * minor than any source has, which played at the newest older one (`downgrade-libraries`); absent + * when none did. */ export interface LibraryBundle { url: string origin: string fromCache: boolean refreshed?: RefreshedLibrary[] + downgraded?: DowngradedLibrary[] } -export type { RefreshedLibrary } from './shared/protocol.js' +export type { DowngradedLibrary, RefreshedLibrary } from './shared/protocol.js' /** Each library of a pack, with where its part is: the `pack` export of `@missing-elements/h5p-libraries`. */ export interface LibraryPack { @@ -296,9 +300,9 @@ function adoptShadowStyles(root: ShadowRoot): void { export class H5PPlayerElement extends HTMLElement { /** * The two attributes a change of which does something at once. Every other one — `sw`, - * `assets-base`, `jobs`, `libraries`, `pack-base`, `refresh-libraries`, `preload`, `resume`, the - * frame options — is read when a load starts or when the package is registered, so a change - * takes effect on the next load and needs no callback. + * `assets-base`, `jobs`, `libraries`, `pack-base`, `refresh-libraries`, `downgrade-libraries`, + * `preload`, `resume`, the frame options — is read when a load starts or when the package is + * registered, so a change takes effect on the next load and needs no callback. */ static get observedAttributes(): string[] { return ['src', 'auto-resize'] @@ -750,6 +754,7 @@ export class H5PPlayerElement extends HTMLElement { if (signal.aborted) return this.iframe.title = frameTitle(indexed.title) + this.reportDowngrades(indexed.downgraded) this.internalRevision = indexed.revision ?? null this.internalMetadata = indexed.metadata || indexed.mainLibrary @@ -870,6 +875,11 @@ export class H5PPlayerElement extends HTMLElement { * * With `deep`, the worker also follows each library's own dependencies, as the runtime will, * and what none of the package's folders provides is fetched the same way. + * + * What every source leaves missing gets one more round, unless `downgrade-libraries="off"`: the + * load asks the worker to serve the newest older minor of the same major for a library named at + * a newer one, and the pack to supply it (#85). Only then, so that a later source with the + * version named wins over an earlier one with an older version. */ private async index(load: LoadRef, signal: AbortSignal, deep = false, refresh = this.refreshesLibraries): Promise { const sources = this.librarySources() @@ -879,13 +889,14 @@ export class H5PPlayerElement extends HTMLElement { let next = fill ? 1 : 0 let packFailure: unknown = null let rounds = 0 + let downgrade = false for (;;) { try { let offer: PackOffer | undefined if (pack) { try { - offer = await this.packOffer(pack, { refresh, fill }) + offer = await this.packOffer(pack, { refresh, fill, downgrade }) } catch (error) { // The index of the host's copy cannot be read, and none was read before: on without // the pack, which a package that carries its libraries does not need. @@ -919,6 +930,13 @@ export class H5PPlayerElement extends HTMLElement { continue } if (!source) { + if (!downgrade && this.downgradesLibraries) { + downgrade = true + // Kept with the load's settings, so a worker started again serves the same folders. + await this.send({ type: 'attach-libraries', ...load, downgrade: true }) + if (signal.aborted) return nothingIndexed() + continue + } if (!packFailure) throw error const reason = packFailure instanceof Error ? packFailure.message : String(packFailure) throw new PlayerError( @@ -945,6 +963,25 @@ export class H5PPlayerElement extends HTMLElement { return this.getAttribute('refresh-libraries')?.trim() !== 'off' } + /** `downgrade-libraries`: on unless `off`. Read by the load. */ + private get downgradesLibraries(): boolean { + return this.getAttribute('downgrade-libraries')?.trim() !== 'off' + } + + /** + * What played at an older minor than the content names, onto `libraryBundle` and the console: + * the content was made for a version no source has, and what that version added is left out. + */ + private reportDowngrades(downgraded: DowngradedLibrary[] | undefined): void { + if (!downgraded?.length) return + if (this.internalLibraryBundle) this.internalLibraryBundle = { ...this.internalLibraryBundle, downgraded } + console.warn( + `[h5p-player] played at an older version than the content names, since no library source has it: ` + + `${downgraded.map(({ library, from, to }) => `${library} ${from} → ${to}`).join(', ')}. ` + + 'What the newer version added is left out; downgrade-libraries="off" refuses such a package instead.' + ) + } + /** Where `libraries="pack"` is: the `pack` property, else a `pack-base`, else the pinned pack on jsDelivr. */ private packLocation(): PackLocation { if (this.packValue?.length) { @@ -956,9 +993,13 @@ export class H5PPlayerElement extends HTMLElement { } /** The pack as an `index` offers it: the worker's own index for the pinned one, else the copy's. */ - private async packOffer(pack: PackLocation, { refresh, fill }: { refresh: boolean; fill: boolean }): Promise { - if (pack.kind === 'pinned') return { pinned: true, refresh, fill } - return { libraries: pack.kind === 'given' ? pack.libraries : await packIndexAt(pack.url), refresh, fill } + private async packOffer( + pack: PackLocation, + { refresh, fill, downgrade = false }: { refresh: boolean; fill: boolean; downgrade?: boolean } + ): Promise { + const asked = { refresh, fill, ...(downgrade ? { downgrade } : {}) } + if (pack.kind === 'pinned') return { pinned: true, ...asked } + return { libraries: pack.kind === 'given' ? pack.libraries : await packIndexAt(pack.url), ...asked } } /** @@ -1958,6 +1999,8 @@ interface IndexResult { /** `h5p.json`'s metadata and content type; absent from a worker older than the element. */ metadata?: ContentMetadata mainLibrary?: string + /** For a deep index: the libraries served at an older minor than asked for. */ + downgraded?: DowngradedLibrary[] } /** @@ -1984,7 +2027,8 @@ function indexResultOf(reply: WorkerReply): IndexResult { title: reply.title, revision: reply.revision, metadata: reply.metadata, - mainLibrary: reply.mainLibrary + mainLibrary: reply.mainLibrary, + downgraded: reply.downgraded } } diff --git a/packages/player/src/shared/protocol.ts b/packages/player/src/shared/protocol.ts index b6771367..2345b9a5 100644 --- a/packages/player/src/shared/protocol.ts +++ b/packages/player/src/shared/protocol.ts @@ -81,6 +81,11 @@ export type PackOffer = { refresh: boolean /** Supply from the pack what the package does not carry. Off while an earlier source is still to be tried. */ fill: boolean + /** + * Supply the newest older minor the pack has of a library the content names at a newer one than + * any source has. Sent only once every source has been tried for the version named. + */ + downgrade?: boolean } & ({ pinned: true } | { libraries: Array }) /** A part to download and attach. */ @@ -101,6 +106,19 @@ export interface RefreshedLibrary { to: string } +/** + * A library the content names at a newer minor than any library source has, played at the newest + * older minor of the same major instead (`downgrade-libraries`, #85). + */ +export interface DowngradedLibrary { + /** The machine name, `H5P.MultiChoice`. */ + library: string + /** The version the content names, `1.17`: a major and a minor, as content names a library. */ + from: string + /** The version that played, `1.16.27`. */ + to: string +} + /** * What the pack has to supply before the package can play: the parts to attach, and the package's * own folders that the newer versions among them replace. @@ -178,6 +196,8 @@ export interface PackageRecord { parts?: string[] /** The package's own library folders a part replaces; see `LoadSettings.superseded`. */ superseded?: string[] + /** An older minor answers for a newer one; see `LoadSettings.downgrade`. */ + downgrade?: boolean /** * `libraries` marks an archive registered only to supply library folders to another package. * It is never played, so it is not held to carrying everything its own `h5p.json` declares. @@ -234,6 +254,13 @@ export interface LoadSettings { * library: requests for them resolve to the part's folder, by the rule `get()` serves with. */ superseded?: string[] + /** + * A library named at a newer minor than any source has is served from the newest older minor of + * the same major. Set by the load with an `attach-libraries`, once every library source has been + * tried for the version named, and kept here so that a worker started again serves the same + * folders the frame was booted with. + */ + downgrade?: boolean /** When a load last registered these, for keeping the newest few. */ registered: number } @@ -350,9 +377,10 @@ export type ToWorkerMessage = /** * Points a package at other ones, already registered and indexed, for its libraries: a bundle, * which replaces the one before, or parts of the pack, which are added, with the package's own - * folders they replace. + * folders they replace. `downgrade`: from now on an older minor answers for a newer one nothing + * provides (`LoadSettings.downgrade`). */ - | { type: 'attach-libraries'; pkgId: string; libraryPkgId?: string; parts?: string[]; superseded?: string[]; view?: string } + | { type: 'attach-libraries'; pkgId: string; libraryPkgId?: string; parts?: string[]; superseded?: string[]; downgrade?: true; view?: string } /** * Asks for a library bundle already downloaded whole from `url`, for when `url` cannot be * reached now. Answered `downloaded-libraries`, with `null` when there is none. @@ -443,6 +471,11 @@ export type WorkerReply = * offered the pack. The reply carries nothing else then: index again once they are attached. */ plan?: PackPlan + /** + * For a `deep` index: the libraries served at an older minor than the content or a library + * asks for, which only a load that asked for the downgrade gets. Absent when none was. + */ + downgraded?: DowngradedLibrary[] } /** `views`: the register named a load key and the worker kept the settings under it. */ | { ok: true; type: 'ack'; views?: true } diff --git a/packages/player/src/sw/mount.ts b/packages/player/src/sw/mount.ts index e33b8279..54ca4eea 100644 --- a/packages/player/src/sw/mount.ts +++ b/packages/player/src/sw/mount.ts @@ -27,9 +27,11 @@ import { normalizeRequestPath } from '../shared/entry-names.js' import { contentTypeOf } from '../shared/mime.js' import { PlayerError, + type DowngradedLibrary, type FromWorkerMessage, type LibraryLoad, type LoadSettings, + type PackLibrary, type PackOffer, type PackPlan, type PackageRecord, @@ -215,10 +217,13 @@ class VirtualServer { } // A partial reader may simply not have what is missing yet; the final index says. if (!reader.partial && this.playable.has(reader)) reader.assertLibrariesPresent() + let downgraded: DowngradedLibrary[] = [] + const offered = message.pack ? packOn(message.pack) : [] if (message.deep && !reader.partial) { const served = reader.hasFallbacks ? await reader.mergedManifest() : reader.manifest - const missing = await reader.missingDependencies(served, (located) => this.readJson(located)) - if (missing) throw new PlayerError('bad-archive', explainMissingLibraries(missing), { missingLibraries: missing }) + const checked = await reader.checkDependencies(served, (located) => this.readJson(located), offered) + if (checked.missing) throw new PlayerError('bad-archive', explainMissingLibraries(checked.missing), { missingLibraries: checked.missing }) + downgraded = checked.downgraded } if (!reader.partial) { await bookkeeping(db.updatePackage(message.pkgId, { status: 'indexed', lastPlayed: Date.now() })) @@ -235,10 +240,11 @@ class VirtualServer { reader.handle.descriptor.type === 'range-http' && !reader.partial ? reader.warmSpans() : undefined, - ready: reader.partial ? await this.bootsEarly(reader) : undefined, + ready: reader.partial ? await this.bootsEarly(reader, offered) : undefined, revision: reader.revision(), metadata: reader.metadata, - mainLibrary: typeof reader.manifest.mainLibrary === 'string' ? reader.manifest.mainLibrary : undefined + mainLibrary: typeof reader.manifest.mainLibrary === 'string' ? reader.manifest.mainLibrary : undefined, + ...(downgraded.length > 0 ? { downgraded } : {}) }) return } @@ -808,6 +814,7 @@ class VirtualServer { // A bundle registered to supply libraries is the host's choice, never the package's. const untrusted = settings.untrusted === true && record.role !== 'libraries' const { libraryPkgId, parts = [], superseded = [] } = settings + const downgrade = settings.downgrade === true // The pack's parts first, then a bundle: the parts are what was planned for this package. const attached = [...parts, ...(libraryPkgId ? [libraryPkgId] : [])] @@ -824,7 +831,7 @@ class VirtualServer { stopped: null } const partialHandle = await openSource(pkgId, record.source, file, { partial: true }) - const partial = await PackageReader.fromForwardIndex(pkgId, partialHandle, snapshot, { untrusted, superseded }) + const partial = await PackageReader.fromForwardIndex(pkgId, partialHandle, snapshot, { untrusted, superseded, downgrade }) for (const id of attached) partial.use(await this.reader({ pkgId: id })) await this.rememberManifest(record, partial) return partial @@ -835,7 +842,7 @@ class VirtualServer { // 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. - const reader = await PackageReader.open(pkgId, handle, { requireLibraries: false, untrusted, superseded }) + const reader = await PackageReader.open(pkgId, handle, { requireLibraries: false, untrusted, superseded, downgrade }) for (const id of attached) reader.use(await this.reader({ pkgId: id })) await reader.settleRevision() if (record.role !== 'libraries') this.playable.add(reader) @@ -857,8 +864,7 @@ class VirtualServer { */ private async planFromPack(reader: PackageReader, offer: PackOffer, deep: boolean): Promise { if (reader.partial && !(reader.untrusted ? reader.get('h5p.json') && reader.contentArrived : reader.bootReady())) return null - const pack = - 'pinned' in offer ? PACK_INDEX.map((library) => ({ ...library, url: `${LIBRARY_PACK_BASE}${library.folder}.h5p` })) : packLibrariesIn(offer.libraries) + const pack = packOn(offer) // A `library.json` over HTTP is two ranged requests until the warm has cached it; from a // picked file or a download, or once warmed, it is a local read. const readable = deep || reader.partial || reader.handle.descriptor.type !== 'range-http' @@ -869,7 +875,9 @@ class VirtualServer { params: await reader.contentParameters(), pack, refresh: offer.refresh === true && !reader.untrusted, - fill: offer.fill !== false + fill: offer.fill !== false, + // Not while the archive arrives: what it lacks so far it may still carry. + downgrade: offer.downgrade === true && !reader.partial }) } @@ -918,14 +926,15 @@ class VirtualServer { /** An entry's JSON, from the cache when it is there, as every library's is after the warm. */ /** * Whether a download still under way can boot the frame: `bootReady`, and no library the - * declared ones need in turn absent so far. One that is absent is waited for — it may still - * arrive — and if it never does, the deep check after the download attaches a bundle that has - * it or refuses the package by name. Booted before then, the runtime asked for its + * declared ones need in turn absent so far, nor a sub-content library a source has the major of + * (`offered`, the pack's). One that is absent is waited for — it may still arrive — and if it + * never does, the deep check after the download attaches a bundle that has it, or the load's + * older minor, or refuses the package by name. Booted before then, the runtime asked for its * `library.json` while the bundle was not attached yet and ended on the 404, read as JSON. */ - private async bootsEarly(reader: PackageReader): Promise { + private async bootsEarly(reader: PackageReader, offered: ReadonlyArray): Promise { if (!reader.bootReady()) return false - return (await reader.missingDependencies(reader.manifest, (located) => this.readJson(located))) === null + return (await reader.missingDependencies(reader.manifest, (located) => this.readJson(located), offered)) === null } private async readJson({ reader, entry }: LocatedEntry): Promise { @@ -978,21 +987,28 @@ function settingsOf(record: PackageRecord, view: string | undefined): Omit( +function attached( settings: T, - { libraryPkgId, parts = [], superseded = [] }: { libraryPkgId?: string; parts?: string[]; superseded?: string[] } + { libraryPkgId, parts = [], superseded = [], downgrade }: { libraryPkgId?: string; parts?: string[]; superseded?: string[]; downgrade?: boolean } ): T { const merged = (before: string[] | undefined, added: string[]) => [...new Set([...(before ?? []), ...added])] return { ...settings, ...(libraryPkgId ? { libraryPkgId } : {}), ...(parts.length ? { parts: merged(settings.parts, parts) } : {}), - ...(superseded.length ? { superseded: merged(settings.superseded, superseded) } : {}) + ...(superseded.length ? { superseded: merged(settings.superseded, superseded) } : {}), + ...(downgrade ? { downgrade: true } : {}) } } +/** The libraries of the pack an `index` offers: the pinned one's, compiled in, or the copy's the element handed over. */ +function packOn(offer: PackOffer): Array { + return 'pinned' in offer ? PACK_INDEX.map((library) => ({ ...library, url: `${LIBRARY_PACK_BASE}${library.folder}.h5p` })) : packLibrariesIn(offer.libraries) +} + /** A registration's settings, as kept under its load key; a bundle is attached by the load itself. */ function loadSettings(record: PackageRecord): LoadSettings { const { frameAssets, allowOrigins, frameOptions, language, untrusted } = record diff --git a/packages/player/src/sw/pack-plan.ts b/packages/player/src/sw/pack-plan.ts index 06f78d06..af4eb146 100644 --- a/packages/player/src/sw/pack-plan.ts +++ b/packages/player/src/sw/pack-plan.ts @@ -21,6 +21,10 @@ import { addonPatterns, textMatches } from './package-reader.js' * matches a string in the parameters, H5P.MathDisplay for LaTeX. Added when the pack refreshes * or fills anything, the pack standing in for the platform's installed libraries; a package * played as exported, with nothing from the pack, gets none, as on a site without the addon. + * - **Downgrade**, once the load asks for it: what the content names at a newer minor than the + * pack has comes from the pack's older one, unless the package carries, or a source already + * provides, a version at least as new as the pack's (#85). The reader then serves the newest of + * them for the version named. * * Taking the newest version of each library satisfies every dependency on both sides, since each * side's requests are already met by its own versions: the pack's index is complete in itself. @@ -60,6 +64,8 @@ export interface PlanInput { pack: ReadonlyArray refresh: boolean fill: boolean + /** Supply the pack's older minor of what nothing has at the minor named. */ + downgrade?: boolean } interface Request { @@ -130,8 +136,25 @@ export function planPack(input: PlanInput): PackPlan | null { if (fromContent && !input.fill) continue const candidate = byLibrary.get(libraryKey(dependency.machineName, dependency.majorVersion)) - if (!candidate || candidate.minorVersion < dependency.minorVersion) continue - // An older minor the package carries gives way to the version that satisfies both. + if (!candidate) continue + if (candidate.minorVersion < dependency.minorVersion) { + if (!input.downgrade) continue + // Nothing has the minor named: the newest older one plays it. What the package carries or + // a source provides may already be as new as the pack's, and is then the one served. + const here = [ + ...own.flatMap((library) => (library.major === null || library.minor === null ? [] : [{ ...library, major: library.major, minor: library.minor }])), + ...[...planned.values()].map((library) => ({ machineName: library.machineName, major: library.majorVersion, minor: library.minorVersion })), + ...input.provided + ].filter((library) => library.machineName === dependency.machineName && library.major === dependency.majorVersion) + const newest = here.reduce<(typeof here)[number] | undefined>((best, library) => (!best || library.minor > best.minor ? library : best), undefined) + if (newest && newest.minor >= candidate.minorVersion) { + const carriedOlder = own.find((library) => library.machineName === newest.machineName && library.major === newest.major && library.minor === newest.minor) + for (const each of carriedOlder?.dependencies ?? []) queue.push({ dependency: each, fromContent: true }) + continue + } + } + // An older minor the package carries gives way to the version that satisfies both, or that + // comes closest to what the content names. const older = own.find((library) => library.machineName === dependency.machineName && library.major === dependency.majorVersion) if (older) supersede(older, candidate) queue.push(...plan(candidate)) diff --git a/packages/player/src/sw/package-reader.ts b/packages/player/src/sw/package-reader.ts index 233f9a95..eda7871b 100644 --- a/packages/player/src/sw/package-reader.ts +++ b/packages/player/src/sw/package-reader.ts @@ -5,6 +5,7 @@ import { extensionOf, isMediaEntry, isTextEntry } from '../shared/mime.js' import { DEFLATE, LOCAL_HEADER_FIXED_SIZE, STORED, readDataStart } from '../shared/local-header.js' import { PlayerError, + type DowngradedLibrary, type EntryLocation, type MissingLibraries, type PrefetchEntry, @@ -150,6 +151,11 @@ export class PackageReader { private readonly withheld: Set /** The package's own library folders a part of the pack replaces; see `inSuperseded`. */ private readonly superseded: ReadonlySet + /** + * Serve a library the content names at a newer minor than anything here at the newest older + * one (`resolveLibraryFolder`), as the load asked once its sources were tried. See `downgrades`. + */ + private readonly downgrade: boolean /** Archives consulted, in order, for an entry this one does not have. */ private readonly fallbacks: PackageReader[] = [] @@ -172,7 +178,8 @@ export class PackageReader { partial = false, /** For an untrusted reader, what was withheld so far; `null` for one that serves everything. */ withheld: Set | null = null, - superseded: ReadonlySet = new Set() + superseded: ReadonlySet = new Set(), + downgrade = false ) { this.pkgId = pkgId this.entries = entries @@ -181,6 +188,16 @@ export class PackageReader { this.untrusted = withheld !== null this.withheld = withheld ?? new Set() this.superseded = superseded + this.downgrade = downgrade + } + + /** + * Whether an older minor answers for a newer one now. Never while the archive is arriving: the + * package may carry the version asked for in a folder still to come, and a frame booted early on + * the older one would keep it. + */ + private get downgrades(): boolean { + return this.downgrade && !this.partial } /** `h5p.json`'s title, when it is a string: the manifest is untrusted, and three things render it. */ @@ -197,7 +214,7 @@ export class PackageReader { static async open( pkgId: string, handle: SourceHandle, - options: { requireLibraries?: boolean; untrusted?: boolean; superseded?: Iterable } = {} + options: { requireLibraries?: boolean; untrusted?: boolean; superseded?: Iterable; downgrade?: boolean } = {} ): Promise { let zipEntries: Entry[] try { @@ -235,7 +252,7 @@ export class PackageReader { const bare = new PackageReader(pkgId, handle, entries, {}) const manifest = await readManifest(bare) - const reader = new PackageReader(pkgId, handle, entries, manifest, false, withheld, superseded) + const reader = new PackageReader(pkgId, handle, entries, manifest, false, withheld, superseded, options.downgrade === true) // Every record, directories and dropped names included: the fingerprint is of the archive // as published, not of what the player chose to serve from it. reader.fingerprint = await indexFingerprint( @@ -261,9 +278,18 @@ export class PackageReader { pkgId: string, handle: SourceHandle, snapshot: ForwardIndexSnapshot, - options: { untrusted?: boolean; superseded?: Iterable } = {} + options: { untrusted?: boolean; superseded?: Iterable; downgrade?: boolean } = {} ): Promise { - const reader = new PackageReader(pkgId, handle, new Map(), {}, true, options.untrusted ? new Set() : null, new Set(options.superseded ?? [])) + const reader = new PackageReader( + pkgId, + handle, + new Map(), + {}, + true, + options.untrusted ? new Set() : null, + new Set(options.superseded ?? []), + options.downgrade === true + ) await reader.absorb(snapshot) return reader } @@ -508,7 +534,7 @@ export class PackageReader { const wanted = parseLibraryFolder(name.slice(0, slash)) if (!wanted) return undefined - const folder = resolveLibraryFolder(this.availableLibraries(), wanted) + const folder = resolveLibraryFolder(this.availableLibraries(), wanted, this.downgrades) if (!folder || folder === wanted.folder) return undefined return this.locate(`${folder}/${name.slice(slash + 1)}`) @@ -570,10 +596,10 @@ export class PackageReader { */ missingLibraries(): MissingLibraries | null { const names = this.entryNames() - const missing = describeMissingLibraries(names, this.manifest) + const missing = describeMissingLibraries(names, this.manifest, this.downgrades) if (!missing || missing.folders.length === 0 || this.withheld.size === 0) return missing const withOwn = new Set([...names, ...this.withheld]) - return findMissingLibraries(withOwn, this.manifest).length === 0 ? { ...missing, carried: true } : missing + return findMissingLibraries(withOwn, this.manifest, this.downgrades).length === 0 ? { ...missing, carried: true } : missing } /** @@ -588,11 +614,39 @@ export class PackageReader { */ async missingDependencies( manifest: PackageManifest, - read: (located: LocatedEntry) => Promise + read: (located: LocatedEntry) => Promise, + offered: ReadonlyArray<{ machineName: string; majorVersion: number }> = [] ): Promise { + return (await this.checkDependencies(manifest, read, offered)).missing + } + + /** + * The walk `missingDependencies` makes, with what it found on the way: the libraries served at an + * older minor than a dependency asks for, which only a reader told to downgrade does, each once, + * by name. The `indexed` reply carries them to the element, which reports them. + * + * The walk starts from the sub-content the parameters name as well, where a source has its + * major: an archive attached, or the pack on offer (`offered`). A stripped export's `h5p.json` + * names its main library alone, and the merged manifest drops what nothing answers for, so a + * question made for a newer minor than the pack's booted without its library and died on its + * creation, "Cannot read properties of undefined (reading 'on')", named nowhere (#85). Missing + * here, it goes to the next source, and then to the load's older minor. A library no source has + * at its major plays as before: dropped from the manifest, and removed by the content check when + * untrusted, as an old export's retired question type is. + */ + async checkDependencies( + manifest: PackageManifest, + read: (located: LocatedEntry) => Promise, + offered: ReadonlyArray<{ machineName: string; majorVersion: number }> = [] + ): Promise<{ missing: MissingLibraries | null; downgraded: DowngradedLibrary[] }> { const missing: string[] = [] + const downgraded = new Map() const seen = new Set() - let level = dependenciesIn(manifest) + const available = this.availableLibraries() + const sourced = ({ machineName, majorVersion }: LibraryDependency) => + (available.get(machineName) ?? []).some(({ major }) => major === Number(majorVersion)) || + offered.some((library) => library.machineName === machineName && library.majorVersion === Number(majorVersion)) + let level = [...dependenciesIn(manifest), ...(await this.contentLibraries()).filter(sourced)] while (level.length > 0) { const next: LibraryDependency[] = [] @@ -615,15 +669,21 @@ export class PackageReader { const reason = error instanceof Error ? error.message : String(error) throw new PlayerError('bad-archive', `${folders[0]}/library.json could not be read: ${reason}`, { cause: error }) } + const older = olderThanAsked(dependency, located, library) + if (older) downgraded.set(`${older.library} ${older.from}`, older) next.push(...dependenciesIn(library)) }) ) level = next } - if (missing.length === 0) return null + const listed = [...downgraded.values()].sort((a, b) => a.library.localeCompare(b.library) || a.from.localeCompare(b.from)) + if (missing.length === 0) return { missing: null, downgraded: listed } const carried = this.withheld.size > 0 && missing.every((folder) => this.withheld.has(`${folder}/library.json`)) - return { mainLibrary: manifest.mainLibrary, folders: missing.sort(), all: false, ...(carried ? { carried } : {}) } + return { + missing: { mainLibrary: manifest.mainLibrary, folders: missing.sort(), all: false, ...(carried ? { carried } : {}) }, + downgraded: listed + } } /** True when another archive is supplying entries this one does not have. */ @@ -647,10 +707,11 @@ export class PackageReader { const kept = new Map() // Reachable as written, or through a compatible newer minor — the same rule `get()` serves - // library files by, so a 1.20 kept here is answered from the bundle's 1.21 folder. + // library files by, so a 1.20 kept here is answered from the bundle's 1.21 folder; or, for a + // load that asked for it, through an older one, so a 1.17 is answered from the pack's 1.16. const consider = (dependency: LibraryDependency) => { if (kept.has(dependency.machineName)) return - if (reachableFolder(dependency, names, available) === undefined) return + if (reachableFolder(dependency, names, available, this.downgrades) === undefined) return kept.set(dependency.machineName, dependency) } @@ -1057,6 +1118,21 @@ export function dependenciesIn(value: unknown): LibraryDependency[] { ) } +/** + * A dependency served at an older minor than it asks for, as `checkDependencies` reports it: only + * from a versioned folder of the same major, the one a downgrade picks. A folder named without a + * version answers for any version, as it always has, and is not a downgrade. + */ +function olderThanAsked(dependency: LibraryDependency, located: LocatedEntry, library: unknown): DowngradedLibrary | null { + const folder = located.entry.name.slice(0, located.entry.name.indexOf('/')) + const served = parseLibraryFolder(folder) + const wanted = { major: Number(dependency.majorVersion), minor: Number(dependency.minorVersion) } + if (!served || served.machineName !== dependency.machineName || served.major !== wanted.major || served.minor >= wanted.minor) return null + const patch = (library as { patchVersion?: unknown } | null)?.patchVersion + const patchVersion = typeof patch === 'number' && Number.isInteger(patch) && patch >= 0 ? patch : typeof patch === 'string' && /^\d+$/.test(patch) ? Number(patch) : 0 + return { library: dependency.machineName, from: `${wanted.major}.${wanted.minor}`, to: `${served.major}.${served.minor}.${patchVersion}` } +} + /** * The two folder names a library may be stored under: the versioned one, and the bare machine * name older packages use. Each is tried in that order, as h5p-standalone tried them. @@ -1072,21 +1148,26 @@ export function libraryFolderNames(dependency: LibraryDependency): string[] { * The folder a dependency is served from: its name as written, or the bare machine name * h5p-standalone falls back to, when that folder's `library.json` is among `names`; else a * compatible newer minor of the same major from `available`, the rule `get()` serves library - * files by. `bootReady`, `mergedManifest` and `findMissingLibraries` all decide by this, so it - * lives once. + * files by, or with `downgrade` an older one. `bootReady`, `mergedManifest` and + * `findMissingLibraries` all decide by this, so it lives once. */ function reachableFolder( dependency: LibraryDependency, names: ReadonlySet, - available: Map + available: Map, + downgrade = false ): string | undefined { return ( libraryFolderNames(dependency).find((folder) => names.has(`${folder}/library.json`)) ?? - resolveLibraryFolder(available, { - machineName: dependency.machineName, - major: Number(dependency.majorVersion), - minor: Number(dependency.minorVersion) - }) + resolveLibraryFolder( + available, + { + machineName: dependency.machineName, + major: Number(dependency.majorVersion), + minor: Number(dependency.minorVersion) + }, + downgrade + ) ) } @@ -1140,16 +1221,23 @@ export function indexLibraryFolders(entryNames: Iterable): Map, - dependency: { machineName: string; major: number; minor: number } + dependency: { machineName: string; major: number; minor: number }, + downgrade = false ): string | undefined { - const satisfying = (available.get(dependency.machineName) ?? []) - .filter((candidate) => candidate.major === dependency.major && candidate.minor >= dependency.minor) - .sort((a, b) => a.minor - b.minor) + const sameMajor = (available.get(dependency.machineName) ?? []).filter((candidate) => candidate.major === dependency.major) + const satisfying = sameMajor.filter((candidate) => candidate.minor >= dependency.minor).sort((a, b) => a.minor - b.minor) + if (satisfying.length > 0 || !downgrade) return satisfying[0]?.folder - return satisfying[0]?.folder + return [...sameMajor].sort((a, b) => b.minor - a.minor)[0]?.folder } /** @@ -1158,14 +1246,15 @@ export function resolveLibraryFolder( */ export function findMissingLibraries( entryNames: ReadonlySet, - manifest: PackageManifest + manifest: PackageManifest, + downgrade = false ): LibraryDependency[] { const dependencies = manifest.preloadedDependencies if (!Array.isArray(dependencies)) return [] const available = indexLibraryFolders(entryNames) - return dependencies.filter((dependency) => reachableFolder(dependency, entryNames, available) === undefined) + return dependencies.filter((dependency) => reachableFolder(dependency, entryNames, available, downgrade) === undefined) } /** @@ -1178,7 +1267,8 @@ export function findMissingLibraries( */ export function describeMissingLibraries( entryNames: ReadonlySet, - manifest: PackageManifest + manifest: PackageManifest, + downgrade = false ): MissingLibraries | null { const dependencies = manifest.preloadedDependencies @@ -1186,7 +1276,7 @@ export function describeMissingLibraries( return { mainLibrary: manifest.mainLibrary, folders: [], all: true } } - const missing = findMissingLibraries(entryNames, manifest) + const missing = findMissingLibraries(entryNames, manifest, downgrade) if (missing.length === 0) return null return { diff --git a/packages/player/tests/browser/pack.test.ts b/packages/player/tests/browser/pack.test.ts index a3f10a04..0cd45143 100644 --- a/packages/player/tests/browser/pack.test.ts +++ b/packages/player/tests/browser/pack.test.ts @@ -94,6 +94,54 @@ describe('the library pack, split into parts', () => { expect((await loadOf(player)).parts).toEqual([]) }) + it('plays content written for a newer minor than the pack has on its newest older one, and says so (#85)', async () => { + const player = await play(fresh(FIXTURES.writtenFor13, 'downgrade'), withPack()) + + // No step runs downward: the parameters play as written, on the older code. + expect(messageOf(player)).toBe('Written for 1.3') + expect(frameWindow(player).document.querySelector('.h5p-offline-child-text')?.textContent).toBe('Child written for 1.2') + expect((await loadOf(player)).parts).toEqual(['H5P.OfflineChild-1.1.h5p', 'H5P.OfflineTest-1.2.h5p']) + expect(player.libraryBundle?.downgraded).toEqual([ + { library: 'H5P.OfflineChild', from: '1.2', to: '1.1.0' }, + { library: 'H5P.OfflineTest', from: '1.3', to: '1.2.0' } + ]) + expect(player.libraryBundle?.refreshed).toEqual([]) + }) + + it('refuses it with downgrade-libraries="off", naming the version it needs', async () => { + const { result } = await settle(fresh(FIXTURES.writtenFor13, 'no-downgrade'), withPack({ 'downgrade-libraries': 'off' })) + if (result.ok) expect.fail('expected the package to be refused') + expect(result.detail).toMatchObject({ code: 'bad-archive', missingLibraries: { folders: ['H5P.OfflineTest-1.3'] } }) + }) + + it('plays sub-content made for a newer minor than the pack has, named only in the parameters, on its older one', async () => { + // The content type is the pack's own version, so nothing `h5p.json` names is missing. Until the + // walk started from the parameters, the child's library was left out of what the frame loads, + // and the content died creating it. + const player = await play(fresh(FIXTURES.newerChild, 'child'), withPack()) + + expect(messageOf(player)).toBe('Written for 1.2') + expect(frameWindow(player).document.querySelector('.h5p-offline-child-text')?.textContent).toBe('Child written for 1.2') + expect((await loadOf(player)).parts).toEqual(['H5P.OfflineChild-1.1.h5p', 'H5P.OfflineTest-1.2.h5p']) + expect(player.libraryBundle?.downgraded).toEqual([{ library: 'H5P.OfflineChild', from: '1.2', to: '1.1.0' }]) + }) + + it('refuses that sub-content by name with downgrade-libraries="off", rather than booting without its library', async () => { + const { result } = await settle(fresh(FIXTURES.newerChild, 'child-off'), withPack({ 'downgrade-libraries': 'off' })) + if (result.ok) expect.fail('expected the package to be refused') + expect(result.detail).toMatchObject({ code: 'bad-archive', missingLibraries: { folders: ['H5P.OfflineChild-1.2'] } }) + }) + + it('takes the version named from a later source before an older one from an earlier source', async () => { + // The bundle, first, has the content type at 1.0; the pack, after it, at the 1.2 the content + // names. Every source is tried for the version named before any older one is played. + const player = await play(fresh(FIXTURES.writtenFor12, 'order'), { libraries: `${FIXTURES.libraries} pack`, 'pack-base': PACK }) + + expect(messageOf(player)).toBe('Written for 1.2') + expect(player.libraryBundle?.downgraded).toBeUndefined() + expect((await loadOf(player)).parts).toEqual(['H5P.OfflineChild-1.1.h5p', 'H5P.OfflineTest-1.2.h5p']) + }) + it('refreshes nothing without libraries="pack", whatever else names the pack', async () => { const player = await play(fresh(FIXTURES.basic, 'no-pack'), { 'pack-base': PACK }) expect(messageOf(player)).toBe(BASIC_MESSAGE) diff --git a/packages/player/tests/browser/untrusted.test.ts b/packages/player/tests/browser/untrusted.test.ts index f481d434..bbfd8c75 100644 --- a/packages/player/tests/browser/untrusted.test.ts +++ b/packages/player/tests/browser/untrusted.test.ts @@ -18,8 +18,8 @@ type Marked = Window & { H5P: { instances: { params: Record }[] } } -const playUntrusted = async (src: string) => { - const player = createPlayer({ untrusted: '', libraries: FIXTURES.libraries }) +const playUntrusted = async (src: string, extra: Record = {}) => { + const player = createPlayer({ untrusted: '', libraries: FIXTURES.libraries, ...extra }) const settled = waitForSettled(player) player.setAttribute('src', src) return { player, result: await settled } @@ -145,8 +145,15 @@ describe('an untrusted package', () => { expect(scripts.some((source) => source.includes('jsdelivr') || source.includes('googleapis'))).toBe(false) }) - it('refuses a package that needs a library only it carries, and says its own copy would play it', async () => { - const { result } = await playUntrusted(FIXTURES.untrustedNewer) + it("plays a package that carries a newer minor than the bundle's on the bundle's, none of its own code running (#85)", async () => { + const { player, result } = await playUntrusted(FIXTURES.untrustedNewer) + if (!result.ok) expect.fail(`${result.detail.code} — ${result.detail.message}`) + expect(message(player)).toBe('Served from the archive, never extracted to disk.') + expect(player.libraryBundle?.downgraded).toEqual([{ library: 'H5P.OfflineTest', from: '1.3', to: '1.0.0' }]) + }) + + it('refuses it with downgrade-libraries="off", and says its own copy would play it', async () => { + const { result } = await playUntrusted(FIXTURES.untrustedNewer, { 'downgrade-libraries': 'off' }) expect(result.ok).toBe(false) if (result.ok) return expect(result.detail.code).toBe('bad-archive') diff --git a/packages/player/tests/browser/utils.ts b/packages/player/tests/browser/utils.ts index 33d5f93f..04cdc867 100644 --- a/packages/player/tests/browser/utils.ts +++ b/packages/player/tests/browser/utils.ts @@ -65,6 +65,10 @@ export const FIXTURES = { writtenFor11: '/fixtures/upgrade-1.1.h5p', writtenFor12: '/fixtures/upgrade-1.2.h5p', upgradeFails: '/fixtures/upgrade-fails.h5p', + /** Written for 1.3 with sub-content at 1.2: a minor ahead of every source here (#85). */ + writtenFor13: '/fixtures/upgrade-1.3.h5p', + /** Written for 1.2, the version served, with sub-content at 1.2, a minor ahead of every source here. */ + newerChild: '/fixtures/newer-child.h5p', /** Library folders with no version suffix, the shape older packages use. */ unversioned: '/fixtures/unversioned.h5p', unversionedPack: '/fixtures/unversioned-pack.h5p' diff --git a/packages/player/tests/unit/library-versions.test.ts b/packages/player/tests/unit/library-versions.test.ts index 24bc860e..21bba9ce 100644 --- a/packages/player/tests/unit/library-versions.test.ts +++ b/packages/player/tests/unit/library-versions.test.ts @@ -69,6 +69,16 @@ describe('resolveLibraryFolder', () => { ).toBeUndefined() }) + it('with downgrade, serves the newest older minor of the same major for one nothing satisfies (#85)', () => { + expect(resolveLibraryFolder(available, { machineName: 'H5P.Text', major: 1, minor: 9 }, true)).toBe('H5P.Text-1.4') + }) + + it('with downgrade, still serves a version that satisfies first, and never crosses a major', () => { + expect(resolveLibraryFolder(available, { machineName: 'H5P.Text', major: 1, minor: 2 }, true)).toBe('H5P.Text-1.4') + expect(resolveLibraryFolder(available, { machineName: 'H5P.Question', major: 1, minor: 0 }, true)).toBeUndefined() + expect(resolveLibraryFolder(available, { machineName: 'H5P.Question', major: 3, minor: 0 }, true)).toBeUndefined() + }) + it('indexes only folders that actually carry a library.json', () => { expect(indexLibraryFolders(['H5P.Text-1.1/text.js']).size).toBe(0) }) @@ -96,4 +106,10 @@ describe('findMissingLibraries with compatible versions', () => { it('still accepts the unversioned folder name', () => { expect(findMissingLibraries(new Set(['H5P.InteractiveVideo/library.json']), manifest)).toEqual([]) }) + + it('reports an older minor as missing, and with downgrade accepts it', () => { + const names = new Set(['H5P.InteractiveVideo-1.21/library.json']) + expect(findMissingLibraries(names, manifest)).toHaveLength(1) + expect(findMissingLibraries(names, manifest, true)).toEqual([]) + }) }) diff --git a/packages/player/tests/unit/merged-manifest.test.ts b/packages/player/tests/unit/merged-manifest.test.ts index eb1a6625..58998432 100644 --- a/packages/player/tests/unit/merged-manifest.test.ts +++ b/packages/player/tests/unit/merged-manifest.test.ts @@ -174,6 +174,43 @@ describe('missingDependencies', () => { const reader = await withPack(inconsistent, bundle) expect(await reader.missingDependencies(await reader.mergedManifest(), read)).toBeNull() }) + + /** A stripped export whose question was made for a newer minor than any source has (#85). */ + const newerQuestion = { + 'h5p.json': JSON.stringify({ mainLibrary: 'H5P.Main', preloadedDependencies: [{ machineName: 'H5P.Main', majorVersion: 1, minorVersion: 0 }] }), + 'content/content.json': JSON.stringify({ questions: [{ library: 'H5P.Sub 1.3', params: {} }, { library: 'H5P.Retired 1.0', params: {} }] }) + } + const older = { 'h5p.json': '{}', 'H5P.Main-1.0/library.json': library('H5P.Main', 1, 0), 'H5P.Sub-1.2/library.json': library('H5P.Sub', 1, 2) } + + it('starts from the sub-content the parameters name, where a source has its major', async () => { + // The merged manifest drops what nothing answers for, so the walk from it alone passed this. + const attached = await withPack(newerQuestion, older) + const merged = await attached.mergedManifest() + expect(merged.preloadedDependencies?.map(({ machineName }) => machineName)).toEqual(['H5P.Main']) + expect(await attached.missingDependencies(merged, read)).toEqual({ mainLibrary: 'H5P.Main', folders: ['H5P.Sub-1.3'], all: false }) + + // The pack on offer counts as a source before any part of it is attached. + const bare = { 'h5p.json': '{}', 'H5P.Main-1.0/library.json': library('H5P.Main', 1, 0) } + const offered = await withPack(newerQuestion, bare) + expect(await offered.missingDependencies(await offered.mergedManifest(), read)).toBeNull() + expect(await offered.missingDependencies(await offered.mergedManifest(), read, [{ machineName: 'H5P.Sub', majorVersion: 1 }])).toEqual({ + mainLibrary: 'H5P.Main', + folders: ['H5P.Sub-1.3'], + all: false + }) + }) + + it('with downgrade, serves it from the older minor and reports it; one no source has at its major plays as before', async () => { + const reader = await PackageReader.open('c', handleOf(await zipOf(newerQuestion)), { requireLibraries: false, downgrade: true }) + reader.use(await PackageReader.open('p', handleOf(await zipOf(older)), { requireLibraries: false })) + const merged = await reader.mergedManifest() + expect(merged.preloadedDependencies?.map(({ machineName }) => machineName)).toEqual(['H5P.Main', 'H5P.Sub']) + // H5P.Retired is in no source at any minor: left out of the manifest and not missing, as before. + expect(await reader.checkDependencies(merged, read)).toEqual({ + missing: null, + downgraded: [{ library: 'H5P.Sub', from: '1.3', to: '1.2.0' }] + }) + }) }) describe('addonPatterns and textMatches', () => { diff --git a/packages/player/tests/unit/pack-plan.test.ts b/packages/player/tests/unit/pack-plan.test.ts index 34b746a6..94e7443c 100644 --- a/packages/player/tests/unit/pack-plan.test.ts +++ b/packages/player/tests/unit/pack-plan.test.ts @@ -160,6 +160,43 @@ describe('supplying what a package lacks', () => { }) }) +describe('content made for a newer minor than the pack has (#85)', () => { + // A content-only export from h5p.com after a minor bump the pack has not caught up with. + const newer = dependencies([['H5P.QuestionSet', 1, 22], ['H5P.MultiChoice', 1, 17]]) + + it('supplies nothing for it until the load asks for the downgrade', () => { + expect(plan({ roots: newer })).toBeNull() + }) + + it("then supplies the pack's newest older minor, with what each part needs", () => { + const result = plan({ roots: newer, downgrade: true }) + expect(folders(result)).toEqual(['H5P.JoubelUI-1.3', 'H5P.MultiChoice-1.16', 'H5P.Question-1.5', 'H5P.QuestionSet-1.21']) + expect(result?.refreshed).toEqual([]) + }) + + it('keeps an older version the package carries when it is at least as new as the pack\'s', () => { + const own = [carried('H5P.MultiChoice', 1, 16, 30, [['H5P.Question', 1, 5]]), carried('H5P.Question', 1, 5, 9)] + expect(plan({ own, roots: dependencies([['H5P.MultiChoice', 1, 17]]), downgrade: true, refresh: false })).toBeNull() + }) + + it("gives one older than the pack's way to the pack's, as a refresh of what the package carries", () => { + const own = [carried('H5P.MultiChoice', 1, 14, 2, [])] + const result = plan({ own, roots: dependencies([['H5P.MultiChoice', 1, 17]]), downgrade: true, refresh: false }) + expect(folders(result)).toEqual(['H5P.JoubelUI-1.3', 'H5P.MultiChoice-1.16', 'H5P.Question-1.5']) + expect(result?.superseded).toEqual(['H5P.MultiChoice-1.14']) + expect(result?.refreshed).toEqual([{ library: 'H5P.MultiChoice', from: '1.14.2', to: '1.16.9' }]) + }) + + it('asks nothing of the pack where an attached archive is as new already', () => { + const provided = [{ folder: 'H5P.MultiChoice-1.16', machineName: 'H5P.MultiChoice', major: 1, minor: 16 }] + expect(plan({ roots: dependencies([['H5P.MultiChoice', 1, 17]]), provided, downgrade: true })).toBeNull() + }) + + it('never crosses a major, and leaves a library the pack has not got for the error', () => { + expect(plan({ roots: dependencies([['H5P.QuestionSet', 2, 0], ['H5P.Unknown', 1, 3]]), downgrade: true })).toBeNull() + }) +}) + describe('addons', () => { const params = { text: 'The area is \\(\\pi r^2\\).' } diff --git a/packages/verify/README.md b/packages/verify/README.md index a01be5c1..ea6b2727 100644 --- a/packages/verify/README.md +++ b/packages/verify/README.md @@ -69,7 +69,8 @@ The package stays on this computer. The preview ends when its tab is closed, or ``` It plays any content type the player plays, with the same player, runtime and library sources -as the check, so `--untrusted`, `--libraries` and `--no-refresh-libraries` mean the same. +as the check, so `--untrusted`, `--libraries`, `--no-refresh-libraries` and +`--no-downgrade-libraries` mean the same. The package is served with `Range`, as a static host serves it. The libraries take a few requests, and a video is read by the ranges the player asks for, so a large one starts at once @@ -91,6 +92,7 @@ Exit code 0 when it ends, 2 when it could not start. | `--untrusted` | play it as a site plays a package it did not make, and report what the content check removed | | `--libraries ` | where libraries come from, tried in order: `pack` (the library pack), a bundle's URL, a bundle on disk, or a copy of the pack's `parts/` folder, which plays as `pack`; the verifier serves what is on disk itself. With the pack, a library the package carries plays at the pack's newer version, as on a site with the pack, and the summary lists each under `refreshed from the pack` | | `--no-refresh-libraries` | play the libraries the package carries even where the pack has newer ones | +| `--no-downgrade-libraries` | fail content made for a newer minor version of a library than any source has. Without it, such content plays at the newest older minor, as on a site with the player's defaults, with a warning for each library and the list in `report.downgraded` | | `--out ` | where the report and screenshot go | | `--browser ` | a Chromium-based browser; otherwise Chrome, then Edge, then Playwright's Chromium | | `--ready ` | time allowed to reach `ready`, default 60 | diff --git a/packages/verify/bin/h5p-verify.mjs b/packages/verify/bin/h5p-verify.mjs index 9c83e86a..e6faf2f8 100755 --- a/packages/verify/bin/h5p-verify.mjs +++ b/packages/verify/bin/h5p-verify.mjs @@ -15,7 +15,8 @@ it could not start. Options: --preview open the package in your browser instead of checking it; it takes - --untrusted, --libraries and --no-refresh-libraries + --untrusted, --libraries, --no-refresh-libraries and + --no-downgrade-libraries --no-open with --preview, print the address instead of opening a browser --untrusted play it as a site plays a package it did not make: none of its own code runs, its libraries come only from --libraries (pack by @@ -27,6 +28,10 @@ Options: pack, a library the package carries plays at the pack's newer version, as on a site with the pack --no-refresh-libraries play the libraries the package carries even where the pack has newer + --no-downgrade-libraries + refuse content made for a newer minor version of a library than any + source has, instead of playing it at the newest older one with a + warning --out where report.json and screenshot.png go (default: .verify/ beside the package) --browser a Chromium-based browser; Chrome, Edge or Playwright's found otherwise @@ -47,6 +52,7 @@ try { libraries: { type: 'string' }, untrusted: { type: 'boolean' }, 'no-refresh-libraries': { type: 'boolean' }, + 'no-downgrade-libraries': { type: 'boolean' }, out: { type: 'string' }, browser: { type: 'string' }, ready: { type: 'string' }, @@ -86,7 +92,8 @@ if (args.values.preview) { file, libraries: args.values.libraries, untrusted: args.values.untrusted, - refreshLibraries: !args.values['no-refresh-libraries'] + refreshLibraries: !args.values['no-refresh-libraries'], + downgradeLibraries: !args.values['no-downgrade-libraries'] }) } catch (error) { console.error(error instanceof VerifyError ? error.message : error) @@ -125,6 +132,7 @@ try { libraries: args.values.libraries, untrusted: args.values.untrusted, refreshLibraries: !args.values['no-refresh-libraries'], + downgradeLibraries: !args.values['no-downgrade-libraries'], out, browser: args.values.browser, readyTimeout: seconds(args.values.ready, 60_000), diff --git a/packages/verify/lib/page.html b/packages/verify/lib/page.html index 46622cbc..ee9d810b 100644 --- a/packages/verify/lib/page.html +++ b/packages/verify/lib/page.html @@ -23,6 +23,7 @@ const packBase = query.get('pack-base') if (packBase) player.setAttribute('pack-base', packBase) if (query.get('refresh-libraries') === 'off') player.setAttribute('refresh-libraries', 'off') + if (query.get('downgrade-libraries') === 'off') player.setAttribute('downgrade-libraries', 'off') // Played as a site plays a package it did not make: none of its own code, the content checked. if (query.has('untrusted')) player.untrusted = true diff --git a/packages/verify/lib/preview.html b/packages/verify/lib/preview.html index bf7eef1e..3e5b815b 100644 --- a/packages/verify/lib/preview.html +++ b/packages/verify/lib/preview.html @@ -35,6 +35,8 @@

Preview

if (settings.libraries) player.setAttribute('libraries', settings.libraries) if (settings.packBase) player.setAttribute('pack-base', settings.packBase) if (!settings.refreshLibraries) player.setAttribute('refresh-libraries', 'off') + // `false` only: a preview page from before the option said nothing, and the element's default is on. + if (settings.downgradeLibraries === false) player.setAttribute('downgrade-libraries', 'off') if (settings.untrusted) player.untrusted = true // Set once its server has gone. A load still under way changes state after that, and its // "Opening…" or the error of a request that failed would write over the page saying so. diff --git a/packages/verify/lib/preview.mjs b/packages/verify/lib/preview.mjs index ac58b792..a12e3cc1 100644 --- a/packages/verify/lib/preview.mjs +++ b/packages/verify/lib/preview.mjs @@ -39,6 +39,8 @@ const HEARTBEAT_MS = 15_000 * @property {boolean} [untrusted] play it as a site that did not make it plays it * @property {boolean} [refreshLibraries] with the pack, play its newer versions of the libraries the * package carries; default true + * @property {boolean} [downgradeLibraries] play a library the content names at a newer minor than any + * source has at the newest older one; default true * @property {{ dist: string, runtime: string }} [roots] the player's `dist/` and the runtime's, for a host * that ships them itself, as the VS Code extension does; the installed packages' otherwise * @property {number} [port] the port to take; default 4645, and any free one when that is taken @@ -67,6 +69,7 @@ export async function previewPackage(options) { libraries: sources.attribute, packBase: sources.packBase, refreshLibraries: options.refreshLibraries !== false, + downgradeLibraries: options.downgradeLibraries !== false, untrusted: options.untrusted === true } // `<` as an escape, so that no file name can end the script block it is written into. diff --git a/packages/verify/lib/verify.mjs b/packages/verify/lib/verify.mjs index ffdc61ef..ba8ddd95 100644 --- a/packages/verify/lib/verify.mjs +++ b/packages/verify/lib/verify.mjs @@ -7,7 +7,7 @@ import { VerifyError, librarySources, packageFile, playerDist, sendFile, serve } export { VerifyError } -/** @import { H5PPlayerElement, PlayerErrorDetail, PlayerState, RefreshedLibrary } from '@missing-elements/h5p-offline-player' */ +/** @import { DowngradedLibrary, H5PPlayerElement, PlayerErrorDetail, PlayerState, RefreshedLibrary } from '@missing-elements/h5p-offline-player' */ /** * Plays a package the way a learner would — the real element, the real Service Worker, a real @@ -44,6 +44,8 @@ const CONTENT_CHECK_HEADER = 'X-H5P-Content-Check' * @property {boolean} [untrusted] play the package `untrusted`, as a site that did not make it plays it * @property {boolean} [refreshLibraries] with the pack, play its newer versions of the libraries the * package carries, as the element does unless told otherwise; default true + * @property {boolean} [downgradeLibraries] play a library the content names at a newer minor than + * any source has at the newest older one, as the element does unless told otherwise; default true * @property {string} [out] where `report.json` and `screenshot.png` go; nothing is written without it * @property {string} [browser] a Chromium-based browser executable; found automatically otherwise * @property {number} [readyTimeout] ms allowed to reach `ready`; default 60 000 @@ -60,6 +62,8 @@ const CONTENT_CHECK_HEADER = 'X-H5P-Content-Check' * @property {string | null} libraries the libraries asked for; `pack` when played untrusted and none were named * @property {boolean} untrusted whether the element played it untrusted, read back from it * @property {RefreshedLibrary[]} refreshed the libraries the package carries that played at the pack's newer version + * @property {DowngradedLibrary[]} downgraded the libraries the content names at a newer minor than any + * source has, which played at the newest older one; each is also a warning * @property {'pass' | 'fail'} verdict * @property {string[]} reasons why it failed; empty on a pass * @property {string[]} warnings what is worth reading either way @@ -187,6 +191,7 @@ export async function verifyPackage(options) { if (sources.attribute) query.set('libraries', sources.attribute) if (sources.packBase) query.set('pack-base', sources.packBase) if (options.refreshLibraries === false) query.set('refresh-libraries', 'off') + if (options.downgradeLibraries === false) query.set('downgrade-libraries', 'off') if (untrusted) query.set('untrusted', '') await page.goto(`${server.url}/${query.size ? `?${query}` : ''}`) await page.setInputFiles('#file', file) @@ -269,6 +274,9 @@ export async function verifyPackage(options) { // The libraries the package carries that played at the pack's newer version: what a site // with the pack shows, and a sign the export is older than the pack. refreshed: collected.libraryBundle?.refreshed ?? [], + // Made for a newer minor than any source has, and played at an older one: what the newer + // version added is left out, which only a person playing it can judge. + downgraded: collected.libraryBundle?.downgraded ?? [], verdict: 'pass', reasons: [], warnings: [], @@ -307,6 +315,9 @@ export async function verifyPackage(options) { report.verdict = 'fail' report.reasons.push(`${booting.length} uncaught error${booting.length === 1 ? '' : 's'} while booting: ${dedupe(booting.map((e) => e.message)).join('; ')}`) } + for (const { library, from, to } of report.downgraded) { + report.warnings.push(`${library} played at ${to}, older than the ${from} the content was made for, since no library source has ${from}: what ${from} added is left out`) + } for (const message of dedupe(report.errors.filter((e) => e.afterReady).map((e) => e.message))) report.warnings.push(`runtime error after ready: ${message}`) for (const { url, status, error } of failedRequests) report.warnings.push(`request failed: ${url} (${status ?? error})`) for (const { directive, blocked } of csp) report.warnings.push(`blocked by the frame's CSP: ${blocked} (${directive})`) diff --git a/packages/verify/tests/verify.test.ts b/packages/verify/tests/verify.test.ts index 70b1998a..6fd53e25 100644 --- a/packages/verify/tests/verify.test.ts +++ b/packages/verify/tests/verify.test.ts @@ -230,9 +230,18 @@ describe('h5p-verify', () => { expect(report.warnings).toEqual([]) }, 120_000) - it('played untrusted, refuses a package that needs its own copy of a library, and says what to do', async () => { + it('played untrusted, plays a package made for a newer minor than the pack has at the pack\'s, with a warning (#85)', async () => { const report = await verifyPackage({ file: await quizNeedingNewerLibrary(), untrusted: true, libraries: pack }) + expect(report.verdict).toBe('pass') + expect(report.downgraded).toEqual([{ library: 'H5P.QuestionSet', from: '1.99', to: expect.stringMatching(/^1\.21\.\d+$/) }]) + expect(report.warnings.some((warning) => warning.startsWith('H5P.QuestionSet played at 1.21.') && warning.includes('1.99'))).toBe(true) + expect(summarize(report)).toContain('warning: H5P.QuestionSet played at 1.21.') + }, 120_000) + + it('played untrusted with --no-downgrade-libraries, refuses a package that needs its own copy of a library, and says what to do', async () => { + const report = await verifyPackage({ file: await quizNeedingNewerLibrary(), untrusted: true, libraries: pack, downgradeLibraries: false }) + expect(report.verdict).toBe('fail') expect(report.errors[0]?.missingLibraries?.carried).toBe(true) expect(report.errors[0]?.missingLibraries?.folders).toContain('H5P.QuestionSet-1.99') From 707dbb6b2ec9d52cc5b92d72cf9d19589a77b7c5 Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Thu, 29 Oct 2026 14:05:09 +0200 Subject: [PATCH 2/2] fix: report libraries played older on the load, not on the library bundle (#85) Found reviewing the first commit. A package served from its own older copy, with no library source attached, played with only the console saying so: the list rode on `libraryBundle`, which is null there, so the verifier passed such a package with no warning where it had failed before. h5p.org's Impressive Presentation is one, its libraries asking for Font Awesome 4.5 beside the 4.3 it carries; an export whose `h5p.json` names a newer minor than its folder is another. The list is now the load's: `downgradedLibraries`, on the element and in the `ready` detail, which the verifier, the demo page and the embed page's report read. Also: the VS Code extension's bar counts the libraries played older, as it counts refreshed ones; the untrusted guide no longer says a newer minor is refused; and the element reads `downgrade-libraries` once per index, as it reads `refresh-libraries`. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 16 ++++++--- apps/demo/demo/player-page.js | 2 +- docs/api.md | 7 ++-- docs/libraries.md | 8 ++--- docs/untrusted.md | 10 +++--- docs/verify.md | 6 ++-- packages/embed/site/embed.js | 25 ++++++++------ packages/embed/tests/site.test.ts | 2 +- packages/player/scripts/build-fixtures.mjs | 13 ++++++++ packages/player/scripts/lib/fixture-names.mjs | 1 + packages/player/src/h5p-offline-player.ts | 33 ++++++++++++++----- .../player/tests/browser/libraries.test.ts | 26 +++++++++++++++ packages/player/tests/browser/pack.test.ts | 6 ++-- .../player/tests/browser/untrusted.test.ts | 2 +- packages/player/tests/browser/utils.ts | 2 ++ packages/verify/lib/verify.mjs | 6 ++-- packages/verify/tests/verify.test.ts | 25 ++++++++++++++ packages/vscode/src/page.mjs | 4 ++- packages/vscode/src/webview.mjs | 12 ++++--- packages/vscode/tests/html.test.ts | 17 ++++++++-- 20 files changed, 170 insertions(+), 53 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ffab1fb0..31b0df4a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1238,11 +1238,17 @@ element, and the element acts. That relay is why `frame-document.ts` has a `mess `pack.test.ts` is that shape. A library no source has at its major still plays as before, dropped from the manifest, its sub-content removed by the content check when untrusted, so an old export's retired question type is not refused for it. The walk names each dependency - served from a versioned folder below the minor asked; the element puts them on - `libraryBundle.downgraded` and - warns in the console, the verifier makes each a warning and `report.downgraded` - (`--no-downgrade-libraries` refuses instead), the player page shows it with an Older if needed - switch, and the embed page passes `&downgrade-libraries=off` through. One thing follows for the + served from a versioned folder below the minor asked. The element keeps them as the load's + `downgradedLibraries`, in the `ready` detail too, and warns in the console; the verifier makes + each a warning and `report.downgraded` (`--no-downgrade-libraries` refuses instead), the + player page and the VS Code extension's bar show them, the player page with an Older if needed + switch, and the embed page passes `&downgrade-libraries=off` through and posts the list in its + report. The list is the load's because the older copy may be the package's own, with no bundle + attached: an export whose `h5p.json` names a newer minor than its folder, or h5p.org's + Impressive Presentation, whose libraries ask for Font Awesome 4.5 beside the 4.3 it carries. + The first cut put it on `libraryBundle`, which is `null` there, so only the console said so, + and the verifier passed such a package without a warning where it had failed before; the + branch's own review found it. One thing follows for the pages that ask before a package's own code runs: untrusted, a package carrying a newer minor than the pack's now plays on the pack's, so they ask only for a library no source has at its major, or with the switch off. The embed's `site.test.ts` plays its Question Set 1.99 package both ways. diff --git a/apps/demo/demo/player-page.js b/apps/demo/demo/player-page.js index 6d295c5d..6b8b5e86 100644 --- a/apps/demo/demo/player-page.js +++ b/apps/demo/demo/player-page.js @@ -120,7 +120,7 @@ player.addEventListener('progress', (event) => { player.addEventListener('ready', () => { bar.hidden = true const refreshed = player.libraryBundle?.refreshed ?? [] - const downgraded = player.libraryBundle?.downgraded ?? [] + const downgraded = player.downgradedLibraries const libraries = (count) => (count === 1 ? 'one library' : `${count} libraries`) modeTag.textContent = (player.untrusted diff --git a/docs/api.md b/docs/api.md index 1f69e91c..7e407a8e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -18,7 +18,7 @@ meaning, and a new error `code` or `progress` phase can only be added. | `pack-base` | attribute | Where `pack` is: the folder of a copy of `@missing-elements/h5p-libraries`' `parts/` on your site. Default: jsDelivr, at the version this release pins | | `pack` | property | The `pack` export of `@missing-elements/h5p-libraries`, as a bundler emits it; wins over `pack-base`. Set before `src` | | `refresh-libraries` | attribute | `off` plays the libraries a package carries as exported, and `pack` only fills gaps. Default: the pack's newer versions play | -| `downgrade-libraries` | attribute | `off` refuses content made for a newer minor version of a library than any source has. Default: once every source has been tried for that version, the newest older minor of the same major plays it, reported in `libraryBundle.downgraded` and the console | +| `downgrade-libraries` | attribute | `off` refuses content made for a newer minor version of a library than any source has. Default: once every source has been tried for that version, the newest older minor of the same major plays it, reported in `downgradedLibraries` and the console | | `untrusted` | attribute, property | Plays a package you did not make as data: its own library folders are ignored and the libraries come from `libraries` (default `pack`), `content/` serves only H5P's own file types, and the frame's script policy names exact paths. Its content is checked against each library's `semantics.json`, as the H5P CMS plugins check it. A package that needs its own copy of a library is refused, with `missingLibraries.carried` set | | `allow-origins` | attribute | Extra origins for the frame's CSP, space separated | | `frame`, `copyright`, `export`, `icon`, `embed` | attribute | Show the H5P action bar and its buttons. `export` needs `download-url` or a package URL, `embed` needs `embed-code` | @@ -38,7 +38,8 @@ meaning, and a new error `code` or `progress` phase can only be added. | `pkgId`, `revision` | read-only | The loaded package's id and build fingerprint | | `source` | read-only | `{ type: 'range-http' \| 'chunked' \| 'file', size, … }` | | `metadata` | read-only | `h5p.json`'s metadata plus `mainLibrary` | -| `libraryBundle` | read-only | `{ url, origin, fromCache, refreshed?, downgraded? }` for what supplied libraries: for the pack, `refreshed` lists the libraries the package carries that played at the pack's version, `{ library, from, to }`; `downgraded` the libraries the content names at a newer minor than any source has, which played at an older one, `{ library, from, to }` with `from` the version named, such as `1.17`, and `to` the one played, such as `1.16.27` | +| `libraryBundle` | read-only | `{ url, origin, fromCache, refreshed? }` for what supplied libraries: for the pack, `refreshed` lists the libraries the package carries that played at the pack's version, `{ library, from, to }` | +| `downgradedLibraries` | read-only | The libraries the content names at a newer minor than any source has, which played at the newest older one (`downgrade-libraries`): `{ library, from, to }`, with `from` the version named, such as `1.17`, and `to` the one played, such as `1.16.27`. Empty when none did. The older version may be the package's own, with no `libraryBundle` | | `scope` | read-only | The Service Worker scope | ## Methods @@ -52,7 +53,7 @@ Events are `CustomEvent`s: | Event | `detail` | When | |---|---|---| -| `ready` | `{ pkgId, source, metadata, revision, libraryBundle }` | The content is visible | +| `ready` | `{ pkgId, source, metadata, revision, libraryBundle, downgradedLibraries }` | The content is visible | | `xapi` | `{ statement, verb }` | Any xAPI statement; nothing is stored | | `finished` | `{ statement }` | The content reported its result: a `completed` or `answered` statement from the content itself, not from a part inside it. That is H5P's own `setFinished` rule, except that a part created without a parent counts as a part too, which H5P's rule misses for Interactive Book's chapters and Game Map's exercises. It can come more than once, for a question checked again; the last is the result. Content that reports no result of its own never raises it, and Interactive Book reports one only with `reporting` | | `userdata` | `{ pkgId, dataType, subContentId, data, revision }` | With `resume`: the content saved its state; `data: null` means delete it | diff --git a/docs/libraries.md b/docs/libraries.md index 949d95eb..dabd927c 100644 --- a/docs/libraries.md +++ b/docs/libraries.md @@ -62,10 +62,10 @@ the pack's libraries, 119 came with an upgrade step, which is how H5P marks such the older code does not find what moved, and a part can be missing or drawn wrong. Played `untrusted`, the content is still checked against the older version's fields. -`libraryBundle.downgraded` and the `ready` event's detail list each library played older, -`{ library, from, to }`, and the console says so. `downgrade-libraries="off"` refuses such a -package instead, naming the version it needs. A package that carries the newer version itself -plays it, trusted, and needs none of this. +`downgradedLibraries`, on the element and in the `ready` event's detail, lists each library +played older, `{ library, from, to }`, and the console says so. `downgrade-libraries="off"` +refuses such a package instead, naming the version it needs. A package that carries the newer +version itself plays it, trusted, and needs none of this. ## On your own hosting diff --git a/docs/untrusted.md b/docs/untrusted.md index 42cfcb11..dd0dd28c 100644 --- a/docs/untrusted.md +++ b/docs/untrusted.md @@ -19,7 +19,7 @@ WordPress and Drupal treat an author's upload: | The content's fields | As written | Checked against each library's `semantics.json` | Checked the same way, on upload | | Scripts the frame allows | Your origin, and the hosts the runtime needs | Exact paths only | Whatever the site's own policy allows | | Media the content names by URL | Loads from that host | Loads from that host | Loads from that host | -| A package carrying a newer library than the site has | Plays with its own copy | Refused, with `missingLibraries.carried` set, so you can offer to play it as it is | Refused, unless the uploader may update libraries | +| A package carrying a newer library than the site has | Plays with its own copy | A newer minor plays at the site's older one. A newer major, or a newer minor with `downgrade-libraries="off"`, is refused with `missingLibraries.carried` set, so you can offer to play it as it is | Refused, unless the uploader may update libraries | Played as it is suits packages your own team made. `untrusted` is for everything else: uploads, links from users, a marketplace, exports from another site. @@ -72,8 +72,9 @@ that runs the check, 0.2 or later. An older runtime plays nothing. ## When a package is refused A package that needs a library your sources do not have is refused with `bad-archive`, naming the -missing libraries. Usually it is a library newer than the pack, which a later pack release will -carry. +missing libraries: a content type the pack does not serve, a newer major version than the pack's, +or, with `downgrade-libraries="off"`, a newer minor. Without that attribute a newer minor plays at +the pack's older one; see [Content newer than the pack](libraries.md#content-newer-than-the-pack). If the package carries that library itself, `missingLibraries.carried` is `true`. Playing it without `untrusted` would run the package's own copy. That is a decision for your site, so ask @@ -98,7 +99,8 @@ With or without `untrusted`: - **Entry names.** An entry whose name is not a plain relative path, such as `../index.html`, is rejected, and the rest of the package still plays. - **Libraries.** A package must carry, or get from `libraries`, every library it declares and every - library those depend on. Otherwise it is refused with the missing ones named, before the + library those depend on, at the minor version named or, unless `downgrade-libraries="off"`, an + older one of the same major. Otherwise it is refused with the missing ones named, before the content starts. ## What it does not cover diff --git a/docs/verify.md b/docs/verify.md index 0142920b..68199e92 100644 --- a/docs/verify.md +++ b/docs/verify.md @@ -15,9 +15,9 @@ content check removes from each field: markup, attributes and styles by name, fi With `--libraries pack`, or a copy of the pack's `parts/`, it plays a library the package carries at the pack's newer version, as a site with the pack will, and says which. Content made for a newer minor version than any source has plays at the newest older one, as the player does by -default, with a warning for each library; `--no-downgrade-libraries` fails it instead. It is meant as the last step of a pipeline that generates or -rewrites packages; the skill in `skills/h5p-verify/` tells an agent when to run it and how to -read the result. +default, with a warning for each library; `--no-downgrade-libraries` fails it instead. It is +meant as the last step of a pipeline that generates or rewrites packages; the skill in +`skills/h5p-verify/` tells an agent when to run it and how to read the result. The check cannot say whether the content is right; a person decides that by playing it. `--preview` checks nothing and opens the package in the real player in the person's own diff --git a/packages/embed/site/embed.js b/packages/embed/site/embed.js index 8cecda5a..0b2d027c 100644 --- a/packages/embed/site/embed.js +++ b/packages/embed/site/embed.js @@ -141,20 +141,23 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null, * What the player learnt about the package, for the embedding page to show: whether the host * streamed it or made the browser download it whole (`source.type`), how big it is, what it * says it is (`metadata`), where libraries it did not carry came from (`libraryBundle`, `null` - * when it carried its own), and how long it took here. Posted once, when the content is up: + * when it carried its own), which played at an older version than the content names + * (`downgradedLibraries`, empty when none did), and how long it took here. Posted once, when the + * content is up: * - * { context: 'h5p-offline-player', action: 'report', source, metadata, libraryBundle, elapsedMs } + * { context: 'h5p-offline-player', action: 'report', source, metadata, libraryBundle, + * downgradedLibraries, elapsedMs } * * and to any parent, like the heights: the parent named the package, and the manifest's strings * are the package's own to tell. A parent treats them as text. A load that fails before the * content is up posts `{ context: 'h5p-offline-player', action: 'error', code, message }` * instead, a refusal by this page included (`code: 'refused'`). The shapes are an interface: - * a site that checks packages builds its preview from them, so they do not change. + * a site that checks packages builds its preview from them, so a field is only ever added. */ let startedAt = 0 player.addEventListener('ready', (event) => { - const { source, metadata, libraryBundle } = /** @type {CustomEvent} */ (event).detail + const { source, metadata, libraryBundle, downgradedLibraries } = /** @type {CustomEvent} */ (event).detail post({ context: 'h5p-offline-player', action: 'report', @@ -167,6 +170,8 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null, mainLibrary: metadata.mainLibrary }, libraryBundle, + // Absent from an element older than the page's own; this page and the element ship together. + downgradedLibraries: downgradedLibraries ?? [], elapsedMs: Math.round(performance.now() - startedAt) }) }) @@ -312,12 +317,12 @@ export function startEmbed({ packBase = null, pack = null, librariesPack = null, * `&frame©right&export` shows H5P's action bar with those buttons, `&fullscreen=off` takes * that one away, `&refresh-libraries=off` plays a package's own libraries even where the pack * has newer ones, `&downgrade-libraries=off` refuses content made for a newer version of a - * library than any source has, `&activity-id=` names the statements' object and `&custom-css=` restyles the - * content to the embedding site's taste. `&lang=` is the embedding page's language, which this - * page cannot read across origins: H5P's own buttons and dialogs follow it for a package that - * does not name its own language, and follow the content's where it does. Not `custom-js`, - * `embed-code` or `user`: a script is a capability on this origin that a link should not hand - * out, the embed is the embed, and a learner's name has no place in a URL. + * library than any source has, `&activity-id=` names the statements' object and `&custom-css=` + * restyles the content to the embedding site's taste. `&lang=` is the embedding page's + * language, which this page cannot read across origins: H5P's own buttons and dialogs follow it + * for a package that does not name its own language, and follow the content's where it does. + * Not `custom-js`, `embed-code` or `user`: a script is a capability on this origin that a link + * should not hand out, the embed is the embed, and a learner's name has no place in a URL. */ const applyOptions = () => { for (const name of ['frame', 'copyright', 'export', 'icon', 'reporting']) { diff --git a/packages/embed/tests/site.test.ts b/packages/embed/tests/site.test.ts index 03df89f1..58e691d6 100644 --- a/packages/embed/tests/site.test.ts +++ b/packages/embed/tests/site.test.ts @@ -389,7 +389,7 @@ describe('a written site, framed from another site', () => { expect(await untrusted(page)).toBe(true) expect(await page.evaluate(() => document.querySelector('#notice button'))).toBeNull() const downgraded = await page.evaluate( - () => (document.querySelector('h5p-player') as unknown as { libraryBundle: { downgraded?: { library: string; from: string; to: string }[] } }).libraryBundle.downgraded + () => (document.querySelector('h5p-player') as unknown as { downgradedLibraries: { library: string; from: string; to: string }[] }).downgradedLibraries ) expect(downgraded).toEqual([{ library: 'H5P.QuestionSet', from: '1.99', to: expect.stringMatching(/^1\.21\./) }]) await page.close() diff --git a/packages/player/scripts/build-fixtures.mjs b/packages/player/scripts/build-fixtures.mjs index f2de8142..f65cd720 100644 --- a/packages/player/scripts/build-fixtures.mjs +++ b/packages/player/scripts/build-fixtures.mjs @@ -395,6 +395,19 @@ built.push([ }) ]) +// 6a'''. One whose `h5p.json` names a newer minor of the content type than the folder it carries, +// as an export whose manifest and folders disagree: nothing has 1.1, so its own 1.0 plays +// it, with no library bundle attached, or it is refused with `downgrade-libraries="off"`. +built.push([ + 'older-own.h5p', + await writeArchive('older-own.h5p', async (writer) => { + const manifest = JSON.parse(await readFile(resolve(sourceDir, 'h5p.json'), 'utf8')) + manifest.preloadedDependencies = [{ machineName: 'H5P.OfflineTest', majorVersion: 1, minorVersion: 1 }] + await writer.add('h5p.json', new TextReader(JSON.stringify(manifest))) + await addBaseFiles(writer, { skip: ['h5p.json'] }) + }) +]) + // 6a''. Content to check against the content type's semantics, played with the bundle: markup a // field does not allow — a script, a handler, a form asking for a password — a scheme off // the list, a field the semantics do not name, and the same in sub-content. Played trusted, diff --git a/packages/player/scripts/lib/fixture-names.mjs b/packages/player/scripts/lib/fixture-names.mjs index cd53cd8e..0028fcf6 100644 --- a/packages/player/scripts/lib/fixture-names.mjs +++ b/packages/player/scripts/lib/fixture-names.mjs @@ -23,6 +23,7 @@ export const GENERATED_FIXTURES = [ 'libraries.h5p', 'untrusted.h5p', 'untrusted-newer.h5p', + 'older-own.h5p', 'needs-dependency.h5p', 'untrusted-markup.h5p', 'libraries-without-semantics.h5p', diff --git a/packages/player/src/h5p-offline-player.ts b/packages/player/src/h5p-offline-player.ts index 5da0a456..73d0e2f7 100644 --- a/packages/player/src/h5p-offline-player.ts +++ b/packages/player/src/h5p-offline-player.ts @@ -189,16 +189,13 @@ export type PackageSource = SourceDescriptor * copy downloaded earlier rather than fetched now. `fromCache` is what a page needs for "nothing * left this origin": a bundle on the page's own origin, or one served from cache, meant no * request to a third party. `refreshed`, for the pack: the libraries the package carries that - * played at the pack's newer version. `downgraded`: the libraries the content names at a newer - * minor than any source has, which played at the newest older one (`downgrade-libraries`); absent - * when none did. + * played at the pack's newer version. */ export interface LibraryBundle { url: string origin: string fromCache: boolean refreshed?: RefreshedLibrary[] - downgraded?: DowngradedLibrary[] } export type { DowngradedLibrary, RefreshedLibrary } from './shared/protocol.js' @@ -228,6 +225,7 @@ export interface ReadyDetail { metadata: PackageMetadata | null revision: string | null libraryBundle: LibraryBundle | null + downgradedLibraries: DowngradedLibrary[] } export interface PlayerErrorDetail { @@ -333,6 +331,8 @@ export class H5PPlayerElement extends HTMLElement { private internalMetadata: PackageMetadata | null = null /** The bundle that supplied the libraries, once one has. See `libraryBundle`. */ private internalLibraryBundle: LibraryBundle | null = null + /** What played at an older minor than the content names, once the index has said. See `downgradedLibraries`. */ + private internalDowngraded: DowngradedLibrary[] = [] private heldStatements: HeldStatement[] = [] /** * The package this element played before the current load, and its revision. Emptying the @@ -541,6 +541,16 @@ export class H5PPlayerElement extends HTMLElement { return this.internalLibraryBundle ? { ...this.internalLibraryBundle } : null } + /** + * The libraries the content names at a newer minor than any source has, which played at the + * newest older one of the same major (`downgrade-libraries`): `{ library, from, to }`, empty when + * none did. The load's, not the bundle's: the older version may be the package's own, with no + * bundle attached at all. + */ + get downgradedLibraries(): DowngradedLibrary[] { + return this.internalDowngraded.map((library) => ({ ...library })) + } + /** The resolved Service Worker scope the routes live under. Read-only, `null` until registered. */ get scope(): string | null { return this.routes?.base ?? null @@ -680,6 +690,7 @@ export class H5PPlayerElement extends HTMLElement { this.internalRevision = null this.internalMetadata = null this.internalLibraryBundle = null + this.internalDowngraded = [] this.currentSource = null } @@ -889,6 +900,8 @@ export class H5PPlayerElement extends HTMLElement { let next = fill ? 1 : 0 let packFailure: unknown = null let rounds = 0 + // Read once, as `refresh` is: the attribute takes effect on the next load, not halfway through. + const mayDowngrade = this.downgradesLibraries let downgrade = false for (;;) { @@ -930,7 +943,7 @@ export class H5PPlayerElement extends HTMLElement { continue } if (!source) { - if (!downgrade && this.downgradesLibraries) { + if (!downgrade && mayDowngrade) { downgrade = true // Kept with the load's settings, so a worker started again serves the same folders. await this.send({ type: 'attach-libraries', ...load, downgrade: true }) @@ -969,12 +982,13 @@ export class H5PPlayerElement extends HTMLElement { } /** - * What played at an older minor than the content names, onto `libraryBundle` and the console: - * the content was made for a version no source has, and what that version added is left out. + * What played at an older minor than the content names, onto `downgradedLibraries` and the + * console: the content was made for a version no source has, and what that version added is + * left out. */ private reportDowngrades(downgraded: DowngradedLibrary[] | undefined): void { if (!downgraded?.length) return - if (this.internalLibraryBundle) this.internalLibraryBundle = { ...this.internalLibraryBundle, downgraded } + this.internalDowngraded = downgraded console.warn( `[h5p-player] played at an older version than the content names, since no library source has it: ` + `${downgraded.map(({ library, from, to }) => `${library} ${from} → ${to}`).join(', ')}. ` + @@ -1718,7 +1732,8 @@ export class H5PPlayerElement extends HTMLElement { source: this.source, metadata: this.metadata, revision: this.internalRevision, - libraryBundle: this.libraryBundle + libraryBundle: this.libraryBundle, + downgradedLibraries: this.downgradedLibraries } }) ) diff --git a/packages/player/tests/browser/libraries.test.ts b/packages/player/tests/browser/libraries.test.ts index bb068204..7dfc563f 100644 --- a/packages/player/tests/browser/libraries.test.ts +++ b/packages/player/tests/browser/libraries.test.ts @@ -1,5 +1,6 @@ import { afterEach, describe, expect, it } from 'vitest' import '../../src/h5p-offline-player' +import type { ReadyDetail } from '../../src/h5p-offline-player' import { FIXTURES, clearPackageCaches, createPlayer, frameFetch, frameWindow, messageOf, play, settle, virtualUrl, waitForSettled } from './utils' /** @@ -108,6 +109,31 @@ describe('supplying missing libraries', () => { } }) + it("plays a package at its own older minor where nothing has the one it names, and says so with no bundle attached (#85)", async () => { + // Its h5p.json names the content type at 1.1 and its folder is 1.0, as an export whose manifest + // and folders disagree. Nothing supplied anything, so `libraryBundle` stays null: the list is + // the load's. It once rode on the bundle, and such a package played with only the console + // saying so, and passed the verifier without a warning where it had failed before. On a host + // without Range the frame waits for the whole download, since a partial index never downgrades. + for (const src of [`${FIXTURES.olderOwn}?case=own`, `/no-range/older-own.h5p?case=own-${Date.now()}`]) { + let detail: ReadyDetail | undefined + const { player, result } = await settle(src, {}, (element) => + element.addEventListener('ready', (event) => (detail = (event as CustomEvent).detail)) + ) + if (!result.ok) expect.fail(`${src}: ${result.detail.code} — ${result.detail.message}`) + expect(messageOf(player), src).toBe('Served from the archive, never extracted to disk.') + expect(player.libraryBundle, src).toBeNull() + expect(player.downgradedLibraries, src).toEqual([{ library: 'H5P.OfflineTest', from: '1.1', to: '1.0.0' }]) + expect(detail?.downgradedLibraries, src).toEqual(player.downgradedLibraries) + } + }) + + it('refuses that package with downgrade-libraries="off", naming the version it names', async () => { + const { result } = await settle(`${FIXTURES.olderOwn}?case=own-off`, { 'downgrade-libraries': 'off' }) + if (result.ok) expect.fail('expected the package to be refused') + expect(result.detail).toMatchObject({ code: 'bad-archive', missingLibraries: { folders: ['H5P.OfflineTest-1.1'] } }) + }) + it("supplies a library's own dependency from the bundle, on a host with Range and on one without", async () => { for (const src of [FIXTURES.needsDependency, FIXTURES.needsDependencyNoRange, pacedNoRange('supplied')]) { const player = await playWithLibraries(src, FIXTURES.libraries) diff --git a/packages/player/tests/browser/pack.test.ts b/packages/player/tests/browser/pack.test.ts index 0cd45143..1102ded7 100644 --- a/packages/player/tests/browser/pack.test.ts +++ b/packages/player/tests/browser/pack.test.ts @@ -101,7 +101,7 @@ describe('the library pack, split into parts', () => { expect(messageOf(player)).toBe('Written for 1.3') expect(frameWindow(player).document.querySelector('.h5p-offline-child-text')?.textContent).toBe('Child written for 1.2') expect((await loadOf(player)).parts).toEqual(['H5P.OfflineChild-1.1.h5p', 'H5P.OfflineTest-1.2.h5p']) - expect(player.libraryBundle?.downgraded).toEqual([ + expect(player.downgradedLibraries).toEqual([ { library: 'H5P.OfflineChild', from: '1.2', to: '1.1.0' }, { library: 'H5P.OfflineTest', from: '1.3', to: '1.2.0' } ]) @@ -123,7 +123,7 @@ describe('the library pack, split into parts', () => { expect(messageOf(player)).toBe('Written for 1.2') expect(frameWindow(player).document.querySelector('.h5p-offline-child-text')?.textContent).toBe('Child written for 1.2') expect((await loadOf(player)).parts).toEqual(['H5P.OfflineChild-1.1.h5p', 'H5P.OfflineTest-1.2.h5p']) - expect(player.libraryBundle?.downgraded).toEqual([{ library: 'H5P.OfflineChild', from: '1.2', to: '1.1.0' }]) + expect(player.downgradedLibraries).toEqual([{ library: 'H5P.OfflineChild', from: '1.2', to: '1.1.0' }]) }) it('refuses that sub-content by name with downgrade-libraries="off", rather than booting without its library', async () => { @@ -138,7 +138,7 @@ describe('the library pack, split into parts', () => { const player = await play(fresh(FIXTURES.writtenFor12, 'order'), { libraries: `${FIXTURES.libraries} pack`, 'pack-base': PACK }) expect(messageOf(player)).toBe('Written for 1.2') - expect(player.libraryBundle?.downgraded).toBeUndefined() + expect(player.downgradedLibraries).toEqual([]) expect((await loadOf(player)).parts).toEqual(['H5P.OfflineChild-1.1.h5p', 'H5P.OfflineTest-1.2.h5p']) }) diff --git a/packages/player/tests/browser/untrusted.test.ts b/packages/player/tests/browser/untrusted.test.ts index bbfd8c75..29c1aa18 100644 --- a/packages/player/tests/browser/untrusted.test.ts +++ b/packages/player/tests/browser/untrusted.test.ts @@ -149,7 +149,7 @@ describe('an untrusted package', () => { const { player, result } = await playUntrusted(FIXTURES.untrustedNewer) if (!result.ok) expect.fail(`${result.detail.code} — ${result.detail.message}`) expect(message(player)).toBe('Served from the archive, never extracted to disk.') - expect(player.libraryBundle?.downgraded).toEqual([{ library: 'H5P.OfflineTest', from: '1.3', to: '1.0.0' }]) + expect(player.downgradedLibraries).toEqual([{ library: 'H5P.OfflineTest', from: '1.3', to: '1.0.0' }]) }) it('refuses it with downgrade-libraries="off", and says its own copy would play it', async () => { diff --git a/packages/player/tests/browser/utils.ts b/packages/player/tests/browser/utils.ts index 04cdc867..b1c09778 100644 --- a/packages/player/tests/browser/utils.ts +++ b/packages/player/tests/browser/utils.ts @@ -58,6 +58,8 @@ export const FIXTURES = { librariesWithoutSemantics: '/fixtures/libraries-without-semantics.h5p', /** Needs the content type at 1.3, which only it carries. */ untrustedNewer: '/fixtures/untrusted-newer.h5p', + /** Names the content type at 1.1 and carries it at 1.0, which nothing else has newer. */ + olderOwn: '/fixtures/older-own.h5p', /** The fixture content type at 1.2 and a sub-content type at 1.1, each with an `upgrades.js`. */ upgradeLibraries: '/fixtures/upgrade-libraries.h5p', /** Stripped exports written for 1.0 (with sub-content at 1.0), 1.1 and 1.2, and one whose first step throws. */ diff --git a/packages/verify/lib/verify.mjs b/packages/verify/lib/verify.mjs index ba8ddd95..4549dd80 100644 --- a/packages/verify/lib/verify.mjs +++ b/packages/verify/lib/verify.mjs @@ -216,7 +216,8 @@ export async function verifyPackage(options) { state: player.state, revision: player.revision, untrusted: player.untrusted === true, - libraryBundle: player.libraryBundle + libraryBundle: player.libraryBundle, + downgradedLibraries: player.downgradedLibraries } }) const frame = page.frames().find((candidate) => candidate.url().includes('/h5p/frame/')) @@ -276,7 +277,8 @@ export async function verifyPackage(options) { refreshed: collected.libraryBundle?.refreshed ?? [], // Made for a newer minor than any source has, and played at an older one: what the newer // version added is left out, which only a person playing it can judge. - downgraded: collected.libraryBundle?.downgraded ?? [], + // The load's, not the bundle's: a package that carries an older minor itself has no bundle. + downgraded: collected.downgradedLibraries ?? [], verdict: 'pass', reasons: [], warnings: [], diff --git a/packages/verify/tests/verify.test.ts b/packages/verify/tests/verify.test.ts index 6fd53e25..2cd31c2d 100644 --- a/packages/verify/tests/verify.test.ts +++ b/packages/verify/tests/verify.test.ts @@ -99,6 +99,21 @@ const quizNeedingNewerLibrary = () => await writer.add(folder ? entry.filename.replace(folder[0], 'H5P.QuestionSet-1.99/') : entry.filename, new Uint8ArrayReader(bytes)) }) +/** + * The quiz whose `h5p.json` names Question Set 1.99 while its folder stays at the version it was + * built with, as an export whose manifest and folders disagree: nothing has 1.99, and its own + * older copy plays it, with no library source attached. + */ +const quizNamingNewerThanItCarries = () => + rewrittenQuiz('names-newer.h5p', async (entry, bytes, writer) => { + if (entry.filename === 'h5p.json') { + const json = JSON.parse(new TextDecoder().decode(bytes)) + for (const dependency of json.preloadedDependencies) if (dependency.machineName === 'H5P.QuestionSet') dependency.minorVersion = 99 + bytes = new TextEncoder().encode(JSON.stringify(json)) + } + await writer.add(entry.filename, new Uint8ArrayReader(bytes)) + }) + /** The quiz built against an older patch of Question Set than the pack has: its own `library.json` says patch 0. */ const quizWithOlderPatch = () => rewrittenQuiz('older-patch.h5p', async (entry, bytes, writer) => { @@ -239,6 +254,16 @@ describe('h5p-verify', () => { expect(summarize(report)).toContain('warning: H5P.QuestionSet played at 1.21.') }, 120_000) + it('played trusted with no library source, warns of a library played at the older minor the package carries (#85)', async () => { + // Nothing supplied anything, so there is no library bundle. The report took the list from it + // once, and this passed with no warning, where before the fallback it failed naming 1.99. + const report = await verifyPackage({ file: await quizNamingNewerThanItCarries() }) + + expect(report.verdict).toBe('pass') + expect(report.downgraded).toEqual([{ library: 'H5P.QuestionSet', from: '1.99', to: expect.stringMatching(/^1\.\d+\.\d+$/) }]) + expect(report.warnings.some((warning) => warning.startsWith('H5P.QuestionSet played at 1.') && warning.includes('1.99'))).toBe(true) + }, 120_000) + it('played untrusted with --no-downgrade-libraries, refuses a package that needs its own copy of a library, and says what to do', async () => { const report = await verifyPackage({ file: await quizNeedingNewerLibrary(), untrusted: true, libraries: pack, downgradeLibraries: false }) diff --git a/packages/vscode/src/page.mjs b/packages/vscode/src/page.mjs index bcba8794..0b423b43 100644 --- a/packages/vscode/src/page.mjs +++ b/packages/vscode/src/page.mjs @@ -49,13 +49,15 @@ export function viewPage(settings) { player.addEventListener('statechange', (event) => tell({ type: 'state', state: event.detail.state })) player.addEventListener('ready', (event) => { - const { metadata, libraryBundle } = event.detail + const { metadata, libraryBundle, downgradedLibraries } = event.detail tell({ type: 'ready', title: (metadata && metadata.title) || null, mainLibrary: (metadata && metadata.mainLibrary) || null, license: metadata && metadata.license ? [metadata.license, metadata.licenseVersion].filter(Boolean).join(' ') : null, refreshed: (libraryBundle && libraryBundle.refreshed) || [], + // Made for a newer version than the pack the extension carries, and played at an older one. + downgraded: downgradedLibraries || [], // The attribute, which is what the element plays by. untrusted: player.hasAttribute('untrusted') }) diff --git a/packages/vscode/src/webview.mjs b/packages/vscode/src/webview.mjs index bd7c6c2b..5055acdb 100644 --- a/packages/vscode/src/webview.mjs +++ b/packages/vscode/src/webview.mjs @@ -116,15 +116,19 @@ export function webviewHtml({ nonce, config }) { const name = document.createElement('strong') name.textContent = message.title || config.name const parts = [message.mainLibrary, message.license, message.untrusted ? 'untrusted' : null] - if (message.refreshed.length > 0) { - parts.push((message.refreshed.length === 1 ? 'one library' : message.refreshed.length + ' libraries') + " at the pack's newer version") - } + const libraries = (count) => (count === 1 ? 'one library' : count + ' libraries') + const downgraded = message.downgraded || [] + if (message.refreshed.length > 0) parts.push(libraries(message.refreshed.length) + " at the pack's newer version") + if (downgraded.length > 0) parts.push(libraries(downgraded.length) + ' older than the content') const detail = document.createElement('span') detail.className = 'detail' detail.textContent = parts.filter(Boolean).map((part) => ' · ' + part).join('') status.className = '' status.replaceChildren(name, detail) - status.title = message.refreshed.map((library) => library.library + ' ' + library.from + ' → ' + library.to).join('\\n') + status.title = [ + ...message.refreshed.map((library) => library.library + ' ' + library.from + ' → ' + library.to), + ...downgraded.map((library) => library.library + ' made for ' + library.from + ', played at ' + library.to) + ].join('\\n') } function showError(message) { diff --git a/packages/vscode/tests/html.test.ts b/packages/vscode/tests/html.test.ts index 0189f67f..31d32ef6 100644 --- a/packages/vscode/tests/html.test.ts +++ b/packages/vscode/tests/html.test.ts @@ -167,6 +167,15 @@ describe('the webview', () => { expect((status.children[0] as StandIn).textContent).toBe('Quiz') }) + it('says in the bar how many libraries played older than the content, and which in its tooltip', () => { + const { receive, fromPage, status } = runWebview() + const refreshed = [{ library: 'H5P.Question', from: '1.5.9', to: '1.5.12' }] + const downgraded = [{ library: 'H5P.MultiChoice', from: '1.17', to: '1.16.27' }] + receive({ source: 'h5p-preview', type: 'ready', title: 'Quiz', mainLibrary: 'H5P.QuestionSet', license: null, refreshed, downgraded, untrusted: false }, fromPage) + expect((status.children[1] as StandIn).textContent).toBe(" · H5P.QuestionSet · one library at the pack's newer version · one library older than the content") + expect(status.title).toBe('H5P.Question 1.5.9 → 1.5.12\nH5P.MultiChoice made for 1.17, played at 1.16.27') + }) + it('takes the page’s messages from the server’s origin only', () => { const { posted, receive, frame } = runWebview() posted.length = 0 @@ -215,9 +224,13 @@ describe('the page a preview frames', () => { it('tells what the element reached to the webview around it, and to no other window', () => { const { player, told } = runPage({ untrusted: true }) const ready = player.listeners.get('ready') as Listener - ready({ detail: { metadata: { title: 'Quiz', mainLibrary: 'H5P.QuestionSet', license: 'CC BY', licenseVersion: '4.0' }, libraryBundle: { refreshed: [] } } }) + const downgradedLibraries = [{ library: 'H5P.MultiChoice', from: '1.17', to: '1.16.27' }] + ready({ detail: { metadata: { title: 'Quiz', mainLibrary: 'H5P.QuestionSet', license: 'CC BY', licenseVersion: '4.0' }, libraryBundle: { refreshed: [] }, downgradedLibraries } }) expect(told).toEqual([ - [{ source: 'h5p-preview', type: 'ready', title: 'Quiz', mainLibrary: 'H5P.QuestionSet', license: 'CC BY 4.0', refreshed: [], untrusted: true }, WEBVIEW_ORIGIN] + [ + { source: 'h5p-preview', type: 'ready', title: 'Quiz', mainLibrary: 'H5P.QuestionSet', license: 'CC BY 4.0', refreshed: [], downgraded: downgradedLibraries, untrusted: true }, + WEBVIEW_ORIGIN + ] ]) const alone = runPage({}, [])