Scheduling API hardening follow-ups from #144 S1/S2 reviews #172

Closed
opened 2026-07-07 18:51:47 +02:00 by timothy · 2 comments
Owner

Non-blocking findings from the adversarial reviews of PRs #170/#171 and the S2 templates slice, consolidated so they don't get lost. None block #144 parity.

  1. Null name in Create/Replace/Copy bodies → NRE → 500 across Block/Template (and likely future Deco) request DTOs: they lack #nullable so the spec marks strings nullable, and handlers do request.Name.Length. Fix class-wide: [property: Required] on the request records or IsNullOrEmpty guards in ToCommand.
  2. Negative-id "(none)" placeholder rows leak to API consumers: GetAllBlocksHandler/GetAllTemplatesHandler synthesize a dummy row per empty group (id = −groupId, name "(none)", minutes 0) to drive the Blazor grouped table. TemplatesScreen filters id > 0 client-side; BlocksScreen doesn't. Prefer filtering at the controllers (SPA renders empty groups from the groups endpoint anyway).
  3. Exact-duplicate template items bypass overlap validation: BlockTemplateItem is a record; the overlap loop skips on value-equality, so two identical rows (same blockId+startTime) both persist. SPA's index-based check catches it; API-only gap. Upstream-shared.
  4. Referential validation gap in ReplaceBlockItems: collectionId/mediaItemId/smartCollectionId/watermarkIds/graphicsElementIds are only null-checked, not existence-checked — garbage ids → DbUpdateException 500. Shared with the schedules precedent (ReplaceProgramScheduleItems).
  5. No lightweight exists query: Delete/pre-check paths load full lists or 3-Include aggregates (BlockController.DeleteGroup loads all groups; PlayoutController pre-checks via GetPlayoutById). One AnyAsync-style exists query family would cover all controllers.
  6. Unreachable 404 ProducesResponseType on group-create actions (copied from precedent) — trim when touching those controllers.
  7. Route Name= missing on PlayoutController Create/Delete/Update (pre-existing) — align when touching.

From earlier sessions (still relevant): GET /api/search dispatches its 10 per-kind queries serially (Task.WhenAll safe); Trakt matched-items link still points at classic /search; /api/logs + /api/troubleshoot/info unauthenticated GETs.


Disposition (2026-07-13 session — verified against main) — PR #325

Most findings were resolved or ratified deliberate since 2026-07-07; three were genuinely live and are fixed:

  • #1 → FIXED (10 handlers). 9 genuine 500s (Block/Template/DecoTemplate/Deco Create+Replace/Update + UpdateFFmpegProfile) + 1 empty-name persist (CreatePlaylist, DTO coalesces null→"").
  • #3 → FIXED (index-based overlap loop).
  • #6 → FIXED (trimmed unreachable 404 on all 4 create-group actions: Block/Template/Deco/DecoTemplate; Playlist already had none; OpenAPI regenerated + metadata test synced).
  • #2, #4 → WON'T-FIX (deliberate-documented) — api-conventions §8 / §3b.
  • #7 → WON'T-FIX (moot) — OperationIdOpenApiTransformer (#197 Bundle C) synthesizes stable operationIds; adding Name= risks renaming generated SPA client methods.
  • #5 → deferred (perf refactor, not a bug — leave as backlog nit; not blocking the API freeze).
  • Tail → already FIXED: unauth /api/logs+/api/troubleshoot/info now [RequiresAuthentication]; Trakt link points at /app/search; /api/search already Task.WhenAll.
  • Follow-up filed: #327 (playlist rename does no name validation — pre-existing create/update asymmetry, backlog).
  • Note: rebased onto #286 (/api/v1 versioning sweep) after it merged mid-session; create-group routes are now /api/v1/.../groups.

Done-when

  • Adversarial review passed (independent cold pass over the diff + fix-commit re-review → MERGEABLE @ 2e4e07a2)
  • All genuinely-live findings fixed or explicitly dispositioned (per-finding, above)
  • Regression tests green (null/blank-name → 422 across 10 handlers; duplicate-template-items → 422)
  • Docs updated in the same PR (decisions.md entry + api-conventions.md §3b null-safe-validation bullet)
  • OpenAPI artifacts regenerated + committed (v1.json)
  • CI green on the PR head (2e4e07a2 — all jobs incl. Build & test, Formatting, EF migration, API docs)
Non-blocking findings from the adversarial reviews of PRs #170/#171 and the S2 templates slice, consolidated so they don't get lost. None block #144 parity. 1. **Null `name` in Create/Replace/Copy bodies → NRE → 500** across Block/Template (and likely future Deco) request DTOs: they lack `#nullable` so the spec marks strings nullable, and handlers do `request.Name.Length`. Fix class-wide: `[property: Required]` on the request records or IsNullOrEmpty guards in ToCommand. 2. **Negative-id "(none)" placeholder rows leak to API consumers**: `GetAllBlocksHandler`/`GetAllTemplatesHandler` synthesize a dummy row per empty group (id = −groupId, name "(none)", minutes 0) to drive the Blazor grouped table. TemplatesScreen filters `id > 0` client-side; BlocksScreen doesn't. Prefer filtering at the controllers (SPA renders empty groups from the groups endpoint anyway). 3. **Exact-duplicate template items bypass overlap validation**: `BlockTemplateItem` is a record; the overlap loop skips on value-equality, so two identical rows (same blockId+startTime) both persist. SPA's index-based check catches it; API-only gap. Upstream-shared. 4. **Referential validation gap in ReplaceBlockItems**: collectionId/mediaItemId/smartCollectionId/watermarkIds/graphicsElementIds are only null-checked, not existence-checked — garbage ids → DbUpdateException 500. Shared with the schedules precedent (`ReplaceProgramScheduleItems`). 5. **No lightweight exists query**: Delete/pre-check paths load full lists or 3-Include aggregates (BlockController.DeleteGroup loads all groups; PlayoutController pre-checks via GetPlayoutById). One `AnyAsync`-style exists query family would cover all controllers. 6. **Unreachable 404 ProducesResponseType on group-create actions** (copied from precedent) — trim when touching those controllers. 7. **Route `Name=` missing** on PlayoutController Create/Delete/Update (pre-existing) — align when touching. From earlier sessions (still relevant): `GET /api/search` dispatches its 10 per-kind queries serially (Task.WhenAll safe); Trakt matched-items link still points at classic /search; `/api/logs` + `/api/troubleshoot/info` unauthenticated GETs. --- ## Disposition (2026-07-13 session — verified against `main`) — PR #325 Most findings were resolved or ratified deliberate since 2026-07-07; three were genuinely live and are fixed: - **#1 → FIXED** (10 handlers). 9 genuine 500s (Block/Template/DecoTemplate/Deco Create+Replace/Update + `UpdateFFmpegProfile`) + 1 empty-name persist (`CreatePlaylist`, DTO coalesces null→""). - **#3 → FIXED** (index-based overlap loop). - **#6 → FIXED** (trimmed unreachable 404 on **all 4** create-group actions: Block/Template/Deco/DecoTemplate; Playlist already had none; OpenAPI regenerated + metadata test synced). - **#2, #4 → WON'T-FIX (deliberate-documented)** — api-conventions §8 / §3b. - **#7 → WON'T-FIX (moot)** — `OperationIdOpenApiTransformer` (#197 Bundle C) synthesizes stable operationIds; adding `Name=` risks renaming generated SPA client methods. - **#5 → deferred** (perf refactor, not a bug — leave as backlog nit; not blocking the API freeze). - **Tail → already FIXED**: unauth `/api/logs`+`/api/troubleshoot/info` now `[RequiresAuthentication]`; Trakt link points at `/app/search`; `/api/search` already `Task.WhenAll`. - Follow-up filed: **#327** (playlist rename does no name validation — pre-existing create/update asymmetry, backlog). - Note: rebased onto #286 (`/api/v1` versioning sweep) after it merged mid-session; create-group routes are now `/api/v1/.../groups`. ## Done-when - [x] Adversarial review passed (independent cold pass over the diff + fix-commit re-review → MERGEABLE @ 2e4e07a2) - [x] All genuinely-live findings fixed or explicitly dispositioned (per-finding, above) - [x] Regression tests green (null/blank-name → 422 across 10 handlers; duplicate-template-items → 422) - [x] Docs updated in the same PR (decisions.md entry + api-conventions.md §3b null-safe-validation bullet) - [x] OpenAPI artifacts regenerated + committed (v1.json) - [x] CI green on the PR head (2e4e07a2 — all jobs incl. Build & test, Formatting, EF migration, API docs)
timothy added the apibugpriority: mediumreview labels 2026-07-11 19:03:44 +02:00
timothy added the in-progress label 2026-07-13 00:05:37 +02:00
Author
Owner

claiming — session started 2026-07-13. Picked as the highest-ranked pickable #197 gate-cluster item (review+api+bug); it's the "other in-flight /api work" that should land before #286's route sweep (which is claimed but sequenced LAST by design).

Heads-up on staleness: these findings are from 2026-07-07 and a lot of API hardening has landed since. On a first read of docs/api-conventions.md, several are now ratified deliberate or already fixed:

  • #4 (referential validation gap in ReplaceBlockItems) → documented deliberate exception (§3b handler-hardening checklist: "don't fix without discussing").
  • #2 (negative-id "(none)" rows) → documented deliberate synthesized row (§8).
  • #7 (missing Name=) → moot: OperationIdOpenApiTransformer (#197 Bundle C) synthesizes stable operationIds for the ~90 Name=-less ops.
  • The unauthenticated /api/logs + /api/troubleshoot/info tail → fixed: §9 puts Troubleshoot/Logs/Settings/Maintenance behind [RequiresAuthentication] (#280–#285/#295).

Verifying every finding against current main before implementing; will fix only what's genuinely live (candidate residue: #1 null-name→500, #3 duplicate-item overlap bypass, the Trakt matched-items link, cosmetic ProducesResponseType trims) and close with a per-finding disposition.

Coordination note for the #286 owner: this touches controllers/DTOs/handlers (Block/Template/Playout) but only method-body validation + attributes, not route strings — low overlap with your /api/v1 route-string sweep, and it's meant to precede it.

claiming — session started 2026-07-13. Picked as the highest-ranked pickable #197 gate-cluster item (`review`+`api`+`bug`); it's the "other in-flight `/api` work" that should land *before* #286's route sweep (which is claimed but sequenced LAST by design). Heads-up on staleness: these findings are from 2026-07-07 and a lot of API hardening has landed since. On a first read of `docs/api-conventions.md`, several are now **ratified deliberate or already fixed**: - **#4** (referential validation gap in ReplaceBlockItems) → documented **deliberate exception** (§3b handler-hardening checklist: "don't fix without discussing"). - **#2** (negative-id "(none)" rows) → documented **deliberate synthesized row** (§8). - **#7** (missing `Name=`) → moot: `OperationIdOpenApiTransformer` (#197 Bundle C) synthesizes stable operationIds for the ~90 `Name=`-less ops. - The unauthenticated `/api/logs` + `/api/troubleshoot/info` tail → **fixed**: §9 puts `Troubleshoot`/`Logs`/`Settings`/`Maintenance` behind `[RequiresAuthentication]` (#280–#285/#295). Verifying every finding against current `main` before implementing; will fix only what's genuinely live (candidate residue: **#1** null-name→500, **#3** duplicate-item overlap bypass, the Trakt matched-items link, cosmetic `ProducesResponseType` trims) and close with a per-finding disposition. Coordination note for the #286 owner: this touches controllers/DTOs/handlers (Block/Template/Playout) but only method-body validation + attributes, not route strings — low overlap with your `/api/v1` route-string sweep, and it's meant to precede it.
Author
Owner

Closed — PR #325 merged to main (2e4e07a2, fast-forward)

What was done. Cleared the still-live findings from this consolidated list; most had been resolved or ratified deliberate since 2026-07-07 (verified against main first, rather than fixing stale nits).

Root cause (finding #1, the real bug). Request DTOs carry no #nullable context (api-conventions §2), so a string Name binds null from name: null/an omitted field; there's no implicit [Required], no FluentValidation validator for these commands, and no global exception filter — so a handler doing request.Name.Length threw an unguarded NullReferenceException that surfaced as HTTP 500. The group-create + copy handlers were already safe because they route the name through the null-safe NotEmpty/NotLongerThan combinator; the create/replace handlers used a raw .Length check. Fixed class-wide with a string.IsNullOrWhiteSpace(...) || guard (minimal blast radius, preserves each handler's error message + 422 mapping).

Fixed (3 live findings):

  • #1 — null/empty name → 500 across 10 handlers (Block/Template/DecoTemplate/Deco Create+Replace/Update + UpdateFFmpegProfile; CreatePlaylist was an empty-name persist, not a 500). Now 422; also rejects empty/whitespace names.
  • #3 — exact-duplicate template items bypassed overlap validation (record value-equality skip) → now index-based, rejected 422.
  • #6 — unreachable 404 ProducesResponseType trimmed from all 4 create-group actions.

Dispositioned (not fixed): #2, #4 → deliberate-documented (api-conventions §8/§3b); #7 → moot (OperationIdOpenApiTransformer, #197 Bundle C); #5 → deferred perf nit; the auth/Trakt/search tail → already fixed on main.

Files changed. 10 handlers (ErsatzTV.Application/{Scheduling,MediaCollections,FFmpegProfiles}/Commands/*Handler.cs); 4 controllers (Block/Template/Deco/DecoTemplate — 404 trims); ErsatzTV.Tests/Application/Scheduling/Issue172HardeningTests.cs (new, 19 cases), FFmpegProfileHandlerTests.cs, ApiErrorResponseMetadataTests.cs; docs/decisions.md, docs/api-conventions.md (§3b); regenerated v1.json.

Deferred / follow-ups. #327 (playlist rename does no name validation — pre-existing create/update asymmetry, backlog, priority: low).

Docs updated (same PR). decisions.md entry (2026-07-13) + api-conventions.md §3b handler-hardening bullet (dereferencing a request string is a latent 500).

Review. Cold zero-context adversarial pass caught a real CI-red blocker (stale metadata-test assertions after the 404 trim) + confirmed the fixes; fix-commit re-reviewed → MERGEABLE. Rebased onto #286 (/api/v1 sweep) mid-session; final head 2e4e07a2, full suite 1583/0, all CI green.

## Closed — PR #325 merged to `main` (`2e4e07a2`, fast-forward) **What was done.** Cleared the still-live findings from this consolidated list; most had been resolved or ratified deliberate since 2026-07-07 (verified against `main` first, rather than fixing stale nits). **Root cause (finding #1, the real bug).** Request DTOs carry no `#nullable` context (api-conventions §2), so a `string Name` binds `null` from `name: null`/an omitted field; there's no implicit `[Required]`, no FluentValidation validator for these commands, and **no global exception filter** — so a handler doing `request.Name.Length` threw an unguarded `NullReferenceException` that surfaced as HTTP 500. The group-create + copy handlers were already safe because they route the name through the null-safe `NotEmpty`/`NotLongerThan` combinator; the create/replace handlers used a raw `.Length` check. Fixed class-wide with a `string.IsNullOrWhiteSpace(...) ||` guard (minimal blast radius, preserves each handler's error message + 422 mapping). **Fixed (3 live findings):** - **#1** — null/empty name → 500 across **10 handlers** (Block/Template/DecoTemplate/Deco Create+Replace/Update + `UpdateFFmpegProfile`; `CreatePlaylist` was an empty-name persist, not a 500). Now 422; also rejects empty/whitespace names. - **#3** — exact-duplicate template items bypassed overlap validation (record value-equality skip) → now index-based, rejected 422. - **#6** — unreachable 404 `ProducesResponseType` trimmed from **all 4** create-group actions. **Dispositioned (not fixed):** #2, #4 → deliberate-documented (api-conventions §8/§3b); #7 → moot (`OperationIdOpenApiTransformer`, #197 Bundle C); #5 → deferred perf nit; the auth/Trakt/search tail → already fixed on `main`. **Files changed.** 10 handlers (`ErsatzTV.Application/{Scheduling,MediaCollections,FFmpegProfiles}/Commands/*Handler.cs`); 4 controllers (Block/Template/Deco/DecoTemplate — 404 trims); `ErsatzTV.Tests/Application/Scheduling/Issue172HardeningTests.cs` (new, 19 cases), `FFmpegProfileHandlerTests.cs`, `ApiErrorResponseMetadataTests.cs`; `docs/decisions.md`, `docs/api-conventions.md` (§3b); regenerated `v1.json`. **Deferred / follow-ups.** #327 (playlist rename does no name validation — pre-existing create/update asymmetry, backlog, `priority: low`). **Docs updated (same PR).** `decisions.md` entry (2026-07-13) + `api-conventions.md` §3b handler-hardening bullet (dereferencing a request `string` is a latent 500). **Review.** Cold zero-context adversarial pass caught a real CI-red blocker (stale metadata-test assertions after the 404 trim) + confirmed the fixes; fix-commit re-reviewed → MERGEABLE. Rebased onto #286 (`/api/v1` sweep) mid-session; final head `2e4e07a2`, full suite 1583/0, all CI green.
timothy removed the in-progress label 2026-07-13 01:28:23 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#172