feat(api): REST foundation + Channels CRUD (#34)

First slice of the REST API (ersatztv#2). Idiomatic REST over existing MediatR handlers; design in docs/rest-api.md.

Foundation: NotFoundError : BaseError (Core) to split 404 from 422; ApiResults mapping helpers (Either/Option -> 201+Location / 200 / 204 / 404 / 422), additive (existing *ToActionResult untouched); ApiKeyAuthorizationFilter (optional X-Api-Key on mutating actions, gated by Api:WriteKey, no-op when unset) — independent of the IPTV JWT toggle so Jellyfin/Dispatcharr reads are unaffected, applied at controller-class level so every mutating action incl. ResetPlayout is covered fail-safe.

Channels: POST /api/channels (201+Location), PUT/{id} (200/404), DELETE/{id} (204/404), GET/{id} (200/404). Request DTOs -> existing commands; responses reuse ChannelViewModel. Ported page-only validations into handlers (ShowInEpg-when-disabled, external-logo-URL, Group NotEmpty) + FFmpegProfile/Watermark/Filler existence on update for create-parity. Fixed a latent 500: the .Filter(c>0) existence pattern threw TaskCanceledException on not-found; rewritten to AnyAsync.

Tests (NUnit, TZ=UTC): handler success/404/422, ApiResults mapping, API-key filter, controller status/Location/mapping, a controller-security regression net, and a create->read->delete EF integration test on a new in-memory SQLite harness. ErsatzTV.Tests 46/46, Architecture 5/5.

Refs #34

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ErsatzTV/Controllers/Api/ChannelController.cs

@@ -1,9 +1,13 @@
-using System.Threading.Channels;
+using System.ComponentModel.DataAnnotations;
+using System.Threading.Channels;
 using ErsatzTV.Application;
 using ErsatzTV.Application.Channels;
 using ErsatzTV.Application.Playouts;
+using ErsatzTV.Controllers.Api.Requests;
+using ErsatzTV.Core;
 using ErsatzTV.Core.Api.Channels;
 using ErsatzTV.Core.Scheduling;
+using ErsatzTV.Extensions;
 using ErsatzTV.Filters;
 using MediatR;
 using Microsoft.AspNetCore.Mvc;
@@ -11,12 +15,72 @@ using Microsoft.AspNetCore.Mvc;
 namespace ErsatzTV.Controllers.Api;
 
 [ApiController]
+// Apply the optional API-key control at the controller level so that EVERY mutating action
+// (including future ones) is covered by default; the filter no-ops on read methods (GET) and
+// when Api:WriteKey is unset, preserving the open LAN behavior. This is fail-safe: a developer
+// adding a new write endpoint here cannot accidentally leave it unauthenticated.
+[ServiceFilter(typeof(ApiKeyAuthorizationFilter))]
 public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerChannel, IMediator mediator)
 {
     [HttpGet("/api/channels")]
     [EndpointGroupName("general")]
     public async Task<List<ChannelResponseModel>> GetAll() => await mediator.Send(new GetAllChannelsForApi());
 
+    [HttpGet("/api/channels/{id:int}", Name = "GetChannelById")]
+    [Tags("Channels")]
+    [EndpointSummary("Get a channel by id")]
+    [EndpointGroupName("general")]
+    public async Task<IActionResult> GetById(int id, CancellationToken cancellationToken)
+    {
+        Option<ChannelViewModel> result = await mediator.Send(new GetChannelById(id), cancellationToken);
+        return result.ToGetResult();
+    }
+
+    [HttpPost("/api/channels")]
+    [Tags("Channels")]
+    [EndpointSummary("Create a channel")]
+    [EndpointGroupName("general")]
+    public async Task<IActionResult> Create(
+        [Required] [FromBody] CreateChannelRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, CreateChannelResult> result = await mediator.Send(request.ToCommand(), cancellationToken);
+        return await result.Match(
+            Left: error => Task.FromResult(error.ToErrorResult()),
+            Right: async created =>
+            {
+                Option<ChannelViewModel> channel =
+                    await mediator.Send(new GetChannelById(created.ChannelId), cancellationToken);
+                return channel.Match(
+                    Some: vm => (IActionResult)new CreatedResult($"/api/channels/{vm.Id}", vm),
+                    None: () => new NotFoundResult());
+            });
+    }
+
+    [HttpPut("/api/channels/{id:int}")]
+    [Tags("Channels")]
+    [EndpointSummary("Update a channel")]
+    [EndpointGroupName("general")]
+    public async Task<IActionResult> Update(
+        int id,
+        [Required] [FromBody] UpdateChannelRequest request,
+        CancellationToken cancellationToken)
+    {
+        Either<BaseError, ChannelViewModel> result =
+            await mediator.Send(request.ToCommand(id), cancellationToken);
+        return result.ToUpdatedResult();
+    }
+
+    [HttpDelete("/api/channels/{id:int}")]
+    [Tags("Channels")]
+    [EndpointSummary("Delete a channel")]
+    [EndpointGroupName("general")]
+    public async Task<IActionResult> Delete(int id, CancellationToken cancellationToken)
+    {
+        Either<BaseError, Unit> result = await mediator.Send(new DeleteChannel(id), cancellationToken);
+        return result.ToDeletedResult();
+    }
+
     [HttpPost("/api/channels/{channelNumber}/playout/reset")]
     [Tags("Channels")]
     [EndpointSummary("Reset channel playout")]
@@ -32,24 +96,4 @@ public class ChannelController(ChannelWriter<IBackgroundServiceRequest> workerCh
 
         return new NotFoundResult();
     }
-
-    // for debugging by fast-forwarding a playout
-    // [HttpPost("/api/channels/{channelNumber}/playout/continue")]
-    // public async Task<IActionResult> ContinuePlayout(string channelNumber, [FromQuery] int days = 1)
-    // {
-    //     Option<int> maybePlayoutId = await mediator.Send(new GetPlayoutIdByChannelNumber(channelNumber));
-    //     foreach (int playoutId in maybePlayoutId)
-    //     {
-    //         DateTimeOffset start = DateTimeOffset.Now;
-    //         for (int i = 0; i < 24 * days; i++)
-    //         {
-    //             await workerChannel.WriteAsync(new BuildPlayout(playoutId, PlayoutBuildMode.Continue, start));
-    //             start += TimeSpan.FromHours(1);
-    //         }
-    //
-    //         return new OkResult();
-    //     }
-    //
-    //     return new NotFoundResult();
-    // }
 }

ErsatzTV/Controllers/Api/Requests/CreateChannelRequest.cs

@@ -0,0 +1,69 @@
+using ErsatzTV.Application.Artworks;
+using ErsatzTV.Application.Channels;
+using ErsatzTV.Core.Domain;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+/// <summary>
+///     JSON request body for creating a channel. Mirrors <see cref="CreateChannel" />; decoupling the
+///     API contract from the MediatR command keeps the wire format stable as the command evolves.
+/// </summary>
+public record CreateChannelRequest(
+    string Name,
+    string Number,
+    string Group,
+    string Categories,
+    int FFmpegProfileId,
+    double? SlugSeconds,
+    ArtworkContentTypeModel Logo,
+    ChannelStreamSelectorMode StreamSelectorMode,
+    string StreamSelector,
+    string PreferredAudioLanguageCode,
+    string PreferredAudioTitle,
+    ChannelPlayoutSource PlayoutSource,
+    ChannelPlayoutMode PlayoutMode,
+    int? MirrorSourceChannelId,
+    TimeSpan? PlayoutOffset,
+    StreamingMode StreamingMode,
+    int? WatermarkId,
+    int? FallbackFillerId,
+    string PreferredSubtitleLanguageCode,
+    ChannelSubtitleMode SubtitleMode,
+    ChannelMusicVideoCreditsMode MusicVideoCreditsMode,
+    string MusicVideoCreditsTemplate,
+    ChannelSongVideoMode SongVideoMode,
+    ChannelTranscodeMode TranscodeMode,
+    ChannelIdleBehavior IdleBehavior,
+    bool IsEnabled,
+    bool ShowInEpg)
+{
+    public CreateChannel ToCommand() =>
+        new(
+            Name,
+            Number,
+            Group,
+            Categories,
+            FFmpegProfileId,
+            SlugSeconds,
+            Logo,
+            StreamSelectorMode,
+            StreamSelector,
+            PreferredAudioLanguageCode,
+            PreferredAudioTitle,
+            PlayoutSource,
+            PlayoutMode,
+            MirrorSourceChannelId,
+            PlayoutOffset,
+            StreamingMode,
+            WatermarkId,
+            FallbackFillerId,
+            PreferredSubtitleLanguageCode,
+            SubtitleMode,
+            MusicVideoCreditsMode,
+            MusicVideoCreditsTemplate,
+            SongVideoMode,
+            TranscodeMode,
+            IdleBehavior,
+            IsEnabled,
+            ShowInEpg);
+}

ErsatzTV/Controllers/Api/Requests/UpdateChannelRequest.cs

@@ -0,0 +1,70 @@
+using ErsatzTV.Application.Artworks;
+using ErsatzTV.Application.Channels;
+using ErsatzTV.Core.Domain;
+
+namespace ErsatzTV.Controllers.Api.Requests;
+
+/// <summary>
+///     JSON request body for updating a channel. The channel id comes from the route, not the body;
+///     all other fields mirror <see cref="UpdateChannel" />.
+/// </summary>
+public record UpdateChannelRequest(
+    string Name,
+    string Number,
+    string Group,
+    string Categories,
+    int FFmpegProfileId,
+    double? SlugSeconds,
+    ArtworkContentTypeModel Logo,
+    ChannelStreamSelectorMode StreamSelectorMode,
+    string StreamSelector,
+    string PreferredAudioLanguageCode,
+    string PreferredAudioTitle,
+    ChannelPlayoutSource PlayoutSource,
+    ChannelPlayoutMode PlayoutMode,
+    int? MirrorSourceChannelId,
+    TimeSpan? PlayoutOffset,
+    StreamingMode StreamingMode,
+    int? WatermarkId,
+    int? FallbackFillerId,
+    string PreferredSubtitleLanguageCode,
+    ChannelSubtitleMode SubtitleMode,
+    ChannelMusicVideoCreditsMode MusicVideoCreditsMode,
+    string MusicVideoCreditsTemplate,
+    ChannelSongVideoMode SongVideoMode,
+    ChannelTranscodeMode TranscodeMode,
+    ChannelIdleBehavior IdleBehavior,
+    bool IsEnabled,
+    bool ShowInEpg)
+{
+    public UpdateChannel ToCommand(int channelId) =>
+        new(
+            channelId,
+            Name,
+            Number,
+            Group,
+            Categories,
+            FFmpegProfileId,
+            SlugSeconds,
+            Logo,
+            StreamSelectorMode,
+            StreamSelector,
+            PreferredAudioLanguageCode,
+            PreferredAudioTitle,
+            PlayoutSource,
+            PlayoutMode,
+            MirrorSourceChannelId,
+            PlayoutOffset,
+            StreamingMode,
+            WatermarkId,
+            FallbackFillerId,
+            PreferredSubtitleLanguageCode,
+            SubtitleMode,
+            MusicVideoCreditsMode,
+            MusicVideoCreditsTemplate,
+            SongVideoMode,
+            TranscodeMode,
+            IdleBehavior,
+            IsEnabled,
+            ShowInEpg);
+}