From e3645a2840ca45f1d14cb2aa63bbf9cd9b44c573 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 25 Jul 2026 14:41:19 +0200 Subject: [PATCH 1/3] feat(484): suppress the media-server sweep on projection failures; reject the ratio threshold MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends MediaServerReconciliationGuard (#477) with a second deterministic refusal: when the enumeration that produced the incoming set silently dropped items whose projection THREW, the file-not-found sweep is refused. A dropped item the server did return is indistinguishable from a deletion at the reconcile step, so a projection regression could otherwise mass-flag a healthy library FileNotFound (which EmptyTrash then deletes permanently). Deliberate guard-clause skips (STRM files, virtual items, unsupported types) are explicitly NOT failures and never suppress a sweep — counting them would permanently disable reconciliation for any library holding a single STRM file. The ratio / missing-fraction threshold is REJECTED, not deferred: it is a two-sided heuristic with no tunable default and no telemetry, and the failure it approximates is exactly observable via the projection-failure count (a genuine bulk deletion produces zero failures). Seam is deliberately narrow — the private ProjectTo* contract inside each api client changed from Option to MediaServerProjectionResult (projected/skipped/failed), the paged helper counts IsFailure in one place, and the scanner reads it through an optional trailing MediaServerProjectionFailureCounter on only the five library-level methods that feed a sweep. The counter is per-enumeration state created by the scanner, never a field on an api client. fixes #484 --- .../Interfaces/Emby/IEmbyApiClient.cs | 18 +- .../Interfaces/Jellyfin/IJellyfinApiClient.cs | 15 +- .../MediaServerProjectionFailureCounter.cs | 23 ++ .../Metadata/MediaServerProjectionResult.cs | 49 ++++ .../Jellyfin/JellyfinApiClientTests.cs | 215 ++++++++++++++++++ ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs | 92 +++++--- .../Jellyfin/JellyfinApiClient.cs | 119 ++++++---- .../MediaServerMovieLibraryScannerTests.cs | 4 +- ...ediaServerOtherVideoLibraryScannerTests.cs | 4 +- .../MediaServerReconciliationGuardTests.cs | 87 ++++++- ...ediaServerTelevisionLibraryScannerTests.cs | 59 ++++- .../Core/Emby/EmbyMovieLibraryScanner.cs | 8 +- .../Core/Emby/EmbyTelevisionLibraryScanner.cs | 11 +- .../Jellyfin/JellyfinMovieLibraryScanner.cs | 8 +- .../JellyfinMusicVideoLibraryScanner.cs | 22 +- .../JellyfinTelevisionLibraryScanner.cs | 8 +- .../MediaServerMovieLibraryScanner.cs | 21 +- .../MediaServerOtherVideoLibraryScanner.cs | 18 +- .../MediaServerReconciliationGuard.cs | 38 +++- .../MediaServerTelevisionLibraryScanner.cs | 26 ++- .../Core/Plex/PlexMovieLibraryScanner.cs | 5 +- .../Core/Plex/PlexOtherVideoLibraryScanner.cs | 5 +- .../Core/Plex/PlexTelevisionLibraryScanner.cs | 7 +- .../JellyfinMusicVideoLibraryScannerTests.cs | 12 +- docs/decisions.md | 72 ++++++ docs/decisions/README.md | 1 + 26 files changed, 829 insertions(+), 118 deletions(-) create mode 100644 ErsatzTV.Core/Metadata/MediaServerProjectionFailureCounter.cs create mode 100644 ErsatzTV.Core/Metadata/MediaServerProjectionResult.cs diff --git a/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs b/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs index 62d70b520..42802fcb0 100644 --- a/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs +++ b/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs @@ -1,5 +1,6 @@ -using ErsatzTV.Core.Domain; +using ErsatzTV.Core.Domain; using ErsatzTV.Core.Emby; +using ErsatzTV.Core.Metadata; namespace ErsatzTV.Core.Interfaces.Emby; @@ -8,9 +9,20 @@ public interface IEmbyApiClient Task> GetServerInformation(string address, string apiKey); Task>> GetLibraries(string address, string apiKey); - IAsyncEnumerable> GetMovieLibraryItems(string address, string apiKey, EmbyLibrary library); + // #484: the two library-level enumerations that feed a reconciliation sweep accept an optional + // per-enumeration counter. The caller creates one instance per enumeration and reads it only after + // the enumeration completes; passing null (the default) opts out and costs existing callers nothing. + IAsyncEnumerable> GetMovieLibraryItems( + string address, + string apiKey, + EmbyLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null); - IAsyncEnumerable> GetShowLibraryItems(string address, string apiKey, EmbyLibrary library); + IAsyncEnumerable> GetShowLibraryItems( + string address, + string apiKey, + EmbyLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetSeasonLibraryItems( string address, diff --git a/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs b/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs index e3bf8080f..1069b52d3 100644 --- a/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs +++ b/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs @@ -1,5 +1,6 @@ -using ErsatzTV.Core.Domain; +using ErsatzTV.Core.Domain; using ErsatzTV.Core.Jellyfin; +using ErsatzTV.Core.Metadata; namespace ErsatzTV.Core.Interfaces.Jellyfin; @@ -8,20 +9,26 @@ public interface IJellyfinApiClient Task> GetServerInformation(string address, string authorizationHeader); Task>> GetLibraries(string address, string authorizationHeader); + // #484: the three library-level enumerations that feed a reconciliation sweep accept an optional + // per-enumeration counter. The caller creates one instance per enumeration and reads it only after + // the enumeration completes; passing null (the default) opts out and costs existing callers nothing. IAsyncEnumerable> GetMovieLibraryItems( string address, string authorizationHeader, - JellyfinLibrary library); + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetMusicVideoLibraryItems( string address, string authorizationHeader, - JellyfinLibrary library); + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetShowLibraryItemsWithoutPeople( string address, string authorizationHeader, - JellyfinLibrary library); + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetSeasonLibraryItems( string address, diff --git a/ErsatzTV.Core/Metadata/MediaServerProjectionFailureCounter.cs b/ErsatzTV.Core/Metadata/MediaServerProjectionFailureCounter.cs new file mode 100644 index 000000000..e64a97a31 --- /dev/null +++ b/ErsatzTV.Core/Metadata/MediaServerProjectionFailureCounter.cs @@ -0,0 +1,23 @@ +namespace ErsatzTV.Core.Metadata; + +// #484: the narrow seam that carries "how many items did the server return that we silently dropped +// because their projection threw?" out of a media-server API client and back to the scanner that owns +// the reconciliation sweep. +// +// Lifetime is deliberately PER ENUMERATION: the scanner that is about to run a sweep creates one +// instance, hands it to the single library-items call whose result it will diff, and reads Count only +// after that enumeration has completed. The API clients are long-lived singletons and scans for +// different libraries run concurrently, so the counter must never be a field on a client or any +// ambient/static state — that would leak one library's failures into another library's sweep decision. +// Increments are interlocked anyway so a paginator that ever fans out stays correct. +public sealed class MediaServerProjectionFailureCounter +{ + private int _count; + + /// + /// Number of items the server returned whose projection threw and was swallowed. + /// + public int Count => Volatile.Read(ref _count); + + public void RecordFailure() => Interlocked.Increment(ref _count); +} diff --git a/ErsatzTV.Core/Metadata/MediaServerProjectionResult.cs b/ErsatzTV.Core/Metadata/MediaServerProjectionResult.cs new file mode 100644 index 000000000..bb7a4ba80 --- /dev/null +++ b/ErsatzTV.Core/Metadata/MediaServerProjectionResult.cs @@ -0,0 +1,49 @@ +namespace ErsatzTV.Core.Metadata; + +// #484: a media-server API client maps each item the server returned through a private projection. That +// projection has TWO reasons to produce nothing, and conflating them is dangerous: +// +// - Skipped — a deliberate guard clause (a virtual/non-FileSystem item, a STRM file, an unsupported +// item type). The item is permanently and expectedly absent from the incoming set; a +// library containing one STRM file produces a Skipped on every single scan, forever. +// - Failed — the projection threw and was swallowed by a `catch { LogWarning; }`. The server DID +// return the item; we simply could not build it. At the reconcile step that is +// indistinguishable from a deletion, so a projection regression can mass-flag healthy +// items FileNotFound (which EmptyTrash then deletes permanently). +// +// Only Failed may suppress the reconciliation sweep (see MediaServerReconciliationGuard). Treating +// Skipped as a failure would permanently disable reconciliation for any library holding a single STRM +// file, so stale rows would accumulate forever — a regression, not a safe default. +public readonly struct MediaServerProjectionResult +{ + private MediaServerProjectionResult(Option item, bool isFailure) + { + Item = item; + IsFailure = isFailure; + } + + public Option Item { get; } + + /// + /// True only when the projection threw. A deliberate guard-clause skip is NOT a failure. + /// + public bool IsFailure { get; } + + public static MediaServerProjectionResult Projected(T item) => new(item, false); + + /// + /// The server returned an item we deliberately and permanently do not import (virtual item, STRM + /// file, unsupported type). Expected on every scan; never suppresses a sweep. + /// + public static MediaServerProjectionResult Skipped() => new(Option.None, false); + + /// + /// The projection threw and the exception was swallowed. The item exists upstream but is missing + /// from the incoming set, so the sweep must not run. + /// + public static MediaServerProjectionResult Failed() => new(Option.None, true); + + public static implicit operator MediaServerProjectionResult(T item) => Projected(item); + + public Option ToOption() => Item; +} diff --git a/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs b/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs index 9bf3b087d..c8907b1f4 100644 --- a/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs +++ b/ErsatzTV.Infrastructure.Tests/Jellyfin/JellyfinApiClientTests.cs @@ -3,6 +3,8 @@ using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Interfaces.Jellyfin; using ErsatzTV.Core.Interfaces.Metadata; +using ErsatzTV.Core.Jellyfin; +using ErsatzTV.Core.Metadata; using ErsatzTV.Infrastructure.Jellyfin; using LanguageExt; using Microsoft.Extensions.Caching.Memory; @@ -271,6 +273,219 @@ public class JellyfinApiClientTests } } + // #484: the projection-failure seam. The api client drops an item for two very different reasons and + // only ONE of them may suppress the downstream reconciliation sweep, so these tests pin the split at + // the layer that actually makes the distinction. + [TestFixture] + public class ProjectionFailureCounter + { + // A STRM file is a deliberate, permanent guard-clause skip. It must NOT be reported as a failure: + // if it were, one STRM file would disable the library's reconciliation sweep on every scan + // forever and stale rows would accumulate. This is the single most important assertion here. + [Test] + public async Task Deliberate_Skip_Is_Not_Counted_As_A_Failure() + { + const string response = """ + { + "Items": [ + { + "Name": "Streamed", + "Id": "item-strm", + "Path": "/data/music/streamed.strm", + "Type": "MusicVideo", + "LocationType": "FileSystem", + "RunTimeTicks": 3120000000, + "DateCreated": "2026-07-01T00:00:00Z", + "ProviderIds": {} + }, + { + "Name": "Virtual", + "Id": "item-virtual", + "Path": "/data/music/virtual.mkv", + "Type": "MusicVideo", + "LocationType": "Virtual", + "RunTimeTicks": 3120000000, + "DateCreated": "2026-07-01T00:00:00Z", + "ProviderIds": {} + }, + { + "Name": "Hells Bells", + "Id": "item-1", + "Path": "/data/music/hells-bells.mkv", + "Type": "MusicVideo", + "LocationType": "FileSystem", + "RunTimeTicks": 3120000000, + "DateCreated": "2026-07-01T00:00:00Z", + "ProviderIds": {} + } + ], + "TotalRecordCount": 3 + } + """; + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + Substitute.For(), + Substitute.For(), + new SingleResponseHttpClientFactory(response), + Substitute.For>()); + + // no PathInfos => the network-path replacement loop is skipped and nothing can throw + var library = new JellyfinLibrary { Id = 42, MediaSourceId = 1, ItemId = "library-1" }; + + var counter = new MediaServerProjectionFailureCounter(); + + List musicVideos = []; + await foreach ((MusicVideo musicVideo, int _) in client.GetMusicVideoLibraryItems( + "http://jellyfin.example", + "MediaBrowser Token=abc", + library, + counter)) + { + musicVideos.Add(musicVideo); + } + + musicVideos.Count.ShouldBe(1); + counter.Count.ShouldBe(0); + } + + // A projection that THREW was swallowed by the catch and the item silently vanished — but the + // server did return it. That must be reported so the sweep refuses to treat it as a deletion. + [Test] + public async Task Swallowed_Projection_Exception_Is_Counted_As_A_Failure() + { + const string response = """ + { + "Items": [ + { + "Name": "Hells Bells", + "Id": "item-1", + "Path": "/network/music/hells-bells.mkv", + "Type": "MusicVideo", + "LocationType": "FileSystem", + "RunTimeTicks": 3120000000, + "DateCreated": "2026-07-01T00:00:00Z", + "ProviderIds": {} + } + ], + "TotalRecordCount": 1 + } + """; + + var pathReplacementService = Substitute.For(); + pathReplacementService.ReplaceNetworkPath( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()) + .Returns(_ => throw new InvalidOperationException("simulated projection regression")); + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + pathReplacementService, + Substitute.For(), + new SingleResponseHttpClientFactory(response), + Substitute.For>()); + + var library = new JellyfinLibrary + { + Id = 42, + MediaSourceId = 1, + ItemId = "library-1", + PathInfos = [new JellyfinPathInfo { NetworkPath = "/network", Path = "/local" }] + }; + + var counter = new MediaServerProjectionFailureCounter(); + + List musicVideos = []; + await foreach ((MusicVideo musicVideo, int _) in client.GetMusicVideoLibraryItems( + "http://jellyfin.example", + "MediaBrowser Token=abc", + library, + counter)) + { + musicVideos.Add(musicVideo); + } + + // the item is gone from the incoming set (exactly the dangerous case) and it is reported + musicVideos.ShouldBeEmpty(); + counter.Count.ShouldBe(1); + } + + // The counter is created per enumeration by the caller, never held by the (singleton) client, so + // two concurrent library scans cannot leak failures into each other's sweep decision. + [Test] + public async Task Counters_Are_Per_Enumeration_And_Do_Not_Leak_Across_Scans() + { + const string failingResponse = """ + { + "Items": [ + { + "Name": "Hells Bells", + "Id": "item-1", + "Path": "/network/music/hells-bells.mkv", + "Type": "MusicVideo", + "LocationType": "FileSystem", + "RunTimeTicks": 3120000000, + "DateCreated": "2026-07-01T00:00:00Z", + "ProviderIds": {} + } + ], + "TotalRecordCount": 1 + } + """; + + var pathReplacementService = Substitute.For(); + pathReplacementService.ReplaceNetworkPath( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()) + .Returns(_ => throw new InvalidOperationException("simulated projection regression")); + + var client = new JellyfinApiClient( + new MemoryCache(new MemoryCacheOptions()), + pathReplacementService, + Substitute.For(), + new SingleResponseHttpClientFactory(failingResponse), + Substitute.For>()); + + var failingLibrary = new JellyfinLibrary + { + Id = 42, + MediaSourceId = 1, + ItemId = "library-1", + PathInfos = [new JellyfinPathInfo { NetworkPath = "/network", Path = "/local" }] + }; + + // same client instance, a second library whose items project cleanly + var healthyLibrary = new JellyfinLibrary { Id = 43, MediaSourceId = 1, ItemId = "library-2" }; + + var failingCounter = new MediaServerProjectionFailureCounter(); + await foreach ((MusicVideo _, int _) in client.GetMusicVideoLibraryItems( + "http://jellyfin.example", + "MediaBrowser Token=abc", + failingLibrary, + failingCounter)) + { + // no items survive the failing projection + } + + var healthyCounter = new MediaServerProjectionFailureCounter(); + await foreach ((MusicVideo _, int _) in client.GetMusicVideoLibraryItems( + "http://jellyfin.example", + "MediaBrowser Token=abc", + healthyLibrary, + healthyCounter)) + { + // the healthy library has no PathInfos, so nothing throws + } + + failingCounter.Count.ShouldBe(1); + healthyCounter.Count.ShouldBe(0); + } + } + private sealed class SingleResponseHttpClientFactory(string response) : IHttpClientFactory { public HttpClient CreateClient(string name) => new(new SingleResponseHttpMessageHandler(response)); diff --git a/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs b/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs index 9b955302d..114eb541c 100644 --- a/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs +++ b/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs @@ -1,4 +1,4 @@ -using System.Globalization; +using System.Globalization; using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Emby; @@ -72,7 +72,8 @@ public class EmbyApiClient : IEmbyApiClient public IAsyncEnumerable> GetMovieLibraryItems( string address, string apiKey, - EmbyLibrary library) + EmbyLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryContents( address, library, @@ -82,12 +83,14 @@ public class EmbyApiClient : IEmbyApiClient itemId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => maybeLibrary.Map(lib => ProjectToMovie(lib, item)).Flatten()); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToMovie(lib, item)), + projectionFailures); public IAsyncEnumerable> GetShowLibraryItems( string address, string apiKey, - EmbyLibrary library) + EmbyLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryContents( address, library, @@ -97,7 +100,8 @@ public class EmbyApiClient : IEmbyApiClient itemId, startIndex: skip, limit: pageSize), - (_, item) => ProjectToShow(item)); + (_, item) => ProjectToShow(item), + projectionFailures); public IAsyncEnumerable> GetSeasonLibraryItems( string address, @@ -129,7 +133,7 @@ public class EmbyApiClient : IEmbyApiClient seasonId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => maybeLibrary.Map(lib => ProjectToEpisode(lib, item)).Flatten()); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item))); public IAsyncEnumerable> GetCollectionLibraryItems(string address, string apiKey) { @@ -208,7 +212,7 @@ public class EmbyApiClient : IEmbyApiClient foreach (EmbyLibraryItemResponse item in itemsResponse.Items) { - return ProjectToShow(item); + return ProjectToShow(item).ToOption(); } return BaseError.New($"Unable to locate show with id {showId}"); @@ -251,7 +255,7 @@ public class EmbyApiClient : IEmbyApiClient foreach (EmbyLibraryItemResponse item in detailResponse.Items) { - Option maybeShow = ProjectToShow(item); + Option maybeShow = ProjectToShow(item).ToOption(); foreach (EmbyShow show in maybeShow) { shows.Add(show); @@ -269,12 +273,20 @@ public class EmbyApiClient : IEmbyApiClient } } + // #484: a library whose id could not be resolved is not a deliberate per-item skip, so fail closed — + // it must never look like a clean "this item was deleted upstream" to a reconciliation sweep. + private static MediaServerProjectionResult WithLibrary( + Option maybeLibrary, + Func> project) => + maybeLibrary.Match(project, MediaServerProjectionResult.Failed); + private static async IAsyncEnumerable> GetPagedLibraryContents( string address, Option maybeLibrary, string parentId, Func> getItems, - Func, EmbyLibraryItemResponse, Option> mapper) + Func, EmbyLibraryItemResponse, MediaServerProjectionResult> mapper, + MediaServerProjectionFailureCounter projectionFailures = null) { IEmbyApi service = RestService.For(address); const int PAGE_SIZE = 10; @@ -290,15 +302,29 @@ public class EmbyApiClient : IEmbyApiClient pages = Math.Min(pages, (result.TotalRecordCount - 1) / PAGE_SIZE + 1); #pragma warning disable VSTHRD003 - foreach (TItem item in result.Items.Map(item => mapper(maybeLibrary, item)).Somes()) + foreach (EmbyLibraryItemResponse response in result.Items) #pragma warning restore VSTHRD003 { - yield return new Tuple(item, result.TotalRecordCount); + MediaServerProjectionResult projection = mapper(maybeLibrary, response); + + // #484: a swallowed projection failure silently drops an item the server DID return, which + // is indistinguishable from a deletion downstream. Report it so the sweep can refuse. + // Deliberate skips (no media sources, virtual items, unsupported type) are NOT counted. + if (projection.IsFailure) + { + projectionFailures?.RecordFailure(); + } + + foreach (TItem item in projection.Item) + { + yield return new Tuple(item, result.TotalRecordCount); + } } } } - private Option ProjectToCollection(EmbyLibraryItemResponse item) + // NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure. + private MediaServerProjectionResult ProjectToCollection(EmbyLibraryItemResponse item) { try { @@ -312,27 +338,27 @@ public class EmbyApiClient : IEmbyApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Emby collection"); - return None; + return MediaServerProjectionResult.Failed(); } } - private Option ProjectToCollectionMediaItem(EmbyLibraryItemResponse item) + private MediaServerProjectionResult ProjectToCollectionMediaItem(EmbyLibraryItemResponse item) { try { return item.Type switch { - "Movie" => new EmbyMovie { ItemId = item.Id }, - "Series" => new EmbyShow { ItemId = item.Id }, - "Season" => new EmbySeason { ItemId = item.Id }, - "Episode" => new EmbyEpisode { ItemId = item.Id }, - _ => Option.None + "Movie" => MediaServerProjectionResult.Projected(new EmbyMovie { ItemId = item.Id }), + "Series" => MediaServerProjectionResult.Projected(new EmbyShow { ItemId = item.Id }), + "Season" => MediaServerProjectionResult.Projected(new EmbySeason { ItemId = item.Id }), + "Episode" => MediaServerProjectionResult.Projected(new EmbyEpisode { ItemId = item.Id }), + _ => MediaServerProjectionResult.Skipped() }; } catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Emby collection media item"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -377,13 +403,15 @@ public class EmbyApiClient : IEmbyApiClient return None; } - private Option ProjectToMovie(EmbyLibrary library, EmbyLibraryItemResponse item) + private MediaServerProjectionResult ProjectToMovie( + EmbyLibrary library, + EmbyLibraryItemResponse item) { try { if (item.MediaSources is null || item.MediaSources.Count == 0) { - return None; + return MediaServerProjectionResult.Skipped(); } string path = item.Path ?? string.Empty; @@ -434,7 +462,7 @@ public class EmbyApiClient : IEmbyApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Emby movie"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -564,7 +592,8 @@ public class EmbyApiClient : IEmbyApiClient return new Writer { Name = person.Name }; } - private Option ProjectToShow(EmbyLibraryItemResponse item) + // NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure. + private MediaServerProjectionResult ProjectToShow(EmbyLibraryItemResponse item) { try { @@ -583,7 +612,7 @@ public class EmbyApiClient : IEmbyApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Emby show"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -657,7 +686,8 @@ public class EmbyApiClient : IEmbyApiClient return metadata; } - private Option ProjectToSeason(EmbyLibraryItemResponse item) + // NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure. + private MediaServerProjectionResult ProjectToSeason(EmbyLibraryItemResponse item) { try { @@ -716,17 +746,19 @@ public class EmbyApiClient : IEmbyApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Emby show"); - return None; + return MediaServerProjectionResult.Failed(); } } - private Option ProjectToEpisode(EmbyLibrary library, EmbyLibraryItemResponse item) + private MediaServerProjectionResult ProjectToEpisode( + EmbyLibrary library, + EmbyLibraryItemResponse item) { try { if (item.LocationType == "Virtual") { - return None; + return MediaServerProjectionResult.Skipped(); } string path = item.Path ?? string.Empty; @@ -777,7 +809,7 @@ public class EmbyApiClient : IEmbyApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Emby movie"); - return None; + return MediaServerProjectionResult.Failed(); } } diff --git a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs index 110fa8848..8ab07a5a0 100644 --- a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs +++ b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs @@ -79,7 +79,8 @@ public class JellyfinApiClient : IJellyfinApiClient public IAsyncEnumerable> GetMovieLibraryItems( string address, string authorizationHeader, - JellyfinLibrary library) => + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryItems( "JF Movies", address, @@ -91,12 +92,14 @@ public class JellyfinApiClient : IJellyfinApiClient itemId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => maybeLibrary.Map(lib => ProjectToMovie(lib, item)).Flatten()); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToMovie(lib, item)), + projectionFailures); public IAsyncEnumerable> GetMusicVideoLibraryItems( string address, string authorizationHeader, - JellyfinLibrary library) => + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryItems( "JF Music Videos", address, @@ -108,12 +111,14 @@ public class JellyfinApiClient : IJellyfinApiClient itemId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => maybeLibrary.Map(lib => ProjectToMusicVideo(lib, item)).Flatten()); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToMusicVideo(lib, item)), + projectionFailures); public IAsyncEnumerable> GetShowLibraryItemsWithoutPeople( string address, string authorizationHeader, - JellyfinLibrary library) => + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryItems( "JF Shows", address, @@ -125,7 +130,8 @@ public class JellyfinApiClient : IJellyfinApiClient itemId, startIndex: skip, limit: pageSize), - (_, item) => ProjectToShow(item)); + (_, item) => ProjectToShow(item), + projectionFailures); public IAsyncEnumerable> GetSeasonLibraryItems( string address, @@ -161,7 +167,7 @@ public class JellyfinApiClient : IJellyfinApiClient seasonId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => maybeLibrary.Map(lib => ProjectToEpisode(lib, item)).Flatten()); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item))); public IAsyncEnumerable> GetEpisodeLibraryItemsWithoutPeople( string address, @@ -179,7 +185,7 @@ public class JellyfinApiClient : IJellyfinApiClient seasonId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => maybeLibrary.Map(lib => ProjectToEpisode(lib, item)).Flatten()); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item))); public IAsyncEnumerable> GetCollectionLibraryItems( string address, @@ -269,7 +275,7 @@ public class JellyfinApiClient : IJellyfinApiClient foreach (JellyfinLibraryItemResponse item in itemsResponse.Items) { - return ProjectToShow(item); + return ProjectToShow(item).ToOption(); } return BaseError.New($"Unable to locate show with id {showId}"); @@ -313,7 +319,7 @@ public class JellyfinApiClient : IJellyfinApiClient foreach (JellyfinLibraryItemResponse item in detailResponse.Items) { - Option maybeShow = ProjectToShow(item); + Option maybeShow = ProjectToShow(item).ToOption(); foreach (JellyfinShow show in maybeShow) { shows.Add(show); @@ -353,7 +359,7 @@ public class JellyfinApiClient : IJellyfinApiClient foreach (JellyfinLibraryItemResponse item in itemsResponse.Items) { - return ProjectToEpisode(library, item); + return ProjectToEpisode(library, item).ToOption(); } return BaseError.New($"Unable to locate episode with id {episodeId}"); @@ -366,6 +372,13 @@ public class JellyfinApiClient : IJellyfinApiClient } } + // #484: a library whose id could not be resolved is not a deliberate per-item skip, so fail closed — + // it must never look like a clean "this item was deleted upstream" to a reconciliation sweep. + private static MediaServerProjectionResult WithLibrary( + Option maybeLibrary, + Func> project) => + maybeLibrary.Match(project, MediaServerProjectionResult.Failed); + private async IAsyncEnumerable> GetPagedLibraryItems( string pageDescription, string address, @@ -373,7 +386,8 @@ public class JellyfinApiClient : IJellyfinApiClient int mediaSourceId, string parentId, Func> getItems, - Func, JellyfinLibraryItemResponse, Option> mapper) + Func, JellyfinLibraryItemResponse, MediaServerProjectionResult> mapper, + MediaServerProjectionFailureCounter projectionFailures = null) { IJellyfinApi service = ServiceForAddress(address); @@ -396,41 +410,55 @@ public class JellyfinApiClient : IJellyfinApiClient // update page count pages = Math.Min(pages, (result.TotalRecordCount - 1) / SystemEnvironment.JellyfinPageSize + 1); - foreach (TItem item in result.Items.Map(item => mapper(maybeLibrary, item)).Somes()) + foreach (JellyfinLibraryItemResponse response in result.Items) { - yield return new Tuple(item, result.TotalRecordCount); + MediaServerProjectionResult projection = mapper(maybeLibrary, response); + + // #484: a swallowed projection failure silently drops an item the server DID return, which + // is indistinguishable from a deletion downstream. Report it so the sweep can refuse. + // Deliberate skips (STRM, virtual, unsupported type) are NOT counted here. + if (projection.IsFailure) + { + projectionFailures?.RecordFailure(); + } + + foreach (TItem item in projection.Item) + { + yield return new Tuple(item, result.TotalRecordCount); + } } } } - private Option ProjectToCollectionMediaItem(JellyfinLibraryItemResponse item) + private MediaServerProjectionResult ProjectToCollectionMediaItem(JellyfinLibraryItemResponse item) { try { if (item.LocationType != "FileSystem") { - return None; + return MediaServerProjectionResult.Skipped(); } if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm") { _logger.LogWarning("STRM files are not supported; skipping {Path}", item.Path); - return None; + return MediaServerProjectionResult.Skipped(); } return item.Type switch { - "Movie" => new JellyfinMovie { ItemId = item.Id }, - "Series" => new JellyfinShow { ItemId = item.Id }, - "Season" => new JellyfinSeason { ItemId = item.Id }, - "Episode" => new JellyfinEpisode { ItemId = item.Id }, - _ => None + "Movie" => MediaServerProjectionResult.Projected(new JellyfinMovie { ItemId = item.Id }), + "Series" => MediaServerProjectionResult.Projected(new JellyfinShow { ItemId = item.Id }), + "Season" => MediaServerProjectionResult.Projected(new JellyfinSeason { ItemId = item.Id }), + "Episode" => MediaServerProjectionResult.Projected( + new JellyfinEpisode { ItemId = item.Id }), + _ => MediaServerProjectionResult.Skipped() }; } catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin collection media item"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -511,19 +539,21 @@ public class JellyfinApiClient : IJellyfinApiClient return None; } - private Option ProjectToMovie(JellyfinLibrary library, JellyfinLibraryItemResponse item) + private MediaServerProjectionResult ProjectToMovie( + JellyfinLibrary library, + JellyfinLibraryItemResponse item) { try { if (item.LocationType != "FileSystem") { - return None; + return MediaServerProjectionResult.Skipped(); } if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm") { _logger.LogInformation("STRM files are not supported; skipping {Path}", item.Path); - return None; + return MediaServerProjectionResult.Skipped(); } string path = item.Path ?? string.Empty; @@ -574,7 +604,7 @@ public class JellyfinApiClient : IJellyfinApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin movie"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -663,19 +693,21 @@ public class JellyfinApiClient : IJellyfinApiClient return metadata; } - private Option ProjectToMusicVideo(JellyfinLibrary library, JellyfinLibraryItemResponse item) + private MediaServerProjectionResult ProjectToMusicVideo( + JellyfinLibrary library, + JellyfinLibraryItemResponse item) { try { if (item.LocationType != "FileSystem") { - return None; + return MediaServerProjectionResult.Skipped(); } if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm") { _logger.LogInformation("STRM files are not supported; skipping {Path}", item.Path); - return None; + return MediaServerProjectionResult.Skipped(); } string path = item.Path ?? string.Empty; @@ -724,7 +756,7 @@ public class JellyfinApiClient : IJellyfinApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin music video"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -843,7 +875,8 @@ public class JellyfinApiClient : IJellyfinApiClient return new Writer { Name = person.Name }; } - private Option ProjectToShow(JellyfinLibraryItemResponse item) + // NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure. + private MediaServerProjectionResult ProjectToShow(JellyfinLibraryItemResponse item) { try { @@ -862,7 +895,7 @@ public class JellyfinApiClient : IJellyfinApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin show"); - return None; + return MediaServerProjectionResult.Failed(); } } @@ -936,7 +969,8 @@ public class JellyfinApiClient : IJellyfinApiClient return metadata; } - private Option ProjectToSeason(JellyfinLibraryItemResponse item) + // NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure. + private MediaServerProjectionResult ProjectToSeason(JellyfinLibraryItemResponse item) { try { @@ -1005,11 +1039,12 @@ public class JellyfinApiClient : IJellyfinApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin season"); - return None; + return MediaServerProjectionResult.Failed(); } } - private Option ProjectToCollection(JellyfinLibraryItemResponse item) + // NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure. + private MediaServerProjectionResult ProjectToCollection(JellyfinLibraryItemResponse item) { try { @@ -1023,23 +1058,25 @@ public class JellyfinApiClient : IJellyfinApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin collection"); - return None; + return MediaServerProjectionResult.Failed(); } } - private Option ProjectToEpisode(JellyfinLibrary library, JellyfinLibraryItemResponse item) + private MediaServerProjectionResult ProjectToEpisode( + JellyfinLibrary library, + JellyfinLibraryItemResponse item) { try { if (item.LocationType != "FileSystem") { - return None; + return MediaServerProjectionResult.Skipped(); } if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm") { _logger.LogWarning("STRM files are not supported; skipping {Path}", item.Path); - return None; + return MediaServerProjectionResult.Skipped(); } string path = item.Path ?? string.Empty; @@ -1090,7 +1127,7 @@ public class JellyfinApiClient : IJellyfinApiClient catch (Exception ex) { _logger.LogWarning(ex, "Error projecting Jellyfin episode"); - return None; + return MediaServerProjectionResult.Failed(); } } diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs index e21e28312..8161df723 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs @@ -81,7 +81,9 @@ public class MediaServerMovieLibraryScannerTests CancellationToken.None); protected override IAsyncEnumerable> GetMovieLibraryItems( - JellyfinConnectionParameters connectionParameters, JellyfinLibrary library) => EmptyMovies(); + JellyfinConnectionParameters connectionParameters, + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => EmptyMovies(); protected override string MediaServerItemId(JellyfinMovie movie) => movie.ItemId; protected override string MediaServerEtag(JellyfinMovie movie) => movie.Etag; diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerOtherVideoLibraryScannerTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerOtherVideoLibraryScannerTests.cs index a13c0fb9d..990d5b9dd 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerOtherVideoLibraryScannerTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerOtherVideoLibraryScannerTests.cs @@ -79,7 +79,9 @@ public class MediaServerOtherVideoLibraryScannerTests CancellationToken.None); protected override IAsyncEnumerable> GetOtherVideoLibraryItems( - PlexConnectionParameters connectionParameters, PlexLibrary library) => EmptyOtherVideos(); + PlexConnectionParameters connectionParameters, + PlexLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => EmptyOtherVideos(); protected override string MediaServerItemId(PlexOtherVideo otherVideo) => otherVideo.Key; protected override string MediaServerEtag(PlexOtherVideo otherVideo) => otherVideo.Etag; diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs index 41f6e3029..2b8206cf9 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs @@ -6,9 +6,10 @@ using Shouldly; namespace ErsatzTV.Scanner.Tests.Core.Metadata; -// #477: the deterministic policy behind the media-server anti-nuke guard. An empty incoming set with -// existing items present is the only case that skips the sweep (and logs); every other combination -// reconciles normally. +// #477/#484: the deterministic policy behind the media-server anti-nuke guard. Two cases skip the sweep +// (and log), both requiring existing items to be at risk: an EMPTY incoming set (#477) and a non-zero +// PROJECTION FAILURE count (#484). Every other combination reconciles normally — in particular a short +// incoming set caused by deliberate skips, and a genuine bulk deletion, both still sweep. public class MediaServerReconciliationGuardTests { [Test] @@ -66,4 +67,84 @@ public class MediaServerReconciliationGuardTests MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 3, 0).ShouldBeTrue(); } + + // #484: an item whose projection threw was silently dropped, so it is missing from the incoming set + // even though the server DID return it. Sweeping here would flag a healthy item FileNotFound. + [Test] + public void Projection_Failure_Skips_And_Warns() + { + var logger = Substitute.For(); + + MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 4, 5, 1).ShouldBeFalse(); + + logger.Received(1).Log( + LogLevel.Warning, + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any>()); + } + + // #484 THE regression guard. Deliberate guard-clause skips (a STRM file, a virtual item, an + // unsupported type) are NOT projection failures: they never reach the counter, so a short incoming + // set caused only by them must still sweep. If skips were counted, one STRM file in a library would + // permanently disable that library's reconciliation and stale rows would accumulate forever. + [Test] + public void Deliberate_Skips_Do_Not_Suppress_The_Sweep() + { + var logger = Substitute.For(); + + // 5 exist locally, the server returned 5, 2 were deliberately skipped => 3 incoming, 0 failures + MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 3, 5, 0).ShouldBeTrue(); + + logger.DidNotReceive().Log( + LogLevel.Warning, + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any>()); + } + + // a genuine bulk deletion produces zero projection failures, so it is unaffected by #484 — this is + // why the rejected ratio threshold was not needed to tell the two apart. + [Test] + public void Bulk_Deletion_With_No_Failures_Still_Flags() + { + var logger = Substitute.For(); + + MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 1, 500, 0).ShouldBeTrue(); + } + + [Test] + public void Projection_Failure_With_No_Existing_Items_Is_A_Noop_Sweep() + { + var logger = Substitute.For(); + + // nothing exists locally, so the sweep flags nothing either way — don't emit the scary warning + MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 2, 0, 3).ShouldBeTrue(); + + logger.DidNotReceive().Log( + LogLevel.Warning, + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any>()); + } + + // both refusals can be true at once (a fetch that dropped everything it returned); either is + // sufficient, and the failure branch is reported because it names the actual cause. + [Test] + public void Projection_Failure_Wins_Over_The_Zero_Incoming_Message() + { + var logger = Substitute.For(); + + MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 0, 5, 2).ShouldBeFalse(); + + logger.Received(1).Log( + LogLevel.Warning, + Arg.Any(), + Arg.Is(o => o.ToString()!.Contains("silently dropped")), + Arg.Any(), + Arg.Any>()); + } } diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs index 0a955cc69..75e40bafa 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs @@ -134,6 +134,57 @@ public class MediaServerTelevisionLibraryScannerTests Arg.Any(), Arg.Any()); } + // #484: the same partial deletion as Removed_Show_Cascades_..., but the api client silently dropped + // an item whose projection threw. "show-6366" is missing from the incoming list only because we + // failed to build it, not because the server stopped reporting it — flagging it would trash a + // healthy show (and, via the #476 cascade, all of its seasons and episodes). Paired with the + // cascade test above as a positive control: identical arrangement, only the counter differs. + [Test] + public async Task Projection_Failure_Suppresses_The_Partial_Deletion_Sweep() + { + var televisionRepository = Substitute.For(); + var scannerProxy = Substitute.For(); + + var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" }; + + televisionRepository.GetExistingShows(library, Arg.Any()) + .Returns(new List + { + new() { ItemId = "show-keep", State = MediaItemState.Normal }, + new() { ItemId = "show-6366", State = MediaItemState.Normal } + }); + + televisionRepository.GetOrAdd(library, Arg.Any(), Arg.Any()) + .Returns(Left>(BaseError.New("skip metadata in test"))); + + scannerProxy.UpdateProgress(Arg.Any(), Arg.Any()).Returns(true); + + var projectionFailures = new MediaServerProjectionFailureCounter(); + projectionFailures.RecordFailure(); + + var scanner = new TestTelevisionLibraryScanner(scannerProxy); + + Either result = await scanner.Scan( + televisionRepository, + new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7), + library, + Shows(new JellyfinShow + { + ItemId = "show-keep", + ShowMetadata = new List { new() { Title = "Keeper" } } + }), + projectionFailures); + + result.IsRight.ShouldBeTrue(); + + await televisionRepository.DidNotReceive().FlagFileNotFoundShows( + Arg.Any(), Arg.Any>(), Arg.Any()); + await televisionRepository.DidNotReceive().FlagFileNotFoundSeasonsForShows( + Arg.Any>(), Arg.Any()); + await televisionRepository.DidNotReceive().FlagFileNotFoundEpisodesForSeasons( + Arg.Any>(), Arg.Any()); + } + private static async IAsyncEnumerable> EmptyShows() { await Task.CompletedTask; @@ -172,18 +223,22 @@ public class MediaServerTelevisionLibraryScannerTests JellyfinItemEtag> televisionRepository, JellyfinConnectionParameters connectionParameters, JellyfinLibrary library, - IAsyncEnumerable> showEntries) => + IAsyncEnumerable> showEntries, + MediaServerProjectionFailureCounter? projectionFailures = null) => ScanLibrary( televisionRepository, connectionParameters, library, _ => string.Empty, showEntries, + projectionFailures ?? new MediaServerProjectionFailureCounter(), false, CancellationToken.None); protected override IAsyncEnumerable> GetShowLibraryItems( - JellyfinConnectionParameters connectionParameters, JellyfinLibrary library) => + JellyfinConnectionParameters connectionParameters, + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => throw new NotSupportedException(); protected override string MediaServerItemId(JellyfinShow show) => show.ItemId; diff --git a/ErsatzTV.Scanner/Core/Emby/EmbyMovieLibraryScanner.cs b/ErsatzTV.Scanner/Core/Emby/EmbyMovieLibraryScanner.cs index 77f142e22..cdf2b9caa 100644 --- a/ErsatzTV.Scanner/Core/Emby/EmbyMovieLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Emby/EmbyMovieLibraryScanner.cs @@ -1,4 +1,4 @@ -using System.IO.Abstractions; +using System.IO.Abstractions; using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Emby; @@ -81,11 +81,13 @@ public class EmbyMovieLibraryScanner : protected override IAsyncEnumerable> GetMovieLibraryItems( EmbyConnectionParameters connectionParameters, - EmbyLibrary library) => + EmbyLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => _embyApiClient.GetMovieLibraryItems( connectionParameters.Address, connectionParameters.ApiKey, - library); + library, + projectionFailures); protected override Task> GetFullMetadata( EmbyConnectionParameters connectionParameters, diff --git a/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs index aa625fbe2..468f8a209 100644 --- a/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs @@ -1,4 +1,4 @@ -using System.IO.Abstractions; +using System.IO.Abstractions; using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Emby; @@ -133,8 +133,13 @@ public class EmbyTelevisionLibraryScanner : MediaServerTelevisionLibraryScanner< protected override IAsyncEnumerable> GetShowLibraryItems( EmbyConnectionParameters connectionParameters, - EmbyLibrary library) => - _embyApiClient.GetShowLibraryItems(connectionParameters.Address, connectionParameters.ApiKey, library); + EmbyLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => + _embyApiClient.GetShowLibraryItems( + connectionParameters.Address, + connectionParameters.ApiKey, + library, + projectionFailures); protected override string MediaServerItemId(EmbyShow show) => show.ItemId; protected override string MediaServerItemId(EmbySeason season) => season.ItemId; diff --git a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMovieLibraryScanner.cs b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMovieLibraryScanner.cs index bdf764141..81e4e7b36 100644 --- a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMovieLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMovieLibraryScanner.cs @@ -1,4 +1,4 @@ -using System.IO.Abstractions; +using System.IO.Abstractions; using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Extensions; @@ -81,11 +81,13 @@ public class JellyfinMovieLibraryScanner : protected override IAsyncEnumerable> GetMovieLibraryItems( JellyfinConnectionParameters connectionParameters, - JellyfinLibrary library) => + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => _jellyfinApiClient.GetMovieLibraryItems( connectionParameters.Address, connectionParameters.AuthorizationHeader, - library); + library, + projectionFailures); protected override Task> GetFullMetadata( JellyfinConnectionParameters connectionParameters, diff --git a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMusicVideoLibraryScanner.cs b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMusicVideoLibraryScanner.cs index 6088dbe65..f11860253 100644 --- a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMusicVideoLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinMusicVideoLibraryScanner.cs @@ -79,11 +79,18 @@ public class JellyfinMusicVideoLibraryScanner : IJellyfinMusicVideoLibraryScanne var processed = 0; var incomingPaths = new List(); + + // #484: one counter per enumeration, created here and read only after the enumeration completes. + // It is never a field on the (singleton) api client, so concurrent scans of different libraries + // cannot leak failures into each other's sweep decision. + var projectionFailures = new MediaServerProjectionFailureCounter(); + await foreach ((MusicVideo incoming, int totalCount) in _jellyfinApiClient .GetMusicVideoLibraryItems( connectionParameters.Address, connectionParameters.AuthorizationHeader, - library) + library, + projectionFailures) .WithCancellation(cancellationToken)) { if (cancellationToken.IsCancellationRequested) @@ -118,7 +125,12 @@ public class JellyfinMusicVideoLibraryScanner : IJellyfinMusicVideoLibraryScanne } } - await TrashMissingMusicVideos(library, libraryPath, incomingPaths, cancellationToken); + await TrashMissingMusicVideos( + library, + libraryPath, + incomingPaths, + projectionFailures, + cancellationToken); return Unit.Default; } @@ -141,17 +153,21 @@ public class JellyfinMusicVideoLibraryScanner : IJellyfinMusicVideoLibraryScanne JellyfinLibrary library, LibraryPath libraryPath, List incomingPaths, + MediaServerProjectionFailureCounter projectionFailures, CancellationToken cancellationToken) { var existingPaths = (await _musicVideoRepository.FindMusicVideoPaths(libraryPath)).ToList(); // #477: refuse the sweep when a successful fetch returned zero items but rows exist locally — an empty // incoming set is indistinguishable from a transient error and would otherwise wipe the whole library. + // #484: also refuse when the api client silently dropped items whose projection threw — those are + // items Jellyfin DID return, so treating them as deletions would hard-delete healthy rows. if (!MediaServerReconciliationGuard.ShouldFlagMissing( _logger, library.Name, incomingPaths.Count, - existingPaths.Count)) + existingPaths.Count, + projectionFailures.Count)) { return; } diff --git a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs index 2f2b475fb..2eeccecad 100644 --- a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs @@ -1,4 +1,4 @@ -using System.IO.Abstractions; +using System.IO.Abstractions; using ErsatzTV.Core; using ErsatzTV.Core.Domain; using ErsatzTV.Core.Errors; @@ -137,11 +137,13 @@ public class JellyfinTelevisionLibraryScanner : MediaServerTelevisionLibraryScan protected override IAsyncEnumerable> GetShowLibraryItems( JellyfinConnectionParameters connectionParameters, - JellyfinLibrary library) => + JellyfinLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => _jellyfinApiClient.GetShowLibraryItemsWithoutPeople( connectionParameters.Address, connectionParameters.AuthorizationHeader, - library); + library, + projectionFailures); protected override string MediaServerItemId(JellyfinShow show) => show.ItemId; protected override string MediaServerItemId(JellyfinSeason season) => season.ItemId; diff --git a/ErsatzTV.Scanner/Core/Metadata/MediaServerMovieLibraryScanner.cs b/ErsatzTV.Scanner/Core/Metadata/MediaServerMovieLibraryScanner.cs index e014aa745..9e80e5d9c 100644 --- a/ErsatzTV.Scanner/Core/Metadata/MediaServerMovieLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Metadata/MediaServerMovieLibraryScanner.cs @@ -52,12 +52,18 @@ public abstract class MediaServerMovieLibraryScanner getLocalPath, IAsyncEnumerable> movieEntries, + MediaServerProjectionFailureCounter projectionFailures, bool deepScan, CancellationToken cancellationToken) { @@ -204,7 +211,11 @@ public abstract class MediaServerMovieLibraryScanner ids = await movieRepository.FlagFileNotFound(library, fileNotFoundItemIds); @@ -220,9 +231,13 @@ public abstract class MediaServerMovieLibraryScanner> GetMovieLibraryItems( TConnectionParameters connectionParameters, - TLibrary library); + TLibrary library, + MediaServerProjectionFailureCounter projectionFailures); protected abstract Task> GetFullMetadata( TConnectionParameters connectionParameters, diff --git a/ErsatzTV.Scanner/Core/Metadata/MediaServerOtherVideoLibraryScanner.cs b/ErsatzTV.Scanner/Core/Metadata/MediaServerOtherVideoLibraryScanner.cs index 18d90dcc2..eb5150431 100644 --- a/ErsatzTV.Scanner/Core/Metadata/MediaServerOtherVideoLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Metadata/MediaServerOtherVideoLibraryScanner.cs @@ -52,12 +52,17 @@ public abstract class MediaServerOtherVideoLibraryScanner getLocalPath, IAsyncEnumerable> otherVideoEntries, + MediaServerProjectionFailureCounter projectionFailures, bool deepScan, CancellationToken cancellationToken) { @@ -211,7 +217,11 @@ public abstract class MediaServerOtherVideoLibraryScanner ids = await otherVideoRepository.FlagFileNotFound(library, fileNotFoundItemIds); @@ -227,9 +237,11 @@ public abstract class MediaServerOtherVideoLibraryScanner> GetOtherVideoLibraryItems( TConnectionParameters connectionParameters, - TLibrary library); + TLibrary library, + MediaServerProjectionFailureCounter projectionFailures); protected abstract Task> GetFullMetadata( TConnectionParameters connectionParameters, diff --git a/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs b/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs index fb5950f57..7cfb9398d 100644 --- a/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs +++ b/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs @@ -14,16 +14,48 @@ namespace ErsatzTV.Scanner.Core.Metadata; // partial-deletion sweep would otherwise handle (see #476's cascade, which still fires for the common // case where survivors are present and only some items are gone). The cost of not flagging a genuinely // emptied library (stale rows persist until an item returns or the library is removed) is far smaller -// than a one-scan permanent wipe. Ratio-thresholds and projection-failure detection are deferred — see -// docs/decisions.md and the #477 follow-up. +// than a one-scan permanent wipe. +// +// #484 extended the policy with a SECOND deterministic refusal and rejected the ratio threshold: +// +// - projection failures (implemented). A media-server API client maps every item the server returned +// through a private projection whose `catch` swallows the exception and drops the item. A dropped +// item the server DID return is indistinguishable from a deletion here, so one projection +// regression could mass-flag a healthy library. When the enumeration that produced `incomingCount` +// reports any such failure, the sweep is refused. Deliberate guard-clause skips (STRM files, +// virtual items, unsupported types) are NOT failures and never suppress the sweep — see +// MediaServerProjectionResult; counting them would permanently disable reconciliation for any +// library holding a single STRM file. +// - ratio / missing-fraction threshold (REJECTED). It is a two-sided heuristic: set low it silently +// suppresses legitimate bulk deletions, set high it misses the partial fetch it exists for, and +// there is no telemetry to tune it with. The failure it approximates is exactly observable via the +// projection-failure count above, and a genuine bulk deletion produces zero projection failures, so +// the deterministic signal has no false positives where the heuristic has unbounded ones. +// +// See docs/decisions.md `scan.projection-failure-sweep-guard`. internal static class MediaServerReconciliationGuard { public static bool ShouldFlagMissing( ILogger logger, string libraryName, int incomingCount, - int existingCount) + int existingCount, + int projectionFailureCount = 0) { + if (projectionFailureCount > 0 && existingCount > 0) + { + logger.LogWarning( + "Media server library {Library} silently dropped {FailureCount} item(s) that failed to " + + "project during this scan ({IncomingCount} usable, {ExistingCount} exist locally); " + + "skipping the file-not-found sweep because a dropped item is indistinguishable from a " + + "deletion and would be flagged as missing", + libraryName, + projectionFailureCount, + incomingCount, + existingCount); + return false; + } + if (incomingCount == 0 && existingCount > 0) { logger.LogWarning( diff --git a/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs index 3b0f6cb2d..bb6c3043b 100644 --- a/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs @@ -55,12 +55,18 @@ public abstract class MediaServerTelevisionLibraryScanner> GetShowLibraryItems( TConnectionParameters connectionParameters, - TLibrary library); + TLibrary library, + MediaServerProjectionFailureCounter projectionFailures); protected abstract string MediaServerItemId(TShow show); protected abstract string MediaServerItemId(TSeason season); @@ -87,6 +97,7 @@ public abstract class MediaServerTelevisionLibraryScanner getLocalPath, IAsyncEnumerable> showEntries, + MediaServerProjectionFailureCounter? projectionFailures, bool deepScan, bool cleanupFileNotFoundItems, CancellationToken cancellationToken) @@ -172,7 +183,11 @@ public abstract class MediaServerTelevisionLibraryScanner s.MediaServerItemId).Except(incomingItemIds).ToList(); @@ -201,6 +216,7 @@ public abstract class MediaServerTelevisionLibraryScanner getLocalPath, IAsyncEnumerable> showEntries, + MediaServerProjectionFailureCounter projectionFailures, bool deepScan, CancellationToken cancellationToken) => await InternalScanLibrary( @@ -209,10 +225,13 @@ public abstract class MediaServerTelevisionLibraryScanner> ScanLibraryWithoutCleanup( IMediaServerTelevisionRepository televisionRepository, TConnectionParameters connectionParameters, @@ -227,6 +246,7 @@ public abstract class MediaServerTelevisionLibraryScanner movie.Etag; + // #484: Plex's movie projection returns a bare PlexMovie with no catch, so a bad item throws and + // unwinds the whole scan instead of being silently dropped — there is no failure to count here. protected override IAsyncEnumerable> GetMovieLibraryItems( PlexConnectionParameters connectionParameters, - PlexLibrary library) => + PlexLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => _plexServerApiClient.GetMovieLibraryContents( library, connectionParameters.Connection, diff --git a/ErsatzTV.Scanner/Core/Plex/PlexOtherVideoLibraryScanner.cs b/ErsatzTV.Scanner/Core/Plex/PlexOtherVideoLibraryScanner.cs index ffac33c50..e843e353f 100644 --- a/ErsatzTV.Scanner/Core/Plex/PlexOtherVideoLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Plex/PlexOtherVideoLibraryScanner.cs @@ -89,9 +89,12 @@ public class PlexOtherVideoLibraryScanner : protected override string MediaServerEtag(PlexOtherVideo otherVideo) => otherVideo.Etag; + // #484: Plex's other-video projection returns a bare PlexOtherVideo with no catch, so a bad item + // throws and unwinds the whole scan instead of being silently dropped — nothing to count here. protected override IAsyncEnumerable> GetOtherVideoLibraryItems( PlexConnectionParameters connectionParameters, - PlexLibrary library) => + PlexLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => _plexServerApiClient.GetOtherVideoLibraryContents( library, connectionParameters.Connection, diff --git a/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs index 8b28e8160..8ef4a7def 100644 --- a/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs @@ -1,4 +1,4 @@ -using System.IO.Abstractions; +using System.IO.Abstractions; using System.Text.RegularExpressions; using ErsatzTV.Core; using ErsatzTV.Core.Domain; @@ -233,9 +233,12 @@ public partial class PlexTelevisionLibraryScanner : // } // } + // #484: Plex's show projection returns a bare PlexShow with no catch, so a bad item throws and + // unwinds the whole scan instead of being silently dropped — there is no failure to count here. protected override IAsyncEnumerable> GetShowLibraryItems( PlexConnectionParameters connectionParameters, - PlexLibrary library) => + PlexLibrary library, + MediaServerProjectionFailureCounter projectionFailures) => _plexServerApiClient.GetShowLibraryContents( library, connectionParameters.Connection, diff --git a/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs b/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs index 7749fec6f..7bd74b8e2 100644 --- a/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs +++ b/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs @@ -58,7 +58,11 @@ public class JellyfinMusicVideoLibraryScannerTests MusicVideo incoming = BuildIncoming(VideoPath, artistName: "Artist 1", title: "Song 1"); var apiClient = Substitute.For(); - apiClient.GetMusicVideoLibraryItems(Arg.Any(), Arg.Any(), Arg.Any()) + apiClient.GetMusicVideoLibraryItems( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()) .Returns(OneItem(incoming)); var pathReplacement = Substitute.For(); @@ -672,7 +676,11 @@ public class JellyfinMusicVideoLibraryScannerTests private static IJellyfinApiClient FakeApi(params Func[] items) { var apiClient = Substitute.For(); - apiClient.GetMusicVideoLibraryItems(Arg.Any(), Arg.Any(), Arg.Any()) + apiClient.GetMusicVideoLibraryItems( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()) .Returns(_ => Items(items)); return apiClient; } diff --git a/docs/decisions.md b/docs/decisions.md index 28e3d239e..36c439e6f 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -3777,3 +3777,75 @@ section renders the date itself, never a stale/fresh verdict. much of this corpus is agent-authored, distinguishing agent-inferred from human-confirmed-after- measuring is real signal; it just needs its own actor convention and wasn't worth coupling to this change. +## 2026-07-25 — A media-server sweep also refuses when the api client silently dropped items whose projection threw; the ratio threshold is rejected (#484) +`key: scan.projection-failure-sweep-guard` · `status: active` · `since: 2026-07-25` · `supersedes: none` · `superseded-by: none` +**Rule:** `MediaServerReconciliationGuard.ShouldFlagMissing` takes a per-enumeration projection-failure count and refuses the file-not-found sweep (logged loudly) whenever it is non-zero against a non-empty existing set; deliberate guard-clause skips (STRM, virtual, unsupported type) are explicitly **not** failures and never suppress a sweep. The missing-fraction / ratio threshold floated by #477 is **rejected**, not deferred. +**Signals:** projection failure, silently dropped item, deferred ratio threshold rejected, STRM skip vs failure, library sweep anti-nuke follow-up · paths: `MediaServerProjectionResult`, `MediaServerProjectionFailureCounter`, `MediaServerReconciliationGuard`, `JellyfinApiClient.GetPagedLibraryItems`, `EmbyApiClient.GetPagedLibraryContents` · issues: #484, #477, #476 +**Mechanics:** `MediaServerReconciliationGuardTests` policy table · `JellyfinApiClientTests.ProjectionFailureCounter` · `MediaServerTelevisionLibraryScannerTests.Projection_Failure_Suppresses_The_Partial_Deletion_Sweep` + +This resolves both items the `scan.zero-item-fetch-guard` record (#477) left deferred. That record's rule +is unchanged and still in force: a zero-item fetch against a non-empty library still refuses the sweep. +This is a **second, independent** refusal on the same guard, plus a decision not to build the first. + +- **The two ways a projection produces nothing are NOT the same thing, and conflating them is the main + way to get this wrong.** Each media-server api client maps every item the server returned through a + private `ProjectTo*` and drops the ones that yield nothing. A *deliberate skip* is a guard clause at + the top of the projection — Jellyfin `ProjectToMovie`/`ProjectToMusicVideo` (`LocationType != + "FileSystem"`, `.strm`), `ProjectToEpisode` (same two), `ProjectToCollectionMediaItem` (both plus an + unmatched `item.Type`); Emby `ProjectToMovie` (no `MediaSources`), `ProjectToEpisode` (`LocationType + == "Virtual"`), `ProjectToCollectionMediaItem` (unmatched `item.Type`). These are permanent and + expected: a library holding one STRM file emits one on **every** scan, forever. A *failure drop* is + the `catch (Exception ex) { LogWarning(ex, "Error projecting …"); }` that every `ProjectTo*` in all + three clients ends with — the server DID return that item, we just could not build it, and at the + reconcile step that is indistinguishable from a deletion. Only failure drops suppress the sweep. + Counting deliberate skips would permanently disable reconciliation for any library containing a single + STRM file, so stale rows would accumulate forever — a regression, not a safe default. + `Jellyfin`/`Emby` `ProjectToShow`, `ProjectToSeason` and `ProjectToCollection` have **no** guard + clause at all, so for them every drop is a failure. +- **Rejected — the missing-fraction / ratio threshold.** It is a two-sided heuristic. Set low it + silently suppresses legitimate bulk deletions (stale rows persist invisibly, and the user's only + signal is a warning nobody reads); set high it misses the partial-fetch case it exists for. Choosing + the number needs per-install telemetry we do not collect, and no default is defensible for both a + 20-item library and a 20,000-item one. Decisively: the failure it approximates is **exactly + observable** by the mechanism above, so accepting an unbounded false-suppression risk to approximate + it is a bad trade. A genuine bulk deletion produces **zero** projection failures (and a + correspondingly smaller server-reported total), so the deterministic signal has no false positives on + the very case the ratio threshold would have broken. +- **A three-state projection result, not a wider tuple.** The seam is deliberately narrow. + `IAsyncEnumerable>` appears in ~90 signatures across `ErsatzTV.Core/Interfaces/ + {Jellyfin,Emby,Plex}`, the three api clients and ~15 scanners; widening it for this would be a + disproportionate, risky refactor. Instead the **private** mapper contract inside each client changed + from `Option` to `MediaServerProjectionResult` (projected / skipped / failed) — private, + so zero public churn — and the paged helper counts `IsFailure` in exactly one place per client. The + scanner reads the count through an **optional trailing parameter** on only the library-level methods + that actually feed a sweep (`IJellyfinApiClient.GetMovieLibraryItems` / + `GetMusicVideoLibraryItems` / `GetShowLibraryItemsWithoutPeople`, `IEmbyApiClient.GetMovieLibraryItems` + / `GetShowLibraryItems`), so every other call site is untouched. A library that cannot be resolved + (`Option.None` inside a mapper) is treated as a **failure**, not a skip — fail closed. +- **The counter is per-enumeration state, never ambient.** `MediaServerProjectionFailureCounter` is + created by the scanner that owns the sweep, handed to the single enumeration whose result it will + diff, and read only after that enumeration completes. It is never a field on an api client (those are + long-lived and shared) and never static, so concurrent scans of different libraries cannot leak + failures into each other's sweep decision; increments are interlocked so a paginator that ever fans + out stays correct. +- **Wired into the four real sweep call sites**, matching #477's scope exactly: the three library-level + base scanners (`MediaServerMovieLibraryScanner`, `MediaServerTelevisionLibraryScanner`, + `MediaServerOtherVideoLibraryScanner`) and `JellyfinMusicVideoLibraryScanner`. The nested TV + season/episode sweeps stay unguarded for the reasons in `scan.zero-item-fetch-guard`, and + `ScanLibraryWithoutCleanup` (single-show rescan) passes no counter because it runs no sweep. +- **Plex reports zero failures because it has none.** `PlexServerApiClient`'s movie/show/other-video + projections return a bare entity with no `Option` and no `catch`, so a bad item throws and unwinds the + whole scan — the pre-existing "protection by accident of control flow" that #477 named. The Plex + scanner overrides therefore accept the counter and ignore it; that is honest, not a gap. If those + projections ever grow a swallowing `catch`, they must report into the counter at the same time. +- **Tests.** `MediaServerReconciliationGuardTests` pins the extended policy table: a failure count skips + and warns; a short incoming set with **zero** failures (the deliberate-skip case) still sweeps; a + 1-of-500 bulk deletion with zero failures still sweeps; failures against an empty local set stay a + silent no-op; the failure branch is reported when both refusals apply. `JellyfinApiClientTests + .ProjectionFailureCounter` drives the real client over real JSON and proves the split at the layer + that makes it — a STRM plus a virtual item leave the counter at 0 while the healthy item still flows, + a projection made to throw yields no items and a count of 1, and two enumerations on one client + instance keep separate counts. `MediaServerTelevisionLibraryScannerTests + .Projection_Failure_Suppresses_The_Partial_Deletion_Sweep` is the integration pair to #476's cascade + test: identical arrangement, only the counter differs, so the cascade test is the positive control + that keeps the new test from passing vacuously. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index e8886584c..fcfc67c4d 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -114,6 +114,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `scan.getoraddfolder-db-lookup` | `ILibraryRepository.GetOrAddFolder` resolves the existing folder via a DB query on `(LibraryPathId, Path)`, not the caller's `LibraryPath.LibraryFolders` in-memory navigation, since that navigation is only eager-loaded on the local scan path and is null on remote (Jellyfin) callers. | 2026-07-20 | [link](../decisions.md#2026-07-20--ilibraryrepositorygetoraddfolder-resolves-the-folder-from-the-db-not-the-callers-librarypathlibraryfolders-navigation-488) | | `scan.jellyfin-mixed-content-library` | A Jellyfin library whose collection type is `mixed` (or absent) maps to one ErsatzTV library of `LibraryMediaKind.Mixed`, scanned by running the movie/television/music-video scanners in sequence against that single library — a library is a place, not a media kind. | 2026-07-20 | [link](../decisions.md#2026-07-20-489--jellyfin-mixed-content-libraries-map-to-one-library-holding-many-kinds) | | `scan.musicvideo-reconciliation` | `JellyfinMusicVideoLibraryScanner` reconciles removed music videos by a library-scoped local-path diff plus hard delete (`TrashMissingMusicVideos`), not the server-itemId soft-trash pattern the other media-server scanners use, because music videos carry no server identity. | 2026-07-20 | [link](../decisions.md#2026-07-20--jellyfinmusicvideolibraryscanner-reconciles-by-library-scoped-path-diff--hard-delete-not-server-itemid-soft-trash-494) | +| `scan.projection-failure-sweep-guard` | `MediaServerReconciliationGuard.ShouldFlagMissing` takes a per-enumeration projection-failure count and refuses the file-not-found sweep (logged loudly) whenever it is non-zero against a non-empty existing set; deliberate guard-clause skips (STRM, virtual, unsupported type) are explicitly **not** failures and never suppress a sweep. The missing-fraction / ratio threshold floated by #477 is **rejected**, not deferred. | 2026-07-25 | [link](../decisions.md#2026-07-25--a-media-server-sweep-also-refuses-when-the-api-client-silently-dropped-items-whose-projection-threw-the-ratio-threshold-is-rejected-484) | | `scan.zero-item-fetch-guard` | A media-server library sweep refuses to flag missing items when a successful fetch returns zero incoming items against a non-empty existing set (`MediaServerReconciliationGuard.ShouldFlagMissing`), rather than treating an ambiguous empty result as a full-library deletion. | 2026-07-19 | [link](../decisions.md#2026-07-19--a-media-server-library-sweep-refuses-to-flag-when-a-successful-fetch-returns-zero-items-rather-than-nuking-the-whole-library-477) | | `sched.auto-tune-foundation` | Auto-tune preview enumeration uses EF distinct+count queries for exact counts, while each created channel is persisted as a live SmartCollection; coexistence with existing channels/numbers is additive-only, never mutating. | 2026-07-16 | [link](../decisions.md#2026-07-16--auto-tuning-enumerates-via-ef-persists-via-smartcollection-additive-coexistence-69) | | `sched.autotune-detailpanel-members` | The Auto-Tune DetailPanel's per-channel content-source list is a live `ISearchIndex.Search` roll-up through the server-owned `AutoTuneAxisMap.GenerateQuery`, not an EF distinct+count query, so the preview matches exactly what the built channel's SmartCollection will contain. | 2026-07-17 | [link](../decisions.md#2026-07-17--auto-tune-detailpanel-member-list--live-search-index-roll-up-not-ef-enumeration-384) | -- 2.47.3 From 6f4497e1ce4be13bcc537bc6eca35c7623760353 Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 25 Jul 2026 15:08:47 +0200 Subject: [PATCH 2/3] fix(484): guard the nested TV season and episode sweeps against projection failures MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding 1 (blocking). ScanSeasons' FlagFileNotFoundSeasons and ScanEpisodes' FlagFileNotFoundEpisodes had no guard at all — neither #477's nor #484's — so ProjectToSeason / ProjectToEpisode returning Failed() was computed and discarded. #477 scoped those out because "the blast radius is one show's seasons / one season's episodes", which holds for a per-parent EMPTY fetch but not for a projection failure: that is systematic by construction. One bad code path fires on every parent, so every season enumerates zero episodes, existing.Except([]) is the whole episode library, and EmptyTrashHandler deletes it permanently. Threads the counter into GetSeasonLibraryItems / GetEpisodeLibraryItems(WithoutPeople) for Jellyfin and Emby using the same optional-trailing-param shape, and guards both sweeps with MediaServerReconciliationGuard.ShouldFlagMissingDescendants — the same class and the same private failure predicate as ShouldFlagMissing, deliberately WITHOUT #477's empty-fetch branch so per-parent empty behaviour (and #476's cascade, which depends on it) is unchanged. Also from the review: - finding 3: tests now pin the same-instance JOIN at every level (movie, show, season, episode, music video) by driving the real ScanLibrary entry point and recording the failure from inside the enumeration, so a refactor handing the api client a fresh counter goes red. - finding 4: the missing-library Failed() branch is documented as defensive and unreachable. - finding 2: the mass-Skip residual (Emby's response-shape-dependent MediaSources guard, Plex's pre-projection filter) is stated as a known limitation in the decision record. - finding 5: the log-contract change (only the #484 message when both refusals apply) is noted. fixes #484 --- .../Interfaces/Emby/IEmbyApiClient.cs | 8 +- .../Interfaces/Jellyfin/IJellyfinApiClient.cs | 11 +- ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs | 18 +- .../Jellyfin/JellyfinApiClient.cs | 24 +- .../MediaServerMovieLibraryScannerTests.cs | 125 +++++++- .../MediaServerReconciliationGuardTests.cs | 59 ++++ ...ediaServerTelevisionLibraryScannerTests.cs | 283 +++++++++++++++++- .../Core/Emby/EmbyTelevisionLibraryScanner.cs | 12 +- .../JellyfinTelevisionLibraryScanner.cs | 16 +- .../MediaServerReconciliationGuard.cs | 68 ++++- .../MediaServerTelevisionLibraryScanner.cs | 96 ++++-- .../Core/Plex/PlexTelevisionLibraryScanner.cs | 8 +- .../JellyfinMusicVideoLibraryScannerTests.cs | 116 +++++++ docs/decisions.md | 64 +++- docs/decisions/README.md | 2 +- 15 files changed, 828 insertions(+), 82 deletions(-) diff --git a/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs b/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs index 42802fcb0..446176af5 100644 --- a/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs +++ b/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs @@ -24,18 +24,22 @@ public interface IEmbyApiClient EmbyLibrary library, MediaServerProjectionFailureCounter projectionFailures = null); + // #484: the nested per-show season and per-season episode enumerations feed their own sweeps + // (FlagFileNotFoundSeasons / FlagFileNotFoundEpisodes), so they carry the same optional counter. IAsyncEnumerable> GetSeasonLibraryItems( string address, string apiKey, EmbyLibrary library, - string showId); + string showId, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetEpisodeLibraryItems( string address, string apiKey, EmbyLibrary library, string showId, - string seasonId); + string seasonId, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetCollectionLibraryItems(string address, string apiKey); diff --git a/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs b/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs index 1069b52d3..89f0802c3 100644 --- a/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs +++ b/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs @@ -30,23 +30,28 @@ public interface IJellyfinApiClient JellyfinLibrary library, MediaServerProjectionFailureCounter projectionFailures = null); + // #484: the nested per-show season and per-season episode enumerations feed their own sweeps + // (FlagFileNotFoundSeasons / FlagFileNotFoundEpisodes), so they carry the same optional counter. IAsyncEnumerable> GetSeasonLibraryItems( string address, string authorizationHeader, JellyfinLibrary library, - string showId); + string showId, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetEpisodeLibraryItems( string address, string authorizationHeader, JellyfinLibrary library, - string seasonId); + string seasonId, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetEpisodeLibraryItemsWithoutPeople( string address, string authorizationHeader, JellyfinLibrary library, - string seasonId); + string seasonId, + MediaServerProjectionFailureCounter projectionFailures = null); IAsyncEnumerable> GetCollectionLibraryItems( string address, diff --git a/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs b/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs index 114eb541c..2f5a7205a 100644 --- a/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs +++ b/ErsatzTV.Infrastructure/Emby/EmbyApiClient.cs @@ -107,7 +107,8 @@ public class EmbyApiClient : IEmbyApiClient string address, string apiKey, EmbyLibrary library, - string showId) => GetPagedLibraryContents( + string showId, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryContents( address, library, showId, @@ -116,14 +117,16 @@ public class EmbyApiClient : IEmbyApiClient itemId, startIndex: skip, limit: pageSize), - (_, item) => ProjectToSeason(item)); + (_, item) => ProjectToSeason(item), + projectionFailures); public IAsyncEnumerable> GetEpisodeLibraryItems( string address, string apiKey, EmbyLibrary library, string showId, - string seasonId) => GetPagedLibraryContents( + string seasonId, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryContents( address, library, seasonId, @@ -133,7 +136,8 @@ public class EmbyApiClient : IEmbyApiClient seasonId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item))); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item)), + projectionFailures); public IAsyncEnumerable> GetCollectionLibraryItems(string address, string apiKey) { @@ -273,8 +277,10 @@ public class EmbyApiClient : IEmbyApiClient } } - // #484: a library whose id could not be resolved is not a deliberate per-item skip, so fail closed — - // it must never look like a clean "this item was deleted upstream" to a reconciliation sweep. + // #484: defensive, and currently UNREACHABLE — every counted path passes a concrete library, and the + // only None caller (collections) does not route through here. Kept because the classification would + // otherwise be wrong by default if a future caller does pass None: a library we could not resolve is + // not a deliberate per-item skip, so fail closed rather than look like a clean upstream deletion. private static MediaServerProjectionResult WithLibrary( Option maybeLibrary, Func> project) => diff --git a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs index 8ab07a5a0..8e8b6dba7 100644 --- a/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs +++ b/ErsatzTV.Infrastructure/Jellyfin/JellyfinApiClient.cs @@ -137,7 +137,8 @@ public class JellyfinApiClient : IJellyfinApiClient string address, string authorizationHeader, JellyfinLibrary library, - string showId) => + string showId, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryItems( "JF Seasons", address, @@ -149,13 +150,15 @@ public class JellyfinApiClient : IJellyfinApiClient showId, startIndex: skip, limit: pageSize), - (_, item) => ProjectToSeason(item)); + (_, item) => ProjectToSeason(item), + projectionFailures); public IAsyncEnumerable> GetEpisodeLibraryItems( string address, string authorizationHeader, JellyfinLibrary library, - string seasonId) => + string seasonId, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryItems( "JF Episodes*", address, @@ -167,13 +170,15 @@ public class JellyfinApiClient : IJellyfinApiClient seasonId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item))); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item)), + projectionFailures); public IAsyncEnumerable> GetEpisodeLibraryItemsWithoutPeople( string address, string authorizationHeader, JellyfinLibrary library, - string seasonId) => + string seasonId, + MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryItems( "JF Episodes", address, @@ -185,7 +190,8 @@ public class JellyfinApiClient : IJellyfinApiClient seasonId, startIndex: skip, limit: pageSize), - (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item))); + (maybeLibrary, item) => WithLibrary(maybeLibrary, lib => ProjectToEpisode(lib, item)), + projectionFailures); public IAsyncEnumerable> GetCollectionLibraryItems( string address, @@ -372,8 +378,10 @@ public class JellyfinApiClient : IJellyfinApiClient } } - // #484: a library whose id could not be resolved is not a deliberate per-item skip, so fail closed — - // it must never look like a clean "this item was deleted upstream" to a reconciliation sweep. + // #484: defensive, and currently UNREACHABLE — every counted path passes a concrete library, and the + // only None caller (collections) does not route through here. Kept because the classification would + // otherwise be wrong by default if a future caller does pass None: a library we could not resolve is + // not a deliberate per-item skip, so fail closed rather than look like a clean upstream deletion. private static MediaServerProjectionResult WithLibrary( Option maybeLibrary, Func> project) => diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs index 8161df723..37cb65cfd 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerMovieLibraryScannerTests.cs @@ -51,6 +51,107 @@ public class MediaServerMovieLibraryScannerTests await scannerProxy.DidNotReceive().ReindexMediaItems( Arg.Any(), Arg.Any()); } + + // #484 finding 3: ScanLibrary creates ONE counter and must hand that same instance to both + // GetMovieLibraryItems and ShouldFlagMissing. A refactor that handed the api client a fresh + // counter would leave the guard reading zero and silently re-enable the sweep — every other test + // would stay green, this one goes red. The zero-incoming guard cannot mask it: a survivor is + // present, so #477's branch does not fire. + [Test] + public async Task Projection_Failure_From_The_Api_Suppresses_The_Sweep_End_To_End() + { + var movieRepository = Substitute.For(); + var scannerProxy = Substitute.For(); + + var library = new JellyfinLibrary { Id = 3, Name = "Movies" }; + + movieRepository.GetExistingMovies(library) + .Returns(new List + { + new() { ItemId = "movie-1", Etag = "e1", State = MediaItemState.Normal }, + new() { ItemId = "movie-2", Etag = "e2", State = MediaItemState.Normal } + }); + + // Left short-circuits the per-item metadata path; the id is still recorded as incoming + movieRepository.GetOrAdd(library, Arg.Any(), Arg.Any(), Arg.Any()) + .Returns(Left>(BaseError.New("skip metadata in test"))); + scannerProxy.UpdateProgress(Arg.Any(), Arg.Any()).Returns(true); + + var scanner = new TestMovieLibraryScanner(scannerProxy) + { + MovieEntries = + [ + new JellyfinMovie + { + ItemId = "movie-1", + Etag = "e1", + MovieMetadata = new List { new() { Title = "Keeper" } } + } + ], + ProjectionFailures = 1 + }; + + Either result = await scanner.Scan( + movieRepository, + new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7), + library); + + result.IsRight.ShouldBeTrue(); + + await movieRepository.DidNotReceive().FlagFileNotFound( + Arg.Any(), Arg.Any>()); + } + + // positive control for the test above: identical arrangement, zero failures => movie-2 IS swept. + [Test] + public async Task Partial_Deletion_With_No_Projection_Failures_Still_Sweeps() + { + var movieRepository = Substitute.For(); + var scannerProxy = Substitute.For(); + + var library = new JellyfinLibrary { Id = 3, Name = "Movies" }; + + movieRepository.GetExistingMovies(library) + .Returns(new List + { + new() { ItemId = "movie-1", Etag = "e1", State = MediaItemState.Normal }, + new() { ItemId = "movie-2", Etag = "e2", State = MediaItemState.Normal } + }); + + movieRepository.GetOrAdd(library, Arg.Any(), Arg.Any(), Arg.Any()) + .Returns(Left>(BaseError.New("skip metadata in test"))); + scannerProxy.UpdateProgress(Arg.Any(), Arg.Any()).Returns(true); + + // an unstubbed substitute returns null, which would NRE on ids.ToArray() + movieRepository.FlagFileNotFound(Arg.Any(), Arg.Any>()) + .Returns(new List { 7 }); + scannerProxy.ReindexMediaItems(Arg.Any(), Arg.Any()).Returns(true); + + var scanner = new TestMovieLibraryScanner(scannerProxy) + { + MovieEntries = + [ + new JellyfinMovie + { + ItemId = "movie-1", + Etag = "e1", + MovieMetadata = new List { new() { Title = "Keeper" } } + } + ], + ProjectionFailures = 0 + }; + + Either result = await scanner.Scan( + movieRepository, + new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7), + library); + + result.IsRight.ShouldBeTrue(); + + await movieRepository.Received(1).FlagFileNotFound( + library, + Arg.Is>(l => l.Count == 1 && l.Contains("movie-2"))); + } } // Minimal concrete subclass exposing the cleanup path. Driven with an empty incoming list, so none of @@ -80,10 +181,16 @@ public class MediaServerMovieLibraryScannerTests false, CancellationToken.None); + // #484: incoming movies plus how many projection failures the enumeration reports into the + // counter the SCANNER created — this is what pins same-instance wiring end to end. + public JellyfinMovie[] MovieEntries { get; init; } = []; + public int ProjectionFailures { get; init; } + protected override IAsyncEnumerable> GetMovieLibraryItems( JellyfinConnectionParameters connectionParameters, JellyfinLibrary library, - MediaServerProjectionFailureCounter projectionFailures) => EmptyMovies(); + MediaServerProjectionFailureCounter projectionFailures) => + Movies(MovieEntries, ProjectionFailures, projectionFailures); protected override string MediaServerItemId(JellyfinMovie movie) => movie.ItemId; protected override string MediaServerEtag(JellyfinMovie movie) => movie.Etag; @@ -103,10 +210,22 @@ public class MediaServerMovieLibraryScannerTests CancellationToken cancellationToken) => throw new NotSupportedException(); - private static async IAsyncEnumerable> EmptyMovies() + // mirrors production: failures are recorded DURING enumeration into the caller's counter + private static async IAsyncEnumerable> Movies( + JellyfinMovie[] movies, + int projectionFailureCount, + MediaServerProjectionFailureCounter projectionFailures) { await Task.CompletedTask; - yield break; + for (var i = 0; i < projectionFailureCount; i++) + { + projectionFailures.RecordFailure(); + } + + foreach (JellyfinMovie movie in movies) + { + yield return new Tuple(movie, movies.Length + projectionFailureCount); + } } } } diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs index 2b8206cf9..69545810c 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerReconciliationGuardTests.cs @@ -131,6 +131,65 @@ public class MediaServerReconciliationGuardTests Arg.Any>()); } + // #484: the nested per-show season / per-season episode sweeps. They get the SAME projection-failure + // predicate... + [Test] + public void Descendant_Sweep_Skips_And_Warns_On_A_Projection_Failure() + { + var logger = Substitute.For(); + + MediaServerReconciliationGuard.ShouldFlagMissingDescendants(logger, "show Keeper seasons", 4, 5, 1) + .ShouldBeFalse(); + + logger.Received(1).Log( + LogLevel.Warning, + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any>()); + } + + // ...but deliberately NOT #477's empty-fetch branch. A per-parent empty is a plausible legitimate + // state (every episode of a season really was deleted) with a bounded blast radius, and #476's + // descendant cascade depends on it still sweeping. Importing that branch here would be a silent + // behaviour change, which is why this is a separate entry point rather than a shared signature. + [Test] + public void Descendant_Sweep_Still_Runs_On_An_Empty_Per_Parent_Fetch() + { + var logger = Substitute.For(); + + MediaServerReconciliationGuard.ShouldFlagMissingDescendants(logger, "season 1 of show Keeper episodes", 0, 5, 0) + .ShouldBeTrue(); + + logger.DidNotReceive().Log( + LogLevel.Warning, + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any>()); + } + + [Test] + public void Descendant_Sweep_Runs_With_No_Failures_And_Is_A_Noop_When_Nothing_Exists() + { + var logger = Substitute.For(); + + // deliberate skips only => still sweeps (the STRM regression guard at the descendant level) + MediaServerReconciliationGuard.ShouldFlagMissingDescendants(logger, "show Keeper seasons", 3, 5, 0) + .ShouldBeTrue(); + + // failures but nothing exists locally => the sweep flags nothing anyway, so don't warn + MediaServerReconciliationGuard.ShouldFlagMissingDescendants(logger, "show Keeper seasons", 2, 0, 3) + .ShouldBeTrue(); + + logger.DidNotReceive().Log( + LogLevel.Warning, + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any>()); + } + // both refusals can be true at once (a fetch that dropped everything it returned); either is // sufficient, and the failure branch is reported because it names the actual cause. [Test] diff --git a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs index 75e40bafa..4dbcf2696 100644 --- a/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs +++ b/ErsatzTV.Scanner.Tests/Core/Metadata/MediaServerTelevisionLibraryScannerTests.cs @@ -185,6 +185,220 @@ public class MediaServerTelevisionLibraryScannerTests Arg.Any>(), Arg.Any()); } + // #484 finding 3: the public ScanLibrary creates the counter and must hand the SAME instance to + // GetShowLibraryItems and to the sweep. A refactor that passed a fresh counter to the api client + // would keep every other test green and silently kill the protection; this one goes red. + [Test] + public async Task Public_ScanLibrary_Joins_The_Api_Counter_To_The_Sweep() + { + var televisionRepository = Substitute.For(); + var scannerProxy = Substitute.For(); + var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" }; + + televisionRepository.GetExistingShows(library, Arg.Any()) + .Returns(new List + { + new() { ItemId = "show-keep", State = MediaItemState.Normal }, + new() { ItemId = "show-6366", State = MediaItemState.Normal } + }); + televisionRepository.GetOrAdd(library, Arg.Any(), Arg.Any()) + .Returns(Left>(BaseError.New("skip metadata in test"))); + scannerProxy.UpdateProgress(Arg.Any(), Arg.Any()).Returns(true); + + var scanner = new TestTelevisionLibraryScanner(scannerProxy) + { + ShowEntries = + [ + new JellyfinShow + { + ItemId = "show-keep", + ShowMetadata = new List { new() { Title = "Keeper" } } + } + ], + ShowProjectionFailures = 1 + }; + + Either result = await scanner.ScanFromApi( + televisionRepository, + new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7), + library); + + result.IsRight.ShouldBeTrue(); + + await televisionRepository.DidNotReceive().FlagFileNotFoundShows( + Arg.Any(), Arg.Any>(), Arg.Any()); + } + + // #484: the per-show SEASON sweep. A projection failure is systematic, so this fires for every + // show at once — the blast radius is the library's whole season tree plus, via #476, its episodes. + [TestCase(1, false, TestName = "Season_Sweep_Is_Skipped_When_The_Season_Projection_Failed")] + [TestCase(0, true, TestName = "Season_Sweep_Still_Runs_With_No_Projection_Failures")] + public async Task Season_Sweep_Respects_Projection_Failures(int failures, bool expectFlag) + { + var televisionRepository = Substitute.For(); + var scannerProxy = Substitute.For(); + var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" }; + + var show = new JellyfinShow + { + ItemId = "show-1", + ShowMetadata = new List { new() { Title = "Keeper" } } + }; + + televisionRepository.GetExistingShows(library, Arg.Any()) + .Returns(new List { new() { ItemId = "show-1", State = MediaItemState.Normal } }); + televisionRepository.GetOrAdd(library, Arg.Any(), Arg.Any()) + .Returns(Right>(new MediaItemScanResult(show))); + scannerProxy.UpdateProgress(Arg.Any(), Arg.Any()).Returns(true); + + // two seasons exist, only one comes back — a partial deletion at the season level + televisionRepository.GetExistingSeasons(library, Arg.Any(), Arg.Any()) + .Returns(new List + { + new() { ItemId = "season-keep", State = MediaItemState.Normal }, + new() { ItemId = "season-gone", State = MediaItemState.Normal } + }); + + // Left short-circuits the per-season path so ScanEpisodes is never entered + televisionRepository.GetOrAdd(library, Arg.Any(), Arg.Any()) + .Returns(Left>(BaseError.New("skip season in test"))); + + // an unstubbed substitute returns null, which would NRE in the sweep's Concat + televisionRepository.FlagFileNotFoundSeasons( + Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(new List { 200 }); + televisionRepository.FlagFileNotFoundEpisodesForSeasons( + Arg.Any>(), Arg.Any()) + .Returns(new List { 300 }); + televisionRepository.FlagFileNotFoundShows( + Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(new List()); + televisionRepository.FlagFileNotFoundSeasonsForShows( + Arg.Any>(), Arg.Any()) + .Returns(new List()); + scannerProxy.ReindexMediaItems(Arg.Any(), Arg.Any()).Returns(true); + + var scanner = new TestTelevisionLibraryScanner(scannerProxy) + { + SeasonEntries = [new JellyfinSeason { ItemId = "season-keep", SeasonNumber = 1 }], + SeasonProjectionFailures = failures + }; + + Either result = await scanner.Scan( + televisionRepository, + new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7), + library, + Shows(show)); + + result.IsRight.ShouldBeTrue(); + + if (expectFlag) + { + await televisionRepository.Received(1).FlagFileNotFoundSeasons( + library, + Arg.Is>(l => l.Count == 1 && l.Contains("season-gone")), + Arg.Any()); + } + else + { + await televisionRepository.DidNotReceive().FlagFileNotFoundSeasons( + Arg.Any(), Arg.Any>(), Arg.Any()); + } + } + + // #484: the per-season EPISODE sweep — the highest-stakes one. A ProjectToEpisode regression makes + // every season enumerate zero episodes, so existing.Except([]) is the entire episode library. + [TestCase(1, false, TestName = "Episode_Sweep_Is_Skipped_When_The_Episode_Projection_Failed")] + [TestCase(0, true, TestName = "Episode_Sweep_Still_Runs_With_No_Projection_Failures")] + public async Task Episode_Sweep_Respects_Projection_Failures(int failures, bool expectFlag) + { + var televisionRepository = Substitute.For(); + var scannerProxy = Substitute.For(); + var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" }; + + var show = new JellyfinShow + { + ItemId = "show-1", + ShowMetadata = new List { new() { Title = "Keeper" } } + }; + var season = new JellyfinSeason { ItemId = "season-1", SeasonNumber = 1 }; + + televisionRepository.GetExistingShows(library, Arg.Any()) + .Returns(new List { new() { ItemId = "show-1", State = MediaItemState.Normal } }); + televisionRepository.GetOrAdd(library, Arg.Any(), Arg.Any()) + .Returns(Right>(new MediaItemScanResult(show))); + scannerProxy.UpdateProgress(Arg.Any(), Arg.Any()).Returns(true); + + // the season comes back, so the season sweep flags nothing and cannot mask the episode assertion + televisionRepository.GetExistingSeasons(library, Arg.Any(), Arg.Any()) + .Returns(new List { new() { ItemId = "season-1", State = MediaItemState.Normal } }); + televisionRepository.GetOrAdd(library, Arg.Any(), Arg.Any()) + .Returns(Right>(new MediaItemScanResult(season))); + + // two episodes exist, only one comes back — a partial deletion at the episode level + televisionRepository.GetExistingEpisodes(library, Arg.Any(), Arg.Any()) + .Returns(new List + { + new() { ItemId = "ep-keep", Etag = "e1", State = MediaItemState.Normal }, + new() { ItemId = "ep-gone", Etag = "e2", State = MediaItemState.Normal } + }); + + // an unstubbed substitute returns null, which would NRE in the sweeps + televisionRepository.FlagFileNotFoundEpisodes( + Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(new List { 300 }); + televisionRepository.FlagFileNotFoundSeasons( + Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(new List()); + televisionRepository.FlagFileNotFoundEpisodesForSeasons( + Arg.Any>(), Arg.Any()) + .Returns(new List()); + televisionRepository.FlagFileNotFoundShows( + Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(new List()); + televisionRepository.FlagFileNotFoundSeasonsForShows( + Arg.Any>(), Arg.Any()) + .Returns(new List()); + scannerProxy.ReindexMediaItems(Arg.Any(), Arg.Any()).Returns(true); + + var scanner = new TestTelevisionLibraryScanner(scannerProxy) + { + SeasonEntries = [season], + + // matching etag + missing local file => ShouldScanItem short-circuits before the metadata + // path, but the id is already recorded as incoming + EpisodeEntries = [new JellyfinEpisode { ItemId = "ep-keep", Etag = "e1" }], + EpisodeProjectionFailures = failures + }; + + Either result = await scanner.Scan( + televisionRepository, + new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7), + library, + Shows(show)); + + result.IsRight.ShouldBeTrue(); + + if (expectFlag) + { + await televisionRepository.Received(1).FlagFileNotFoundEpisodes( + library, + Arg.Is>(l => l.Count == 1 && l.Contains("ep-gone")), + Arg.Any()); + } + else + { + await televisionRepository.DidNotReceive().FlagFileNotFoundEpisodes( + Arg.Any(), Arg.Any>(), Arg.Any()); + } + + // the season counter is a separate instance and stays clean either way + await televisionRepository.DidNotReceive().FlagFileNotFoundSeasons( + Arg.Any(), + Arg.Is>(l => l.Count > 0), + Arg.Any()); + } + private static async IAsyncEnumerable> EmptyShows() { await Task.CompletedTask; @@ -202,8 +416,10 @@ public class MediaServerTelevisionLibraryScannerTests } // Minimal concrete subclass that exposes the abstract scanner's cleanup path. The incoming show list - // is supplied directly (empty = "all shows removed"), so none of the per-item metadata members below - // are ever invoked — they exist only to satisfy the abstract contract. + // is supplied directly (empty = "all shows removed"). #484 extended it to also drive the NESTED season + // and episode sweeps: SeasonEntries/EpisodeEntries supply those enumerations, and + // SeasonProjectionFailures/EpisodeProjectionFailures make the enumeration report failures into the + // counter the SCANNER handed it — so these tests also pin same-instance wiring at both nested levels. private sealed class TestTelevisionLibraryScanner : MediaServerTelevisionLibraryScanner< JellyfinConnectionParameters, JellyfinLibrary, JellyfinShow, JellyfinSeason, JellyfinEpisode, JellyfinItemEtag> @@ -218,6 +434,17 @@ public class MediaServerTelevisionLibraryScannerTests { } + // #484: incoming shows for the top-level (public) ScanLibrary entry point, plus how many + // projection failures that enumeration should report into the counter the scanner created. + public JellyfinShow[] ShowEntries { get; init; } = []; + public int ShowProjectionFailures { get; init; } + + public JellyfinSeason[] SeasonEntries { get; init; } = []; + public int SeasonProjectionFailures { get; init; } + + public JellyfinEpisode[] EpisodeEntries { get; init; } = []; + public int EpisodeProjectionFailures { get; init; } + public Task> Scan( IMediaServerTelevisionRepository televisionRepository, @@ -235,11 +462,26 @@ public class MediaServerTelevisionLibraryScannerTests false, CancellationToken.None); + // #484 finding 3: the PUBLIC entry point, which creates the counter itself and must hand the SAME + // instance to both GetShowLibraryItems and the sweep. Nothing else exercises that join. + public Task> ScanFromApi( + IMediaServerTelevisionRepository televisionRepository, + JellyfinConnectionParameters connectionParameters, + JellyfinLibrary library) => + ScanLibrary( + televisionRepository, + connectionParameters, + library, + _ => string.Empty, + false, + CancellationToken.None); + protected override IAsyncEnumerable> GetShowLibraryItems( JellyfinConnectionParameters connectionParameters, JellyfinLibrary library, MediaServerProjectionFailureCounter projectionFailures) => - throw new NotSupportedException(); + Enumerate(ShowEntries, ShowProjectionFailures, projectionFailures); protected override string MediaServerItemId(JellyfinShow show) => show.ItemId; protected override string MediaServerItemId(JellyfinSeason season) => season.ItemId; @@ -249,23 +491,46 @@ public class MediaServerTelevisionLibraryScannerTests protected override string MediaServerEtag(JellyfinEpisode episode) => episode.Etag; protected override IAsyncEnumerable> GetSeasonLibraryItems( - JellyfinLibrary library, JellyfinConnectionParameters connectionParameters, JellyfinShow show) => - throw new NotSupportedException(); + JellyfinLibrary library, JellyfinConnectionParameters connectionParameters, JellyfinShow show, + MediaServerProjectionFailureCounter projectionFailures) => + Enumerate(SeasonEntries, SeasonProjectionFailures, projectionFailures); protected override IAsyncEnumerable> GetEpisodeLibraryItems( JellyfinLibrary library, JellyfinConnectionParameters connectionParameters, JellyfinShow show, - JellyfinSeason season, bool isNewSeason) => - throw new NotSupportedException(); + JellyfinSeason season, bool isNewSeason, + MediaServerProjectionFailureCounter projectionFailures) => + Enumerate(EpisodeEntries, EpisodeProjectionFailures, projectionFailures); + // mirrors production: failures are recorded DURING enumeration, into the counter the caller + // supplied, and are only read after the enumeration completes. + private static async IAsyncEnumerable> Enumerate( + T[] items, + int projectionFailureCount, + MediaServerProjectionFailureCounter projectionFailures) + { + await Task.CompletedTask; + for (var i = 0; i < projectionFailureCount; i++) + { + projectionFailures.RecordFailure(); + } + + foreach (T item in items) + { + yield return new Tuple(item, items.Length + projectionFailureCount); + } + } + + // returning None makes the base's UpdateMetadata a passthrough, so the per-item metadata path is + // never entered and the nested sweeps can be driven without a full metadata harness. protected override Task> GetFullMetadata( JellyfinConnectionParameters connectionParameters, JellyfinLibrary library, MediaItemScanResult result, JellyfinShow incoming, bool deepScan) => - throw new NotSupportedException(); + Task.FromResult(Option.None); protected override Task> GetFullMetadata( JellyfinConnectionParameters connectionParameters, JellyfinLibrary library, MediaItemScanResult result, JellyfinSeason incoming, bool deepScan) => - throw new NotSupportedException(); + Task.FromResult(Option.None); protected override Task> GetFullMetadata( JellyfinConnectionParameters connectionParameters, JellyfinLibrary library, diff --git a/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs index 468f8a209..7b8652669 100644 --- a/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Emby/EmbyTelevisionLibraryScanner.cs @@ -152,25 +152,29 @@ public class EmbyTelevisionLibraryScanner : MediaServerTelevisionLibraryScanner< protected override IAsyncEnumerable> GetSeasonLibraryItems( EmbyLibrary library, EmbyConnectionParameters connectionParameters, - EmbyShow show) => + EmbyShow show, + MediaServerProjectionFailureCounter projectionFailures) => _embyApiClient.GetSeasonLibraryItems( connectionParameters.Address, connectionParameters.ApiKey, library, - show.ItemId); + show.ItemId, + projectionFailures); protected override IAsyncEnumerable> GetEpisodeLibraryItems( EmbyLibrary library, EmbyConnectionParameters connectionParameters, EmbyShow show, EmbySeason season, - bool isNewSeason) => + bool isNewSeason, + MediaServerProjectionFailureCounter projectionFailures) => _embyApiClient.GetEpisodeLibraryItems( connectionParameters.Address, connectionParameters.ApiKey, library, show.ItemId, - season.ItemId); + season.ItemId, + projectionFailures); protected override Task> GetFullMetadata( EmbyConnectionParameters connectionParameters, diff --git a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs index 2eeccecad..fdf38f62b 100644 --- a/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Jellyfin/JellyfinTelevisionLibraryScanner.cs @@ -156,34 +156,40 @@ public class JellyfinTelevisionLibraryScanner : MediaServerTelevisionLibraryScan protected override IAsyncEnumerable> GetSeasonLibraryItems( JellyfinLibrary library, JellyfinConnectionParameters connectionParameters, - JellyfinShow show) => + JellyfinShow show, + MediaServerProjectionFailureCounter projectionFailures) => _jellyfinApiClient.GetSeasonLibraryItems( connectionParameters.Address, connectionParameters.AuthorizationHeader, library, - show.ItemId); + show.ItemId, + projectionFailures); protected override IAsyncEnumerable> GetEpisodeLibraryItems( JellyfinLibrary library, JellyfinConnectionParameters connectionParameters, JellyfinShow show, JellyfinSeason season, - bool isNewSeason) + bool isNewSeason, + MediaServerProjectionFailureCounter projectionFailures) { + // both variants must report into the SAME counter — they feed one episode sweep if (isNewSeason) { return _jellyfinApiClient.GetEpisodeLibraryItems( connectionParameters.Address, connectionParameters.AuthorizationHeader, library, - season.ItemId); + season.ItemId, + projectionFailures); } return _jellyfinApiClient.GetEpisodeLibraryItemsWithoutPeople( connectionParameters.Address, connectionParameters.AuthorizationHeader, library, - season.ItemId); + season.ItemId, + projectionFailures); } protected override async Task> GetFullMetadata( diff --git a/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs b/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs index 7cfb9398d..70538852b 100644 --- a/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs +++ b/ErsatzTV.Scanner/Core/Metadata/MediaServerReconciliationGuard.cs @@ -32,6 +32,15 @@ namespace ErsatzTV.Scanner.Core.Metadata; // projection-failure count above, and a genuine bulk deletion produces zero projection failures, so // the deterministic signal has no false positives where the heuristic has unbounded ones. // +// #484 also applies the projection-failure refusal to the NESTED per-show season and per-season episode +// sweeps, which #477 deliberately left unguarded. #477's reasoning ("blast radius is one show's seasons / +// one season's episodes") holds for a per-parent EMPTY fetch — a plausible legitimate state — but not for +// a projection failure, which is systematic by construction: one bad code path fires on every parent, so +// every season enumerates zero episodes and the whole episode library is swept in a single scan. The +// nested sweeps therefore get ShouldFlagMissingDescendants: the SAME failure predicate from the SAME +// class, deliberately WITHOUT #477's empty-fetch branch, so the per-parent empty behaviour (and #476's +// cascade, which depends on it) is unchanged. +// // See docs/decisions.md `scan.projection-failure-sweep-guard`. internal static class MediaServerReconciliationGuard { @@ -42,17 +51,13 @@ internal static class MediaServerReconciliationGuard int existingCount, int projectionFailureCount = 0) { - if (projectionFailureCount > 0 && existingCount > 0) - { - logger.LogWarning( - "Media server library {Library} silently dropped {FailureCount} item(s) that failed to " - + "project during this scan ({IncomingCount} usable, {ExistingCount} exist locally); " - + "skipping the file-not-found sweep because a dropped item is indistinguishable from a " - + "deletion and would be flagged as missing", - libraryName, - projectionFailureCount, + if (RefuseForProjectionFailures( + logger, + $"library {libraryName}", incomingCount, - existingCount); + existingCount, + projectionFailureCount)) + { return false; } @@ -69,4 +74,47 @@ internal static class MediaServerReconciliationGuard return true; } + + /// + /// The nested per-show season / per-season episode sweeps. Applies ONLY the #484 projection-failure + /// refusal — a per-parent empty fetch is a plausible legitimate state at this level and #477 + /// deliberately left it unguarded, so importing that branch here would silently change #476's + /// per-parent cascade behaviour. + /// + /// + /// Names the parent whose descendants are being swept, e.g. show "Sesame Street" seasons. + /// + public static bool ShouldFlagMissingDescendants( + ILogger logger, + string scope, + int incomingCount, + int existingCount, + int projectionFailureCount) => + !RefuseForProjectionFailures(logger, scope, incomingCount, existingCount, projectionFailureCount); + + // the one place the projection-failure predicate lives, so the library-level and descendant-level + // sweeps can never drift apart on what counts as a failure or when it matters. + private static bool RefuseForProjectionFailures( + ILogger logger, + string scope, + int incomingCount, + int existingCount, + int projectionFailureCount) + { + if (projectionFailureCount <= 0 || existingCount <= 0) + { + return false; + } + + logger.LogWarning( + "Media server {Scope} silently dropped {FailureCount} item(s) that failed to project during " + + "this scan ({IncomingCount} usable, {ExistingCount} exist locally); skipping the " + + "file-not-found sweep because a dropped item is indistinguishable from a deletion and " + + "would be flagged as missing", + scope, + projectionFailureCount, + incomingCount, + existingCount); + return true; + } } diff --git a/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs index bb6c3043b..5d0c456e6 100644 --- a/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Metadata/MediaServerTelevisionLibraryScanner.cs @@ -141,6 +141,9 @@ public abstract class MediaServerTelevisionLibraryScanner result in maybeShow.RightToSeq()) { + // #484: one counter per season enumeration, i.e. per show + var seasonProjectionFailures = new MediaServerProjectionFailureCounter(); + Either scanResult = await ScanSeasons( televisionRepository, library, @@ -148,7 +151,12 @@ public abstract class MediaServerTelevisionLibraryScanner> GetSeasonLibraryItems( TLibrary library, TConnectionParameters connectionParameters, - TShow show); + TShow show, + MediaServerProjectionFailureCounter projectionFailures); protected abstract IAsyncEnumerable> GetEpisodeLibraryItems( TLibrary library, TConnectionParameters connectionParameters, TShow show, TSeason season, - bool isNewSeason); + bool isNewSeason, + MediaServerProjectionFailureCounter projectionFailures); protected abstract Task> GetFullMetadata( TConnectionParameters connectionParameters, @@ -309,6 +322,14 @@ public abstract class MediaServerTelevisionLibraryScanner + Optional(show.ShowMetadata).Flatten().HeadOrNone() + .Map(m => m.Title) + .Filter(t => !string.IsNullOrWhiteSpace(t)) + .IfNone(() => MediaServerItemId(show)); + private async Task> ScanSeasons( IMediaServerTelevisionRepository televisionRepository, TLibrary library, @@ -317,6 +338,7 @@ public abstract class MediaServerTelevisionLibraryScanner> seasonEntries, + MediaServerProjectionFailureCounter projectionFailures, bool deepScan, CancellationToken cancellationToken) { @@ -356,6 +378,9 @@ public abstract class MediaServerTelevisionLibraryScanner result in maybeSeason.RightToSeq()) { + // #484: one counter per episode enumeration, i.e. per season + var episodeProjectionFailures = new MediaServerProjectionFailureCounter(); + Either scanResult = await ScanEpisodes( televisionRepository, library, @@ -364,7 +389,14 @@ public abstract class MediaServerTelevisionLibraryScanner s.MediaServerItemId).Except(incomingItemIds).ToList(); - List ids = await televisionRepository.FlagFileNotFoundSeasons(library, fileNotFoundItemIds, cancellationToken); - - // #476: a season gone from the media server (while its show remains) is absent from the incoming - // list, so the per-season loop never visits it and the episode sweep in ScanEpisodes never runs - // for it. Cascade the flag to its episodes. - List episodeIds = await televisionRepository.FlagFileNotFoundEpisodesForSeasons(ids, cancellationToken); - - if (!await _scannerProxy.ReindexMediaItems(ids.Concat(episodeIds).ToArray(), cancellationToken)) + // #484: a projection failure is systematic, not per-parent — one bad code path drops seasons for + // EVERY show, so this sweep would flag the library's entire season tree (and, via the #476 + // cascade below, its episodes) in one scan. A per-parent EMPTY fetch is still swept, unchanged. + if (MediaServerReconciliationGuard.ShouldFlagMissingDescendants( + _logger, + $"show {ShowScope(show)} seasons", + incomingItemIds.Count, + existingSeasons.Count, + projectionFailures.Count)) { - _logger.LogWarning("Failed to reindex media items from scanner process"); + // trash seasons that are no longer present on the media server + var fileNotFoundItemIds = existingSeasons.Map(s => s.MediaServerItemId).Except(incomingItemIds).ToList(); + List ids = await televisionRepository.FlagFileNotFoundSeasons(library, fileNotFoundItemIds, cancellationToken); + + // #476: a season gone from the media server (while its show remains) is absent from the incoming + // list, so the per-season loop never visits it and the episode sweep in ScanEpisodes never runs + // for it. Cascade the flag to its episodes. + List episodeIds = await televisionRepository.FlagFileNotFoundEpisodesForSeasons(ids, cancellationToken); + + if (!await _scannerProxy.ReindexMediaItems(ids.Concat(episodeIds).ToArray(), cancellationToken)) + { + _logger.LogWarning("Failed to reindex media items from scanner process"); + } } return Unit.Default; @@ -423,6 +466,7 @@ public abstract class MediaServerTelevisionLibraryScanner> episodeEntries, + MediaServerProjectionFailureCounter projectionFailures, bool deepScan, CancellationToken cancellationToken) { @@ -570,12 +614,24 @@ public abstract class MediaServerTelevisionLibraryScanner m.MediaServerItemId).Except(incomingItemIds).ToList(); - List ids = await televisionRepository.FlagFileNotFoundEpisodes(library, fileNotFoundItemIds, cancellationToken); - if (!await _scannerProxy.ReindexMediaItems(ids.ToArray(), cancellationToken)) + // #484: the highest-stakes sweep in the scanner. A ProjectToEpisode regression fires for every + // episode of every season, so each season enumerates zero and existing.Except([]) is the entire + // episode library — permanently deleted by EmptyTrashHandler. A per-parent EMPTY fetch with no + // failures is still swept, unchanged (#477 scoped that case out on purpose). + if (MediaServerReconciliationGuard.ShouldFlagMissingDescendants( + _logger, + $"season {season.SeasonNumber} of show {ShowScope(show)} episodes", + incomingItemIds.Count, + existingEpisodes.Count, + projectionFailures.Count)) { - _logger.LogWarning("Failed to reindex media items from scanner process"); + // trash episodes that are no longer present on the media server + var fileNotFoundItemIds = existingEpisodes.Map(m => m.MediaServerItemId).Except(incomingItemIds).ToList(); + List ids = await televisionRepository.FlagFileNotFoundEpisodes(library, fileNotFoundItemIds, cancellationToken); + if (!await _scannerProxy.ReindexMediaItems(ids.ToArray(), cancellationToken)) + { + _logger.LogWarning("Failed to reindex media items from scanner process"); + } } return Unit.Default; diff --git a/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs b/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs index 8ef4a7def..ccb9585de 100644 --- a/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs +++ b/ErsatzTV.Scanner/Core/Plex/PlexTelevisionLibraryScanner.cs @@ -244,10 +244,13 @@ public partial class PlexTelevisionLibraryScanner : connectionParameters.Connection, connectionParameters.Token); + // #484: as with shows, Plex's season/episode projections return bare entities with no catch, so a + // bad item throws and unwinds the scan instead of being silently dropped — nothing to count here. protected override IAsyncEnumerable> GetSeasonLibraryItems( PlexLibrary library, PlexConnectionParameters connectionParameters, - PlexShow show) => + PlexShow show, + MediaServerProjectionFailureCounter projectionFailures) => _plexServerApiClient.GetShowSeasons( library, show, @@ -259,7 +262,8 @@ public partial class PlexTelevisionLibraryScanner : PlexConnectionParameters connectionParameters, PlexShow show, PlexSeason season, - bool isNewSeason) => + bool isNewSeason, + MediaServerProjectionFailureCounter projectionFailures) => _plexServerApiClient.GetSeasonEpisodes( library, season, diff --git a/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs b/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs index 7bd74b8e2..92d359b6b 100644 --- a/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs +++ b/ErsatzTV.Tests/Integration/JellyfinMusicVideoLibraryScannerTests.cs @@ -397,6 +397,84 @@ public class JellyfinMusicVideoLibraryScannerTests // alone would only ever reach music videos ADDED after it — an EXISTING item whose album/track is set or // corrected in Jellyfin would keep its stale value forever. Same shape as the #497 collection bug, one // layer up. Non-vacuous: reverting the two assignments in UpdateMetadata fails both assertions below. + // #484: music videos are HARD-deleted by this sweep (there is no per-item FileNotFound seam), so a + // silently dropped projection is immediately destructive here. Parameterised with its own positive + // control: identical arrangement, only the failure count differs. + [TestCase(1, false, TestName = "MusicVideo_Sweep_Is_Skipped_When_A_Projection_Failed")] + [TestCase(0, true, TestName = "MusicVideo_Sweep_Still_Runs_With_No_Projection_Failures")] + public async Task MusicVideo_Sweep_Respects_Projection_Failures(int failures, bool expectDelete) + { + JellyfinLibrary library = BuildLibrary(1, "/data/music"); + var connectionParameters = new JellyfinConnectionParameters("http://jellyfin", "api-key", 1); + const string KeepPath = "/data/music/artist1/song1.mkv"; + const string GonePath = "/data/music/artist1/song2.mkv"; + + var existing = new MusicVideo + { + Id = 7, + ArtistId = 3, + MediaVersions = + [ + new MediaVersion + { + MediaFiles = [new MediaFile { Path = KeepPath }], + Streams = [] + } + ], + MusicVideoMetadata = + [ + new MusicVideoMetadata { Id = 11, Genres = [], Tags = [], Studios = [], Artists = [] } + ] + }; + + var artistRepository = Substitute.For(); + artistRepository.GetArtistByMetadata(Arg.Any(), Arg.Any()) + .Returns(Some(new Artist { Id = 3, ArtistMetadata = new List() })); + artistRepository.DeleteEmptyArtists(Arg.Any()).Returns(new List()); + + var musicVideoRepository = Substitute.For(); + musicVideoRepository + .GetOrAdd(Arg.Any(), Arg.Any(), Arg.Any(), Arg.Any()) + .Returns(Right>( + new MediaItemScanResult(existing) { IsAdded = false })); + + // two rows exist locally, only one comes back — a genuine partial deletion, so #477's empty + // branch cannot mask the assertion + musicVideoRepository.FindMusicVideoPaths(Arg.Any()) + .Returns(new List { KeepPath, GonePath }.AsEnumerable()); + musicVideoRepository.DeleteByPath(Arg.Any(), Arg.Any()).Returns(new List { 7 }); + + var metadataRepository = Substitute.For(); + metadataRepository.Update(Arg.Any()).Returns(true); + metadataRepository.UpdateStatistics(Arg.Any(), Arg.Any(), Arg.Any()) + .Returns(false); + + var libraryRepository = Substitute.For(); + libraryRepository.GetParentFolderId(Arg.Any(), Arg.Any(), Arg.Any()) + .Returns(Option.None); + libraryRepository.GetOrAddFolder(Arg.Any(), Arg.Any>(), Arg.Any()) + .Returns(new LibraryFolder { Id = 5, Path = "/data/music/artist1" }); + + JellyfinMusicVideoLibraryScanner scanner = BuildScannerWith( + FakeApiWithProjectionFailures(failures, () => BuildIncoming(KeepPath, "Artist 1", "Song 1")), + artistRepository, + musicVideoRepository, + libraryRepository, + metadataRepository); + + (await scanner.ScanLibrary(connectionParameters, library, deepScan: false, CancellationToken.None)) + .IsRight.ShouldBeTrue(); + + if (expectDelete) + { + await musicVideoRepository.Received(1).DeleteByPath(Arg.Any(), GonePath); + } + else + { + await musicVideoRepository.DidNotReceive().DeleteByPath(Arg.Any(), Arg.Any()); + } + } + [Test] public async Task ScanLibrary_Should_Update_Album_And_Track_On_Rescan_Of_Existing_Item() { @@ -671,6 +749,44 @@ public class JellyfinMusicVideoLibraryScannerTests return (scanner, scannerProxy); } + // #484 finding 3: the api client records projection failures into the counter the SCANNER created and + // handed it. This fake does the same, so the test exercises the same-instance join that + // JellyfinMusicVideoLibraryScanner.ScanLibrary makes between GetMusicVideoLibraryItems and the sweep. + private static IJellyfinApiClient FakeApiWithProjectionFailures( + int projectionFailureCount, + params Func[] items) + { + var apiClient = Substitute.For(); + apiClient.GetMusicVideoLibraryItems( + Arg.Any(), + Arg.Any(), + Arg.Any(), + Arg.Any()) + .Returns(ci => ItemsWithFailures( + items, + projectionFailureCount, + ci.ArgAt(3))); + return apiClient; + } + + private static async IAsyncEnumerable> ItemsWithFailures( + Func[] items, + int projectionFailureCount, + MediaServerProjectionFailureCounter projectionFailures) + { + for (var i = 0; i < projectionFailureCount; i++) + { + projectionFailures.RecordFailure(); + } + + foreach (Func item in items) + { + yield return new Tuple(item(), items.Length + projectionFailureCount); + } + + await Task.CompletedTask; + } + // Each Func builds a fresh MusicVideo so the async stream can be re-enumerated across ScanLibrary calls // (an IAsyncEnumerable iterator is single-use, and the scanner mutates the incoming item). private static IJellyfinApiClient FakeApi(params Func[] items) diff --git a/docs/decisions.md b/docs/decisions.md index 36c439e6f..400518c3f 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -3779,8 +3779,8 @@ measuring is real signal; it just needs its own actor convention and wasn't wort change. ## 2026-07-25 — A media-server sweep also refuses when the api client silently dropped items whose projection threw; the ratio threshold is rejected (#484) `key: scan.projection-failure-sweep-guard` · `status: active` · `since: 2026-07-25` · `supersedes: none` · `superseded-by: none` -**Rule:** `MediaServerReconciliationGuard.ShouldFlagMissing` takes a per-enumeration projection-failure count and refuses the file-not-found sweep (logged loudly) whenever it is non-zero against a non-empty existing set; deliberate guard-clause skips (STRM, virtual, unsupported type) are explicitly **not** failures and never suppress a sweep. The missing-fraction / ratio threshold floated by #477 is **rejected**, not deferred. -**Signals:** projection failure, silently dropped item, deferred ratio threshold rejected, STRM skip vs failure, library sweep anti-nuke follow-up · paths: `MediaServerProjectionResult`, `MediaServerProjectionFailureCounter`, `MediaServerReconciliationGuard`, `JellyfinApiClient.GetPagedLibraryItems`, `EmbyApiClient.GetPagedLibraryContents` · issues: #484, #477, #476 +**Rule:** `MediaServerReconciliationGuard` takes a per-enumeration projection-failure count and refuses the file-not-found sweep (logged loudly) whenever it is non-zero against a non-empty existing set — at all six sweeps, including the nested per-show season and per-season episode ones #477 left unguarded (via `ShouldFlagMissingDescendants`, which applies the failure refusal but not #477's empty-fetch branch). Deliberate guard-clause skips (STRM, virtual, unsupported type) are explicitly **not** failures and never suppress a sweep. The missing-fraction / ratio threshold floated by #477 is **rejected**, not deferred. +**Signals:** projection failure, silently dropped item, deferred ratio threshold rejected, STRM skip vs failure, library sweep anti-nuke follow-up, nested season/episode sweep guard · paths: `MediaServerProjectionResult`, `MediaServerProjectionFailureCounter`, `MediaServerReconciliationGuard`, `JellyfinApiClient.GetPagedLibraryItems`, `EmbyApiClient.GetPagedLibraryContents` · issues: #484, #477, #476 **Mechanics:** `MediaServerReconciliationGuardTests` policy table · `JellyfinApiClientTests.ProjectionFailureCounter` · `MediaServerTelevisionLibraryScannerTests.Projection_Failure_Suppresses_The_Partial_Deletion_Sweep` This resolves both items the `scan.zero-item-fetch-guard` record (#477) left deferred. That record's rule @@ -3820,19 +3820,53 @@ This is a **second, independent** refusal on the same guard, plus a decision not scanner reads the count through an **optional trailing parameter** on only the library-level methods that actually feed a sweep (`IJellyfinApiClient.GetMovieLibraryItems` / `GetMusicVideoLibraryItems` / `GetShowLibraryItemsWithoutPeople`, `IEmbyApiClient.GetMovieLibraryItems` - / `GetShowLibraryItems`), so every other call site is untouched. A library that cannot be resolved - (`Option.None` inside a mapper) is treated as a **failure**, not a skip — fail closed. + / `GetShowLibraryItems`) **and** the nested season/episode ones (`GetSeasonLibraryItems`, + `GetEpisodeLibraryItems`, `GetEpisodeLibraryItemsWithoutPeople`), so every other call site is untouched. + A library that cannot be resolved (`Option.None` inside a mapper) is classed as a **failure** + rather than a skip; that branch is defensive and currently **unreachable** (every counted path passes a + concrete library, and the only `None` caller — collections — does not route through it), kept only so + the default classification is right if a future caller does pass `None`. - **The counter is per-enumeration state, never ambient.** `MediaServerProjectionFailureCounter` is created by the scanner that owns the sweep, handed to the single enumeration whose result it will diff, and read only after that enumeration completes. It is never a field on an api client (those are long-lived and shared) and never static, so concurrent scans of different libraries cannot leak failures into each other's sweep decision; increments are interlocked so a paginator that ever fans out stays correct. -- **Wired into the four real sweep call sites**, matching #477's scope exactly: the three library-level - base scanners (`MediaServerMovieLibraryScanner`, `MediaServerTelevisionLibraryScanner`, - `MediaServerOtherVideoLibraryScanner`) and `JellyfinMusicVideoLibraryScanner`. The nested TV - season/episode sweeps stay unguarded for the reasons in `scan.zero-item-fetch-guard`, and +- **Wired into all six sweeps, not #477's four.** The four library-level ones — the three base scanners + (`MediaServerMovieLibraryScanner`, `MediaServerTelevisionLibraryScanner`, + `MediaServerOtherVideoLibraryScanner`) plus `JellyfinMusicVideoLibraryScanner` — **and** the two nested + TV ones, `ScanSeasons`' `FlagFileNotFoundSeasons` and `ScanEpisodes`' `FlagFileNotFoundEpisodes`. `ScanLibraryWithoutCleanup` (single-show rescan) passes no counter because it runs no sweep. +- **The nested season/episode sweeps get the failure refusal but NOT #477's empty-fetch branch.** + `scan.zero-item-fetch-guard` left them unguarded because "the blast radius is one show's seasons / one + season's episodes, not the whole library." That reasoning is sound for a per-parent **empty fetch** — a + plausible legitimate state, bounded to one parent — but it does **not** transfer to a projection + failure, which is systematic by construction: one bad code path fires on every parent, so a + `ProjectToEpisode` regression makes *every* season enumerate zero episodes and + `existing.Except([])` sweeps the **entire** episode library in a single scan, which `EmptyTrashHandler` + then deletes permanently. Same shape for `ProjectToSeason` plus #476's cascade. So the nested sweeps + call `MediaServerReconciliationGuard.ShouldFlagMissingDescendants` — the **same class and the same + private failure predicate** as `ShouldFlagMissing`, deliberately without the empty-fetch branch. A + separate entry point rather than reusing `ShouldFlagMissing` wholesale, because importing #477's + zero-count branch here would silently change per-parent behaviour and break #476's cascade, which + depends on an emptied parent still sweeping. One class still owns the invariant; only the empty-fetch + policy differs, and the difference is pinned by a test. +- **Known residual: a mass *Skip* is not covered, by design, and one skip site is response-shape + dependent.** The whole split rests on skips being permanent and item-intrinsic. Emby's + `ProjectToMovie` guard (`MediaSources is null || Count == 0`) does not fully satisfy that: it is + response-shape dependent, so a Refit/DTO drift or a `fields`-parameter regression would present as a + mass **Skip**, which by construction leaves the sweep enabled. A *total* such regression is caught by + #477's zero-incoming branch; a *partial* one (say 1,200 incoming vs 2,000 existing, zero failures) + would sweep 800 healthy movies into `FileNotFound`. Plex's pre-projection + `.Filter(m => m.Media.Count > 0 …)` is the same class. This is stated rather than engineered around: + re-classifying shape-dependent skips as failures would reintroduce exactly the STRM-style permanent + suppression the split exists to prevent. Treat it as the known next question if a mass-skip incident + ever occurs. +- **Log-contract note.** When both refusals apply, only the #484 "silently dropped …" warning is emitted, + not #477's "returned zero items" line — the failure names the actual cause, and emitting both would + imply two independent problems. Operator alerting that greps the #477 string will not fire in that + case. The message property is `{Scope}` (e.g. `library Movies`, `show Keeper seasons`, + `season 1 of show Keeper episodes`), not `{Library}`, so one alert pattern covers all six sweeps. - **Plex reports zero failures because it has none.** `PlexServerApiClient`'s movie/show/other-video projections return a bare entity with no `Option` and no `catch`, so a bad item throws and unwinds the whole scan — the pre-existing "protection by accident of control flow" that #477 named. The Plex @@ -3848,4 +3882,16 @@ This is a **second, independent** refusal on the same guard, plus a decision not instance keep separate counts. `MediaServerTelevisionLibraryScannerTests .Projection_Failure_Suppresses_The_Partial_Deletion_Sweep` is the integration pair to #476's cascade test: identical arrangement, only the counter differs, so the cascade test is the positive control - that keeps the new test from passing vacuously. + that keeps the new test from passing vacuously. The nested levels get + `Season_Sweep_Respects_Projection_Failures` and `Episode_Sweep_Respects_Projection_Failures`, each + parameterised with its own zero-failure positive control, plus guard tests asserting the descendant + entry point still sweeps a per-parent **empty** fetch (the #477-scope invariant) and still sweeps when + only deliberate skips shortened the incoming set. +- **Tests pin the JOIN, not just the two halves.** A client test proving the counter fills, plus a + scanner test proving the guard honours a counter it is handed, would both stay green if a refactor + handed the api client a *fresh* counter while the sweep read the local one — silently killing the + protection. `MediaServerMovieLibraryScannerTests.Projection_Failure_From_The_Api_Suppresses_The_Sweep_ + End_To_End`, `MediaServerTelevisionLibraryScannerTests.Public_ScanLibrary_Joins_The_Api_Counter_To_The_ + Sweep`, the two nested TV cases, and `JellyfinMusicVideoLibraryScannerTests + .MusicVideo_Sweep_Respects_Projection_Failures` all drive the real `ScanLibrary` entry point and record + the failure from *inside* the enumeration, so same-instance wiring is what makes them pass. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index fcfc67c4d..526c7874a 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -114,7 +114,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `scan.getoraddfolder-db-lookup` | `ILibraryRepository.GetOrAddFolder` resolves the existing folder via a DB query on `(LibraryPathId, Path)`, not the caller's `LibraryPath.LibraryFolders` in-memory navigation, since that navigation is only eager-loaded on the local scan path and is null on remote (Jellyfin) callers. | 2026-07-20 | [link](../decisions.md#2026-07-20--ilibraryrepositorygetoraddfolder-resolves-the-folder-from-the-db-not-the-callers-librarypathlibraryfolders-navigation-488) | | `scan.jellyfin-mixed-content-library` | A Jellyfin library whose collection type is `mixed` (or absent) maps to one ErsatzTV library of `LibraryMediaKind.Mixed`, scanned by running the movie/television/music-video scanners in sequence against that single library — a library is a place, not a media kind. | 2026-07-20 | [link](../decisions.md#2026-07-20-489--jellyfin-mixed-content-libraries-map-to-one-library-holding-many-kinds) | | `scan.musicvideo-reconciliation` | `JellyfinMusicVideoLibraryScanner` reconciles removed music videos by a library-scoped local-path diff plus hard delete (`TrashMissingMusicVideos`), not the server-itemId soft-trash pattern the other media-server scanners use, because music videos carry no server identity. | 2026-07-20 | [link](../decisions.md#2026-07-20--jellyfinmusicvideolibraryscanner-reconciles-by-library-scoped-path-diff--hard-delete-not-server-itemid-soft-trash-494) | -| `scan.projection-failure-sweep-guard` | `MediaServerReconciliationGuard.ShouldFlagMissing` takes a per-enumeration projection-failure count and refuses the file-not-found sweep (logged loudly) whenever it is non-zero against a non-empty existing set; deliberate guard-clause skips (STRM, virtual, unsupported type) are explicitly **not** failures and never suppress a sweep. The missing-fraction / ratio threshold floated by #477 is **rejected**, not deferred. | 2026-07-25 | [link](../decisions.md#2026-07-25--a-media-server-sweep-also-refuses-when-the-api-client-silently-dropped-items-whose-projection-threw-the-ratio-threshold-is-rejected-484) | +| `scan.projection-failure-sweep-guard` | `MediaServerReconciliationGuard` takes a per-enumeration projection-failure count and refuses the file-not-found sweep (logged loudly) whenever it is non-zero against a non-empty existing set — at all six sweeps, including the nested per-show season and per-season episode ones #477 left unguarded (via `ShouldFlagMissingDescendants`, which applies the failure refusal but not #477's empty-fetch branch). Deliberate guard-clause skips (STRM, virtual, unsupported type) are explicitly **not** failures and never suppress a sweep. The missing-fraction / ratio threshold floated by #477 is **rejected**, not deferred. | 2026-07-25 | [link](../decisions.md#2026-07-25--a-media-server-sweep-also-refuses-when-the-api-client-silently-dropped-items-whose-projection-threw-the-ratio-threshold-is-rejected-484) | | `scan.zero-item-fetch-guard` | A media-server library sweep refuses to flag missing items when a successful fetch returns zero incoming items against a non-empty existing set (`MediaServerReconciliationGuard.ShouldFlagMissing`), rather than treating an ambiguous empty result as a full-library deletion. | 2026-07-19 | [link](../decisions.md#2026-07-19--a-media-server-library-sweep-refuses-to-flag-when-a-successful-fetch-returns-zero-items-rather-than-nuking-the-whole-library-477) | | `sched.auto-tune-foundation` | Auto-tune preview enumeration uses EF distinct+count queries for exact counts, while each created channel is persisted as a live SmartCollection; coexistence with existing channels/numbers is additive-only, never mutating. | 2026-07-16 | [link](../decisions.md#2026-07-16--auto-tuning-enumerates-via-ef-persists-via-smartcollection-additive-coexistence-69) | | `sched.autotune-detailpanel-members` | The Auto-Tune DetailPanel's per-channel content-source list is a live `ISearchIndex.Search` roll-up through the server-owned `AutoTuneAxisMap.GenerateQuery`, not an EF distinct+count query, so the preview matches exactly what the built channel's SmartCollection will contain. | 2026-07-17 | [link](../decisions.md#2026-07-17--auto-tune-detailpanel-member-list--live-search-index-roll-up-not-ef-enumeration-384) | -- 2.47.3 From 7cc12881de7252d6734aa8ee7f2a827924b7d77a Mon Sep 17 00:00:00 2001 From: Timothy Date: Sat, 25 Jul 2026 15:16:59 +0200 Subject: [PATCH 3/3] docs(484): correct the counted-enumeration counts on the api client interfaces Review follow-up. The comments still said three (Jellyfin) / two (Emby) library-level enumerations after the nested season and episode ones were counted, which understates the reach of the very safety property this branch establishes -- a future auditor reading them would conclude the nested sweeps are unprotected. --- ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs | 9 ++++++--- ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs | 9 ++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs b/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs index 446176af5..7378b01b5 100644 --- a/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs +++ b/ErsatzTV.Core/Interfaces/Emby/IEmbyApiClient.cs @@ -9,9 +9,12 @@ public interface IEmbyApiClient Task> GetServerInformation(string address, string apiKey); Task>> GetLibraries(string address, string apiKey); - // #484: the two library-level enumerations that feed a reconciliation sweep accept an optional - // per-enumeration counter. The caller creates one instance per enumeration and reads it only after - // the enumeration completes; passing null (the default) opts out and costs existing callers nothing. + // #484: the four enumerations that feed a reconciliation sweep accept an optional per-enumeration + // counter -- the two library-level ones (movies, shows) AND the two nested ones (seasons per show, + // episodes per season), which feed the per-parent sweeps in MediaServerTelevisionLibraryScanner. + // The caller creates one instance per enumeration, scoped to the parent it sweeps, and reads it + // only after that enumeration completes; passing null (the default) opts out and costs existing + // callers nothing. IAsyncEnumerable> GetMovieLibraryItems( string address, string apiKey, diff --git a/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs b/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs index 89f0802c3..8f2c94575 100644 --- a/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs +++ b/ErsatzTV.Core/Interfaces/Jellyfin/IJellyfinApiClient.cs @@ -9,9 +9,12 @@ public interface IJellyfinApiClient Task> GetServerInformation(string address, string authorizationHeader); Task>> GetLibraries(string address, string authorizationHeader); - // #484: the three library-level enumerations that feed a reconciliation sweep accept an optional - // per-enumeration counter. The caller creates one instance per enumeration and reads it only after - // the enumeration completes; passing null (the default) opts out and costs existing callers nothing. + // #484: the six enumerations that feed a reconciliation sweep accept an optional per-enumeration + // counter -- the three library-level ones (movies, music videos, shows) AND the three nested ones + // (seasons per show, episodes per season, both episode variants), which feed the per-parent sweeps + // in MediaServerTelevisionLibraryScanner. The caller creates one instance per enumeration, scoped + // to the parent it sweeps, and reads it only after that enumeration completes; passing null (the + // default) opts out and costs existing callers nothing. IAsyncEnumerable> GetMovieLibraryItems( string address, string authorizationHeader, -- 2.47.3