Rerun collections: the list endpoint returns a null selection for every row, and the detail GET 500s or nulls for five media types #671

Closed
opened 2026-07-27 00:00:10 +02:00 by timothy · 2 comments
Owner

Found while working #651 (searchable library-browse pickers) and confirmed by reading the handlers. All server-side, all predating #651. The SPA side is defended in #651's branch — the editor now merges rather than replaces, so a stored id is never cleared — but that is a client-side guard over a server-side defect, and the underlying data is still missing.

1. The list endpoint returns a null selection for EVERY rerun collection

ErsatzTV.Application/MediaCollections/Queries/GetPagedRerunCollectionsHandler.cs has no .Include() calls at all and runs AsNoTracking():

IQueryable<RerunCollection> query = dbContext.RerunCollections.AsNoTracking();
…
.Map(list => list.Map(ProjectToViewModel).ToList());

But Mapper.ProjectToViewModel(RerunCollection) reads four navigations — collection.Collection, collection.MultiCollection, collection.SmartCollection, collection.MediaItem. With no eager load and no lazy loading configured, all four are null for every row, of every collection type.

Effect in production: the list badge renders Collection · with no name, for every rerun collection. The editor is entirely dependent on the detail GET to recover the selection.

2. Mapper returns null for RemoteStream, and 500s on two types

ErsatzTV.Application/MediaCollections/Mapper.cs — the collection.MediaItem switch enumerates Show, Season, Artist, Movie, Episode, MusicVideo, OtherVideo, Song, Image and then falls through _ => null. RemoteStream hits the fallthrough, so a successful 200 carries a null selection.

Worse, the detail handler (GetRerunCollectionByIdHandler) loads sufficient metadata only for Show, Season, Artist and Movie. The remaining types go through unloaded navigations:

Type Detail GET behaviour
RemoteStream 200, null selection (_ => null)
Image 200, null selection
Episode 500 — NRE on the unloaded Season navigation in EpisodeTitle
MusicVideo 500 — NRE on the unloaded Artist navigation
Song / OtherVideo 200, id resolves, name is a placeholder

An endpoint returning 500 for two of its supported types is the sharp end of this.

Why it wasn't caught

Both the id and the name are derived from the same eager-loaded navigation, so the id is only ever as available as the name — there is no state where the API knows which item is selected but not what it's called. That coupling is why the client-side symptom looked like a naming problem rather than a loading one.

Done-when

  • GetPagedRerunCollectionsHandler eager-loads the navigations ProjectToViewModel reads, so list rows carry a real selection id and name
  • GetRerunCollectionByIdHandler loads sufficient metadata for every supported type — no 500 for Episode or MusicVideo
  • Mapper's _ => null fallthrough no longer silently drops RemoteStream (handle it, or make the unhandled case loud)
  • A test covers every ProgramScheduleItemCollectionType / media type the entity permits, not a sample — the defect here is precisely the types nobody enumerated
  • The N+1 / query cost of the added includes is considered for the paged list path
  • Adversarial review passed

Context: #651. The client-side guard that makes this survivable lives in feat/651-searchable-pickers (RerunCollectionsScreen merges the refresh instead of replacing it) — that guard should stay even after this is fixed.

Found while working #651 (searchable library-browse pickers) and **confirmed by reading the handlers**. All server-side, all predating #651. The SPA side is defended in #651's branch — the editor now merges rather than replaces, so a stored id is never cleared — but that is a client-side guard over a server-side defect, and the underlying data is still missing. ## 1. The list endpoint returns a null selection for EVERY rerun collection `ErsatzTV.Application/MediaCollections/Queries/GetPagedRerunCollectionsHandler.cs` has **no `.Include()` calls at all** and runs `AsNoTracking()`: ```csharp IQueryable<RerunCollection> query = dbContext.RerunCollections.AsNoTracking(); … .Map(list => list.Map(ProjectToViewModel).ToList()); ``` But `Mapper.ProjectToViewModel(RerunCollection)` reads four navigations — `collection.Collection`, `collection.MultiCollection`, `collection.SmartCollection`, `collection.MediaItem`. With no eager load and no lazy loading configured, **all four are null for every row, of every collection type.** **Effect in production:** the list badge renders `Collection · ` with no name, for every rerun collection. The editor is entirely dependent on the detail GET to recover the selection. ## 2. `Mapper` returns null for `RemoteStream`, and 500s on two types `ErsatzTV.Application/MediaCollections/Mapper.cs` — the `collection.MediaItem switch` enumerates Show, Season, Artist, Movie, Episode, MusicVideo, OtherVideo, Song, Image and then falls through `_ => null`. **`RemoteStream` hits the fallthrough**, so a successful 200 carries a null selection. Worse, the detail handler (`GetRerunCollectionByIdHandler`) loads sufficient metadata only for Show, Season, Artist and Movie. The remaining types go through unloaded navigations: | Type | Detail GET behaviour | |---|---| | RemoteStream | 200, **null** selection (`_ => null`) | | Image | 200, **null** selection | | Episode | **500** — NRE on the unloaded `Season` navigation in `EpisodeTitle` | | MusicVideo | **500** — NRE on the unloaded `Artist` navigation | | Song / OtherVideo | 200, id resolves, name is a placeholder | An endpoint returning **500** for two of its supported types is the sharp end of this. ## Why it wasn't caught Both the id and the name are derived from the *same* eager-loaded navigation, so the id is only ever as available as the name — there is no state where the API knows *which* item is selected but not *what it's called*. That coupling is why the client-side symptom looked like a naming problem rather than a loading one. ## Done-when - [x] `GetPagedRerunCollectionsHandler` eager-loads the navigations `ProjectToViewModel` reads, so list rows carry a real selection id and name - [x] `GetRerunCollectionByIdHandler` loads sufficient metadata for **every** supported type — no 500 for Episode or MusicVideo - [x] `Mapper`'s `_ => null` fallthrough no longer silently drops `RemoteStream` (handle it, or make the unhandled case loud) - [x] A test covers **every** `ProgramScheduleItemCollectionType` / media type the entity permits, not a sample — the defect here is precisely the types nobody enumerated - [x] The N+1 / query cost of the added includes is considered for the paged list path - [x] Adversarial review passed Context: #651. The client-side guard that makes this survivable lives in `feat/651-searchable-pickers` (`RerunCollectionsScreen` merges the refresh instead of replacing it) — that guard should stay even after this is fixed.
timothy added the bugapipriority: medium labels 2026-07-27 00:00:10 +02:00
Author
Owner

Claiming this (Claude Code orchestrator session, 2026-07-28). Four-way claim check clean: no open PR references #671, git ls-remote --heads origin '*671*' empty, no prior comments, origin/main fresh at d4ea1584c.

Claiming this (Claude Code orchestrator session, 2026-07-28). Four-way claim check clean: no open PR references #671, `git ls-remote --heads origin '*671*'` empty, no prior comments, `origin/main` fresh at `d4ea1584c`.
timothy added the in-progress label 2026-07-28 18:21:06 +02:00
Author
Owner

Closing record

Outcome: Shipped in #692 (merged as 036bcfc5a). Both handlers now project through one shared RerunCollectionQueryExtensions.IncludeSelectionDetails(); the media-item switch — previously duplicated verbatim for RerunCollection and PlaylistItem — is one ProjectMediaItemToViewModel that handles RemoteStream and never falls through to null; every metadata navigation in MediaItems.Mapper degrades to "???" rather than throwing.

One correction to the issue body: RemoteStream does have a mapper overload, but it returns RemoteStreamViewModel, an unrelated record, and C# will not overload on return type — so there was no named projection to fall back on. Hence the new ProjectToNamedViewModel.

Root cause: The selected id and the display name are read off the same eager-loaded navigation, so the id is only ever as available as the name. The list handler had no .Include() calls at all and ran AsNoTracking() (which suppresses navigation fixup), and the by-id handler covered 4 of 10 media types. The issue body identified this coupling correctly — and it is also why the symptom looked cosmetic (an unlabelled badge) when the real harm was the dropped id silently clearing a stored selection.

Decisions/conventions changed: Added api.selection-projection-include-chain — one shared include chain per projected aggregate (joining the #229 IncludeScheduleItemDetails precedent, extended from the write path to the read path), and a flattening switch that never ends in _ => null.

Reusable knowledge:

  • Adding an eager-load can CREATE a 500. SongMetadata.Artists is a nullable EF primitive collection (JSON in one column, not a navigation) that FallbackMetadataProvider leaves unassigned for a song whose tags fail to read; string.Join throws ArgumentNullException, not NullReferenceException. A "null navigation" audit misses it and so does a grep for NullReferenceException. It was already a live 500 on GET /api/v1/playlists/{id}/items before this branch (verified against origin/main) — eager-loading it on the rerun list merely made the same throw reachable on a second path.
  • Sweep by FIELD, not by the call site the issue names. Fixing the rerun site left an identical unguarded join in Playouts/Mapper.GetDisplayTitle, likewise live, feeding the playout guide, troubleshooting, media-item info and channel states. LibraryBrowseItemMapper already wrote Artists ?? [], so the nullability was known in-tree — those sites were simply never swept.
  • A "not a placeholder" assertion cannot see a missing NESTED include leg. Dropping Episode → Season → Show still renders s00e04 - Selected episode, placeholder-free. Pin the whole expected string.
  • Derive a type matrix from the production predicate (IsSupportedSelectionType) rather than hand-listing it, so a newly-supported type joins coverage automatically and trips a loud default:.

Verification: All 7 test projects green (4,444 passed, 0 failed). Every mechanism was removed in turn and the suite quoted red before restoring it — stripping the list chain failed all 13 types on "lost its selected id"; the original 4-type chain failed exactly the 6 types named here; reverting the bare dereferences reproduced NullReferenceException for Episode/MusicVideo; reverting either Artists guard reproduced ArgumentNullException; reverting the chapter fix rendered ErsatzTV.Core.Domain.Song (Chapter 1). CI green on 2249a806c, with Build & test at 25m35s (a real run, not the docs-only fast path). Four review rounds: one cross-family (Codex) and three cold same-family. No live-E2E: this is a read-path projection change with no write path and no API contract change.

Deferred: #690 (paged TotalCount ignores the search query — pre-existing, different axis) and #691 (SongVideoGenerator dereferences Artists/AlbumArtists unguarded on the playback path, where the right fallback needs thought rather than a mechanical ?? []).

Docs updated: docs/api-conventions.md (new §2a, "Flattening a tagged-union selection (read path)"), docs/decisions/records/api/selection-projection-include-chain.md, and the regenerated docs/decisions/README.md catalog.

## Closing record **Outcome:** Shipped in #692 (merged as `036bcfc5a`). Both handlers now project through one shared `RerunCollectionQueryExtensions.IncludeSelectionDetails()`; the media-item switch — previously duplicated verbatim for `RerunCollection` and `PlaylistItem` — is one `ProjectMediaItemToViewModel` that handles `RemoteStream` and never falls through to null; every metadata navigation in `MediaItems.Mapper` degrades to `"???"` rather than throwing. One correction to the issue body: `RemoteStream` **does** have a mapper overload, but it returns `RemoteStreamViewModel`, an unrelated record, and C# will not overload on return type — so there was no named projection to fall back on. Hence the new `ProjectToNamedViewModel`. **Root cause:** The selected **id** and the display **name** are read off the *same* eager-loaded navigation, so the id is only ever as available as the name. The list handler had no `.Include()` calls at all and ran `AsNoTracking()` (which suppresses navigation fixup), and the by-id handler covered 4 of 10 media types. The issue body identified this coupling correctly — and it is also why the symptom *looked* cosmetic (an unlabelled badge) when the real harm was the dropped id silently clearing a stored selection. **Decisions/conventions changed:** Added `api.selection-projection-include-chain` — one shared include chain per projected aggregate (joining the `#229` `IncludeScheduleItemDetails` precedent, extended from the write path to the read path), and a flattening switch that never ends in `_ => null`. **Reusable knowledge:** - **Adding an eager-load can CREATE a 500.** `SongMetadata.Artists` is a nullable EF *primitive collection* (JSON in one column, **not** a navigation) that `FallbackMetadataProvider` leaves unassigned for a song whose tags fail to read; `string.Join` throws `ArgumentNullException`, not `NullReferenceException`. A "null navigation" audit misses it and so does a grep for `NullReferenceException`. It was already a live 500 on `GET /api/v1/playlists/{id}/items` before this branch (verified against `origin/main`) — eager-loading it on the rerun list merely made the same throw reachable on a second path. - **Sweep by FIELD, not by the call site the issue names.** Fixing the rerun site left an identical unguarded join in `Playouts/Mapper.GetDisplayTitle`, likewise live, feeding the playout guide, troubleshooting, media-item info and channel states. `LibraryBrowseItemMapper` already wrote `Artists ?? []`, so the nullability was known in-tree — those sites were simply never swept. - **A "not a placeholder" assertion cannot see a missing NESTED include leg.** Dropping `Episode → Season → Show` still renders `s00e04 - Selected episode`, placeholder-free. Pin the whole expected string. - Derive a type matrix from the production predicate (`IsSupportedSelectionType`) rather than hand-listing it, so a newly-supported type joins coverage automatically and trips a loud `default:`. **Verification:** All 7 test projects green (4,444 passed, 0 failed). Every mechanism was removed in turn and the suite quoted **red** before restoring it — stripping the list chain failed all 13 types on "lost its selected id"; the original 4-type chain failed exactly the 6 types named here; reverting the bare dereferences reproduced `NullReferenceException` for Episode/MusicVideo; reverting either `Artists` guard reproduced `ArgumentNullException`; reverting the chapter fix rendered `ErsatzTV.Core.Domain.Song (Chapter 1)`. CI green on `2249a806c`, with `Build & test` at **25m35s** (a real run, not the docs-only fast path). Four review rounds: one cross-family (Codex) and three cold same-family. No live-E2E: this is a read-path projection change with no write path and no API contract change. **Deferred:** #690 (paged `TotalCount` ignores the search query — pre-existing, different axis) and #691 (`SongVideoGenerator` dereferences `Artists`/`AlbumArtists` unguarded on the *playback* path, where the right fallback needs thought rather than a mechanical `?? []`). **Docs updated:** `docs/api-conventions.md` (new §2a, "Flattening a tagged-union selection (read path)"), `docs/decisions/records/api/selection-projection-include-chain.md`, and the regenerated `docs/decisions/README.md` catalog.
timothy removed the in-progress label 2026-07-28 20:56:58 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#671