Repository navigation
fix(admin): stop offering deprecated and known-broken plugins (#8246) - #8250
Conversation
The admin "Available plugins" list was built straight from
`${updateServer}/plugins.json` with no filter, so every package the feed
knows about was installable from the admin UI — including packages that
are known not to work with the running Etherpad. The reported case is
`ep_adminpads2`: archived upstream, superseded by core's own Manage pads
page, and installing it breaks the admin UI because it registers
/admin/pads ahead of the core route and its template pulls scripts core
no longer ships.
The feed itself carries no deprecation data. It does carry a
`compatibility` verdict per plugin (`compatible` / `warning` / `failed`)
that core ignored until now. So three signals are combined, cheapest
first, in a new pure module `pluginCatalogFilter.ts`:
1. feed `compatibility === 'failed'` — the plugin registry could not
get the plugin working against current Etherpad;
2. a short, documented list of superseded packages that install
cleanly and then break a working install (currently only
ep_adminpads2) — entries are meant to be retired once the package
is deprecated on npm;
3. `deprecated` on the published npm version metadata.
Signal 3 needs a registry lookup, so it is cached by name@version for
12 hours, runs 8 at a time behind a 15s overall budget, and is
fail-open: a package whose lookup fails (offline, npm firewalled, 404,
timeout) is listed, not hidden. Emptying the admin catalog because npm
was unreachable would be a worse bug than the one this fixes. The
install-time preflight already fetched the same npm document for
`engines.node`, so it now reads `deprecated` from it at no extra cost
and logs a warning; it does not block the install, because that same
code path serves the admin UI's "update plugin" button.
Hiding a plugin only stops new installs, so an already-installed plugin
that is deprecated or superseded is flagged with a "Deprecated" badge in
the Installed plugins list, with the upstream reason in its tooltip.
Core (ep_etherpad-lite) is never looked up or flagged.
Covered by backend specs for the decision table, the end-to-end catalog
path with a stubbed registry (deprecated excluded, healthy still listed,
registry failure still lists), and an admin Playwright spec that asserts
ep_adminpads2 is not offered while ep_align still is.
Fixes #8246
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013S4pYSjwUsiZtdtMMpW7bw
|
ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing |
PR Summary by QodoFilter deprecated and known-broken plugins from admin catalog
AI Description
Diagram
High-Level Assessment
Files changed (16)
|
Code Review by Qodo
1.
|
Addresses the three findings from the Qodo review of #8250. 1. Refuse the install, not just the listing. Hiding a package from the catalog does not stop a stale admin page, an older client or a replayed socket event from asking the server to install it, so install() now applies the same policy: superseded packages are refused before any network call (so the block holds offline), and a package npm marks deprecated is refused after the preflight document it already fetches. An unreachable registry still lets the install proceed, and `pnpm run plugins i ep_<name>` goes through LinkInstaller directly, so an operator on the server can override. New error code PLUGIN_DEPRECATED, mapped to a localized toast. 2. Don't sweep npm twice on page load. The admin page emits `getInstalled` (which checks for updates) and `search` together, and both land in getAvailablePlugins(); on a cold cache each one fetched the feed and looked up every listed plugin. Concurrent callers now share one in-flight refresh, and individual deprecation lookups share one in-flight request per name@version. The shared promise is cleared on failure too, so a transient feed outage does not pin later callers to a rejected promise. 3. Don't leave a stale badge on an installed plugin. `getInstalled` wrote per-response status onto the live package objects held in pluginDefs.plugins, so a `deprecated` reason survived npm un-deprecating the package, a failed lookup, or the catalog being turned off. It now emits shallow copies and always assigns both status fields. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013S4pYSjwUsiZtdtMMpW7bw
CodeQL flags `url.includes('npmjs.org')` in the catalog spec as
incomplete URL sanitization (js/incomplete-url-substring-sanitization).
It is test-only routing, but the prefix match is both stricter and
clearer, so use it for the stub router and the call assertion.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013S4pYSjwUsiZtdtMMpW7bw
Fixes #8246
What the feed actually provides
I fetched
https://static.etherpad.org/plugins.jsonand inspected it before writing anything. Every one of the 174 entries has exactly these keys:{"name": "ep_adminpads2", "description": "...", "time": "2025-01-06", "version": "2.1.110", "official": true, "downloads": 655, "compatibility": "compatible"}compatibilityverdict —compatible(162),failed(10),warning(2) — produced by the registry's own compatibility run. Core ignored it completely until now. This is the second half of the issue's suggestion ("let the plugin feed carry a compatibility range") already available, with no feed change needed.registry.npmjs.org/<name>/latestfor all 174 packages: zero are deprecated today. Notablyep_adminpads2is not npm-deprecated either — it is archived on GitHub only. (ep_readonly_guestis deprecated on npm, and is already absent from the feed.)So a deprecation-only filter, which is what the issue suggests, would be correct and future-proof but would not fix the reported case. That is why this PR combines three signals.
The fix
New pure module
src/static/js/pluginfw/pluginCatalogFilter.tsdecides, per entry, whether the catalog may offer it — cheapest signal first:compatibility === 'failed'→ not offered (warningstill is);supersededPlugins, a short hand-maintained map of packages that install cleanly and then break a working Etherpad. One entry today:ep_adminpads2, with the reason inline. Entries are explicitly meant to be retired once the package is deprecated on npm;deprecatedon the published npm version metadata, looked up byinstaller.tsand passed in.getAvailablePlugins()applies it after normalising the feed, sosearch,getAvailableand the "update available" check all inherit it.Failure behaviour (point 3 of the brief): fail open, deliberately. The npm sweep is cached by
name@versionfor 12 h, runs 8 requests at a time behind a single 15 s budget, and any package whose lookup fails — offline, npm firewalled, 404, timeout, budget exhausted — is listed, not hidden, with a log line. If the whole sweep throws, the feed-only signals still apply and everything else stays listed. An admin behind a firewall must get a working catalog, not an empty one; that would be a worse bug than the one being fixed. A plugin-feed failure still propagates as before (the admin UI shows its error) rather than silently rendering an empty catalog.Install path: hiding a package from the listing does not stop a stale admin page, an older client or a replayed socket event from asking the server to install it, so
install()applies the same policy. A superseded package is refused before any network call, so the block holds with npm unreachable; a package npm marks deprecated is refused from the preflight document the install already fetched forengines.node, i.e. no extra request. New error codePLUGIN_DEPRECATEDwith a localized toast. Fail-open still holds: if the registry cannot be reached the install proceeds, andpnpm run plugins i ep_<name>on the server goes through LinkInstaller directly, so an operator keeps an override. (Deprecated plugins are also never reported as updatable, so this cannot hijack the "update plugin" button.)Concurrency: the admin page emits
getInstalledandsearchtogether, and both reachgetAvailablePlugins(). Concurrent callers share one in-flight refresh, and individual deprecation lookups share one in-flight request pername@version, so a cold load costs one feed fetch and one npm lookup per listed plugin — not two of each. The shared promise is cleared on failure, so a transient feed outage does not pin later callers to a rejected promise.Installed plugins (point 4): hiding a plugin only stops new installs, so
getInstallednow flags an already-installed deprecated/superseded plugin and the UI renders a localizedDEPRECATEDbadge next to the version, with the upstream reason in the tooltip.getInstalledemits shallow copies rather than writing that status onto the live package objects inpluginDefs.plugins, so a badge cannot outlive its cause. Core (ep_etherpad-lite) is never looked up or flagged. New i18n keysadmin_plugins.tag_deprecated,admin_plugins.deprecated_titleandadmin_plugins.install_error_deprecated(en + qqq).Effect on the live catalog today
163 of 174 entries are still listed. The 11 hidden:
ep_adminpads2(superseded) plus the 10 the registry already marksfailed—ep_back_button2,ep_content_title,ep_inline_toolbar_pro,ep_kaput,ep_mention,ep_mention_plugin,ep_mypads,ep_no_console,ep_script_elements,ep_script_page_view. Judgement call worth a second opinion:ep_mypadsis in that list. Its npm build (2.0.1) does not support Etherpad 3.x, and Framasoft ships from framagit rather than npm, so hiding the npm build looks right — but say the word and I will restrict signal 1 or drop it.Tests
src/tests/backend/specs/pluginCatalogFilter.ts— 19 cases pinning the decision table and the install-block policy, including "unknown deprecation state keeps the plugin",warningstays listed, and a missingcompatibilityfield is not evidence of breakage.src/tests/backend/specs/pluginCatalog.ts— 16 cases drivinggetAvailablePlugins()andinstall()withglobal.fetchstubbed: deprecated excluded / healthy still listed,ep_adminpads2excluded, registry unreachable → full catalog still listed, npm 404 → still listed, feed 503 → still throws, one feed fetch + one npm lookup per plugin across two concurrent callers, a failed refresh does not stick, cache hit does not re-query, a failed lookup is not cached, install refused for superseded (with zero network calls) and for npm-deprecated.src/tests/frontend-new/admin-spec/admin_plugin_catalog.spec.ts— chromium-admin: the catalog does not offerep_adminpads2, and still offersep_align.Evidence: with the filter stubbed back out to pre-fix behaviour, 5 of the
pluginCatalog.tscases fail; with the fix, 35/35 pass across the two specs. Full backend suite1735 passing, 0 failing; vitest840 passed;pnpm run ts-checkclean;admintscclean.Real-UI verification
Server on :9160 with the built admin bundle, driven with Playwright:
The committed admin spec passes against that instance (2 passed), and so does the existing
adminupdateplugins.spec.tsinstall/uninstall flow (3 passed) — a normal plugin still installs from the admin UI with the new install-time check in place.Follow-up for a maintainer
The durable fix for
ep_adminpads2isnpm deprecate ep_adminpads2 "archived; Etherpad's built-in Manage pads page replaces it"— signal 3 then catches it everywhere and thesupersededPluginsentry can be deleted. I did not touch npm; that needs publish rights and your call.Docs updated:
PRIVACY.md(the npm registry lookups are now documented as a third outbound call, with how to switch them off),doc/plugins.md+doc/plugins.adoc,CHANGELOG.md.🤖 Generated with Claude Code
https://claude.ai/code/session_013S4pYSjwUsiZtdtMMpW7bw