From 292eb8263d799c86a6320078c56447790290d8e2 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 00:59:54 +0200 Subject: [PATCH 01/10] feat(489): project Jellyfin mixed-content libraries instead of dropping them Adds LibraryMediaKind.Mixed and maps Jellyfin's "mixed" (and absent) CollectionType onto it. Previously such libraries hit `_ => None` in JellyfinApiClient.Project and were dropped with no log line, so a mixed library configured in Jellyfin simply never appeared in ErsatzTV. Unknown collection types (notably "music" audio libraries, which have no supported scanner) still fall through to None -- pinned by a guard test so "mixed" cannot silently become a catch-all. Negative control: with the Project change reverted, the two new Mixed tests fail and the other two pass. Refs #489 --- .../Domain/Library/LibraryMediaKind.cs | 10 +- .../Jellyfin/JellyfinApiClientTests.cs | 100 ++++++++++++++++++ .../Jellyfin/JellyfinApiClient.cs | 15 +++ 3 files changed, 124 insertions(+), 1 deletion(-) diff --git a/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs b/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs index d31834026..922c92000 100644 --- a/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs +++ b/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs @@ -8,5 +8,13 @@ public enum LibraryMediaKind OtherVideos = 4, Songs = 5, Images = 6, - RemoteStreams = 7 + RemoteStreams = 7, + + /// + /// A library whose contents are heterogeneous - movies, shows and music videos together. + /// Only produced for remote (Jellyfin) libraries whose collection type is "mixed", where the + /// media server classifies each item for us. A local library is never Mixed: the local folder + /// scanners all share one video extension list and would claim each other's files. + /// + Mixed = 8 } diff --git a/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs b/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs index a369015da..766955291 100644 --- a/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs +++ b/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs @@ -53,6 +53,106 @@ public class JellyfinApiClientTests libraries[0].ShouldSyncItems.ShouldBeFalse(); libraries[0].Paths.Single().Path.ShouldBe("jellyfin://library-1"); } + + [Test] + public async Task Should_Project_Mixed_Libraries() + { + const string response = """ + [ + { + "Name": "Music Videos", + "CollectionType": "mixed", + "ItemId": "library-9", + "LibraryOptions": { + "PathInfos": [] + } + } + ] + """; + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + Substitute.For(), + Substitute.For(), + new SingleResponseHttpClientFactory(response), + Substitute.For>()); + + Either> result = + await client.GetLibraries("http://jellyfin.example", "MediaBrowser Token=abc"); + + result.IsRight.ShouldBeTrue(); + List libraries = result.RightToSeq().Single(); + libraries.Count.ShouldBe(1); + libraries[0].Name.ShouldBe("Music Videos"); + libraries[0].ItemId.ShouldBe("library-9"); + libraries[0].MediaKind.ShouldBe(LibraryMediaKind.Mixed); + libraries[0].ShouldSyncItems.ShouldBeFalse(); + libraries[0].Paths.Single().Path.ShouldBe("jellyfin://library-9"); + } + + [Test] + public async Task Should_Project_Libraries_With_No_CollectionType_As_Mixed() + { + const string response = """ + [ + { + "Name": "Standup", + "ItemId": "library-10", + "LibraryOptions": { + "PathInfos": [] + } + } + ] + """; + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + Substitute.For(), + Substitute.For(), + new SingleResponseHttpClientFactory(response), + Substitute.For>()); + + Either> result = + await client.GetLibraries("http://jellyfin.example", "MediaBrowser Token=abc"); + + result.IsRight.ShouldBeTrue(); + List libraries = result.RightToSeq().Single(); + libraries.Count.ShouldBe(1); + libraries[0].Name.ShouldBe("Standup"); + libraries[0].MediaKind.ShouldBe(LibraryMediaKind.Mixed); + } + + // Guard: mixed must not become a catch-all. Jellyfin "music" (audio) libraries have no + // supported scanner, so they must keep falling through to None. + [Test] + public async Task Should_Not_Project_Unknown_CollectionTypes() + { + const string response = """ + [ + { + "Name": "Explo Discovery", + "CollectionType": "music", + "ItemId": "library-11", + "LibraryOptions": { + "PathInfos": [] + } + } + ] + """; + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + Substitute.For(), + Substitute.For(), + new SingleResponseHttpClientFactory(response), + Substitute.For>()); + + Either> result = + await client.GetLibraries("http://jellyfin.example", "MediaBrowser Token=abc"); + + result.IsRight.ShouldBeTrue(); + result.RightToSeq().Single().ShouldBeEmpty(); + } } private sealed class SingleResponseHttpClientFactory(string response) : IHttpClientFactory diff --git a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs index 5df85c91d..28ada76b9 100644 --- a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs +++ b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs @@ -466,6 +466,21 @@ public class JellyfinApiClient : IJellyfinApiClient }, // TODO: ??? for music libraries "boxsets" => CacheCollectionLibraryId(response.ItemId), + + // A "mixed content" library. Jellyfin reports these as either the literal "mixed" or with + // no collection type at all, depending on server version. Its items are read per type via + // includeItemTypes, so the mix is resolved authoritatively by Jellyfin rather than guessed. + "mixed" or null => new JellyfinLibrary + { + ItemId = response.ItemId, + Name = response.Name, + MediaKind = LibraryMediaKind.Mixed, + ShouldSyncItems = false, + Paths = new List { new() { Path = $"jellyfin://{response.ItemId}" } }, + PathInfos = GetPathInfos(response) + }, + + // anything else (notably "music" audio libraries) stays unsupported _ => None }; -- 2.47.3 From 032d770e68d23a01288067faaea507e0177816a3 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 01:05:23 +0200 Subject: [PATCH 02/10] feat(489): scan mixed Jellyfin libraries with all three per-kind scanners Adds the Mixed dispatch arm. Each per-kind scanner queries Jellyfin with its own includeItemTypes, so the three passes see disjoint sets and their reconciliation stays type-scoped. Failure semantics, both pinned by tests: - one kind failing does NOT skip the others (a broken music-video scan must not block the movies in the same library); the library as a whole fails and LastScan is not stamped - ScanCanceled aborts the sequence immediately -- a user cancellation is not one kind failing Also removes the silent-success default from BOTH dispatchers. `_ => Unit.Default` returned Right for an unhandled kind, which stamped LastScan as though a scan had run -- exactly how a missing Mixed arm would have hidden. And targeted Jellyfin show scans now accept Mixed, since a mixed library legitimately contains shows. Negative control: with the Mixed arm reverted, the 3 new dispatch tests fail and the 2 pre-existing ones pass. Refs #489 --- ...chronizeJellyfinLibraryByIdHandlerTests.cs | 243 ++++++++++++++++++ .../SynchronizeJellyfinLibraryByIdHandler.cs | 72 +++++- .../SynchronizeJellyfinShowByIdHandler.cs | 5 +- .../Commands/ScanLocalLibraryHandler.cs | 6 +- 4 files changed, 322 insertions(+), 4 deletions(-) diff --git a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs index f07ad772f..54560d07c 100644 --- a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs +++ b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs @@ -174,5 +174,248 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests == "Scan of jellyfin library Concerts was canceled") .ShouldBeTrue(); } + + [Test] + public async Task Should_Scan_All_Three_Kinds_For_Mixed_Libraries() + { + var scannerProxy = Substitute.For(); + var mediaSourceRepository = Substitute.For(); + var jellyfinSecretStore = Substitute.For(); + var jellyfinMovieLibraryScanner = Substitute.For(); + var jellyfinTelevisionLibraryScanner = Substitute.For(); + var jellyfinMusicVideoLibraryScanner = Substitute.For(); + var libraryRepository = Substitute.For(); + var configElementRepository = Substitute.For(); + + var library = new JellyfinLibrary + { + Id = 42, + Name = "Music Videos", + MediaKind = LibraryMediaKind.Mixed, + MediaSourceId = 7 + }; + var mediaSource = new JellyfinMediaSource + { + Id = 7, + Connections = + [ + new JellyfinConnection + { + Address = "http://jellyfin.example", + JellyfinMediaSourceId = 7 + } + ] + }; + + mediaSourceRepository.GetJellyfinByLibraryId(library.Id).Returns(Some(mediaSource).AsTask()); + mediaSourceRepository.GetJellyfinLibrary(library.Id).Returns(Some(library).AsTask()); + jellyfinSecretStore.ReadSecrets().Returns(new JellyfinSecrets + { + Address = "http://jellyfin.example", + ApiKey = "abc" + }); + configElementRepository.GetValue( + Arg.Is(key => key.Key == ConfigElementKey.LibraryRefreshInterval.Key), + Arg.Any()) + .Returns(Task.FromResult>(Some(0))); + + jellyfinMovieLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Right(Unit.Default).AsTask()); + jellyfinTelevisionLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Right(Unit.Default).AsTask()); + jellyfinMusicVideoLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Right(Unit.Default).AsTask()); + + var handler = new SynchronizeJellyfinLibraryByIdHandler( + scannerProxy, + mediaSourceRepository, + jellyfinSecretStore, + jellyfinMovieLibraryScanner, + jellyfinTelevisionLibraryScanner, + jellyfinMusicVideoLibraryScanner, + libraryRepository, + configElementRepository, + Substitute.For>()); + + Either result = await handler.Handle( + new SynchronizeJellyfinLibraryById("http://ersatztv.example", library.Id, true, true), + CancellationToken.None); + + result.LeftToSeq().ShouldBeEmpty(); + result.IsRight.ShouldBeTrue(); + result.RightToSeq().Single().ShouldBe("Music Videos"); + + await jellyfinMovieLibraryScanner.Received(1).ScanLibrary( + Arg.Any(), library, true, Arg.Any()); + await jellyfinTelevisionLibraryScanner.Received(1).ScanLibrary( + Arg.Any(), library, true, Arg.Any()); + await jellyfinMusicVideoLibraryScanner.Received(1).ScanLibrary( + Arg.Any(), library, true, Arg.Any()); + await libraryRepository.Received(1).UpdateLastScan(library); + } + + [Test] + public async Task Should_Run_Remaining_Scanners_When_One_Fails_For_Mixed_Libraries() + { + var scannerProxy = Substitute.For(); + var mediaSourceRepository = Substitute.For(); + var jellyfinSecretStore = Substitute.For(); + var jellyfinMovieLibraryScanner = Substitute.For(); + var jellyfinTelevisionLibraryScanner = Substitute.For(); + var jellyfinMusicVideoLibraryScanner = Substitute.For(); + var libraryRepository = Substitute.For(); + var configElementRepository = Substitute.For(); + + var library = new JellyfinLibrary + { + Id = 42, + Name = "Music Videos", + MediaKind = LibraryMediaKind.Mixed, + MediaSourceId = 7 + }; + var mediaSource = new JellyfinMediaSource + { + Id = 7, + Connections = + [ + new JellyfinConnection + { + Address = "http://jellyfin.example", + JellyfinMediaSourceId = 7 + } + ] + }; + + mediaSourceRepository.GetJellyfinByLibraryId(library.Id).Returns(Some(mediaSource).AsTask()); + mediaSourceRepository.GetJellyfinLibrary(library.Id).Returns(Some(library).AsTask()); + jellyfinSecretStore.ReadSecrets().Returns(new JellyfinSecrets + { + Address = "http://jellyfin.example", + ApiKey = "abc" + }); + configElementRepository.GetValue( + Arg.Is(key => key.Key == ConfigElementKey.LibraryRefreshInterval.Key), + Arg.Any()) + .Returns(Task.FromResult>(Some(0))); + + jellyfinMovieLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Left(BaseError.New("movie scan blew up")).AsTask()); + jellyfinTelevisionLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Right(Unit.Default).AsTask()); + jellyfinMusicVideoLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Right(Unit.Default).AsTask()); + + var handler = new SynchronizeJellyfinLibraryByIdHandler( + scannerProxy, + mediaSourceRepository, + jellyfinSecretStore, + jellyfinMovieLibraryScanner, + jellyfinTelevisionLibraryScanner, + jellyfinMusicVideoLibraryScanner, + libraryRepository, + configElementRepository, + Substitute.For>()); + + Either result = await handler.Handle( + new SynchronizeJellyfinLibraryById("http://ersatztv.example", library.Id, true, true), + CancellationToken.None); + + // the movie arm failed, so the library as a whole failed... + result.IsLeft.ShouldBeTrue(); + + // ...but the other two kinds were still ingested + await jellyfinTelevisionLibraryScanner.Received(1).ScanLibrary( + Arg.Any(), library, true, Arg.Any()); + await jellyfinMusicVideoLibraryScanner.Received(1).ScanLibrary( + Arg.Any(), library, true, Arg.Any()); + + // and LastScan is not stamped, because the scan was not fully successful + await libraryRepository.DidNotReceive().UpdateLastScan(Arg.Any()); + } + + [Test] + public async Task Should_Stop_Scanning_Mixed_Library_When_Canceled() + { + var scannerProxy = Substitute.For(); + var mediaSourceRepository = Substitute.For(); + var jellyfinSecretStore = Substitute.For(); + var jellyfinMovieLibraryScanner = Substitute.For(); + var jellyfinTelevisionLibraryScanner = Substitute.For(); + var jellyfinMusicVideoLibraryScanner = Substitute.For(); + var libraryRepository = Substitute.For(); + var configElementRepository = Substitute.For(); + + var library = new JellyfinLibrary + { + Id = 42, + Name = "Music Videos", + MediaKind = LibraryMediaKind.Mixed, + MediaSourceId = 7 + }; + var mediaSource = new JellyfinMediaSource + { + Id = 7, + Connections = + [ + new JellyfinConnection + { + Address = "http://jellyfin.example", + JellyfinMediaSourceId = 7 + } + ] + }; + + mediaSourceRepository.GetJellyfinByLibraryId(library.Id).Returns(Some(mediaSource).AsTask()); + mediaSourceRepository.GetJellyfinLibrary(library.Id).Returns(Some(library).AsTask()); + jellyfinSecretStore.ReadSecrets().Returns(new JellyfinSecrets + { + Address = "http://jellyfin.example", + ApiKey = "abc" + }); + configElementRepository.GetValue( + Arg.Is(key => key.Key == ConfigElementKey.LibraryRefreshInterval.Key), + Arg.Any()) + .Returns(Task.FromResult>(Some(0))); + + jellyfinMovieLibraryScanner.ScanLibrary( + Arg.Any(), library, true, Arg.Any()) + .Returns(Left(new ScanCanceled()).AsTask()); + + var handler = new SynchronizeJellyfinLibraryByIdHandler( + scannerProxy, + mediaSourceRepository, + jellyfinSecretStore, + jellyfinMovieLibraryScanner, + jellyfinTelevisionLibraryScanner, + jellyfinMusicVideoLibraryScanner, + libraryRepository, + configElementRepository, + Substitute.For>()); + + Either result = await handler.Handle( + new SynchronizeJellyfinLibraryById("http://ersatztv.example", library.Id, true, true), + CancellationToken.None); + + result.IsLeft.ShouldBeTrue(); + + // a user-initiated cancellation aborts the whole library; later kinds must not run + await jellyfinTelevisionLibraryScanner.DidNotReceive().ScanLibrary( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()); + await jellyfinMusicVideoLibraryScanner.DidNotReceive().ScanLibrary( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()); + await libraryRepository.DidNotReceive().UpdateLastScan(Arg.Any()); + } } } diff --git a/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinLibraryByIdHandler.cs b/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinLibraryByIdHandler.cs index efe0beb77..f5c480818 100644 --- a/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinLibraryByIdHandler.cs +++ b/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinLibraryByIdHandler.cs @@ -85,7 +85,10 @@ public class parameters.Library, parameters.DeepScan, cancellationToken), - _ => Unit.Default + LibraryMediaKind.Mixed => + await ScanMixedLibrary(parameters, cancellationToken), + _ => BaseError.New( + $"Jellyfin library {parameters.Library.Name} has unsupported media kind {parameters.Library.MediaKind}") }; if (result.IsRight) @@ -116,6 +119,73 @@ public class return parameters.Library.Name; } + /// + /// Scans a mixed-content library by running each per-kind scanner against it in turn. Jellyfin + /// resolves the mix server-side - each scanner queries with its own includeItemTypes - so the + /// passes see disjoint item sets, and their reconciliation is type-scoped and cannot + /// cross-delete. + /// + private async Task> ScanMixedLibrary( + RequestParameters parameters, + CancellationToken cancellationToken) + { + _logger.LogInformation( + "Scanning mixed-content jellyfin library {Name}", + parameters.Library.Name); + + var scans = new Func>>[] + { + () => _jellyfinMovieLibraryScanner.ScanLibrary( + parameters.ConnectionParameters, + parameters.Library, + parameters.DeepScan, + cancellationToken), + () => _jellyfinTelevisionLibraryScanner.ScanLibrary( + parameters.ConnectionParameters, + parameters.Library, + parameters.DeepScan, + cancellationToken), + () => _jellyfinMusicVideoLibraryScanner.ScanLibrary( + parameters.ConnectionParameters, + parameters.Library, + parameters.DeepScan, + cancellationToken) + }; + + var errors = new List(); + + foreach (Func>> scan in scans) + { + Either result = await scan(); + + foreach (BaseError error in result.LeftToSeq()) + { + // a cancellation aborts the whole library immediately; it is not one kind failing + if (error is ScanCanceled) + { + return error; + } + + // one kind failing must not stop the others from being ingested + _logger.LogWarning( + "Error scanning one media kind of mixed jellyfin library {Name}: {Error}", + parameters.Library.Name, + error.Value); + + errors.Add(error); + } + } + + if (errors.Count > 0) + { + return BaseError.New( + $"Mixed library {parameters.Library.Name} had {errors.Count} scan error(s): " + + string.Join("; ", errors.Map(e => e.Value))); + } + + return Unit.Default; + } + private async Task> Validate( SynchronizeJellyfinLibraryById request, CancellationToken cancellationToken) => diff --git a/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs b/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs index b40467b6f..c0e818001 100644 --- a/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs +++ b/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs @@ -48,9 +48,10 @@ public class RequestParameters parameters, CancellationToken cancellationToken) { - if (parameters.Library.MediaKind != LibraryMediaKind.Shows) + // a mixed library legitimately contains shows alongside movies and music videos + if (parameters.Library.MediaKind is not (LibraryMediaKind.Shows or LibraryMediaKind.Mixed)) { - return BaseError.New($"Library {parameters.Library.Name} is not a TV show library"); + return BaseError.New($"Library {parameters.Library.Name} does not contain TV shows"); } _scannerProxy.SetBaseUrl(parameters.BaseUrl); diff --git a/ErsatzTV.Scanner/Application/MediaSources/Commands/ScanLocalLibraryHandler.cs b/ErsatzTV.Scanner/Application/MediaSources/Commands/ScanLocalLibraryHandler.cs index 23a992d91..26f7bf8ec 100644 --- a/ErsatzTV.Scanner/Application/MediaSources/Commands/ScanLocalLibraryHandler.cs +++ b/ErsatzTV.Scanner/Application/MediaSources/Commands/ScanLocalLibraryHandler.cs @@ -139,7 +139,11 @@ public class ScanLocalLibraryHandler : IRequestHandler Unit.Default + + // returning success here would stamp LastScan as though the library had been + // scanned; a local library has no scanner for Mixed and never should + _ => BaseError.New( + $"Local library {localLibrary.Name} has unsupported media kind {localLibrary.MediaKind}") }; if (result.IsRight) -- 2.47.3 From e9b7fabb0b842bdce6f76c871ba6b7ac4a2a8495 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 01:06:24 +0200 Subject: [PATCH 03/10] chore(489): regenerate OpenAPI + typed client for LibraryMediaKind.Mixed Also audited MediaSourceRepository's rediscovery kind-rewrite (Plex/Jellyfin/ Emby, ~lines 182/253/335): it only rewrites MediaKind when ShouldSyncItems is false, and then only to what the media server currently reports. A Mixed library stays Mixed while Jellyfin still reports it mixed, and cannot be flipped at all once syncing is enabled. No code change needed. Refs #489 --- ErsatzTV/wwwroot/openapi/v1.json | 3 ++- web/src/api/generated/v1.d.ts | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/ErsatzTV/wwwroot/openapi/v1.json b/ErsatzTV/wwwroot/openapi/v1.json index b168e4324..422921ae5 100644 --- a/ErsatzTV/wwwroot/openapi/v1.json +++ b/ErsatzTV/wwwroot/openapi/v1.json @@ -27011,7 +27011,8 @@ "OtherVideos", "Songs", "Images", - "RemoteStreams" + "RemoteStreams", + "Mixed" ], "type": "string" }, diff --git a/web/src/api/generated/v1.d.ts b/web/src/api/generated/v1.d.ts index 5d5b8511e..c05d1c554 100644 --- a/web/src/api/generated/v1.d.ts +++ b/web/src/api/generated/v1.d.ts @@ -813,7 +813,7 @@ export interface components { "seasonId"?: null | number; }; "LibraryBrowseMediaType": "Movie" | "TelevisionShow" | "TelevisionSeason" | "Artist" | "Collection" | "SmartCollection" | "MultiCollection" | "RerunCollection" | "Playlist" | "Episode" | "MusicVideo" | "Song" | "OtherVideo" | "Image" | "RemoteStream"; - "LibraryMediaKind": "Movies" | "Shows" | "MusicVideos" | "OtherVideos" | "Songs" | "Images" | "RemoteStreams"; + "LibraryMediaKind": "Movies" | "Shows" | "MusicVideos" | "OtherVideos" | "Songs" | "Images" | "RemoteStreams" | "Mixed"; "LibraryScanStatusResponseModel": { "libraryId": number; "percent": number; -- 2.47.3 From 38342666d712a1f4b741e239433e1534afefceb0 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 01:07:07 +0200 Subject: [PATCH 04/10] docs(489): record the mixed-library decision and Jellyfin-only scope Refs #489 --- docs/decisions.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/decisions.md b/docs/decisions.md index e89069f2c..0f85d4dda 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -897,6 +897,7 @@ relabelled to reflect the #295 reality. Convention + hook documented in `spa-con implicit route-label ⟺ screen-subscription coupling is the kind of thing #247 (shell extraction) will formalize; #238 keeps it a documented convention guarded by a data-driven `App.test.tsx` test over the URL-navigating create screens (a typo'd route id → the banner navigates nowhere → red). Refs #238 #247. + ## 2026-07-13 — API versioning: the whole `/api` surface is mounted at `/api/v1`, additive-only after freeze (#286) The #197 cold review's C1 **BLOCKER**: `/api/*` was entirely unversioned (`info.version` was cosmetic), so the @@ -1214,6 +1215,7 @@ channel" has no reason to look under "Alternate Schedules", and on finding that Fixed with a task-shaped **"Recipe: seasonal / holiday programming"** section in `channels.md` (both engines, plus the gotchas above) and a `domain-model.md` glossary row. No production code changed, so no live-E2E (same reasoning as #77). + ## 2026-07-17 — Auto-Tune DetailPanel member list = live search-index roll-up, not EF enumeration (#384) The Auto-Tune DetailPanel (#383) shows, per proposed channel, the distinct **content sources** its @@ -1357,6 +1359,7 @@ not size the `small` lane expecting otherwise. **Not addressed here**: the 12–35 min queue waits (server-management#604) and the redundant triple-build (#398). + ## 2026-07-17 — Channel health on the API = the raw `PlayoutCount` fact on the list DTO, not a derived status enum (#72) #72 asks for per-channel status in the Channels list, "especially channels that will fail to play". @@ -1400,6 +1403,7 @@ Keeping all three out held #72 to a **read-path-only** change: no migration, no channel editor's playout-source guard. Both call sites now share `Mapper.GetPlayoutsCount` (Mirror-aware). The related *silent* server-side coercion of Mirror→Generated (a 200 that discards the caller's intent, against the §3 "surface it, don't silently filter" rule) is filed as **#401**, not fixed here. + ## 2026-07-17 — Weighted / fair-share distribution is a new `WeightedShuffle` order; `ShuffleInOrder` is anti-clumping, not fair-share (#70) `PlaybackOrder.WeightedShuffle = 9` ships the two behaviors #70 asked for — "air Show A 70% / Show B 30%" @@ -1535,6 +1539,7 @@ part — is skipped. Two adjacent redundancies are deliberately **out of scope**: the whole matrix re-running on a PR and again on the merge-to-`main` over identical code (#420), and the within-run triple `dotnet build` (#398). Full mechanism in `ci-cd.md` → "Docs-only skip". + ## 2026-07-17 — Docs-only detect must be shallow-checkout safe: FETCH_HEAD + two-dot, not origin/main + three-dot (#416 follow-up) The #416 docs-only skip shipped (#422) safe but **ineffective**: every docs-only PR still ran the full @@ -1550,6 +1555,7 @@ because they use `fetch-depth: 0` — a difference the first cut missed. Meta-le gating change can pass every local test and merge green while being a complete no-op in CI; only real-PR verification that **measures the effect** (job durations, not just a green check) catches it — which is exactly what #416's Done-when demanded. Fixed in the #416 follow-up PR. + ## 2026-07-17 — Pre-push guard: don't push a file whose working-tree copy is uncommitted (H13, #416 session) A review fix (`--no-renames`) was edited into the working file and empirically verified there, but a @@ -1614,6 +1620,7 @@ shipped here; the rest is deliberately deferred rather than forced. materialization — neither is the additive plumbing this slice was scoped to, and it is a channel-wide capability rather than an auto-tune concern. Left for its own issue / the SPA branding work; the uploaded `logo` above already covers the on-screen bug for channels that supply an image. + ## 2026-07-17 — Health-check remediation is server-declared `{Kind, Target}` on an additive DTO; the SPA acts on it (#164) #164 asked to make the ~14 health checks *actionable* — the Dashboard health panel showed problems @@ -1722,6 +1729,7 @@ index actually supports. for value inputs, relative-date operators, nesting deeper than one level, and inline adoption of `RuleBuilder` by ChannelBuilder / Auto-Tune (it was built reusable for exactly that reuse — see `spa-conventions.md` §12). + ## 2026-07-18 — Auto-Tune per-source weights ride #70's MultiCollection machinery; created at tune time, not a post-hoc PUT (#425) Per-source rotation weights (`3× Show A, 1× Show B`) and query corrections (exclude / add-untagged) for @@ -1889,6 +1897,7 @@ the three still-**silent** build-time dispatch sites — the ones this issue nam `SeasonEpisodeMediaCollectionEnumerator`) that simply aren't reverse-mapped, so making it "loud" would emit false-positive warnings. Completing that reverse map is a separate concern from "an unsupported *order* degrades silently" and is not part of #403's scope. + ## 2026-07-18 — CI build-once was measured and rejected; keep the #420 tree-skip Build-once (a `compile` job producing a single artifact, consumed by `test`/`migrations`/ @@ -2081,6 +2090,7 @@ Disabling the servers is worth it (consistent reduction, no resident server), bu off the live test-job peak-anon this instrument now reports, not off the build-only A/B. The older #411 probe (`anon 7134 MiB`) read higher than these swap-off sampled numbers and is superseded (swap/read-method move the figure >1 GiB). + ## 2026-07-19 — Media-server remote-stream URLs are probed before use: a redirected 404 fails closed, everything else fails open, no toggle (#473) `GetPlayoutItemProcessByChannelNumberHandler.ValidatePlayoutItemPath` now probes the Plex/Jellyfin/Emby @@ -2290,3 +2300,46 @@ media-server identity those base scanners rely on. SQLite, extending the #488 harness) pin removal, empty-artist cleanup, cross-kind safety, and the empty-fetch guard. Proven non-vacuous: all four fail against the pre-fix scanner except the guard control, which only earns its keep once the sweep exists. + +## 2026-07-20 (#489) — Jellyfin mixed-content libraries map to one library holding many kinds + +A Jellyfin library whose collection type is `mixed` — or absent — now maps to `LibraryMediaKind.Mixed` +instead of being dropped by `JellyfinApiClient.Project()`'s `_ => None`. Scanning it runs the movie, +television and music-video scanners in sequence against that one library. + +- **A library is a place, not a media kind.** One physical path ↔ one Jellyfin library ↔ one ErsatzTV + library, whose contents are heterogeneous. This is what keeps music and standup content segregated from + the main `Movies` and `TV Shows` libraries, which was the actual goal (#474). The previous workaround was + a *local* library pointed at the same tree, which bypassed Jellyfin, scanned the content twice and + mis-modelled shows as movies. +- **The classification is Jellyfin's, not ours.** Each scanner queries `parentId` + `includeItemTypes` + (`"Movie"` / `"Series"` / `"MusicVideo"`), so the three passes receive disjoint, authoritative sets. + Nothing is inferred from folder shape or NFO contents. This is why mixed support is tractable at all — an + earlier reading that it would require guessing per item was wrong. +- **No migration.** `MediaItem` is table-per-type with no discriminator and `LibraryPathId` on the abstract + base, so heterogeneous items under one `LibraryPath` were always legal; + `MediaItemRepository.GetAllTrashedItems` already `COALESCE`s across every subclass id for a single path. +- **No cross-deletion.** Reconciliation is type-scoped (`GetExistingMovies(library)` and friends), so a pass + over one kind cannot trash another kind's items in the same library. +- **`MediaKind` is dispatch + presentation only.** Scheduling, playout, collections, smart collections and + search hold zero references to it; search keys off the item's own subclass and the SPA's browse screens + use a per-item `LibraryBrowseMediaType`. Adding a kind is therefore cheap. + +**Deliberately scoped to Jellyfin. Local mixed libraries are NOT supported** and `Mixed` is absent from the +SPA's local-library media-kind options. Locally the same approach is unsafe: every local scanner shares +`LocalFolderScanner.VideoFileExtensions`, so the movie scanner would claim episode files, and `LibraryFolder` +rows are keyed by `LibraryPathId` with no notion of kind, so two scanners over one path would thrash each +other's etags. Neither hazard exists remotely — among the remote scanners only +`JellyfinMusicVideoLibraryScanner` touches `LibraryFolder` at all. (The existing `Images` + `OtherVideos` +shared-path exemption in `LocalLibraryHandlerBase.AreSubPaths` is the closest local analogue, and it already +carries that etag contention.) + +**Failure semantics of the `Mixed` arm**: one kind failing does *not* skip the others — a broken music-video +scan must not prevent the movies in the same library from being ingested — but the library as a whole then +reports failure and `LastScan` is not stamped. `ScanCanceled` aborts the sequence immediately, since a user +cancellation is not one kind failing. + +**Also fixed here**: `ScanLocalLibraryHandler` and `SynchronizeJellyfinLibraryByIdHandler` both ended their +dispatch switch with `_ => Unit.Default`, returning **success** for an unhandled kind and stamping `LastScan` +as though a scan had run. Both now return a `BaseError`. That silent success is precisely how a missing +`Mixed` arm would have hidden, so removing it is part of the feature, not a drive-by. -- 2.47.3 From 6b05a2a40c908356262c9a00e6c4943e1d54eaa6 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 01:16:49 +0200 Subject: [PATCH 05/10] style(489): strip UTF-8 BOM from the .cs files this PR touches The #311 formatting gate is fix-as-you-touch: charset=utf-8 means no BOM, so a legacy file's inherited BOM becomes this PR's problem once the PR edits it. Zero content change. Refs #489 --- ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs | 2 +- ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs b/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs index 922c92000..934b46c88 100644 --- a/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs +++ b/ErsatzTV.Core/Domain/Library/LibraryMediaKind.cs @@ -1,4 +1,4 @@ -namespace ErsatzTV.Core.Domain; +namespace ErsatzTV.Core.Domain; public enum LibraryMediaKind { diff --git a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs index 28ada76b9..f84f75122 100644 --- a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs +++ b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs @@ -1,4 +1,4 @@ -using System.Globalization; +using System.Globalization; using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Interfaces.Jellyfin; -- 2.47.3 From f916695e15ca1b0147c146b83d9ff21943fc45f1 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 01:46:58 +0200 Subject: [PATCH 06/10] =?UTF-8?q?fix(489):=20address=20adversarial=20revie?= =?UTF-8?q?w=20=E2=80=94=20enforce=20the=20local-Mixed=20invariant,=20hand?= =?UTF-8?q?le=20blank=20CollectionType?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review verdict was MERGEABLE; these are the findings worth fixing before merge. M1 (the one gating finding): LibraryMediaKind.Mixed was accepted by POST /api/v1/libraries/local. That created a library with no scanner, which then failed every scan forever and logged at ERROR on each scheduler tick. The invariant was asserted in prose twice and enforced nowhere -- and hiding it from the SPA dropdown is not enforcement, since machine clients are a stated audience for /api/v1. Now validated in CreateLocalLibraryHandler. M3: an empty or whitespace CollectionType did not match the `null` pattern and fell through to None, so on Jellyfin versions that serialize it that way the whole feature silently no-opped -- no library, no log line. Normalized via IsNullOrWhiteSpace, covered by a TestCase for "" and " ". L4: the cancellation test asserted IsLeft but not that ScanCanceled reaches the caller's info-log branch. That is the fragile bit -- folding it into an aggregate BaseError would silently demote a user cancellation to an ERROR log (#410). Now pinned in both directions. Nit: reverted the show-guard message to match the byte-identical Plex/Emby guards; the original wording is still accurate since the guard only fires when the kind is neither Shows nor Mixed. Also documented three accepted limitations in decisions.md (progress bar resets per kind, one failing kind forces the others to rescan, and the fact that the music-video scanner does no reconciliation at all -- which is why it cannot cross-delete, but also means removals never propagate). Negative controls: reverting the M1 validation fails its test; reverting the projection/dispatch fails theirs. Refs #489 --- .../Commands/CreateLocalLibraryHandler.cs | 14 ++++++++ .../Jellyfin/JellyfinApiClientTests.cs | 35 +++++++++++++++++++ .../Jellyfin/JellyfinApiClient.cs | 4 ++- ...chronizeJellyfinLibraryByIdHandlerTests.cs | 16 ++++++++- .../SynchronizeJellyfinShowByIdHandler.cs | 2 +- .../CreateLocalLibraryHandlerTests.cs | 22 ++++++++++++ docs/decisions.md | 18 ++++++++++ 7 files changed, 108 insertions(+), 3 deletions(-) diff --git a/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs b/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs index 0f5976a34..1f12b1112 100644 --- a/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs +++ b/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs @@ -70,9 +70,23 @@ public class CreateLocalLibraryHandler : LocalLibraryHandlerBase, CreateLocalLibrary request) => MediaSourceMustExist(dbContext, request) .BindT(localLibrary => NameMustBeValid(request, localLibrary)) + .BindT(MediaKindMustBeSupportedLocally) .BindT(localLibrary => PathsMustBeValid(dbContext, localLibrary)) .BindT(localLibrary => NewPathsMustExist(fileSystem, localLibrary)); + /// + /// Mixed is only ever produced for remote (Jellyfin) libraries, where the media server classifies + /// each item for us. No local folder scanner handles it, so a local Mixed library would fail every + /// scan forever. The API takes a raw LibraryMediaKind, so this must be enforced here rather than + /// left to the SPA's media-kind options. + /// + private static Validation MediaKindMustBeSupportedLocally( + LocalLibrary localLibrary) => + localLibrary.MediaKind is LibraryMediaKind.Mixed + ? BaseError.New( + "Local libraries cannot use the Mixed media kind; it is only valid for Jellyfin libraries.") + : localLibrary; + private static Task> MediaSourceMustExist( TvContext dbContext, CreateLocalLibrary request) => diff --git a/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs b/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs index 766955291..2dc74150d 100644 --- a/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs +++ b/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs @@ -122,6 +122,41 @@ public class JellyfinApiClientTests libraries[0].MediaKind.ShouldBe(LibraryMediaKind.Mixed); } + // Jellyfin serializes "no content type" as absent, empty or whitespace depending on version; + // all three mean mixed content, so all three must project identically. + [TestCase("\"CollectionType\": \"\",")] + [TestCase("\"CollectionType\": \" \",")] + public async Task Should_Project_Libraries_With_Blank_CollectionType_As_Mixed(string collectionTypeLine) + { + string response = $$""" + [ + { + "Name": "Standup", + {{collectionTypeLine}} + "ItemId": "library-12", + "LibraryOptions": { + "PathInfos": [] + } + } + ] + """; + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + Substitute.For(), + Substitute.For(), + new SingleResponseHttpClientFactory(response), + Substitute.For>()); + + Either> result = + await client.GetLibraries("http://jellyfin.example", "MediaBrowser Token=abc"); + + result.IsRight.ShouldBeTrue(); + List libraries = result.RightToSeq().Single(); + libraries.Count.ShouldBe(1); + libraries[0].MediaKind.ShouldBe(LibraryMediaKind.Mixed); + } + // Guard: mixed must not become a catch-all. Jellyfin "music" (audio) libraries have no // supported scanner, so they must keep falling through to None. [Test] diff --git a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs index f84f75122..55930f11c 100644 --- a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs +++ b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs @@ -435,7 +435,9 @@ public class JellyfinApiClient : IJellyfinApiClient } private Option Project(JellyfinLibraryResponse response) => - response.CollectionType?.ToLowerInvariant() switch + // normalize "no content type" to null: Jellyfin serializes a mixed library's collection type + // as absent, empty or whitespace depending on server version, and all three mean the same thing + (string.IsNullOrWhiteSpace(response.CollectionType) ? null : response.CollectionType.ToLowerInvariant()) switch { "tvshows" => new JellyfinLibrary { diff --git a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs index 54560d07c..80475b7fc 100644 --- a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs +++ b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs @@ -383,6 +383,8 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests Arg.Any()) .Returns(Task.FromResult>(Some(0))); + var logger = Substitute.For>(); + jellyfinMovieLibraryScanner.ScanLibrary( Arg.Any(), library, true, Arg.Any()) .Returns(Left(new ScanCanceled()).AsTask()); @@ -396,7 +398,7 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests jellyfinMusicVideoLibraryScanner, libraryRepository, configElementRepository, - Substitute.For>()); + logger); Either result = await handler.Handle( new SynchronizeJellyfinLibraryById("http://ersatztv.example", library.Id, true, true), @@ -416,6 +418,18 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests Arg.Any(), Arg.Any()); await libraryRepository.DidNotReceive().UpdateLastScan(Arg.Any()); + + // ScanMixedLibrary must return the ScanCanceled INSTANCE unwrapped, not folded into an + // aggregate BaseError -- otherwise `error is ScanCanceled` in the caller fails and a user + // cancellation is demoted to an ERROR log (#410). + logger.ReceivedCalls() + .Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString() + == "Scan of jellyfin library Music Videos was canceled") + .ShouldBeTrue(); + logger.ReceivedCalls() + .Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString() + == "Error synchronizing jellyfin library: Scan was canceled") + .ShouldBeFalse(); } } } diff --git a/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs b/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs index c0e818001..27c2de30f 100644 --- a/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs +++ b/ErsatzTV.Scanner/Application/Jellyfin/Commands/SynchronizeJellyfinShowByIdHandler.cs @@ -51,7 +51,7 @@ public class // a mixed library legitimately contains shows alongside movies and music videos if (parameters.Library.MediaKind is not (LibraryMediaKind.Shows or LibraryMediaKind.Mixed)) { - return BaseError.New($"Library {parameters.Library.Name} does not contain TV shows"); + return BaseError.New($"Library {parameters.Library.Name} is not a TV show library"); } _scannerProxy.SetBaseUrl(parameters.BaseUrl); diff --git a/ErsatzTV.Tests/Application/Libraries/CreateLocalLibraryHandlerTests.cs b/ErsatzTV.Tests/Application/Libraries/CreateLocalLibraryHandlerTests.cs index 47d2b4a58..3a11f664a 100644 --- a/ErsatzTV.Tests/Application/Libraries/CreateLocalLibraryHandlerTests.cs +++ b/ErsatzTV.Tests/Application/Libraries/CreateLocalLibraryHandlerTests.cs @@ -42,6 +42,28 @@ public class CreateLocalLibraryHandlerTests result.IfLeft(error => error.Value.ShouldContain("/media/movies")); } + // LibraryMediaKind.Mixed exists only for remote (Jellyfin) libraries, where the media server + // classifies each item. No local folder scanner handles it, so a local Mixed library would fail + // every scan forever and log at ERROR on every scheduler tick. The API takes a raw + // LibraryMediaKind, so hiding it from the SPA dropdown is not enforcement (#489 review M1). + [Test] + public async Task Handle_Should_Reject_The_Mixed_Media_Kind_For_Local_Libraries() + { + await SeedLocalMediaSource(); + + var fileSystem = new MockFileSystem(); + fileSystem.Directory.CreateDirectory("/media/music"); + + CreateLocalLibraryHandler handler = CreateHandler(fileSystem); + + Either result = await handler.Handle( + new CreateLocalLibrary("Music", LibraryMediaKind.Mixed, ["/media/music"]), + CancellationToken.None); + + result.IsLeft.ShouldBeTrue(); + result.IfLeft(error => error.Value.ShouldContain("Mixed")); + } + [Test] public async Task Handle_Should_List_Only_The_Missing_Paths_When_Mixed() { diff --git a/docs/decisions.md b/docs/decisions.md index 0f85d4dda..a6208807f 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -2343,3 +2343,21 @@ cancellation is not one kind failing. dispatch switch with `_ => Unit.Default`, returning **success** for an unhandled kind and stamping `LastScan` as though a scan had run. Both now return a `BaseError`. That silent success is precisely how a missing `Mixed` arm would have hidden, so removing it is part of the feature, not a drive-by. + +**Known limitations of the `Mixed` arm**, surfaced by the adversarial review and accepted rather than +fixed here: + +- **Scan progress resets twice.** Each per-kind scanner independently drives `_scannerProxy.UpdateProgress` + from 0 to 1 over its own item set, so a mixed library's progress bar fills and resets three times. The + local scanner solves this by threading `progressMin`/`progressMax` per path (`ScanLocalLibraryHandler`), + but the Jellyfin `ScanLibrary` signature has no such parameter, so fixing it means changing three scanner + interfaces. Cosmetic, and deliberately out of scope. +- **One permanently-failing kind forces the healthy kinds to rescan forever.** `ScanMixedLibrary` returns + `Left` if any arm failed, so `LastScan` is never stamped and the whole library re-scans every interval. + Single-kind libraries already behave this way; `Mixed` widens the blast radius to the other two kinds. + Accepted: the alternative — stamping `LastScan` on partial success — would silently mask a broken kind, + which is worse. +- **`JellyfinMusicVideoLibraryScanner` performs no reconciliation at all** — no `GetExisting*`, no trash + sweep. This is *why* it cannot cross-delete in a mixed library, but it also means a music video removed + from Jellyfin is never removed from ErsatzTV. Pre-existing and orthogonal to this change; it belongs with + that scanner's other gaps (no `ItemId`/`Etag`, path-keyed identity — see #488). -- 2.47.3 From bee4a42042d659ffdaab7bc3426e07b5f9f73206 Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 01:57:26 +0200 Subject: [PATCH 07/10] style(489): strip inherited UTF-8 BOM from CreateLocalLibraryHandler.cs Missed by my own BOM check, which used `git diff origin/main...HEAD` and so only saw COMMITTED files -- this one was still uncommitted at the time. Use `git diff origin/main` (no ...HEAD) so the working tree is included. Caught by the format gate: CHARSET error, .editorconfig sets charset=utf-8 (no BOM). Zero content change. Refs #489 --- .../Libraries/Commands/CreateLocalLibraryHandler.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs b/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs index 1f12b1112..e91d14c3e 100644 --- a/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs +++ b/ErsatzTV.Application/Libraries/Commands/CreateLocalLibraryHandler.cs @@ -1,4 +1,4 @@ -using System.IO.Abstractions; +using System.IO.Abstractions; using System.Threading.Channels; using ErsatzTV.Application.MediaSources; using ErsatzTV.Core; -- 2.47.3 From 6a1bffb6835550c84a217a3a63fd2a9008e3782e Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 02:16:09 +0200 Subject: [PATCH 08/10] fix(489): re-review follow-ups + stabilize a CI-only SPA flake Re-review of the fix commits returned MERGEABLE with two Low findings; both fixed here. L-1: my ScanCanceled negative log assertion was VACUOUS. It matched the rendered message by equality, but the regression it claims to pin (folding ScanCanceled into the aggregate error) produces a DIFFERENT string -- so the assertion stayed false either way and could never fail. Now a prefix match. Proven non-vacuous: neutralizing the early-return makes the test fail, which it did not do before. L-2: v1.json publishes Mixed as a legal LibraryMediaKind, and that enum is the request type for POST /api/v1/libraries/local, which now 422s on it. Machine clients are a stated audience for /api/v1, so an unexplained 422 is a real DX defect. Documented via EndpointDescription; OpenAPI regenerated. Unrelated to this feature: LibrariesScreen.test.tsx's '#447' waitFor calls used the 1000ms default, which is ample locally (~1s for the file) but marginal on the CI VM, where the SPA suite runs ~8x slower (98s vs 12s). It failed there on run 889 -- on a diff whose ONLY web change is one line of generated .d.ts, i.e. types erased at runtime, with LibrariesScreen untouched. A diff that cannot cause a failure is evidence the failure isn't the diff's. Bumped those two waits per-test rather than raising the global default. Refs #489 --- ...chronizeJellyfinLibraryByIdHandlerTests.cs | 5 ++++- .../Api/LocalLibrariesController.cs | 4 ++++ ErsatzTV/wwwroot/openapi/v1.json | 1 + web/src/screens/LibrariesScreen.test.tsx | 22 ++++++++++++++----- 4 files changed, 25 insertions(+), 7 deletions(-) diff --git a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs index 80475b7fc..685841b1e 100644 --- a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs +++ b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs @@ -426,9 +426,12 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests .Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString() == "Scan of jellyfin library Music Videos was canceled") .ShouldBeTrue(); + // prefix match, not equality: if ScanCanceled were folded into the aggregate error the + // rendered message becomes "...: Mixed library X had 1 scan error(s): Scan was canceled", + // which an equality assertion would NOT catch -- making the check vacuous logger.ReceivedCalls() .Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString() - == "Error synchronizing jellyfin library: Scan was canceled") + ?.StartsWith("Error synchronizing jellyfin library:", StringComparison.Ordinal) == true) .ShouldBeFalse(); } } diff --git a/ErsatzTV/Controllers/Api/LocalLibrariesController.cs b/ErsatzTV/Controllers/Api/LocalLibrariesController.cs index d6ad63d31..6b44a7f6c 100644 --- a/ErsatzTV/Controllers/Api/LocalLibrariesController.cs +++ b/ErsatzTV/Controllers/Api/LocalLibrariesController.cs @@ -55,6 +55,10 @@ public class LocalLibrariesController( [HttpPost("/api/v1/libraries/local")] [Tags("Libraries")] [EndpointSummary("Create a local library")] + [EndpointDescription( + "The shared LibraryMediaKind enum includes Mixed, but it is rejected here with 422. Mixed exists " + + "only for Jellyfin libraries, where the media server classifies each item; no local folder " + + "scanner handles it.")] [ProducesResponseType(typeof(LocalLibraryResponseModel), StatusCodes.Status201Created)] [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)] public async Task Create( diff --git a/ErsatzTV/wwwroot/openapi/v1.json b/ErsatzTV/wwwroot/openapi/v1.json index 422921ae5..e0c8ec4d3 100644 --- a/ErsatzTV/wwwroot/openapi/v1.json +++ b/ErsatzTV/wwwroot/openapi/v1.json @@ -9514,6 +9514,7 @@ "Libraries" ], "summary": "Create a local library", + "description": "The shared LibraryMediaKind enum includes Mixed, but it is rejected here with 422. Mixed exists only for Jellyfin libraries, where the media server classifies each item; no local folder scanner handles it.", "operationId": "LocalLibrariesCreate", "requestBody": { "content": { diff --git a/web/src/screens/LibrariesScreen.test.tsx b/web/src/screens/LibrariesScreen.test.tsx index 23d8c34e1..5165bb164 100644 --- a/web/src/screens/LibrariesScreen.test.tsx +++ b/web/src/screens/LibrariesScreen.test.tsx @@ -283,12 +283,22 @@ describe('LibrariesScreen', () => { // few microtask ticks after runPollTick's `act(async () => ...)` callback has already resolved. // Asserting synchronously right after the tick races that chain (#447); waitFor lets both // settle before asserting, without weakening either check. - await waitFor(() => { - expect(screen.queryByText('75%')).not.toBeInTheDocument(); - }); - await waitFor(() => { - expect(fetchCount(handle, '/api/v1/media-sources')).toBe(sourceFetchesBeforeCompletion + 1); - }); + // Explicit timeouts: waitFor defaults to 1000ms, ample locally (this file runs in ~1s) but + // marginal on the CI VM, where the SPA suite runs ~8x slower under load. Observed failing there + // on a types-only diff that cannot affect this screen. Bump per-test rather than raising the + // global default, so a genuinely slow assertion elsewhere still fails fast. + await waitFor( + () => { + expect(screen.queryByText('75%')).not.toBeInTheDocument(); + }, + { timeout: 10000 } + ); + await waitFor( + () => { + expect(fetchCount(handle, '/api/v1/media-sources')).toBe(sourceFetchesBeforeCompletion + 1); + }, + { timeout: 10000 } + ); }); it('reconciles a 409 "already scanning" against scan-status without an error toast (#232)', async () => { -- 2.47.3 From 39966ec616f80404fc43e9873e407132e961ee1e Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 17:41:16 +0200 Subject: [PATCH 09/10] =?UTF-8?q?fix(489):=20round-3=20review=20=E2=80=94?= =?UTF-8?q?=20make=20the=20waitFor=20bump=20actually=20reachable?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit M-1: the {timeout: 10000} I added was unreachable. vitest defaults testTimeout to 5000ms and web/vite.config.ts does not override it, so the whole it() dies at 5s -- and it dies with a generic 'Test timed out in 5000ms' carrying NO assertion diff, which is strictly worse diagnostics than the 1000ms default it replaced. A partial fix that degrades the failure message. Fixed using the repo's established pattern, which I had diverged from without stating a reason: a test-level timeout (}, 15000) as in TrashScreen.test.tsx (run 686) and CollectionsScreen.test.tsx, with the per-waitFor timeouts set below that budget so waitFor -- not vitest -- is what reports the failure. L-a: the comment claimed headroom the test could not have. Rewritten to state the constraint (per-waitFor must stay under the test budget) rather than a number that was false. N-a: made the sibling negative log assertion a prefix match too. The reviewer confirmed equality was exact and non-vacuous there, so this is consistency, not a correctness fix -- two assertions checking the same property should not differ in form. Refs #489 --- ...ynchronizeJellyfinLibraryByIdHandlerTests.cs | 4 +++- web/src/screens/LibrariesScreen.test.tsx | 17 ++++++++++------- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs index 685841b1e..fbce38d62 100644 --- a/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs +++ b/ErsatzTV.Scanner.Tests/Application/Jellyfin/SynchronizeJellyfinLibraryByIdHandlerTests.cs @@ -165,9 +165,11 @@ public class SynchronizeJellyfinLibraryByIdHandlerTests // a user-initiated cancellation is not a failure and must not be logged at ERROR (#410) await libraryRepository.DidNotReceive().UpdateLastScan(Arg.Any()); + // prefix match, matching the mixed-library test below: equality would still be exact for + // this single-kind path, but a prefix cannot be quietly defeated by a reworded error logger.ReceivedCalls() .Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString() - == "Error synchronizing jellyfin library: Scan was canceled") + ?.StartsWith("Error synchronizing jellyfin library:", StringComparison.Ordinal) == true) .ShouldBeFalse(); logger.ReceivedCalls() .Any(call => call.GetArguments().ElementAtOrDefault(2)?.ToString() diff --git a/web/src/screens/LibrariesScreen.test.tsx b/web/src/screens/LibrariesScreen.test.tsx index 5165bb164..b8cc5599a 100644 --- a/web/src/screens/LibrariesScreen.test.tsx +++ b/web/src/screens/LibrariesScreen.test.tsx @@ -283,23 +283,26 @@ describe('LibrariesScreen', () => { // few microtask ticks after runPollTick's `act(async () => ...)` callback has already resolved. // Asserting synchronously right after the tick races that chain (#447); waitFor lets both // settle before asserting, without weakening either check. - // Explicit timeouts: waitFor defaults to 1000ms, ample locally (this file runs in ~1s) but - // marginal on the CI VM, where the SPA suite runs ~8x slower under load. Observed failing there - // on a types-only diff that cannot affect this screen. Bump per-test rather than raising the - // global default, so a genuinely slow assertion elsewhere still fails fast. + // waitFor's 1000ms default is ample locally (this file runs in ~1s) but marginal on the CI VM, + // where the SPA suite runs ~8x slower under load — observed failing there on a types-only diff + // that cannot affect this screen. The per-waitFor timeout must stay under the test-level budget + // below, or the test dies on vitest's timeout with no assertion diff instead of waitFor's. await waitFor( () => { expect(screen.queryByText('75%')).not.toBeInTheDocument(); }, - { timeout: 10000 } + { timeout: 5000 } ); await waitFor( () => { expect(fetchCount(handle, '/api/v1/media-sources')).toBe(sourceFetchesBeforeCompletion + 1); }, - { timeout: 10000 } + { timeout: 5000 } ); - }); + // Generous test timeout: vitest defaults to 5s for the whole test, which the two waits above + // would otherwise share with render + findByText + runPollTick. Same pattern and reason as + // TrashScreen.test.tsx (run 686) and CollectionsScreen.test.tsx. + }, 15000); it('reconciles a 409 "already scanning" against scan-status without an error toast (#232)', async () => { mockApi({ -- 2.47.3 From bf48b64ad5feb40e848e59338b03c01755a962df Mon Sep 17 00:00:00 2001 From: Timothy Date: Mon, 20 Jul 2026 18:14:11 +0200 Subject: [PATCH 10/10] test(489): widen the LibrariesScreen test budget to 20s Round-4 review (Low): 2 x 5s waits plus a CI-slowed render/findByText/ runPollTick prelude comes to ~13-14s against a 15s budget, so the generic vitest-timeout failure mode was made unlikely rather than eliminated. Took the reviewer's suggested 20s budget, which leaves real headroom and keeps waitFor -- not vitest -- as the thing that reports a failure. Also correcting a claim in the previous commit message: CollectionsScreen.test.tsx uses the options-object form it(name, {timeout}, fn), not the trailing-number form; only TrashScreen.test.tsx:172 matches literally. Both are test-level timeouts so the substance was right, but the citation was not. Refs #489 --- web/src/screens/LibrariesScreen.test.tsx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/web/src/screens/LibrariesScreen.test.tsx b/web/src/screens/LibrariesScreen.test.tsx index b8cc5599a..8218d50f5 100644 --- a/web/src/screens/LibrariesScreen.test.tsx +++ b/web/src/screens/LibrariesScreen.test.tsx @@ -300,9 +300,11 @@ describe('LibrariesScreen', () => { { timeout: 5000 } ); // Generous test timeout: vitest defaults to 5s for the whole test, which the two waits above - // would otherwise share with render + findByText + runPollTick. Same pattern and reason as - // TrashScreen.test.tsx (run 686) and CollectionsScreen.test.tsx. - }, 15000); + // would otherwise share with render + findByText + runPollTick. Budgeted so the waits cannot + // exhaust it: 2 x 5s of waits plus a CI-slowed prelude still leaves headroom at 20s, so a + // failure is reported by waitFor (with an assertion diff) rather than by vitest's generic + // timeout. Same reason as TrashScreen.test.tsx (run 686) and CollectionsScreen.test.tsx. + }, 20000); it('reconciles a 409 "already scanning" against scan-status without an error toast (#232)', async () => { mockApi({ -- 2.47.3