feat(484): suppress the media-server sweep on projection failures; reject the ratio threshold #612

Merged
timothy merged 3 commits from feat/484-scanner-guard-threshold into main 2026-07-25 17:08:08 +02:00
26 changed files with 1635 additions and 172 deletions
@@ -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,22 +9,40 @@ public interface IEmbyApiClient
Task<Either<BaseError, EmbyServerInformation>> GetServerInformation(string address, string apiKey);
Task<Either<BaseError, List<EmbyLibrary>>> GetLibraries(string address, string apiKey);
IAsyncEnumerable<Tuple<EmbyMovie, int>> GetMovieLibraryItems(string address, string apiKey, EmbyLibrary library);
// #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<Tuple<EmbyMovie, int>> GetMovieLibraryItems(
string address,
string apiKey,
EmbyLibrary library,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<EmbyShow, int>> GetShowLibraryItems(string address, string apiKey, EmbyLibrary library);
IAsyncEnumerable<Tuple<EmbyShow, int>> GetShowLibraryItems(
string address,
string apiKey,
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<Tuple<EmbySeason, int>> GetSeasonLibraryItems(
string address,
string apiKey,
EmbyLibrary library,
string showId);
string showId,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<EmbyEpisode, int>> GetEpisodeLibraryItems(
string address,
string apiKey,
EmbyLibrary library,
string showId,
string seasonId);
string seasonId,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<EmbyCollection, int>> GetCollectionLibraryItems(string address, string apiKey);
@@ -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,38 +9,52 @@ public interface IJellyfinApiClient
Task<Either<BaseError, JellyfinServerInformation>> GetServerInformation(string address, string authorizationHeader);
Task<Either<BaseError, List<JellyfinLibrary>>> GetLibraries(string address, string authorizationHeader);
// #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<Tuple<JellyfinMovie, int>> GetMovieLibraryItems(
string address,
string authorizationHeader,
JellyfinLibrary library);
JellyfinLibrary library,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<MusicVideo, int>> GetMusicVideoLibraryItems(
string address,
string authorizationHeader,
JellyfinLibrary library);
JellyfinLibrary library,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<JellyfinShow, int>> GetShowLibraryItemsWithoutPeople(
string address,
string authorizationHeader,
JellyfinLibrary library);
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<Tuple<JellyfinSeason, int>> GetSeasonLibraryItems(
string address,
string authorizationHeader,
JellyfinLibrary library,
string showId);
string showId,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<JellyfinEpisode, int>> GetEpisodeLibraryItems(
string address,
string authorizationHeader,
JellyfinLibrary library,
string seasonId);
string seasonId,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<JellyfinEpisode, int>> GetEpisodeLibraryItemsWithoutPeople(
string address,
string authorizationHeader,
JellyfinLibrary library,
string seasonId);
string seasonId,
MediaServerProjectionFailureCounter projectionFailures = null);
IAsyncEnumerable<Tuple<JellyfinCollection, int>> GetCollectionLibraryItems(
string address,
@@ -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;
/// <summary>
/// Number of items the server returned whose projection threw and was swallowed.
/// </summary>
public int Count => Volatile.Read(ref _count);
public void RecordFailure() => Interlocked.Increment(ref _count);
}
@@ -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<T>
{
private MediaServerProjectionResult(Option<T> item, bool isFailure)
{
Item = item;
IsFailure = isFailure;
}
public Option<T> Item { get; }
/// <summary>
/// True only when the projection threw. A deliberate guard-clause skip is NOT a failure.
/// </summary>
public bool IsFailure { get; }
public static MediaServerProjectionResult<T> Projected(T item) => new(item, false);
/// <summary>
/// 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.
/// </summary>
public static MediaServerProjectionResult<T> Skipped() => new(Option<T>.None, false);
/// <summary>
/// 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.
/// </summary>
public static MediaServerProjectionResult<T> Failed() => new(Option<T>.None, true);
public static implicit operator MediaServerProjectionResult<T>(T item) => Projected(item);
public Option<T> ToOption() => Item;
}
@@ -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<IJellyfinPathReplacementService>(),
Substitute.For<IFallbackMetadataProvider>(),
new SingleResponseHttpClientFactory(response),
Substitute.For<ILogger<JellyfinApiClient>>());
// 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<MusicVideo> 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<IJellyfinPathReplacementService>();
pathReplacementService.ReplaceNetworkPath(
Arg.Any<JellyfinMediaSource>(),
Arg.Any<string>(),
Arg.Any<string>(),
Arg.Any<string>())
.Returns(_ => throw new InvalidOperationException("simulated projection regression"));
var client = new JellyfinApiClient(
new MemoryCache(new MemoryCacheOptions()),
pathReplacementService,
Substitute.For<IFallbackMetadataProvider>(),
new SingleResponseHttpClientFactory(response),
Substitute.For<ILogger<JellyfinApiClient>>());
var library = new JellyfinLibrary
{
Id = 42,
MediaSourceId = 1,
ItemId = "library-1",
PathInfos = [new JellyfinPathInfo { NetworkPath = "/network", Path = "/local" }]
};
var counter = new MediaServerProjectionFailureCounter();
List<MusicVideo> 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<IJellyfinPathReplacementService>();
pathReplacementService.ReplaceNetworkPath(
Arg.Any<JellyfinMediaSource>(),
Arg.Any<string>(),
Arg.Any<string>(),
Arg.Any<string>())
.Returns(_ => throw new InvalidOperationException("simulated projection regression"));
var client = new JellyfinApiClient(
new MemoryCache(new MemoryCacheOptions()),
pathReplacementService,
Substitute.For<IFallbackMetadataProvider>(),
new SingleResponseHttpClientFactory(failingResponse),
Substitute.For<ILogger<JellyfinApiClient>>());
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));
+71 -33
View File
@@ -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<Tuple<EmbyMovie, int>> 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<Tuple<EmbyShow, int>> GetShowLibraryItems(
string address,
string apiKey,
EmbyLibrary library)
EmbyLibrary library,
MediaServerProjectionFailureCounter projectionFailures = null)
=> GetPagedLibraryContents(
address,
library,
@@ -97,13 +100,15 @@ public class EmbyApiClient : IEmbyApiClient
itemId,
startIndex: skip,
limit: pageSize),
(_, item) => ProjectToShow(item));
(_, item) => ProjectToShow(item),
projectionFailures);
public IAsyncEnumerable<Tuple<EmbySeason, int>> GetSeasonLibraryItems(
string address,
string apiKey,
EmbyLibrary library,
string showId) => GetPagedLibraryContents(
string showId,
MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryContents(
address,
library,
showId,
@@ -112,14 +117,16 @@ public class EmbyApiClient : IEmbyApiClient
itemId,
startIndex: skip,
limit: pageSize),
(_, item) => ProjectToSeason(item));
(_, item) => ProjectToSeason(item),
projectionFailures);
public IAsyncEnumerable<Tuple<EmbyEpisode, int>> GetEpisodeLibraryItems(
string address,
string apiKey,
EmbyLibrary library,
string showId,
string seasonId) => GetPagedLibraryContents(
string seasonId,
MediaServerProjectionFailureCounter projectionFailures = null) => GetPagedLibraryContents(
address,
library,
seasonId,
@@ -129,7 +136,8 @@ 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)),
projectionFailures);
public IAsyncEnumerable<Tuple<EmbyCollection, int>> GetCollectionLibraryItems(string address, string apiKey)
{
@@ -208,7 +216,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 +259,7 @@ public class EmbyApiClient : IEmbyApiClient
foreach (EmbyLibraryItemResponse item in detailResponse.Items)
{
Option<EmbyShow> maybeShow = ProjectToShow(item);
Option<EmbyShow> maybeShow = ProjectToShow(item).ToOption();
foreach (EmbyShow show in maybeShow)
{
shows.Add(show);
@@ -269,12 +277,22 @@ public class EmbyApiClient : IEmbyApiClient
}
}
// #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<TItem> WithLibrary<TItem>(
Option<EmbyLibrary> maybeLibrary,
Func<EmbyLibrary, MediaServerProjectionResult<TItem>> project) =>
maybeLibrary.Match(project, MediaServerProjectionResult<TItem>.Failed);
private static async IAsyncEnumerable<Tuple<TItem, int>> GetPagedLibraryContents<TItem>(
string address,
Option<EmbyLibrary> maybeLibrary,
string parentId,
Func<IEmbyApi, string, int, int, Task<EmbyLibraryItemsResponse>> getItems,
Func<Option<EmbyLibrary>, EmbyLibraryItemResponse, Option<TItem>> mapper)
Func<Option<EmbyLibrary>, EmbyLibraryItemResponse, MediaServerProjectionResult<TItem>> mapper,
MediaServerProjectionFailureCounter projectionFailures = null)
{
IEmbyApi service = RestService.For<IEmbyApi>(address);
const int PAGE_SIZE = 10;
@@ -290,15 +308,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<TItem, int>(item, result.TotalRecordCount);
MediaServerProjectionResult<TItem> 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<TItem, int>(item, result.TotalRecordCount);
}
}
}
}
private Option<EmbyCollection> ProjectToCollection(EmbyLibraryItemResponse item)
// NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure.
private MediaServerProjectionResult<EmbyCollection> ProjectToCollection(EmbyLibraryItemResponse item)
{
try
{
@@ -312,27 +344,27 @@ public class EmbyApiClient : IEmbyApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Emby collection");
return None;
return MediaServerProjectionResult<EmbyCollection>.Failed();
}
}
private Option<MediaItem> ProjectToCollectionMediaItem(EmbyLibraryItemResponse item)
private MediaServerProjectionResult<MediaItem> 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<MediaItem>.None
"Movie" => MediaServerProjectionResult<MediaItem>.Projected(new EmbyMovie { ItemId = item.Id }),
"Series" => MediaServerProjectionResult<MediaItem>.Projected(new EmbyShow { ItemId = item.Id }),
"Season" => MediaServerProjectionResult<MediaItem>.Projected(new EmbySeason { ItemId = item.Id }),
"Episode" => MediaServerProjectionResult<MediaItem>.Projected(new EmbyEpisode { ItemId = item.Id }),
_ => MediaServerProjectionResult<MediaItem>.Skipped()
};
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Emby collection media item");
return None;
return MediaServerProjectionResult<MediaItem>.Failed();
}
}
@@ -377,13 +409,15 @@ public class EmbyApiClient : IEmbyApiClient
return None;
}
private Option<EmbyMovie> ProjectToMovie(EmbyLibrary library, EmbyLibraryItemResponse item)
private MediaServerProjectionResult<EmbyMovie> ProjectToMovie(
EmbyLibrary library,
EmbyLibraryItemResponse item)
{
try
{
if (item.MediaSources is null || item.MediaSources.Count == 0)
{
return None;
return MediaServerProjectionResult<EmbyMovie>.Skipped();
}
string path = item.Path ?? string.Empty;
@@ -434,7 +468,7 @@ public class EmbyApiClient : IEmbyApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Emby movie");
return None;
return MediaServerProjectionResult<EmbyMovie>.Failed();
}
}
@@ -564,7 +598,8 @@ public class EmbyApiClient : IEmbyApiClient
return new Writer { Name = person.Name };
}
private Option<EmbyShow> ProjectToShow(EmbyLibraryItemResponse item)
// NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure.
private MediaServerProjectionResult<EmbyShow> ProjectToShow(EmbyLibraryItemResponse item)
{
try
{
@@ -583,7 +618,7 @@ public class EmbyApiClient : IEmbyApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Emby show");
return None;
return MediaServerProjectionResult<EmbyShow>.Failed();
}
}
@@ -657,7 +692,8 @@ public class EmbyApiClient : IEmbyApiClient
return metadata;
}
private Option<EmbySeason> ProjectToSeason(EmbyLibraryItemResponse item)
// NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure.
private MediaServerProjectionResult<EmbySeason> ProjectToSeason(EmbyLibraryItemResponse item)
{
try
{
@@ -716,17 +752,19 @@ public class EmbyApiClient : IEmbyApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Emby show");
return None;
return MediaServerProjectionResult<EmbySeason>.Failed();
}
}
private Option<EmbyEpisode> ProjectToEpisode(EmbyLibrary library, EmbyLibraryItemResponse item)
private MediaServerProjectionResult<EmbyEpisode> ProjectToEpisode(
EmbyLibrary library,
EmbyLibraryItemResponse item)
{
try
{
if (item.LocationType == "Virtual")
{
return None;
return MediaServerProjectionResult<EmbyEpisode>.Skipped();
}
string path = item.Path ?? string.Empty;
@@ -777,7 +815,7 @@ public class EmbyApiClient : IEmbyApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Emby movie");
return None;
return MediaServerProjectionResult<EmbyEpisode>.Failed();
}
}
@@ -79,7 +79,8 @@ public class JellyfinApiClient : IJellyfinApiClient
public IAsyncEnumerable<Tuple<JellyfinMovie, int>> 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<Tuple<MusicVideo, int>> 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<Tuple<JellyfinShow, int>> GetShowLibraryItemsWithoutPeople(
string address,
string authorizationHeader,
JellyfinLibrary library) =>
JellyfinLibrary library,
MediaServerProjectionFailureCounter projectionFailures = null) =>
GetPagedLibraryItems(
"JF Shows",
address,
@@ -125,13 +130,15 @@ public class JellyfinApiClient : IJellyfinApiClient
itemId,
startIndex: skip,
limit: pageSize),
(_, item) => ProjectToShow(item));
(_, item) => ProjectToShow(item),
projectionFailures);
public IAsyncEnumerable<Tuple<JellyfinSeason, int>> GetSeasonLibraryItems(
string address,
string authorizationHeader,
JellyfinLibrary library,
string showId) =>
string showId,
MediaServerProjectionFailureCounter projectionFailures = null) =>
GetPagedLibraryItems(
"JF Seasons",
address,
@@ -143,13 +150,15 @@ public class JellyfinApiClient : IJellyfinApiClient
showId,
startIndex: skip,
limit: pageSize),
(_, item) => ProjectToSeason(item));
(_, item) => ProjectToSeason(item),
projectionFailures);
public IAsyncEnumerable<Tuple<JellyfinEpisode, int>> GetEpisodeLibraryItems(
string address,
string authorizationHeader,
JellyfinLibrary library,
string seasonId) =>
string seasonId,
MediaServerProjectionFailureCounter projectionFailures = null) =>
GetPagedLibraryItems(
"JF Episodes*",
address,
@@ -161,13 +170,15 @@ 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)),
projectionFailures);
public IAsyncEnumerable<Tuple<JellyfinEpisode, int>> GetEpisodeLibraryItemsWithoutPeople(
string address,
string authorizationHeader,
JellyfinLibrary library,
string seasonId) =>
string seasonId,
MediaServerProjectionFailureCounter projectionFailures = null) =>
GetPagedLibraryItems(
"JF Episodes",
address,
@@ -179,7 +190,8 @@ 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)),
projectionFailures);
public IAsyncEnumerable<Tuple<JellyfinCollection, int>> GetCollectionLibraryItems(
string address,
@@ -269,7 +281,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 +325,7 @@ public class JellyfinApiClient : IJellyfinApiClient
foreach (JellyfinLibraryItemResponse item in detailResponse.Items)
{
Option<JellyfinShow> maybeShow = ProjectToShow(item);
Option<JellyfinShow> maybeShow = ProjectToShow(item).ToOption();
foreach (JellyfinShow show in maybeShow)
{
shows.Add(show);
@@ -353,7 +365,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 +378,15 @@ public class JellyfinApiClient : IJellyfinApiClient
}
}
// #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<TItem> WithLibrary<TItem>(
Option<JellyfinLibrary> maybeLibrary,
Func<JellyfinLibrary, MediaServerProjectionResult<TItem>> project) =>
maybeLibrary.Match(project, MediaServerProjectionResult<TItem>.Failed);
private async IAsyncEnumerable<Tuple<TItem, int>> GetPagedLibraryItems<TItem>(
string pageDescription,
string address,
@@ -373,7 +394,8 @@ public class JellyfinApiClient : IJellyfinApiClient
int mediaSourceId,
string parentId,
Func<IJellyfinApi, string, int, int, Task<JellyfinLibraryItemsResponse>> getItems,
Func<Option<JellyfinLibrary>, JellyfinLibraryItemResponse, Option<TItem>> mapper)
Func<Option<JellyfinLibrary>, JellyfinLibraryItemResponse, MediaServerProjectionResult<TItem>> mapper,
MediaServerProjectionFailureCounter projectionFailures = null)
{
IJellyfinApi service = ServiceForAddress(address);
@@ -396,41 +418,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<TItem, int>(item, result.TotalRecordCount);
MediaServerProjectionResult<TItem> 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<TItem, int>(item, result.TotalRecordCount);
}
}
}
}
private Option<MediaItem> ProjectToCollectionMediaItem(JellyfinLibraryItemResponse item)
private MediaServerProjectionResult<MediaItem> ProjectToCollectionMediaItem(JellyfinLibraryItemResponse item)
{
try
{
if (item.LocationType != "FileSystem")
{
return None;
return MediaServerProjectionResult<MediaItem>.Skipped();
}
if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm")
{
_logger.LogWarning("STRM files are not supported; skipping {Path}", item.Path);
return None;
return MediaServerProjectionResult<MediaItem>.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<MediaItem>.Projected(new JellyfinMovie { ItemId = item.Id }),
"Series" => MediaServerProjectionResult<MediaItem>.Projected(new JellyfinShow { ItemId = item.Id }),
"Season" => MediaServerProjectionResult<MediaItem>.Projected(new JellyfinSeason { ItemId = item.Id }),
"Episode" => MediaServerProjectionResult<MediaItem>.Projected(
new JellyfinEpisode { ItemId = item.Id }),
_ => MediaServerProjectionResult<MediaItem>.Skipped()
};
}
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin collection media item");
return None;
return MediaServerProjectionResult<MediaItem>.Failed();
}
}
@@ -511,19 +547,21 @@ public class JellyfinApiClient : IJellyfinApiClient
return None;
}
private Option<JellyfinMovie> ProjectToMovie(JellyfinLibrary library, JellyfinLibraryItemResponse item)
private MediaServerProjectionResult<JellyfinMovie> ProjectToMovie(
JellyfinLibrary library,
JellyfinLibraryItemResponse item)
{
try
{
if (item.LocationType != "FileSystem")
{
return None;
return MediaServerProjectionResult<JellyfinMovie>.Skipped();
}
if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm")
{
_logger.LogInformation("STRM files are not supported; skipping {Path}", item.Path);
return None;
return MediaServerProjectionResult<JellyfinMovie>.Skipped();
}
string path = item.Path ?? string.Empty;
@@ -574,7 +612,7 @@ public class JellyfinApiClient : IJellyfinApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin movie");
return None;
return MediaServerProjectionResult<JellyfinMovie>.Failed();
}
}
@@ -663,19 +701,21 @@ public class JellyfinApiClient : IJellyfinApiClient
return metadata;
}
private Option<MusicVideo> ProjectToMusicVideo(JellyfinLibrary library, JellyfinLibraryItemResponse item)
private MediaServerProjectionResult<MusicVideo> ProjectToMusicVideo(
JellyfinLibrary library,
JellyfinLibraryItemResponse item)
{
try
{
if (item.LocationType != "FileSystem")
{
return None;
return MediaServerProjectionResult<MusicVideo>.Skipped();
}
if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm")
{
_logger.LogInformation("STRM files are not supported; skipping {Path}", item.Path);
return None;
return MediaServerProjectionResult<MusicVideo>.Skipped();
}
string path = item.Path ?? string.Empty;
@@ -724,7 +764,7 @@ public class JellyfinApiClient : IJellyfinApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin music video");
return None;
return MediaServerProjectionResult<MusicVideo>.Failed();
}
}
@@ -843,7 +883,8 @@ public class JellyfinApiClient : IJellyfinApiClient
return new Writer { Name = person.Name };
}
private Option<JellyfinShow> ProjectToShow(JellyfinLibraryItemResponse item)
// NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure.
private MediaServerProjectionResult<JellyfinShow> ProjectToShow(JellyfinLibraryItemResponse item)
{
try
{
@@ -862,7 +903,7 @@ public class JellyfinApiClient : IJellyfinApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin show");
return None;
return MediaServerProjectionResult<JellyfinShow>.Failed();
}
}
@@ -936,7 +977,8 @@ public class JellyfinApiClient : IJellyfinApiClient
return metadata;
}
private Option<JellyfinSeason> ProjectToSeason(JellyfinLibraryItemResponse item)
// NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure.
private MediaServerProjectionResult<JellyfinSeason> ProjectToSeason(JellyfinLibraryItemResponse item)
{
try
{
@@ -1005,11 +1047,12 @@ public class JellyfinApiClient : IJellyfinApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin season");
return None;
return MediaServerProjectionResult<JellyfinSeason>.Failed();
}
}
private Option<JellyfinCollection> ProjectToCollection(JellyfinLibraryItemResponse item)
// NOTE (#484): no deliberate-skip guard clause here — every drop from this projection is a failure.
private MediaServerProjectionResult<JellyfinCollection> ProjectToCollection(JellyfinLibraryItemResponse item)
{
try
{
@@ -1023,23 +1066,25 @@ public class JellyfinApiClient : IJellyfinApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin collection");
return None;
return MediaServerProjectionResult<JellyfinCollection>.Failed();
}
}
private Option<JellyfinEpisode> ProjectToEpisode(JellyfinLibrary library, JellyfinLibraryItemResponse item)
private MediaServerProjectionResult<JellyfinEpisode> ProjectToEpisode(
JellyfinLibrary library,
JellyfinLibraryItemResponse item)
{
try
{
if (item.LocationType != "FileSystem")
{
return None;
return MediaServerProjectionResult<JellyfinEpisode>.Skipped();
}
if (Path.GetExtension(item.Path)?.ToLowerInvariant() == ".strm")
{
_logger.LogWarning("STRM files are not supported; skipping {Path}", item.Path);
return None;
return MediaServerProjectionResult<JellyfinEpisode>.Skipped();
}
string path = item.Path ?? string.Empty;
@@ -1090,7 +1135,7 @@ public class JellyfinApiClient : IJellyfinApiClient
catch (Exception ex)
{
_logger.LogWarning(ex, "Error projecting Jellyfin episode");
return None;
return MediaServerProjectionResult<JellyfinEpisode>.Failed();
}
}
@@ -51,6 +51,107 @@ public class MediaServerMovieLibraryScannerTests
await scannerProxy.DidNotReceive().ReindexMediaItems(
Arg.Any<int[]>(), Arg.Any<CancellationToken>());
}
// #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<IJellyfinMovieRepository>();
var scannerProxy = Substitute.For<IScannerProxy>();
var library = new JellyfinLibrary { Id = 3, Name = "Movies" };
movieRepository.GetExistingMovies(library)
.Returns(new List<JellyfinItemEtag>
{
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<JellyfinMovie>(), Arg.Any<bool>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, MediaItemScanResult<JellyfinMovie>>(BaseError.New("skip metadata in test")));
scannerProxy.UpdateProgress(Arg.Any<decimal>(), Arg.Any<CancellationToken>()).Returns(true);
var scanner = new TestMovieLibraryScanner(scannerProxy)
{
MovieEntries =
[
new JellyfinMovie
{
ItemId = "movie-1",
Etag = "e1",
MovieMetadata = new List<MovieMetadata> { new() { Title = "Keeper" } }
}
],
ProjectionFailures = 1
};
Either<BaseError, Unit> result = await scanner.Scan(
movieRepository,
new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7),
library);
result.IsRight.ShouldBeTrue();
await movieRepository.DidNotReceive().FlagFileNotFound(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>());
}
// 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<IJellyfinMovieRepository>();
var scannerProxy = Substitute.For<IScannerProxy>();
var library = new JellyfinLibrary { Id = 3, Name = "Movies" };
movieRepository.GetExistingMovies(library)
.Returns(new List<JellyfinItemEtag>
{
new() { ItemId = "movie-1", Etag = "e1", State = MediaItemState.Normal },
new() { ItemId = "movie-2", Etag = "e2", State = MediaItemState.Normal }
});
movieRepository.GetOrAdd(library, Arg.Any<JellyfinMovie>(), Arg.Any<bool>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, MediaItemScanResult<JellyfinMovie>>(BaseError.New("skip metadata in test")));
scannerProxy.UpdateProgress(Arg.Any<decimal>(), Arg.Any<CancellationToken>()).Returns(true);
// an unstubbed substitute returns null, which would NRE on ids.ToArray()
movieRepository.FlagFileNotFound(Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>())
.Returns(new List<int> { 7 });
scannerProxy.ReindexMediaItems(Arg.Any<int[]>(), Arg.Any<CancellationToken>()).Returns(true);
var scanner = new TestMovieLibraryScanner(scannerProxy)
{
MovieEntries =
[
new JellyfinMovie
{
ItemId = "movie-1",
Etag = "e1",
MovieMetadata = new List<MovieMetadata> { new() { Title = "Keeper" } }
}
],
ProjectionFailures = 0
};
Either<BaseError, Unit> result = await scanner.Scan(
movieRepository,
new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7),
library);
result.IsRight.ShouldBeTrue();
await movieRepository.Received(1).FlagFileNotFound(
library,
Arg.Is<List<string>>(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,8 +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<Tuple<JellyfinMovie, int>> GetMovieLibraryItems(
JellyfinConnectionParameters connectionParameters, JellyfinLibrary library) => EmptyMovies();
JellyfinConnectionParameters connectionParameters,
JellyfinLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
Movies(MovieEntries, ProjectionFailures, projectionFailures);
protected override string MediaServerItemId(JellyfinMovie movie) => movie.ItemId;
protected override string MediaServerEtag(JellyfinMovie movie) => movie.Etag;
@@ -101,10 +210,22 @@ public class MediaServerMovieLibraryScannerTests
CancellationToken cancellationToken) =>
throw new NotSupportedException();
private static async IAsyncEnumerable<Tuple<JellyfinMovie, int>> EmptyMovies()
// mirrors production: failures are recorded DURING enumeration into the caller's counter
private static async IAsyncEnumerable<Tuple<JellyfinMovie, int>> 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<JellyfinMovie, int>(movie, movies.Length + projectionFailureCount);
}
}
}
}
@@ -79,7 +79,9 @@ public class MediaServerOtherVideoLibraryScannerTests
CancellationToken.None);
protected override IAsyncEnumerable<Tuple<PlexOtherVideo, int>> 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;
@@ -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,143 @@ 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<ILogger>();
MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 4, 5, 1).ShouldBeFalse();
logger.Received(1).Log(
LogLevel.Warning,
Arg.Any<EventId>(),
Arg.Any<object>(),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
// #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<ILogger>();
// 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<EventId>(),
Arg.Any<object>(),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
// 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<ILogger>();
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<ILogger>();
// 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<EventId>(),
Arg.Any<object>(),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
// #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<ILogger>();
MediaServerReconciliationGuard.ShouldFlagMissingDescendants(logger, "show Keeper seasons", 4, 5, 1)
.ShouldBeFalse();
logger.Received(1).Log(
LogLevel.Warning,
Arg.Any<EventId>(),
Arg.Any<object>(),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
// ...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<ILogger>();
MediaServerReconciliationGuard.ShouldFlagMissingDescendants(logger, "season 1 of show Keeper episodes", 0, 5, 0)
.ShouldBeTrue();
logger.DidNotReceive().Log(
LogLevel.Warning,
Arg.Any<EventId>(),
Arg.Any<object>(),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
[Test]
public void Descendant_Sweep_Runs_With_No_Failures_And_Is_A_Noop_When_Nothing_Exists()
{
var logger = Substitute.For<ILogger>();
// 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<EventId>(),
Arg.Any<object>(),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
// 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<ILogger>();
MediaServerReconciliationGuard.ShouldFlagMissing(logger, "Movies", 0, 5, 2).ShouldBeFalse();
logger.Received(1).Log(
LogLevel.Warning,
Arg.Any<EventId>(),
Arg.Is<object>(o => o.ToString()!.Contains("silently dropped")),
Arg.Any<Exception>(),
Arg.Any<Func<object, Exception?, string>>());
}
}
@@ -134,6 +134,271 @@ public class MediaServerTelevisionLibraryScannerTests
Arg.Any<int[]>(), Arg.Any<CancellationToken>());
}
// #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<IJellyfinTelevisionRepository>();
var scannerProxy = Substitute.For<IScannerProxy>();
var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" };
televisionRepository.GetExistingShows(library, Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag>
{
new() { ItemId = "show-keep", State = MediaItemState.Normal },
new() { ItemId = "show-6366", State = MediaItemState.Normal }
});
televisionRepository.GetOrAdd(library, Arg.Any<JellyfinShow>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, MediaItemScanResult<JellyfinShow>>(BaseError.New("skip metadata in test")));
scannerProxy.UpdateProgress(Arg.Any<decimal>(), Arg.Any<CancellationToken>()).Returns(true);
var projectionFailures = new MediaServerProjectionFailureCounter();
projectionFailures.RecordFailure();
var scanner = new TestTelevisionLibraryScanner(scannerProxy);
Either<BaseError, Unit> result = await scanner.Scan(
televisionRepository,
new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7),
library,
Shows(new JellyfinShow
{
ItemId = "show-keep",
ShowMetadata = new List<ShowMetadata> { new() { Title = "Keeper" } }
}),
projectionFailures);
result.IsRight.ShouldBeTrue();
await televisionRepository.DidNotReceive().FlagFileNotFoundShows(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>());
await televisionRepository.DidNotReceive().FlagFileNotFoundSeasonsForShows(
Arg.Any<List<int>>(), Arg.Any<CancellationToken>());
await televisionRepository.DidNotReceive().FlagFileNotFoundEpisodesForSeasons(
Arg.Any<List<int>>(), Arg.Any<CancellationToken>());
}
// #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<IJellyfinTelevisionRepository>();
var scannerProxy = Substitute.For<IScannerProxy>();
var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" };
televisionRepository.GetExistingShows(library, Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag>
{
new() { ItemId = "show-keep", State = MediaItemState.Normal },
new() { ItemId = "show-6366", State = MediaItemState.Normal }
});
televisionRepository.GetOrAdd(library, Arg.Any<JellyfinShow>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, MediaItemScanResult<JellyfinShow>>(BaseError.New("skip metadata in test")));
scannerProxy.UpdateProgress(Arg.Any<decimal>(), Arg.Any<CancellationToken>()).Returns(true);
var scanner = new TestTelevisionLibraryScanner(scannerProxy)
{
ShowEntries =
[
new JellyfinShow
{
ItemId = "show-keep",
ShowMetadata = new List<ShowMetadata> { new() { Title = "Keeper" } }
}
],
ShowProjectionFailures = 1
};
Either<BaseError, Unit> result = await scanner.ScanFromApi(
televisionRepository,
new JellyfinConnectionParameters("http://jellyfin.example", "abc", 7),
library);
result.IsRight.ShouldBeTrue();
await televisionRepository.DidNotReceive().FlagFileNotFoundShows(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>());
}
// #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<IJellyfinTelevisionRepository>();
var scannerProxy = Substitute.For<IScannerProxy>();
var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" };
var show = new JellyfinShow
{
ItemId = "show-1",
ShowMetadata = new List<ShowMetadata> { new() { Title = "Keeper" } }
};
televisionRepository.GetExistingShows(library, Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag> { new() { ItemId = "show-1", State = MediaItemState.Normal } });
televisionRepository.GetOrAdd(library, Arg.Any<JellyfinShow>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, MediaItemScanResult<JellyfinShow>>(new MediaItemScanResult<JellyfinShow>(show)));
scannerProxy.UpdateProgress(Arg.Any<decimal>(), Arg.Any<CancellationToken>()).Returns(true);
// two seasons exist, only one comes back — a partial deletion at the season level
televisionRepository.GetExistingSeasons(library, Arg.Any<JellyfinShow>(), Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag>
{
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<JellyfinSeason>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, MediaItemScanResult<JellyfinSeason>>(BaseError.New("skip season in test")));
// an unstubbed substitute returns null, which would NRE in the sweep's Concat
televisionRepository.FlagFileNotFoundSeasons(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>())
.Returns(new List<int> { 200 });
televisionRepository.FlagFileNotFoundEpisodesForSeasons(
Arg.Any<List<int>>(), Arg.Any<CancellationToken>())
.Returns(new List<int> { 300 });
televisionRepository.FlagFileNotFoundShows(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>())
.Returns(new List<int>());
televisionRepository.FlagFileNotFoundSeasonsForShows(
Arg.Any<List<int>>(), Arg.Any<CancellationToken>())
.Returns(new List<int>());
scannerProxy.ReindexMediaItems(Arg.Any<int[]>(), Arg.Any<CancellationToken>()).Returns(true);
var scanner = new TestTelevisionLibraryScanner(scannerProxy)
{
SeasonEntries = [new JellyfinSeason { ItemId = "season-keep", SeasonNumber = 1 }],
SeasonProjectionFailures = failures
};
Either<BaseError, Unit> 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<List<string>>(l => l.Count == 1 && l.Contains("season-gone")),
Arg.Any<CancellationToken>());
}
else
{
await televisionRepository.DidNotReceive().FlagFileNotFoundSeasons(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>());
}
}
// #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<IJellyfinTelevisionRepository>();
var scannerProxy = Substitute.For<IScannerProxy>();
var library = new JellyfinLibrary { Id = 42, Name = "TV Shows" };
var show = new JellyfinShow
{
ItemId = "show-1",
ShowMetadata = new List<ShowMetadata> { new() { Title = "Keeper" } }
};
var season = new JellyfinSeason { ItemId = "season-1", SeasonNumber = 1 };
televisionRepository.GetExistingShows(library, Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag> { new() { ItemId = "show-1", State = MediaItemState.Normal } });
televisionRepository.GetOrAdd(library, Arg.Any<JellyfinShow>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, MediaItemScanResult<JellyfinShow>>(new MediaItemScanResult<JellyfinShow>(show)));
scannerProxy.UpdateProgress(Arg.Any<decimal>(), Arg.Any<CancellationToken>()).Returns(true);
// the season comes back, so the season sweep flags nothing and cannot mask the episode assertion
televisionRepository.GetExistingSeasons(library, Arg.Any<JellyfinShow>(), Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag> { new() { ItemId = "season-1", State = MediaItemState.Normal } });
televisionRepository.GetOrAdd(library, Arg.Any<JellyfinSeason>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, MediaItemScanResult<JellyfinSeason>>(new MediaItemScanResult<JellyfinSeason>(season)));
// two episodes exist, only one comes back — a partial deletion at the episode level
televisionRepository.GetExistingEpisodes(library, Arg.Any<JellyfinSeason>(), Arg.Any<CancellationToken>())
.Returns(new List<JellyfinItemEtag>
{
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<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>())
.Returns(new List<int> { 300 });
televisionRepository.FlagFileNotFoundSeasons(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>())
.Returns(new List<int>());
televisionRepository.FlagFileNotFoundEpisodesForSeasons(
Arg.Any<List<int>>(), Arg.Any<CancellationToken>())
.Returns(new List<int>());
televisionRepository.FlagFileNotFoundShows(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>())
.Returns(new List<int>());
televisionRepository.FlagFileNotFoundSeasonsForShows(
Arg.Any<List<int>>(), Arg.Any<CancellationToken>())
.Returns(new List<int>());
scannerProxy.ReindexMediaItems(Arg.Any<int[]>(), Arg.Any<CancellationToken>()).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<BaseError, Unit> 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<List<string>>(l => l.Count == 1 && l.Contains("ep-gone")),
Arg.Any<CancellationToken>());
}
else
{
await televisionRepository.DidNotReceive().FlagFileNotFoundEpisodes(
Arg.Any<JellyfinLibrary>(), Arg.Any<List<string>>(), Arg.Any<CancellationToken>());
}
// the season counter is a separate instance and stays clean either way
await televisionRepository.DidNotReceive().FlagFileNotFoundSeasons(
Arg.Any<JellyfinLibrary>(),
Arg.Is<List<string>>(l => l.Count > 0),
Arg.Any<CancellationToken>());
}
private static async IAsyncEnumerable<Tuple<JellyfinShow, int>> EmptyShows()
{
await Task.CompletedTask;
@@ -151,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>
@@ -167,24 +434,54 @@ 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<Either<BaseError, Unit>> Scan(
IMediaServerTelevisionRepository<JellyfinLibrary, JellyfinShow, JellyfinSeason, JellyfinEpisode,
JellyfinItemEtag> televisionRepository,
JellyfinConnectionParameters connectionParameters,
JellyfinLibrary library,
IAsyncEnumerable<Tuple<JellyfinShow, int>> showEntries) =>
IAsyncEnumerable<Tuple<JellyfinShow, int>> showEntries,
MediaServerProjectionFailureCounter? projectionFailures = null) =>
ScanLibrary(
televisionRepository,
connectionParameters,
library,
_ => string.Empty,
showEntries,
projectionFailures ?? new MediaServerProjectionFailureCounter(),
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<Either<BaseError, Unit>> ScanFromApi(
IMediaServerTelevisionRepository<JellyfinLibrary, JellyfinShow, JellyfinSeason, JellyfinEpisode,
JellyfinItemEtag> televisionRepository,
JellyfinConnectionParameters connectionParameters,
JellyfinLibrary library) =>
ScanLibrary(
televisionRepository,
connectionParameters,
library,
_ => string.Empty,
false,
CancellationToken.None);
protected override IAsyncEnumerable<Tuple<JellyfinShow, int>> GetShowLibraryItems(
JellyfinConnectionParameters connectionParameters, JellyfinLibrary library) =>
throw new NotSupportedException();
JellyfinConnectionParameters connectionParameters,
JellyfinLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
Enumerate(ShowEntries, ShowProjectionFailures, projectionFailures);
protected override string MediaServerItemId(JellyfinShow show) => show.ItemId;
protected override string MediaServerItemId(JellyfinSeason season) => season.ItemId;
@@ -194,23 +491,46 @@ public class MediaServerTelevisionLibraryScannerTests
protected override string MediaServerEtag(JellyfinEpisode episode) => episode.Etag;
protected override IAsyncEnumerable<Tuple<JellyfinSeason, int>> 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<Tuple<JellyfinEpisode, int>> 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<Tuple<T, int>> Enumerate<T>(
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<T, int>(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<Option<ShowMetadata>> GetFullMetadata(
JellyfinConnectionParameters connectionParameters, JellyfinLibrary library,
MediaItemScanResult<JellyfinShow> result, JellyfinShow incoming, bool deepScan) =>
throw new NotSupportedException();
Task.FromResult(Option<ShowMetadata>.None);
protected override Task<Option<SeasonMetadata>> GetFullMetadata(
JellyfinConnectionParameters connectionParameters, JellyfinLibrary library,
MediaItemScanResult<JellyfinSeason> result, JellyfinSeason incoming, bool deepScan) =>
throw new NotSupportedException();
Task.FromResult(Option<SeasonMetadata>.None);
protected override Task<Option<EpisodeMetadata>> GetFullMetadata(
JellyfinConnectionParameters connectionParameters, JellyfinLibrary library,
@@ -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<Tuple<EmbyMovie, int>> GetMovieLibraryItems(
EmbyConnectionParameters connectionParameters,
EmbyLibrary library) =>
EmbyLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
_embyApiClient.GetMovieLibraryItems(
connectionParameters.Address,
connectionParameters.ApiKey,
library);
library,
projectionFailures);
protected override Task<Option<MovieMetadata>> GetFullMetadata(
EmbyConnectionParameters connectionParameters,
@@ -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<Tuple<EmbyShow, int>> 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;
@@ -147,25 +152,29 @@ public class EmbyTelevisionLibraryScanner : MediaServerTelevisionLibraryScanner<
protected override IAsyncEnumerable<Tuple<EmbySeason, int>> 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<Tuple<EmbyEpisode, int>> 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<Option<ShowMetadata>> GetFullMetadata(
EmbyConnectionParameters connectionParameters,
@@ -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<Tuple<JellyfinMovie, int>> GetMovieLibraryItems(
JellyfinConnectionParameters connectionParameters,
JellyfinLibrary library) =>
JellyfinLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
_jellyfinApiClient.GetMovieLibraryItems(
connectionParameters.Address,
connectionParameters.AuthorizationHeader,
library);
library,
projectionFailures);
protected override Task<Option<MovieMetadata>> GetFullMetadata(
JellyfinConnectionParameters connectionParameters,
@@ -79,11 +79,18 @@ public class JellyfinMusicVideoLibraryScanner : IJellyfinMusicVideoLibraryScanne
var processed = 0;
var incomingPaths = new List<string>();
// #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<string> 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;
}
@@ -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<Tuple<JellyfinShow, int>> 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;
@@ -154,34 +156,40 @@ public class JellyfinTelevisionLibraryScanner : MediaServerTelevisionLibraryScan
protected override IAsyncEnumerable<Tuple<JellyfinSeason, int>> 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<Tuple<JellyfinEpisode, int>> 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<Option<ShowMetadata>> GetFullMetadata(
@@ -52,12 +52,18 @@ public abstract class MediaServerMovieLibraryScanner<TConnectionParameters, TLib
{
try
{
// #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();
return await ScanLibrary(
movieRepository,
connectionParameters,
library,
getLocalPath,
GetMovieLibraryItems(connectionParameters, library),
GetMovieLibraryItems(connectionParameters, library, projectionFailures),
projectionFailures,
deepScan,
cancellationToken);
}
@@ -73,6 +79,7 @@ public abstract class MediaServerMovieLibraryScanner<TConnectionParameters, TLib
TLibrary library,
Func<TMovie, string> getLocalPath,
IAsyncEnumerable<Tuple<TMovie, int>> movieEntries,
MediaServerProjectionFailureCounter projectionFailures,
bool deepScan,
CancellationToken cancellationToken)
{
@@ -204,7 +211,11 @@ public abstract class MediaServerMovieLibraryScanner<TConnectionParameters, TLib
// trash movies that are no longer present on the media server
if (MediaServerReconciliationGuard.ShouldFlagMissing(
_logger, library.Name, incomingItemIds.Count, existingMovies.Count))
_logger,
library.Name,
incomingItemIds.Count,
existingMovies.Count,
projectionFailures.Count))
{
var fileNotFoundItemIds = existingMovies.Keys.Except(incomingItemIds).ToList();
List<int> ids = await movieRepository.FlagFileNotFound(library, fileNotFoundItemIds);
@@ -220,9 +231,13 @@ public abstract class MediaServerMovieLibraryScanner<TConnectionParameters, TLib
protected abstract string MediaServerItemId(TMovie movie);
protected abstract string MediaServerEtag(TMovie movie);
// #484: projectionFailures is the per-enumeration sink the api client reports swallowed projection
// failures into. Implementations that cannot silently drop an item (Plex projects without an
// Option/catch, so a bad item throws and unwinds the scan) simply ignore it.
protected abstract IAsyncEnumerable<Tuple<TMovie, int>> GetMovieLibraryItems(
TConnectionParameters connectionParameters,
TLibrary library);
TLibrary library,
MediaServerProjectionFailureCounter projectionFailures);
protected abstract Task<Option<MovieMetadata>> GetFullMetadata(
TConnectionParameters connectionParameters,
@@ -52,12 +52,17 @@ public abstract class MediaServerOtherVideoLibraryScanner<TConnectionParameters,
{
try
{
// #484: one counter per enumeration — see MediaServerMovieLibraryScanner for why it must
// not be shared or ambient.
var projectionFailures = new MediaServerProjectionFailureCounter();
return await ScanLibrary(
otherVideoRepository,
connectionParameters,
library,
getLocalPath,
GetOtherVideoLibraryItems(connectionParameters, library),
GetOtherVideoLibraryItems(connectionParameters, library, projectionFailures),
projectionFailures,
deepScan,
cancellationToken);
}
@@ -73,6 +78,7 @@ public abstract class MediaServerOtherVideoLibraryScanner<TConnectionParameters,
TLibrary library,
Func<TOtherVideo, string> getLocalPath,
IAsyncEnumerable<Tuple<TOtherVideo, int>> otherVideoEntries,
MediaServerProjectionFailureCounter projectionFailures,
bool deepScan,
CancellationToken cancellationToken)
{
@@ -211,7 +217,11 @@ public abstract class MediaServerOtherVideoLibraryScanner<TConnectionParameters,
// trash OtherVideo that are no longer present on the media server
if (MediaServerReconciliationGuard.ShouldFlagMissing(
_logger, library.Name, incomingItemIds.Count, existingOtherVideos.Count))
_logger,
library.Name,
incomingItemIds.Count,
existingOtherVideos.Count,
projectionFailures.Count))
{
var fileNotFoundItemIds = existingOtherVideos.Keys.Except(incomingItemIds).ToList();
List<int> ids = await otherVideoRepository.FlagFileNotFound(library, fileNotFoundItemIds);
@@ -227,9 +237,11 @@ public abstract class MediaServerOtherVideoLibraryScanner<TConnectionParameters,
protected abstract string MediaServerItemId(TOtherVideo otherVideo);
protected abstract string MediaServerEtag(TOtherVideo otherVideo);
// #484: see MediaServerMovieLibraryScanner.GetMovieLibraryItems for the counter's contract.
protected abstract IAsyncEnumerable<Tuple<TOtherVideo, int>> GetOtherVideoLibraryItems(
TConnectionParameters connectionParameters,
TLibrary library);
TLibrary library,
MediaServerProjectionFailureCounter projectionFailures);
protected abstract Task<Option<OtherVideoMetadata>> GetFullMetadata(
TConnectionParameters connectionParameters,
@@ -14,16 +14,53 @@ 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.
//
// #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
{
public static bool ShouldFlagMissing(
ILogger logger,
string libraryName,
int incomingCount,
int existingCount)
int existingCount,
int projectionFailureCount = 0)
{
if (RefuseForProjectionFailures(
logger,
$"library {libraryName}",
incomingCount,
existingCount,
projectionFailureCount))
{
return false;
}
if (incomingCount == 0 && existingCount > 0)
{
logger.LogWarning(
@@ -37,4 +74,47 @@ internal static class MediaServerReconciliationGuard
return true;
}
/// <summary>
/// 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.
/// </summary>
/// <param name="scope">
/// Names the parent whose descendants are being swept, e.g. <c>show "Sesame Street" seasons</c>.
/// </param>
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;
}
}
@@ -55,12 +55,18 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
{
try
{
// #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();
return await ScanLibrary(
televisionRepository,
connectionParameters,
library,
getLocalPath,
GetShowLibraryItems(connectionParameters, library),
GetShowLibraryItems(connectionParameters, library, projectionFailures),
projectionFailures,
deepScan,
cancellationToken);
}
@@ -70,9 +76,13 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
}
}
// #484: projectionFailures is the per-enumeration sink the api client reports swallowed projection
// failures into. Implementations that cannot silently drop an item (Plex projects without an
// Option/catch, so a bad item throws and unwinds the scan) simply ignore it.
protected abstract IAsyncEnumerable<Tuple<TShow, int>> 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<TConnectionParameters,
TLibrary library,
Func<TEpisode, string> getLocalPath,
IAsyncEnumerable<Tuple<TShow, int>> showEntries,
MediaServerProjectionFailureCounter? projectionFailures,
bool deepScan,
bool cleanupFileNotFoundItems,
CancellationToken cancellationToken)
@@ -130,6 +141,9 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
foreach (MediaItemScanResult<TShow> result in maybeShow.RightToSeq())
{
// #484: one counter per season enumeration, i.e. per show
var seasonProjectionFailures = new MediaServerProjectionFailureCounter();
Either<BaseError, Unit> scanResult = await ScanSeasons(
televisionRepository,
library,
@@ -137,7 +151,12 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
result.Item,
result.IsUpdated,
connectionParameters,
GetSeasonLibraryItems(library, connectionParameters, result.Item),
GetSeasonLibraryItems(
library,
connectionParameters,
result.Item,
seasonProjectionFailures),
seasonProjectionFailures,
deepScan,
cancellationToken);
@@ -172,7 +191,11 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
if (cleanupFileNotFoundItems &&
MediaServerReconciliationGuard.ShouldFlagMissing(
_logger, library.Name, incomingItemIds.Count, existingShows.Count))
_logger,
library.Name,
incomingItemIds.Count,
existingShows.Count,
projectionFailures?.Count ?? 0))
{
// trash shows that are no longer present on the media server
var fileNotFoundItemIds = existingShows.Map(s => s.MediaServerItemId).Except(incomingItemIds).ToList();
@@ -201,6 +224,7 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
TLibrary library,
Func<TEpisode, string> getLocalPath,
IAsyncEnumerable<Tuple<TShow, int>> showEntries,
MediaServerProjectionFailureCounter projectionFailures,
bool deepScan,
CancellationToken cancellationToken) =>
await InternalScanLibrary(
@@ -209,10 +233,13 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
library,
getLocalPath,
showEntries,
projectionFailures,
deepScan,
true,
cancellationToken);
// no sweep runs on this path (cleanupFileNotFoundItems: false), so there is nothing for a
// projection-failure counter to guard — #484.
protected async Task<Either<BaseError, Unit>> ScanLibraryWithoutCleanup(
IMediaServerTelevisionRepository<TLibrary, TShow, TSeason, TEpisode, TEtag> televisionRepository,
TConnectionParameters connectionParameters,
@@ -227,21 +254,27 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
library,
getLocalPath,
showEntries,
null,
deepScan,
false,
cancellationToken);
// #484: see GetShowLibraryItems. These feed the nested per-show / per-season sweeps, which are
// guarded against projection failures (though NOT against a per-parent empty fetch — see
// MediaServerReconciliationGuard.ShouldFlagMissingDescendants).
protected abstract IAsyncEnumerable<Tuple<TSeason, int>> GetSeasonLibraryItems(
TLibrary library,
TConnectionParameters connectionParameters,
TShow show);
TShow show,
MediaServerProjectionFailureCounter projectionFailures);
protected abstract IAsyncEnumerable<Tuple<TEpisode, int>> GetEpisodeLibraryItems(
TLibrary library,
TConnectionParameters connectionParameters,
TShow show,
TSeason season,
bool isNewSeason);
bool isNewSeason,
MediaServerProjectionFailureCounter projectionFailures);
protected abstract Task<Option<ShowMetadata>> GetFullMetadata(
TConnectionParameters connectionParameters,
@@ -289,6 +322,14 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
EpisodeMetadata fullMetadata,
CancellationToken cancellationToken);
// a human-readable name for the guard's warning; falls back to the server item id when a show has no
// metadata (possible for a freshly-added row), so this can never throw inside the sweep.
private string ShowScope(TShow show) =>
Optional(show.ShowMetadata).Flatten().HeadOrNone()
.Map(m => m.Title)
.Filter(t => !string.IsNullOrWhiteSpace(t))
.IfNone(() => MediaServerItemId(show));
private async Task<Either<BaseError, Unit>> ScanSeasons(
IMediaServerTelevisionRepository<TLibrary, TShow, TSeason, TEpisode, TEtag> televisionRepository,
TLibrary library,
@@ -297,6 +338,7 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
bool showIsUpdated,
TConnectionParameters connectionParameters,
IAsyncEnumerable<Tuple<TSeason, int>> seasonEntries,
MediaServerProjectionFailureCounter projectionFailures,
bool deepScan,
CancellationToken cancellationToken)
{
@@ -336,6 +378,9 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
foreach (MediaItemScanResult<TSeason> result in maybeSeason.RightToSeq())
{
// #484: one counter per episode enumeration, i.e. per season
var episodeProjectionFailures = new MediaServerProjectionFailureCounter();
Either<BaseError, Unit> scanResult = await ScanEpisodes(
televisionRepository,
library,
@@ -344,7 +389,14 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
showIsUpdated,
result.Item,
connectionParameters,
GetEpisodeLibraryItems(library, connectionParameters, show, result.Item, result.IsAdded),
GetEpisodeLibraryItems(
library,
connectionParameters,
show,
result.Item,
result.IsAdded,
episodeProjectionFailures),
episodeProjectionFailures,
deepScan,
cancellationToken);
@@ -377,18 +429,29 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
}
}
// trash seasons that are no longer present on the media server
var fileNotFoundItemIds = existingSeasons.Map(s => s.MediaServerItemId).Except(incomingItemIds).ToList();
List<int> 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<int> 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<int> 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<int> 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;
@@ -403,6 +466,7 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
TSeason season,
TConnectionParameters connectionParameters,
IAsyncEnumerable<Tuple<TEpisode, int>> episodeEntries,
MediaServerProjectionFailureCounter projectionFailures,
bool deepScan,
CancellationToken cancellationToken)
{
@@ -550,12 +614,24 @@ public abstract class MediaServerTelevisionLibraryScanner<TConnectionParameters,
}
}
// trash episodes that are no longer present on the media server
var fileNotFoundItemIds = existingEpisodes.Map(m => m.MediaServerItemId).Except(incomingItemIds).ToList();
List<int> 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<int> 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;
@@ -89,9 +89,12 @@ public class PlexMovieLibraryScanner :
protected override string MediaServerEtag(PlexMovie movie) => 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<Tuple<PlexMovie, int>> GetMovieLibraryItems(
PlexConnectionParameters connectionParameters,
PlexLibrary library) =>
PlexLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
_plexServerApiClient.GetMovieLibraryContents(
library,
connectionParameters.Connection,
@@ -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<Tuple<PlexOtherVideo, int>> GetOtherVideoLibraryItems(
PlexConnectionParameters connectionParameters,
PlexLibrary library) =>
PlexLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
_plexServerApiClient.GetOtherVideoLibraryContents(
library,
connectionParameters.Connection,
@@ -1,4 +1,4 @@
using System.IO.Abstractions;
using System.IO.Abstractions;
using System.Text.RegularExpressions;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
@@ -233,18 +233,24 @@ 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<Tuple<PlexShow, int>> GetShowLibraryItems(
PlexConnectionParameters connectionParameters,
PlexLibrary library) =>
PlexLibrary library,
MediaServerProjectionFailureCounter projectionFailures) =>
_plexServerApiClient.GetShowLibraryContents(
library,
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<Tuple<PlexSeason, int>> GetSeasonLibraryItems(
PlexLibrary library,
PlexConnectionParameters connectionParameters,
PlexShow show) =>
PlexShow show,
MediaServerProjectionFailureCounter projectionFailures) =>
_plexServerApiClient.GetShowSeasons(
library,
show,
@@ -256,7 +262,8 @@ public partial class PlexTelevisionLibraryScanner :
PlexConnectionParameters connectionParameters,
PlexShow show,
PlexSeason season,
bool isNewSeason) =>
bool isNewSeason,
MediaServerProjectionFailureCounter projectionFailures) =>
_plexServerApiClient.GetSeasonEpisodes(
library,
season,
@@ -58,7 +58,11 @@ public class JellyfinMusicVideoLibraryScannerTests
MusicVideo incoming = BuildIncoming(VideoPath, artistName: "Artist 1", title: "Song 1");
var apiClient = Substitute.For<IJellyfinApiClient>();
apiClient.GetMusicVideoLibraryItems(Arg.Any<string>(), Arg.Any<string>(), Arg.Any<JellyfinLibrary>())
apiClient.GetMusicVideoLibraryItems(
Arg.Any<string>(),
Arg.Any<string>(),
Arg.Any<JellyfinLibrary>(),
Arg.Any<MediaServerProjectionFailureCounter>())
.Returns(OneItem(incoming));
var pathReplacement = Substitute.For<IJellyfinPathReplacementService>();
@@ -393,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<IArtistRepository>();
artistRepository.GetArtistByMetadata(Arg.Any<int>(), Arg.Any<ArtistMetadata>())
.Returns(Some(new Artist { Id = 3, ArtistMetadata = new List<ArtistMetadata>() }));
artistRepository.DeleteEmptyArtists(Arg.Any<LibraryPath>()).Returns(new List<int>());
var musicVideoRepository = Substitute.For<IMusicVideoRepository>();
musicVideoRepository
.GetOrAdd(Arg.Any<Artist>(), Arg.Any<LibraryPath>(), Arg.Any<LibraryFolder>(), Arg.Any<string>())
.Returns(Right<BaseError, MediaItemScanResult<MusicVideo>>(
new MediaItemScanResult<MusicVideo>(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<LibraryPath>())
.Returns(new List<string> { KeepPath, GonePath }.AsEnumerable());
musicVideoRepository.DeleteByPath(Arg.Any<LibraryPath>(), Arg.Any<string>()).Returns(new List<int> { 7 });
var metadataRepository = Substitute.For<IMetadataRepository>();
metadataRepository.Update(Arg.Any<ErsatzTV.Core.Domain.Metadata>()).Returns(true);
metadataRepository.UpdateStatistics(Arg.Any<MediaItem>(), Arg.Any<MediaVersion>(), Arg.Any<bool>())
.Returns(false);
var libraryRepository = Substitute.For<ILibraryRepository>();
libraryRepository.GetParentFolderId(Arg.Any<LibraryPath>(), Arg.Any<string>(), Arg.Any<CancellationToken>())
.Returns(Option<int>.None);
libraryRepository.GetOrAddFolder(Arg.Any<LibraryPath>(), Arg.Any<Option<int>>(), Arg.Any<string>())
.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<LibraryPath>(), GonePath);
}
else
{
await musicVideoRepository.DidNotReceive().DeleteByPath(Arg.Any<LibraryPath>(), Arg.Any<string>());
}
}
[Test]
public async Task ScanLibrary_Should_Update_Album_And_Track_On_Rescan_Of_Existing_Item()
{
@@ -667,12 +749,54 @@ 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<MusicVideo>[] items)
{
var apiClient = Substitute.For<IJellyfinApiClient>();
apiClient.GetMusicVideoLibraryItems(
Arg.Any<string>(),
Arg.Any<string>(),
Arg.Any<JellyfinLibrary>(),
Arg.Any<MediaServerProjectionFailureCounter>())
.Returns(ci => ItemsWithFailures(
items,
projectionFailureCount,
ci.ArgAt<MediaServerProjectionFailureCounter>(3)));
return apiClient;
}
private static async IAsyncEnumerable<Tuple<MusicVideo, int>> ItemsWithFailures(
Func<MusicVideo>[] items,
int projectionFailureCount,
MediaServerProjectionFailureCounter projectionFailures)
{
for (var i = 0; i < projectionFailureCount; i++)
{
projectionFailures.RecordFailure();
}
foreach (Func<MusicVideo> item in items)
{
yield return new Tuple<MusicVideo, int>(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<MusicVideo>[] items)
{
var apiClient = Substitute.For<IJellyfinApiClient>();
apiClient.GetMusicVideoLibraryItems(Arg.Any<string>(), Arg.Any<string>(), Arg.Any<JellyfinLibrary>())
apiClient.GetMusicVideoLibraryItems(
Arg.Any<string>(),
Arg.Any<string>(),
Arg.Any<JellyfinLibrary>(),
Arg.Any<MediaServerProjectionFailureCounter>())
.Returns(_ => Items(items));
return apiClient;
}
+118
View File
@@ -3777,3 +3777,121 @@ 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` 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
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<Tuple<TItem, int>>` 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<TItem>` to `MediaServerProjectionResult<TItem>` (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`) **and** the nested season/episode ones (`GetSeasonLibraryItems`,
`GetEpisodeLibraryItems`, `GetEpisodeLibraryItemsWithoutPeople`), so every other call site is untouched.
A library that cannot be resolved (`Option<TLibrary>.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 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
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. 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.
+1
View File
@@ -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` 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) |