Skip to content

fix(plugins): refuse a plugin update that another install overtook during its download - #4509

Merged
Quick104 merged 3 commits into
Silo-Server:mainfrom
Rhainland:fix/4352-plugin-replace-version-guard
Nov 18, 2026
Merged

Quick104 merged 3 commits into
Silo-Server:mainfrom
Rhainland:fix/4352-plugin-replace-version-guard

Conversation

@Rhainland

@Rhainland Rhainland commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Closes #4352
Related issue: N/A
Validation tasks: changes #1224 C1; changes #1225 C1 (only when two installs or updates of one plugin overlap; a single install or update behaves as before)

Other clients: Apple N/A (no plugin administration); Android N/A (no plugin administration); Roku N/A (no plugin administration)

When an automatic plugin update was still downloading and an admin installed a newer release of the same plugin, the automatic update won once its download finished. It stopped the newer plugin, wrote its older package, stored archive and version over the installation, and left the newer release's files on disk. The admin's install had reported success, and the plugin ran the older release afterwards. Two manual installs, updates or uploads of one plugin could race the same way.

With this change, an install, update or upload only replaces the installation it started from. One that another install overtook is refused without writing anything. The newer release, its stored package and its files stay. A manual one answers 409. An automatic update is skipped and records no refusal.

Approach

  • The replacement write now saves the installation row and the stored archive in one transaction, and only while the row still holds the install path the replacement was prepared against. Each install gets a fresh directory, so the install path identifies the installed package, including a reinstall of the same version, which a version check would miss. UpdateInstallationInput gains Archive and IfInstallPath, and a guarded write that no longer matches returns the new ErrInstallationChanged instead of doing nothing. The refusal record that automatic updates write already used IfVersion and now ignores that error.
  • Before stopping the running plugin, the manual and automatic paths re-read the installation and refuse if it changed, so the newer release keeps running. The guarded write covers a change that lands after that check. In that window the newer process can be stopped once and is then started again by the existing lifecycle hooks.
  • Applying a recorded update (POST /api/v2/admin/plugins/installations/{id}/update) prepares against the installation that recorded the available version. Before, it read the installation again after resolving the catalog, so an install landing in between could be replaced by the older recorded version.
  • A catalog install reads the installation before it resolves the catalog entry, so an install that lands during that lookup also refuses it.
  • The web admin refreshes the plugin lists when an install, upload or update answers 409, so the page shows the version the message asks the admin to check.
  • A skipped automatic update clears an old refusal record only while the installation still holds the package it read, so it can't erase a refusal recorded against the newer release.
  • /api/v2: createAdminPluginInstallation and uploadAdminPluginInstallation now declare 409, which applyAdminPluginUpdate and the chunked upload's complete step already declared. The problem type is conflict with a detail written for the admin. This is additive. The OpenAPI document, web types and docs/admin-api.md are updated. The frozen /api/v1 bridge, jellycompat and the Apple and Android clients are not involved.
  • No cross-server lock. The issue left that open. The guarded write gives the same result whichever API server finishes first, and the remaining cost is the brief restart described above.
  • The user manual does not describe concurrent plugin installs, so no manual issue is needed.

Validation

  • go build ./..., gofmt -l, go mod tidy -diff, go vet ./..., make lint-changed, make lint-router-recovery: pass.
  • make verify-route-inventory, verify-apiv2-openapi, verify-apiv2-web-types, verify-apiv2-contract, verify-apiv2-fixtures, TestCommittedArtifactMatchesRouter, verify-local-paths, verify-case-collisions, verify-size-ratchet, verify-bidi: pass.
  • make test-go against a migrated PostgreSQL 18 database: passes. One earlier run failed in internal/scanner (TestScanKeepsFileRowAcrossRenameDB). That test passes on its own and on the rerun, and this branch does not touch the scanner.
  • New and extended tests cover the stored replacement (Postgres: a replacement that finishes after another install is refused, and the newer row, archive and files stay; the guard also holds for an archive-only write), the catalog install and applied-update paths (refused before the plugin is stopped), the automatic update (skipped, not counted or recorded as a failure, and the newer release's refusal record is left alone), and the 409 mapping. Each failed before its fix. The new Postgres test is listed in scripts/ci/db-contracts.txt.
  • Web: pnpm exec vitest run src/hooks/queries/admin/ src/pages/AdminPluginDetail.test.tsx, tsc --noEmit, eslint and prettier on the changed files: pass. The new hook test fails without the 409 refresh.
  • Not run: verify-settings-bindings-all, verify-playback-fixtures, verify-migrations, verify-prometheus-rules, verify-actionlint and verify-shellcheck (none of their inputs changed).

Evidence

Checked on a local server running origin/main (before) and this branch (after), with the same database. A local test catalog lists a test plugin at 1.0.0, 2.0.0 and 3.0.0. 1.0.0 is installed with automatic updates on. The 2.0.0 download is served slowly. Check Plugin Updates starts the automatic update to 2.0.0, and two seconds later the admin installs 3.0.0 from the catalog.

Before (origin/main):

## auto-update: POST /api/v2/admin/tasks/check_plugin_updates/run (catalog lists 1.0.0, 2.0.0; 2.0.0 downloads for 12s)
## manual install: POST /api/v2/admin/plugins/installations {plugin_id, version: 3.0.0}
HTTP 201 {"version":"3.0.0"}
## right after the manual install
{"version":"3.0.0","install_path":"3.0.0/install-2973146988/plugin"}
## after the 2.0.0 download finished
{"version":"2.0.0","install_path":"2.0.0/install-1544194735/plugin"}
## stored archive version
2.0.0
## release dirs on disk
2.0.0/install-1544194735 3.0.0/install-2973146988

After (this branch), same steps:

## manual install: POST /api/v2/admin/plugins/installations {plugin_id, version: 3.0.0}
HTTP 201 {"version":"3.0.0"}
## right after the manual install
{"version":"3.0.0","install_path":"3.0.0/install-3446866819/plugin"}
## after the 2.0.0 download finished
{"version":"3.0.0","install_path":"3.0.0/install-3446866819/plugin"}
## stored archive version
3.0.0
## server log
level=INFO msg="skipped plugin auto-update: the plugin was replaced while it downloaded" plugin_id=example.issue4352-stub from_version=1.0.0 to_version=2.0.0

(The extra 3.0.0/install-2973146988 directory still on disk after the fix was left behind by the earlier run on origin/main.)

Reverse order on this branch: the admin's 2.0.0 install downloads slowly while Check Plugin Updates installs 3.0.0.

## after the auto-update
{"version":"3.0.0"}
manual HTTP 409
{"status":409,"title":"Conflict","detail":"Another install or update replaced this plugin while its package downloaded, so Silo didn't install it. Check the installed version and try again."}
## after the manual install answered
{"version":"3.0.0"}

On the same build, an automatic update with no concurrent install still goes from 1.0.0 to 2.0.0. So does applying a recorded update with POST /api/v2/admin/plugins/installations/{id}/update.

Follow-ups

Risks

  • No migration.
  • A guarded InstallationStore.Update that no longer matches now returns ErrInstallationChanged instead of nil. Its only earlier caller, the automatic update's refusal record, handles the error.
  • An admin whose install loses the race now sees a 409 with a reason instead of a success that the other install later undid.

Checklist

  • I read and can explain the complete diff.
  • This pull request addresses one concern.
  • Each test this pull request adds meets "Decide what to test" in CONTRIBUTING.md.
  • The Evidence section shows every change a user can see, or how I checked a change nobody sees.

AI Disclosure

  • Harness: Claude Code (via T3 Code); Codex CLI for code review
  • Tool(s): Claude Code, Codex CLI, GitHub CLI, git, Docker, curl
  • Model(s): claude-opus-5-5; gpt-6.2-sol, gpt-6.2-astra, claude-fable-5-2 (code review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: four independent reviews of the full diff (gpt-6.2-sol and gpt-6.2-astra through Codex CLI, claude-opus-5-5 and claude-fable-5-2 as Claude Code subagents) covered correctness, repository standards and the issue's requirements, followed by a second four-way review of the fixes. Fixed from the first round: applying a recorded update could still replace a newer install that landed while the catalog resolved (Sol, Astra); a guarded write that changed no column skipped its guard (Astra); a skipped automatic update could clear a refusal recorded against the newer release (Sol, Astra); the 409 mapping had no test (Sol, Astra, Fable); and the docs overstated that the newer process is never stopped (Sol, Astra, Fable). Accepted: the short window between the pre-stop check and the stop, where the newer process is restarted once, rather than adding a cross-server lock. The second round found no problems in the fixes. Two reviewers noted that a same-version reinstall could still have its refusal record cleared, so the clear now checks the install path instead of the version.
  • Maintainer review: claude-opus-5-5 (Claude Code via T3 Code) reviewed the PR with gpt-6.2-sol (Codex) as a cross-provider reviewer, and pushed the catalog-lookup and web 409 fixes in a18456d plus a merge of main.

Note

Refuse plugin updates overtaken by another install during download

  • Adds ErrInstallationChanged in installation.go. Guarded installation updates now reject stale state when the install path or version changed since preparation, and the installation row plus archive are written in one transaction.
  • Service.replaceStopped and AutoUpdateService.autoUpdatePlugin check the installation path before stopping the plugin, so an overtaken update returns early. The newer release, stored package, and files remain.
  • Automatic updates that hit this case are skipped without recording a failure. Admin API mutations map the error to HTTP 409 with a Problem response, and the web hooks invalidate plugin queries on 409 before showing the error toast.
  • Risk: guarded writes that previously no-op'd now return ErrInstallationChanged — see updateInstallationRow in installation.go and the updated assertion in builtin_guard_test.go.

Macroscope summarized 2bc8e22.

…during its download

A plugin replacement wrote its package over whatever the installation held
when it finished. An automatic update still downloading when an admin
installed a newer release stopped that release, wrote the older package,
stored archive and version over it, and left the newer release's files on
disk.

A replacement now writes its row and stored archive in one transaction,
guarded on the install path it was prepared against, and a changed
installation is refused with ErrInstallationChanged before its process is
stopped. Applying a recorded update prepares against the installation that
recorded it. A manual install, update or upload that loses the race answers
409; an automatic update is skipped and leaves the newer release's refusal
record alone.

Closes Silo-Server#4352
@silo-kody

silo-kody Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

This organization requires a seat for paid usage-based reviews, including automatic and on-demand reviews. Ask an admin to assign a seat or enable paid usage-based reviews for users without a seat in Billing.

Next included review available in 49 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 818c928a-f187-49f4-8ac0-b7642ab429e9
Commits

Reviewing files that changed from the base of the PR and between 4a73f48 and 2bc8e22.

Files selected for processing: 18

  • contracts/api/v2/openapi.json
  • docs/admin-api.md
  • internal/apiv2/admin_plugin_catalog_settings_test.go
  • internal/apiv2/admin_plugin_configuration.go
  • internal/apiv2/admin_plugin_lifecycle.go
  • internal/apiv2/admin_plugin_uploads.go
  • internal/plugins/auto_update.go
  • internal/plugins/auto_update_replace_test.go
  • internal/plugins/builtin_guard_test.go
  • internal/plugins/installation.go
  • internal/plugins/installer.go
  • internal/plugins/installer_replace_test.go
  • internal/plugins/service.go
  • internal/plugins/service_install_catalog_db_test.go
  • scripts/ci/db-contracts.txt
  • web/src/api/v2/schema.ts
  • web/src/hooks/queries/admin/pluginLifecycle.test.ts
  • web/src/hooks/queries/admin/plugins.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@silo-triage silo-triage Bot added the size/L 200–499 added + deleted lines (all files); change volume, not priority. label Nov 18, 2026
Comment on lines +330 to +332
existing := expected
if existing == nil {
existing, err = s.existingInstallationByPluginID(ctx, req.PluginID)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug high

Catalog resolution can hide an intervening plugin replacement

An update completed while ResolveInstall fetches the repository index can become the baseline and be overwritten by an older requested release. Capture the existing installation before catalog resolution and guard the replacement against that snapshot.

Prompt for LLM
File internal/plugins/service.go, lines 330-332:

Catalog resolution can hide an intervening plugin replacement

A catalog install reads the existing installation only after `ResolveInstall` fetches the repository index, so an update that completes during that fetch becomes the baseline and can be overwritten by the older requested release. Capture the existing installation before resolving the catalog and guard the replacement against that snapshot.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Claude Code (claude-opus-5-5)

This holds for a plain catalog install. /update now passes the installation it read, but InstallCatalog still reads the installation after ResolveInstall returns, so an install that lands while the index is fetched becomes the baseline and gets replaced. I'm fixing this in a commit on this branch by reading the installation before the catalog resolves, so there's no need to change it yourself.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense. Reading the installation before catalog resolution closes the window for plain catalog installs, just as passing the earlier snapshot does for /update. Thanks for handling the fix on the branch.

@Quick104 Quick104 Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Claude Code (claude-opus-5-5)

Fixed in a18456d: installCatalog now reads the installation before ResolveInstall, so an install that lands while the index is fetched refuses this one with 409. A new case in TestServiceInstallCatalogStopsPluginOnlyForAnAcceptedPackageDB ("replaced while a catalog install resolves") fails on 74c42e1 and passes now. docs/admin-api.md says the guard covers the catalog lookup as well as the download.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for fixing this. Reading the installation before catalog resolution closes the window identified in the suggestion, and the new regression case covers it. The documentation update also makes the guard’s scope clear.

@silo-triage silo-triage Bot added bug Something isn't working priority: P2 Limited scope, workaround exists, or polish labels Nov 18, 2026

@Quick104 Quick104 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Claude Code (claude-opus-5-5)

One finding outside the diff, so it goes here rather than on a line. The catalog-install window from the existing thread on internal/plugins/service.go holds up too; my reply is in that thread.

Low: the web plugin list stays stale after the new 409. useInstallPlugin, useUploadPlugin and useApplyPluginUpdate in web/src/hooks/queries/admin/plugins.ts refresh the plugin queries only on success. With this PR, an install, upload or update that loses to another install answers 409, and the message asks the admin to check the installed version. The page still shows the version from before the other install landed, and still offers the update. Repair: refresh the plugin queries when one of these calls answers 409. I'm fixing this in a commit on this branch, so there's no need to change it yourself.

Quick104 and others added 2 commits November 18, 2026 15:19
…solves

InstallCatalog read the installation after ResolveInstall returned, so an
install that landed while the repository index was fetched became the
baseline and was replaced. Read it first, as /update already does.

The web admin now refreshes the plugin lists when an install, upload or
update answers 409, so the page shows the version the message asks the
admin to check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-triage silo-triage Bot added size/XL 500–999 added + deleted lines (all files); change volume, not priority. and removed size/L 200–499 added + deleted lines (all files); change volume, not priority. labels Nov 18, 2026
@silo-kody

silo-kody Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@Quick104

Copy link
Copy Markdown
Contributor

🤖 Claude Code (claude-opus-5-5)

Review summary

Reviewed head: 2bc8e225db (74c42e1 plus one fix commit, a18456dde8, and a merge of main, which had changed openapi.json, schema.ts and db-contracts.txt; the generated contract checks pass after the merge).

The approach holds: the guarded write on install_path is the right arbiter for API servers that share Postgres, and the pre-stop check keeps the newer release running in the common case. A stale replacement prepared against 1.0.0 and applied after 2.0.0 left 1.1.0 installed with its archive on e8de111, and is refused with 2.0.0 and its archive kept on this branch (a throwaway Postgres test through prepareBinary/Apply, which exist on both sides). The PR's own new tests don't build on the base because they use ErrInstallationChanged, IfInstallPath and ArchiveInput, so that boundary test is the base comparison.

Addressed

  • Catalog install overtaken while the catalog resolves (from the existing thread on service.go): installCatalog now reads the installation before ResolveInstall. New case in TestServiceInstallCatalogStopsPluginOnlyForAnAcceptedPackageDB; it fails on 74c42e1 and passes now.
  • Web plugin list stale after a 409: install, upload and apply-update now refresh the plugin queries on 409. New test in pluginLifecycle.test.ts; it fails without the change.
  • docs/admin-api.md now says the guard covers the catalog lookup as well as the download.

Checked and left as is

  • A plugin deleted inside Update's own transaction gets 409 rather than 404. A delete any earlier is reported as 404 by checkUnchanged or Update's first read, so this window is too small to matter.
  • A refused automatic update still guards its refusal record on the version, not the install path. The record describes the catalog release that was refused, which stays true for any copy of the same installed version.
  • Holding the row lock while the archive bytes are written is the cost of writing them in one transaction, and it applies only to a replacement.
  • The restart of the newer release when both writes finish together is disclosed in the PR and documented.

Left for maintainers

Older gaps on the same paths, outside this PR:

  • [bug] Some plugin installation writes ignore a newer install of the same plugin #4518: archive repair, the notify marker, /update's second marker clear, and /update's 500 when the marker disappears between reads all write by ID alone. They need this PR's guard, so they wait for it to merge.
  • Two first installs of one plugin can create duplicate rows, since ordinary plugin IDs have no unique index. That fix is in progress separately.

Validation

Validation tasks: changes #1224 C1; changes #1225 C1, the same as the body. A single install or update behaves as before. #1224 C2 and #1225 C2 are unaffected.

Other checks

  • User manual: unaffected. The plugins page doesn't describe overlapping installs, and its advice to retry only when the message says so fits the new 409.
  • Apple, Android, Roku: N/A. None of them administer plugins.
  • Evidence: the published page still matches. The fixes change only the catalog-lookup window and the web list refresh, which unit and hook tests cover.
  • Cross-provider review: gpt-6.2-sol (Codex), one round on 74c42e1. Its catalog-lookup finding is fixed above. Its other findings either predate this PR (tracked above) or are the refusal-record guard covered under "Checked and left as is".

Fit: 9/10 · Readiness: 9/10: ready (assuming CI is green)

Fit: it fixes a real way to lose a newer plugin install. The fix is a database guard that works the same on one server or many, with no new setting. Readiness: the race is refused on this branch and reproduced on the base, the two gaps the review found are fixed with tests that failed before, and the remaining gaps predate this PR and are tracked.

existing := expected
if existing == nil {
var err error
existing, err = s.existingInstallationByPluginID(ctx, req.PluginID)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug critical

A concurrent first install can create duplicate plugin installations

A concurrent install can make the initial lookup stale, causing InstallBinary or InstallRemote to create a duplicate and later installs to fail with multiple existing installations found. Enforce uniqueness atomically when inserting the installation.

Prompt for LLM
File internal/plugins/service.go, line 329:

A concurrent first install can create duplicate plugin installations

If the plugin is absent at this lookup but another install completes while the catalog resolves, the stale nil snapshot sends this request through `InstallBinary` or `InstallRemote`, which inserts a second installation instead of detecting the new row; subsequent catalog installs then fail with `multiple existing installations found`. Guard the create path against an installation appearing after the initial snapshot, with an atomic uniqueness check at insertion.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

@Rhainland Rhainland Nov 18, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed. Reading the installation before the catalog resolves widened the window for a duplicate first install. This PR merged before my fix was pushed, so the fix isn't on main yet: commit 9539ccc on the PR branch reads the installation again once the catalog resolves and answers 409 (ErrInstallationChanged) if one appeared meanwhile. It comes with TestServiceInstallCatalogRefusesAFirstInstallOvertakenWhileResolvingDB, which fails without the fix. It will land as a follow-up PR.

Two first installs whose downloads overlap can still both create a row, as before this PR. Only a unique index on plugin_installations.plugin_id closes that fully.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification. The recheck addresses the widened race during catalog resolution, and the new test covers that case.

The broader duplicate-first-install race remains when downloads overlap; the recheck alone cannot enforce uniqueness at insertion. I understand the unique-index migration is being handled separately, so I would treat that as a known follow-up rather than a reason to block this PR.

@Quick104
Quick104 merged commit 939cf24 into Silo-Server:main Nov 18, 2026
22 of 24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working priority: P2 Limited scope, workaround exists, or polish size/XL 500–999 added + deleted lines (all files); change volume, not priority.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[bug] A plugin update can overwrite a newer install of the same plugin that finished during its download

2 participants