#197 C3+C7 [HIGH]: DTO nullability noise + raw VMs + search pageNum before freeze #288

Closed
opened 2026-07-11 23:21:32 +02:00 by timothy · 3 comments
Owner

From the #197 cold API contract review. Phase 2 contract-freeze gate.

Findings:

  • C3 [HIGH]: 482 properties are required AND nullable — an artifact of <Nullable>disable</Nullable> in Core/Application, not real domain nullability. The signal is useless in both directions and freezes wrong (tightening name→non-null becomes a "breaking" change under strict validators).
  • C7 [MED]: 5 raw *ViewModels exposed directly (ChannelViewModel, MediaCollectionViewModel, ProgramScheduleViewModel, ResolutionViewModel, SmartCollectionViewModel — leak version/derived fields, violate api-conventions §2); /api/search has pageSize but no pageNum; page-envelope page nullability drifts across Paged* models.

Fix (Phase-2 #9): targeted honesty pass — #nullable enable across all ErsatzTV.Core/Api/ files (60/72 already have it), hand-audit the high-traffic DTOs so members are ? only when the mapper can emit null, pin the audited schemas' required/nullable sets. Cheap C7 fixes: wrap the 5 raw VMs in ResponseModels, add /api/search pageNum. NOT flipping <Nullable>enable on Core (thousands of warnings; nullable→non-null is an additive tightening later). Channel {id} vs {channelNumber} re-key = freeze-as-wart pending owner sign-off. Refs #197.

From the #197 cold API contract review. **Phase 2 contract-freeze gate.** **Findings:** - **C3 [HIGH]:** 482 properties are `required` AND nullable — an artifact of `<Nullable>disable</Nullable>` in Core/Application, not real domain nullability. The signal is useless in both directions and freezes wrong (tightening `name`→non-null becomes a "breaking" change under strict validators). - **C7 [MED]:** 5 raw `*ViewModel`s exposed directly (`ChannelViewModel`, `MediaCollectionViewModel`, `ProgramScheduleViewModel`, `ResolutionViewModel`, `SmartCollectionViewModel` — leak `version`/derived fields, violate api-conventions §2); `/api/search` has `pageSize` but no `pageNum`; page-envelope `page` nullability drifts across Paged* models. **Fix (Phase-2 #9):** targeted honesty pass — `#nullable enable` across all `ErsatzTV.Core/Api/` files (60/72 already have it), hand-audit the high-traffic DTOs so members are `?` only when the mapper can emit null, pin the audited schemas' `required`/`nullable` sets. Cheap C7 fixes: wrap the 5 raw VMs in ResponseModels, add `/api/search` `pageNum`. NOT flipping `<Nullable>enable` on Core (thousands of warnings; nullable→non-null is an additive tightening later). Channel `{id}` vs `{channelNumber}` re-key = freeze-as-wart pending owner sign-off. Refs #197.
timothy added the apipriority: mediumreview labels 2026-07-11 23:21:32 +02:00
Author
Owner

Bundling — Bundle C "contract cleanup" (single session / one PR with #287). Both regenerate v1.json/v1.d.ts + touch DTOs/OpenAPI → do together, one regen. Phase-2 freeze gate. Must precede or coordinate with #286 (versioning re-sweeps routes + regenerates everything). See #197 roadmap.

**Bundling — Bundle C "contract cleanup" (single session / one PR with #287).** Both regenerate `v1.json`/`v1.d.ts` + touch DTOs/OpenAPI → do together, one regen. Phase-2 freeze gate. **Must precede or coordinate with #286** (versioning re-sweeps routes + regenerates everything). See #197 roadmap.
timothy added the in-progress label 2026-07-12 01:36:19 +02:00
Author
Owner

Claiming — session started 2026-07-12. Bundled with #287 as Bundle C (worktree bundle-c-197-contract). Owner directed deciding the channel {id} → {channelNumber} re-key now (C7) instead of freeze-as-wart — recon + Fable design pass before implementing. Read/write key split is already settled (single key, per Bundle A session).

Claiming — session started 2026-07-12. Bundled with #287 as Bundle C (worktree `bundle-c-197-contract`). Owner directed **deciding the channel `{id}` → `{channelNumber}` re-key now** (C7) instead of freeze-as-wart — recon + Fable design pass before implementing. Read/write key split is already settled (single key, per Bundle A session).
Author
Owner

Done — merged to main (c40e78d8) via PR #296 (FF, CI green).

What was done:

  • C3 — #nullable enable on all ErsatzTV.Core/Api/ files (the 24 laggards flipped); members ? only where the mapper can emit null (honest MediaSources fields: PathReplacementResponseModel.LocalPath/RemotePath, RemoteMediaSourceItemResponseModel.Address/Name, RemoteLibraryResponseModel.Name — the write-path-validated Local*.Name/Path left non-null).
  • C7 — no /api/* action returns an Application VM anymore: CollectionController → new MediaCollectionResponseModel, ScheduleController → new ProgramScheduleResponseModel (both drop the header-only Version — SPA-verified it reads Version from the ETag header, never the body), SmartCollectionController → existing SmartCollectionResponseModel, ResolutionController.GetResolutionByName → ResolutionResponseModel, and the channel detail GET/writes → new ChannelDetailResponseModel (the full editable field set the channel editor needs, distinct from the lean list ChannelResponseModel; drops only derived webEncodedName). pageNum added to GET /api/search.
  • Channel playout/reset re-keyed {channelNumber} → {id:int} (owner-directed + Fable design verdict — Number is user-mutable, unusable as a stable key; new GetPlayoutIdByChannelId, by-number kept for HlsSessionWorker broadcast).

Files: 5 controllers, new ResponseModels + mappers (ChannelDetailResponseModel+ChannelLogoResponseModel, MediaCollectionResponseModel, ProgramScheduleResponseModel), ChannelRepository.GetChannel .Include(FFmpegProfile), new Application queries (GetChannelByIdForApi, GetPlayoutIdByChannelId), SPA client repoints (channels.ts/collections.ts/schedules.ts) + App.tsx reset call site, regen artifacts.

Docs: api-conventions.md §2/§3a/§7a, decisions.md (2026-07-12), rest-api.md reset route.

Verification: 1472 C# + 691 SPA tests; Codex + cold + re-review MERGEABLE; live E2E channel-editor round-trip PASS (all fields pre-fill + save + reload persist) and reset → POST /api/channels/1/playout/reset 202.

Follow-up (backlog nit): add channelId to PlayoutListItemResponseModel so the SPA reset button keys directly instead of resolving the id from channelStates.

**Done — merged to `main` (`c40e78d8`) via PR #296** (FF, CI green). **What was done**: - **C3** — `#nullable enable` on all `ErsatzTV.Core/Api/` files (the 24 laggards flipped); members `?` only where the mapper can emit null (honest MediaSources fields: `PathReplacementResponseModel.LocalPath/RemotePath`, `RemoteMediaSourceItemResponseModel.Address/Name`, `RemoteLibraryResponseModel.Name` — the write-path-validated `Local*.Name`/`Path` left non-null). - **C7** — no `/api/*` action returns an Application VM anymore: `CollectionController` → new `MediaCollectionResponseModel`, `ScheduleController` → new `ProgramScheduleResponseModel` (both drop the header-only `Version` — SPA-verified it reads `Version` from the ETag header, never the body), `SmartCollectionController` → existing `SmartCollectionResponseModel`, `ResolutionController.GetResolutionByName` → `ResolutionResponseModel`, and the **channel detail** GET/writes → new **`ChannelDetailResponseModel`** (the full editable field set the channel editor needs, distinct from the lean list `ChannelResponseModel`; drops only derived `webEncodedName`). `pageNum` added to `GET /api/search`. - **Channel `playout/reset` re-keyed** `{channelNumber}` → `{id:int}` (owner-directed + Fable design verdict — `Number` is user-mutable, unusable as a stable key; new `GetPlayoutIdByChannelId`, by-number kept for `HlsSessionWorker` broadcast). **Files**: 5 controllers, new ResponseModels + mappers (`ChannelDetailResponseModel`+`ChannelLogoResponseModel`, `MediaCollectionResponseModel`, `ProgramScheduleResponseModel`), `ChannelRepository.GetChannel` `.Include(FFmpegProfile)`, new Application queries (`GetChannelByIdForApi`, `GetPlayoutIdByChannelId`), SPA client repoints (`channels.ts`/`collections.ts`/`schedules.ts`) + `App.tsx` reset call site, regen artifacts. **Docs**: `api-conventions.md` §2/§3a/§7a, `decisions.md` (2026-07-12), `rest-api.md` reset route. **Verification**: 1472 C# + 691 SPA tests; Codex + cold + re-review MERGEABLE; **live E2E channel-editor round-trip PASS** (all fields pre-fill + save + reload persist) and reset → `POST /api/channels/1/playout/reset` 202. **Follow-up (backlog nit)**: add `channelId` to `PlayoutListItemResponseModel` so the SPA reset button keys directly instead of resolving the id from `channelStates`.
timothy removed the in-progress label 2026-07-12 12:26:54 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#288