diff --git a/AGENTS.md b/AGENTS.md index 59b36167..31b0df4a 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,59 @@ 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 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. + 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 +2098,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 +3150,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..6b8b5e86 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.downgradedLibraries + 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..7e407a8e 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 `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,6 +39,7 @@ meaning, and a new error `code` or `progress` phase can only be added. | `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 }` | +| `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 @@ -51,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/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..dabd927c 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. + +`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 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/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 5de534a2..68199e92 100644 --- a/docs/verify.md +++ b/docs/verify.md @@ -13,9 +13,11 @@ 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 -rewrites packages; the skill in `skills/h5p-verify/` tells an agent when to run it and how to -read the result. +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. 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/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..0b2d027c 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=] * @@ -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) }) }) @@ -311,12 +316,13 @@ 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 - * 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. + * 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. */ const applyOptions = () => { for (const name of ['frame', 'copyright', 'export', 'icon', 'reporting']) { @@ -326,6 +332,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..58e691d6 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 { 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() + }) + + 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..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, @@ -481,7 +494,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..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', @@ -31,6 +32,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..73d0e2f7 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, @@ -197,7 +198,7 @@ export interface LibraryBundle { refreshed?: RefreshedLibrary[] } -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 { @@ -224,6 +225,7 @@ export interface ReadyDetail { metadata: PackageMetadata | null revision: string | null libraryBundle: LibraryBundle | null + downgradedLibraries: DowngradedLibrary[] } export interface PlayerErrorDetail { @@ -296,9 +298,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'] @@ -329,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 @@ -537,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 @@ -676,6 +690,7 @@ export class H5PPlayerElement extends HTMLElement { this.internalRevision = null this.internalMetadata = null this.internalLibraryBundle = null + this.internalDowngraded = [] this.currentSource = null } @@ -750,6 +765,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 +886,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 +900,16 @@ 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 (;;) { 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 +943,13 @@ export class H5PPlayerElement extends HTMLElement { continue } if (!source) { + 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 }) + if (signal.aborted) return nothingIndexed() + continue + } if (!packFailure) throw error const reason = packFailure instanceof Error ? packFailure.message : String(packFailure) throw new PlayerError( @@ -945,6 +976,26 @@ 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 `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 + 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(', ')}. ` + + '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 +1007,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 } } /** @@ -1677,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 } }) ) @@ -1958,6 +2014,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 +2042,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/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 a3f10a04..1102ded7 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.downgradedLibraries).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.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 () => { + 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.downgradedLibraries).toEqual([]) + 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..29c1aa18 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.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 () => { + 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..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. */ @@ -65,6 +67,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..4549dd80 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) @@ -211,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/')) @@ -269,6 +275,10 @@ 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. + // 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: [], @@ -307,6 +317,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..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) => { @@ -230,9 +245,28 @@ 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 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 }) + expect(report.verdict).toBe('fail') expect(report.errors[0]?.missingLibraries?.carried).toBe(true) expect(report.errors[0]?.missingLibraries?.folders).toContain('H5P.QuestionSet-1.99') 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({}, [])