Merge remote-tracking branch 'origin/main' into feat/253-pr3-diff-scalar
Build ErsatzTV Image / Docs update reminder (pull_request) Successful in 5s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m21s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 10m12s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Has been skipped
Build ErsatzTV Image / Docs update reminder (push) Has been skipped
Build ErsatzTV Image / Build & push image (amd64) (push) Has been cancelled
Build ErsatzTV Image / Build & test (.NET) (push) Has been cancelled
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (push) Has been cancelled

# Conflicts:
#	docs/decisions.md
This commit was merged in pull request #270.
This commit is contained in:
2026-07-11 20:45:22 +02:00
103 changed files with 4634 additions and 314 deletions
@@ -2,6 +2,6 @@ using ErsatzTV.Core;
namespace ErsatzTV.Application.Emby;
public record SynchronizeEmbyCollections(int EmbyMediaSourceId, bool ForceScan, bool DeepScan)
public record SynchronizeEmbyCollections(int EmbyMediaSourceId, bool ForceScan, bool DeepScan, bool Unlock = true)
: IRequest<Either<BaseError, Unit>>,
IScannerBackgroundServiceRequest;
@@ -2,6 +2,6 @@ using ErsatzTV.Core;
namespace ErsatzTV.Application.Jellyfin;
public record SynchronizeJellyfinCollections(int JellyfinMediaSourceId, bool ForceScan, bool DeepScan) :
public record SynchronizeJellyfinCollections(int JellyfinMediaSourceId, bool ForceScan, bool DeepScan, bool Unlock = true) :
IRequest<Either<BaseError, Unit>>,
IScannerBackgroundServiceRequest;
@@ -8,4 +8,4 @@ public enum QueueLibraryScanResult
AlreadyScanning
}
public record QueueLibraryScanByLibraryId(int LibraryId) : IRequest<QueueLibraryScanResult>;
public record QueueLibraryScanByLibraryId(int LibraryId, bool DeepScan = false) : IRequest<QueueLibraryScanResult>;
@@ -66,7 +66,7 @@ public class QueueLibraryScanByLibraryIdHandler(
new SynchronizePlexLibraries(library.MediaSourceId),
cancellationToken);
await scannerWorker.WriteAsync(
new ForceSynchronizePlexLibraryById(library.Id, false),
new ForceSynchronizePlexLibraryById(library.Id, request.DeepScan),
cancellationToken);
break;
case JellyfinLibrary:
@@ -74,7 +74,7 @@ public class QueueLibraryScanByLibraryIdHandler(
new SynchronizeJellyfinLibraries(library.MediaSourceId),
cancellationToken);
await scannerWorker.WriteAsync(
new ForceSynchronizeJellyfinLibraryById(library.Id, false),
new ForceSynchronizeJellyfinLibraryById(library.Id, request.DeepScan),
cancellationToken);
break;
case EmbyLibrary:
@@ -82,7 +82,7 @@ public class QueueLibraryScanByLibraryIdHandler(
new SynchronizeEmbyLibraries(library.MediaSourceId),
cancellationToken);
await scannerWorker.WriteAsync(
new ForceSynchronizeEmbyLibraryById(library.Id, false),
new ForceSynchronizeEmbyLibraryById(library.Id, request.DeepScan),
cancellationToken);
break;
}
@@ -1,3 +1,14 @@
namespace ErsatzTV.Application.Libraries;
public record QueueShowScanByLibraryId(int LibraryId, int ShowId, string ShowTitle, bool DeepScan) : IRequest<bool>;
public enum QueueShowScanResult
{
Queued,
NotFound,
Unsupported,
SyncDisabled,
AlreadyScanning,
ScanFailed
}
public record QueueShowScanByLibraryId(int LibraryId, int ShowId, string ShowTitle, bool DeepScan)
: IRequest<QueueShowScanResult>;
@@ -19,9 +19,9 @@ public class QueueShowScanByLibraryIdHandler(
IMediator mediator,
ChannelWriter<IBackgroundServiceRequest> workerChannel,
ILogger<QueueShowScanByLibraryIdHandler> logger)
: IRequestHandler<QueueShowScanByLibraryId, bool>
: IRequestHandler<QueueShowScanByLibraryId, QueueShowScanResult>
{
public async Task<bool> Handle(QueueShowScanByLibraryId request, CancellationToken cancellationToken)
public async Task<QueueShowScanResult> Handle(QueueShowScanByLibraryId request, CancellationToken cancellationToken)
{
await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
@@ -42,14 +42,14 @@ public class QueueShowScanByLibraryIdHandler(
if (!shouldSyncItems)
{
logger.LogWarning("Library sync is disabled for library id {Id}", library.Id);
return false;
return QueueShowScanResult.SyncDisabled;
}
// Check if library is already being scanned - return false if locked
// A false from LockLibrary means a scan is already in progress; we own no release.
if (!locker.LockLibrary(library.Id))
{
logger.LogWarning("Library {Id} is already being scanned, cannot scan individual show", library.Id);
return false;
return QueueShowScanResult.AlreadyScanning;
}
logger.LogDebug(
@@ -60,41 +60,43 @@ public class QueueShowScanByLibraryIdHandler(
try
{
var success = false;
QueueShowScanResult outcome;
switch (library)
{
case PlexLibrary:
Either<BaseError, string> plexResult = await mediator.Send(
new SynchronizePlexShowById(library.Id, request.ShowId, request.DeepScan),
cancellationToken);
success = plexResult.IsRight;
outcome = plexResult.IsRight ? QueueShowScanResult.Queued : QueueShowScanResult.ScanFailed;
break;
case JellyfinLibrary:
Either<BaseError, string> jellyfinResult = await mediator.Send(
new SynchronizeJellyfinShowById(library.Id, request.ShowId, request.DeepScan),
cancellationToken);
success = jellyfinResult.IsRight;
outcome = jellyfinResult.IsRight ? QueueShowScanResult.Queued : QueueShowScanResult.ScanFailed;
break;
case EmbyLibrary:
Either<BaseError, string> embyResult = await mediator.Send(
new SynchronizeEmbyShowById(library.Id, request.ShowId, request.DeepScan),
cancellationToken);
success = embyResult.IsRight;
outcome = embyResult.IsRight ? QueueShowScanResult.Queued : QueueShowScanResult.ScanFailed;
break;
case LocalLibrary:
logger.LogWarning("Single show scanning is not supported for local libraries");
outcome = QueueShowScanResult.Unsupported;
break;
default:
logger.LogWarning("Unknown library type for library {Id}", library.Id);
outcome = QueueShowScanResult.Unsupported;
break;
}
if (success && request.DeepScan)
if (outcome == QueueShowScanResult.Queued && request.DeepScan)
{
await workerChannel.WriteAsync(new ExtractEmbeddedShowSubtitles(request.ShowId), cancellationToken);
}
return success;
return outcome;
}
finally
{
@@ -103,6 +105,6 @@ public class QueueShowScanByLibraryIdHandler(
}
}
return false;
return QueueShowScanResult.NotFound;
}
}
@@ -32,6 +32,10 @@ public class AddEpisodeToPlaylistHandler(IDbContextFactory<TvContext> dbContextF
};
parameters.Playlist.Items.Add(playlistItem);
// Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
parameters.Playlist.Version++;
await dbContext.SaveChangesAsync();
return Unit.Default;
}
@@ -69,6 +69,9 @@ public class AddItemsToPlaylistHandler : IRequestHandler<AddItemsToPlaylist, Eit
}
}
// Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
playlist.Version++;
await dbContext.SaveChangesAsync(cancellationToken);
return Unit.Default;
@@ -32,6 +32,10 @@ public class AddMovieToPlaylistHandler(IDbContextFactory<TvContext> dbContextFac
};
parameters.Playlist.Items.Add(playlistItem);
// Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
parameters.Playlist.Version++;
await dbContext.SaveChangesAsync();
return Unit.Default;
}
@@ -32,6 +32,10 @@ public class AddSeasonToPlaylistHandler(IDbContextFactory<TvContext> dbContextFa
};
parameters.Playlist.Items.Add(playlistItem);
// Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
parameters.Playlist.Version++;
await dbContext.SaveChangesAsync();
return Unit.Default;
}
@@ -32,6 +32,10 @@ public class AddShowToPlaylistHandler(IDbContextFactory<TvContext> dbContextFact
};
parameters.Playlist.Items.Add(playlistItem);
// Mutates the playlist's editor-visible item list, so bump the concurrency token (issue #253).
parameters.Playlist.Version++;
await dbContext.SaveChangesAsync();
return Unit.Default;
}
@@ -2,5 +2,9 @@ using ErsatzTV.Core;
namespace ErsatzTV.Application.MediaCollections;
public record ReplacePlaylistItems(int PlaylistId, string Name, List<ReplacePlaylistItem> Items)
public record ReplacePlaylistItems(
int PlaylistId,
string Name,
List<ReplacePlaylistItem> Items,
Option<int> ExpectedVersion = default)
: IRequest<Either<BaseError, List<PlaylistItemViewModel>>>;
@@ -15,10 +15,21 @@ public class ReplacePlaylistItemsHandler(IDbContextFactory<TvContext> dbContextF
{
await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
Validation<BaseError, Playlist> validation = await Validate(dbContext, request, cancellationToken);
return await validation.Apply(ps => Persist(dbContext, request, ps, cancellationToken));
// Introduce the optimistic-concurrency check as a standalone Either AFTER the validation
// pipeline (never via Apply) so a PreconditionFailedError survives to a 412 and is not
// flattened to a generic 422 by Join() (issue #253 / api-conventions §7a).
// LanguageExtensions.ToEither joins the Seq<BaseError> to a single BaseError (the native
// Validation.ToEither() would keep Seq and is called explicitly here to avoid that shadow).
Either<BaseError, Playlist> validated = LanguageExtensions.ToEither(validation)
.Bind(playlist => playlist.CheckVersion(request.ExpectedVersion));
return await validated.Match(
Right: playlist => Persist(dbContext, request, playlist, cancellationToken),
Left: error => Task.FromResult<Either<BaseError, List<PlaylistItemViewModel>>>(error));
}
private static async Task<List<PlaylistItemViewModel>> Persist(
private static async Task<Either<BaseError, List<PlaylistItemViewModel>>> Persist(
TvContext dbContext,
ReplacePlaylistItems request,
Playlist playlist,
@@ -30,9 +41,15 @@ public class ReplacePlaylistItemsHandler(IDbContextFactory<TvContext> dbContextF
dbContext.RemoveRange(playlist.Items);
playlist.Items = request.Items.Map(i => BuildItem(playlist, i.Index, i)).ToList();
await dbContext.SaveChangesAsync(cancellationToken);
// Unconditional bump: EF emits the root UPDATE only when a scalar actually differs, so a
// same-value/no-op save would otherwise write no root row and neither fire the concurrency
// token nor rotate other clients' ETags. Bumping guarantees both on every save (issue #253).
playlist.Version++;
return playlist.Items.Map(Mapper.ProjectToViewModel).ToList();
// Save through the guard so an EF concurrency failure (a racing writer won between our load
// and save) maps to 412 rather than surfacing as a 500.
Either<BaseError, Unit> saved = await dbContext.SaveChangesWithConcurrencyGuard(cancellationToken);
return saved.Map(_ => playlist.Items.Map(Mapper.ProjectToViewModel).ToList());
}
private static PlaylistItem BuildItem(Playlist playlist, int index, ReplacePlaylistItem item) =>
@@ -92,7 +92,7 @@ internal static class Mapper
new(playlistGroup.Id, playlistGroup.Name, playlistGroup.Playlists.Count, playlistGroup.IsSystem);
internal static PlaylistViewModel ProjectToViewModel(Playlist playlist) =>
new(playlist.Id, playlist.PlaylistGroupId, playlist.Name, playlist.IsSystem);
new(playlist.Id, playlist.PlaylistGroupId, playlist.Name, playlist.IsSystem, playlist.Version);
internal static PlaylistItemViewModel ProjectToViewModel(PlaylistItem playlistItem) =>
new(
@@ -1,3 +1,3 @@
namespace ErsatzTV.Application.MediaCollections;
public record PlaylistViewModel(int Id, int PlaylistGroupId, string Name, bool IsSystem);
public record PlaylistViewModel(int Id, int PlaylistGroupId, string Name, bool IsSystem, int Version);
@@ -1,3 +1,3 @@
namespace ErsatzTV.Application.Playouts;
public record ResetAllPlayouts : IRequest;
public record ResetAllPlayouts : IRequest<ResetAllPlayoutsResult>;
@@ -11,33 +11,49 @@ public class ResetAllPlayoutsHandler(
IEntityLocker locker,
ChannelWriter<IBackgroundServiceRequest> channel,
IDbContextFactory<TvContext> dbContextFactory)
: IRequestHandler<ResetAllPlayouts>
: IRequestHandler<ResetAllPlayouts, ResetAllPlayoutsResult>
{
public async Task Handle(ResetAllPlayouts request, CancellationToken cancellationToken)
public async Task<ResetAllPlayoutsResult> Handle(
ResetAllPlayouts request,
CancellationToken cancellationToken)
{
await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
var queued = new List<int>();
var skippedLocked = new List<int>();
var skippedUnsupported = new List<int>();
foreach (Playout playout in await dbContext.Playouts.ToListAsync(cancellationToken))
{
switch (playout.ScheduleKind)
{
case PlayoutScheduleKind.Classic:
if (!locker.IsPlayoutLocked(playout.Id))
if (locker.IsPlayoutLocked(playout.Id))
{
skippedLocked.Add(playout.Id);
}
else
{
await channel.WriteAsync(
new BuildPlayout(playout.Id, PlayoutBuildMode.Refresh),
cancellationToken);
queued.Add(playout.Id);
}
break;
case PlayoutScheduleKind.Block:
case PlayoutScheduleKind.Sequential:
case PlayoutScheduleKind.Scripted:
if (!locker.IsPlayoutLocked(playout.Id))
if (locker.IsPlayoutLocked(playout.Id))
{
skippedLocked.Add(playout.Id);
}
else
{
await channel.WriteAsync(
new BuildPlayout(playout.Id, PlayoutBuildMode.Reset),
cancellationToken);
queued.Add(playout.Id);
}
break;
@@ -45,8 +61,11 @@ public class ResetAllPlayoutsHandler(
case PlayoutScheduleKind.None:
default:
// external json cannot be reset
skippedUnsupported.Add(playout.Id);
continue;
}
}
return new ResetAllPlayoutsResult(queued, skippedLocked, skippedUnsupported);
}
}
@@ -0,0 +1,6 @@
namespace ErsatzTV.Application.Playouts;
public record ResetAllPlayoutsResult(
List<int> QueuedPlayoutIds,
List<int> SkippedLocked,
List<int> SkippedUnsupported);
@@ -2,5 +2,5 @@ using ErsatzTV.Core;
namespace ErsatzTV.Application.Plex;
public record SynchronizePlexCollections(int PlexMediaSourceId, bool ForceScan, bool DeepScan)
public record SynchronizePlexCollections(int PlexMediaSourceId, bool ForceScan, bool DeepScan, bool Unlock = true)
: IRequest<Either<BaseError, Unit>>, IScannerBackgroundServiceRequest;
@@ -52,6 +52,9 @@ public class AddProgramScheduleItemHandler : ProgramScheduleItemCommandBase,
ProgramScheduleItem item = BuildItem(programSchedule, nextIndex, request);
programSchedule.Items.Add(item);
// bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253)
programSchedule.Version++;
await dbContext.SaveChangesAsync(cancellationToken);
// refresh any playouts that use this schedule
@@ -34,6 +34,10 @@ public class DeleteProgramScheduleItemHandler(
List<Playout> playouts = item.ProgramSchedule.Playouts;
dbContext.ProgramScheduleItems.Remove(item);
// bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253)
item.ProgramSchedule.Version++;
await dbContext.SaveChangesAsync(cancellationToken);
// post-commit side effect runs on CancellationToken.None so a late request cancellation
@@ -44,5 +44,8 @@ public record ReplaceProgramScheduleItem(
string PreferredSubtitleLanguageCode,
ChannelSubtitleMode? SubtitleMode) : IProgramScheduleItemRequest;
public record ReplaceProgramScheduleItems(int ProgramScheduleId, List<ReplaceProgramScheduleItem> Items) : IRequest<
public record ReplaceProgramScheduleItems(
int ProgramScheduleId,
List<ReplaceProgramScheduleItem> Items,
Option<int> ExpectedVersion = default) : IRequest<
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>>>;
@@ -26,13 +26,23 @@ public class ReplaceProgramScheduleItemsHandler(
Some: async programSchedule =>
{
Validation<BaseError, ProgramSchedule> validation = await Validate(dbContext, request, programSchedule);
return await validation.Apply(ps => PersistItems(dbContext, request, ps, cancellationToken));
// Introduce the optimistic-concurrency check as a standalone Either AFTER the validation
// pipeline (never via Apply) so a PreconditionFailedError survives to a 412 and is not
// flattened to a generic 422 by Join() (issue #253 / api-conventions §7a).
Either<BaseError, ProgramSchedule> validated = LanguageExtensions.ToEither(validation)
.Bind(ps => ps.CheckVersion(request.ExpectedVersion));
return await validated.Match(
Right: ps => PersistItems(dbContext, request, ps, cancellationToken),
Left: error =>
Task.FromResult<Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>>>(error));
},
None: () => Task.FromResult<Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>>>(
new NotFoundError("[ProgramScheduleId] does not exist.")));
}
private async Task<IEnumerable<ProgramScheduleItemViewModel>> PersistItems(
private async Task<Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>>> PersistItems(
TvContext dbContext,
ReplaceProgramScheduleItems request,
ProgramSchedule programSchedule,
@@ -92,7 +102,20 @@ public class ReplaceProgramScheduleItemsHandler(
programSchedule.Items.Add(BuildItem(programSchedule, i, orderedItems[i]));
}
await dbContext.SaveChangesAsync(cancellationToken);
// Unconditional bump: this handler frequently saves with only CHILD changes and no root-scalar
// change, so without an explicit bump EF would emit no root UPDATE and the concurrency token
// would never fire (nor rotate other clients' ETags). Bumping guarantees both on every save,
// including a no-op same-items PUT-back (issue #253 / api-conventions §7a).
programSchedule.Version++;
// Save through the guard so an EF concurrency failure (a racing writer won between our load and
// save) maps to 412 rather than surfacing as a 500. On failure, propagate the error WITHOUT
// running the post-save reload/enqueue below.
Either<BaseError, Unit> saved = await dbContext.SaveChangesWithConcurrencyGuard(cancellationToken);
if (saved.IsLeft)
{
return saved.Map(_ => (IEnumerable<ProgramScheduleItemViewModel>)[]);
}
// refresh any playouts that use this schedule
// post-commit side effect runs on CancellationToken.None so a late request cancellation
@@ -54,6 +54,9 @@ public class UpdateProgramScheduleHandler(
programSchedule.RandomStartPoint = request.RandomStartPoint;
programSchedule.FixedStartTimeBehavior = request.FixedStartTimeBehavior;
// bump the optimistic-concurrency token so this config edit rotates other clients' ETags (#253)
programSchedule.Version++;
await dbContext.SaveChangesAsync();
if (needToRefreshPlayout)
@@ -12,7 +12,8 @@ internal static class Mapper
programSchedule.TreatCollectionsAsShows,
programSchedule.ShuffleScheduleItems,
programSchedule.RandomStartPoint,
programSchedule.FixedStartTimeBehavior);
programSchedule.FixedStartTimeBehavior,
programSchedule.Version);
internal static ProgramScheduleItemViewModel ProjectToViewModel(ProgramScheduleItem programScheduleItem) =>
programScheduleItem switch
@@ -9,4 +9,5 @@ public record ProgramScheduleViewModel(
bool TreatCollectionsAsShows,
bool ShuffleScheduleItems,
bool RandomStartPoint,
FixedStartTimeBehavior FixedStartTimeBehavior);
FixedStartTimeBehavior FixedStartTimeBehavior,
int Version);
@@ -19,7 +19,8 @@ public class GetAllProgramSchedulesHandler(IDbContextFactory<TvContext> dbContex
ps.TreatCollectionsAsShows,
ps.ShuffleScheduleItems,
ps.RandomStartPoint,
ps.FixedStartTimeBehavior))
ps.FixedStartTimeBehavior,
ps.Version))
.ToListAsync(cancellationToken);
}
}
@@ -6,5 +6,6 @@ public record ReplaceDecoTemplateItems(
int DecoTemplateId,
int DecoTemplateGroupId,
string Name,
List<ReplaceDecoTemplateItem> Items)
List<ReplaceDecoTemplateItem> Items,
Option<int> ExpectedVersion = default)
: IRequest<Either<BaseError, List<DecoTemplateItemViewModel>>>;
@@ -20,10 +20,19 @@ public class ReplaceDecoTemplateItemsHandler(
{
await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
Validation<BaseError, DecoTemplate> validation = await Validate(dbContext, request, cancellationToken);
return await validation.Apply(ps => Persist(dbContext, request, ps, cancellationToken));
// Introduce the optimistic-concurrency check as a standalone Either AFTER the validation
// pipeline (never via Apply) so a PreconditionFailedError survives to a 412 and is not
// flattened to a generic 422 by Join() (issue #253 / api-conventions §7a).
Either<BaseError, DecoTemplate> validated = LanguageExtensions.ToEither(validation)
.Bind(decoTemplate => decoTemplate.CheckVersion(request.ExpectedVersion));
return await validated.Match(
Right: decoTemplate => Persist(dbContext, request, decoTemplate, cancellationToken),
Left: error => Task.FromResult<Either<BaseError, List<DecoTemplateItemViewModel>>>(error));
}
private async Task<List<DecoTemplateItemViewModel>> Persist(
private async Task<Either<BaseError, List<DecoTemplateItemViewModel>>> Persist(
TvContext dbContext,
ReplaceDecoTemplateItems request,
DecoTemplate decoTemplate,
@@ -36,33 +45,49 @@ public class ReplaceDecoTemplateItemsHandler(
decoTemplate.Items = request.Items.Map(i => BuildItem(decoTemplate, i)).ToList();
await dbContext.SaveChangesAsync(cancellationToken);
// Unconditional bump: EF emits the root UPDATE only when a scalar actually differs, so a
// same-value/no-op save would otherwise write no root row and neither fire the concurrency
// token nor rotate other clients' ETags. Bumping guarantees both on every save (issue #253).
decoTemplate.Version++;
// Deco/break/default-filler content is only (re)applied during a Reset build (a Continue keeps the
// frozen DecoDefault filler items), and BlockKey change-detection has no deco dimension, so nothing
// self-heals a deco-template edit — the editor returned 200 but built filler stayed stale until a
// manual Reset (#251). Enqueue a Reset for every playout that references this deco template. This
// whole post-commit invalidation runs with CancellationToken.None (audit #22 policy): once the edit
// is committed, a late request cancellation must not be able to abort the affected-playout query OR
// the enqueue and leave content stale.
List<int> playoutIds = await dbContext.PlayoutTemplates
.Where(pt => pt.DecoTemplateId == decoTemplate.Id)
.Select(pt => pt.PlayoutId)
.Distinct()
.ToListAsync(CancellationToken.None);
// Save through the guard so an EF concurrency failure (a racing writer won between our load
// and save) maps to 412 rather than surfacing as a 500.
Either<BaseError, Unit> saved = await dbContext.SaveChangesWithConcurrencyGuard(cancellationToken);
return await saved.Match(
Right: async _ =>
{
// Deco/break/default-filler content is only (re)applied during a Reset build (a Continue keeps
// the frozen DecoDefault filler items), and BlockKey change-detection has no deco dimension, so
// nothing self-heals a deco-template edit — the editor returned 200 but built filler stayed
// stale until a manual Reset (#251). Enqueue a Reset for every playout that references this
// deco template. This whole post-commit invalidation runs with CancellationToken.None (audit
// #22 policy): once the edit is committed, a late request cancellation must not be able to
// abort the affected-playout query OR the enqueue and leave content stale. Only runs after a
// successful save (issue #253) — a 412/422 must not enqueue a Reset for content that was never
// persisted.
List<int> playoutIds = await dbContext.PlayoutTemplates
.Where(pt => pt.DecoTemplateId == decoTemplate.Id)
.Select(pt => pt.PlayoutId)
.Distinct()
.ToListAsync(CancellationToken.None);
foreach (int playoutId in playoutIds)
{
await channel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Reset), CancellationToken.None);
}
foreach (int playoutId in playoutIds)
{
await channel.WriteAsync(
new BuildPlayout(playoutId, PlayoutBuildMode.Reset),
CancellationToken.None);
}
await dbContext.Entry(decoTemplate)
.Collection(t => t.Items)
.Query()
.Include(i => i.Deco)
.LoadAsync(cancellationToken);
await dbContext.Entry(decoTemplate)
.Collection(t => t.Items)
.Query()
.Include(i => i.Deco)
.LoadAsync(cancellationToken);
return decoTemplate.Items.Map(Mapper.ProjectToViewModel).ToList();
return Right<BaseError, List<DecoTemplateItemViewModel>>(
decoTemplate.Items.Map(Mapper.ProjectToViewModel).ToList());
},
Left: error => Task.FromResult(Left<BaseError, List<DecoTemplateItemViewModel>>(error)));
}
private static DecoTemplateItem BuildItem(DecoTemplate decoTemplate, ReplaceDecoTemplateItem item) =>
@@ -2,5 +2,10 @@ using ErsatzTV.Core;
namespace ErsatzTV.Application.Scheduling;
public record ReplaceTemplateItems(int TemplateGroupId, int TemplateId, string Name, List<ReplaceTemplateItem> Items)
public record ReplaceTemplateItems(
int TemplateGroupId,
int TemplateId,
string Name,
List<ReplaceTemplateItem> Items,
Option<int> ExpectedVersion = default)
: IRequest<Either<BaseError, List<TemplateItemViewModel>>>;
@@ -15,10 +15,19 @@ public class ReplaceTemplateItemsHandler(IDbContextFactory<TvContext> dbContextF
{
await using TvContext dbContext = await dbContextFactory.CreateDbContextAsync(cancellationToken);
Validation<BaseError, Template> validation = await Validate(dbContext, request, cancellationToken);
return await validation.Apply(ps => Persist(dbContext, request, ps, cancellationToken));
// Introduce the optimistic-concurrency check as a standalone Either AFTER the validation
// pipeline (never via Apply) so a PreconditionFailedError survives to a 412 and is not
// flattened to a generic 422 by Join() (issue #253 / api-conventions §7a).
Either<BaseError, Template> validated = LanguageExtensions.ToEither(validation)
.Bind(template => template.CheckVersion(request.ExpectedVersion));
return await validated.Match(
Right: template => Persist(dbContext, request, template, cancellationToken),
Left: error => Task.FromResult<Either<BaseError, List<TemplateItemViewModel>>>(error));
}
private static async Task<List<TemplateItemViewModel>> Persist(
private static async Task<Either<BaseError, List<TemplateItemViewModel>>> Persist(
TvContext dbContext,
ReplaceTemplateItems request,
Template template,
@@ -30,7 +39,10 @@ public class ReplaceTemplateItemsHandler(IDbContextFactory<TvContext> dbContextF
dbContext.RemoveRange(template.Items);
template.Items = request.Items.Map(i => BuildItem(template, i)).ToList();
await dbContext.SaveChangesAsync(cancellationToken);
// Unconditional bump: EF emits the root UPDATE only when a scalar actually differs, so a
// same-value/no-op save would otherwise write no root row and neither fire the concurrency
// token nor rotate other clients' ETags. Bumping guarantees both on every save (issue #253).
template.Version++;
// TODO: refresh any playouts that use this schedule
// foreach (Playout playout in programSchedule.Playouts)
@@ -38,13 +50,22 @@ public class ReplaceTemplateItemsHandler(IDbContextFactory<TvContext> dbContextF
// await _channel.WriteAsync(new BuildPlayout(playout.Id, PlayoutBuildMode.Refresh));
// }
await dbContext.Entry(template)
.Collection(t => t.Items)
.Query()
.Include(i => i.Block)
.LoadAsync(cancellationToken);
// Save through the guard so an EF concurrency failure (a racing writer won between our load
// and save) maps to 412 rather than surfacing as a 500.
Either<BaseError, Unit> saved = await dbContext.SaveChangesWithConcurrencyGuard(cancellationToken);
return await saved.Match(
Right: async _ =>
{
await dbContext.Entry(template)
.Collection(t => t.Items)
.Query()
.Include(i => i.Block)
.LoadAsync(cancellationToken);
return template.Items.Map(Mapper.ProjectToViewModel).ToList();
return Right<BaseError, List<TemplateItemViewModel>>(
template.Items.Map(Mapper.ProjectToViewModel).ToList());
},
Left: error => Task.FromResult(Left<BaseError, List<TemplateItemViewModel>>(error)));
}
private static TemplateItem BuildItem(Template template, ReplaceTemplateItem item) =>
@@ -1,3 +1,3 @@
namespace ErsatzTV.Application.Scheduling;
public record DecoTemplateViewModel(int Id, int DecoTemplateGroupId, string GroupName, string Name);
public record DecoTemplateViewModel(int Id, int DecoTemplateGroupId, string GroupName, string Name, int Version);
+3 -2
View File
@@ -65,7 +65,7 @@ internal static class Mapper
new(templateGroup.Id, templateGroup.Name, templateGroup.Templates.Count);
internal static TemplateViewModel ProjectToViewModel(Template template) =>
new(template.Id, template.TemplateGroupId, template.TemplateGroup.Name, template.Name);
new(template.Id, template.TemplateGroupId, template.TemplateGroup.Name, template.Name, template.Version);
internal static TemplateItemViewModel ProjectToViewModel(TemplateItem templateItem)
{
@@ -168,7 +168,8 @@ internal static class Mapper
decoTemplate.Id,
decoTemplate.DecoTemplateGroupId,
decoTemplate.DecoTemplateGroup.Name,
decoTemplate.Name);
decoTemplate.Name,
decoTemplate.Version);
}
internal static DecoTemplateItemViewModel ProjectToViewModel(DecoTemplateItem decoTemplateItem)
@@ -1,3 +1,3 @@
namespace ErsatzTV.Application.Scheduling;
public record TemplateViewModel(int Id, int TemplateGroupId, string GroupName, string Name);
public record TemplateViewModel(int Id, int TemplateGroupId, string GroupName, string Name, int Version);
@@ -14,7 +14,8 @@ public record PlayoutResponseModel(
TimeSpan? DailyRebuildTime,
PlayoutBuildStatusResponseModel? BuildStatus,
int? DecoId,
string? DecoName)
string? DecoName,
bool IsLocked)
{
public static PlayoutResponseModel From(
int id,
@@ -27,7 +28,8 @@ public record PlayoutResponseModel(
TimeSpan? dailyRebuildTime,
PlayoutBuildStatusResponseModel? buildStatus,
int? decoId,
string? decoName) =>
string? decoName,
bool isLocked) =>
new(
id,
scheduleKind,
@@ -39,5 +41,6 @@ public record PlayoutResponseModel(
dailyRebuildTime,
buildStatus,
decoId,
decoName);
decoName,
isLocked);
}
@@ -0,0 +1,7 @@
#nullable enable
namespace ErsatzTV.Core.Api.Playouts;
public record ResetAllPlayoutsResponseModel(
List<int> QueuedPlayoutIds,
List<int> SkippedLocked,
List<int> SkippedUnsupported);
@@ -164,6 +164,30 @@ public class QueueLibraryScanByLibraryIdHandlerTests
locker.Received(1).UnlockLibrary(libraryId);
}
[Test]
public async Task Handle_Should_Thread_DeepScan_Into_Plex_ForceSynchronize()
{
int libraryId = await SeedSyncEnabledPlexLibrary();
var locker = Substitute.For<IEntityLocker>();
locker.LockLibrary(libraryId).Returns(true);
Channel<IScannerBackgroundServiceRequest> channel = ThreadingChannel.CreateUnbounded<IScannerBackgroundServiceRequest>();
QueueLibraryScanByLibraryIdHandler handler = CreateHandler(locker, channel.Writer);
QueueLibraryScanResult result = await handler.Handle(
new QueueLibraryScanByLibraryId(libraryId, DeepScan: true),
CancellationToken.None);
result.ShouldBe(QueueLibraryScanResult.Queued);
// first message refreshes the library list, second is the deep force-sync carrying DeepScan == true
channel.Reader.TryRead(out IScannerBackgroundServiceRequest? first).ShouldBeTrue();
first.ShouldBeOfType<ErsatzTV.Application.Plex.SynchronizePlexLibraries>();
channel.Reader.TryRead(out IScannerBackgroundServiceRequest? second).ShouldBeTrue();
second.ShouldBeOfType<ErsatzTV.Application.Plex.ForceSynchronizePlexLibraryById>().DeepScan.ShouldBeTrue();
}
private QueueLibraryScanByLibraryIdHandler CreateHandler(
IEntityLocker locker,
ChannelWriter<IScannerBackgroundServiceRequest> writer) =>
@@ -193,7 +217,11 @@ public class QueueLibraryScanByLibraryIdHandlerTests
return source.Libraries[0].Id;
}
private async Task<int> SeedSyncDisabledPlexLibrary()
private async Task<int> SeedSyncDisabledPlexLibrary() => await SeedPlexLibrary(shouldSyncItems: false);
private async Task<int> SeedSyncEnabledPlexLibrary() => await SeedPlexLibrary(shouldSyncItems: true);
private async Task<int> SeedPlexLibrary(bool shouldSyncItems)
{
await using TvContext context = _db.CreateContext();
var source = new PlexMediaSource
@@ -212,7 +240,7 @@ public class QueueLibraryScanByLibraryIdHandlerTests
Name = "Plex Movies",
MediaKind = LibraryMediaKind.Movies,
Key = "1",
ShouldSyncItems = false,
ShouldSyncItems = shouldSyncItems,
Paths = []
}
]
@@ -0,0 +1,214 @@
using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.Libraries;
using ErsatzTV.Application.Plex;
using ErsatzTV.Application.Subtitles;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Interfaces.Locking;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using LanguageExt;
using MediatR;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
using ThreadingChannel = System.Threading.Channels.Channel;
namespace ErsatzTV.Tests.Application.Libraries;
[TestFixture]
public class QueueShowScanByLibraryIdHandlerTests
{
private InMemoryTvContext _db = null!;
[SetUp]
public async Task SetUp() => _db = await InMemoryTvContext.CreateAsync();
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
[Test]
public async Task Handle_Should_Return_NotFound_When_Library_Missing()
{
var locker = Substitute.For<IEntityLocker>();
var mediator = Substitute.For<IMediator>();
QueueShowScanByLibraryIdHandler handler = CreateHandler(locker, mediator, out _);
QueueShowScanResult result = await handler.Handle(
new QueueShowScanByLibraryId(9999, 1, "Show", false),
CancellationToken.None);
result.ShouldBe(QueueShowScanResult.NotFound);
locker.DidNotReceive().LockLibrary(Arg.Any<int>());
}
[Test]
public async Task Handle_Should_Return_SyncDisabled_When_Item_Sync_Off()
{
int libraryId = await SeedPlexLibrary(shouldSyncItems: false);
var locker = Substitute.For<IEntityLocker>();
var mediator = Substitute.For<IMediator>();
QueueShowScanByLibraryIdHandler handler = CreateHandler(locker, mediator, out _);
QueueShowScanResult result = await handler.Handle(
new QueueShowScanByLibraryId(libraryId, 1, "Show", false),
CancellationToken.None);
result.ShouldBe(QueueShowScanResult.SyncDisabled);
locker.DidNotReceive().LockLibrary(Arg.Any<int>());
}
[Test]
public async Task Handle_Should_Return_AlreadyScanning_When_Lock_Not_Acquired()
{
int libraryId = await SeedPlexLibrary(shouldSyncItems: true);
var locker = Substitute.For<IEntityLocker>();
locker.LockLibrary(libraryId).Returns(false);
var mediator = Substitute.For<IMediator>();
QueueShowScanByLibraryIdHandler handler = CreateHandler(locker, mediator, out _);
QueueShowScanResult result = await handler.Handle(
new QueueShowScanByLibraryId(libraryId, 1, "Show", false),
CancellationToken.None);
result.ShouldBe(QueueShowScanResult.AlreadyScanning);
await mediator.DidNotReceive().Send(Arg.Any<SynchronizePlexShowById>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task Handle_Should_Return_Unsupported_For_Local_Library()
{
int libraryId = await SeedLocalLibrary();
var locker = Substitute.For<IEntityLocker>();
locker.LockLibrary(libraryId).Returns(true);
var mediator = Substitute.For<IMediator>();
QueueShowScanByLibraryIdHandler handler = CreateHandler(locker, mediator, out _);
QueueShowScanResult result = await handler.Handle(
new QueueShowScanByLibraryId(libraryId, 1, "Show", false),
CancellationToken.None);
result.ShouldBe(QueueShowScanResult.Unsupported);
locker.Received(1).UnlockLibrary(libraryId);
}
[Test]
public async Task Handle_Should_Return_Queued_And_Extract_Subtitles_On_Deep_Success()
{
int libraryId = await SeedPlexLibrary(shouldSyncItems: true);
var locker = Substitute.For<IEntityLocker>();
locker.LockLibrary(libraryId).Returns(true);
var mediator = Substitute.For<IMediator>();
mediator.Send(Arg.Any<SynchronizePlexShowById>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, string>("ok"));
QueueShowScanByLibraryIdHandler handler = CreateHandler(
locker,
mediator,
out Channel<IBackgroundServiceRequest> worker);
QueueShowScanResult result = await handler.Handle(
new QueueShowScanByLibraryId(libraryId, 42, "Show", DeepScan: true),
CancellationToken.None);
result.ShouldBe(QueueShowScanResult.Queued);
locker.Received(1).UnlockLibrary(libraryId);
worker.Reader.TryRead(out IBackgroundServiceRequest? request).ShouldBeTrue();
request.ShouldBeOfType<ExtractEmbeddedShowSubtitles>().ShowId.ShouldBe(42);
}
[Test]
public async Task Handle_Should_Return_ScanFailed_When_SubScan_Left()
{
int libraryId = await SeedPlexLibrary(shouldSyncItems: true);
var locker = Substitute.For<IEntityLocker>();
locker.LockLibrary(libraryId).Returns(true);
var mediator = Substitute.For<IMediator>();
mediator.Send(Arg.Any<SynchronizePlexShowById>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, string>(BaseError.New("scan error")));
QueueShowScanByLibraryIdHandler handler = CreateHandler(
locker,
mediator,
out Channel<IBackgroundServiceRequest> worker);
QueueShowScanResult result = await handler.Handle(
new QueueShowScanByLibraryId(libraryId, 42, "Show", DeepScan: true),
CancellationToken.None);
result.ShouldBe(QueueShowScanResult.ScanFailed);
locker.Received(1).UnlockLibrary(libraryId);
// no subtitle extraction on a failed scan
worker.Reader.TryRead(out _).ShouldBeFalse();
}
private QueueShowScanByLibraryIdHandler CreateHandler(
IEntityLocker locker,
IMediator mediator,
out Channel<IBackgroundServiceRequest> worker)
{
worker = ThreadingChannel.CreateUnbounded<IBackgroundServiceRequest>();
return new QueueShowScanByLibraryIdHandler(
_db.Factory,
locker,
mediator,
worker.Writer,
NullLogger<QueueShowScanByLibraryIdHandler>.Instance);
}
private async Task<int> SeedLocalLibrary()
{
await using TvContext context = _db.CreateContext();
var source = new LocalMediaSource
{
Libraries =
[
new LocalLibrary
{
Name = "Local Movies",
MediaKind = LibraryMediaKind.Movies,
Paths = []
}
]
};
await context.LocalMediaSources.AddAsync(source);
await context.SaveChangesAsync();
return source.Libraries[0].Id;
}
private async Task<int> SeedPlexLibrary(bool shouldSyncItems)
{
await using TvContext context = _db.CreateContext();
var source = new PlexMediaSource
{
ServerName = "Plex Server",
ProductVersion = "1",
Platform = "Linux",
PlatformVersion = "1",
ClientIdentifier = "plex",
Connections = [],
PathReplacements = [],
Libraries =
[
new PlexLibrary
{
Name = "Plex Shows",
MediaKind = LibraryMediaKind.Shows,
Key = "1",
ShouldSyncItems = shouldSyncItems,
Paths = []
}
]
};
await context.PlexMediaSources.AddAsync(source);
await context.SaveChangesAsync();
return source.Libraries[0].Id;
}
}
@@ -0,0 +1,155 @@
using ErsatzTV.Application;
using ErsatzTV.Application.MediaCollections;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using LanguageExt;
using Microsoft.EntityFrameworkCore;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
namespace ErsatzTV.Tests.Application.MediaCollections;
/// <summary>
/// Contract tests for the #253 optimistic-concurrency mechanic on the Playlist aggregate (mirrors
/// ReplaceBlockItemsHandlerConcurrencyTests, the Block reference implementation): the handler
/// pre-check (stale If-Match → 412), the force-write path (no If-Match), the unconditional Version
/// bump on every save, and the EF concurrency-token backstop that catches a writer that lost the
/// load→save race. The backstop test is non-vacuous by construction — remove the
/// <c>IsConcurrencyToken()</c> config on Playlist and the losing save silently succeeds instead of
/// mapping to a <see cref="PreconditionFailedError" />.
/// </summary>
[TestFixture]
public class ReplacePlaylistItemsHandlerConcurrencyTests
{
private InMemoryTvContext _db = null!;
[SetUp]
public async Task SetUp() => _db = await InMemoryTvContext.CreateAsync();
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
private async Task SeedPlaylistAsync(int version)
{
await using TvContext ctx = _db.CreateContext();
ctx.Playlists.Add(
new Playlist
{
Id = 1,
PlaylistGroupId = 1,
Name = "Kids",
IsSystem = false,
Version = version,
Items = new List<PlaylistItem>()
});
await ctx.SaveChangesAsync();
}
private static ReplacePlaylistItems Command(Option<int> expectedVersion) =>
new(
1,
"Kids",
new List<ReplacePlaylistItem>
{
new(0, CollectionType.Movie, null, null, null, 55, PlaybackOrder.Shuffle, null, false, true)
},
expectedVersion);
private async Task<int> ReadVersionAsync()
{
await using TvContext ctx = _db.CreateContext();
return await ctx.Playlists.Where(p => p.Id == 1).Select(p => p.Version).SingleAsync();
}
private static BaseError? LeftOrNull<T>(Either<BaseError, T> result) =>
result.Match<BaseError?>(Right: _ => null, Left: e => e);
[Test]
public async Task Stale_If_Match_Should_Fail_Precondition_And_Not_Mutate()
{
await SeedPlaylistAsync(version: 2);
var handler = new ReplacePlaylistItemsHandler(_db.Factory);
Either<BaseError, List<PlaylistItemViewModel>> result =
await handler.Handle(Command(Some(1)), CancellationToken.None);
LeftOrNull(result).ShouldBeOfType<PreconditionFailedError>();
// The pre-check runs before any mutation: version unchanged, no items written.
(await ReadVersionAsync()).ShouldBe(2);
await using TvContext ctx = _db.CreateContext();
(await ctx.PlaylistItems.CountAsync(i => i.PlaylistId == 1)).ShouldBe(0);
}
[Test]
public async Task Matching_If_Match_Should_Succeed_And_Bump_Version()
{
await SeedPlaylistAsync(version: 2);
var handler = new ReplacePlaylistItemsHandler(_db.Factory);
Either<BaseError, List<PlaylistItemViewModel>> result =
await handler.Handle(Command(Some(2)), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Absent_If_Match_Should_Force_Write_And_Bump_Version()
{
await SeedPlaylistAsync(version: 2);
var handler = new ReplacePlaylistItemsHandler(_db.Factory);
// None expected version = Phase-1 force-write regardless of the stored version.
Either<BaseError, List<PlaylistItemViewModel>> result =
await handler.Handle(Command(None), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Save_Should_Bump_Version_Even_When_Content_Is_Unchanged()
{
await SeedPlaylistAsync(version: 5);
var handler = new ReplacePlaylistItemsHandler(_db.Factory);
// Same content twice: the unconditional bump (M1) must still rotate the version each time,
// otherwise a no-op PUT-back would not fire the token or rotate other clients' ETags.
(await handler.Handle(Command(Some(5)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(6);
(await handler.Handle(Command(Some(6)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(7);
}
[Test]
public async Task Racing_Save_Should_Map_Concurrency_Failure_To_412()
{
await SeedPlaylistAsync(version: 1);
// Two writers load the same version, then both bump-and-save. The IsConcurrencyToken guard on
// Playlist makes the second UPDATE key on the original version; it matches zero rows and throws
// DbUpdateConcurrencyException, which the shared save helper maps to a PreconditionFailedError.
await using TvContext ctxWinner = _db.CreateContext();
await using TvContext ctxLoser = _db.CreateContext();
Playlist winner = await ctxWinner.Playlists.SingleAsync(p => p.Id == 1);
Playlist loser = await ctxLoser.Playlists.SingleAsync(p => p.Id == 1);
winner.Version++;
Either<BaseError, Unit> winnerResult = await ctxWinner.SaveChangesWithConcurrencyGuard(CancellationToken.None);
winnerResult.IsRight.ShouldBeTrue();
loser.Version++;
Either<BaseError, Unit> loserResult = await ctxLoser.SaveChangesWithConcurrencyGuard(CancellationToken.None);
LeftOrNull(loserResult).ShouldBeOfType<PreconditionFailedError>();
// Non-vacuous: the winner's write stuck at exactly its +1; the loser did not overwrite it.
(await ReadVersionAsync()).ShouldBe(2);
}
}
@@ -0,0 +1,82 @@
using System.Collections.Generic;
using System.Threading;
using System.Threading.Channels;
using System.Threading.Tasks;
using ErsatzTV.Application;
using ErsatzTV.Application.Playouts;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Interfaces.Locking;
using ErsatzTV.Core.Scheduling;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using NSubstitute;
using NUnit.Framework;
using Shouldly;
using Channel = System.Threading.Channels.Channel;
namespace ErsatzTV.Tests.Application.Playouts;
[TestFixture]
public class ResetAllPlayoutsHandlerTests
{
private InMemoryTvContext _db = null!;
private Channel<IBackgroundServiceRequest> _worker = null!;
private IEntityLocker _entityLocker = null!;
[SetUp]
public async Task SetUp()
{
_db = await InMemoryTvContext.CreateAsync();
_worker = Channel.CreateUnbounded<IBackgroundServiceRequest>();
_entityLocker = Substitute.For<IEntityLocker>();
}
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
private ResetAllPlayoutsHandler CreateHandler() =>
new(_entityLocker, _worker.Writer, _db.Factory);
private async Task<int> SeedPlayout(PlayoutScheduleKind kind)
{
await using TvContext context = _db.CreateContext();
var playout = new Playout { ChannelId = 0, ScheduleKind = kind };
context.Playouts.Add(playout);
await context.SaveChangesAsync();
return playout.Id;
}
[Test]
public async Task Handle_Should_Queue_Eligible_And_Report_Skipped()
{
int classicId = await SeedPlayout(PlayoutScheduleKind.Classic);
int blockId = await SeedPlayout(PlayoutScheduleKind.Block);
int lockedId = await SeedPlayout(PlayoutScheduleKind.Sequential);
int externalJsonId = await SeedPlayout(PlayoutScheduleKind.ExternalJson);
int noneId = await SeedPlayout(PlayoutScheduleKind.None);
_entityLocker.IsPlayoutLocked(lockedId).Returns(true);
ResetAllPlayoutsResult result =
await CreateHandler().Handle(new ResetAllPlayouts(), CancellationToken.None);
// eligible, unlocked playouts are queued
result.QueuedPlayoutIds.ShouldBe(new List<int> { classicId, blockId }, ignoreOrder: true);
// locked playout lands in SkippedLocked, not queued
result.SkippedLocked.ShouldBe(new List<int> { lockedId });
// ExternalJson + None land in SkippedUnsupported
result.SkippedUnsupported.ShouldBe(new List<int> { externalJsonId, noneId }, ignoreOrder: true);
// exactly one BuildPlayout message per queued playout was enqueued
var enqueued = new List<int>();
while (_worker.Reader.TryRead(out IBackgroundServiceRequest? request))
{
var build = request.ShouldBeOfType<BuildPlayout>();
enqueued.Add(build.PlayoutId);
}
enqueued.ShouldBe(new List<int> { classicId, blockId }, ignoreOrder: true);
}
}
@@ -0,0 +1,231 @@
using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.ProgramSchedules;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Scheduling;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using LanguageExt;
using Microsoft.EntityFrameworkCore;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
namespace ErsatzTV.Tests.Application.ProgramSchedules;
/// <summary>
/// Contract tests for the #253 optimistic-concurrency mechanic on the ProgramSchedule / schedule-items
/// aggregate: the handler pre-check (stale If-Match → 412, before the positional reconcile runs — so the
/// item rows AND persisted fill-group/shuffle state are left untouched), the force-write path (no
/// If-Match), the unconditional Version bump on every save (including a no-op same-items PUT-back where
/// only child rows change), and the EF concurrency-token backstop that catches a writer that lost the
/// load→save race. The backstop test is non-vacuous by construction — remove the
/// <c>IsConcurrencyToken()</c> config on ProgramSchedule and the losing save silently succeeds instead
/// of mapping to a <see cref="PreconditionFailedError" />.
/// </summary>
[TestFixture]
public class ReplaceProgramScheduleItemsHandlerConcurrencyTests
{
private InMemoryTvContext _db = null!;
private ChannelWriter<IBackgroundServiceRequest> _worker = null!;
[SetUp]
public async Task SetUp()
{
_db = await InMemoryTvContext.CreateAsync();
_worker = System.Threading.Channels.Channel.CreateUnbounded<IBackgroundServiceRequest>().Writer;
}
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
// Seeds a schedule (Id=1) with a single One/SearchQuery item (Id=1) and a persisted fill-group
// enumerator state pointing at that item, so the stale-If-Match test can prove the reconcile never ran.
private async Task SeedScheduleAsync(int version)
{
await using TvContext ctx = _db.CreateContext();
ctx.ProgramSchedules.Add(
new ProgramSchedule
{
Id = 1,
Name = "Concurrency",
Version = version,
Items = new List<ProgramScheduleItem>
{
new ProgramScheduleItemOne
{
Id = 1,
Index = 0,
CollectionType = CollectionType.SearchQuery,
SearchTitle = "a",
SearchQuery = "a",
PlaybackOrder = PlaybackOrder.Shuffle,
GuideMode = GuideMode.Normal
}
},
Playouts = [],
ProgramScheduleAlternates = []
});
await ctx.SaveChangesAsync();
ctx.Add(new PlayoutScheduleItemFillGroupIndex
{
PlayoutId = 1,
ProgramScheduleItemId = 1,
EnumeratorState = new CollectionEnumeratorState { Seed = 12345, Index = 7 }
});
await ctx.SaveChangesAsync();
}
private static ReplaceProgramScheduleItems Command(
Option<int> expectedVersion,
List<ReplaceProgramScheduleItem>? items = null) =>
new(1, items ?? [MakeItem(0, PlayoutMode.One, "a")], expectedVersion);
private async Task<int> ReadVersionAsync()
{
await using TvContext ctx = _db.CreateContext();
return await ctx.ProgramSchedules.Where(s => s.Id == 1).Select(s => s.Version).SingleAsync();
}
private static BaseError? LeftOrNull(Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result) =>
result.Match<BaseError?>(Right: _ => null, Left: e => e);
[Test]
public async Task Stale_If_Match_Should_Fail_Precondition_And_Not_Mutate()
{
await SeedScheduleAsync(version: 2);
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
// An empty item list WOULD delete the existing item (and cascade its fill-group state) if the
// reconcile ran. A stale If-Match must reject before that, leaving everything untouched.
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
await handler.Handle(Command(Some(1), []), CancellationToken.None);
LeftOrNull(result).ShouldBeOfType<PreconditionFailedError>();
(await ReadVersionAsync()).ShouldBe(2);
await using TvContext ctx = _db.CreateContext();
(await ctx.ProgramScheduleItems.CountAsync(i => i.ProgramScheduleId == 1)).ShouldBe(1);
// The reconcile never ran: the fill-group enumerator state is exactly as seeded.
PlayoutScheduleItemFillGroupIndex fillGroup = await ctx.Set<PlayoutScheduleItemFillGroupIndex>()
.Include(x => x.EnumeratorState)
.SingleAsync();
fillGroup.ProgramScheduleItemId.ShouldBe(1);
fillGroup.EnumeratorState.Seed.ShouldBe(12345);
fillGroup.EnumeratorState.Index.ShouldBe(7);
}
[Test]
public async Task Matching_If_Match_Should_Succeed_And_Bump_Version()
{
await SeedScheduleAsync(version: 2);
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
await handler.Handle(Command(Some(2)), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Absent_If_Match_Should_Force_Write_And_Bump_Version()
{
await SeedScheduleAsync(version: 2);
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
// None expected version = Phase-1 force-write regardless of the stored version.
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
await handler.Handle(Command(None), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task NoOp_Save_Should_Bump_Version_Even_With_Only_Child_Changes()
{
await SeedScheduleAsync(version: 5);
var handler = new ReplaceProgramScheduleItemsHandler(_db.Factory, _worker);
// Same content twice: this handler saves with only CHILD changes and no root-scalar change, so the
// unconditional bump (M1) must still rotate the version each time, otherwise a no-op PUT-back would
// neither fire the token nor rotate other clients' ETags.
(await handler.Handle(Command(Some(5)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(6);
(await handler.Handle(Command(Some(6)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(7);
}
[Test]
public async Task Racing_Save_Should_Map_Concurrency_Failure_To_412()
{
await SeedScheduleAsync(version: 1);
// Two writers load the same version, then both bump-and-save. The IsConcurrencyToken guard on
// ProgramSchedule makes the second UPDATE key on the original version; it matches zero rows and
// throws DbUpdateConcurrencyException, which the shared save helper maps to a PreconditionFailedError.
await using TvContext ctxWinner = _db.CreateContext();
await using TvContext ctxLoser = _db.CreateContext();
ProgramSchedule winner = await ctxWinner.ProgramSchedules.SingleAsync(s => s.Id == 1);
ProgramSchedule loser = await ctxLoser.ProgramSchedules.SingleAsync(s => s.Id == 1);
winner.Version++;
Either<BaseError, Unit> winnerResult = await ctxWinner.SaveChangesWithConcurrencyGuard(CancellationToken.None);
winnerResult.IsRight.ShouldBeTrue();
loser.Version++;
Either<BaseError, Unit> loserResult = await ctxLoser.SaveChangesWithConcurrencyGuard(CancellationToken.None);
loserResult.Match<BaseError?>(Right: _ => null, Left: e => e).ShouldBeOfType<PreconditionFailedError>();
// Non-vacuous: the winner's write stuck at exactly its +1; the loser did not overwrite it.
(await ReadVersionAsync()).ShouldBe(2);
}
private static ReplaceProgramScheduleItem MakeItem(int index, PlayoutMode mode, string searchQuery) =>
new(
index,
StartType.Dynamic,
StartTime: null,
FixedStartTimeBehavior: null,
mode,
CollectionType.SearchQuery,
CollectionId: null,
MultiCollectionId: null,
SmartCollectionId: null,
RerunCollectionId: null,
MediaItemId: null,
PlaylistId: null,
SearchTitle: searchQuery,
SearchQuery: searchQuery,
PlaybackOrder.Shuffle,
MarathonGroupBy.None,
MarathonShuffleGroups: false,
MarathonShuffleItems: false,
MarathonBatchSize: null,
FillWithGroupMode.None,
MultipleMode.Count,
MultipleCount: "1",
PlayoutDuration: null,
TailMode.None,
DiscardToFillAttempts: null,
CustomTitle: null,
GuideMode.Normal,
PreRollFillerId: null,
MidRollFillerId: null,
PostRollFillerId: null,
TailFillerId: null,
FallbackFillerId: null,
WatermarkIds: [],
GraphicsElementIds: [],
PreferredAudioLanguageCode: null,
PreferredAudioTitle: null,
PreferredSubtitleLanguageCode: null,
SubtitleMode: null);
}
@@ -0,0 +1,164 @@
using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.Playouts;
using ErsatzTV.Application.Scheduling;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Domain.Scheduling;
using ErsatzTV.Core.Errors;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using LanguageExt;
using Microsoft.EntityFrameworkCore;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
namespace ErsatzTV.Tests.Application.Scheduling;
/// <summary>
/// Contract tests for the #253 optimistic-concurrency mechanic on the DecoTemplate aggregate,
/// mirroring <see cref="ReplaceBlockItemsHandlerConcurrencyTests" /> (the Block reference
/// implementation): the handler pre-check (stale If-Match → 412), the force-write path (no
/// If-Match), the unconditional Version bump on every save, and the EF concurrency-token backstop
/// that catches a writer that lost the load→save race. The backstop test is non-vacuous by
/// construction — remove the <c>IsConcurrencyToken()</c> config on DecoTemplate and the losing save
/// silently succeeds instead of mapping to a <see cref="PreconditionFailedError" />.
/// </summary>
[TestFixture]
public class ReplaceDecoTemplateItemsHandlerConcurrencyTests
{
private InMemoryTvContext _db = null!;
private Channel<IBackgroundServiceRequest> _channel = null!;
[SetUp]
public async Task SetUp()
{
_db = await InMemoryTvContext.CreateAsync();
_channel = System.Threading.Channels.Channel.CreateUnbounded<IBackgroundServiceRequest>();
}
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
private async Task SeedDecoTemplateAsync(int version)
{
await using TvContext ctx = _db.CreateContext();
ctx.Decos.Add(new Deco { Id = 10, DecoGroupId = 1, Name = "D" });
ctx.DecoTemplates.Add(
new DecoTemplate
{
Id = 1,
DecoTemplateGroupId = 1,
Name = "Weekday",
Version = version,
Items = new List<DecoTemplateItem>()
});
await ctx.SaveChangesAsync();
}
private ReplaceDecoTemplateItemsHandler CreateHandler() => new(_db.Factory, _channel.Writer);
private static ReplaceDecoTemplateItems Command(Option<int> expectedVersion) =>
new(
DecoTemplateId: 1,
DecoTemplateGroupId: 1,
Name: "Weekday",
Items: [new ReplaceDecoTemplateItem(DecoId: 10, StartTime: TimeSpan.Zero, EndTime: TimeSpan.FromHours(1))],
ExpectedVersion: expectedVersion);
private async Task<int> ReadVersionAsync()
{
await using TvContext ctx = _db.CreateContext();
return await ctx.DecoTemplates.Where(t => t.Id == 1).Select(t => t.Version).SingleAsync();
}
private static BaseError? LeftOrNull<T>(Either<BaseError, T> result) =>
result.Match<BaseError?>(Right: _ => null, Left: e => e);
[Test]
public async Task Stale_If_Match_Should_Fail_Precondition_And_Not_Mutate()
{
await SeedDecoTemplateAsync(version: 2);
ReplaceDecoTemplateItemsHandler handler = CreateHandler();
Either<BaseError, List<DecoTemplateItemViewModel>> result =
await handler.Handle(Command(Some(1)), CancellationToken.None);
LeftOrNull(result).ShouldBeOfType<PreconditionFailedError>();
// The pre-check runs before any mutation: version unchanged, no items written.
(await ReadVersionAsync()).ShouldBe(2);
await using TvContext ctx = _db.CreateContext();
(await ctx.DecoTemplateItems.CountAsync(i => i.DecoTemplateId == 1)).ShouldBe(0);
}
[Test]
public async Task Matching_If_Match_Should_Succeed_And_Bump_Version()
{
await SeedDecoTemplateAsync(version: 2);
ReplaceDecoTemplateItemsHandler handler = CreateHandler();
Either<BaseError, List<DecoTemplateItemViewModel>> result =
await handler.Handle(Command(Some(2)), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Absent_If_Match_Should_Force_Write_And_Bump_Version()
{
await SeedDecoTemplateAsync(version: 2);
ReplaceDecoTemplateItemsHandler handler = CreateHandler();
// None expected version = Phase-1 force-write regardless of the stored version.
Either<BaseError, List<DecoTemplateItemViewModel>> result =
await handler.Handle(Command(None), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Save_Should_Bump_Version_Even_When_Content_Is_Unchanged()
{
await SeedDecoTemplateAsync(version: 5);
ReplaceDecoTemplateItemsHandler handler = CreateHandler();
// Same content twice: the unconditional bump (M1) must still rotate the version each time,
// otherwise a no-op PUT-back would not fire the token or rotate other clients' ETags.
(await handler.Handle(Command(Some(5)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(6);
(await handler.Handle(Command(Some(6)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(7);
}
[Test]
public async Task Racing_Save_Should_Map_Concurrency_Failure_To_412()
{
await SeedDecoTemplateAsync(version: 1);
// Two writers load the same version, then both bump-and-save. The IsConcurrencyToken guard on
// DecoTemplate makes the second UPDATE key on the original version; it matches zero rows and
// throws DbUpdateConcurrencyException, which the shared save helper maps to a
// PreconditionFailedError.
await using TvContext ctxWinner = _db.CreateContext();
await using TvContext ctxLoser = _db.CreateContext();
DecoTemplate winner = await ctxWinner.DecoTemplates.SingleAsync(t => t.Id == 1);
DecoTemplate loser = await ctxLoser.DecoTemplates.SingleAsync(t => t.Id == 1);
winner.Version++;
Either<BaseError, Unit> winnerResult = await ctxWinner.SaveChangesWithConcurrencyGuard(CancellationToken.None);
winnerResult.IsRight.ShouldBeTrue();
loser.Version++;
Either<BaseError, Unit> loserResult = await ctxLoser.SaveChangesWithConcurrencyGuard(CancellationToken.None);
LeftOrNull(loserResult).ShouldBeOfType<PreconditionFailedError>();
// Non-vacuous: the winner's write stuck at exactly its +1; the loser did not overwrite it.
(await ReadVersionAsync()).ShouldBe(2);
}
}
@@ -0,0 +1,163 @@
using ErsatzTV.Application;
using ErsatzTV.Application.Scheduling;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain.Scheduling;
using ErsatzTV.Core.Errors;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Tests.Support;
using LanguageExt;
using Microsoft.EntityFrameworkCore;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
namespace ErsatzTV.Tests.Application.Scheduling;
/// <summary>
/// Contract tests for the #253 optimistic-concurrency mechanic on the Template aggregate,
/// mirroring <see cref="ReplaceBlockItemsHandlerConcurrencyTests" /> (the Block reference
/// implementation): the handler pre-check (stale If-Match → 412), the force-write path (no
/// If-Match), the unconditional Version bump on every save, and the EF concurrency-token backstop
/// that catches a writer that lost the load→save race. The backstop test is non-vacuous by
/// construction — remove the <c>IsConcurrencyToken()</c> config on Template and the losing save
/// silently succeeds instead of mapping to a <see cref="PreconditionFailedError" />.
/// </summary>
[TestFixture]
public class ReplaceTemplateItemsHandlerConcurrencyTests
{
private InMemoryTvContext _db = null!;
[SetUp]
public async Task SetUp() => _db = await InMemoryTvContext.CreateAsync();
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
private async Task SeedTemplateAsync(int version)
{
await using TvContext ctx = _db.CreateContext();
ctx.Blocks.Add(
new Block
{
Id = 10,
BlockGroupId = 1,
Name = "Morning",
Minutes = 30,
StopScheduling = BlockStopScheduling.AfterDurationEnd,
Items = new List<BlockItem>()
});
ctx.Templates.Add(
new Template
{
Id = 1,
TemplateGroupId = 1,
Name = "Weekday",
Version = version,
Items = new List<TemplateItem>()
});
await ctx.SaveChangesAsync();
}
private static ReplaceTemplateItems Command(Option<int> expectedVersion) =>
new(
1,
1,
"Weekday",
new List<ReplaceTemplateItem> { new(10, TimeSpan.Zero) },
expectedVersion);
private async Task<int> ReadVersionAsync()
{
await using TvContext ctx = _db.CreateContext();
return await ctx.Templates.Where(t => t.Id == 1).Select(t => t.Version).SingleAsync();
}
private static BaseError? LeftOrNull<T>(Either<BaseError, T> result) =>
result.Match<BaseError?>(Right: _ => null, Left: e => e);
[Test]
public async Task Stale_If_Match_Should_Fail_Precondition_And_Not_Mutate()
{
await SeedTemplateAsync(version: 2);
var handler = new ReplaceTemplateItemsHandler(_db.Factory);
Either<BaseError, List<TemplateItemViewModel>> result =
await handler.Handle(Command(Some(1)), CancellationToken.None);
LeftOrNull(result).ShouldBeOfType<PreconditionFailedError>();
// The pre-check runs before any mutation: version unchanged, no items written.
(await ReadVersionAsync()).ShouldBe(2);
await using TvContext ctx = _db.CreateContext();
(await ctx.TemplateItems.CountAsync(i => i.TemplateId == 1)).ShouldBe(0);
}
[Test]
public async Task Matching_If_Match_Should_Succeed_And_Bump_Version()
{
await SeedTemplateAsync(version: 2);
var handler = new ReplaceTemplateItemsHandler(_db.Factory);
Either<BaseError, List<TemplateItemViewModel>> result =
await handler.Handle(Command(Some(2)), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Absent_If_Match_Should_Force_Write_And_Bump_Version()
{
await SeedTemplateAsync(version: 2);
var handler = new ReplaceTemplateItemsHandler(_db.Factory);
// None expected version = Phase-1 force-write regardless of the stored version.
Either<BaseError, List<TemplateItemViewModel>> result =
await handler.Handle(Command(None), CancellationToken.None);
result.IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(3);
}
[Test]
public async Task Save_Should_Bump_Version_Even_When_Content_Is_Unchanged()
{
await SeedTemplateAsync(version: 5);
var handler = new ReplaceTemplateItemsHandler(_db.Factory);
// Same content twice: the unconditional bump (M1) must still rotate the version each time,
// otherwise a no-op PUT-back would not fire the token or rotate other clients' ETags.
(await handler.Handle(Command(Some(5)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(6);
(await handler.Handle(Command(Some(6)), CancellationToken.None)).IsRight.ShouldBeTrue();
(await ReadVersionAsync()).ShouldBe(7);
}
[Test]
public async Task Racing_Save_Should_Map_Concurrency_Failure_To_412()
{
await SeedTemplateAsync(version: 1);
// Two writers load the same version, then both bump-and-save. The IsConcurrencyToken guard on
// Template makes the second UPDATE key on the original version; it matches zero rows and
// throws DbUpdateConcurrencyException, which the shared save helper maps to a
// PreconditionFailedError.
await using TvContext ctxWinner = _db.CreateContext();
await using TvContext ctxLoser = _db.CreateContext();
Template winner = await ctxWinner.Templates.SingleAsync(t => t.Id == 1);
Template loser = await ctxLoser.Templates.SingleAsync(t => t.Id == 1);
winner.Version++;
Either<BaseError, Unit> winnerResult = await ctxWinner.SaveChangesWithConcurrencyGuard(CancellationToken.None);
winnerResult.IsRight.ShouldBeTrue();
loser.Version++;
Either<BaseError, Unit> loserResult = await ctxLoser.SaveChangesWithConcurrencyGuard(CancellationToken.None);
LeftOrNull(loserResult).ShouldBeOfType<PreconditionFailedError>();
// Non-vacuous: the winner's write stuck at exactly its +1; the loser did not overwrite it.
(await ReadVersionAsync()).ShouldBe(2);
}
}
@@ -407,7 +407,7 @@ public class ChannelControllerTests
IActionResult result = await _controller.ResetPlayout("5", mode: null, CancellationToken.None);
result.ShouldBeOfType<OkResult>();
result.ShouldBeOfType<AcceptedResult>().StatusCode.ShouldBe(202);
_workerChannel.Reader.TryRead(out IBackgroundServiceRequest? request).ShouldBeTrue();
var buildPlayout = request.ShouldBeOfType<BuildPlayout>();
buildPlayout.PlayoutId.ShouldBe(9);
@@ -436,7 +436,7 @@ public class ChannelControllerTests
IActionResult result = await _controller.ResetPlayout("5", PlayoutBuildMode.Continue, CancellationToken.None);
result.ShouldBeOfType<OkResult>();
result.ShouldBeOfType<AcceptedResult>().StatusCode.ShouldBe(202);
_workerChannel.Reader.TryRead(out IBackgroundServiceRequest? request).ShouldBeTrue();
request.ShouldBeOfType<BuildPlayout>().Mode.ShouldBe(PlayoutBuildMode.Continue);
await _mediator.DidNotReceive().Send(Arg.Any<GetPlayoutById>(), Arg.Any<CancellationToken>());
@@ -152,7 +152,7 @@ public class DecoControllerTests
null,
null,
null,
new ErsatzTV.Application.MediaCollections.PlaylistViewModel(9, 3, "Idents", false),
new ErsatzTV.Application.MediaCollections.PlaylistViewModel(9, 3, "Idents", false, 1),
DecoBreakPlacement.BlockStart)
]);
_mediator.Send(Arg.Any<GetDecoById>(), Arg.Any<CancellationToken>())
@@ -4,8 +4,10 @@ using ErsatzTV.Controllers.Api;
using ErsatzTV.Controllers.Api.Requests;
using ErsatzTV.Core;
using ErsatzTV.Core.Api.Scheduling;
using ErsatzTV.Core.Errors;
using LanguageExt;
using MediatR;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Routing;
using NSubstitute;
@@ -25,7 +27,12 @@ public class DecoTemplateControllerTests
public void SetUp()
{
_mediator = Substitute.For<IMediator>();
_controller = new DecoTemplateController(_mediator);
_controller = new DecoTemplateController(_mediator)
{
// Provide a real HttpContext so the ETag/If-Match concurrency headers (#253) can be
// read from Request and written to Response.
ControllerContext = new ControllerContext { HttpContext = new DefaultHttpContext() }
};
}
[Test]
@@ -259,12 +266,10 @@ public class DecoTemplateControllerTests
_mediator.Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<DecoTemplateViewModel>.Some(MakeDecoTemplate(4, 7, "Morning")));
_mediator.Send(Arg.Any<ReplaceDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<DecoTemplateItemViewModel>>([]));
.Returns(Right<BaseError, List<DecoTemplateItemViewModel>>(
[MakeItem(10, "Morning Bumper", TimeSpan.FromHours(6), TimeSpan.FromHours(7))]));
_mediator.Send(Arg.Any<GetDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<DecoTemplateItemViewModel>
{
MakeItem(10, "Morning Bumper", TimeSpan.FromHours(6), TimeSpan.FromHours(7))
});
.Returns([MakeItem(10, "Morning Bumper", TimeSpan.FromHours(6), TimeSpan.FromHours(7))]);
IActionResult result = await _controller.Replace(
4,
@@ -318,11 +323,100 @@ public class DecoTemplateControllerTests
CancellationToken.None);
result.ShouldBeOfType<UnprocessableEntityObjectResult>();
await _mediator.DidNotReceive().Send(Arg.Any<GetDecoTemplateItems>(), Arg.Any<CancellationToken>());
}
private static DecoTemplateViewModel MakeDecoTemplate(int id, int groupId, string name) =>
new(id, groupId, "Group", name);
[Test]
public async Task GetItems_Should_Set_ETag_From_DecoTemplate_Version()
{
_mediator.Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<DecoTemplateViewModel>.Some(MakeDecoTemplate(4, 2, "Morning", version: 9)));
_mediator.Send(Arg.Any<GetDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<DecoTemplateItemViewModel>());
await _controller.GetItems(4, CancellationToken.None);
_controller.Response.Headers.ETag.ToString().ShouldBe("\"9\"");
}
[Test]
public async Task Replace_Should_Return_400_On_Malformed_If_Match()
{
_controller.Request.Headers.IfMatch = "not-an-etag";
IActionResult result = await _controller.Replace(
4,
new ReplaceDecoTemplateRequest("Morning", []),
CancellationToken.None);
result.ShouldBeOfType<BadRequestObjectResult>();
await _mediator.DidNotReceive().Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>());
await _mediator.DidNotReceive().Send(Arg.Any<ReplaceDecoTemplateItems>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task Replace_Should_Thread_If_Match_Version_Into_Command()
{
_controller.Request.Headers.IfMatch = "\"3\"";
_mediator.Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<DecoTemplateViewModel>.Some(MakeDecoTemplate(4, 7, "Morning", version: 4)));
_mediator.Send(Arg.Any<ReplaceDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<DecoTemplateItemViewModel>>([]));
_mediator.Send(Arg.Any<GetDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<DecoTemplateItemViewModel>());
IActionResult result = await _controller.Replace(
4,
new ReplaceDecoTemplateRequest("Morning", []),
CancellationToken.None);
result.ShouldBeOfType<OkObjectResult>();
// On success the response carries the refreshed deco template's ETag.
_controller.Response.Headers.ETag.ToString().ShouldBe("\"4\"");
await _mediator.Received(1).Send(
Arg.Is<ReplaceDecoTemplateItems>(c => c.ExpectedVersion == Option<int>.Some(3)),
Arg.Any<CancellationToken>());
}
[Test]
public async Task Replace_Without_If_Match_Should_Force_Write()
{
_mediator.Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<DecoTemplateViewModel>.Some(MakeDecoTemplate(4, 7, "Morning")));
_mediator.Send(Arg.Any<ReplaceDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<DecoTemplateItemViewModel>>([]));
_mediator.Send(Arg.Any<GetDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<DecoTemplateItemViewModel>());
await _controller.Replace(
4,
new ReplaceDecoTemplateRequest("Morning", []),
CancellationToken.None);
await _mediator.Received(1).Send(
Arg.Is<ReplaceDecoTemplateItems>(c => c.ExpectedVersion == Option<int>.None),
Arg.Any<CancellationToken>());
}
[Test]
public async Task Replace_Should_Return_412_On_Precondition_Failed()
{
_controller.Request.Headers.IfMatch = "\"2\"";
_mediator.Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<DecoTemplateViewModel>.Some(MakeDecoTemplate(4, 7, "Morning", version: 5)));
_mediator.Send(Arg.Any<ReplaceDecoTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, List<DecoTemplateItemViewModel>>(new PreconditionFailedError("stale")));
IActionResult result = await _controller.Replace(
4,
new ReplaceDecoTemplateRequest("Morning", []),
CancellationToken.None);
var objectResult = result.ShouldBeOfType<ObjectResult>();
objectResult.StatusCode.ShouldBe(StatusCodes.Status412PreconditionFailed);
}
private static DecoTemplateViewModel MakeDecoTemplate(int id, int groupId, string name, int version = 1) =>
new(id, groupId, "Group", name, version);
private static DecoTemplateItemViewModel MakeItem(int decoId, string decoName, TimeSpan startTime, TimeSpan endTime)
{
@@ -75,6 +75,10 @@ public class EmbyMediaSourcesControllerTests
nameof(EmbyMediaSourcesController.RefreshLibraries),
"POST",
"/api/media-sources/emby/{id:int}/refresh-libraries");
ShouldHaveActionRoute(
nameof(EmbyMediaSourcesController.ScanCollections),
"POST",
"/api/media-sources/emby/{id:int}/scan-collections");
}
[Test]
@@ -414,6 +418,48 @@ public class EmbyMediaSourcesControllerTests
request.ShouldBeOfType<SynchronizeEmbyLibraries>().EmbyMediaSourceId.ShouldBe(1);
}
[Test]
public async Task ScanCollections_Should_Return_404_When_Source_Missing()
{
_mediator.Send(Arg.Any<GetEmbyMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(Option<EmbyMediaSourceViewModel>.None);
IActionResult result = await _controller.ScanCollections(99, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<NotFoundObjectResult>();
_entityLocker.DidNotReceive().LockEmbyCollections();
}
[Test]
public async Task ScanCollections_Should_Return_409_When_Collections_Locked()
{
_mediator.Send(Arg.Any<GetEmbyMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(Option<EmbyMediaSourceViewModel>.Some(new EmbyMediaSourceViewModel(1, "s", "a")));
_entityLocker.LockEmbyCollections().Returns(false);
IActionResult result = await _controller.ScanCollections(1, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<ConflictObjectResult>().Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(409);
_scannerChannel.Reader.TryRead(out _).ShouldBeFalse();
}
[Test]
public async Task ScanCollections_Should_Enqueue_And_Return_202()
{
_mediator.Send(Arg.Any<GetEmbyMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(Option<EmbyMediaSourceViewModel>.Some(new EmbyMediaSourceViewModel(1, "s", "a")));
_entityLocker.LockEmbyCollections().Returns(true);
IActionResult result = await _controller.ScanCollections(1, deep: true, CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
_scannerChannel.Reader.TryRead(out IScannerBackgroundServiceRequest? request).ShouldBeTrue();
var command = request.ShouldBeOfType<SynchronizeEmbyCollections>();
command.EmbyMediaSourceId.ShouldBe(1);
command.ForceScan.ShouldBeTrue();
command.DeepScan.ShouldBeTrue();
}
private static void ShouldHaveActionRoute(string actionName, string httpMethod, string route)
{
MethodInfo action = typeof(EmbyMediaSourcesController).GetMethod(actionName)
@@ -75,6 +75,10 @@ public class JellyfinMediaSourcesControllerTests
nameof(JellyfinMediaSourcesController.RefreshLibraries),
"POST",
"/api/media-sources/jellyfin/{id:int}/refresh-libraries");
ShouldHaveActionRoute(
nameof(JellyfinMediaSourcesController.ScanCollections),
"POST",
"/api/media-sources/jellyfin/{id:int}/scan-collections");
}
[Test]
@@ -414,6 +418,48 @@ public class JellyfinMediaSourcesControllerTests
request.ShouldBeOfType<SynchronizeJellyfinLibraries>().JellyfinMediaSourceId.ShouldBe(1);
}
[Test]
public async Task ScanCollections_Should_Return_404_When_Source_Missing()
{
_mediator.Send(Arg.Any<GetJellyfinMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(Option<JellyfinMediaSourceViewModel>.None);
IActionResult result = await _controller.ScanCollections(99, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<NotFoundObjectResult>();
_entityLocker.DidNotReceive().LockJellyfinCollections();
}
[Test]
public async Task ScanCollections_Should_Return_409_When_Collections_Locked()
{
_mediator.Send(Arg.Any<GetJellyfinMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(Option<JellyfinMediaSourceViewModel>.Some(new JellyfinMediaSourceViewModel(1, "s", "a")));
_entityLocker.LockJellyfinCollections().Returns(false);
IActionResult result = await _controller.ScanCollections(1, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<ConflictObjectResult>().Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(409);
_scannerChannel.Reader.TryRead(out _).ShouldBeFalse();
}
[Test]
public async Task ScanCollections_Should_Enqueue_And_Return_202()
{
_mediator.Send(Arg.Any<GetJellyfinMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(Option<JellyfinMediaSourceViewModel>.Some(new JellyfinMediaSourceViewModel(1, "s", "a")));
_entityLocker.LockJellyfinCollections().Returns(true);
IActionResult result = await _controller.ScanCollections(1, deep: true, CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
_scannerChannel.Reader.TryRead(out IScannerBackgroundServiceRequest? request).ShouldBeTrue();
var command = request.ShouldBeOfType<SynchronizeJellyfinCollections>();
command.JellyfinMediaSourceId.ShouldBe(1);
command.ForceScan.ShouldBeTrue();
command.DeepScan.ShouldBeTrue();
}
private static void ShouldHaveActionRoute(string actionName, string httpMethod, string route)
{
MethodInfo action = typeof(JellyfinMediaSourcesController).GetMethod(actionName)
@@ -71,14 +71,15 @@ public class LibrariesControllerTests
}
[Test]
public async Task ScanShow_Should_Queue_Scan_By_Show_Id_When_Show_Belongs_To_Library()
public async Task ScanShow_Should_Return_202_And_Queue_Scan_By_Show_Id_When_Show_Belongs_To_Library()
{
_televisionRepository.GetShowTitle(3, 42).Returns(Option<string>.Some("The Office"));
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>()).Returns(true);
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueShowScanResult.Queued);
IActionResult result = await _controller.ScanShow(3, new ScanShowRequest(42, DeepScan: true));
result.ShouldBeOfType<OkResult>();
result.ShouldBeOfType<AcceptedResult>();
await _mediator.Received(1).Send(
Arg.Is<QueueShowScanByLibraryId>(r =>
r.LibraryId == 3 && r.ShowId == 42 && r.ShowTitle == "The Office" && r.DeepScan),
@@ -86,14 +87,68 @@ public class LibrariesControllerTests
}
[Test]
public async Task ScanShow_Should_Return_BadRequest_When_Mediator_Fails_To_Queue()
public async Task ScanShow_Should_Return_409_When_AlreadyScanning()
{
_televisionRepository.GetShowTitle(3, 42).Returns(Option<string>.Some("The Office"));
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>()).Returns(false);
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueShowScanResult.AlreadyScanning);
IActionResult result = await _controller.ScanShow(3, new ScanShowRequest(42));
result.ShouldBeOfType<BadRequestObjectResult>();
var conflict = result.ShouldBeOfType<ConflictObjectResult>();
conflict.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status409Conflict);
}
[Test]
public async Task ScanShow_Should_Return_422_When_SyncDisabled()
{
_televisionRepository.GetShowTitle(3, 42).Returns(Option<string>.Some("The Office"));
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueShowScanResult.SyncDisabled);
IActionResult result = await _controller.ScanShow(3, new ScanShowRequest(42));
var unprocessable = result.ShouldBeOfType<UnprocessableEntityObjectResult>();
unprocessable.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status422UnprocessableEntity);
}
[Test]
public async Task ScanShow_Should_Return_422_When_Unsupported()
{
_televisionRepository.GetShowTitle(3, 42).Returns(Option<string>.Some("The Office"));
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueShowScanResult.Unsupported);
IActionResult result = await _controller.ScanShow(3, new ScanShowRequest(42));
var unprocessable = result.ShouldBeOfType<UnprocessableEntityObjectResult>();
unprocessable.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status422UnprocessableEntity);
}
[Test]
public async Task ScanShow_Should_Return_422_When_ScanFailed()
{
_televisionRepository.GetShowTitle(3, 42).Returns(Option<string>.Some("The Office"));
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueShowScanResult.ScanFailed);
IActionResult result = await _controller.ScanShow(3, new ScanShowRequest(42));
var unprocessable = result.ShouldBeOfType<UnprocessableEntityObjectResult>();
unprocessable.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status422UnprocessableEntity);
}
[Test]
public async Task ScanShow_Should_Return_404_When_Handler_Reports_NotFound()
{
_televisionRepository.GetShowTitle(3, 42).Returns(Option<string>.Some("The Office"));
_mediator.Send(Arg.Any<QueueShowScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueShowScanResult.NotFound);
IActionResult result = await _controller.ScanShow(3, new ScanShowRequest(42));
var notFound = result.ShouldBeOfType<NotFoundObjectResult>();
notFound.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status404NotFound);
}
[Test]
@@ -102,11 +157,25 @@ public class LibrariesControllerTests
_mediator.Send(Arg.Any<QueueLibraryScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueLibraryScanResult.Queued);
IActionResult result = await _controller.ScanLibrary(7, CancellationToken.None);
IActionResult result = await _controller.ScanLibrary(7, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
await _mediator.Received(1).Send(
Arg.Is<QueueLibraryScanByLibraryId>(r => r.LibraryId == 7),
Arg.Is<QueueLibraryScanByLibraryId>(r => r.LibraryId == 7 && !r.DeepScan),
Arg.Any<CancellationToken>());
}
[Test]
public async Task ScanLibrary_Should_Pass_DeepScan_When_Deep_Query_True()
{
_mediator.Send(Arg.Any<QueueLibraryScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueLibraryScanResult.Queued);
IActionResult result = await _controller.ScanLibrary(7, deep: true, CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
await _mediator.Received(1).Send(
Arg.Is<QueueLibraryScanByLibraryId>(r => r.LibraryId == 7 && r.DeepScan),
Arg.Any<CancellationToken>());
}
@@ -116,7 +185,7 @@ public class LibrariesControllerTests
_mediator.Send(Arg.Any<QueueLibraryScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueLibraryScanResult.NotFound);
IActionResult result = await _controller.ScanLibrary(7, CancellationToken.None);
IActionResult result = await _controller.ScanLibrary(7, cancellationToken: CancellationToken.None);
var notFound = result.ShouldBeOfType<NotFoundObjectResult>();
notFound.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status404NotFound);
@@ -128,7 +197,7 @@ public class LibrariesControllerTests
_mediator.Send(Arg.Any<QueueLibraryScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueLibraryScanResult.AlreadyScanning);
IActionResult result = await _controller.ScanLibrary(7, CancellationToken.None);
IActionResult result = await _controller.ScanLibrary(7, cancellationToken: CancellationToken.None);
var conflict = result.ShouldBeOfType<ConflictObjectResult>();
conflict.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status409Conflict);
@@ -140,7 +209,7 @@ public class LibrariesControllerTests
_mediator.Send(Arg.Any<QueueLibraryScanByLibraryId>(), Arg.Any<CancellationToken>())
.Returns(QueueLibraryScanResult.SyncDisabled);
IActionResult result = await _controller.ScanLibrary(7, CancellationToken.None);
IActionResult result = await _controller.ScanLibrary(7, cancellationToken: CancellationToken.None);
var unprocessable = result.ShouldBeOfType<UnprocessableEntityObjectResult>();
unprocessable.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(StatusCodes.Status422UnprocessableEntity);
@@ -0,0 +1,67 @@
using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.Maintenance;
using ErsatzTV.Controllers.Api;
using ErsatzTV.Core;
using LanguageExt;
using MediatR;
using Microsoft.AspNetCore.Mvc;
using NSubstitute;
using NUnit.Framework;
using Shouldly;
using static LanguageExt.Prelude;
namespace ErsatzTV.Tests.Controllers;
[TestFixture]
public class MaintenanceControllerTests
{
private MaintenanceController _controller = null!;
private IMediator _mediator = null!;
private Channel<IBackgroundServiceRequest> _workerChannel = null!;
[SetUp]
public void SetUp()
{
_mediator = Substitute.For<IMediator>();
_workerChannel = Channel.CreateUnbounded<IBackgroundServiceRequest>();
_controller = new MaintenanceController(_mediator, _workerChannel.Writer);
}
[Test]
public async Task EmptyTrash_Should_Return_200_On_Success()
{
_mediator.Send(Arg.Any<EmptyTrash>())
.Returns(Right<BaseError, LanguageExt.Unit>(unit));
IActionResult result = await _controller.EmptyTrash();
result.ShouldBeOfType<OkResult>();
await _mediator.Received(1).Send(Arg.Any<EmptyTrash>());
}
[Test]
public async Task EmptyTrash_Should_Return_422_ProblemDetails_On_Error()
{
_mediator.Send(Arg.Any<EmptyTrash>())
.Returns(Left<BaseError, LanguageExt.Unit>(BaseError.New("Failed to empty trash")));
IActionResult result = await _controller.EmptyTrash();
var unprocessable = result.ShouldBeOfType<UnprocessableEntityObjectResult>();
var problem = unprocessable.Value.ShouldBeOfType<ProblemDetails>();
problem.Status.ShouldBe(422);
problem.Detail.ShouldBe("Failed to empty trash");
}
[Test]
public async Task CleanArtwork_Should_Return_202_And_Enqueue_DeleteOrphanedArtwork()
{
IActionResult result = await _controller.CleanArtwork(CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
_workerChannel.Reader.TryRead(out IBackgroundServiceRequest? enqueued).ShouldBeTrue();
enqueued.ShouldBeOfType<DeleteOrphanedArtwork>();
}
}
@@ -7,8 +7,10 @@ using ErsatzTV.Controllers.Api.Requests;
using ErsatzTV.Core;
using ErsatzTV.Core.Api.MediaCollections;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Errors;
using LanguageExt;
using MediatR;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Routing;
using NSubstitute;
@@ -26,7 +28,12 @@ public class PlaylistControllerTests
public void SetUp()
{
_mediator = Substitute.For<IMediator>();
_controller = new PlaylistController(_mediator);
_controller = new PlaylistController(_mediator)
{
// Provide a real HttpContext so the ETag/If-Match concurrency headers (#253) can be
// read from Request and written to Response.
ControllerContext = new ControllerContext { HttpContext = new DefaultHttpContext() }
};
}
private PlaylistController _controller = null!;
@@ -204,7 +211,7 @@ public class PlaylistControllerTests
public async Task GetById_Should_Return_200_For_Some()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
IActionResult result = await _controller.GetById(4, CancellationToken.None);
@@ -226,7 +233,7 @@ public class PlaylistControllerTests
public async Task GetItems_Should_Return_200_And_Flatten_Names()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
_mediator.Send(Arg.Any<GetPlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(new List<PlaylistItemViewModel>
{
@@ -280,11 +287,24 @@ public class PlaylistControllerTests
await _mediator.DidNotReceive().Send(Arg.Any<GetPlaylistItems>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task GetItems_Should_Set_ETag_From_Playlist_Version()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 9)));
_mediator.Send(Arg.Any<GetPlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(new List<PlaylistItemViewModel>());
await _controller.GetItems(4, CancellationToken.None);
_controller.Response.Headers.ETag.ToString().ShouldBe("\"9\"");
}
[Test]
public async Task Create_Should_Return_201_And_Map_Request()
{
_mediator.Send(Arg.Any<CreatePlaylist>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, PlaylistViewModel>(new PlaylistViewModel(9, 1, "Kids", false)));
.Returns(Right<BaseError, PlaylistViewModel>(new PlaylistViewModel(9, 1, "Kids", false, 1)));
IActionResult result = await _controller.Create(
new CreatePlaylistRequest(1, "Kids"),
@@ -313,8 +333,12 @@ public class PlaylistControllerTests
[Test]
public async Task Update_Should_Return_200_With_Items_And_Map_Request_By_Array_Order()
{
// Existence pre-check reads version 1; the post-save re-query reads the bumped version 2 —
// the response ETag must carry the refreshed value (issue #253).
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(
Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)),
Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 2)));
_mediator.Send(Arg.Any<ReplacePlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<PlaylistItemViewModel>>(new List<PlaylistItemViewModel>
{
@@ -331,6 +355,22 @@ public class PlaylistControllerTests
false,
true)
}));
_mediator.Send(Arg.Any<GetPlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(new List<PlaylistItemViewModel>
{
new(
100,
0,
CollectionType.Movie,
null,
null,
null,
new NamedMediaItemViewModel(55, "The Movie"),
PlaybackOrder.Shuffle,
null,
false,
true)
});
IActionResult result = await _controller.Update(
4,
@@ -346,6 +386,8 @@ public class PlaylistControllerTests
result.ShouldBeOfType<OkObjectResult>().Value.ShouldBeOfType<List<PlaylistItemResponseModel>>().Count
.ShouldBe(1);
// On success the response carries the refreshed playlist's ETag.
_controller.Response.Headers.ETag.ToString().ShouldBe("\"2\"");
await _mediator.Received(1).Send(
Arg.Is<ReplacePlaylistItems>(c =>
c.PlaylistId == 4 &&
@@ -358,6 +400,81 @@ public class PlaylistControllerTests
Arg.Any<CancellationToken>());
}
[Test]
public async Task Update_Should_Return_400_On_Malformed_If_Match()
{
_controller.Request.Headers.IfMatch = "not-an-etag";
IActionResult result = await _controller.Update(
4,
new ReplacePlaylistRequest("Kids", new List<PlaylistItemRequest>()),
CancellationToken.None);
result.ShouldBeOfType<BadRequestObjectResult>();
await _mediator.DidNotReceive().Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>());
await _mediator.DidNotReceive().Send(Arg.Any<ReplacePlaylistItems>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task Update_Should_Thread_If_Match_Version_Into_Command()
{
_controller.Request.Headers.IfMatch = "\"3\"";
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 3)));
_mediator.Send(Arg.Any<ReplacePlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<PlaylistItemViewModel>>(new List<PlaylistItemViewModel>()));
_mediator.Send(Arg.Any<GetPlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(new List<PlaylistItemViewModel>());
IActionResult result = await _controller.Update(
4,
new ReplacePlaylistRequest("Kids", new List<PlaylistItemRequest>()),
CancellationToken.None);
result.ShouldBeOfType<OkObjectResult>();
await _mediator.Received(1).Send(
Arg.Is<ReplacePlaylistItems>(c => c.ExpectedVersion == Option<int>.Some(3)),
Arg.Any<CancellationToken>());
}
[Test]
public async Task Update_Without_If_Match_Should_Force_Write()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
_mediator.Send(Arg.Any<ReplacePlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<PlaylistItemViewModel>>(new List<PlaylistItemViewModel>()));
_mediator.Send(Arg.Any<GetPlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(new List<PlaylistItemViewModel>());
await _controller.Update(
4,
new ReplacePlaylistRequest("Kids", new List<PlaylistItemRequest>()),
CancellationToken.None);
await _mediator.Received(1).Send(
Arg.Is<ReplacePlaylistItems>(c => c.ExpectedVersion == Option<int>.None),
Arg.Any<CancellationToken>());
}
[Test]
public async Task Update_Should_Return_412_On_Precondition_Failed()
{
_controller.Request.Headers.IfMatch = "\"2\"";
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 5)));
_mediator.Send(Arg.Any<ReplacePlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, List<PlaylistItemViewModel>>(new PreconditionFailedError("stale")));
IActionResult result = await _controller.Update(
4,
new ReplacePlaylistRequest("Kids", new List<PlaylistItemRequest>()),
CancellationToken.None);
var objectResult = result.ShouldBeOfType<ObjectResult>();
objectResult.StatusCode.ShouldBe(StatusCodes.Status412PreconditionFailed);
}
[Test]
public async Task Update_Should_Return_404_When_Playlist_Missing()
{
@@ -377,7 +494,7 @@ public class PlaylistControllerTests
public async Task Update_Should_Return_422_On_Validation_Error()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
_mediator.Send(Arg.Any<ReplacePlaylistItems>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, List<PlaylistItemViewModel>>(BaseError.New("bad item")));
@@ -393,7 +510,7 @@ public class PlaylistControllerTests
public async Task Update_Should_Return_422_On_System_Playlist_And_Not_Replace_Items()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "System", true)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "System", true, 1)));
IActionResult result = await _controller.Update(
4,
@@ -410,7 +527,7 @@ public class PlaylistControllerTests
public async Task Delete_Should_Return_204_On_Success()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
_mediator.Send(Arg.Any<DeletePlaylist>(), Arg.Any<CancellationToken>())
.Returns(Option<BaseError>.None);
@@ -438,7 +555,7 @@ public class PlaylistControllerTests
public async Task Delete_Should_Return_422_On_System_Playlist()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "System", true)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "System", true, 1)));
_mediator.Send(Arg.Any<DeletePlaylist>(), Arg.Any<CancellationToken>())
.Returns(Option<BaseError>.Some(BaseError.New("Cannot delete system (generated) playlist")));
@@ -451,7 +568,7 @@ public class PlaylistControllerTests
public async Task AddItems_Should_Return_204_And_Map_Request()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
_mediator.Send(Arg.Any<AddItemsToPlaylist>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, Unit>(Unit.Default));
@@ -488,7 +605,7 @@ public class PlaylistControllerTests
public async Task AddItems_Should_Return_422_On_System_Playlist()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "System", true)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "System", true, 1)));
_mediator.Send(Arg.Any<AddItemsToPlaylist>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, Unit>(BaseError.New("Cannot add items to system (generated) playlist")));
@@ -504,7 +621,7 @@ public class PlaylistControllerTests
public async Task AddItems_Should_Return_422_On_Validation_Error()
{
_mediator.Send(Arg.Any<GetPlaylistById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false)));
.Returns(Option<PlaylistViewModel>.Some(new PlaylistViewModel(4, 1, "Kids", false, 1)));
_mediator.Send(Arg.Any<AddItemsToPlaylist>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, Unit>(BaseError.New("Movie does not exist")));
@@ -532,6 +532,21 @@ public class PlayoutControllerTests
result.ShouldBeOfType<OkObjectResult>().Value.ShouldBe(ToResponse(vm));
}
[Test]
public async Task GetById_Should_Expose_IsLocked_From_EntityLocker()
{
PlayoutNameViewModel vm = MakePlayout(9);
_mediator.Send(Arg.Any<GetPlayoutById>(), Arg.Any<CancellationToken>())
.Returns(Option<PlayoutNameViewModel>.Some(vm));
_entityLocker.IsPlayoutLocked(9).Returns(true);
IActionResult result = await _controller.GetById(9, CancellationToken.None);
var body = result.ShouldBeOfType<OkObjectResult>().Value.ShouldBeOfType<PlayoutResponseModel>();
body.IsLocked.ShouldBeTrue();
body.ShouldBe(ToResponse(vm, isLocked: true));
}
[Test]
public async Task GetById_Should_Return_404_For_None_With_ProblemDetails()
{
@@ -698,9 +713,17 @@ public class PlayoutControllerTests
[Test]
public async Task ResetAll_Should_Return_202_And_Send_Command()
{
_mediator.Send(Arg.Any<ResetAllPlayouts>(), Arg.Any<CancellationToken>())
.Returns(new ResetAllPlayoutsResult([1, 2], [3], [4]));
IActionResult result = await _controller.ResetAll(CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
var accepted = result.ShouldBeOfType<AcceptedResult>();
accepted.StatusCode.ShouldBe(202);
var body = accepted.Value.ShouldBeOfType<ResetAllPlayoutsResponseModel>();
body.QueuedPlayoutIds.ShouldBe(new List<int> { 1, 2 });
body.SkippedLocked.ShouldBe(new List<int> { 3 });
body.SkippedUnsupported.ShouldBe(new List<int> { 4 });
await _mediator.Received(1).Send(Arg.Any<ResetAllPlayouts>(), Arg.Any<CancellationToken>());
}
@@ -1113,7 +1136,7 @@ public class PlayoutControllerTests
_mediator.Send(Arg.Any<GetAllTemplates>(), Arg.Any<CancellationToken>())
.Returns([MakeTemplateViewModel(7), MakeTemplateViewModel(8)]);
_mediator.Send(Arg.Any<GetDecoTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<DecoTemplateViewModel>.Some(new DecoTemplateViewModel(5, 1, "G", "DT")));
.Returns(Option<DecoTemplateViewModel>.Some(new DecoTemplateViewModel(5, 1, "G", "DT", 0)));
_mediator.Send(Arg.Any<ReplacePlayoutTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Option<BaseError>.None);
_mediator.Send(Arg.Any<GetPlayoutTemplates>(), Arg.Any<CancellationToken>())
@@ -1252,16 +1275,16 @@ public class PlayoutControllerTests
new(0, programScheduleId, [], [], [], false, 1, 1, null, 12, 31, null);
private static ProgramScheduleViewModel MakeScheduleVm(int id) =>
new(id, $"Schedule {id}", false, false, false, false, FixedStartTimeBehavior.Strict);
new(id, $"Schedule {id}", false, false, false, false, FixedStartTimeBehavior.Strict, 0);
private static TemplateViewModel MakeTemplateViewModel(int id) =>
new(id, 1, "Group", $"Template {id}");
new(id, 1, "Group", $"Template {id}", 0);
private static PlayoutTemplateViewModel MakeTemplateVm(int id, int index, int templateId, int? decoTemplateId) =>
new(
id,
new TemplateViewModel(templateId, 1, "Group", $"Template {templateId}"),
decoTemplateId is { } dtId ? new DecoTemplateViewModel(dtId, 1, "DGroup", $"Deco {dtId}") : null,
new TemplateViewModel(templateId, 1, "Group", $"Template {templateId}", 0),
decoTemplateId is { } dtId ? new DecoTemplateViewModel(dtId, 1, "DGroup", $"Deco {dtId}", 0) : null,
index,
[],
[],
@@ -1292,7 +1315,7 @@ public class PlayoutControllerTests
null,
0);
private static PlayoutResponseModel ToResponse(PlayoutNameViewModel vm) =>
private static PlayoutResponseModel ToResponse(PlayoutNameViewModel vm, bool isLocked = false) =>
PlayoutResponseModel.From(
vm.PlayoutId,
vm.ScheduleKind,
@@ -1309,7 +1332,8 @@ public class PlayoutControllerTests
vm.BuildStatus.Success,
vm.BuildStatus.Message),
vm.DecoId,
vm.DecoName);
vm.DecoName,
isLocked);
private static void ShouldHaveActionRoute(string actionName, string httpMethod, string route)
{
@@ -70,6 +70,10 @@ public class PlexMediaSourcesControllerTests
nameof(PlexMediaSourcesController.RefreshLibraries),
"POST",
"/api/media-sources/plex/{id:int}/refresh-libraries");
ShouldHaveActionRoute(
nameof(PlexMediaSourcesController.ScanCollections),
"POST",
"/api/media-sources/plex/{id:int}/scan-collections");
}
// ----- P1 GetState -----
@@ -452,6 +456,64 @@ public class PlexMediaSourcesControllerTests
Arg.Any<CancellationToken>());
}
// ----- P9 ScanCollections -----
[Test]
public async Task ScanCollections_Should_Return_404_When_Source_Missing()
{
SourceExists(false);
IActionResult result = await _controller.ScanCollections(9, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<NotFoundObjectResult>();
_entityLocker.DidNotReceive().LockPlexCollections();
await _channel.DidNotReceive().WriteAsync(
Arg.Any<IScannerBackgroundServiceRequest>(),
Arg.Any<CancellationToken>());
}
[Test]
public async Task ScanCollections_Should_Return_409_When_Collections_Locked()
{
SourceExists(true);
_entityLocker.LockPlexCollections().Returns(false);
IActionResult result = await _controller.ScanCollections(3, cancellationToken: CancellationToken.None);
result.ShouldBeOfType<ConflictObjectResult>().Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(409);
await _channel.DidNotReceive().WriteAsync(
Arg.Any<IScannerBackgroundServiceRequest>(),
Arg.Any<CancellationToken>());
}
[Test]
public async Task ScanCollections_Should_Return_202_And_Enqueue()
{
SourceExists(true);
_entityLocker.LockPlexCollections().Returns(true);
IActionResult result = await _controller.ScanCollections(3, deep: true, CancellationToken.None);
result.ShouldBeOfType<AcceptedResult>();
await _channel.Received(1).WriteAsync(
Arg.Is<SynchronizePlexCollections>(s => s.PlexMediaSourceId == 3 && s.ForceScan && s.DeepScan),
Arg.Any<CancellationToken>());
}
[Test]
public async Task ScanCollections_Should_Compensate_Unlock_When_Enqueue_Throws()
{
SourceExists(true);
_entityLocker.LockPlexCollections().Returns(true);
_channel.WriteAsync(Arg.Any<SynchronizePlexCollections>(), Arg.Any<CancellationToken>())
.Returns<ValueTask>(_ => throw new InvalidOperationException("channel closed"));
await Should.ThrowAsync<InvalidOperationException>(
() => _controller.ScanCollections(3, cancellationToken: CancellationToken.None));
_entityLocker.Received(1).UnlockPlexCollections();
}
private void SourceExists(bool exists) =>
_mediator.Send(Arg.Any<GetPlexMediaSourceById>(), Arg.Any<CancellationToken>())
.Returns(exists
@@ -10,6 +10,7 @@ using ErsatzTV.Core.Errors;
using ErsatzTV.Core.Scheduling;
using LanguageExt;
using MediatR;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Routing;
using NSubstitute;
@@ -30,7 +31,12 @@ public class ScheduleControllerTests
public void SetUp()
{
_mediator = Substitute.For<IMediator>();
_controller = new ScheduleController(_mediator);
_controller = new ScheduleController(_mediator)
{
// Provide a real HttpContext so the ETag/If-Match concurrency headers (#253) can be
// read from Request and written to Response.
ControllerContext = new ControllerContext { HttpContext = new DefaultHttpContext() }
};
}
[Test]
@@ -253,6 +259,10 @@ public class ScheduleControllerTests
List<ProgramScheduleItemViewModel> items = [MakeOneItem(21), MakeOneItem(22)];
_mediator.Send(Arg.Any<ReplaceProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, IEnumerable<ProgramScheduleItemViewModel>>(items));
_mediator.Send(Arg.Any<GetProgramScheduleById>(), Arg.Any<CancellationToken>())
.Returns(Option<ProgramScheduleViewModel>.Some(MakeSchedule(4, "Daily")));
_mediator.Send(Arg.Any<GetProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns(items);
IActionResult result = await _controller.ReplaceItems(
4,
@@ -271,6 +281,94 @@ public class ScheduleControllerTests
Arg.Any<CancellationToken>());
}
[Test]
public async Task GetItems_Should_Set_ETag_From_Schedule_Version()
{
var response = new ProgramScheduleItemsWithDurationViewModel([], null);
_mediator.Send(Arg.Any<GetProgramScheduleById>(), Arg.Any<CancellationToken>())
.Returns(Option<ProgramScheduleViewModel>.Some(MakeSchedule(4, "Daily", version: 9)));
_mediator.Send(Arg.Any<GetProgramScheduleItemsWithDurations>(), Arg.Any<CancellationToken>())
.Returns(response);
await _controller.GetItems(4, CancellationToken.None);
_controller.Response.Headers.ETag.ToString().ShouldBe("\"9\"");
}
[Test]
public async Task ReplaceItems_Should_Return_400_On_Malformed_If_Match()
{
_controller.Request.Headers.IfMatch = "not-an-etag";
IActionResult result = await _controller.ReplaceItems(
4,
new ReplaceScheduleItemsRequest([MakeItemRequest(PlayoutMode.One)]),
CancellationToken.None);
result.ShouldBeOfType<BadRequestObjectResult>();
await _mediator.DidNotReceive().Send(Arg.Any<ReplaceProgramScheduleItems>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task ReplaceItems_Should_Thread_If_Match_Version_Into_Command_And_Set_New_ETag()
{
_controller.Request.Headers.IfMatch = "\"3\"";
_mediator.Send(Arg.Any<ReplaceProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, IEnumerable<ProgramScheduleItemViewModel>>([MakeOneItem(21)]));
_mediator.Send(Arg.Any<GetProgramScheduleById>(), Arg.Any<CancellationToken>())
.Returns(Option<ProgramScheduleViewModel>.Some(MakeSchedule(4, "Daily", version: 4)));
_mediator.Send(Arg.Any<GetProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns([MakeOneItem(21)]);
IActionResult result = await _controller.ReplaceItems(
4,
new ReplaceScheduleItemsRequest([MakeItemRequest(PlayoutMode.One)]),
CancellationToken.None);
result.ShouldBeOfType<OkObjectResult>();
// On success the response carries the refreshed schedule's ETag.
_controller.Response.Headers.ETag.ToString().ShouldBe("\"4\"");
await _mediator.Received(1).Send(
Arg.Is<ReplaceProgramScheduleItems>(c => c.ExpectedVersion == Option<int>.Some(3)),
Arg.Any<CancellationToken>());
}
[Test]
public async Task ReplaceItems_Without_If_Match_Should_Force_Write()
{
_mediator.Send(Arg.Any<ReplaceProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, IEnumerable<ProgramScheduleItemViewModel>>([MakeOneItem(21)]));
_mediator.Send(Arg.Any<GetProgramScheduleById>(), Arg.Any<CancellationToken>())
.Returns(Option<ProgramScheduleViewModel>.Some(MakeSchedule(4, "Daily", version: 1)));
_mediator.Send(Arg.Any<GetProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns([MakeOneItem(21)]);
await _controller.ReplaceItems(
4,
new ReplaceScheduleItemsRequest([MakeItemRequest(PlayoutMode.One)]),
CancellationToken.None);
await _mediator.Received(1).Send(
Arg.Is<ReplaceProgramScheduleItems>(c => c.ExpectedVersion == Option<int>.None),
Arg.Any<CancellationToken>());
}
[Test]
public async Task ReplaceItems_Should_Return_412_On_Precondition_Failed()
{
_controller.Request.Headers.IfMatch = "\"2\"";
_mediator.Send(Arg.Any<ReplaceProgramScheduleItems>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, IEnumerable<ProgramScheduleItemViewModel>>(new PreconditionFailedError("stale")));
IActionResult result = await _controller.ReplaceItems(
4,
new ReplaceScheduleItemsRequest([MakeItemRequest(PlayoutMode.One)]),
CancellationToken.None);
var objectResult = result.ShouldBeOfType<ObjectResult>();
objectResult.StatusCode.ShouldBe(StatusCodes.Status412PreconditionFailed);
}
[Test]
public async Task DeleteItem_Should_Return_204_And_Map_Route_Ids()
{
@@ -343,8 +441,8 @@ public class ScheduleControllerTests
PreferredSubtitleLanguageCode: null,
SubtitleMode: null);
private static ProgramScheduleViewModel MakeSchedule(int id, string name) =>
new(id, name, true, true, false, false, FixedStartTimeBehavior.Flexible);
private static ProgramScheduleViewModel MakeSchedule(int id, string name, int version = 0) =>
new(id, name, true, true, false, false, FixedStartTimeBehavior.Flexible, version);
private static ProgramScheduleItemOneViewModel MakeOneItem(int id) =>
new(
@@ -4,8 +4,10 @@ using ErsatzTV.Controllers.Api;
using ErsatzTV.Controllers.Api.Requests;
using ErsatzTV.Core;
using ErsatzTV.Core.Api.Scheduling;
using ErsatzTV.Core.Errors;
using LanguageExt;
using MediatR;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Routing;
using NSubstitute;
@@ -25,7 +27,12 @@ public class TemplateControllerTests
public void SetUp()
{
_mediator = Substitute.For<IMediator>();
_controller = new TemplateController(_mediator);
_controller = new TemplateController(_mediator)
{
// Provide a real HttpContext so the ETag/If-Match concurrency headers (#253) can be
// read from Request and written to Response.
ControllerContext = new ControllerContext { HttpContext = new DefaultHttpContext() }
};
}
[Test]
@@ -248,12 +255,10 @@ public class TemplateControllerTests
_mediator.Send(Arg.Any<GetTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<TemplateViewModel>.Some(MakeTemplate(4, 7, "Morning")));
_mediator.Send(Arg.Any<ReplaceTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<TemplateItemViewModel>>([]));
.Returns(Right<BaseError, List<TemplateItemViewModel>>(
[MakeItem(10, "Cartoons", TimeSpan.FromHours(6), 60)]));
_mediator.Send(Arg.Any<GetTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<TemplateItemViewModel>
{
MakeItem(10, "Cartoons", TimeSpan.FromHours(6), 60)
});
.Returns([MakeItem(10, "Cartoons", TimeSpan.FromHours(6), 60)]);
IActionResult result = await _controller.Replace(
4,
@@ -305,7 +310,96 @@ public class TemplateControllerTests
CancellationToken.None);
result.ShouldBeOfType<UnprocessableEntityObjectResult>();
await _mediator.DidNotReceive().Send(Arg.Any<GetTemplateItems>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task GetItems_Should_Set_ETag_From_Template_Version()
{
_mediator.Send(Arg.Any<GetTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<TemplateViewModel>.Some(MakeTemplate(4, 2, "Morning", version: 9)));
_mediator.Send(Arg.Any<GetTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<TemplateItemViewModel>());
await _controller.GetItems(4, CancellationToken.None);
_controller.Response.Headers.ETag.ToString().ShouldBe("\"9\"");
}
[Test]
public async Task Replace_Should_Return_400_On_Malformed_If_Match()
{
_controller.Request.Headers.IfMatch = "not-an-etag";
IActionResult result = await _controller.Replace(
4,
new ReplaceTemplateRequest("Morning", []),
CancellationToken.None);
result.ShouldBeOfType<BadRequestObjectResult>();
await _mediator.DidNotReceive().Send(Arg.Any<GetTemplateById>(), Arg.Any<CancellationToken>());
await _mediator.DidNotReceive().Send(Arg.Any<ReplaceTemplateItems>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task Replace_Should_Thread_If_Match_Version_Into_Command()
{
_controller.Request.Headers.IfMatch = "\"3\"";
_mediator.Send(Arg.Any<GetTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<TemplateViewModel>.Some(MakeTemplate(4, 7, "Morning", version: 4)));
_mediator.Send(Arg.Any<ReplaceTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<TemplateItemViewModel>>([]));
_mediator.Send(Arg.Any<GetTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<TemplateItemViewModel>());
IActionResult result = await _controller.Replace(
4,
new ReplaceTemplateRequest("Morning", []),
CancellationToken.None);
result.ShouldBeOfType<OkObjectResult>();
// On success the response carries the refreshed template's ETag.
_controller.Response.Headers.ETag.ToString().ShouldBe("\"4\"");
await _mediator.Received(1).Send(
Arg.Is<ReplaceTemplateItems>(c => c.ExpectedVersion == Option<int>.Some(3)),
Arg.Any<CancellationToken>());
}
[Test]
public async Task Replace_Without_If_Match_Should_Force_Write()
{
_mediator.Send(Arg.Any<GetTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<TemplateViewModel>.Some(MakeTemplate(4, 7, "Morning")));
_mediator.Send(Arg.Any<ReplaceTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Right<BaseError, List<TemplateItemViewModel>>([]));
_mediator.Send(Arg.Any<GetTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(new List<TemplateItemViewModel>());
await _controller.Replace(
4,
new ReplaceTemplateRequest("Morning", []),
CancellationToken.None);
await _mediator.Received(1).Send(
Arg.Is<ReplaceTemplateItems>(c => c.ExpectedVersion == Option<int>.None),
Arg.Any<CancellationToken>());
}
[Test]
public async Task Replace_Should_Return_412_On_Precondition_Failed()
{
_controller.Request.Headers.IfMatch = "\"2\"";
_mediator.Send(Arg.Any<GetTemplateById>(), Arg.Any<CancellationToken>())
.Returns(Option<TemplateViewModel>.Some(MakeTemplate(4, 7, "Morning", version: 5)));
_mediator.Send(Arg.Any<ReplaceTemplateItems>(), Arg.Any<CancellationToken>())
.Returns(Left<BaseError, List<TemplateItemViewModel>>(new PreconditionFailedError("stale")));
IActionResult result = await _controller.Replace(
4,
new ReplaceTemplateRequest("Morning", []),
CancellationToken.None);
var objectResult = result.ShouldBeOfType<ObjectResult>();
objectResult.StatusCode.ShouldBe(StatusCodes.Status412PreconditionFailed);
}
[Test]
@@ -359,8 +453,8 @@ public class TemplateControllerTests
result.ShouldBeOfType<UnprocessableEntityObjectResult>();
}
private static TemplateViewModel MakeTemplate(int id, int groupId, string name) =>
new(id, groupId, "Group", name);
private static TemplateViewModel MakeTemplate(int id, int groupId, string name, int version = 1) =>
new(id, groupId, "Group", name, version);
private static TemplateItemViewModel MakeItem(int blockId, string blockName, TimeSpan startTime, int minutes)
{
@@ -12,6 +12,7 @@ using ErsatzTV.Controllers.Api.Requests;
using ErsatzTV.Core;
using ErsatzTV.Core.Api.Troubleshooting;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Interfaces.FFmpeg;
using ErsatzTV.Core.Interfaces.Locking;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Core.Interfaces.Troubleshooting;
@@ -274,6 +275,55 @@ public class TroubleshootControllerTests
.Send(Arg.Any<PrepareTroubleshootingPlayback>(), Arg.Any<CancellationToken>());
}
[Test]
public async Task TroubleshootPlayback_Should_Return_404_ProblemDetails_When_Prepare_Not_Found()
{
_entityLocker.IsTroubleshootingPlaybackLocked().Returns(false);
_mediator.Send(Arg.Any<PrepareTroubleshootingPlayback>(), Arg.Any<CancellationToken>())
.Returns(Either<BaseError, PlayoutItemResult>.Left(
new ErsatzTV.Core.Errors.NotFoundError("no such media item")));
IActionResult result = await _controller.TroubleshootPlayback(
mediaItem: 999,
channel: 0,
ffmpegProfile: 1,
StreamingMode.HttpLiveStreamingSegmenter,
watermark: [],
graphicsElement: [],
streamSelector: string.Empty,
subtitleId: null,
seekSeconds: 0,
start: null,
CancellationToken.None);
var notFound = result.ShouldBeOfType<NotFoundObjectResult>();
notFound.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(404);
}
[Test]
public async Task TroubleshootPlayback_Should_Return_422_ProblemDetails_When_Prepare_Fails_Validation()
{
_entityLocker.IsTroubleshootingPlaybackLocked().Returns(false);
_mediator.Send(Arg.Any<PrepareTroubleshootingPlayback>(), Arg.Any<CancellationToken>())
.Returns(Either<BaseError, PlayoutItemResult>.Left(BaseError.New("unable to prepare")));
IActionResult result = await _controller.TroubleshootPlayback(
mediaItem: 1,
channel: 0,
ffmpegProfile: 1,
StreamingMode.HttpLiveStreamingSegmenter,
watermark: [],
graphicsElement: [],
streamSelector: string.Empty,
subtitleId: null,
seekSeconds: 0,
start: null,
CancellationToken.None);
var unprocessable = result.ShouldBeOfType<UnprocessableEntityObjectResult>();
unprocessable.Value.ShouldBeOfType<ProblemDetails>().Status.ShouldBe(422);
}
[Test]
public async Task GetPlaybackStatus_Should_Report_Idle_When_No_Result_And_Unlocked()
{
@@ -0,0 +1,160 @@
using System.Reflection;
using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.Emby;
using ErsatzTV.Application.Jellyfin;
using ErsatzTV.Application.Plex;
using ErsatzTV.Core;
using ErsatzTV.Core.Interfaces.Locking;
using ErsatzTV.Infrastructure.Locking;
using ErsatzTV.Services;
using LanguageExt;
using MediatR;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using NUnit.Framework;
using Shouldly;
namespace ErsatzTV.Tests.Services;
/// <summary>
/// Regression net for the #250 cross-release bug on the per-provider collections lock (#235):
/// a scheduler-enqueued collection scan running with <c>Unlock: false</c> must NOT release a
/// collections lock owned by another party (an in-flight API scan), while <c>Unlock: true</c>
/// (an API request or the last message of a scheduler batch) must release on completion.
/// </summary>
[TestFixture]
public class ScannerServiceCollectionLockTests
{
[Test]
public async Task Plex_UnlockFalse_DoesNotReleaseHeldLock()
{
(ScannerService service, EntityLocker locker) = BuildService(
new SynchronizePlexCollections(1, false, false, Unlock: false));
// another party (an API scan) owns the collections lock
locker.LockPlexCollections().ShouldBeTrue();
await RunToCompletion(service);
locker.ArePlexCollectionsLocked().ShouldBeTrue();
}
[Test]
public async Task Plex_UnlockTrue_ReleasesHeldLock()
{
(ScannerService service, EntityLocker locker) = BuildService(
new SynchronizePlexCollections(1, false, false, Unlock: true));
locker.LockPlexCollections().ShouldBeTrue();
await RunToCompletion(service);
locker.ArePlexCollectionsLocked().ShouldBeFalse();
}
[Test]
public async Task Jellyfin_UnlockFalse_DoesNotReleaseHeldLock()
{
(ScannerService service, EntityLocker locker) = BuildService(
new SynchronizeJellyfinCollections(1, false, false, Unlock: false));
locker.LockJellyfinCollections().ShouldBeTrue();
await RunToCompletion(service);
locker.AreJellyfinCollectionsLocked().ShouldBeTrue();
}
[Test]
public async Task Jellyfin_UnlockTrue_ReleasesHeldLock()
{
(ScannerService service, EntityLocker locker) = BuildService(
new SynchronizeJellyfinCollections(1, false, false, Unlock: true));
locker.LockJellyfinCollections().ShouldBeTrue();
await RunToCompletion(service);
locker.AreJellyfinCollectionsLocked().ShouldBeFalse();
}
[Test]
public async Task Emby_UnlockFalse_DoesNotReleaseHeldLock()
{
(ScannerService service, EntityLocker locker) = BuildService(
new SynchronizeEmbyCollections(1, false, false, Unlock: false));
locker.LockEmbyCollections().ShouldBeTrue();
await RunToCompletion(service);
locker.AreEmbyCollectionsLocked().ShouldBeTrue();
}
[Test]
public async Task Emby_UnlockTrue_ReleasesHeldLock()
{
(ScannerService service, EntityLocker locker) = BuildService(
new SynchronizeEmbyCollections(1, false, false, Unlock: true));
locker.LockEmbyCollections().ShouldBeTrue();
await RunToCompletion(service);
locker.AreEmbyCollectionsLocked().ShouldBeFalse();
}
private static (ScannerService, EntityLocker) BuildService(IScannerBackgroundServiceRequest request)
{
var mediator = Substitute.For<IMediator>();
// every collection sync request returns success; the finally is what we're exercising
Either<BaseError, LanguageExt.Unit> ok = LanguageExt.Unit.Default;
mediator.Send(Arg.Any<SynchronizePlexCollections>(), Arg.Any<CancellationToken>())
.Returns(ok);
mediator.Send(Arg.Any<SynchronizeJellyfinCollections>(), Arg.Any<CancellationToken>())
.Returns(ok);
mediator.Send(Arg.Any<SynchronizeEmbyCollections>(), Arg.Any<CancellationToken>())
.Returns(ok);
var locker = new EntityLocker(mediator, NullLogger<EntityLocker>.Instance);
var provider = Substitute.For<IServiceProvider>();
provider.GetService(typeof(IMediator)).Returns(mediator);
provider.GetService(typeof(IEntityLocker)).Returns(locker);
var scope = Substitute.For<IServiceScope>();
scope.ServiceProvider.Returns(provider);
var scopeFactory = Substitute.For<IServiceScopeFactory>();
scopeFactory.CreateScope().Returns(scope);
var channel = Channel.CreateUnbounded<IScannerBackgroundServiceRequest>();
channel.Writer.TryWrite(request).ShouldBeTrue();
channel.Writer.Complete();
var startup = new SystemStartup();
startup.DatabaseIsReady();
startup.SearchIndexIsReady();
var service = new ScannerService(
channel.Reader,
scopeFactory,
startup,
NullLogger<ScannerService>.Instance);
return (service, locker);
}
private static async Task RunToCompletion(ScannerService service)
{
MethodInfo executeAsync = typeof(ScannerService)
.GetMethod("ExecuteAsync", BindingFlags.NonPublic | BindingFlags.Instance)!;
// the channel writer is already completed, so the read loop drains the one queued
// request, runs its finally, then ExecuteAsync returns
var task = (Task)executeAsync.Invoke(service, [CancellationToken.None])!;
await task.WaitAsync(TimeSpan.FromSeconds(10));
}
}
@@ -0,0 +1,150 @@
using System.Reflection;
using System.Threading.Channels;
using SysChannels = System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.Plex;
using ErsatzTV.Core;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Interfaces.Locking;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Services;
using ErsatzTV.Tests.Support;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using NUnit.Framework;
using Shouldly;
namespace ErsatzTV.Tests.Services;
/// <summary>
/// Verifies the scheduler's lock-once-per-provider collection batch (#235): it acquires
/// <c>LockPlexCollections()</c> exactly once, and when the slot is already held (an API scan or a
/// prior tick) it SKIPS the collection enqueue entirely rather than enqueuing an unlocked scan
/// that would cross-release the holder's lock (#250). When it does acquire, only the LAST message
/// carries the release (<c>Unlock: true</c>).
/// </summary>
[TestFixture]
public class SchedulerServiceCollectionLockTests
{
private InMemoryTvContext _db;
[SetUp]
public async Task SetUp() => _db = await InMemoryTvContext.CreateAsync();
[TearDown]
public async Task TearDown() => await _db.DisposeAsync();
[Test]
public async Task Plex_SkipsCollectionEnqueue_WhenCollectionsLockAlreadyHeld()
{
await SeedPlexLibrary(id: 1, mediaSourceId: 7);
var locker = Substitute.For<IEntityLocker>();
// isolate the collection path: the library loop enqueues nothing but still records the source id
locker.LockLibrary(Arg.Any<int>()).Returns(false);
// the collections slot is already held by another party
locker.LockPlexCollections().Returns(false);
(SchedulerService service, SysChannels.Channel<IScannerBackgroundServiceRequest> scannerChannel) = BuildService(locker);
await InvokeScanPlex(service);
List<IScannerBackgroundServiceRequest> writes = await Drain(scannerChannel);
locker.Received(1).LockPlexCollections();
writes.OfType<SynchronizePlexCollections>().ShouldBeEmpty();
locker.DidNotReceive().UnlockPlexCollections();
}
[Test]
public async Task Plex_EnqueuesBatch_LastMessageOwnsRelease_WhenLockAcquired()
{
await SeedPlexLibrary(id: 1, mediaSourceId: 7);
await SeedPlexLibrary(id: 2, mediaSourceId: 8);
var locker = Substitute.For<IEntityLocker>();
locker.LockLibrary(Arg.Any<int>()).Returns(false);
locker.LockPlexCollections().Returns(true);
(SchedulerService service, SysChannels.Channel<IScannerBackgroundServiceRequest> scannerChannel) = BuildService(locker);
await InvokeScanPlex(service);
List<IScannerBackgroundServiceRequest> writes = await Drain(scannerChannel);
locker.Received(1).LockPlexCollections();
List<SynchronizePlexCollections> collectionScans = writes.OfType<SynchronizePlexCollections>().ToList();
collectionScans.Count.ShouldBe(2);
// exactly one message owns the single release, and it is the last one written
collectionScans.Count(m => m.Unlock).ShouldBe(1);
collectionScans.Last().Unlock.ShouldBeTrue();
collectionScans.First().Unlock.ShouldBeFalse();
// release is handed off to the last message; no compensating unlock on the happy path
locker.DidNotReceive().UnlockPlexCollections();
}
private async Task SeedPlexLibrary(int id, int mediaSourceId)
{
await using TvContext context = _db.CreateContext();
context.PlexLibraries.Add(
new PlexLibrary
{
Id = id,
Name = $"Plex {id}",
MediaKind = LibraryMediaKind.Movies,
MediaSourceId = mediaSourceId,
ShouldSyncItems = true,
Key = $"key-{id}"
});
await context.SaveChangesAsync();
}
private (SchedulerService, SysChannels.Channel<IScannerBackgroundServiceRequest>) BuildService(IEntityLocker locker)
{
var provider = Substitute.For<IServiceProvider>();
provider.GetService(typeof(TvContext)).Returns(_ => _db.CreateContext());
var scope = Substitute.For<IServiceScope>();
scope.ServiceProvider.Returns(provider);
var scopeFactory = Substitute.For<IServiceScopeFactory>();
scopeFactory.CreateScope().Returns(scope);
var workerChannel = SysChannels.Channel.CreateUnbounded<IBackgroundServiceRequest>();
var scannerChannel = SysChannels.Channel.CreateUnbounded<IScannerBackgroundServiceRequest>();
var startup = new SystemStartup();
var service = new SchedulerService(
scopeFactory,
workerChannel.Writer,
scannerChannel.Writer,
locker,
startup,
NullLogger<SchedulerService>.Instance);
return (service, scannerChannel);
}
private static async Task<List<IScannerBackgroundServiceRequest>> Drain(
SysChannels.Channel<IScannerBackgroundServiceRequest> channel)
{
channel.Writer.Complete();
var results = new List<IScannerBackgroundServiceRequest>();
await foreach (IScannerBackgroundServiceRequest request in channel.Reader.ReadAllAsync())
{
results.Add(request);
}
return results;
}
private static async Task InvokeScanPlex(SchedulerService service)
{
MethodInfo method = typeof(SchedulerService)
.GetMethod("ScanPlexMediaSources", BindingFlags.NonPublic | BindingFlags.Instance)!;
var task = (Task)method.Invoke(service, [CancellationToken.None])!;
await task.WaitAsync(TimeSpan.FromSeconds(10));
}
}
@@ -0,0 +1,101 @@
using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.MediaCollections;
using ErsatzTV.Core;
using ErsatzTV.Core.Interfaces.Locking;
using ErsatzTV.Services;
using LanguageExt;
using MediatR;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using NUnit.Framework;
using Shouldly;
using Unit = LanguageExt.Unit;
namespace ErsatzTV.Tests.Services;
[TestFixture]
public class WorkerServiceTests
{
// F7 regression (issue #235): the global Trakt lock is acquired by SchedulerService and released
// only when the *terminal* (Unlock: true) message of a batch is processed by WorkerService. If the
// worker stops before reaching that terminal message (shutdown break / channel completion /
// cancellation), the release never fires and the in-memory Trakt lock leaks for the life of the
// process. WorkerService must release a held Trakt lock as a compensating action on shutdown.
[Test]
public async Task Should_Release_Held_Trakt_Lock_When_Worker_Stops_Before_Terminal_Message()
{
var channel = Channel.CreateUnbounded<IBackgroundServiceRequest>();
// A Trakt batch: only the terminal message carries Unlock: true. If the worker never processes
// it, the handler-side UnlockTrakt() never runs.
AddTraktList nonTerminal = AddTraktList.Existing("user", "list-1", false);
AddTraktList terminal = AddTraktList.Existing("user", "list-2", true);
await channel.Writer.WriteAsync(nonTerminal);
await channel.Writer.WriteAsync(terminal);
// Stateful stand-in for the singleton EntityLocker: the lock starts held (a batch acquired it).
var traktLocked = 1;
var locker = Substitute.For<IEntityLocker>();
locker.IsTraktLocked().Returns(_ => Volatile.Read(ref traktLocked) == 1);
locker.UnlockTrakt().Returns(_ => Interlocked.Exchange(ref traktLocked, 0) == 1);
// Gate: processing the first (non-terminal) message parks on the stopping token, guaranteeing
// the worker never reaches the terminal (Unlock: true) message before it is stopped.
var firstSeen = new TaskCompletionSource();
var processed = new List<AddTraktList>();
var mediator = Substitute.For<IMediator>();
mediator.Send(Arg.Any<AddTraktList>(), Arg.Any<CancellationToken>())
.Returns(async call =>
{
lock (processed)
{
processed.Add(call.Arg<AddTraktList>());
}
firstSeen.TrySetResult();
// Block on the stopping token so the loop parks here until StopAsync cancels it.
await Task.Delay(Timeout.Infinite, call.Arg<CancellationToken>());
return (Either<BaseError, Unit>)Unit.Default;
});
var provider = Substitute.For<IServiceProvider>();
provider.GetService(typeof(IMediator)).Returns(mediator);
var scope = Substitute.For<IServiceScope>();
scope.ServiceProvider.Returns(provider);
var scopeFactory = Substitute.For<IServiceScopeFactory>();
scopeFactory.CreateScope().Returns(scope);
var worker = new WorkerService(
channel.Reader,
scopeFactory,
locker,
NullLogger<WorkerService>.Instance);
await worker.StartAsync(CancellationToken.None);
// Wait until the first message is actively being processed (parked on the stopping token).
await firstSeen.Task.WaitAsync(TimeSpan.FromSeconds(5));
// Shut the worker down: cancels the stopping token -> parked Delay throws -> loop breaks
// before the terminal message is ever processed.
await worker.StopAsync(CancellationToken.None);
// The compensating release must have fired even though the terminal message was never handled.
locker.IsTraktLocked().ShouldBeFalse();
locker.Received(1).UnlockTrakt();
// Prove the leak scenario is genuine: we stopped after the non-terminal message but before the
// terminal (Unlock: true) one, so the handler-side release could not have run.
List<AddTraktList> seen;
lock (processed)
{
seen = processed.ToList();
}
seen.ShouldContain(nonTerminal);
seen.ShouldNotContain(terminal);
}
}
@@ -211,7 +211,7 @@ public class ChannelController(
"progress) and all other playout kinds use Reset (rebuild from scratch), matching the Blazor UI. " +
"Pass mode to force a specific PlayoutBuildMode.")]
[EndpointGroupName("general")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
public async Task<IActionResult> ResetPlayout(
@@ -233,7 +233,7 @@ public class ChannelController(
PlayoutBuildMode buildMode = mode ?? await DefaultResetMode(playoutId, cancellationToken);
await workerChannel.WriteAsync(new BuildPlayout(playoutId, buildMode), cancellationToken);
return new OkResult();
return new AcceptedResult();
}
return ApiResults.NotFoundProblem();
@@ -143,6 +143,9 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
[HttpGet("/api/deco-templates/{id:int}/items")]
[Tags("DecoTemplates")]
[EndpointSummary("Get deco template items")]
[EndpointDescription(
"Returns the deco template's items and a strong ETag of the deco template's version. Pass that ETag " +
"back as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(List<DecoTemplateItemResponseModel>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -154,6 +157,9 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
return ApiResults.NotFoundProblem();
}
// The items GET returns children, not the root, so read the deco template's version for the ETag.
ConcurrencyHeaders.SetETag(Response, decoTemplate.Map(t => t.Version).IfNone(0));
List<DecoTemplateItemViewModel> items = await mediator.Send(new GetDecoTemplateItems(id), cancellationToken);
return new OkObjectResult(
items.OrderBy(i => i.StartTime.TimeOfDay).Map(ProjectToResponseModel).ToList());
@@ -164,16 +170,32 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
[EndpointSummary("Replace a deco template and its items")]
[EndpointDescription(
"Replaces the deco template's name and its full item list. Each item assigns a deco to a start/end time " +
"of day; an end time of 00:00:00 means the item runs to the end of the day. Items must not overlap.")]
"of day; an end time of 00:00:00 means the item runs to the end of the day. Items must not overlap. " +
"Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); " +
"a successful response carries the new ETag.")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(DecoTemplateWithItemsResponseModel), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> Replace(
int id,
[Required] [FromBody] ReplaceDecoTemplateRequest request,
CancellationToken cancellationToken)
{
IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
if (ifMatch.Kind is IfMatchKind.Malformed)
{
return new BadRequestObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status400BadRequest,
Title = "Invalid If-Match header",
Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
});
}
Option<DecoTemplateViewModel> maybeDecoTemplate =
await mediator.Send(new GetDecoTemplateById(id), cancellationToken);
if (maybeDecoTemplate.IsNone)
@@ -184,18 +206,27 @@ public class DecoTemplateController(IMediator mediator) : ControllerBase
int decoTemplateGroupId = maybeDecoTemplate.Map(t => t.DecoTemplateGroupId).IfNone(0);
Either<BaseError, List<DecoTemplateItemViewModel>> result =
await mediator.Send(request.ToCommand(decoTemplateGroupId, id), cancellationToken);
await mediator.Send(
request.ToCommand(decoTemplateGroupId, id, ifMatch.ExpectedVersion),
cancellationToken);
return await result.Match(
Left: error => Task.FromResult(error.ToErrorResult()),
Right: async _ =>
{
// Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
// the returned items (issue #253 fail-safe ordering; matches BlockController).
Option<DecoTemplateViewModel> refreshed =
await mediator.Send(new GetDecoTemplateById(id), cancellationToken);
List<DecoTemplateItemViewModel> items =
await mediator.Send(new GetDecoTemplateItems(id), cancellationToken);
return refreshed.Match(
Some: vm => (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items)),
Some: vm =>
{
// Return the new ETag so a same-tab second save doesn't 412 against its own write.
ConcurrencyHeaders.SetETag(Response, vm.Version);
return (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items));
},
None: () => ApiResults.NotFoundProblem());
});
}
@@ -278,6 +278,53 @@ public class EmbyMediaSourcesController(
return new AcceptedResult();
}
[HttpPost("/api/media-sources/emby/{id:int}/scan-collections", Name = "ScanEmbyCollections")]
[Tags("Emby")]
[EndpointSummary("Scan an Emby source's collections")]
[EndpointDescription(
"Queues a synchronization of the source's collections (fire-and-forget). Pass ?deep=true for a deep " +
"scan. Returns 409 while an Emby collections scan is already in progress.")]
[EndpointGroupName("general")]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
public async Task<IActionResult> ScanCollections(
int id,
[FromQuery] bool deep = false,
CancellationToken cancellationToken = default)
{
Option<EmbyMediaSourceViewModel> maybeSource =
await mediator.Send(new GetEmbyMediaSourceById(id), cancellationToken);
if (maybeSource.IsNone)
{
return ApiResults.NotFoundProblem();
}
// The collections lock IS the running scan (§3b): fail to acquire = a scan is already active → 409.
if (!entityLocker.LockEmbyCollections())
{
return ApiResults.ConflictProblem(
"Emby collections scan in progress",
"An Emby collections scan is already in progress; try again once it completes.");
}
try
{
await scannerWorkerChannel.WriteAsync(
new SynchronizeEmbyCollections(id, true, deep),
cancellationToken);
}
catch
{
// the scanner releases the lock when it processes the message; if the enqueue throws after we
// acquired the lock, release it here (EnqueueWithTraktLock compensating-unlock, §3b)
entityLocker.UnlockEmbyCollections();
throw;
}
return new AcceptedResult();
}
// §C7: LockLibrary then enqueue the sync pair; a throw from the enqueue compensates by unlocking
// (EnqueueWithTraktLock pattern) — a locked library is silently skipped (Blazor parity).
private async Task EnqueueLibrarySync(int sourceId, int libraryId, CancellationToken cancellationToken)
@@ -278,6 +278,53 @@ public class JellyfinMediaSourcesController(
return new AcceptedResult();
}
[HttpPost("/api/media-sources/jellyfin/{id:int}/scan-collections", Name = "ScanJellyfinCollections")]
[Tags("Jellyfin")]
[EndpointSummary("Scan a Jellyfin source's collections")]
[EndpointDescription(
"Queues a synchronization of the source's collections (fire-and-forget). Pass ?deep=true for a deep " +
"scan. Returns 409 while a Jellyfin collections scan is already in progress.")]
[EndpointGroupName("general")]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
public async Task<IActionResult> ScanCollections(
int id,
[FromQuery] bool deep = false,
CancellationToken cancellationToken = default)
{
Option<JellyfinMediaSourceViewModel> maybeSource =
await mediator.Send(new GetJellyfinMediaSourceById(id), cancellationToken);
if (maybeSource.IsNone)
{
return ApiResults.NotFoundProblem();
}
// The collections lock IS the running scan (§3b): fail to acquire = a scan is already active → 409.
if (!entityLocker.LockJellyfinCollections())
{
return ApiResults.ConflictProblem(
"Jellyfin collections scan in progress",
"A Jellyfin collections scan is already in progress; try again once it completes.");
}
try
{
await scannerWorkerChannel.WriteAsync(
new SynchronizeJellyfinCollections(id, true, deep),
cancellationToken);
}
catch
{
// the scanner releases the lock when it processes the message; if the enqueue throws after we
// acquired the lock, release it here (EnqueueWithTraktLock compensating-unlock, §3b)
entityLocker.UnlockJellyfinCollections();
throw;
}
return new AcceptedResult();
}
// §C7: LockLibrary then enqueue the sync pair; a throw from the enqueue compensates by unlocking
// (EnqueueWithTraktLock pattern) — a locked library is silently skipped (Blazor parity).
private async Task EnqueueLibrarySync(int sourceId, int libraryId, CancellationToken cancellationToken)
@@ -1,3 +1,4 @@
using System.Diagnostics;
using ErsatzTV.Application.Libraries;
using ErsatzTV.Core.Api.Libraries;
using ErsatzTV.Core.Interfaces.Repositories;
@@ -22,13 +23,18 @@ public class LibrariesController(ITelevisionRepository televisionRepository, IMe
[HttpPost("/api/libraries/{id:int}/scan")]
[Tags("Libraries")]
[EndpointSummary("Scan library")]
[EndpointDescription("Queues a scan of the whole library. Pass ?deep=true for a deep (metadata-refresh) scan.")]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> ScanLibrary(int id, CancellationToken cancellationToken)
public async Task<IActionResult> ScanLibrary(
int id,
[FromQuery] bool deep = false,
CancellationToken cancellationToken = default)
{
QueueLibraryScanResult result = await mediator.Send(new QueueLibraryScanByLibraryId(id), cancellationToken);
QueueLibraryScanResult result =
await mediator.Send(new QueueLibraryScanByLibraryId(id, deep), cancellationToken);
return result switch
{
QueueLibraryScanResult.Queued => new AcceptedResult(),
@@ -49,19 +55,48 @@ public class LibrariesController(ITelevisionRepository televisionRepository, IMe
[HttpPost("/api/libraries/{id:int}/scan-show")]
[Tags("Libraries")]
[EndpointSummary("Scan show")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> ScanShow(int id, [FromBody] ScanShowRequest request)
{
Option<string> maybeTitle = await televisionRepository.GetShowTitle(id, request.ShowId);
foreach (string title in maybeTitle)
{
bool result = await mediator.Send(new QueueShowScanByLibraryId(id, request.ShowId, title, request.DeepScan));
QueueShowScanResult result =
await mediator.Send(new QueueShowScanByLibraryId(id, request.ShowId, title, request.DeepScan));
return result
? new OkResult()
: new BadRequestObjectResult(new { error = "Unable to queue show scan. Library may not exist, may not support single show scanning, or may already be scanning." });
return result switch
{
QueueShowScanResult.Queued => new AcceptedResult(),
QueueShowScanResult.AlreadyScanning => ApiResults.ConflictProblem(
"Library scan in progress",
$"A scan for library {id} is already in progress; cannot scan an individual show."),
QueueShowScanResult.SyncDisabled => new UnprocessableEntityObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status422UnprocessableEntity,
Title = "Library sync is disabled",
Detail = $"Item sync is disabled for library {id}."
}),
QueueShowScanResult.Unsupported => new UnprocessableEntityObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status422UnprocessableEntity,
Title = "Single show scanning is not supported",
Detail = $"Library {id} does not support scanning an individual show."
}),
QueueShowScanResult.ScanFailed => new UnprocessableEntityObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status422UnprocessableEntity,
Title = "Unable to scan show",
Detail = $"The scan for show {request.ShowId} in library {id} could not be completed."
}),
QueueShowScanResult.NotFound => ApiResults.NotFoundProblem($"Library {id} does not exist."),
_ => throw new UnreachableException($"Unmapped QueueShowScanResult: {result}")
};
}
return ApiResults.NotFoundProblem($"Show {request.ShowId} does not exist in library {id}.");
@@ -2,6 +2,7 @@ using System.Threading.Channels;
using ErsatzTV.Application;
using ErsatzTV.Application.Maintenance;
using ErsatzTV.Core;
using ErsatzTV.Extensions;
using MediatR;
using Microsoft.AspNetCore.Mvc;
@@ -23,17 +24,14 @@ public class MaintenanceController(IMediator mediator, ChannelWriter<IBackground
[HttpPost("/api/maintenance/empty_trash")]
[Tags("Maintenance")]
[EndpointSummary("Empty trash")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> EmptyTrash()
{
Either<BaseError, Unit> result = await mediator.Send(new EmptyTrash());
foreach (BaseError error in result.LeftToSeq())
{
return new ContentResult
{
StatusCode = StatusCodes.Status500InternalServerError,
Content = error.ToString(),
ContentType = "text/plain"
};
return error.ToErrorResult();
}
return new OkResult();
@@ -42,9 +40,10 @@ public class MaintenanceController(IMediator mediator, ChannelWriter<IBackground
[HttpPost("/api/maintenance/clean_artwork")]
[Tags("Maintenance")]
[EndpointSummary("Clean artwork cache")]
[ProducesResponseType(StatusCodes.Status202Accepted)]
public async Task<IActionResult> CleanArtwork(CancellationToken cancellationToken)
{
await workerChannel.WriteAsync(new DeleteOrphanedArtwork(), cancellationToken);
return new OkResult();
return new AcceptedResult();
}
}
+43 -4
View File
@@ -134,6 +134,9 @@ public class PlaylistController(IMediator mediator) : ControllerBase
[HttpGet("/api/playlists/{id:int}/items", Name = "GetPlaylistItems")]
[Tags("Playlists")]
[EndpointSummary("Get the items in a playlist")]
[EndpointDescription(
"Returns the playlist's items and a strong ETag of the playlist's version. Pass that ETag back " +
"as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(List<PlaylistItemResponseModel>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -145,6 +148,9 @@ public class PlaylistController(IMediator mediator) : ControllerBase
return ApiResults.NotFoundProblem();
}
// The items GET returns children, not the root, so read the playlist's version for the ETag.
ConcurrencyHeaders.SetETag(Response, maybePlaylist.Map(p => p.Version).IfNone(0));
List<PlaylistItemViewModel> items = await mediator.Send(new GetPlaylistItems(id), cancellationToken);
return new OkObjectResult(items.Map(ProjectToItemResponse).ToList());
}
@@ -168,15 +174,33 @@ public class PlaylistController(IMediator mediator) : ControllerBase
[HttpPut("/api/playlists/{id:int}", Name = "UpdatePlaylist")]
[Tags("Playlists")]
[EndpointSummary("Update a playlist (rename and replace its items)")]
[EndpointDescription(
"Replaces the playlist's name and its full item list. Item indexes are assigned from the array " +
"order. Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 " +
"(issue #253); a successful response carries the new ETag.")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(List<PlaylistItemResponseModel>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> Update(
int id,
[Required] [FromBody] ReplacePlaylistRequest request,
CancellationToken cancellationToken)
{
IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
if (ifMatch.Kind is IfMatchKind.Malformed)
{
return new BadRequestObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status400BadRequest,
Title = "Invalid If-Match header",
Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
});
}
Option<PlaylistViewModel> maybePlaylist = await mediator.Send(new GetPlaylistById(id), cancellationToken);
if (maybePlaylist.IsNone)
{
@@ -195,10 +219,25 @@ public class PlaylistController(IMediator mediator) : ControllerBase
}
Either<BaseError, List<PlaylistItemViewModel>> result =
await mediator.Send(request.ToCommand(id), cancellationToken);
return result.Match(
Left: error => error.ToErrorResult(),
Right: items => (IActionResult)new OkObjectResult(items.Map(ProjectToItemResponse).ToList()));
await mediator.Send(request.ToCommand(id, ifMatch.ExpectedVersion), cancellationToken);
return await result.Match(
Left: error => Task.FromResult(error.ToErrorResult()),
Right: async _ =>
{
// Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
// the returned items (issue #253 fail-safe ordering; matches BlockController). A None root
// (deleted between commit and reload) is a 404, never a 200 without an ETag.
Option<PlaylistViewModel> refreshed =
await mediator.Send(new GetPlaylistById(id), cancellationToken);
List<PlaylistItemViewModel> items = await mediator.Send(new GetPlaylistItems(id), cancellationToken);
return refreshed.Match(
Some: vm =>
{
ConcurrencyHeaders.SetETag(Response, vm.Version);
return (IActionResult)new OkObjectResult(items.Map(ProjectToItemResponse).ToList());
},
None: () => ApiResults.NotFoundProblem());
});
}
[HttpDelete("/api/playlists/{id:int}", Name = "DeletePlaylist")]
+19 -10
View File
@@ -69,7 +69,7 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
{
Option<PlayoutNameViewModel> result = await mediator.Send(new GetPlayoutById(id), cancellationToken);
return result.Map(ToResponse).ToGetResult();
return result.Map(vm => ToResponse(vm, entityLocker.IsPlayoutLocked(id))).ToGetResult();
}
[HttpGet("/api/playouts/{id:int}/items", Name = "GetPlayoutItems")]
@@ -128,7 +128,9 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
Option<PlayoutNameViewModel> playout =
await mediator.Send(new GetPlayoutById(created.PlayoutId), cancellationToken);
return playout.Match(
Some: vm => (IActionResult)new CreatedResult($"/api/playouts/{vm.PlayoutId}", ToResponse(vm)),
Some: vm => (IActionResult)new CreatedResult(
$"/api/playouts/{vm.PlayoutId}",
ToResponse(vm, entityLocker.IsPlayoutLocked(vm.PlayoutId))),
None: () => ApiResults.NotFoundProblem());
});
});
@@ -194,7 +196,8 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
return result.Match(
Left: error => error.ToErrorResult(),
Right: playout => (IActionResult)new OkObjectResult(ToResponse(playout)));
Right: playout => (IActionResult)new OkObjectResult(
ToResponse(playout, entityLocker.IsPlayoutLocked(id))));
}
private async Task<Either<BaseError, PlayoutNameViewModel>> UpdateScheduleFile(
@@ -260,7 +263,7 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
Option<PlayoutNameViewModel> refreshed = await mediator.Send(new GetPlayoutById(id), cancellationToken);
return refreshed.Match(
Some: vm => (IActionResult)new OkObjectResult(ToResponse(vm)),
Some: vm => (IActionResult)new OkObjectResult(ToResponse(vm, entityLocker.IsPlayoutLocked(id))),
None: () => ApiResults.NotFoundProblem());
}
@@ -583,14 +586,19 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
[Tags("Playouts")]
[EndpointSummary("Reset all playouts")]
[EndpointGroupName("general")]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ResetAllPlayoutsResponseModel), StatusCodes.Status202Accepted)]
// No 409 lock guard here (unlike the id-keyed mutations): ResetAllPlayoutsHandler already
// skips any playout whose build lock is held, matching Blazor. It is a fire-and-forget
// bulk enqueue, so it always accepts. See docs/decisions.md 2026-07-10.
// bulk enqueue, so it always accepts — the 202 body reports which playouts were queued and
// which were skipped (locked, or an unsupported ExternalJson/None kind). See docs/decisions.md 2026-07-10.
public async Task<IActionResult> ResetAll(CancellationToken cancellationToken)
{
await mediator.Send(new ResetAllPlayouts(), cancellationToken);
return Accepted();
ResetAllPlayoutsResult result = await mediator.Send(new ResetAllPlayouts(), cancellationToken);
var body = new ResetAllPlayoutsResponseModel(
result.QueuedPlayoutIds,
result.SkippedLocked,
result.SkippedUnsupported);
return new AcceptedResult((string)null, body);
}
[HttpPost("/api/playouts/{id:int}/erase-items", Name = "ErasePlayoutItems")]
@@ -761,7 +769,7 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
private static PlayoutHistoryDetailsResponseModel ToDetailsResponse(PlayoutHistoryDetailsViewModel vm) =>
new(vm.PlaybackOrder, vm.CollectionType, vm.Name, vm.MediaItemType, vm.MediaItemTitle);
private static PlayoutResponseModel ToResponse(PlayoutNameViewModel vm) =>
private static PlayoutResponseModel ToResponse(PlayoutNameViewModel vm, bool isLocked) =>
PlayoutResponseModel.From(
vm.PlayoutId,
vm.ScheduleKind,
@@ -773,7 +781,8 @@ public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) :
vm.DbDailyRebuildTime,
ToBuildStatus(vm.BuildStatus),
vm.DecoId,
vm.DecoName);
vm.DecoName,
isLocked);
private static PlayoutAlternateScheduleResponseModel ToResponse(PlayoutAlternateScheduleViewModel vm) =>
new(
@@ -277,6 +277,51 @@ public class PlexMediaSourcesController(
return new AcceptedResult();
}
[HttpPost("/api/media-sources/plex/{id:int}/scan-collections", Name = "ScanPlexCollections")]
[Tags("Plex")]
[EndpointSummary("Scan a Plex server's collections")]
[EndpointDescription(
"Queues a synchronization of the server's collections (fire-and-forget). Pass ?deep=true for a deep " +
"scan. Returns 409 while a Plex collections scan is already in progress.")]
[EndpointGroupName("general")]
[ProducesResponseType(StatusCodes.Status202Accepted)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
public async Task<IActionResult> ScanCollections(
int id,
[FromQuery] bool deep = false,
CancellationToken cancellationToken = default)
{
if (!await PlexSourceExists(id, cancellationToken))
{
return ApiResults.NotFoundProblem();
}
// The collections lock IS the running scan (§3b): fail to acquire = a scan is already active → 409.
if (!entityLocker.LockPlexCollections())
{
return ApiResults.ConflictProblem(
"Plex collections scan in progress",
"A Plex collections scan is already in progress; try again once it completes.");
}
try
{
await scannerWorkerChannel.WriteAsync(
new SynchronizePlexCollections(id, true, deep),
cancellationToken);
}
catch
{
// the scanner releases the lock when it processes the message; if the enqueue throws after we
// acquired the lock, release it here (EnqueueWithTraktLock compensating-unlock, §3b)
entityLocker.UnlockPlexCollections();
throw;
}
return new AcceptedResult();
}
private async Task<bool> PlexSourceExists(int id, CancellationToken cancellationToken) =>
(await mediator.Send(new GetPlexMediaSourceById(id), cancellationToken)).IsSome;
@@ -4,10 +4,14 @@ namespace ErsatzTV.Controllers.Api.Requests;
public record ReplaceDecoTemplateRequest(string Name, List<DecoTemplateItemRequest> Items)
{
public ReplaceDecoTemplateItems ToCommand(int decoTemplateGroupId, int decoTemplateId) =>
public ReplaceDecoTemplateItems ToCommand(
int decoTemplateGroupId,
int decoTemplateId,
Option<int> expectedVersion = default) =>
new(
decoTemplateId,
decoTemplateGroupId,
Name,
(Items ?? []).Select(item => item.ToReplaceItem()).ToList());
(Items ?? []).Select(item => item.ToReplaceItem()).ToList(),
expectedVersion);
}
@@ -3,6 +3,7 @@ using System.Collections.Generic;
using System.Linq;
using ErsatzTV.Application.MediaCollections;
using ErsatzTV.Core.Domain;
using LanguageExt;
namespace ErsatzTV.Controllers.Api.Requests;
@@ -56,8 +57,8 @@ public record PlaylistItemRequest(
public record ReplacePlaylistRequest(string? Name, List<PlaylistItemRequest>? Items)
{
public ReplacePlaylistItems ToCommand(int id) =>
new(id, Name ?? string.Empty, BuildItems());
public ReplacePlaylistItems ToCommand(int id, Option<int> expectedVersion = default) =>
new(id, Name ?? string.Empty, BuildItems(), expectedVersion);
// Preview operates on the posted draft, so there is no persisted playlist id (0).
public ReplacePlaylistItems ToReplaceCommand() =>
@@ -4,8 +4,9 @@ namespace ErsatzTV.Controllers.Api.Requests;
public record ReplaceScheduleItemsRequest(List<ScheduleItemRequest> Items)
{
public ReplaceProgramScheduleItems ToCommand(int scheduleId) =>
public ReplaceProgramScheduleItems ToCommand(int scheduleId, Option<int> expectedVersion = default) =>
new(
scheduleId,
(Items ?? []).Select((item, index) => item.ToReplaceCommand(index)).ToList());
(Items ?? []).Select((item, index) => item.ToReplaceCommand(index)).ToList(),
expectedVersion);
}
@@ -4,10 +4,11 @@ namespace ErsatzTV.Controllers.Api.Requests;
public record ReplaceTemplateRequest(string Name, List<TemplateItemRequest> Items)
{
public ReplaceTemplateItems ToCommand(int templateGroupId, int templateId) =>
public ReplaceTemplateItems ToCommand(int templateGroupId, int templateId, Option<int> expectedVersion = default) =>
new(
templateGroupId,
templateId,
Name,
(Items ?? []).Select(item => item.ToReplaceItem()).ToList());
(Items ?? []).Select(item => item.ToReplaceItem()).ToList(),
expectedVersion);
}
+47 -5
View File
@@ -104,7 +104,9 @@ public class ScheduleController(IMediator mediator) : ControllerBase
[EndpointDescription(
"Returns the schedule's items plus a computed, best-effort runtime estimate: each item carries a " +
"nullable durationEstimate and the envelope carries a nullable totalDurationEstimate. Estimates are " +
"derived from referenced collection/media runtimes and are null when unbounded or unknown.")]
"derived from referenced collection/media runtimes and are null when unbounded or unknown. The " +
"response also carries a strong ETag of the schedule's version; pass that ETag back as If-Match on " +
"the replace (PUT) to detect a concurrent edit (issue #253).")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(ScheduleItemsResponseModel), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -116,6 +118,9 @@ public class ScheduleController(IMediator mediator) : ControllerBase
return ApiResults.NotFoundProblem();
}
// The items GET returns children, not the root, so read the schedule's version for the ETag.
ConcurrencyHeaders.SetETag(Response, schedule.Map(s => s.Version).IfNone(0));
ProgramScheduleItemsWithDurationViewModel items =
await mediator.Send(new GetProgramScheduleItemsWithDurations(id), cancellationToken);
return new OkObjectResult(ScheduleItemResponseMapper.ProjectToResponseModel(items));
@@ -143,20 +148,57 @@ public class ScheduleController(IMediator mediator) : ControllerBase
[HttpPut("/api/schedules/{id:int}/items")]
[Tags("Schedules")]
[EndpointSummary("Replace schedule items")]
[EndpointDescription(
"Replaces the schedule's full item list; item indexes are assigned from the array order. Send the " +
"ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); a successful " +
"response carries the new ETag.")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(List<ScheduleItemResponseModel>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> ReplaceItems(
int id,
[Required] [FromBody] ReplaceScheduleItemsRequest request,
CancellationToken cancellationToken)
{
IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
if (ifMatch.Kind is IfMatchKind.Malformed)
{
return new BadRequestObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status400BadRequest,
Title = "Invalid If-Match header",
Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
});
}
Either<BaseError, IEnumerable<ProgramScheduleItemViewModel>> result =
await mediator.Send(request.ToCommand(id), cancellationToken);
return result
.Map(items => items.Select(ScheduleItemResponseMapper.ProjectToResponseModel).ToList())
.ToUpdatedResult();
await mediator.Send(request.ToCommand(id, ifMatch.ExpectedVersion), cancellationToken);
return await result.Match(
Left: error => Task.FromResult(error.ToErrorResult()),
Right: async _ =>
{
// Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
// the returned items (issue #253 fail-safe ordering; matches BlockController). A None root
// (deleted between commit and reload) is a 404, never a 200 without an ETag.
Option<ProgramScheduleViewModel> refreshed =
await mediator.Send(new GetProgramScheduleById(id), cancellationToken);
List<ProgramScheduleItemViewModel> items =
await mediator.Send(new GetProgramScheduleItems(id), cancellationToken);
return refreshed.Match(
Some: vm =>
{
// Return the new ETag so a same-tab second save doesn't 412 against its own write.
ConcurrencyHeaders.SetETag(Response, vm.Version);
return (IActionResult)new OkObjectResult(
items.Select(ScheduleItemResponseMapper.ProjectToResponseModel).ToList());
},
None: () => ApiResults.NotFoundProblem());
});
}
[HttpDelete("/api/schedules/{id:int}/items/{itemId:int}")]
+34 -3
View File
@@ -134,6 +134,9 @@ public class TemplateController(IMediator mediator) : ControllerBase
[HttpGet("/api/templates/{id:int}/items")]
[Tags("Templates")]
[EndpointSummary("Get template items")]
[EndpointDescription(
"Returns the template's items and a strong ETag of the template's version. Pass that ETag back as " +
"If-Match on the replace (PUT) to detect a concurrent edit (issue #253).")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(List<TemplateItemResponseModel>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
@@ -145,6 +148,9 @@ public class TemplateController(IMediator mediator) : ControllerBase
return ApiResults.NotFoundProblem();
}
// The items GET returns children, not the root, so read the template's version for the ETag.
ConcurrencyHeaders.SetETag(Response, template.Map(t => t.Version).IfNone(0));
List<TemplateItemViewModel> items = await mediator.Send(new GetTemplateItems(id), cancellationToken);
return new OkObjectResult(
items.OrderBy(i => i.StartTime.TimeOfDay).Map(ProjectToResponseModel).ToList());
@@ -155,16 +161,32 @@ public class TemplateController(IMediator mediator) : ControllerBase
[EndpointSummary("Replace a template and its items")]
[EndpointDescription(
"Replaces the template's name and its full item list. Each item assigns a block to a start time of day; " +
"items must not overlap (an item's end time is its start time plus the assigned block's duration).")]
"items must not overlap (an item's end time is its start time plus the assigned block's duration). " +
"Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); " +
"a successful response carries the new ETag.")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(TemplateWithItemsResponseModel), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status412PreconditionFailed)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> Replace(
int id,
[Required] [FromBody] ReplaceTemplateRequest request,
CancellationToken cancellationToken)
{
IfMatchCondition ifMatch = ConcurrencyHeaders.ParseIfMatch(Request);
if (ifMatch.Kind is IfMatchKind.Malformed)
{
return new BadRequestObjectResult(
new ProblemDetails
{
Status = StatusCodes.Status400BadRequest,
Title = "Invalid If-Match header",
Detail = "If-Match must be a strong ETag of the resource version (e.g. \"3\") or \"*\"."
});
}
Option<TemplateViewModel> maybeTemplate = await mediator.Send(new GetTemplateById(id), cancellationToken);
if (maybeTemplate.IsNone)
{
@@ -174,16 +196,25 @@ public class TemplateController(IMediator mediator) : ControllerBase
int templateGroupId = maybeTemplate.Map(t => t.TemplateGroupId).IfNone(0);
Either<BaseError, List<TemplateItemViewModel>> result =
await mediator.Send(request.ToCommand(templateGroupId, id), cancellationToken);
await mediator.Send(request.ToCommand(templateGroupId, id, ifMatch.ExpectedVersion), cancellationToken);
return await result.Match(
Left: error => Task.FromResult(error.ToErrorResult()),
Right: async _ =>
{
// Reload the root (version) FIRST, then the items, so the emitted ETag is never newer than
// the returned items (issue #253 fail-safe ordering; matches BlockController). Returning the
// handler's item snapshot alongside a separately re-queried version could pair stale items
// with a newer ETag — a client would then silently overwrite the interleaving write.
Option<TemplateViewModel> refreshed = await mediator.Send(new GetTemplateById(id), cancellationToken);
List<TemplateItemViewModel> items = await mediator.Send(new GetTemplateItems(id), cancellationToken);
return refreshed.Match(
Some: vm => (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items)),
Some: vm =>
{
// Return the new ETag so a same-tab second save doesn't 412 against its own write.
ConcurrencyHeaders.SetETag(Response, vm.Version);
return (IActionResult)new OkObjectResult(ProjectToWithItemsResponseModel(vm, items));
},
None: () => ApiResults.NotFoundProblem());
});
}
@@ -114,7 +114,9 @@ public class TroubleshootController(
[Tags("Troubleshooting")]
[EndpointSummary("Start a troubleshooting playback session")]
[EndpointGroupName("general")]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
public async Task<IActionResult> TroubleshootPlayback(
[FromQuery]
int mediaItem,
@@ -174,9 +176,15 @@ public class TroubleshootController(
Optional(start)),
cancellationToken);
if (result.IsLeft)
// Distinguish "prepare failed" from the later "no playable output" fall-through: map the
// handler's BaseError through the standard helper (404 for NotFoundError — e.g. an unknown
// media item/channel — else 422 for a validation failure) with a ProblemDetails body,
// instead of a bare body-less 404. The SPA feeds this URL straight to hls.js (HlsPlayer)
// and never inspects the status code — failures surface via the /status poll — so the
// 404→422 split for validation errors is safe.
foreach (BaseError error in result.LeftToSeq())
{
return NotFound();
return error.ToErrorResult();
}
// Prepare returned a process, so the handler holds the troubleshooting lock now
@@ -273,7 +281,12 @@ public class TroubleshootController(
}
}
return NotFound();
// Terminal fall-through: Prepare succeeded but no playable output was produced (playback
// failed to start, was cancelled, or the segmenter never wrote segments). Keep the 404 status
// the SPA player already tolerates, but attach a distinguishing ProblemDetails body rather
// than a bare NotFound() so the response is self-describing.
return ApiResults.NotFoundProblem(
"Troubleshooting playback did not produce any output. It may have failed to start or been cancelled.");
}
[HttpHead("api/troubleshoot/playback/archive")]
+3 -2
View File
@@ -307,8 +307,9 @@
private async Task ScanShow(bool deepScan)
{
bool result = await Mediator.Send(new QueueShowScanByLibraryId(_show.LibraryId, _show.Id, _show.Title, deepScan));
if (!result)
QueueShowScanResult result =
await Mediator.Send(new QueueShowScanByLibraryId(_show.LibraryId, _show.Id, _show.Title, deepScan));
if (result != QueueShowScanResult.Queued)
{
Snackbar.Add($"Unable to scan show {_show.Title}", Severity.Error);
}
+11 -3
View File
@@ -221,7 +221,11 @@ public class ScannerService : BackgroundService
}
finally
{
if (entityLocker.ArePlexCollectionsLocked())
// request.Unlock is false when this collections scan is part of a scheduler-enqueued
// per-provider batch and a later message owns the single release (see #250 / #235).
// request.Unlock is false when this collections scan is part of a scheduler-enqueued
// per-provider batch and a later message owns the single release (see #250 / #235).
if (request.Unlock && entityLocker.ArePlexCollectionsLocked())
{
entityLocker.UnlockPlexCollections();
}
@@ -351,7 +355,9 @@ public class ScannerService : BackgroundService
}
finally
{
if (entityLocker.AreJellyfinCollectionsLocked())
// request.Unlock is false when this collections scan is part of a scheduler-enqueued
// per-provider batch and a later message owns the single release (see #250 / #235).
if (request.Unlock && entityLocker.AreJellyfinCollectionsLocked())
{
entityLocker.UnlockJellyfinCollections();
}
@@ -438,7 +444,9 @@ public class ScannerService : BackgroundService
}
finally
{
if (entityLocker.AreEmbyCollectionsLocked())
// request.Unlock is false when this collections scan is part of a scheduler-enqueued
// per-provider batch and a later message owns the single release (see #250 / #235).
if (request.Unlock && entityLocker.AreEmbyCollectionsLocked())
{
entityLocker.UnlockEmbyCollections();
}
+64 -12
View File
@@ -265,11 +265,35 @@ public class SchedulerService : BackgroundService
}
}
foreach (int mediaSourceId in mediaSourceIds)
// lock the collections slot once for the whole provider batch: the LAST message owns the
// single release (Unlock: true), the rest run Unlock: false. If the slot is already held
// (an API scan or a prior tick's batch is running/queued), skip enqueuing entirely - never
// enqueue unlocked, which would cross-release the holder's lock (#250). Skipping starves
// nothing: the next tick retries. (see #235)
// lock the collections slot once for the whole provider batch: the LAST message owns the
// single release (Unlock: true), the rest run Unlock: false. If the slot is already held
// (an API scan or a prior tick's batch is running/queued), skip enqueuing entirely - never
// enqueue unlocked, which would cross-release the holder's lock (#250). Skipping starves
// nothing: the next tick retries. (see #235)
var plexSourceIds = mediaSourceIds.ToList();
if (plexSourceIds.Count > 0 && _entityLocker.LockPlexCollections())
{
await _scannerWorkerChannel.WriteAsync(
new SynchronizePlexCollections(mediaSourceId, false, false),
cancellationToken);
try
{
for (var i = 0; i < plexSourceIds.Count; i++)
{
bool isLast = i == plexSourceIds.Count - 1;
await _scannerWorkerChannel.WriteAsync(
new SynchronizePlexCollections(plexSourceIds[i], false, false, Unlock: isLast),
cancellationToken);
}
}
catch
{
// an enqueue threw before the last (releasing) message went out - compensate here
_entityLocker.UnlockPlexCollections();
throw;
}
}
}
@@ -300,11 +324,25 @@ public class SchedulerService : BackgroundService
}
}
foreach (int mediaSourceId in mediaSourceIds)
// lock-once per provider batch; last message owns the release; skip entirely if held (#235/#250)
var jellyfinSourceIds = mediaSourceIds.ToList();
if (jellyfinSourceIds.Count > 0 && _entityLocker.LockJellyfinCollections())
{
await _scannerWorkerChannel.WriteAsync(
new SynchronizeJellyfinCollections(mediaSourceId, false, false),
cancellationToken);
try
{
for (var i = 0; i < jellyfinSourceIds.Count; i++)
{
bool isLast = i == jellyfinSourceIds.Count - 1;
await _scannerWorkerChannel.WriteAsync(
new SynchronizeJellyfinCollections(jellyfinSourceIds[i], false, false, Unlock: isLast),
cancellationToken);
}
}
catch
{
_entityLocker.UnlockJellyfinCollections();
throw;
}
}
}
@@ -335,11 +373,25 @@ public class SchedulerService : BackgroundService
}
}
foreach (int mediaSourceId in mediaSourceIds)
// lock-once per provider batch; last message owns the release; skip entirely if held (#235/#250)
var embySourceIds = mediaSourceIds.ToList();
if (embySourceIds.Count > 0 && _entityLocker.LockEmbyCollections())
{
await _scannerWorkerChannel.WriteAsync(
new SynchronizeEmbyCollections(mediaSourceId, false, false),
cancellationToken);
try
{
for (var i = 0; i < embySourceIds.Count; i++)
{
bool isLast = i == embySourceIds.Count - 1;
await _scannerWorkerChannel.WriteAsync(
new SynchronizeEmbyCollections(embySourceIds[i], false, false, Unlock: isLast),
cancellationToken);
}
}
catch
{
_entityLocker.UnlockEmbyCollections();
throw;
}
}
}
+18
View File
@@ -9,6 +9,7 @@ using ErsatzTV.Application.MediaCollections;
using ErsatzTV.Application.Playouts;
using ErsatzTV.Application.Subtitles;
using ErsatzTV.Core;
using ErsatzTV.Core.Interfaces.Locking;
using MediatR;
namespace ErsatzTV.Services;
@@ -16,16 +17,19 @@ namespace ErsatzTV.Services;
public class WorkerService : BackgroundService
{
private readonly ChannelReader<IBackgroundServiceRequest> _channel;
private readonly IEntityLocker _entityLocker;
private readonly ILogger<WorkerService> _logger;
private readonly IServiceScopeFactory _serviceScopeFactory;
public WorkerService(
ChannelReader<IBackgroundServiceRequest> channel,
IServiceScopeFactory serviceScopeFactory,
IEntityLocker entityLocker,
ILogger<WorkerService> logger)
{
_channel = channel;
_serviceScopeFactory = serviceScopeFactory;
_entityLocker = entityLocker;
_logger = logger;
}
@@ -143,5 +147,19 @@ public class WorkerService : BackgroundService
{
_logger.LogInformation("Worker service shutting down");
}
finally
{
// The global Trakt lock is acquired by SchedulerService/TraktController and released only
// when the *terminal* (Unlock: true) message of a batch is processed here. If this loop
// stops before reaching that message - shutdown break above, channel completion, or the
// reader throwing on cancellation - the release never fires and the in-memory Trakt lock
// leaks for the remaining life of the process (subsequent Trakt operations 409 forever).
// Make the batch-release loss-tolerant with a compensating release on worker shutdown.
if (_entityLocker.IsTraktLocked())
{
_logger.LogDebug("Releasing held Trakt lock during worker shutdown");
_entityLocker.UnlockTrakt();
}
}
}
}
+587 -14
View File
@@ -1863,8 +1863,8 @@
}
],
"responses": {
"200": {
"description": "OK"
"202": {
"description": "Accepted"
},
"404": {
"description": "Not Found",
@@ -4079,7 +4079,7 @@
"DecoTemplates"
],
"summary": "Replace a deco template and its items",
"description": "Replaces the deco template's name and its full item list. Each item assigns a deco to a start/end time of day; an end time of 00:00:00 means the item runs to the end of the day. Items must not overlap.",
"description": "Replaces the deco template's name and its full item list. Each item assigns a deco to a start/end time of day; an end time of 00:00:00 means the item runs to the end of the day. Items must not overlap. Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); a successful response carries the new ETag.",
"parameters": [
{
"name": "id",
@@ -4137,6 +4137,26 @@
}
}
},
"400": {
"description": "Bad Request",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
@@ -4157,6 +4177,26 @@
}
}
},
"412": {
"description": "Precondition Failed",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
@@ -4186,6 +4226,7 @@
"DecoTemplates"
],
"summary": "Get deco template items",
"description": "Returns the deco template's items and a strong ETag of the deco template's version. Pass that ETag back as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).",
"parameters": [
{
"name": "id",
@@ -4879,6 +4920,80 @@
}
}
},
"/api/media-sources/emby/{id}/scan-collections": {
"post": {
"tags": [
"Emby"
],
"summary": "Scan an Emby source's collections",
"description": "Queues a synchronization of the source's collections (fire-and-forget). Pass ?deep=true for a deep scan. Returns 409 while an Emby collections scan is already in progress.",
"operationId": "ScanEmbyCollections",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "deep",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not Found",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/ffmpeg/profiles": {
"get": {
"tags": [
@@ -6657,6 +6772,80 @@
}
}
},
"/api/media-sources/jellyfin/{id}/scan-collections": {
"post": {
"tags": [
"Jellyfin"
],
"summary": "Scan a Jellyfin source's collections",
"description": "Queues a synchronization of the source's collections (fire-and-forget). Pass ?deep=true for a deep scan. Returns 409 while a Jellyfin collections scan is already in progress.",
"operationId": "ScanJellyfinCollections",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "deep",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not Found",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/languages": {
"get": {
"tags": [
@@ -6743,6 +6932,7 @@
"Libraries"
],
"summary": "Scan library",
"description": "Queues a scan of the whole library. Pass ?deep=true for a deep (metadata-refresh) scan.",
"parameters": [
{
"name": "id",
@@ -6752,6 +6942,14 @@
"type": "integer",
"format": "int32"
}
},
{
"name": "deep",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
@@ -6864,8 +7062,8 @@
"required": true
},
"responses": {
"200": {
"description": "OK"
"202": {
"description": "Accepted"
},
"404": {
"description": "Not Found",
@@ -6887,8 +7085,28 @@
}
}
},
"400": {
"description": "Bad Request",
"409": {
"description": "Conflict",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"text/plain": {
"schema": {
@@ -7629,6 +7847,26 @@
"responses": {
"200": {
"description": "OK"
},
"422": {
"description": "Unprocessable Entity",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
@@ -7640,8 +7878,8 @@
],
"summary": "Clean artwork cache",
"responses": {
"200": {
"description": "OK"
"202": {
"description": "Accepted"
}
}
}
@@ -8784,6 +9022,7 @@
"Playlists"
],
"summary": "Update a playlist (rename and replace its items)",
"description": "Replaces the playlist's name and its full item list. Item indexes are assigned from the array order. Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); a successful response carries the new ETag.",
"operationId": "UpdatePlaylist",
"parameters": [
{
@@ -8851,6 +9090,26 @@
}
}
},
"400": {
"description": "Bad Request",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
@@ -8871,6 +9130,26 @@
}
}
},
"412": {
"description": "Precondition Failed",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
@@ -8963,6 +9242,7 @@
"Playlists"
],
"summary": "Get the items in a playlist",
"description": "Returns the playlist's items and a strong ETag of the playlist's version. Pass that ETag back as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).",
"operationId": "GetPlaylistItems",
"parameters": [
{
@@ -10659,7 +10939,24 @@
"operationId": "ResetAllPlayouts",
"responses": {
"202": {
"description": "Accepted"
"description": "Accepted",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ResetAllPlayoutsResponseModel"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResetAllPlayoutsResponseModel"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ResetAllPlayoutsResponseModel"
}
}
}
}
}
}
@@ -11476,6 +11773,80 @@
}
}
},
"/api/media-sources/plex/{id}/scan-collections": {
"post": {
"tags": [
"Plex"
],
"summary": "Scan a Plex server's collections",
"description": "Queues a synchronization of the server's collections (fire-and-forget). Pass ?deep=true for a deep scan. Returns 409 while a Plex collections scan is already in progress.",
"operationId": "ScanPlexCollections",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "deep",
"in": "query",
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not Found",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
},
"/api/rerun-collections": {
"get": {
"tags": [
@@ -12521,7 +12892,7 @@
"Schedules"
],
"summary": "Get schedule items",
"description": "Returns the schedule's items plus a computed, best-effort runtime estimate: each item carries a nullable durationEstimate and the envelope carries a nullable totalDurationEstimate. Estimates are derived from referenced collection/media runtimes and are null when unbounded or unknown.",
"description": "Returns the schedule's items plus a computed, best-effort runtime estimate: each item carries a nullable durationEstimate and the envelope carries a nullable totalDurationEstimate. Estimates are derived from referenced collection/media runtimes and are null when unbounded or unknown. The response also carries a strong ETag of the schedule's version; pass that ETag back as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).",
"parameters": [
{
"name": "id",
@@ -12685,6 +13056,7 @@
"Schedules"
],
"summary": "Replace schedule items",
"description": "Replaces the schedule's full item list; item indexes are assigned from the array order. Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); a successful response carries the new ETag.",
"parameters": [
{
"name": "id",
@@ -12751,6 +13123,26 @@
}
}
},
"400": {
"description": "Bad Request",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
@@ -12771,6 +13163,26 @@
}
}
},
"412": {
"description": "Precondition Failed",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
@@ -15156,7 +15568,7 @@
"Templates"
],
"summary": "Replace a template and its items",
"description": "Replaces the template's name and its full item list. Each item assigns a block to a start time of day; items must not overlap (an item's end time is its start time plus the assigned block's duration).",
"description": "Replaces the template's name and its full item list. Each item assigns a block to a start time of day; items must not overlap (an item's end time is its start time plus the assigned block's duration). Send the ETag from the items GET as If-Match to reject a stale overwrite with 412 (issue #253); a successful response carries the new ETag.",
"parameters": [
{
"name": "id",
@@ -15214,6 +15626,26 @@
}
}
},
"400": {
"description": "Bad Request",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
@@ -15234,6 +15666,26 @@
}
}
},
"412": {
"description": "Precondition Failed",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
@@ -15263,6 +15715,7 @@
"Templates"
],
"summary": "Get template items",
"description": "Returns the template's items and a strong ETag of the template's version. Pass that ETag back as If-Match on the replace (PUT) to detect a concurrent edit (issue #253).",
"parameters": [
{
"name": "id",
@@ -16087,6 +16540,26 @@
}
],
"responses": {
"404": {
"description": "Not Found",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
@@ -16106,6 +16579,26 @@
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
},
@@ -16201,6 +16694,26 @@
}
],
"responses": {
"404": {
"description": "Not Found",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
@@ -16220,6 +16733,26 @@
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
}
}
@@ -22779,7 +23312,8 @@
"dailyRebuildTime",
"buildStatus",
"decoId",
"decoName"
"decoName",
"isLocked"
],
"type": "object",
"properties": {
@@ -22837,6 +23371,9 @@
"null",
"string"
]
},
"isLocked": {
"type": "boolean"
}
}
},
@@ -23142,7 +23679,8 @@
"treatCollectionsAsShows",
"shuffleScheduleItems",
"randomStartPoint",
"fixedStartTimeBehavior"
"fixedStartTimeBehavior",
"version"
],
"type": "object",
"properties": {
@@ -23170,6 +23708,10 @@
},
"fixedStartTimeBehavior": {
"$ref": "#/components/schemas/FixedStartTimeBehavior"
},
"version": {
"type": "integer",
"format": "int32"
}
}
},
@@ -23668,6 +24210,37 @@
}
}
},
"ResetAllPlayoutsResponseModel": {
"required": [
"queuedPlayoutIds",
"skippedLocked",
"skippedUnsupported"
],
"type": "object",
"properties": {
"queuedPlayoutIds": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
},
"skippedLocked": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
},
"skippedUnsupported": {
"type": "array",
"items": {
"type": "integer",
"format": "int32"
}
}
}
},
"ResolutionResponseModel": {
"required": [
"id",
+37 -6
View File
@@ -112,12 +112,21 @@ Established by issue #215 (`PlayoutController` + `ChannelController.ResetPlayout
`[ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]` to each guarded
action. Precedent for the 409 shape: `TraktController` (its private `ConflictProblem()`). Two nuances:
- **Fire-and-forget bulk operations don't 409** — `POST /api/playouts/reset-all` stays 202; its
handler (`ResetAllPlayoutsHandler`) already *skips* locked playouts, matching Blazor + the handler
semantics. Only per-id mutations 409.
handler (`ResetAllPlayoutsHandler`) *skips* locked playouts, matching Blazor + the handler
semantics. Only per-id mutations 409. As of #235 the handler returns a `ResetAllPlayoutsResult`
(`QueuedPlayoutIds` / `SkippedLocked` / `SkippedUnsupported`) and the controller returns the 202
**with a `ResetAllPlayoutsResponseModel` body** reporting what was queued vs. skipped (locked, or
an unsupported `ExternalJson`/`None` kind) — a fire-and-forget bulk op still reports its outcome
rather than silently swallowing skips.
- **Surface the lock state to clients** so they can pre-disable the buttons: stamp an `IsLocked`
boolean onto the list DTO (`PlayoutListItemResponseModel`, set from `IsPlayoutLocked` in the
controller's list projection) rather than adding a push channel. The SPA reads it and, on a 409,
refreshes the list to pick up the flag.
controller's list projection) rather than adding a push channel — and (as of #235) onto the
single-playout GET DTO (`PlayoutResponseModel.IsLocked`, set the same way in every action that
maps it) so a client polling one playout has the same flag. The SPA reads it and, on a 409,
refreshes to pick up the flag.
- **Async-op success is 202, not 200** — an endpoint whose success path only *queues* a background
rebuild returns **202 Accepted**, not 200 (#235: `POST /api/channels/{channelNumber}/playout/reset`
queues a `BuildPlayout` → `AcceptedResult`). Reserve 200 for a synchronous durable result.
### 3b. Map a "queue a background job" outcome to status codes with an enum, not a `bool`
@@ -135,6 +144,15 @@ operation itself, not a mutation racing it). Add `[ProducesResponseType]` for 20
`EnqueueWithTraktLock` compensating-unlock pattern (`TraktController`): if a `WriteAsync` throws
after a successful `Lock*`, `Unlock*` in a `catch` and rethrow — one lock ⇄ exactly one release.
A second exemplar (issue #235 slice B), where the lock lives on the **controller** rather than in a
handler: `POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections?deep=` acquires the
per-source collections lock (`entityLocker.LockPlexCollections()` etc.) — the lock IS the running
collections scan, so a `false` = 409 — then `WriteAsync`es `Synchronize{X}Collections(id, ForceScan:
true, deep)` to the scanner channel and returns **202**. `ScannerService` releases that lock in a
`finally` when it processes the message; the controller compensating-unlocks in a `catch` if the
enqueue throws. `POST /api/libraries/{id}/scan?deep=` similarly threads an optional `[FromQuery] bool
deep` into `QueueLibraryScanByLibraryId(id, DeepScan)`.
`NotFoundError : BaseError` lives in `ErsatzTV.Core/Errors/NotFoundError.cs` — return it from a
handler's validation when a lookup fails, so the controller-side mapping falls out for free.
@@ -293,8 +311,21 @@ GET handlers that feed an ordered list must also `.OrderBy(i => i.Index)` — id
The replace-all aggregate PUTs (blocks, templates, schedules items, playlists, collections, playouts,
etc.) carry an **optimistic-concurrency contract** so a stale second tab can't silently overwrite a
fresher edit (issue #253). The Block endpoints are the reference implementation; PRs 2–4 fan the same
recipe across the other aggregates.
fresher edit (issue #253). The Block endpoints are the reference implementation; **PR2 fanned the same
recipe onto Template, DecoTemplate, Playlist, and schedule-items** (`PUT /api/templates/{id}`,
`/api/deco-templates/{id}`, `/api/playlists/{id}`, `/api/schedules/{id}/items`); PR3 covers the
Diff/Scalar aggregates (Collection, Playout ×2, MultiCollection, RerunCollection) and PR4 is the Phase-2
428 flip.
Each replace PUT keeps its **own** existing 200 body shape (Template/DecoTemplate return a
`…WithItemsResponseModel`, Block likewise; Playlist and schedule-items return the item array) and adds the
ETag as a **header only** — except schedules: `ScheduleController` returns the Application-layer
`ProgramScheduleViewModel` *directly* (no `ProgramScheduleResponseModel` exists), so the added
`int Version` also surfaces as a redundant `version` field in the `GET /api/schedules[/{id}]` bodies. That
is intentional and harmless (the ETag remains the authority); introducing a ResponseModel purely to hide
one field was judged disproportionate. Every replace PUT's *sibling config writers* bump `Version` too
(Playlist: the five `Add*ToPlaylist` handlers; schedule: `AddProgramScheduleItem` / `DeleteProgramScheduleItem`
/ `UpdateProgramSchedule`; Template/DecoTemplate have none).
**Token.** Each versioned root implements `IVersionedAggregate` (`int Version`, EF-mapped with
`.IsConcurrencyToken()` in its `IEntityTypeConfiguration`). A single dual-provider migration
+17 -5
View File
@@ -270,11 +270,23 @@ intentional exit ramp until phase (b) removes Blazor entirely.
## Section 5 — Removal execution runbook (#91 phase b, Step 2/3)
The removal PR is **gated** — it starts only after these clear: ~~#202 (media-source write API + SPA)~~
**DONE 2026-07-11**, #235 F9 (deep-scan + external-collections-scan API — no API today, so `Libraries.razor`
can't be deleted yet), and the **mandatory cold adversarial pass** (#91 comment 2026-07-09). (#204's id-carrying pattern
redirects landed 2026-07-11; its catch-all fallback that replaces `MapFallbackToPage("/_Host")` is folded
into Step 2 below, since it can only ship when `_Host` is deleted.) When those close, the removal-PR routine
executes, in order:
**DONE 2026-07-11**, ~~#235 F9 (deep-scan + external-collections-scan API)~~ **API DONE (#235 slice B)**:
`POST /api/libraries/{id}/scan?deep=` now threads deep-scan, and `POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections?deep=`
covers external-collections scan (the two `Libraries.razor` parity gaps) — the SPA `Libraries.razor` port can now
proceed, and the **mandatory cold adversarial pass** (#91 comment 2026-07-09). ~~**Remaining SPA affordance for
the removal PR**: `LibrariesScreen` exposes only quick-scan; add the **deep-scan** and **external-collections-scan**
buttons before deleting `Libraries.razor`.~~ **SPA affordance DONE 2026-07-11** (landed ahead of the removal PR
so the deletion diff stays pure): `LibrariesScreen` now wires the shipped `scanLibrary(id, deep)` +
`scanCollections(family, id, deep)` clients — a **Deep Scan Library** button on each remote library row and an
**External Collections** section (quick + deep per remote source), matching all four `Libraries.razor` scan actions.
The External Collections rows derive client-side from `getMediaSources()` (no new endpoint): the media-sources API
handler already filters each source's `libraries` to sync-enabled entries, so a remote source with a non-empty
`libraries` list is exactly `GetExternalCollections`'s `Libraries.Any(ShouldSyncItems)` filter. Collections scans
have no scan-status poll surface, so their button pending state is optimistic + timeout-bounded (follow-up #271: a
collections scan-status endpoint would let it reconcile like library scans). (#204's id-carrying
pattern redirects landed 2026-07-11; its catch-all fallback that replaces `MapFallbackToPage("/_Host")` is folded
into Step 2 below, since it can only ship when `_Host` is deleted.) With the SPA parity done, the removal PR's
remaining pre-work is just the **mandatory cold adversarial pass**; the runbook then executes, in order:
1. **Cut the rollback tag `blazor-final`** on the pre-deletion `main` commit — the *first* action, before
deleting anything. Exact command + restore path: `docs/decisions.md` 2026-07-11 "Pre-removal Blazor
+87
View File
@@ -650,6 +650,60 @@ action of the Step 2 deletion PR merge** (not before — `main` moves until then
Not cut this session — `main` still carries Blazor and will advance before the removal PR.
## 2026-07-11 — Async-op API contract normalization + playout build observability + F9 scan endpoints (#235)
Reviewer#20 F7/F8/F9. Normalizes the queue-triggering `/api/*` endpoints onto one contract, closes the two
F9 `Libraries.razor` parity gaps, and hardens the Trakt batch-lock lifecycle. Much of the F8 surface was
**already normalized** by #232 (library scan → `QueueLibraryScanResult` 202/404/409/422) and #215 (per-id
playout mutations + reset → 409 lock guard) — this issue finished the remaining outliers.
**Normalized async-op contract** (queue-triggering endpoints): **202 Accepted** = work queued; **404
ProblemDetails** = entity missing (controller pre-check); **409 ProblemDetails** = lock held (the running
job, or a mutation racing it — §3a/§3b); **422 ProblemDetails** = domain precondition (sync disabled /
unsupported / start failed). Trakt was the reference implementation. Changes made:
- `MaintenanceController.EmptyTrash` — error path **500 text/plain → 404/422 ProblemDetails** (`ToErrorResult`).
- `MaintenanceController.CleanArtwork` — silent **200 → 202** (fire-and-forget enqueue). No SPA consumer.
- `LibrariesController.ScanShow` — conflated **400 `{error}` → 202/404/409/422** via a new
`QueueShowScanResult` enum (6 outcomes incl. an honest `ScanFailed`→422, distinct from `Unsupported`).
- `ChannelController.ResetPlayout` — **200 → 202** (queue-triggering; 404/409 unchanged).
- `PlayoutController.ResetAll` — **202 (no body) → 202 + `ResetAllPlayoutsResponseModel`** reporting
`queuedPlayoutIds` / `skippedLocked` / `skippedUnsupported` (replaces the silent skip; still 202, still
skips locked/ExternalJson by design per §3a — now it *reports* what it skipped).
- `TroubleshootController.TroubleshootPlayback` — bare body-less `NotFound()` → **404/422 ProblemDetails**
with distinguishing detail. **Status codes the SPA HLS player depends on were preserved** — verified
`HlsPlayer.tsx` never branches on this endpoint's status (playback state comes from the separate
`/api/troubleshoot/playback/status` poll); only the error *body* was enriched.
**Playout build observability**: the list endpoint (`GET /api/playouts`) already stamped `isLocked` +
`BuildStatus` on `PlayoutListItemResponseModel` (#215); this issue adds **`isLocked` to the single-playout
`GET /api/playouts/{id}`** (`PlayoutResponseModel`), so the detail poll surface carries the §3a lock flag
too. No dedicated `GET /api/playouts/{id}/status` push channel was added — the flag on the existing GETs is
the HTTP-observable substitute for Blazor's live lock event, matching the `GET /api/trakt/status` precedent.
**F9 parity endpoints** (the `Libraries.razor` deletion gate — #202 did NOT close these):
- **Deep scan**: `POST /api/libraries/{id}/scan` gains `?deep=false`, threaded through
`QueueLibraryScanByLibraryId(LibraryId, DeepScan=false)` into `ForceSynchronize{Plex,Jellyfin,Emby}LibraryById(id, deep)`
(was hardcoded `false`). Non-breaking: existing callers omit it.
- **External-collections scan**: new `POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections?deep=false`
on the three #202 media-source controllers, dispatching `Synchronize{X}Collections(id, ForceScan:true, deep)`.
Each pre-checks source existence (404), acquires the per-source **collections** lock (`Lock{X}Collections()` —
the lock *is* the running scan, so a false = **409**), then enqueues and returns 202; the controller
compensating-unlocks in a `catch` if the enqueue throws (§3b), and `ScannerService` releases in its `finally`.
Thin SPA clients shipped (`scanLibrary(id, deep)`, `scanCollections`); **the SPA deep-scan / collections
buttons are the removal PR's remaining parity work** (parity doc §5).
**F7 Trakt batch-lock leak fix**: the global Trakt lock was released only when the *terminal* batch message
(`Unlock: true`) was processed; a `WorkerService` shutdown/cancellation before that message leaked the lock
permanently (subsequent Trakt ops 409 until restart — same class as #231/#233/#234). Fix: `WorkerService`
now releases the Trakt lock in a `finally` on read-loop exit if still held. Non-vacuous regression test proven
against an inverted-condition control.
**Accepted-by-design** (per the issue's decision-record ask): the worker's channels are **unbounded** and
there is **no shutdown drain** — messages still queued at process exit are dropped. This is acceptable because
the entity locks are **in-memory singletons that die with the process**, so a dropped message can't strand a
lock across restarts (the F7 `finally` covers the *within-process* shutdown-break leak, which is the only way
a lock outlives its batch while the process keeps running). Adding a bounded-channel backpressure / graceful
drain is out of scope and would not fix a correctness bug.
## 2026-07-11 — Optimistic-concurrency contract for replace-all PUTs (#253 PR1: infra + Block reference)
Replace-all aggregate PUTs had **no** optimistic concurrency — a stale second tab silently overwrote a
@@ -758,3 +812,36 @@ done with the #197 contract work. Tracked as a follow-up issue.
(`MediaCollectionViewModel`, `MultiCollectionViewModel`, `RerunCollectionViewModel`) carry `int Version = 0`
(defaulted — 0 for the selection-placeholder constructions, real value from the Mapper projection).
Header-only via ETag, never echoed in a response body (the Block precedent).
**Post-merge addendum (PR3 review, #269).** Activating the `Version` token means EF guards *every* root
UPDATE, so non-participating root-scalar writers that use plain `SaveChangesAsync` (playout settings /
schedule-file / on-demand-checkpoint, collection name) would 500 on a concurrent bump. The realistic
UPDATE writers were fixed in-PR with `ConcurrencyExtensions.SaveChangesForcingVersion` (Phase-1
force-write on conflict: adopt the stored token, retry, never revert the concurrent bump). The deferral
above is re-scoped to the DELETE handlers + repository `Add*` writers only (→ #269).
## 2026-07-11 — External Collections in the SPA derives from `getMediaSources()`; collections scans are optimistically bounded (#91b Libraries.razor parity)
**Context.** The last SPA pre-work before deleting Blazor `Libraries.razor` was wiring the shipped
`scanLibrary(id, deep)` + `scanCollections(family, id, deep)` clients (F9 API, #235) into `LibrariesScreen`,
matching the page's four scan actions: quick-library (already had it), deep-library, quick-collections,
deep-collections. Landed as its own pure-SPA PR ahead of the removal PR so the deletion diff stays surgical.
**Decision 1 — derive the External Collections rows client-side, no new endpoint.** Blazor's second table
comes from the `GetExternalCollections` MediatR query (one row per Plex/Jellyfin/Emby source with
`Libraries.Any(ShouldSyncItems)`), which has no REST wrapper. Rather than add one, the SPA derives the rows
from the existing `GET /api/media-sources`: `GetAllMediaSourcesForApiHandler` already filters each source's
`libraries` to sync-enabled entries (`ShouldIncludeLibrary` = `ShouldSyncItems` for remote families), so a
remote source with a **non-empty `libraries` list** is *exactly* the `Libraries.Any(ShouldSyncItems)` filter.
No extra endpoint, no extra fetch, single source of truth. (If `MediaSourceLibraryResponseModel` ever stops
filtering to sync-enabled libraries, this equivalence breaks — a test asserting the row set guards it.)
**Decision 2 — collections-scan buttons use optimistic, timeout-bounded pending (no poll reconcile).** Library
scans reconcile their optimistic "pending" flag against `GET /api/libraries/scan-status`. Collections scans
have **no** such surface — that endpoint is library-keyed, and Blazor only ever observed collections locks via
in-process `IEntityLocker` `Are{X}CollectionsLocked` events with no HTTP mirror. So the `useCollectionsScan`
hook disables a button optimistically on click and clears it after a fixed `COLLECTIONS_PENDING_TIMEOUT_MS`
(a 409 "already scanning" is benign and keeps it disabled until the timeout; a 404/network clears it and
surfaces the error). This is the honest ceiling of what the current API exposes. **Follow-up (backlog):** a
collections scan-status endpoint would let the SPA reconcile collections pending against a live active set the
way library scans do; filed as **#271** so the timeout isn't mistaken for the intended end state.
+4 -1
View File
@@ -2,7 +2,7 @@
*Generated by `scripts/generate-endpoint-index.py` from `ErsatzTV/wwwroot/openapi/v1.json`. Do not edit by hand -- regenerated by `scripts/update-openapi.sh`.*
155 endpoints, 240 operations.
158 endpoints, 243 operations.
## Artists
@@ -122,6 +122,7 @@
| GET | `/api/media-sources/emby/{id}/path-replacements` | GetEmbyPathReplacements | Get an Emby source's path replacements |
| PUT | `/api/media-sources/emby/{id}/path-replacements` | ReplaceEmbyPathReplacements | Replace an Emby source's path replacements |
| POST | `/api/media-sources/emby/{id}/refresh-libraries` | RefreshEmbyLibraries | Refresh an Emby source's libraries |
| POST | `/api/media-sources/emby/{id}/scan-collections` | ScanEmbyCollections | Scan an Emby source's collections |
## FFmpeg Profiles
@@ -176,6 +177,7 @@
| GET | `/api/media-sources/jellyfin/{id}/path-replacements` | GetJellyfinPathReplacements | Get a Jellyfin source's path replacements |
| PUT | `/api/media-sources/jellyfin/{id}/path-replacements` | ReplaceJellyfinPathReplacements | Replace a Jellyfin source's path replacements |
| POST | `/api/media-sources/jellyfin/{id}/refresh-libraries` | RefreshJellyfinLibraries | Refresh a Jellyfin source's libraries |
| POST | `/api/media-sources/jellyfin/{id}/scan-collections` | ScanJellyfinCollections | Scan a Jellyfin source's collections |
## Languages
@@ -295,6 +297,7 @@
| GET | `/api/media-sources/plex/{id}/path-replacements` | GetPlexPathReplacements | Get a Plex server's path replacements |
| PUT | `/api/media-sources/plex/{id}/path-replacements` | ReplacePlexPathReplacements | Replace a Plex server's path replacements |
| POST | `/api/media-sources/plex/{id}/refresh-libraries` | RefreshPlexLibraries | Refresh a Plex server's libraries |
| POST | `/api/media-sources/plex/{id}/scan-collections` | ScanPlexCollections | Scan a Plex server's collections |
## Rerun Collections
+16
View File
@@ -213,3 +213,19 @@ HARD CONSTRAINTS:
on #N", status tables), not just resolve the conflict markers — git fast-forwards stale *facts* silently. The
hand-written-docs sibling of the "regenerate generated artifacts after merging main" lesson. Also: docs-only
PRs still trip main's `Build & test` branch protection, so a rebase = a fresh full-CI cycle before merge.
- **A lock/channel-ownership "no cross-release" verdict must enumerate EVERY producer of that message
type, not just the enqueuers visible in the PR diff** (2026-07-11, #235/#267). The cold fork cleared the
new `scan-collections` per-provider lock as sound — "only the acquirer enqueues, so only its message
triggers the scanner unlock" — because it checked the three new controllers but never grepped for ALL
`Synchronize{X}Collections(` senders. Codex did: `SchedulerService` also enqueues them *periodically and
unlocked*, and `ScannerService`'s `finally` released the lock whenever held → a scheduled scan
cross-releases an API scan's lock (#250 class). Rule: before trusting any "single owner / no double
release / no cross-release" claim, `grep` the whole host project for every writer of that channel message
(or acquirer of that lock) — the background scheduler/worker is the usual missing producer. This is why the
independent Codex pass earns its keep alongside the fork even when the fork returns MERGEABLE.
- **Fork-vs-Codex disagreement on a gate PR → Fable, and Fable often improves the fix, not just the verdict**
(2026-07-11, #235): the reconciliation isn't only "who's right" — Fable ratified Codex's High AND caught
that the orchestrator's proposed *fix* (per-source lock-or-skip) would deterministically starve the 2nd+
media source (fixed loop order), prescribing the shipped library-scan §C7 pattern instead (lock once per
provider, batch-enqueue, release on the `Unlock: isLast` message). Escalate the FIX approach too, not just
the finding.
+20 -3
View File
@@ -1,4 +1,4 @@
import { ApiError, request } from './client';
import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client';
import type { components } from './generated/v1';
export type DecoTemplateGroup = components['schemas']['DecoTemplateGroupResponseModel'];
@@ -46,8 +46,25 @@ export function getDecoTemplateItems(id: number): Promise<DecoTemplateItem[]> {
return request<DecoTemplateItem[]>(`/api/deco-templates/${id}/items`);
}
export function replaceDecoTemplate(id: number, body: ReplaceDecoTemplateRequest): Promise<DecoTemplateWithItems> {
return request<DecoTemplateWithItems>(`/api/deco-templates/${id}`, { body, method: 'PUT' });
/** Load deco template items together with the deco template's concurrency ETag (issue #253). */
export function getDecoTemplateItemsWithMeta(id: number): Promise<ResponseWithMeta<DecoTemplateItem[]>> {
return requestWithMeta<DecoTemplateItem[]>(`/api/deco-templates/${id}/items`);
}
/**
* Replace a deco template. Pass the last-seen ETag as `If-Match` to reject a stale overwrite with
* 412; the resolved value carries the new ETag for a subsequent save (issue #253).
*/
export function replaceDecoTemplate(
id: number,
body: ReplaceDecoTemplateRequest,
ifMatch?: string | null
): Promise<ResponseWithMeta<DecoTemplateWithItems>> {
return requestWithMeta<DecoTemplateWithItems>(`/api/deco-templates/${id}`, {
body,
method: 'PUT',
headers: ifMatch ? { 'If-Match': ifMatch } : undefined
});
}
export function messageFromDecoTemplateError(error: unknown, fallback = 'Unable to load deco templates'): string {
+7
View File
@@ -1094,6 +1094,7 @@ export interface components {
"buildStatus": null | components["schemas"]["PlayoutBuildStatusResponseModel"];
"decoId": null | number;
"decoName": null | string;
"isLocked": boolean;
};
"PlayoutScheduleKind": "None" | "Classic" | "Block" | "Sequential" | "Scripted" | "ExternalJson";
"PlayoutSettingsResponseModel": {
@@ -1154,6 +1155,7 @@ export interface components {
"shuffleScheduleItems": boolean;
"randomStartPoint": boolean;
"fixedStartTimeBehavior": components["schemas"]["FixedStartTimeBehavior"];
"version": number;
};
"RemoteConnectionResponseModel": {
"address": null | string;
@@ -1244,6 +1246,11 @@ export interface components {
"selectedName": null | string;
"firstRunPlaybackOrder": components["schemas"]["PlaybackOrder"];
"rerunPlaybackOrder": components["schemas"]["PlaybackOrder"];
};
"ResetAllPlayoutsResponseModel": {
"queuedPlayoutIds": Array<number>;
"skippedLocked": Array<number>;
"skippedUnsupported": Array<number>;
};
"ResolutionResponseModel": {
"id": number;
+20 -1
View File
@@ -1,5 +1,5 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { scanLibrary, scanShow } from './libraries';
import { scanCollections, scanLibrary, scanShow } from './libraries';
function noContent(): Response {
return new Response(null, { status: 200 });
@@ -22,6 +22,25 @@ describe('libraries api client', () => {
expect(fetchMock).toHaveBeenCalledWith('/api/libraries/4/scan', expect.objectContaining({ method: 'POST' }));
});
it('scanLibrary appends ?deep=true for a deep scan', async () => {
const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(noContent());
await scanLibrary(4, true);
expect(fetchMock).toHaveBeenCalledWith('/api/libraries/4/scan?deep=true', expect.objectContaining({ method: 'POST' }));
});
it('scanCollections POSTs to the media-source scan-collections endpoint', async () => {
const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(noContent());
await scanCollections('jellyfin', 7);
expect(fetchMock).toHaveBeenCalledWith('/api/media-sources/jellyfin/7/scan-collections', expect.objectContaining({ method: 'POST' }));
});
it('scanCollections appends ?deep=true for a deep scan', async () => {
const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(noContent());
await scanCollections('plex', 3, true);
const { url } = lastCall(fetchMock);
expect(url).toBe('/api/media-sources/plex/3/scan-collections?deep=true');
});
it('scanShow POSTs the show id and deepScan flag', async () => {
const fetchMock = vi.spyOn(window, 'fetch').mockResolvedValue(noContent());
await scanShow(4, { deepScan: true, showId: 42 });
+129 -9
View File
@@ -16,7 +16,7 @@ export type LibrariesScreenQueryState =
data: LibrariesScreenData;
error: string | null;
refresh: () => void;
scanLibrary: (libraryId: number) => Promise<void>;
scanLibrary: (libraryId: number, deep?: boolean) => Promise<void>;
scanningLibraryIds: Set<number>;
status: 'success';
}
@@ -42,8 +42,24 @@ export function getLibraryScanStatus(): Promise<LibraryScanStatus[]> {
);
}
export function scanLibrary(libraryId: number): Promise<void> {
return request<void>(`/api/libraries/${libraryId}/scan`, { method: 'POST' });
// Queues a library scan. `deep` requests a deep (force-metadata) scan — the API equivalent of the
// legacy Blazor "Deep Scan Library" button (#235 F9); omit or pass false for a quick scan. Returns
// 202 when queued, 404 (missing), 409 (already scanning), 422 (sync disabled) — see §3b.
export function scanLibrary(libraryId: number, deep = false): Promise<void> {
const query = deep ? '?deep=true' : '';
return request<void>(`/api/libraries/${libraryId}/scan${query}`, { method: 'POST' });
}
// Media-source families that support an external-collections scan (#235 F9). Matches the three
// media-source controllers #202 introduced.
export type CollectionsScanSource = 'emby' | 'jellyfin' | 'plex';
// Queues an external-collections scan for a Plex/Jellyfin/Emby media source — the API equivalent of
// the legacy Blazor "Scan Collections" button (#235 F9). `deep` requests a deep scan. Returns 202
// when queued, 404 (source missing), 409 (a collections scan is already running for that source).
export function scanCollections(source: CollectionsScanSource, sourceId: number, deep = false): Promise<void> {
const query = deep ? '?deep=true' : '';
return request<void>(`/api/media-sources/${source}/${sourceId}/scan-collections${query}`, { method: 'POST' });
}
export interface ScanShowParams {
@@ -51,9 +67,11 @@ export interface ScanShowParams {
deepScan?: boolean;
}
// Queues a scan of a single show (by id) within a library. Returns 200 on success, 404 when the
// show id doesn't exist in the library, 400 when the library doesn't support single-show
// scanning. Body keys are `showId` and `deepScan` (see LibrariesController.ScanShowRequest).
// Queues a scan of a single show (by id) within a library. Returns 202 when queued, 404 when the
// show id doesn't exist in the library, 409 when a scan is already running, and 422 when the
// library doesn't support single-show scanning / sync is disabled / the scan failed to start (all
// error bodies are ProblemDetails; #235 normalized the old conflated 400). Body keys are `showId`
// and `deepScan` (see LibrariesController.ScanShowRequest).
export function scanShow(libraryId: number, params: ScanShowParams): Promise<void> {
return request<void>(`/api/libraries/${libraryId}/scan-show`, {
body: { deepScan: params.deepScan ?? false, showId: params.showId },
@@ -297,9 +315,10 @@ export function useLibrariesScreenQuery(pollMs = 10000): LibrariesScreenQuerySta
});
}, []);
const triggerScan = useCallback((libraryId: number): Promise<void> => {
const triggerScan = useCallback((libraryId: number, deep = false): Promise<void> => {
if (pendingIdsRef.current.has(libraryId) || activeIdsRef.current.has(libraryId)) {
// Already pending or active - ignore the duplicate submission.
// Already pending or active - ignore the duplicate submission. Quick and deep scans share the
// same per-library lock, so both affordances gate on (and reconcile through) this one id set.
return Promise.resolve();
}
@@ -320,7 +339,7 @@ export function useLibrariesScreenQuery(pollMs = 10000): LibrariesScreenQuerySta
};
});
return scanLibrary(libraryId)
return scanLibrary(libraryId, deep)
.then(() => {
// 202 Accepted - a scan is genuinely queued. Poll scan-status; the pending flag is
// promoted to "active" once the scan appears there.
@@ -381,6 +400,107 @@ export function useLibrariesScreenQuery(pollMs = 10000): LibrariesScreenQuerySta
return { data: null, error: null, refresh, status: 'loading' };
}
// --- External collections scan (Plex/Jellyfin/Emby) ---
// A pending collections scan re-enables its button after this bound. Unlike library scans, an
// external-collections scan has NO authoritative "in progress" REST surface: /api/libraries/scan-status
// is library-keyed, and Blazor only ever observed collections locks through in-process IEntityLocker
// events (Are{X}CollectionsLocked) that have no HTTP mirror. So we can't reconcile "pending" against a
// live active set the way library scans do - we optimistically disable, then give up after this bound
// so a button can't wedge disabled forever. (A collections scan-status endpoint would let us reconcile
// properly - see the #91b follow-up note.)
const COLLECTIONS_PENDING_TIMEOUT_MS = 30000;
export interface CollectionsScanState {
error: string | null;
scan: (source: CollectionsScanSource, sourceId: number, deep: boolean) => Promise<void>;
scanningKeys: Set<string>;
}
// Stable key for a per-(family, source) collections scan, used by both the hook and the screen so the
// "is this row scanning?" lookup has exactly one definition.
export function collectionsScanKey(source: CollectionsScanSource, sourceId: number): string {
return `${source}:${sourceId}`;
}
export function useCollectionsScan(): CollectionsScanState {
const [scanningKeys, setScanningKeys] = useState<Set<string>>(new Set());
const [error, setError] = useState<string | null>(null);
// Mirror kept in sync synchronously so scan() can guard double-submits without waiting for a render.
const scanningKeysRef = useRef<Set<string>>(new Set());
const timeoutsRef = useRef<Map<string, number>>(new Map());
const activeRef = useRef(true);
useEffect(() => {
activeRef.current = true;
// Identity is stable across the hook's life (we only .set/.delete entries, never reassign the
// Map), so capturing it here is the same instance the cleanup clears at unmount.
const timeouts = timeoutsRef.current;
return () => {
activeRef.current = false;
timeouts.forEach((timeoutId) => window.clearTimeout(timeoutId));
timeouts.clear();
};
}, []);
const clearKey = useCallback((key: string) => {
const timeoutId = timeoutsRef.current.get(key);
if (timeoutId !== undefined) {
window.clearTimeout(timeoutId);
timeoutsRef.current.delete(key);
}
const next = new Set(scanningKeysRef.current);
next.delete(key);
scanningKeysRef.current = next;
if (activeRef.current) {
setScanningKeys(next);
}
}, []);
const scan = useCallback(
(source: CollectionsScanSource, sourceId: number, deep: boolean): Promise<void> => {
const key = collectionsScanKey(source, sourceId);
if (scanningKeysRef.current.has(key)) {
// Already pending - ignore the duplicate submission (quick and deep share the source lock).
return Promise.resolve();
}
const pending = new Set(scanningKeysRef.current).add(key);
scanningKeysRef.current = pending;
setScanningKeys(pending);
setError(null);
const timeoutId = window.setTimeout(() => clearKey(key), COLLECTIONS_PENDING_TIMEOUT_MS);
timeoutsRef.current.set(key, timeoutId);
return scanCollections(source, sourceId, deep)
.then(() => {
// 202 Accepted - a scan is genuinely queued. Keep the button disabled until the bounded
// timeout expires (there is no completion signal to reconcile against).
})
.catch((err: unknown) => {
if (err instanceof ApiError && err.status === 409) {
// 409 Conflict - a collections scan is already running for this source. Benign: keep the
// optimistic pending flag (button stays disabled) with no error; it clears on the timeout.
return;
}
// 404 (source missing) / network error - nothing was queued, so re-enable and surface it.
clearKey(key);
if (activeRef.current) {
setError(messageFromLibrariesError(err, 'Unable to scan collections'));
}
});
},
[clearKey]
);
return { error, scan, scanningKeys };
}
function messageFromLibrariesError(error: unknown, fallback = 'Unable to load libraries'): string {
if (error instanceof ApiError) {
return error.detail ?? error.message;
+19 -4
View File
@@ -1,4 +1,4 @@
import { ApiError, request } from './client';
import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client';
import type { components } from './generated/v1';
export type AddItemsToPlaylistRequest = components['schemas']['AddItemsToPlaylistRequest'];
@@ -41,13 +41,28 @@ export function getPlaylistItems(id: number): Promise<PlaylistItem[]> {
return request<PlaylistItem[]>(`/api/playlists/${id}/items`);
}
/** Load playlist items together with the playlist's concurrency ETag (issue #253). */
export function getPlaylistItemsWithMeta(id: number): Promise<ResponseWithMeta<PlaylistItem[]>> {
return requestWithMeta<PlaylistItem[]>(`/api/playlists/${id}/items`);
}
export function createPlaylist(body: CreatePlaylistRequest): Promise<Playlist> {
return request<Playlist>('/api/playlists', { body, method: 'POST' });
}
// PUT = rename + replace the full item list; returns the persisted (re-indexed) items.
export function updatePlaylist(id: number, body: ReplacePlaylistRequest): Promise<PlaylistItem[]> {
return request<PlaylistItem[]>(`/api/playlists/${id}`, { body, method: 'PUT' });
// PUT = rename + replace the full item list; returns the persisted (re-indexed) items. Pass the
// last-seen ETag as `If-Match` to reject a stale overwrite with 412; the resolved value carries
// the new ETag for a subsequent save (issue #253).
export function updatePlaylist(
id: number,
body: ReplacePlaylistRequest,
ifMatch?: string | null
): Promise<ResponseWithMeta<PlaylistItem[]>> {
return requestWithMeta<PlaylistItem[]>(`/api/playlists/${id}`, {
body,
method: 'PUT',
headers: ifMatch ? { 'If-Match': ifMatch } : undefined
});
}
export function deletePlaylist(id: number): Promise<void> {
+7 -2
View File
@@ -108,8 +108,13 @@ export function getPlayoutChannelStates(): Promise<PlayoutChannelState[]> {
return request<PlayoutChannelState[]>('/api/channels/state');
}
export function resetAllPlayouts(): Promise<void> {
return request<void>('/api/playouts/reset-all', { method: 'POST' });
export type ResetAllPlayoutsResult = components['schemas']['ResetAllPlayoutsResponseModel'];
// Queues a reset of every eligible playout. Returns 202 with a body reporting which playouts were
// queued vs skipped (locked, or an unsupported ExternalJson/None schedule kind) — #235 replaced the
// old silent skip. The caller may surface `skipped*` to explain why some playouts didn't reset.
export function resetAllPlayouts(): Promise<ResetAllPlayoutsResult> {
return request<ResetAllPlayoutsResult>('/api/playouts/reset-all', { method: 'POST' });
}
export function deletePlayout(playoutId: number): Promise<void> {
+20 -6
View File
@@ -1,4 +1,4 @@
import { ApiError, request } from './client';
import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client';
import type { components } from './generated/v1';
// FillerPreset is exported by ./pickers — import (don't re-export) to avoid a duplicate `export *`
// name in api/index.ts. LanguageCode/getLanguages moved to ./languages (also re-exported via
@@ -46,17 +46,31 @@ export function getScheduleItems(scheduleId: number): Promise<ScheduleItemsRespo
return request<ScheduleItemsResponse>(`/api/schedules/${scheduleId}/items`);
}
/** Load schedule items together with the schedule's concurrency ETag (issue #253). */
export function getScheduleItemsWithMeta(
scheduleId: number
): Promise<ResponseWithMeta<ScheduleItemsResponse>> {
return requestWithMeta<ScheduleItemsResponse>(`/api/schedules/${scheduleId}/items`);
}
export function addScheduleItem(scheduleId: number, body: ScheduleItemRequest): Promise<ScheduleItem> {
return request<ScheduleItem>(`/api/schedules/${scheduleId}/items`, { body, method: 'POST' });
}
// Destructive replace: the server deletes+recreates every item row (new ids) and triggers playout
// rebuilds. The editor batches all local draft edits into this single call. See docs/decisions.md.
// Positional in-place reconcile: the server reuses same-typed item rows (keeping fill-group state) and
// triggers playout rebuilds. The editor batches all local draft edits into this single call. Pass the
// last-seen ETag as `If-Match` to reject a stale overwrite with 412; the resolved value carries the new
// ETag for a subsequent save (issue #253). See docs/decisions.md.
export function replaceScheduleItems(
scheduleId: number,
body: ReplaceScheduleItemsRequest
): Promise<ScheduleItem[]> {
return request<ScheduleItem[]>(`/api/schedules/${scheduleId}/items`, { body, method: 'PUT' });
body: ReplaceScheduleItemsRequest,
ifMatch?: string | null
): Promise<ResponseWithMeta<ScheduleItem[]>> {
return requestWithMeta<ScheduleItem[]>(`/api/schedules/${scheduleId}/items`, {
body,
method: 'PUT',
headers: ifMatch ? { 'If-Match': ifMatch } : undefined
});
}
export function deleteScheduleItem(scheduleId: number, itemId: number): Promise<void> {
+20 -3
View File
@@ -1,4 +1,4 @@
import { ApiError, request } from './client';
import { ApiError, request, requestWithMeta, type ResponseWithMeta } from './client';
import type { components } from './generated/v1';
export type TemplateGroup = components['schemas']['TemplateGroupResponseModel'];
@@ -47,8 +47,25 @@ export function getTemplateItems(id: number): Promise<TemplateItem[]> {
return request<TemplateItem[]>(`/api/templates/${id}/items`);
}
export function replaceTemplate(id: number, body: ReplaceTemplateRequest): Promise<TemplateWithItems> {
return request<TemplateWithItems>(`/api/templates/${id}`, { body, method: 'PUT' });
/** Load template items together with the template's concurrency ETag (issue #253). */
export function getTemplateItemsWithMeta(id: number): Promise<ResponseWithMeta<TemplateItem[]>> {
return requestWithMeta<TemplateItem[]>(`/api/templates/${id}/items`);
}
/**
* Replace a template. Pass the last-seen ETag as `If-Match` to reject a stale overwrite with 412;
* the resolved value carries the new ETag for a subsequent save (issue #253).
*/
export function replaceTemplate(
id: number,
body: ReplaceTemplateRequest,
ifMatch?: string | null
): Promise<ResponseWithMeta<TemplateWithItems>> {
return requestWithMeta<TemplateWithItems>(`/api/templates/${id}`, {
body,
method: 'PUT',
headers: ifMatch ? { 'If-Match': ifMatch } : undefined
});
}
export function copyTemplate(id: number, body: CopyTemplateRequest): Promise<Template> {
@@ -185,4 +185,42 @@ describe('DecoTemplatesScreen', () => {
expect(screen.queryByText(/must start before it ends/)).not.toBeInTheDocument();
expect(screen.getByRole('button', { name: /Save deco template/ })).not.toBeDisabled();
});
it('shows a conflict dialog and reloads when the deco template changed elsewhere (412)', async () => {
window.history.pushState({}, '', '/app/deco-templates/4');
let putCount = 0;
const fetchMock = mockApi({
items: [{ decoId: 10, decoName: 'Sunrise', startTime: '06:00:00', endTime: '07:00:00' }],
onRequest: (url, method) => {
if (url === '/api/deco-templates/4' && method === 'PUT') {
putCount += 1;
if (putCount === 1) {
return new Response(
JSON.stringify({ status: 412, title: 'Precondition Failed', detail: 'stale' }),
{ headers: { 'Content-Type': 'application/json' }, status: 412 }
);
}
}
return null;
}
});
render(<DecoTemplatesScreen />);
await waitFor(() => expect(screen.getByDisplayValue('Bumpers')).toBeInTheDocument());
const itemsGetCount = () =>
fetchMock.mock.calls.filter(
([u, init]) => u === '/api/deco-templates/4/items' && (init?.method ?? 'GET') === 'GET'
).length;
const before = itemsGetCount();
fireEvent.click(screen.getByRole('button', { name: /Save deco template/ }));
// A 412 opens the "changed elsewhere" dialog rather than showing a generic save error.
expect(await screen.findByText(/Reload to get the latest version/i)).toBeInTheDocument();
// Reloading re-fetches the deco template items.
fireEvent.click(screen.getByRole('button', { name: /^Reload$/ }));
await waitFor(() => expect(itemsGetCount()).toBeGreaterThan(before));
});
});
+61 -22
View File
@@ -3,6 +3,7 @@ import { ArrowLeft, Check, FolderPlus, Plus, Trash2, TriangleAlert } from 'lucid
import { navigateToPath } from '../routing';
import { Badge, Button, Card, ConfirmDialog, Dialog, IconButton, Input, Select, Spinner } from '../components';
import {
ApiError,
createDecoTemplate,
createDecoTemplateGroup,
deleteDecoTemplate,
@@ -10,7 +11,7 @@ import {
getDecoGroups,
getDecoTemplate,
getDecoTemplateGroups,
getDecoTemplateItems,
getDecoTemplateItemsWithMeta,
getDecoTemplates,
getDecos,
messageFromDecoTemplateError,
@@ -477,6 +478,11 @@ function DecoTemplateEditor({ decoTemplateId }: { decoTemplateId: number }) {
const [loadError, setLoadError] = useState<null | string>(null);
const [saveError, setSaveError] = useState<null | string>(null);
const [saving, setSaving] = useState(false);
const [conflictOpen, setConflictOpen] = useState(false);
const [reloadKey, setReloadKey] = useState(0);
// Concurrency ETag (issue #253): captured from the items GET, sent as If-Match on save, and
// replaced from the PUT response on every successful save.
const etagRef = useRef<string | null>(null);
const [addGroupId, setAddGroupId] = useState('');
const [addDecoId, setAddDecoId] = useState('');
@@ -487,34 +493,38 @@ function DecoTemplateEditor({ decoTemplateId }: { decoTemplateId: number }) {
useEffect(() => {
let active = true;
Promise.all([
getDecoTemplate(decoTemplateId),
getDecoTemplateItems(decoTemplateId),
getDecoGroups(),
getDecos()
])
.then(([decoTemplateData, items, groupData, decoData]) => {
// Read items + ETag FIRST, then the root metadata, mirroring BlockEditor (issue #253): the ETag
// must be no newer than every piece of versioned data the draft is built from.
void (async () => {
try {
const itemsMeta = await getDecoTemplateItemsWithMeta(decoTemplateId);
const [decoTemplateData, groupData, decoData] = await Promise.all([
getDecoTemplate(decoTemplateId),
getDecoGroups(),
getDecos()
]);
if (!active) {
return;
}
etagRef.current = itemsMeta.etag;
setDecoTemplate(decoTemplateData);
setDecoGroups(groupData);
setDecos(decoData);
setDraft({
name: decoTemplateData.name,
items: items.map(itemFromResponse)
items: itemsMeta.data.map(itemFromResponse)
});
})
.catch((error: unknown) => {
} catch (error) {
if (active) {
setLoadError(messageFromDecoTemplateError(error, 'Unable to load deco template'));
}
});
}
})();
return () => {
active = false;
};
}, [decoTemplateId]);
}, [decoTemplateId, reloadKey]);
if (loadError) {
return (
@@ -590,22 +600,40 @@ function DecoTemplateEditor({ decoTemplateId }: { decoTemplateId: number }) {
setSaving(true);
setSaveError(null);
try {
await replaceDecoTemplate(decoTemplateId, {
name: draft.name.trim(),
items: draft.items.map((item) => ({
decoId: item.decoId,
startTime: item.startTime,
endTime: item.endTime
}))
});
const { etag } = await replaceDecoTemplate(
decoTemplateId,
{
name: draft.name.trim(),
items: draft.items.map((item) => ({
decoId: item.decoId,
startTime: item.startTime,
endTime: item.endTime
}))
},
etagRef.current
);
etagRef.current = etag;
navigateToPath(BASE_PATH);
} catch (error) {
setSaveError(messageFromDecoTemplateError(error, 'Unable to save deco template'));
if (error instanceof ApiError && error.status === 412) {
// Another edit landed since we loaded — force a reload rather than overwriting it (#253).
setConflictOpen(true);
} else {
setSaveError(messageFromDecoTemplateError(error, 'Unable to save deco template'));
}
} finally {
setSaving(false);
}
};
const reloadAfterConflict = () => {
setConflictOpen(false);
setSaveError(null);
setDraft(null);
setDecoTemplate(null);
setReloadKey((key) => key + 1);
};
return (
<div className="ctv-collections">
<div className="ctv-channels-actionbar">
@@ -758,6 +786,17 @@ function DecoTemplateEditor({ decoTemplateId }: { decoTemplateId: number }) {
</table>
)}
</Card>
<ConfirmDialog
cancelLabel="Keep editing"
confirmLabel="Reload"
message="This deco template was changed elsewhere since you opened it. Reload to get the latest version — your unsaved changes will be discarded."
onCancel={() => setConflictOpen(false)}
onConfirm={reloadAfterConflict}
open={conflictOpen}
title="Deco template changed elsewhere"
tone="danger"
/>
</div>
);
}
+155 -1
View File
@@ -74,7 +74,14 @@ function mockApi(options: MockOptions = {}): MockHandle {
return Promise.resolve(jsonResponse(options.libraryScanStatuses ?? []));
}
if (/^\/api\/libraries\/\d+\/scan$/.test(url) && method === 'POST') {
if (/^\/api\/libraries\/\d+\/scan(\?deep=true)?$/.test(url) && method === 'POST') {
if (url in mutationFailures) {
return Promise.resolve(jsonResponse(mutationFailures[url], mutationFailures[url].status ?? 422));
}
return Promise.resolve(new Response(null, { status: 202 }));
}
if (/^\/api\/media-sources\/(plex|jellyfin|emby)\/\d+\/scan-collections(\?deep=true)?$/.test(url) && method === 'POST') {
if (url in mutationFailures) {
return Promise.resolve(jsonResponse(mutationFailures[url], mutationFailures[url].status ?? 422));
}
@@ -369,6 +376,153 @@ describe('LibrariesScreen', () => {
expect(await screen.findByText('No media sources returned')).toBeInTheDocument();
});
describe('deep scan + external collections (#91b Libraries.razor parity)', () => {
// A remote source with two sync-enabled libraries (deep-scan available) plus an External
// Collections row; a Local source (no deep, no collections row); and a remote source with NO
// sync-enabled libraries (no External Collections row).
function paritySources(): unknown[] {
return [
mediaSource({
id: 30,
kind: 'Local',
libraries: [library({ id: 31, mediaKind: 'Movies', name: 'Movies' })],
name: 'Local'
}),
mediaSource({
connectionAddress: 'https://plex.example.test',
id: 40,
kind: 'Plex',
libraries: [library({ id: 41, mediaKind: 'Shows', name: 'TV Shows' })],
name: 'Plex Server'
}),
mediaSource({
connectionAddress: 'https://jellyfin.example.test',
id: 50,
kind: 'Jellyfin',
libraries: [],
name: 'Jellyfin Home'
})
];
}
it('deep-scans a remote library via POST /api/libraries/{id}/scan?deep=true', async () => {
const handle = mockApi({ mediaSources: paritySources() });
render(<LibrariesScreen />);
await screen.findByText('TV Shows');
fireEvent.click(screen.getByRole('button', { name: 'Deep scan TV Shows' }));
await waitFor(() => {
expect(handle.fetchSpy).toHaveBeenCalledWith('/api/libraries/41/scan?deep=true', expect.objectContaining({ method: 'POST' }));
});
expect(fetchCount(handle, '/api/libraries/41/scan')).toBe(0);
});
it('offers a deep-scan button only for remote libraries, never Local', async () => {
mockApi({ mediaSources: paritySources() });
render(<LibrariesScreen />);
await screen.findByText('TV Shows');
// Local library "Movies" has a quick scan but no deep scan.
expect(screen.getByRole('button', { name: 'Scan Movies' })).toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Deep scan Movies' })).not.toBeInTheDocument();
// Remote library "TV Shows" has both.
expect(screen.getByRole('button', { name: 'Scan TV Shows' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: 'Deep scan TV Shows' })).toBeInTheDocument();
});
it('renders an External Collections row only for remote sources with sync-enabled libraries', async () => {
mockApi({ mediaSources: paritySources() });
render(<LibrariesScreen />);
await screen.findByText('TV Shows');
expect(screen.getByRole('heading', { name: 'External Collections' })).toBeInTheDocument();
// Plex Server has a sync-enabled library → a collections row.
expect(screen.getByRole('button', { name: 'Scan Plex Server collections' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: 'Deep scan Plex Server collections' })).toBeInTheDocument();
// Jellyfin Home has no sync-enabled library → no collections row; Local never gets one.
expect(screen.queryByRole('button', { name: 'Scan Jellyfin Home collections' })).not.toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Scan Local collections' })).not.toBeInTheDocument();
});
it('omits the External Collections section entirely when no remote source has sync-enabled libraries', async () => {
mockApi({
mediaSources: [
mediaSource({ id: 30, kind: 'Local', libraries: [library({ id: 31, name: 'Movies' })], name: 'Local' })
]
});
render(<LibrariesScreen />);
expect((await screen.findAllByText('Movies')).length).toBeGreaterThan(0);
expect(screen.queryByRole('heading', { name: 'External Collections' })).not.toBeInTheDocument();
});
it('queues a quick collections scan via POST /api/media-sources/{family}/{id}/scan-collections', async () => {
const handle = mockApi({ mediaSources: paritySources() });
render(<LibrariesScreen />);
await screen.findByRole('button', { name: 'Scan Plex Server collections' });
fireEvent.click(screen.getByRole('button', { name: 'Scan Plex Server collections' }));
await waitFor(() => {
expect(handle.fetchSpy).toHaveBeenCalledWith('/api/media-sources/plex/40/scan-collections', expect.objectContaining({ method: 'POST' }));
});
// The button is optimistically disabled while the scan is pending.
expect(screen.getByRole('button', { name: 'Scan Plex Server collections' })).toBeDisabled();
});
it('queues a deep collections scan with ?deep=true', async () => {
const handle = mockApi({ mediaSources: paritySources() });
render(<LibrariesScreen />);
await screen.findByRole('button', { name: 'Deep scan Plex Server collections' });
fireEvent.click(screen.getByRole('button', { name: 'Deep scan Plex Server collections' }));
await waitFor(() => {
expect(handle.fetchSpy).toHaveBeenCalledWith('/api/media-sources/plex/40/scan-collections?deep=true', expect.objectContaining({ method: 'POST' }));
});
});
it('treats a 409 "already scanning" collections response as benign (button stays disabled, no error)', async () => {
mockApi({
mediaSources: paritySources(),
mutationFailures: { '/api/media-sources/plex/40/scan-collections': { status: 409 } }
});
render(<LibrariesScreen />);
await screen.findByRole('button', { name: 'Scan Plex Server collections' });
fireEvent.click(screen.getByRole('button', { name: 'Scan Plex Server collections' }));
await waitFor(() => {
expect(screen.getByRole('button', { name: 'Scan Plex Server collections' })).toBeDisabled();
});
expect(screen.queryByText(/Unable to scan collections/)).not.toBeInTheDocument();
expect(screen.queryByText(/Request failed/)).not.toBeInTheDocument();
});
it('surfaces a collections scan failure and re-enables the button', async () => {
mockApi({
mediaSources: paritySources(),
mutationFailures: { '/api/media-sources/plex/40/scan-collections': { status: 404 } }
});
render(<LibrariesScreen />);
await screen.findByRole('button', { name: 'Scan Plex Server collections' });
fireEvent.click(screen.getByRole('button', { name: 'Scan Plex Server collections' }));
expect(await screen.findByText('Request failed with status 404')).toBeInTheDocument();
expect(screen.getByRole('button', { name: 'Scan Plex Server collections' })).not.toBeDisabled();
});
});
describe('hub wiring (slice S5)', () => {
it('Add Source menu navigates to the local-new and each family route', async () => {
const pushSpy = vi.spyOn(window.history, 'pushState');
+102 -2
View File
@@ -6,11 +6,13 @@ import {
Film,
Folder,
HardDrive,
Library,
MonitorPlay,
Music,
Plus,
Radio,
RefreshCw,
ScanSearch,
Server,
Settings,
TriangleAlert
@@ -25,7 +27,10 @@ import {
StatusDot
} from '../components';
import {
collectionsScanKey,
useCollectionsScan,
useLibrariesScreenQuery,
type CollectionsScanSource,
type LibraryScanStatus,
type MediaSource,
type MediaSourceLibrary
@@ -41,6 +46,7 @@ import {
export function LibrariesScreen() {
const query = useLibrariesScreenQuery();
const collectionsScan = useCollectionsScan();
if (query.status === 'loading') {
return <LibrariesLoadingState />;
@@ -60,6 +66,21 @@ export function LibrariesScreen() {
);
const scanStatusesByLibraryId = new Map(query.data.scanStatuses.map((status) => [status.libraryId, status]));
// External Collections mirrors Blazor Libraries.razor's second table: one row per Plex/Jellyfin/Emby
// source that has at least one sync-enabled library. GetAllMediaSourcesForApiHandler already filters
// each source's `libraries` to sync-enabled entries (ShouldIncludeLibrary), so a remote source with a
// non-empty `libraries` list is exactly the `Libraries.Any(ShouldSyncItems)` filter GetExternalCollections
// applies - no separate endpoint needed.
const collectionsRows = query.data.sources
.map((source) => {
const family = parseRemoteFamily(source.kind);
if (family === null || source.libraries.length === 0) {
return null;
}
return { family, name: source.name, sourceId: source.id };
})
.filter((row): row is { family: CollectionsScanSource; name: string; sourceId: number } => row !== null);
return (
<div className="ctv-libraries-screen">
<section className="ctv-libraries-header">
@@ -97,10 +118,81 @@ export function LibrariesScreen() {
/>
))}
</div>
{collectionsRows.length > 0 && (
<ExternalCollectionsSection
error={collectionsScan.error}
onScanCollections={collectionsScan.scan}
rows={collectionsRows}
scanningKeys={collectionsScan.scanningKeys}
/>
)}
</div>
);
}
// External Collections table (parity with Blazor Libraries.razor's second table). Each row is a
// remote source with sync-enabled libraries; the quick/deep buttons queue that source's collections
// scan. There is no scan-status poll surface for collections (see useCollectionsScan), so a row's
// "scanning" state is optimistic and bounded by a timeout rather than reconciled against a live set.
function ExternalCollectionsSection({
error,
onScanCollections,
rows,
scanningKeys
}: {
error: string | null;
onScanCollections: (source: CollectionsScanSource, sourceId: number, deep: boolean) => Promise<void>;
rows: Array<{ family: CollectionsScanSource; name: string; sourceId: number }>;
scanningKeys: Set<string>;
}) {
return (
<section className="ctv-library-source-card" aria-label="External collections">
<div className="ctv-library-source-head">
<span className="ctv-library-kind-icon"><Library aria-hidden="true" size={18} /></span>
<div>
<div className="ctv-library-source-title">
<h3>External Collections</h3>
</div>
<span>Sync Plex, Jellyfin, and Emby collections into ErsatzTV.</span>
</div>
</div>
{error && (
<div className="ctv-channels-error" role="alert">
<TriangleAlert aria-hidden="true" size={15} />
<span>{error}</span>
</div>
)}
<div className="ctv-library-list" role="list" aria-label="External collections list">
{rows.map((row) => {
const scanning = scanningKeys.has(collectionsScanKey(row.family, row.sourceId));
return (
<div className="ctv-library-row" key={collectionsScanKey(row.family, row.sourceId)} role="listitem">
<span className={`ctv-library-kind-icon ctv-library-kind-${row.family}`}><Server aria-hidden="true" size={16} /></span>
<div className="ctv-library-row-main">
<strong>{row.name}</strong>
<span>{familyLabel(row.family)} collections</span>
</div>
<div className="ctv-library-row-status">
{scanning ? <Badge tone="accent" dot>Scanning</Badge> : <Badge tone="ok" dot>Idle</Badge>}
<IconButton disabled={scanning} onClick={() => void onScanCollections(row.family, row.sourceId, true)} size="sm" title={`Deep scan ${row.name} collections`}>
<ScanSearch aria-hidden="true" size={15} />
</IconButton>
<IconButton disabled={scanning} onClick={() => void onScanCollections(row.family, row.sourceId, false)} size="sm" title={`Scan ${row.name} collections`}>
<RefreshCw aria-hidden="true" size={15} />
</IconButton>
</div>
</div>
);
})}
</div>
</section>
);
}
// "Add Source" dropdown: Local library opens the create editor; each remote family opens its screen.
// Mirrors the AddToMenu popover pattern (click-outside + Escape close). Navigation goes through
// navigateToPath, which App's popstate owner turns into the right libraries sub-path (design §D.2).
@@ -203,7 +295,7 @@ function MediaSourceCard({
scanningLibraryIds,
source
}: {
onScanLibrary: (libraryId: number) => Promise<void>;
onScanLibrary: (libraryId: number, deep?: boolean) => Promise<void>;
scanStatusesByLibraryId: Map<number, LibraryScanStatus>;
scanningLibraryIds: Set<number>;
source: MediaSource;
@@ -250,6 +342,7 @@ function MediaSourceCard({
) : source.libraries.map((library) => (
<LibraryRow
key={library.id}
allowDeepScan={!isLocal}
editable={isLocal}
library={library}
onScanLibrary={onScanLibrary}
@@ -268,15 +361,17 @@ function MediaSourceCard({
}
function LibraryRow({
allowDeepScan,
editable,
library,
onScanLibrary,
scanStatus,
scanning
}: {
allowDeepScan: boolean;
editable: boolean;
library: MediaSourceLibrary;
onScanLibrary: (libraryId: number) => Promise<void>;
onScanLibrary: (libraryId: number, deep?: boolean) => Promise<void>;
scanStatus: LibraryScanStatus | null;
scanning: boolean;
}) {
@@ -300,6 +395,11 @@ function LibraryRow({
) : (
<Badge tone="ok" dot>Synced</Badge>
)}
{allowDeepScan && (
<IconButton disabled={disabled} onClick={() => void onScanLibrary(library.id, true)} size="sm" title={`Deep scan ${library.name}`}>
<ScanSearch aria-hidden="true" size={15} />
</IconButton>
)}
<IconButton disabled={disabled} onClick={() => void onScanLibrary(library.id)} size="sm" title={`Scan ${library.name}`}>
<RefreshCw aria-hidden="true" size={15} />
</IconButton>
+38
View File
@@ -206,6 +206,44 @@ describe('PlaylistsScreen', () => {
});
});
it('shows a conflict dialog and reloads when the playlist changed elsewhere (412)', async () => {
let putCount = 0;
const fetchMock = mockApi({
onRequest: (url, method) => {
if (url === '/api/playlists/10' && method === 'PUT') {
putCount += 1;
if (putCount === 1) {
return new Response(
JSON.stringify({ status: 412, title: 'Precondition Failed', detail: 'stale' }),
{ headers: { 'Content-Type': 'application/json' }, status: 412 }
);
}
return jsonResponse([], 200);
}
return null;
}
});
render(<PlaylistsScreen />);
fireEvent.click(await screen.findByText('Bumps'));
expect(await screen.findByText('Favorites')).toBeInTheDocument();
const itemsGetCount = () =>
fetchMock.mock.calls.filter(([u, init]) => u === '/api/playlists/10/items' && (init?.method ?? 'GET') === 'GET')
.length;
const before = itemsGetCount();
fireEvent.click(screen.getByRole('button', { name: 'Save playlist' }));
// A 412 opens the "changed elsewhere" dialog rather than showing a generic save error.
expect(await screen.findByText(/Reload to get the latest version/i)).toBeInTheDocument();
// Reloading re-fetches the playlist items.
fireEvent.click(screen.getByRole('button', { name: /^Reload$/ }));
await waitFor(() => expect(itemsGetCount()).toBeGreaterThan(before));
});
it('disables the playback-order select for single media-item types', async () => {
mockApi();
render(<PlaylistsScreen />);
+47 -7
View File
@@ -18,6 +18,7 @@ import {
import { Badge, Button, Card, ConfirmDialog, Dialog, IconButton, Input, Select, Spinner, Switch } from '../components';
import type { SelectOption } from '../components';
import {
ApiError,
createPlaylist,
createPlaylistGroup,
deletePlaylist,
@@ -27,7 +28,7 @@ import {
getMultiCollections,
getPlaylistById,
getPlaylistGroups,
getPlaylistItems,
getPlaylistItemsWithMeta,
getPlaylists,
getSmartCollections,
messageFromPlaylistError,
@@ -379,17 +380,32 @@ function PlaylistEditor({ playlistId, onBack, onSaved }: { playlistId: number; o
const [previewItems, setPreviewItems] = useState<PlaylistPreviewItem[] | null>(null);
const [previewMessage, setPreviewMessage] = useState<string | null>(null);
const [previewing, setPreviewing] = useState(false);
const [conflictOpen, setConflictOpen] = useState(false);
const [reloadKey, setReloadKey] = useState(0);
const activeRef = useRef(true);
// Concurrency ETag (issue #253): captured from the items GET, sent as If-Match on save, and
// replaced from the PUT response on every successful save.
const etagRef = useRef<string | null>(null);
useEffect(() => {
activeRef.current = true;
Promise.all([getPlaylistById(playlistId), getPlaylistItems(playlistId)])
.then(([playlist, loaded]) => {
// Read items + ETag FIRST, then the root metadata, so the ETag is never newer than the data
// the draft is built from (issue #253) — any resulting inconsistency fails safe via a 412 on
// save rather than a silent overwrite. These MUST be sequential, not Promise.all: a concurrent
// root read could return a stale name paired with the current items ETag, and a later save would
// then silently restore that stale name.
getPlaylistItemsWithMeta(playlistId)
.then(async (itemsMeta) => {
const playlist = await getPlaylistById(playlistId);
return [itemsMeta, playlist] as const;
})
.then(([itemsMeta, playlist]) => {
if (!activeRef.current) {
return;
}
const drafts = loaded.map(draftFromItem);
etagRef.current = itemsMeta.etag;
const drafts = itemsMeta.data.map(draftFromItem);
setName(playlist.name);
setItems(drafts);
setSelectedKey(drafts.length === 1 ? drafts[0].key : null);
@@ -404,7 +420,7 @@ function PlaylistEditor({ playlistId, onBack, onSaved }: { playlistId: number; o
return () => {
activeRef.current = false;
};
}, [playlistId]);
}, [playlistId, reloadKey]);
const selectedItem = items.find((item) => item.key === selectedKey) ?? null;
const selectedType = selectedItem?.collectionType;
@@ -506,15 +522,28 @@ function PlaylistEditor({ playlistId, onBack, onSaved }: { playlistId: number; o
setSaveError(null);
try {
await updatePlaylist(playlistId, buildRequest());
const { etag } = await updatePlaylist(playlistId, buildRequest(), etagRef.current);
etagRef.current = etag;
onSaved();
} catch (error) {
setSaveError(messageFromPlaylistError(error, 'Unable to save playlist'));
if (error instanceof ApiError && error.status === 412) {
// Another edit landed since we loaded — force a reload rather than overwriting it (#253).
setConflictOpen(true);
} else {
setSaveError(messageFromPlaylistError(error, 'Unable to save playlist'));
}
} finally {
setSaving(false);
}
};
const reloadAfterConflict = () => {
setConflictOpen(false);
setSaveError(null);
setState({ status: 'loading' });
setReloadKey((key) => key + 1);
};
const runPreview = async () => {
setPreviewing(true);
setPreviewMessage(null);
@@ -774,6 +803,17 @@ function PlaylistEditor({ playlistId, onBack, onSaved }: { playlistId: number; o
)}
</Card>
)}
<ConfirmDialog
cancelLabel="Keep editing"
confirmLabel="Reload"
message="This playlist was changed elsewhere since you opened it. Reload to get the latest version — your unsaved changes will be discarded."
onCancel={() => setConflictOpen(false)}
onConfirm={reloadAfterConflict}
open={conflictOpen}
title="Playlist changed elsewhere"
tone="danger"
/>
</div>
);
}
+30
View File
@@ -267,6 +267,36 @@ describe('SchedulesScreen — error + dirty handling', () => {
expect((screen.getByRole('button', { name: /^Save$/ }) as HTMLButtonElement).disabled).toBe(false);
});
it('412 on Save opens the conflict dialog; Reload discards the draft and reloads', async () => {
let putCount = 0;
const handle = await renderReady({
onRequest: (url, method) => {
if (url === '/api/schedules/1/items' && method === 'PUT') {
putCount += 1;
return jsonResponse({ title: 'Precondition Failed', detail: 'stale' }, 412);
}
return null;
}
});
// Make dirty, then Save → 412.
fireEvent.click(screen.getByRole('button', { name: /Add item/ }));
const getsBefore = handle.requests.filter((r) => r.url === '/api/schedules/1/items' && r.method === 'GET').length;
fireEvent.click(screen.getByRole('button', { name: /^Save$/ }));
// The conflict dialog appears (distinct from the generic save-error path).
await screen.findByText('Schedule changed elsewhere');
expect(putCount).toBe(1);
// Reload discards the draft and re-fetches the active schedule's items.
fireEvent.click(screen.getByRole('button', { name: /^Reload$/ }));
await waitFor(() =>
expect(handle.requests.filter((r) => r.url === '/api/schedules/1/items' && r.method === 'GET').length)
.toBeGreaterThan(getsBefore));
// Dialog closed; draft reset to the (single-item) server baseline.
await waitFor(() => expect(screen.queryByText('Schedule changed elsewhere')).toBeNull());
expect(within(screen.getByLabelText('Schedule lineup')).getAllByRole('listitem')).toHaveLength(1);
});
it('guards a schedule switch when dirty (confirm=false aborts)', async () => {
vi.spyOn(window, 'confirm').mockReturnValue(false);
const handle = await renderReady({ schedules: [schedule, { ...schedule, id: 2, name: 'Late' }] });

Some files were not shown because too many files have changed in this diff Show More