merge: origin/main (review-gates batch #222/#239) into feat/207-212

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ErsatzTV/Controllers/Api/ChannelController.cs

@@ -8,6 +8,7 @@ using ErsatzTV.Controllers.Api.Requests;
 using ErsatzTV.Core;
 using ErsatzTV.Core.Api.Channels;
 using ErsatzTV.Core.Domain;
+using ErsatzTV.Core.Interfaces.Locking;
 using ErsatzTV.Core.Scheduling;
 using ErsatzTV.Extensions;
 using MediatR;
@@ -17,7 +18,10 @@ using Microsoft.AspNetCore.Mvc;
 namespace ErsatzTV.Controllers.Api;
 
 [ApiController]
-public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerChannel, IMediator mediator)
+public class ChannelController(
+    ChannelWriter<IBackgroundServiceRequest> workerChannel,
+    IMediator mediator,
+    IEntityLocker entityLocker)
 {
     [HttpGet("/api/channels")]
     [EndpointGroupName("general")]
@@ -209,6 +213,7 @@ public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerCh
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     public async Task<IActionResult> ResetPlayout(
         string channelNumber,
         [FromQuery] PlayoutBuildMode? mode,
@@ -218,6 +223,14 @@ public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerCh
             await mediator.Send(new GetPlayoutIdByChannelNumber(channelNumber), cancellationToken);
         foreach (int playoutId in maybePlayoutId)
         {
+            // Mirror Blazor's EntityLocker gating: don't enqueue a rebuild while one is already in flight.
+            if (entityLocker.IsPlayoutLocked(playoutId))
+            {
+                return ApiResults.ConflictProblem(
+                    "Playout build in progress",
+                    "A build for this playout is currently in progress; try again once it completes.");
+            }
+
             PlayoutBuildMode buildMode = mode ?? await DefaultResetMode(playoutId, cancellationToken);
             await workerChannel.WriteAsync(new BuildPlayout(playoutId, buildMode), cancellationToken);
             return new OkResult();

ErsatzTV/Controllers/Api/LibrariesController.cs

@@ -1,6 +1,7 @@
 using ErsatzTV.Application.Libraries;
 using ErsatzTV.Core.Api.Libraries;
 using ErsatzTV.Core.Interfaces.Repositories;
+using ErsatzTV.Extensions;
 using MediatR;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
@@ -29,27 +30,23 @@ public class LibrariesController(ITelevisionRepository televisionRepository, IMe
     [HttpPost("/api/libraries/{id:int}/scan-show")]
     [Tags("Libraries")]
     [EndpointSummary("Scan show")]
+    [ProducesResponseType(StatusCodes.Status200OK)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(StatusCodes.Status400BadRequest)]
     public async Task<IActionResult> ScanShow(int id, [FromBody] ScanShowRequest request)
     {
-        if (string.IsNullOrWhiteSpace(request.ShowTitle))
+        Option<string> maybeTitle = await televisionRepository.GetShowTitle(id, request.ShowId);
+        foreach (string title in maybeTitle)
         {
-            return new BadRequestObjectResult(new { error = "ShowTitle is required" });
-        }
-
-        string trimmedTitle = request.ShowTitle.Trim();
-        Option<int> maybeShowId = await televisionRepository.GetShowIdByTitle(id, trimmedTitle);
-        foreach (int showId in maybeShowId)
-        {
-            bool result = await mediator.Send(new QueueShowScanByLibraryId(id, showId, trimmedTitle, request.DeepScan));
+            bool 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 new BadRequestObjectResult(
-            new { error = $"Unable to locate show with title {request.ShowTitle} in library {id}" });
+        return ApiResults.NotFoundProblem($"Show {request.ShowId} does not exist in library {id}.");
     }
 }
 
-public record ScanShowRequest(string ShowTitle, bool DeepScan = false);
+public record ScanShowRequest(int ShowId, bool DeepScan = false);

ErsatzTV/Controllers/Api/LogsController.cs

@@ -1,3 +1,4 @@
+using System.Linq.Expressions;
 using ErsatzTV.Application.Logs;
 using ErsatzTV.Core.Api.Logs;
 using MediatR;
@@ -11,22 +12,48 @@ public class LogsController(IMediator mediator) : ControllerBase
 {
     private const int MaxPageSize = 100;
 
+    // Mirrors the sortable columns from the legacy Blazor Logs.razor (MudTableSortLabel on
+    // Timestamp/Level; Message was never sortable there either).
+    private static readonly System.Collections.Generic.HashSet<string> AllowedSortFields =
+        new(StringComparer.OrdinalIgnoreCase) { "timestamp", "level" };
+
     [HttpGet("/api/logs", Name = "GetLogs")]
     [Tags("Logs")]
     [EndpointSummary("Get recent log entries")]
+    [EndpointDescription(
+        "sortField is validated against an allow-list (timestamp, level); an unrecognized value " +
+        "falls back to timestamp. sortDirection accepts asc/desc and falls back to desc (the " +
+        "pre-existing default, newest first).")]
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(PagedLogEntriesResponseModel), StatusCodes.Status200OK)]
     public async Task<PagedLogEntriesResponseModel> GetLogs(
         [FromQuery] int pageNum = 0,
         [FromQuery] int pageSize = 100,
         [FromQuery] string filter = "",
+        [FromQuery] string sortField = "timestamp",
+        [FromQuery] string sortDirection = "desc",
         CancellationToken cancellationToken = default)
     {
         int clampedPageNum = Math.Max(0, pageNum);
         int clampedPageSize = Math.Clamp(pageSize, 1, MaxPageSize);
 
+        string normalizedSortField = AllowedSortFields.Contains(sortField ?? string.Empty)
+            ? sortField!.ToLowerInvariant()
+            : "timestamp";
+        bool descending = !string.Equals(sortDirection, "asc", StringComparison.OrdinalIgnoreCase);
+
+        Expression<Func<LogEntryViewModel, object>> sortExpression = normalizedSortField switch
+        {
+            "level" => le => le.Level,
+            _ => le => le.Timestamp
+        };
+
         PagedLogEntriesViewModel result = await mediator.Send(
-            new GetRecentLogEntries(clampedPageNum, clampedPageSize, filter ?? string.Empty),
+            new GetRecentLogEntries(clampedPageNum, clampedPageSize, filter ?? string.Empty)
+            {
+                SortExpression = sortExpression,
+                SortDescending = descending
+            },
             cancellationToken);
 
         return new PagedLogEntriesResponseModel(

ErsatzTV/Controllers/Api/PlayoutController.cs

@@ -10,6 +10,7 @@ using ErsatzTV.Core.Api.Playouts;
 using ErsatzTV.Core.Api.Scheduling;
 using ErsatzTV.Core.Domain;
 using ErsatzTV.Core.Domain.Filler;
+using ErsatzTV.Core.Interfaces.Locking;
 using ErsatzTV.Extensions;
 using MediatR;
 using Microsoft.AspNetCore.Http;
@@ -18,10 +19,21 @@ using Microsoft.AspNetCore.Mvc;
 namespace ErsatzTV.Controllers.Api;
 
 [ApiController]
-public class PlayoutController(IMediator mediator) : ControllerBase
+public class PlayoutController(IMediator mediator, IEntityLocker entityLocker) : ControllerBase
 {
     private const int MaxPageSize = 100;
 
+    // Blazor disables per-playout Reset/Erase/Delete/Edit while a build is in flight
+    // (EntityLocker.IsPlayoutLocked); the API mirrors that invariant by rejecting any
+    // id-keyed mutation with 409 while the build lock is held. See docs/decisions.md 2026-07-10.
+    private const string BuildInProgressTitle = "Playout build in progress";
+
+    private const string BuildInProgressDetail =
+        "A build for this playout is currently in progress; try again once it completes.";
+
+    private static IActionResult PlayoutLockedProblem() =>
+        ApiResults.ConflictProblem(BuildInProgressTitle, BuildInProgressDetail);
+
     [HttpGet("/api/playouts", Name = "GetPlayouts")]
     [Tags("Playouts")]
     [EndpointSummary("List playouts")]
@@ -37,7 +49,7 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             await mediator.Send(new GetPagedPlayouts(query, pageNum, pageSize), cancellationToken);
         return new PagedPlayoutsResponseModel(
             result.TotalCount,
-            result.Page.Map(ToListItemResponse).ToList());
+            result.Page.Map(vm => ToListItemResponse(vm, entityLocker.IsPlayoutLocked(vm.PlayoutId))).ToList());
     }
 
     [HttpGet("/api/playouts/warnings/count", Name = "GetPlayoutWarningsCount")]
@@ -131,12 +143,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(PlayoutResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Update(
         int id,
         [Required] [FromBody] UpdatePlayoutDetailsRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -204,12 +222,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(PlayoutResponseModel), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> UpdateDefaultDeco(
         int id,
         [Required] [FromBody] UpdateDefaultDecoRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -284,12 +308,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<PlayoutAlternateScheduleResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> ReplaceAlternateSchedules(
         int id,
         [Required] [FromBody] ReplacePlayoutAlternateSchedulesRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -376,12 +406,18 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(typeof(List<PlayoutTemplateResponseModel>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> ReplaceTemplates(
         int id,
         [Required] [FromBody] ReplacePlayoutTemplatesRequest request,
         CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -515,6 +551,9 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointSummary("Reset all playouts")]
     [EndpointGroupName("general")]
     [ProducesResponseType(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.
     public async Task<IActionResult> ResetAll(CancellationToken cancellationToken)
     {
         await mediator.Send(new ResetAllPlayouts(), cancellationToken);
@@ -531,9 +570,15 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> EraseItems(int id, CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -563,9 +608,15 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> EraseItemsAndHistory(int id, CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Option<PlayoutNameViewModel> maybePlayout = await mediator.Send(new GetPlayoutById(id), cancellationToken);
         if (maybePlayout.IsNone)
         {
@@ -608,9 +659,15 @@ public class PlayoutController(IMediator mediator) : ControllerBase
     [EndpointGroupName("general")]
     [ProducesResponseType(StatusCodes.Status204NoContent)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ProblemDetails), StatusCodes.Status422UnprocessableEntity)]
     public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
     {
+        if (entityLocker.IsPlayoutLocked(id))
+        {
+            return PlayoutLockedProblem();
+        }
+
         Either<BaseError, Unit> result = await mediator.Send(new DeletePlayout(id), cancellationToken);
         return result.ToDeletedResult();
     }
@@ -722,7 +779,7 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             vm.EndDay,
             vm.EndYear);
 
-    private static PlayoutListItemResponseModel ToListItemResponse(PlayoutNameViewModel vm) =>
+    private static PlayoutListItemResponseModel ToListItemResponse(PlayoutNameViewModel vm, bool isLocked) =>
         new(
             vm.PlayoutId,
             vm.ChannelNumber,
@@ -731,7 +788,8 @@ public class PlayoutController(IMediator mediator) : ControllerBase
             vm.ScheduleName,
             vm.DbDailyRebuildTime,
             ToBuildStatus(vm.BuildStatus),
-            vm.PlayoutMode);
+            vm.PlayoutMode,
+            isLocked);
 
     private static PlayoutBuildStatusResponseModel ToBuildStatus(PlayoutBuildStatus buildStatus) =>
         buildStatus is null