Async-op API contract normalization + playout build observability (reviewer#20 F7+F8+F9) #235

Closed
opened 2026-07-11 00:55:51 +02:00 by timothy · 3 comments
Owner

From audit adversarial-reviewer#20, findings F8 (Medium) + F7 (Medium-low) + F9 (Low). Last of the reviewer#20 batch — land after the per-surface fixes. Explicitly separate from #197 (broad API security/contract review); #197 should reference the contract table this issue produces.

Current inconsistency (per the audit's endpoint table)

Accepted-async is variously 200 / 202 / long-block-302; lock conflict is 409 only for Trakt (silent 200 no-op for library scan, conflated 400 for scan-show, silent skip for reset-all, bare 404 for troubleshoot); empty_trash errors as 500 text/plain.

Task

Adopt uniformly for queue-triggering endpoints (Trakt already implements it):

  • 202 Accepted — work queued (library scan, POST /api/channels/{n}/playout/reset, clean_artwork move from 200).
  • 404 — entity missing (real controller pre-check per convention).
  • 409 ProblemDetails — lock held.
  • 422 ProblemDetails — disabled/unsupported (sync disabled, local-library show scan, ExternalJson reset).
  • POST /api/playouts/reset-all → 202 + body reporting skipped playouts (locked / ExternalJson) instead of silent skip (ResetAllPlayoutsHandler.cs:25,36).
  • empty_trash 500 text/plain → ProblemDetails.
  • Playout build observability: every 202 needs a pollable status surface; scans/Trakt/troubleshooting have one, playout builds have nothing (IsPlayoutLocked not exposed; SPA does one blind refresh, web/src/App.tsx:3064-3109). Expose build state (lock + PlayoutBuildStatus) over HTTP — coordinate with #215's gating surface.
  • F7 hardening (with the scan-lifecycle issue if more natural there): Trakt scheduler unlock-by-last-item (SchedulerService.cs:319-328, 343-352) leaks the global Trakt lock if the last message is never processed (WorkerService shutdown break, WorkerService.cs:42-45) — make batch release loss-tolerant.
  • F9 parity gaps → #91b gate list: deep scan unreachable via API (ForceSynchronize*ById(id, false) hardcoded; Blazor passes true); external-collections scan (Synchronize*Collections) has no API trigger. Either add endpoints here or file/gate under the Blazor-removal tracker before deleting Libraries.razor.
  • Decision record (docs/decisions.md): unbounded channels + no shutdown drain is accepted-by-design (in-memory locks die with the process).

Same-PR requirements: OpenAPI regen + endpoint index, contract tests for every changed code, SPA consumers updated in the same PR (status-code changes are SPA-breaking: web/src/api/libraries.ts, playout reset paths; TraktListsScreen unaffected).

From audit [adversarial-reviewer#20](https://gitea.tblindustries.be/timothy/adversarial-reviewer/issues/20#issuecomment-7588), findings **F8 (Medium) + F7 (Medium-low) + F9 (Low)**. Last of the reviewer#20 batch — land after the per-surface fixes. Explicitly **separate from #197** (broad API security/contract review); #197 should reference the contract table this issue produces. ## Current inconsistency (per the audit's endpoint table) Accepted-async is variously 200 / 202 / long-block-302; lock conflict is 409 only for Trakt (silent 200 no-op for library scan, conflated 400 for scan-show, silent skip for reset-all, bare 404 for troubleshoot); `empty_trash` errors as **500 text/plain**. ## Task Adopt uniformly for queue-triggering endpoints (Trakt already implements it): - **202 Accepted** — work queued (library scan, `POST /api/channels/{n}/playout/reset`, `clean_artwork` move from 200). - **404** — entity missing (real controller pre-check per convention). - **409 ProblemDetails** — lock held. - **422 ProblemDetails** — disabled/unsupported (sync disabled, local-library show scan, ExternalJson reset). - `POST /api/playouts/reset-all` → 202 + body reporting skipped playouts (locked / ExternalJson) instead of silent skip (`ResetAllPlayoutsHandler.cs:25,36`). - `empty_trash` 500 text/plain → ProblemDetails. - **Playout build observability**: every 202 needs a pollable status surface; scans/Trakt/troubleshooting have one, playout builds have nothing (`IsPlayoutLocked` not exposed; SPA does one blind refresh, `web/src/App.tsx:3064-3109`). Expose build state (lock + `PlayoutBuildStatus`) over HTTP — coordinate with #215's gating surface. - **F7 hardening** (with the scan-lifecycle issue if more natural there): Trakt scheduler unlock-by-last-item (`SchedulerService.cs:319-328, 343-352`) leaks the global Trakt lock if the last message is never processed (WorkerService shutdown `break`, `WorkerService.cs:42-45`) — make batch release loss-tolerant. - **F9 parity gaps → #91b gate list**: deep scan unreachable via API (`ForceSynchronize*ById(id, false)` hardcoded; Blazor passes `true`); external-collections scan (`Synchronize*Collections`) has no API trigger. Either add endpoints here or file/gate under the Blazor-removal tracker before deleting `Libraries.razor`. - Decision record (`docs/decisions.md`): unbounded channels + no shutdown drain is accepted-by-design (in-memory locks die with the process). Same-PR requirements: OpenAPI regen + endpoint index, contract tests for every changed code, SPA consumers updated in the same PR (status-code changes are SPA-breaking: `web/src/api/libraries.ts`, playout reset paths; TraktListsScreen unaffected).
timothy added the enhancementapipriority: mediumreview labels 2026-07-11 00:55:51 +02:00
timothy added this to the Blazor removal (#91 phase b) milestone 2026-07-11 01:19:59 +02:00
timothy added the in-progress label 2026-07-11 17:44:52 +02:00
Author
Owner

Claiming — session started 2026-07-11 ~17:45. Picking this up as the arc's forward edge now that #202 (media-source write API+SPA) has landed on main @ 8e2f9954, which resolves the prior App.tsx/libraries.ts collision that was holding this issue. Parallel-safe vs the two active sessions (#253 concurrency-contract PR1, #254 hardening cluster — neither touches the libraries/scan/playout-build surface).

Note: #202's refactor invalidated this issue's SPA line refs (App.tsx is now 2823 lines; the :3064-3109 playout-build blind-refresh anchor moved). Doing fresh recon of the current async-op status-code landscape + the F9 deep-scan/external-collections-scan gap (which #202 may have partially closed) before scoping the PR.

Claiming — session started 2026-07-11 ~17:45. Picking this up as the arc's forward edge now that #202 (media-source write API+SPA) has landed on `main @ 8e2f9954`, which resolves the prior App.tsx/libraries.ts collision that was holding this issue. Parallel-safe vs the two active sessions (#253 concurrency-contract PR1, #254 hardening cluster — neither touches the libraries/scan/playout-build surface). Note: #202's refactor invalidated this issue's SPA line refs (`App.tsx` is now 2823 lines; the `:3064-3109` playout-build blind-refresh anchor moved). Doing fresh recon of the current async-op status-code landscape + the F9 deep-scan/external-collections-scan gap (which #202 may have partially closed) before scoping the PR.
Author
Owner

PR #267 open. Built in 4 parallel disjoint-file slices (Maintenance+Troubleshoot / Libraries+F9 / Playouts / Trakt-F7), merged back, one OpenAPI regen; then merged current main in (incl. #253 PR1 #263) and re-regenerated artifacts.

Recon correction to the issue premises: #232/#215 had already normalized library-scan + playout-reset to the 202/404/409/422 contract — the genuine outliers were empty_trash (500 text/plain), clean_artwork (silent 200), scan-show (conflated 400), channel reset (200), and troubleshoot (bare 404). Observability was also further along than the issue said: the list endpoint already exposes isLocked+BuildStatus (#215); only the single-playout GET was missing isLocked (added). Both F9 gaps confirmed still open (#202 did not close them) → new ?deep= on library scan + POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections.

Live E2E (fresh local host, real MVC+Newtonsoft pipeline) confirmed: clean_artwork→202, empty_trash→200, scan/scan?deep=true/scan-show/scan-collections on missing ids→404 application/problem+json, reset-all→202 with {queuedPlayoutIds,skippedLocked,skippedUnsupported}. Full backend suite (1324/493/1467/53/5/20, 0 failed) + web 666 tests + no API drift.

Two independent adversarial passes (cold Claude + Codex) running over the diff, focused on the scan-collections lock lifecycle. Will report done/deferred on close.

PR **#267** open. Built in 4 parallel disjoint-file slices (Maintenance+Troubleshoot / Libraries+F9 / Playouts / Trakt-F7), merged back, one OpenAPI regen; then merged current `main` in (incl. #253 PR1 #263) and re-regenerated artifacts. **Recon correction to the issue premises**: #232/#215 had already normalized library-scan + playout-reset to the 202/404/409/422 contract — the genuine outliers were `empty_trash` (500 text/plain), `clean_artwork` (silent 200), `scan-show` (conflated 400), `channel reset` (200), and `troubleshoot` (bare 404). Observability was also further along than the issue said: the list endpoint already exposes `isLocked`+`BuildStatus` (#215); only the single-playout GET was missing `isLocked` (added). Both **F9 gaps confirmed still open** (#202 did not close them) → new `?deep=` on library scan + `POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections`. **Live E2E** (fresh local host, real MVC+Newtonsoft pipeline) confirmed: `clean_artwork`→202, `empty_trash`→200, `scan`/`scan?deep=true`/`scan-show`/`scan-collections` on missing ids→404 `application/problem+json`, `reset-all`→202 with `{queuedPlayoutIds,skippedLocked,skippedUnsupported}`. Full backend suite (1324/493/1467/53/5/20, 0 failed) + web 666 tests + no API drift. Two independent adversarial passes (cold Claude + Codex) running over the diff, focused on the scan-collections lock lifecycle. Will report done/deferred on close.
Author
Owner

Closed — PR #267 merged to main (4aeabada, fast-forward)

What was done (reviewer#20 F7+F8+F9):

  • F8 async-op contract normalized to 202/404-PD/409-PD/422-PD: empty_trash (500 text/plain→PD), clean_artwork (200→202), scan-show (conflated 400→202/404/409/422 via QueueShowScanResult), channel reset (200→202), reset-all (now returns skipped-playouts body), troubleshoot (bare 404→PD). #232/#215 had already normalized library-scan + playout-reset — this finished the outliers.
  • Observability: isLocked added to GET /api/playouts/{id} (list endpoint already had it via #215).
  • F9 parity endpoints (the Libraries.razor deletion gate): ?deep= on library scan + new POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections. API gate now CLOSED; the SPA deep-scan/collections buttons are the removal PR's remaining parity work (parity doc §5).
  • F7: Trakt batch-lock leak on worker shutdown fixed (WorkerService releases in finally).

Root cause of the review-found High (Codex): the new scan-collections endpoints acquire a per-provider collections lock and delegate release to ScannerService's finally, but SchedulerService enqueued periodic collection scans unlocked while the scanner released the lock whenever held → cross-release (#250 class). Pre-existing in the Blazor path; newly reachable via the REST API this issue shipped. Fixed with the §C7 lock-once-per-provider batch pattern (Unlock: isLast), Fable-reconciled and Codex-re-reviewed (FIX CORRECT).

Files: 3 Maintenance/Troubleshoot/Channel/Playout/Libraries controllers + 3 media-source controllers; QueueLibraryScanByLibraryId/QueueShowScanByLibraryId (+handlers, +QueueShowScanResult/DeepScan); ResetAllPlayouts(+Result/ResponseModel); PlayoutResponseModel.IsLocked; 3 Synchronize{X}Collections records + ScannerService + SchedulerService (lock fix); WorkerService (F7); SPA libraries.ts/playouts.ts(+tests); regenerated v1.json/v1.d.ts/endpoint-index.md.

Docs: decisions.md (#235 entry incl. accepted-by-design unbounded-channels/no-drain note), api-conventions.md §3a/§3b, blazor-route-parity.md §5 (F9 gate closed).

Deferred / follow-ups: none filed. The scan-collections SchedulerService batch test covers Plex only (Jellyfin/Emby code is symmetric, verified by review); minor coverage gap, not a defect. SPA deep-scan/collections buttons → removal PR (parity doc §5).

Verification: full backend suite (ErsatzTV.Tests 1335, 0 failed) + web 666 + no API drift + live E2E on a running host (202/404-PD/reset-all-body all confirmed) + CI green on the merge head. Two independent reviews + Fable reconciliation + Codex fix-commit re-review.

## Closed — PR #267 merged to `main` (`4aeabada`, fast-forward) **What was done** (reviewer#20 F7+F8+F9): - **F8 async-op contract** normalized to 202/404-PD/409-PD/422-PD: `empty_trash` (500 text/plain→PD), `clean_artwork` (200→202), `scan-show` (conflated 400→202/404/409/422 via `QueueShowScanResult`), channel `reset` (200→202), `reset-all` (now returns skipped-playouts body), troubleshoot (bare 404→PD). #232/#215 had already normalized library-scan + playout-reset — this finished the outliers. - **Observability**: `isLocked` added to `GET /api/playouts/{id}` (list endpoint already had it via #215). - **F9 parity endpoints** (the `Libraries.razor` deletion gate): `?deep=` on library scan + new `POST /api/media-sources/{plex|jellyfin|emby}/{id}/scan-collections`. **API gate now CLOSED**; the SPA deep-scan/collections *buttons* are the removal PR's remaining parity work (parity doc §5). - **F7**: Trakt batch-lock leak on worker shutdown fixed (`WorkerService` releases in `finally`). **Root cause of the review-found High** (Codex): the new `scan-collections` endpoints acquire a per-provider collections lock and delegate release to `ScannerService`'s `finally`, but `SchedulerService` enqueued periodic collection scans **unlocked** while the scanner released the lock whenever held → cross-release (#250 class). Pre-existing in the Blazor path; newly reachable via the REST API this issue shipped. Fixed with the §C7 lock-once-per-provider batch pattern (`Unlock: isLast`), Fable-reconciled and Codex-re-reviewed (FIX CORRECT). **Files**: 3 Maintenance/Troubleshoot/Channel/Playout/Libraries controllers + 3 media-source controllers; `QueueLibraryScanByLibraryId`/`QueueShowScanByLibraryId` (+handlers, +`QueueShowScanResult`/`DeepScan`); `ResetAllPlayouts`(+Result/ResponseModel); `PlayoutResponseModel.IsLocked`; 3 `Synchronize{X}Collections` records + `ScannerService` + `SchedulerService` (lock fix); `WorkerService` (F7); SPA `libraries.ts`/`playouts.ts`(+tests); regenerated `v1.json`/`v1.d.ts`/`endpoint-index.md`. **Docs**: `decisions.md` (#235 entry incl. accepted-by-design unbounded-channels/no-drain note), `api-conventions.md` §3a/§3b, `blazor-route-parity.md` §5 (F9 gate closed). **Deferred / follow-ups**: none filed. The scan-collections **SchedulerService batch test** covers Plex only (Jellyfin/Emby code is symmetric, verified by review); minor coverage gap, not a defect. SPA deep-scan/collections **buttons** → removal PR (parity doc §5). **Verification**: full backend suite (ErsatzTV.Tests 1335, 0 failed) + web 666 + no API drift + live E2E on a running host (202/404-PD/reset-all-body all confirmed) + CI green on the merge head. Two independent reviews + Fable reconciliation + Codex fix-commit re-review.
timothy removed the in-progress label 2026-07-11 19:06:40 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#235