diff --git a/ErsatzTV.Application/Channels/Mapper.cs b/ErsatzTV.Application/Channels/Mapper.cs index 52bb4311f..1dfdfd51e 100644 --- a/ErsatzTV.Application/Channels/Mapper.cs +++ b/ErsatzTV.Application/Channels/Mapper.cs @@ -96,7 +96,10 @@ internal static class Mapper channel.ShowInEpg); } - internal static ChannelResponseModel ProjectToResponseModel(Channel channel, int playoutCount) => + internal static ChannelResponseModel ProjectToResponseModel( + Channel channel, + int playoutCount, + bool iptvJwtEnabled) => new( channel.Id, channel.Number, @@ -110,7 +113,8 @@ internal static class Mapper channel.IsEnabled, channel.ShowInEpg, playoutCount, - GetLogoUrl(channel)); + GetLogoUrl(channel), + GetPreview(channel.StreamingMode, channel.Number, iptvJwtEnabled, channel.IsEnabled, playoutCount)); internal static ResolutionViewModel ProjectToViewModel(Resolution resolution) => new(resolution.Height, resolution.Width); @@ -174,4 +178,68 @@ internal static class Mapper StreamingMode.HttpLiveStreamingSegmenter => "HLS Segmenter", _ => throw new ArgumentOutOfRangeException(nameof(channel)) }; + +#nullable enable + internal static ChannelPreviewResponseModel GetPreview( + StreamingMode streamingMode, + string channelNumber, + bool iptvJwtEnabled, + bool isEnabled, + int playoutCount) + { + // Precedence among the three Unavailable causes (checked in this order; the first match wins): + // 1. JWT enabled — a host-wide auth configuration; nothing the operator can fix per-channel. + // 2. channel disabled — an explicit operator choice; IptvController 404s a disabled channel, so + // preview must not even try. + // 3. no playout — the channel could theoretically play once scheduled, but a manifest + // request against it blocks indefinitely today; catch it before that happens. + // + // /iptv/* is gated by ConditionalIptvAuthorizeFilter only when JWT is configured, and the + // "jwt" scheme does not accept the SPA's ctv-session cookie. Nothing mints a JWT for the + // SPA today, so preview cannot run at all in that configuration. + if (iptvJwtEnabled) + { + return new ChannelPreviewResponseModel( + ChannelPreviewAvailability.Unavailable, + null, + "IPTV JWT authentication is enabled"); + } + + if (!isEnabled) + { + return new ChannelPreviewResponseModel( + ChannelPreviewAvailability.Unavailable, + null, + "Channel is disabled"); + } + + if (playoutCount == 0) + { + return new ChannelPreviewResponseModel( + ChannelPreviewAvailability.Unavailable, + null, + "Channel has no playout"); + } + + return streamingMode switch + { + StreamingMode.HttpLiveStreamingSegmenter or StreamingMode.HttpLiveStreamingDirect => + new ChannelPreviewResponseModel( + ChannelPreviewAvailability.Available, + $"/iptv/channel/{channelNumber}.m3u8", + null), + + // A browser cannot play video/mp2t. Forcing ?mode=segmenter yields a playable stream, + // but one that does not exercise the channel's configured Transport Stream pipeline — + // the SPA labels this result accordingly. + StreamingMode.TransportStream or StreamingMode.TransportStreamHybrid => + new ChannelPreviewResponseModel( + ChannelPreviewAvailability.ForcedHlsOnly, + $"/iptv/channel/{channelNumber}.m3u8?mode=segmenter", + null), + + _ => throw new ArgumentOutOfRangeException(nameof(streamingMode)) + }; + } +#nullable restore } diff --git a/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApi.cs b/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApi.cs index 58a1a9ea0..2b1b705e9 100644 --- a/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApi.cs +++ b/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApi.cs @@ -1,5 +1,5 @@ -using ErsatzTV.Core.Api.Channels; +using ErsatzTV.Core.Api.Channels; namespace ErsatzTV.Application.Channels; -public record GetAllChannelsForApi : IRequest>; +public record GetAllChannelsForApi(bool IptvJwtEnabled) : IRequest>; diff --git a/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApiHandler.cs b/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApiHandler.cs index 08c5148c3..7b539acb8 100644 --- a/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApiHandler.cs +++ b/ErsatzTV.Application/Channels/Queries/GetAllChannelsForApiHandler.cs @@ -13,6 +13,6 @@ public class GetAllChannelsForApiHandler(IChannelRepository channelRepository) CancellationToken cancellationToken) { IEnumerable channels = Optional(await channelRepository.GetAll(cancellationToken)).Flatten(); - return channels.Map(c => ProjectToResponseModel(c, GetPlayoutsCount(c))).ToList(); + return channels.Map(c => ProjectToResponseModel(c, GetPlayoutsCount(c), request.IptvJwtEnabled)).ToList(); } } diff --git a/ErsatzTV.Core/Api/Channels/ChannelPreviewResponseModel.cs b/ErsatzTV.Core/Api/Channels/ChannelPreviewResponseModel.cs new file mode 100644 index 000000000..b098ef917 --- /dev/null +++ b/ErsatzTV.Core/Api/Channels/ChannelPreviewResponseModel.cs @@ -0,0 +1,32 @@ +#nullable enable + +namespace ErsatzTV.Core.Api.Channels; + +/// Server-declared browser-preview capability for a channel. +/// +/// The SPA renders and acts on this; it never derives preview eligibility itself (see +/// docs/decisions.md, api.healthcheck-remediation-dto for the same pattern). Deriving it in the +/// SPA would mean keying behavior off the human-readable StreamingMode label. +/// +public record ChannelPreviewResponseModel( + // One of ChannelPreviewAvailability's values. A plain string (not a C# enum), which keeps the + // OpenAPI schema simple, but the tradeoff is that the generated TypeScript types this as a bare + // `string`, not a literal union — the SPA hand-maintains its own `ChannelPreviewAvailability` + // union (web/src/api/channels.ts) and narrows against it, rather than getting one for free. + string Availability, + // Rooted, directly-usable HLS manifest URL; null when Availability is Unavailable. + string? ManifestUrl, + // Human-readable reason; non-null only when Availability is Unavailable. + string? UnavailableReason); + +public static class ChannelPreviewAvailability +{ + /// The channel's configured mode is browser-playable; preview exercises the real pipeline. + public const string Available = "Available"; + + /// Configured for Transport Stream; preview must force an HLS session and is content-only. + public const string ForcedHlsOnly = "ForcedHlsOnly"; + + /// Preview cannot run at all (IPTV JWT auth is enabled and the SPA cannot mint a token). + public const string Unavailable = "Unavailable"; +} diff --git a/ErsatzTV.Core/Api/Channels/ChannelResponseModel.cs b/ErsatzTV.Core/Api/Channels/ChannelResponseModel.cs index 4eec0fefb..3d9976c8d 100644 --- a/ErsatzTV.Core/Api/Channels/ChannelResponseModel.cs +++ b/ErsatzTV.Core/Api/Channels/ChannelResponseModel.cs @@ -19,4 +19,6 @@ public record ChannelResponseModel( int PlayoutCount, // Rooted, directly-usable logo URL for the SPA's ; null when the channel has no logo // (SPA then renders the generated initials fallback). See ErsatzTV.Application Channels.Mapper.GetLogoUrl. - string? Logo); + string? Logo, + // Server-declared browser-preview capability; see ChannelPreviewResponseModel. + ChannelPreviewResponseModel Preview); diff --git a/ErsatzTV.Tests/Application/Channels/ChannelPreviewTests.cs b/ErsatzTV.Tests/Application/Channels/ChannelPreviewTests.cs new file mode 100644 index 000000000..2109dcdc0 --- /dev/null +++ b/ErsatzTV.Tests/Application/Channels/ChannelPreviewTests.cs @@ -0,0 +1,126 @@ +using ErsatzTV.Application.Channels; +using ErsatzTV.Core.Api.Channels; +using ErsatzTV.Core.Domain; +using NUnit.Framework; +using Shouldly; + +namespace ErsatzTV.Tests.Application.Channels; + +[TestFixture] +public class ChannelPreviewTests +{ + [TestCase(StreamingMode.HttpLiveStreamingSegmenter)] + [TestCase(StreamingMode.HttpLiveStreamingDirect)] + public void HlsModes_Are_Available_With_Plain_Manifest_Url(StreamingMode mode) + { + ChannelPreviewResponseModel result = + Mapper.GetPreview(mode, "12.1", iptvJwtEnabled: false, isEnabled: true, playoutCount: 1); + + result.Availability.ShouldBe("Available"); + result.ManifestUrl.ShouldBe("/iptv/channel/12.1.m3u8"); + result.UnavailableReason.ShouldBeNull(); + } + + [TestCase(StreamingMode.TransportStream)] + [TestCase(StreamingMode.TransportStreamHybrid)] + public void TransportStream_Modes_Are_ForcedHlsOnly(StreamingMode mode) + { + ChannelPreviewResponseModel result = + Mapper.GetPreview(mode, "12.1", iptvJwtEnabled: false, isEnabled: true, playoutCount: 1); + + result.Availability.ShouldBe("ForcedHlsOnly"); + result.ManifestUrl.ShouldBe("/iptv/channel/12.1.m3u8?mode=segmenter"); + result.UnavailableReason.ShouldBeNull(); + } + + [TestCase(StreamingMode.HttpLiveStreamingSegmenter)] + [TestCase(StreamingMode.HttpLiveStreamingDirect)] + [TestCase(StreamingMode.TransportStream)] + [TestCase(StreamingMode.TransportStreamHybrid)] + public void Jwt_Enabled_Makes_Every_Mode_Unavailable(StreamingMode mode) + { + ChannelPreviewResponseModel result = + Mapper.GetPreview(mode, "12.1", iptvJwtEnabled: true, isEnabled: true, playoutCount: 1); + + result.Availability.ShouldBe("Unavailable"); + result.ManifestUrl.ShouldBeNull(); + result.UnavailableReason.ShouldBe("IPTV JWT authentication is enabled"); + } + + [Test] + public void Disabled_Channel_Is_Unavailable() + { + ChannelPreviewResponseModel result = Mapper.GetPreview( + StreamingMode.HttpLiveStreamingSegmenter, + "12.1", + iptvJwtEnabled: false, + isEnabled: false, + playoutCount: 1); + + result.Availability.ShouldBe("Unavailable"); + result.ManifestUrl.ShouldBeNull(); + result.UnavailableReason.ShouldBe("Channel is disabled"); + } + + [Test] + public void Zero_Playout_Count_Is_Unavailable() + { + ChannelPreviewResponseModel result = Mapper.GetPreview( + StreamingMode.HttpLiveStreamingSegmenter, + "12.1", + iptvJwtEnabled: false, + isEnabled: true, + playoutCount: 0); + + result.Availability.ShouldBe("Unavailable"); + result.ManifestUrl.ShouldBeNull(); + result.UnavailableReason.ShouldBe("Channel has no playout"); + } + + [Test] + public void Jwt_Enabled_Takes_Precedence_Over_Disabled_Channel() + { + // Both causes are true at once: JWT enabled (checked first) must win over the channel being + // disabled (checked second), per the precedence order documented on GetPreview. + ChannelPreviewResponseModel result = Mapper.GetPreview( + StreamingMode.HttpLiveStreamingSegmenter, + "12.1", + iptvJwtEnabled: true, + isEnabled: false, + playoutCount: 0); + + result.Availability.ShouldBe("Unavailable"); + result.ManifestUrl.ShouldBeNull(); + result.UnavailableReason.ShouldBe("IPTV JWT authentication is enabled"); + } + + [Test] + public void Disabled_Channel_Takes_Precedence_Over_Zero_Playout_Count() + { + // Both causes are true at once: channel disabled (checked second) must win over zero + // playouts (checked third), per the precedence order documented on GetPreview. + ChannelPreviewResponseModel result = Mapper.GetPreview( + StreamingMode.HttpLiveStreamingSegmenter, + "12.1", + iptvJwtEnabled: false, + isEnabled: false, + playoutCount: 0); + + result.Availability.ShouldBe("Unavailable"); + result.ManifestUrl.ShouldBeNull(); + result.UnavailableReason.ShouldBe("Channel is disabled"); + } + + [Test] + public void Channel_Number_Is_Used_Verbatim_In_The_Manifest_Url() + { + ChannelPreviewResponseModel result = Mapper.GetPreview( + StreamingMode.HttpLiveStreamingSegmenter, + "7", + iptvJwtEnabled: false, + isEnabled: true, + playoutCount: 1); + + result.ManifestUrl.ShouldBe("/iptv/channel/7.m3u8"); + } +} diff --git a/ErsatzTV.Tests/Application/Channels/GetAllChannelsForApiHandlerTests.cs b/ErsatzTV.Tests/Application/Channels/GetAllChannelsForApiHandlerTests.cs index bc7de11de..4eb3f1d57 100644 --- a/ErsatzTV.Tests/Application/Channels/GetAllChannelsForApiHandlerTests.cs +++ b/ErsatzTV.Tests/Application/Channels/GetAllChannelsForApiHandlerTests.cs @@ -35,7 +35,9 @@ public class GetAllChannelsForApiHandlerTests ]); var handler = new GetAllChannelsForApiHandler(repository); - List result = await handler.Handle(new GetAllChannelsForApi(), CancellationToken.None); + List result = await handler.Handle( + new GetAllChannelsForApi(IptvJwtEnabled: false), + CancellationToken.None); ChannelResponseModel channel = result.ShouldHaveSingleItem(); channel.Id.ShouldBe(7); @@ -61,7 +63,9 @@ public class GetAllChannelsForApiHandlerTests .Returns([NewChannel(new Artwork { ArtworkKind = ArtworkKind.Logo, Path = "abc123.png" })]); var handler = new GetAllChannelsForApiHandler(repository); - List result = await handler.Handle(new GetAllChannelsForApi(), CancellationToken.None); + List result = await handler.Handle( + new GetAllChannelsForApi(IptvJwtEnabled: false), + CancellationToken.None); // Uploaded logos are addressed as "iptv/logos/{file}"; the browse DTO roots it (leading slash) so // the SPA's resolves against the site root regardless of the current SPA route. @@ -76,7 +80,9 @@ public class GetAllChannelsForApiHandlerTests .Returns([NewChannel(new Artwork { ArtworkKind = ArtworkKind.Logo, Path = "https://example.com/logo.png" })]); var handler = new GetAllChannelsForApiHandler(repository); - List result = await handler.Handle(new GetAllChannelsForApi(), CancellationToken.None); + List result = await handler.Handle( + new GetAllChannelsForApi(IptvJwtEnabled: false), + CancellationToken.None); // An absolute external URL is directly usable and must pass through unchanged (no leading slash added). result.ShouldHaveSingleItem().Logo.ShouldBe("https://example.com/logo.png"); diff --git a/ErsatzTV.Tests/Controllers/OpenApiSerializerContractTests.cs b/ErsatzTV.Tests/Controllers/OpenApiSerializerContractTests.cs index c37c624de..c28e27d54 100644 --- a/ErsatzTV.Tests/Controllers/OpenApiSerializerContractTests.cs +++ b/ErsatzTV.Tests/Controllers/OpenApiSerializerContractTests.cs @@ -1,7 +1,9 @@ using System.Text.Json; +using ErsatzTV.Application.Channels; using ErsatzTV.Core.Api.Channels; using ErsatzTV.Core.Api.MediaItems; using ErsatzTV.Core.Api.Settings; +using ErsatzTV.Core.Domain; using ErsatzTV.Serialization; using Newtonsoft.Json; using Newtonsoft.Json.Converters; @@ -153,7 +155,8 @@ public class OpenApiSerializerContractTests true, true, 2, - "/iptv/logos/logo.png"); + "/iptv/logos/logo.png", + Mapper.GetPreview(StreamingMode.HttpLiveStreamingSegmenter, "1", false, true, 2)); private static string FindOpenApiDocument() { diff --git a/ErsatzTV/Controllers/Api/ChannelController.cs b/ErsatzTV/Controllers/Api/ChannelController.cs index 5fe037530..d4ffc6436 100644 --- a/ErsatzTV/Controllers/Api/ChannelController.cs +++ b/ErsatzTV/Controllers/Api/ChannelController.cs @@ -26,7 +26,8 @@ public class ChannelController( { [HttpGet("/api/v1/channels")] [EndpointGroupName("general")] - public async Task> GetAll() => await mediator.Send(new GetAllChannelsForApi()); + public async Task> GetAll() => + await mediator.Send(new GetAllChannelsForApi(JwtHelper.IsEnabled)); [HttpGet("/api/v1/channels/state")] [Tags("Channels")] diff --git a/ErsatzTV/wwwroot/openapi/v1.json b/ErsatzTV/wwwroot/openapi/v1.json index 7dd4a1583..4a314b650 100644 --- a/ErsatzTV/wwwroot/openapi/v1.json +++ b/ErsatzTV/wwwroot/openapi/v1.json @@ -23895,6 +23895,31 @@ ], "type": "string" }, + "ChannelPreviewResponseModel": { + "required": [ + "availability", + "manifestUrl", + "unavailableReason" + ], + "type": "object", + "properties": { + "availability": { + "type": "string" + }, + "manifestUrl": { + "type": [ + "null", + "string" + ] + }, + "unavailableReason": { + "type": [ + "null", + "string" + ] + } + } + }, "ChannelResponseModel": { "required": [ "id", @@ -23909,7 +23934,8 @@ "isEnabled", "showInEpg", "playoutCount", - "logo" + "logo", + "preview" ], "type": "object", "properties": { @@ -23957,6 +23983,9 @@ "null", "string" ] + }, + "preview": { + "$ref": "#/components/schemas/ChannelPreviewResponseModel" } } }, diff --git a/docs/api-conventions.md b/docs/api-conventions.md index 717610f3d..df7120e85 100644 --- a/docs/api-conventions.md +++ b/docs/api-conventions.md @@ -85,6 +85,11 @@ Exemplars: (`record NamedIdResponseModel(int Id, string Name)`) when a response DTO needs to embed a list of named references (e.g. a schedule item's `watermarks` / `graphicsElements`) rather than minting a one-off `(int, string)` record per domain. +- **Server-declared capability fields.** When the SPA must decide whether an action is possible, + the server declares it as structured metadata on the response DTO (`{Availability, ...}`) rather + than the SPA inferring it from a display string. Examples: health-check remediation + (`api.healthcheck-remediation-dto`) and channel preview capability + (`ChannelPreviewResponseModel`). - **Flatten polymorphic VMs for the wire**: when an Application ViewModel is an abstract/polymorphic record (subtypes carrying extra fields), the OpenAPI schema only captures the base shape — promote every subtype field to a nullable top-level member on a flat response DTO and pattern-match the diff --git a/docs/blazor-route-parity.md b/docs/blazor-route-parity.md index 6b5ecab24..7ffffb6e1 100644 --- a/docs/blazor-route-parity.md +++ b/docs/blazor-route-parity.md @@ -193,6 +193,7 @@ redirect (nothing to redirect *from*). Recorded here so the parity tracker is co | SPA route | Screen | Notes | |---|---|---| | `/app/auto-tune` | `AutoTuneScreen` | **Net-new (#69).** Auto-Tune wizard: bulk-generate channels from library metadata (axes: TV Shows / TV Genres / Movie Genres) → preview & select → bulk-create, over the PR1 `POST /api/v1/channels/auto-tune/preview` + `POST /api/v1/channels/auto-tune` endpoints. Additive/non-destructive; no Blazor equivalent. Per-channel DetailPanel deferred to #383. | +| `/app/channels` (Play button) | `ChannelPreviewPanel` | **Net-new (#60).** In-browser channel preview: the channels-list Play button opens a `SlideOver` HLS player driven by the server-declared `Preview` field on `ChannelResponseModel` (`Available` / `ForcedHlsOnly` / `Unavailable`) — not derived client-side. HLS-mode channels preview directly; Transport Stream channels require an explicit opt-in and always show a caveat that the check does not exercise the channel's configured pipeline; JWT-enabled deployments show `Unavailable` (`/iptv/*` doesn't accept the SPA's session cookie). No Blazor predecessor — this is an addition, not a parity item. See `docs/decisions.md` → `api.channel-preview-capability`. | ## Section 3 — BLAZOR-ONLY (blocking issues) diff --git a/docs/decisions.md b/docs/decisions.md index fa3d5c749..f534c6c99 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -3441,3 +3441,32 @@ leaving the shared tree dirty is the one outcome that would make this script a n **The enum lives in `ErsatzTV.Core`, not the Application command, on purpose.** The OpenAPI string-enum pass (`Startup.UseStringEnumSchemas`) scans the Core assembly wholesale; an enum defined in `ErsatzTV.Application` renders as a bare `integer` in the spec while every sibling advanced-options enum (`PlaybackOrder`, `ChannelSubtitleMode`, …) is a string enum. Placing `CreateChannelFromLineupClearField` in `ErsatzTV.Core/Api/Channels/` makes the wire contract a string enum by construction, matching its siblings. **SPA is id-fields-first; the API is complete ahead of the UI.** The Channel Builder + Auto-Tune DetailPanel re-add a real "None" option to the five id selects (watermark + fillers) — the pickers #89 had degraded to "Inherit"-only — routed through a `CLEAR` overrides sentinel folded into `advanced.clear` at request-build time (`applyOverridesToRequest`, so the sentinel never leaks as a field value). The three string clear-fields are covered by the backend enum for machine clients (MCP) but the SPA text inputs keep "empty = inherit"; adding a tri-state to those inputs is deferred, not blocked. This is the deliberate "REST API is a real audience" posture (`rest-api-purpose-mcp-and-new-ui`). +## 2026-07-21 — Browser channel preview is a server-declared per-channel capability (#60) + +`key: api.channel-preview-capability` · `status: active` · `since: 2026-07-21` · `supersedes: none` · `superseded-by: none` +**Rule:** Whether a channel can be previewed in the browser is declared by the server, not derived by the SPA, as an additive `Preview` field (`{Availability, ManifestUrl, UnavailableReason}`) on `ChannelResponseModel`. +**Signals:** a Play button that does nothing; preview eligibility inferred from a display string; a green preview on a Transport Stream channel being read as validating its configured pipeline · paths: `ErsatzTV.Core/Api/Channels/ChannelPreviewResponseModel.cs`, `ErsatzTV.Application/Channels/Mapper.cs`, `web/src/screens/channels/ChannelPreviewPanel.tsx` · issues: #60 +**Mechanics:** `Mapper.GetPreview(StreamingMode, channelNumber, iptvJwtEnabled, isEnabled, playoutCount)` is pure; `JwtHelper.IsEnabled` is read only at `ChannelController.GetAll` and passed in + +`ChannelPreviewAvailability` is one of `Available`, `ForcedHlsOnly`, or `Unavailable`, computed in one +place from the real `StreamingMode` enum plus JWT status. The SPA renders and acts on it and derives +nothing — deriving it client-side would mean keying behavior off `Mapper.GetStreamingMode`'s +human-readable display label, where a copy tweak would silently break playback. + +`Unavailable` now covers three causes, checked in this order (first match wins): JWT enabled, the +channel is disabled (`IptvController` 404s a disabled channel, so preview must not even try), and +the channel has zero playouts (a manifest request against one blocks indefinitely). Only the JWT +case was in scope at first pass; the other two were keying preview on `StreamingMode` + JWT alone, +so a disabled or playout-less channel was declared `Available` and then failed confusingly. + +Only the two HLS modes are browser-playable; a browser cannot play the `video/mp2t` that the +Transport Stream modes serve over `/iptv/*`. Those are declared `ForcedHlsOnly`: preview is offered +only as an explicit opt-in that requests `/iptv/channel/{n}.m3u8?mode=segmenter`, and is always shown +with a caveat that the check does not exercise the channel's configured pipeline. Fatal HLS errors +are reported, never auto-recovered — a diagnostic surface must show the fault rather than retry past +it; a user-initiated Retry re-issues the manifest request via a real `playToken` because the manifest +GET starts a server-side session, so a byte-identical repeat URL would otherwise be a no-op. + +`/iptv/*` does not accept the SPA's `ctv-session` cookie, and nothing mints a JWT for the SPA, so +under a JWT-enabled deployment preview is declared `Unavailable` with the reason `IPTV JWT +authentication is enabled` rather than failing silently against a 401. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 13f7c2d70..60e28b0ae 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -11,6 +11,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera | `api.artwork-rooted-urls` | API response DTOs return artwork as rooted, directly-usable URLs (plus passthrough for absolute/proxy URLs), never relative Blazor-convention paths. | 2026-07-07 | [link](../decisions.md#2026-07-07--api-artwork-contract-rooted-urls-produced-server-side) | | `api.async-op-contract` | Queue-triggering `/api/*` endpoints normalize onto one contract — 202 Accepted (queued), 404 (missing entity), 409 (lock held), 422 (domain precondition) — with Trakt as the reference implementation; playout list/detail GETs also carry an `isLocked` observability flag as the HTTP-observable substitute for a live push channel. | 2026-07-11 | [link](../decisions.md#2026-07-11--async-op-api-contract-normalization--playout-build-observability--f9-scan-endpoints-235) | | `api.channel-health-signal` | Channel health rides `ChannelResponseModel`/`ChannelListItem` DTOs as a raw `int PlayoutCount` fact (free — `GetAll` already `Include`s `Playouts`), not a new endpoint, not `/channels/state` (runtime-liveness cadence), and not a derived `ChannelHealth` enum (would freeze policy before the #383/#384 auto-tune status taxonomy lands). | 2026-07-17 | [link](../decisions.md#2026-07-17--channel-health-on-the-api--the-raw-playoutcount-fact-on-the-list-dto-not-a-derived-status-enum-72) | +| `api.channel-preview-capability` | Whether a channel can be previewed in the browser is declared by the server, not derived by the SPA, as an additive `Preview` field (`{Availability, ManifestUrl, UnavailableReason}`) on `ChannelResponseModel`. | 2026-07-21 | [link](../decisions.md#2026-07-21--browser-channel-preview-is-a-server-declared-per-channel-capability-60) | | `api.decode-by-id` | Endpoints that decode/expand opaque stored state accept a database row id and resolve it server-side rather than round-tripping client-supplied serialized state. | 2026-07-07 | [link](../decisions.md#2026-07-07--decode-style-endpoints-take-a-row-id-and-look-up-server-side) | | `api.from-lineup-clear-to-none` | `POST /api/v1/channels/from-lineup` (and the Auto-Tune per-channel `advanced`, which reuses the same DTO) distinguishes *inherit* from *clear-to-none* with a typed `clear` enum list on `advanced`. A field left null/omitted still inherits the template value (unchanged for every existing client); naming a field in `clear` forces it to none on the new channel even when the template sets one. Sending both a set value and a clear for the same field is a validation error. | 2026-07-21 | [link](../decisions.md#2026-07-21--from-lineup-advanced-overrides-express-clear-to-none-via-a-typed-clear-enum-list-135) | | `api.healthcheck-remediation-dto` | Health-check remediation is server-declared `{Kind, Target}` metadata on an additive DTO field; the SPA renders/acts on it, it doesn't derive labels itself. | 2026-07-17 | [link](../decisions.md#2026-07-17--health-check-remediation-is-server-declared-kind-target-on-an-additive-dto-the-spa-acts-on-it-164) | diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md index aa6972da5..32f537a44 100644 --- a/docs/spa-conventions.md +++ b/docs/spa-conventions.md @@ -209,6 +209,22 @@ manifest. **In tests, mock `hls.js` wholesale** (`vi.mock('hls.js', …)` with a touches a real `MediaSource`; assert the manifest URL via the mocked `loadSource` spy (see `PlaybackTroubleshootingScreen.test.tsx`). +It also takes an optional `onError(message)` wired to `Hls.Events.ERROR` (fatal errors only) and, +on the Safari native path, the `