From 6d31758cca4c1700f250894dbc138af46c2de398 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sun, 12 Jul 2026 14:23:58 +0200 Subject: [PATCH 1/2] feat(api): #271 collections scan-status REST surface + authoritative SPA reconcile MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add GET /api/media-sources/collections-scan-status (MediaSourcesController → GetCollectionsScanStatus handler) reporting which media-source families (plex/jellyfin/emby) currently hold their external-collections scan lock, reading IEntityLocker.Are{X}CollectionsLocked(). The lock is family-global (no source id) and boolean (no percent), so the DTO carries just {family} and returns only active families — the counterpart to GET /api/libraries/scan-status. SPA: useCollectionsScan now polls this endpoint and reconciles optimistic pending against the active-family set (seeding on mount so an in-progress scan disables buttons immediately), using the same grace-tick helper as library scans (now generic over the pending key type). Drops COLLECTIONS_PENDING_TIMEOUT_MS — a long deep scan no longer re-enables the button early, and a fast scan no longer wedges it disabled for the full timeout. A row shows Scanning when its family is active or it has an in-grace optimistic pending key. Tests: handler (3), controller route+delegation (2), SPA api fn + hook reconcile (mount-seed / 202-promote / 409-keeps-disabled / 404-error). OpenAPI + TS types regenerated. Docs: api-conventions §3b, blazor-route-parity §5, decisions.md. Unblocks #91b (arc item 4): Libraries.razor's collections-scan affordance now has full authoritative parity. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../Queries/GetCollectionsScanStatus.cs | 5 + .../GetCollectionsScanStatusHandler.cs | 38 ++++ .../CollectionsScanStatusResponseModel.cs | 8 + .../GetCollectionsScanStatusHandlerTests.cs | 60 ++++++ .../MediaSourcesControllerTests.cs | 27 +++ .../Controllers/Api/MediaSourcesController.cs | 14 ++ ErsatzTV/wwwroot/openapi/v1.json | 65 +++++++ docs/api-conventions.md | 9 + docs/blazor-route-parity.md | 4 +- docs/decisions.md | 29 +++ docs/endpoint-index.md | 3 +- web/src/api/generated/v1.d.ts | 3 + web/src/api/libraries.test.ts | 104 ++++++++++- web/src/api/libraries.ts | 173 ++++++++++++------ web/src/screens/LibrariesScreen.tsx | 20 +- 15 files changed, 495 insertions(+), 67 deletions(-) create mode 100644 ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatus.cs create mode 100644 ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatusHandler.cs create mode 100644 ErsatzTV.Core/Api/MediaSources/CollectionsScanStatusResponseModel.cs create mode 100644 ErsatzTV.Tests/Application/MediaSources/GetCollectionsScanStatusHandlerTests.cs diff --git a/ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatus.cs b/ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatus.cs new file mode 100644 index 000000000..44d7173b4 --- /dev/null +++ b/ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatus.cs @@ -0,0 +1,5 @@ +using ErsatzTV.Core.Api.MediaSources; + +namespace ErsatzTV.Application.MediaSources; + +public record GetCollectionsScanStatus : IRequest>; diff --git a/ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatusHandler.cs b/ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatusHandler.cs new file mode 100644 index 000000000..08b06f406 --- /dev/null +++ b/ErsatzTV.Application/MediaSources/Queries/GetCollectionsScanStatusHandler.cs @@ -0,0 +1,38 @@ +#nullable enable +using ErsatzTV.Core.Api.MediaSources; +using ErsatzTV.Core.Interfaces.Locking; + +namespace ErsatzTV.Application.MediaSources; + +// Reports which media-source families currently hold their external-collections scan lock. The lock +// is the running scan (the scan-collections controllers acquire it before enqueueing and the scanner +// releases it on completion), so IEntityLocker is the authoritative source — analogous to how +// GetLibraryScanStatus reads IScannerProxyService.GetActiveScans(). Collections locks are family-global, +// so this returns at most one entry per family, and only for families actively scanning. +public class GetCollectionsScanStatusHandler(IEntityLocker entityLocker) + : IRequestHandler> +{ + public Task> Handle( + GetCollectionsScanStatus request, + CancellationToken cancellationToken) + { + var result = new List(); + + if (entityLocker.ArePlexCollectionsLocked()) + { + result.Add(new CollectionsScanStatusResponseModel("plex")); + } + + if (entityLocker.AreJellyfinCollectionsLocked()) + { + result.Add(new CollectionsScanStatusResponseModel("jellyfin")); + } + + if (entityLocker.AreEmbyCollectionsLocked()) + { + result.Add(new CollectionsScanStatusResponseModel("emby")); + } + + return Task.FromResult(result); + } +} diff --git a/ErsatzTV.Core/Api/MediaSources/CollectionsScanStatusResponseModel.cs b/ErsatzTV.Core/Api/MediaSources/CollectionsScanStatusResponseModel.cs new file mode 100644 index 000000000..f44695dea --- /dev/null +++ b/ErsatzTV.Core/Api/MediaSources/CollectionsScanStatusResponseModel.cs @@ -0,0 +1,8 @@ +#nullable enable +namespace ErsatzTV.Core.Api.MediaSources; + +// One entry per media-source family (plex/jellyfin/emby) whose external-collections scan is currently +// running. Collections locks are family-global (there is no per-source collections lock), so an entry +// means every source of that family is scanning. Mirrors the shape of LibraryScanStatusResponseModel, +// but there is no percent: collections scans expose only a boolean lock, not progress. +public record CollectionsScanStatusResponseModel(string Family); diff --git a/ErsatzTV.Tests/Application/MediaSources/GetCollectionsScanStatusHandlerTests.cs b/ErsatzTV.Tests/Application/MediaSources/GetCollectionsScanStatusHandlerTests.cs new file mode 100644 index 000000000..c3358a4bd --- /dev/null +++ b/ErsatzTV.Tests/Application/MediaSources/GetCollectionsScanStatusHandlerTests.cs @@ -0,0 +1,60 @@ +using ErsatzTV.Application.MediaSources; +using ErsatzTV.Core.Api.MediaSources; +using ErsatzTV.Core.Interfaces.Locking; +using NSubstitute; +using NUnit.Framework; +using Shouldly; + +namespace ErsatzTV.Tests.Application.MediaSources; + +[TestFixture] +public class GetCollectionsScanStatusHandlerTests +{ + [Test] + public async Task Handle_Should_Return_Empty_When_No_Family_Is_Locked() + { + var locker = Substitute.For(); + locker.ArePlexCollectionsLocked().Returns(false); + locker.AreJellyfinCollectionsLocked().Returns(false); + locker.AreEmbyCollectionsLocked().Returns(false); + + var handler = new GetCollectionsScanStatusHandler(locker); + + List result = + await handler.Handle(new GetCollectionsScanStatus(), CancellationToken.None); + + result.ShouldBeEmpty(); + } + + [Test] + public async Task Handle_Should_Return_Only_Locked_Families() + { + var locker = Substitute.For(); + locker.ArePlexCollectionsLocked().Returns(true); + locker.AreJellyfinCollectionsLocked().Returns(false); + locker.AreEmbyCollectionsLocked().Returns(true); + + var handler = new GetCollectionsScanStatusHandler(locker); + + List result = + await handler.Handle(new GetCollectionsScanStatus(), CancellationToken.None); + + result.Select(r => r.Family).ShouldBe(["plex", "emby"]); + } + + [Test] + public async Task Handle_Should_Return_All_Families_When_All_Locked() + { + var locker = Substitute.For(); + locker.ArePlexCollectionsLocked().Returns(true); + locker.AreJellyfinCollectionsLocked().Returns(true); + locker.AreEmbyCollectionsLocked().Returns(true); + + var handler = new GetCollectionsScanStatusHandler(locker); + + List result = + await handler.Handle(new GetCollectionsScanStatus(), CancellationToken.None); + + result.Select(r => r.Family).ShouldBe(["plex", "jellyfin", "emby"]); + } +} diff --git a/ErsatzTV.Tests/Controllers/MediaSourcesControllerTests.cs b/ErsatzTV.Tests/Controllers/MediaSourcesControllerTests.cs index 3e2c98b08..13ddfe03a 100644 --- a/ErsatzTV.Tests/Controllers/MediaSourcesControllerTests.cs +++ b/ErsatzTV.Tests/Controllers/MediaSourcesControllerTests.cs @@ -36,6 +36,33 @@ public class MediaSourcesControllerTests attribute.Name.ShouldBe("GetMediaSources"); } + [Test] + public void CollectionsScanStatus_Should_Expose_Idiomatic_Rest_Route() + { + MethodInfo action = typeof(MediaSourcesController) + .GetMethod(nameof(MediaSourcesController.GetCollectionsScanStatus)) + ?? throw new AssertionException("Missing action GetCollectionsScanStatus"); + + HttpMethodAttribute attribute = action.GetCustomAttributes(inherit: true).Single(); + attribute.HttpMethods.ShouldContain("GET"); + attribute.Template.ShouldBe("/api/media-sources/collections-scan-status"); + attribute.Name.ShouldBe("GetCollectionsScanStatus"); + } + + [Test] + public async Task GetCollectionsScanStatus_Should_Return_Results_From_Mediator() + { + var expected = new List { new("plex"), new("emby") }; + + _mediator.Send(Arg.Any(), Arg.Any()) + .Returns(expected); + + List result = + await _controller.GetCollectionsScanStatus(CancellationToken.None); + + result.ShouldBe(expected); + } + [Test] public async Task GetAll_Should_Return_Results_From_Mediator() { diff --git a/ErsatzTV/Controllers/Api/MediaSourcesController.cs b/ErsatzTV/Controllers/Api/MediaSourcesController.cs index ca774dc1e..a4eac9794 100644 --- a/ErsatzTV/Controllers/Api/MediaSourcesController.cs +++ b/ErsatzTV/Controllers/Api/MediaSourcesController.cs @@ -16,4 +16,18 @@ public class MediaSourcesController(IMediator mediator) : ControllerBase [ProducesResponseType(typeof(List), StatusCodes.Status200OK)] public async Task> GetAll(CancellationToken cancellationToken) => await mediator.Send(new GetAllMediaSourcesForApi(), cancellationToken); + + [HttpGet("/api/media-sources/collections-scan-status", Name = "GetCollectionsScanStatus")] + [Tags("Media Sources")] + [EndpointSummary("Get active external-collections scan status")] + [EndpointDescription( + "Returns the media-source families (plex/jellyfin/emby) whose external-collections scan lock is " + + "currently held. Collections locks are family-global, so an entry means every source of that family " + + "is scanning. Empty when nothing is scanning. The SPA polls this to reconcile the collections scan " + + "buttons against a live active set, matching the library-scan UX.")] + [EndpointGroupName("general")] + [ProducesResponseType(typeof(List), StatusCodes.Status200OK)] + public async Task> GetCollectionsScanStatus( + CancellationToken cancellationToken) => + await mediator.Send(new GetCollectionsScanStatus(), cancellationToken); } diff --git a/ErsatzTV/wwwroot/openapi/v1.json b/ErsatzTV/wwwroot/openapi/v1.json index 3838d6143..f6abb3756 100644 --- a/ErsatzTV/wwwroot/openapi/v1.json +++ b/ErsatzTV/wwwroot/openapi/v1.json @@ -10357,6 +10357,60 @@ ] } }, + "/api/media-sources/collections-scan-status": { + "get": { + "tags": [ + "Media Sources" + ], + "summary": "Get active external-collections scan status", + "description": "Returns the media-source families (plex/jellyfin/emby) whose external-collections scan lock is currently held. Collections locks are family-global, so an entry means every source of that family is scanning. Empty when nothing is scanning. The SPA polls this to reconcile the collections scan buttons against a live active set, matching the library-scan UX.", + "operationId": "GetCollectionsScanStatus", + "responses": { + "200": { + "description": "OK", + "content": { + "text/plain": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionsScanStatusResponseModel" + } + } + }, + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionsScanStatusResponseModel" + } + } + }, + "text/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionsScanStatusResponseModel" + } + } + } + } + }, + "401": { + "description": "API key missing or invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProblemDetails" + } + } + } + } + }, + "security": [ + { } + ] + } + }, "/api/movies/{id}": { "get": { "tags": [ @@ -23680,6 +23734,17 @@ ], "type": "string" }, + "CollectionsScanStatusResponseModel": { + "required": [ + "family" + ], + "type": "object", + "properties": { + "family": { + "type": "string" + } + } + }, "CollectionType": { "enum": [ "Collection", diff --git a/docs/api-conventions.md b/docs/api-conventions.md index 7ee695f02..b8e301bc4 100644 --- a/docs/api-conventions.md +++ b/docs/api-conventions.md @@ -168,6 +168,15 @@ true, deep)` to the scanner channel and returns **202**. `ScannerService` releas enqueue throws. `POST /api/libraries/{id}/scan?deep=` similarly threads an optional `[FromQuery] bool deep` into `QueueLibraryScanByLibraryId(id, DeepScan)`. +**Status counterpart for a lock-backed async op.** A queue-triggering endpoint whose "is it running?" +state lives in a lock/registry should expose a **GET status surface** the SPA can poll to reconcile its +optimistic pending flag, rather than relying on a client-side timeout. Two exemplars: +`GET /api/libraries/scan-status` reads `IScannerProxyService.GetActiveScans()` (per-library, with +percent); `GET /api/media-sources/collections-scan-status` (#271) reads +`IEntityLocker.Are{X}CollectionsLocked()` and returns one `{family}` entry per **family-global** +collections lock that's held (no id, no percent — the lock granularity dictates the DTO shape). Return +only the *active* entries (empty list = nothing running), mirroring the queue op's own lock. + `NotFoundError : BaseError` lives in `ErsatzTV.Core/Errors/NotFoundError.cs` — return it from a handler's validation when a lookup fails, so the controller-side mapping falls out for free. diff --git a/docs/blazor-route-parity.md b/docs/blazor-route-parity.md index 7e2baae9f..027efbde3 100644 --- a/docs/blazor-route-parity.md +++ b/docs/blazor-route-parity.md @@ -325,8 +325,8 @@ so the deletion diff stays pure): `LibrariesScreen` now wires the shipped `scanL The External Collections rows derive client-side from `getMediaSources()` (no new endpoint): the media-sources API handler already filters each source's `libraries` to sync-enabled entries, so a remote source with a non-empty `libraries` list is exactly `GetExternalCollections`'s `Libraries.Any(ShouldSyncItems)` filter. Collections scans -have no scan-status poll surface, so their button pending state is optimistic + timeout-bounded (follow-up #271: a -collections scan-status endpoint would let it reconcile like library scans). (#204's id-carrying +now reconcile against `GET /api/media-sources/collections-scan-status` (family-global lock state), like library +scans do — #271 replaced the original optimistic timeout with authoritative polling. (#204's id-carrying pattern redirects landed 2026-07-11; its catch-all fallback that replaces `MapFallbackToPage("/_Host")` is folded into Step 2 below, since it can only ship when `_Host` is deleted.) With the SPA parity done and the **mandatory cold adversarial pass** complete, the runbook was executed, in order: diff --git a/docs/decisions.md b/docs/decisions.md index d79dce14a..b2f8d8b0a 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -846,6 +846,35 @@ surfaces the error). This is the honest ceiling of what the current API exposes. collections scan-status endpoint would let the SPA reconcile collections pending against a live active set the way library scans do; filed as **#271** so the timeout isn't mistaken for the intended end state. +## 2026-07-12 — External-collections scans get an authoritative status surface (#271); the SPA timeout is retired + +**Context.** The 2026-07-11 entry above shipped collections-scan buttons with an optimistic, +`COLLECTIONS_PENDING_TIMEOUT_MS`-bounded pending flag because collections locks had **no** HTTP mirror +(unlike library scans, which reconcile against `GET /api/libraries/scan-status`). That was the honest +ceiling of the API at the time and was filed as **#271** so the timeout wasn't mistaken for the end state. +This entry closes that follow-up. + +**Decision 1 — one family-global status endpoint, reading `IEntityLocker`.** New +`GET /api/media-sources/collections-scan-status` (`MediaSourcesController` → `GetCollectionsScanStatus` +handler) returns one `CollectionsScanStatusResponseModel { family }` entry per media-source family +(`plex`/`jellyfin`/`emby`) whose collections lock is currently held, and only for active ones — the direct +counterpart to `GET /api/libraries/scan-status`. It reads `IEntityLocker.Are{X}CollectionsLocked()` (the lock +*is* the running scan — the scan-collections controllers acquire it before enqueueing and the scanner releases +it on completion), analogous to how the library endpoint reads `IScannerProxyService.GetActiveScans()`. Two +deliberate shape differences from libraries: (a) **family-global, not per-source** — the collections lock takes +no source id (`LockPlexCollections()`), so an entry means *every* source of that family is scanning, matching +Blazor's all-rows-disabled behavior (per the PR #272 review note); (b) **no percent** — collections scans +expose only a boolean lock, not progress. + +**Decision 2 — the SPA reconciles authoritatively; the fixed timeout is removed.** `useCollectionsScan` now +polls the new endpoint (seeding on mount, so a scan already running when the screen opens disables the buttons +immediately — the old timeout couldn't) and reconciles optimistic pending against the active-family set using +the **same `pruneGraceExpiredPending` grace-tick helper** the library hook uses (now generic over the pending +key type). A row shows "Scanning" when its family is in the active set **or** it has a still-in-grace optimistic +pending key. The grace window is kept (not the old wholesale timeout) to absorb the click→observed-active lag and +the fast-scan-between-polls race — the same bounded-pending discipline #232/#230 established for library scans. +`COLLECTIONS_PENDING_TIMEOUT_MS` is gone. + ## 2026-07-11 — Blazor Server UI removed (#91 phase b) The #91 phase (b) removal PR deletes the legacy Blazor Server UI now that the ChicoryTV SPA has parity diff --git a/docs/endpoint-index.md b/docs/endpoint-index.md index a21d04d56..9d1d65709 100644 --- a/docs/endpoint-index.md +++ b/docs/endpoint-index.md @@ -2,7 +2,7 @@ *Generated by `scripts/generate-endpoint-index.py` from `ErsatzTV/wwwroot/openapi/v1.json`. Do not edit by hand -- regenerated by `scripts/update-openapi.sh`.* -158 endpoints, 243 operations. +159 endpoints, 244 operations. ## Artists @@ -227,6 +227,7 @@ | Method | Path | Operation | Summary | |---|---|---|---| | GET | `/api/media-sources` | GetMediaSources | Get all media sources with their libraries | +| GET | `/api/media-sources/collections-scan-status` | GetCollectionsScanStatus | Get active external-collections scan status | ## Movies diff --git a/web/src/api/generated/v1.d.ts b/web/src/api/generated/v1.d.ts index e43b190d1..22f0e30ce 100644 --- a/web/src/api/generated/v1.d.ts +++ b/web/src/api/generated/v1.d.ts @@ -255,6 +255,9 @@ export interface components { "ChannelTranscodeMode": "OnDemand"; "ChannelWatermarkImageSource": "Custom" | "ChannelLogo" | "Resource"; "ChannelWatermarkMode": "None" | "Permanent" | "Intermittent" | "OpacityExpression"; + "CollectionsScanStatusResponseModel": { + "family": string; + }; "CollectionType": "Collection" | "TelevisionShow" | "TelevisionSeason" | "Artist" | "MultiCollection" | "SmartCollection" | "Playlist" | "RerunFirstRun" | "RerunRerun" | "SearchQuery" | "Movie" | "Episode" | "MusicVideo" | "OtherVideo" | "Song" | "Image" | "RemoteStream" | "FakeCollection" | "FakePlaylistItem"; "CombinedVersion": { "apiVersion": number; diff --git a/web/src/api/libraries.test.ts b/web/src/api/libraries.test.ts index 2cb3745cd..fe23561be 100644 --- a/web/src/api/libraries.test.ts +++ b/web/src/api/libraries.test.ts @@ -1,15 +1,56 @@ +import { renderHook, waitFor } from '@testing-library/react'; import { beforeEach, describe, expect, it, vi } from 'vitest'; -import { scanCollections, scanLibrary, scanShow } from './libraries'; +import { + getCollectionsScanStatus, + scanCollections, + scanLibrary, + scanShow, + useCollectionsScan +} from './libraries'; function noContent(): Response { return new Response(null, { status: 200 }); } +function json(data: unknown, status = 200): Response { + return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' }, status }); +} + function lastCall(fetchMock: ReturnType) { const call = fetchMock.mock.calls[fetchMock.mock.calls.length - 1]; return { init: call[1] as RequestInit | undefined, url: String(call[0]) }; } +// Stateful collections backend mock: the scan-collections POST acquires the family-global lock +// synchronously (as the real controller does before returning 202/409), so a subsequent status GET +// reports that family active. `postStatus` overrides the POST response for error-path tests. +function mockCollectionsBackend(opts: { postStatus?: number; seededFamilies?: string[] } = {}) { + const active = new Set(opts.seededFamilies ?? []); + const fetchMock = vi.spyOn(window, 'fetch').mockImplementation((input, init) => { + const url = String(input); + const method = (init?.method ?? 'GET').toUpperCase(); + + if (url.includes('/api/media-sources/collections-scan-status')) { + return Promise.resolve(json([...active].map((family) => ({ family })))); + } + + const match = url.match(/\/api\/media-sources\/(\w+)\/\d+\/scan-collections/); + if (match && method === 'POST') { + const status = opts.postStatus ?? 202; + if (status === 202 || status === 409) { + // Both mean a collections scan is now running for this family -> the lock is held. + active.add(match[1]); + return Promise.resolve(status === 202 ? noContent() : json({ detail: 'already scanning' }, 409)); + } + return Promise.resolve(json({ detail: 'not found' }, status)); + } + + return Promise.resolve(json({ detail: 'unexpected' }, 500)); + }); + + return { active, fetchMock }; +} + describe('libraries api client', () => { beforeEach(() => { window.localStorage.clear(); @@ -56,4 +97,65 @@ describe('libraries api client', () => { const { init } = lastCall(fetchMock); expect(JSON.parse(String(init?.body))).toEqual({ deepScan: false, showId: 17 }); }); + + it('getCollectionsScanStatus GETs the collections scan-status endpoint', async () => { + const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(json([{ family: 'plex' }])); + const result = await getCollectionsScanStatus(); + expect(fetchMock).toHaveBeenCalledWith('/api/media-sources/collections-scan-status', expect.anything()); + expect(result).toEqual([{ family: 'plex' }]); + }); +}); + +describe('useCollectionsScan', () => { + beforeEach(() => { + window.localStorage.clear(); + vi.restoreAllMocks(); + }); + + it('seeds activeFamilies from the initial poll (scan already in progress on mount)', async () => { + mockCollectionsBackend({ seededFamilies: ['plex'] }); + const { result } = renderHook(() => useCollectionsScan()); + + await waitFor(() => expect(result.current.activeFamilies.has('plex')).toBe(true)); + expect(result.current.pendingKeys.size).toBe(0); + }); + + it('optimistically marks pending on scan, then promotes to active once the family is observed', async () => { + mockCollectionsBackend(); + const { result } = renderHook(() => useCollectionsScan()); + + await waitFor(() => expect(result.current.activeFamilies.size).toBe(0)); + + await result.current.scan('jellyfin', 7, false); + + // The scan()'s 202 poll observes the (synchronously-locked) family active and reconciles. + await waitFor(() => expect(result.current.activeFamilies.has('jellyfin')).toBe(true)); + expect(result.current.pendingKeys.has('jellyfin:7')).toBe(false); + expect(result.current.error).toBeNull(); + }); + + it('keeps the family disabled and surfaces no error on a 409 (already scanning)', async () => { + mockCollectionsBackend({ postStatus: 409 }); + const { result } = renderHook(() => useCollectionsScan()); + + await waitFor(() => expect(result.current.activeFamilies.size).toBe(0)); + + await result.current.scan('emby', 3, true); + + await waitFor(() => expect(result.current.activeFamilies.has('emby')).toBe(true)); + expect(result.current.error).toBeNull(); + }); + + it('clears pending and surfaces an error on a 404 (source missing)', async () => { + mockCollectionsBackend({ postStatus: 404 }); + const { result } = renderHook(() => useCollectionsScan()); + + await waitFor(() => expect(result.current.activeFamilies.size).toBe(0)); + + await result.current.scan('plex', 9, false); + + await waitFor(() => expect(result.current.error).not.toBeNull()); + expect(result.current.pendingKeys.has('plex:9')).toBe(false); + expect(result.current.activeFamilies.has('plex')).toBe(false); + }); }); diff --git a/web/src/api/libraries.ts b/web/src/api/libraries.ts index c9263f8ad..2de95a261 100644 --- a/web/src/api/libraries.ts +++ b/web/src/api/libraries.ts @@ -5,6 +5,7 @@ import type { components } from './generated/v1'; export type MediaSource = components['schemas']['MediaSourceResponseModel']; export type MediaSourceLibrary = components['schemas']['MediaSourceLibraryResponseModel']; export type LibraryScanStatus = components['schemas']['LibraryScanStatusResponseModel']; +export type CollectionsScanStatus = components['schemas']['CollectionsScanStatusResponseModel']; export interface LibrariesScreenData { scanStatuses: LibraryScanStatus[]; @@ -93,32 +94,34 @@ const PENDING_GRACE_TICKS = 3; // there). A pending id not yet seen active is kept, but only for PENDING_GRACE_TICKS polls: the // per-id counter is decremented each tick and the id is dropped once it hits zero. Mutates the // grace-ticks map in place (delete on promote/expire, set on decrement); callers must still write -// pendingIdsRef.current with the returned set themselves, and must call this exactly once per tick +// their pending ref with the returned set themselves, and must call this exactly once per tick // before that write to keep it a single, ref-free computation safe under StrictMode double-invocation. -function pruneGraceExpiredPending( - pendingIds: Set, - graceTicks: Map, - isSeenActive: (libraryId: number) => boolean -): Set { - const nextPending = new Set(); +// Generic over the pending key type so both library scans (keyed by numeric library id) and +// collections scans (keyed by `${family}:${sourceId}` string) share one definition. +function pruneGraceExpiredPending( + pendingIds: Set, + graceTicks: Map, + isSeenActive: (id: T) => boolean +): Set { + const nextPending = new Set(); - pendingIds.forEach((libraryId) => { - if (isSeenActive(libraryId)) { + pendingIds.forEach((id) => { + if (isSeenActive(id)) { // Seen active at least once - normal active/inactive pruning takes over. - graceTicks.delete(libraryId); + graceTicks.delete(id); return; } - const ticksRemaining = (graceTicks.get(libraryId) ?? PENDING_GRACE_TICKS) - 1; + const ticksRemaining = (graceTicks.get(id) ?? PENDING_GRACE_TICKS) - 1; if (ticksRemaining <= 0) { // Grace window expired without ever appearing in scan-status - give up on it. - graceTicks.delete(libraryId); + graceTicks.delete(id); return; } - graceTicks.set(libraryId, ticksRemaining); - nextPending.add(libraryId); + graceTicks.set(id, ticksRemaining); + nextPending.add(id); }); return nextPending; @@ -402,19 +405,22 @@ export function useLibrariesScreenQuery(pollMs = 10000): LibrariesScreenQuerySta // --- External collections scan (Plex/Jellyfin/Emby) --- -// A pending collections scan re-enables its button after this bound. Unlike library scans, an -// external-collections scan has NO authoritative "in progress" REST surface: /api/libraries/scan-status -// is library-keyed, and Blazor only ever observed collections locks through in-process IEntityLocker -// events (Are{X}CollectionsLocked) that have no HTTP mirror. So we can't reconcile "pending" against a -// live active set the way library scans do - we optimistically disable, then give up after this bound -// so a button can't wedge disabled forever. (A collections scan-status endpoint would let us reconcile -// properly - see the #91b follow-up note.) -const COLLECTIONS_PENDING_TIMEOUT_MS = 30000; +// Fetch the media-source families whose external-collections scan is currently running. Collections +// locks are family-global, so this returns at most one entry per family and only for active ones - +// the authoritative counterpart to /api/libraries/scan-status for collections (#271, #91b F9). +export function getCollectionsScanStatus(): Promise { + return request('/api/media-sources/collections-scan-status'); +} export interface CollectionsScanState { + // Families (plex/jellyfin/emby) whose collections lock is currently held, per the authoritative + // poll. Every source of an active family should render as scanning (the lock is family-global). + activeFamilies: Set; error: string | null; + // Optimistically-pending `${family}:${sourceId}` keys not yet confirmed active by a poll (bridges + // the click -> observed-active window; grace-bounded so a fast/failed scan can't wedge a button). + pendingKeys: Set; scan: (source: CollectionsScanSource, sourceId: number, deep: boolean) => Promise; - scanningKeys: Set; } // Stable key for a per-(family, source) collections scan, used by both the hook and the screen so the @@ -423,68 +429,123 @@ export function collectionsScanKey(source: CollectionsScanSource, sourceId: numb return `${source}:${sourceId}`; } -export function useCollectionsScan(): CollectionsScanState { - const [scanningKeys, setScanningKeys] = useState>(new Set()); +// Recover the family from a `${family}:${sourceId}` key (the family segment has no colon). +function collectionsScanKeyFamily(key: string): CollectionsScanSource { + return key.slice(0, key.indexOf(':')) as CollectionsScanSource; +} + +export function useCollectionsScan(pollMs = 10000): CollectionsScanState { + const [activeFamilies, setActiveFamilies] = useState>(new Set()); + const [pendingKeys, setPendingKeys] = useState>(new Set()); const [error, setError] = useState(null); - // Mirror kept in sync synchronously so scan() can guard double-submits without waiting for a render. - const scanningKeysRef = useRef>(new Set()); - const timeoutsRef = useRef>(new Map()); + // Mirrors kept in sync synchronously so scan() can guard double-submits without waiting for a render. + const activeFamiliesRef = useRef>(new Set()); + const pendingKeysRef = useRef>(new Set()); + // Per-pending-key countdown of remaining polls before we give up waiting for it to appear active. + const pendingGraceTicksRef = useRef>(new Map()); const activeRef = useRef(true); + const loadScanStatus = useCallback(() => { + return getCollectionsScanStatus() + .then((statuses) => { + if (!activeRef.current) { + return; + } + + const active = new Set( + statuses.map((status) => status.family as CollectionsScanSource) + ); + activeFamiliesRef.current = active; + + // Reconcile optimistic pending against the authoritative active families - a pending key + // whose family is scanning is promoted (dropped from pending; the active-family set now + // disables it), and one never seen active expires after the bounded grace window. Compute + // OUTSIDE setState (updaters must be pure under StrictMode) and write the ref here. + const nextPending = pruneGraceExpiredPending(pendingKeysRef.current, pendingGraceTicksRef.current, (key) => + active.has(collectionsScanKeyFamily(key)) + ); + pendingKeysRef.current = nextPending; + + setActiveFamilies(active); + setPendingKeys(nextPending); + }) + .catch(() => { + if (!activeRef.current) { + return; + } + + // A persistently failing poll must not leave optimistically-pending buttons stuck disabled + // forever. Burn a grace tick for every pending key (none can be confirmed active while the + // fetch is failing) so pending still expires within the bounded window. + const nextPending = pruneGraceExpiredPending(pendingKeysRef.current, pendingGraceTicksRef.current, () => false); + pendingKeysRef.current = nextPending; + setPendingKeys(nextPending); + }); + }, []); + useEffect(() => { activeRef.current = true; - // Identity is stable across the hook's life (we only .set/.delete entries, never reassign the - // Map), so capturing it here is the same instance the cleanup clears at unmount. - const timeouts = timeoutsRef.current; + // Seed the active set on mount so a collections scan already in progress (started by another tab + // or a scheduled sync) disables the buttons immediately - the old timeout approach couldn't. + void loadScanStatus(); return () => { activeRef.current = false; - timeouts.forEach((timeoutId) => window.clearTimeout(timeoutId)); - timeouts.clear(); }; - }, []); + }, [loadScanStatus]); - const clearKey = useCallback((key: string) => { - const timeoutId = timeoutsRef.current.get(key); - if (timeoutId !== undefined) { - window.clearTimeout(timeoutId); - timeoutsRef.current.delete(key); + const hasActive = pendingKeys.size > 0 || activeFamilies.size > 0; + + useEffect(() => { + if (!hasActive) { + return undefined; } - const next = new Set(scanningKeysRef.current); + const intervalId = window.setInterval(loadScanStatus, Math.max(pollMs, 10000)); + + return () => { + window.clearInterval(intervalId); + }; + }, [hasActive, loadScanStatus, pollMs]); + + const clearKey = useCallback((key: string) => { + const next = new Set(pendingKeysRef.current); next.delete(key); - scanningKeysRef.current = next; + pendingKeysRef.current = next; + pendingGraceTicksRef.current.delete(key); if (activeRef.current) { - setScanningKeys(next); + setPendingKeys(next); } }, []); const scan = useCallback( (source: CollectionsScanSource, sourceId: number, deep: boolean): Promise => { const key = collectionsScanKey(source, sourceId); - if (scanningKeysRef.current.has(key)) { - // Already pending - ignore the duplicate submission (quick and deep share the source lock). + if (pendingKeysRef.current.has(key) || activeFamiliesRef.current.has(source)) { + // Already pending, or the whole family is already scanning (family-global lock) - ignore the + // duplicate submission. Quick and deep scans share the same lock, so both gate on this. return Promise.resolve(); } - const pending = new Set(scanningKeysRef.current).add(key); - scanningKeysRef.current = pending; - setScanningKeys(pending); + // Optimistically mark pending; the POST response and the next poll tell us how to reconcile. + const pending = new Set(pendingKeysRef.current).add(key); + pendingKeysRef.current = pending; + pendingGraceTicksRef.current.set(key, PENDING_GRACE_TICKS); + setPendingKeys(pending); setError(null); - const timeoutId = window.setTimeout(() => clearKey(key), COLLECTIONS_PENDING_TIMEOUT_MS); - timeoutsRef.current.set(key, timeoutId); - return scanCollections(source, sourceId, deep) .then(() => { - // 202 Accepted - a scan is genuinely queued. Keep the button disabled until the bounded - // timeout expires (there is no completion signal to reconcile against). + // 202 Accepted - a scan is genuinely queued (the controller already holds the family lock). + // Poll; the pending key is promoted to "active" once the family appears in scan-status. + void loadScanStatus(); }) .catch((err: unknown) => { if (err instanceof ApiError && err.status === 409) { - // 409 Conflict - a collections scan is already running for this source. Benign: keep the - // optimistic pending flag (button stays disabled) with no error; it clears on the timeout. + // 409 Conflict - a collections scan is already running for this family. Benign: keep the + // optimistic pending flag (button stays disabled), no error; a poll reconciles it. + void loadScanStatus(); return; } @@ -495,10 +556,10 @@ export function useCollectionsScan(): CollectionsScanState { } }); }, - [clearKey] + [clearKey, loadScanStatus] ); - return { error, scan, scanningKeys }; + return { activeFamilies, error, pendingKeys, scan }; } function messageFromLibrariesError(error: unknown, fallback = 'Unable to load libraries'): string { diff --git a/web/src/screens/LibrariesScreen.tsx b/web/src/screens/LibrariesScreen.tsx index 3ae7ce712..5675ea39a 100644 --- a/web/src/screens/LibrariesScreen.tsx +++ b/web/src/screens/LibrariesScreen.tsx @@ -121,10 +121,11 @@ export function LibrariesScreen() { {collectionsRows.length > 0 && ( )} @@ -133,18 +134,22 @@ export function LibrariesScreen() { // External Collections table (parity with Blazor Libraries.razor's second table). Each row is a // remote source with sync-enabled libraries; the quick/deep buttons queue that source's collections -// scan. There is no scan-status poll surface for collections (see useCollectionsScan), so a row's -// "scanning" state is optimistic and bounded by a timeout rather than reconciled against a live set. +// scan. A row's "scanning" state is reconciled against the authoritative collections scan-status poll +// (#271): the collections lock is family-global, so every source of an active family shows scanning +// (matching Blazor's all-rows-disabled behavior), plus a short-lived optimistic pending flag bridges +// the click -> observed-active window. function ExternalCollectionsSection({ + activeFamilies, error, onScanCollections, - rows, - scanningKeys + pendingKeys, + rows }: { + activeFamilies: Set; error: string | null; onScanCollections: (source: CollectionsScanSource, sourceId: number, deep: boolean) => Promise; + pendingKeys: Set; rows: Array<{ family: CollectionsScanSource; name: string; sourceId: number }>; - scanningKeys: Set; }) { return (
@@ -167,7 +172,8 @@ function ExternalCollectionsSection({
{rows.map((row) => { - const scanning = scanningKeys.has(collectionsScanKey(row.family, row.sourceId)); + const scanning = + activeFamilies.has(row.family) || pendingKeys.has(collectionsScanKey(row.family, row.sourceId)); return (
-- 2.47.3 From 4112413ca5397bd91bbd075cc1c4d658478df3f5 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sun, 12 Jul 2026 14:34:05 +0200 Subject: [PATCH 2/2] fix(spa): #271 disable all family rows on click (family-global lock parity) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cold-review nit fixes on PR #298: - useCollectionsScan.scan() now guards on the whole family being busy (active OR any pending key of that family), not just the exact key — a sibling source of a family with a scan in flight no longer fires a redundant (benign-409) POST. - LibrariesScreen ExternalCollectionsSection disables every row of a family that has a pending or active scan (derives pendingFamilies from pendingKeys), matching Blazor's instant all-rows-disabled behavior instead of waiting a poll RTT. - Rewrite the promote test to actually observe the optimistic-pending window via a deferred POST (was only asserting the promoted end state), and add a test proving a sibling-source click fires no second POST while the family is pending. Co-Authored-By: Claude Opus 4.8 (1M context) --- web/src/api/libraries.test.ts | 64 +++++++++++++++++++++++------ web/src/api/libraries.ts | 12 ++++-- web/src/screens/LibrariesScreen.tsx | 8 +++- 3 files changed, 66 insertions(+), 18 deletions(-) diff --git a/web/src/api/libraries.test.ts b/web/src/api/libraries.test.ts index fe23561be..9feed970b 100644 --- a/web/src/api/libraries.test.ts +++ b/web/src/api/libraries.test.ts @@ -1,4 +1,4 @@ -import { renderHook, waitFor } from '@testing-library/react'; +import { act, renderHook, waitFor } from '@testing-library/react'; import { beforeEach, describe, expect, it, vi } from 'vitest'; import { getCollectionsScanStatus, @@ -24,31 +24,41 @@ function lastCall(fetchMock: ReturnType) { // Stateful collections backend mock: the scan-collections POST acquires the family-global lock // synchronously (as the real controller does before returning 202/409), so a subsequent status GET // reports that family active. `postStatus` overrides the POST response for error-path tests. -function mockCollectionsBackend(opts: { postStatus?: number; seededFamilies?: string[] } = {}) { +function mockCollectionsBackend(opts: { deferPost?: boolean; postStatus?: number; seededFamilies?: string[] } = {}) { const active = new Set(opts.seededFamilies ?? []); - const fetchMock = vi.spyOn(window, 'fetch').mockImplementation((input, init) => { + // When deferPost is set, the scan-collections POST does not resolve until releasePost() is called - + // this lets a test observe the optimistic-pending window before the POST completes. + let releasePost = () => {}; + const postGate = opts.deferPost ? new Promise((resolve) => (releasePost = resolve)) : Promise.resolve(); + + const fetchMock = vi.spyOn(window, 'fetch').mockImplementation(async (input, init) => { const url = String(input); const method = (init?.method ?? 'GET').toUpperCase(); if (url.includes('/api/media-sources/collections-scan-status')) { - return Promise.resolve(json([...active].map((family) => ({ family })))); + return json([...active].map((family) => ({ family }))); } const match = url.match(/\/api\/media-sources\/(\w+)\/\d+\/scan-collections/); if (match && method === 'POST') { + await postGate; const status = opts.postStatus ?? 202; if (status === 202 || status === 409) { // Both mean a collections scan is now running for this family -> the lock is held. active.add(match[1]); - return Promise.resolve(status === 202 ? noContent() : json({ detail: 'already scanning' }, 409)); + return status === 202 ? noContent() : json({ detail: 'already scanning' }, 409); } - return Promise.resolve(json({ detail: 'not found' }, status)); + return json({ detail: 'not found' }, status); } - return Promise.resolve(json({ detail: 'unexpected' }, 500)); + return json({ detail: 'unexpected' }, 500); }); - return { active, fetchMock }; + function scanPostCount(): number { + return fetchMock.mock.calls.filter((call) => String(call[0]).includes('scan-collections')).length; + } + + return { active, fetchMock, releasePost: () => releasePost(), scanPostCount }; } describe('libraries api client', () => { @@ -120,20 +130,50 @@ describe('useCollectionsScan', () => { expect(result.current.pendingKeys.size).toBe(0); }); - it('optimistically marks pending on scan, then promotes to active once the family is observed', async () => { - mockCollectionsBackend(); + it('bridges the click->observed-active gap with optimistic pending, then promotes', async () => { + const backend = mockCollectionsBackend({ deferPost: true }); const { result } = renderHook(() => useCollectionsScan()); await waitFor(() => expect(result.current.activeFamilies.size).toBe(0)); - await result.current.scan('jellyfin', 7, false); + let scanPromise: Promise = Promise.resolve(); + act(() => { + scanPromise = result.current.scan('jellyfin', 7, false); + }); - // The scan()'s 202 poll observes the (synchronously-locked) family active and reconciles. + // Optimistic pending is visible immediately, BEFORE the (deferred) POST resolves. + await waitFor(() => expect(result.current.pendingKeys.has('jellyfin:7')).toBe(true)); + expect(result.current.activeFamilies.has('jellyfin')).toBe(false); + + // Release the POST (lock now held) -> the follow-up poll promotes the family to active. + act(() => backend.releasePost()); + await scanPromise; await waitFor(() => expect(result.current.activeFamilies.has('jellyfin')).toBe(true)); expect(result.current.pendingKeys.has('jellyfin:7')).toBe(false); expect(result.current.error).toBeNull(); }); + it('does not fire a second scan for a sibling source while the family is already pending', async () => { + const backend = mockCollectionsBackend({ deferPost: true }); + const { result } = renderHook(() => useCollectionsScan()); + + await waitFor(() => expect(result.current.activeFamilies.size).toBe(0)); + + act(() => { + void result.current.scan('plex', 1, false); + }); + await waitFor(() => expect(result.current.pendingKeys.has('plex:1')).toBe(true)); + const postsAfterFirst = backend.scanPostCount(); + + // Sibling source of the same (family-global-locked) family - must be ignored, no second POST. + await act(async () => { + await result.current.scan('plex', 2, false); + }); + expect(backend.scanPostCount()).toBe(postsAfterFirst); + + backend.releasePost(); + }); + it('keeps the family disabled and surfaces no error on a 409 (already scanning)', async () => { mockCollectionsBackend({ postStatus: 409 }); const { result } = renderHook(() => useCollectionsScan()); diff --git a/web/src/api/libraries.ts b/web/src/api/libraries.ts index 2de95a261..6ca875e66 100644 --- a/web/src/api/libraries.ts +++ b/web/src/api/libraries.ts @@ -430,7 +430,7 @@ export function collectionsScanKey(source: CollectionsScanSource, sourceId: numb } // Recover the family from a `${family}:${sourceId}` key (the family segment has no colon). -function collectionsScanKeyFamily(key: string): CollectionsScanSource { +export function collectionsScanKeyFamily(key: string): CollectionsScanSource { return key.slice(0, key.indexOf(':')) as CollectionsScanSource; } @@ -522,9 +522,13 @@ export function useCollectionsScan(pollMs = 10000): CollectionsScanState { const scan = useCallback( (source: CollectionsScanSource, sourceId: number, deep: boolean): Promise => { const key = collectionsScanKey(source, sourceId); - if (pendingKeysRef.current.has(key) || activeFamiliesRef.current.has(source)) { - // Already pending, or the whole family is already scanning (family-global lock) - ignore the - // duplicate submission. Quick and deep scans share the same lock, so both gate on this. + const familyBusy = + activeFamiliesRef.current.has(source) || + [...pendingKeysRef.current].some((pendingKey) => collectionsScanKeyFamily(pendingKey) === source); + if (familyBusy) { + // The whole family is already scanning or has a pending scan - ignore the duplicate. The lock + // is family-global, so a sibling source of a busy family would only earn a benign 409; don't + // fire it. (Covers the same-key case too - a pending key implies its family is pending.) return Promise.resolve(); } diff --git a/web/src/screens/LibrariesScreen.tsx b/web/src/screens/LibrariesScreen.tsx index 5675ea39a..cba971637 100644 --- a/web/src/screens/LibrariesScreen.tsx +++ b/web/src/screens/LibrariesScreen.tsx @@ -28,6 +28,7 @@ import { } from '../components'; import { collectionsScanKey, + collectionsScanKeyFamily, useCollectionsScan, useLibrariesScreenQuery, type CollectionsScanSource, @@ -151,6 +152,10 @@ function ExternalCollectionsSection({ pendingKeys: Set; rows: Array<{ family: CollectionsScanSource; name: string; sourceId: number }>; }) { + // The collections lock is family-global, so a scan running (or just clicked) for any source of a + // family disables every row of that family - matching Blazor's all-rows-disabled behavior. + const pendingFamilies = new Set([...pendingKeys].map((key) => collectionsScanKeyFamily(key))); + return (
@@ -172,8 +177,7 @@ function ExternalCollectionsSection({
{rows.map((row) => { - const scanning = - activeFamilies.has(row.family) || pendingKeys.has(collectionsScanKey(row.family, row.sourceId)); + const scanning = activeFamilies.has(row.family) || pendingFamilies.has(row.family); return (
-- 2.47.3