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
No Branch/Tag Specified
main
renovate/dotnet-monorepo
renovate/meziantou.analyzer-3.x
renovate/lucene.net
renovate/sqlitepclraw.bundle_e_sqlite3-3.x
renovate/cliwrap-3.x
913-scripted-playout-401
release/v26.15.0-notes
issue-806-guard-populations
scratch/767b-poisoned
scratch/767b-control
release/v26.14.0-notes
release/v26.14.0
docs/510-skill-logo-bug-policy
fix/510-watermark-resolution-policy
fix/629-verdict-classifier-falseopens
fix/609-decisions-edit-token-scope
issue-135-clear-to-none
release/v26.12.0-notes
fix/409b-lastscan-api-parity
fix/401-updatechannel-mirror-422
fix/327-playlist-rename-validation
fix/410-scancancel-log-level
fix/409-447-librariesscreen-neverscanned
fix/338-zap-exit-code
fix/367-plex-budget-message
fix/310-debom-legacy-cs
ci/604-lane-rebalance
feat/388-design-mirror
feat/247-test-ownership
feat/247-primary-action
feat/357-player-owned-playback
feat/357-jellyfin-plugin-poc
fix/289-mcp-hardening
issue58-mcp
feat/244-channels-extract
ci/auto-bump-prod-compose
feat/multi-rerun-collections-api
feat/collections-api
feat/quick-wins
feat/185-docs-part2
feat/140-collections-screen
feat/146-channel-edit
feat/147-classic-ui-link
issue22-renovate-dashboard
feat/91-cutover
feat/63-composite-create
feat/65-library-browse
feat/85-epg
feat/86-schedule-editor
feat/109-dashboard-data
feat/99-session-tracking
fix/dockerfile-node-tag
feat/59-spa-foundation
docs/59-ui-redesign-brief
feat/102-json-guide
feat/111-schedule-durations
feat/104-artwork-upload
feat/103-media-sources-api
feat/playouts-read-api
feat/108-health-api
feat/105-picker-list-endpoints
issue-97-channel-state-api
issue42-jellyfin-musicvideos
issue46-rest-api-error-contract
dependabot/nuget/ErsatzTV.FFmpeg.Tests/multi-d307a2e06f
qsv-improvements
hdr-vulkan-cuda-test
v26.16.0
v26.15.0
v26.14.0
v26.13.0
v26.12.0
v26.11.0
v26.10.0
v26.9.0
v26.8.0
v26.7.0
blazor-final
v26.6.0
v26.5.0
v26.4.0
v26.3.1
v26.3.0
v26.2.0
v26.1.1
v26.1.0
v25.9.0
v25.8.0
v25.7.1
v25.7.0
v25.6.0
v25.5.0
v25.4.0
v25.3.1
v25.3.0
v25.2.0
v25.1.0
v0.8.8-beta
v0.8.7-beta
v0.8.6-beta
v0.8.5-beta
v0.8.4-beta
v0.8.3-beta
v0.8.2-beta
v0.8.1-beta
v0.8.0-beta
v0.7.9-beta
v0.7.8-beta
v0.7.7-beta
v0.7.6-beta
v0.7.5-beta
v0.7.4-beta
v0.7.3-beta
v0.7.2-beta
v0.7.1-beta
v0.7.0-beta
v0.6.9-beta
v0.6.8-beta
v0.6.7-beta
v0.6.6-beta
v0.6.5-beta
v0.6.4-beta
v0.6.3-beta
v0.6.2-beta
v0.6.1-beta
v0.6.0-beta
v0.5.8-beta
v0.5.7-beta
v0.5.6-beta
v0.5.5-beta
v0.5.4-beta
v0.5.3-beta
v0.5.2-beta
v0.5.1-beta
v0.5.0-beta
v0.4.5-alpha
v0.4.4-alpha
v0.4.3-alpha
v0.4.2-alpha
v0.4.1-alpha
v0.4.0-alpha
v0.3.8-alpha
v0.3.7-alpha
develop
v0.3.6-alpha
v0.3.5-alpha
v0.3.4-alpha
v0.3.3-alpha
v0.3.2-alpha
v0.3.1-alpha
v0.3.0-alpha
v0.2.5-alpha
v0.2.4-alpha
v0.2.3-alpha
v0.2.2-alpha
v0.2.1-alpha
v0.2.0-alpha
v0.1.5-alpha
v0.1.4-alpha
v0.1.3-alpha
v0.1.2-alpha
v0.1.1-alpha
v0.1.0-alpha
v0.0.62-alpha
v0.0.61-alpha
v0.0.60-alpha
v0.0.59-alpha
v0.0.58-alpha
v0.0.57-alpha
v0.0.56-alpha
v0.0.55-alpha
v0.0.54-alpha
v0.0.53-alpha
v0.0.52-alpha
v0.0.51-alpha
v0.0.50-alpha
v0.0.49-prealpha
v0.0.48-prealpha
v0.0.47-prealpha
v0.0.46-prealpha
v0.0.45-prealpha
v0.0.44-prealpha
v0.0.43-prealpha
v0.0.42-prealpha
v0.0.41-prealpha
v0.0.40-prealpha
v0.0.39-prealpha
v0.0.38-prealpha
v0.0.37-prealpha
v0.0.36-prealpha
v0.0.35-prealpha
v0.0.34-prealpha
v0.0.33-prealpha
v0.0.32-prealpha
v0.0.31-prealpha
v0.0.30-prealpha
v0.0.29-prealpha
v0.0.28-prealpha
v0.0.27-prealpha
v0.0.26-prealpha
v0.0.25-prealpha
v0.0.24-prealpha
v0.0.23-prealpha
v0.0.22-prealpha
v0.0.21-prealpha
v0.0.20-prealpha
v0.0.19-prealpha
v0.0.18-prealpha
v0.0.17-prealpha
v0.0.16-prealpha
v0.0.15-prealpha
v0.0.14-prealpha
v0.0.13-prealpha
v0.0.12-prealpha
v0.0.11-prealpha
v0.0.10-prealpha
v0.0.9-prealpha
v0.0.8-prealpha
v0.0.7-prealpha
v0.0.6-prealpha
v0.0.5-prealpha
v0.0.4-prealpha
v0.0.3-prealpha
v0.0.2-prealpha
v0.0.1-prealpha
Labels
Clear labels
ad-hoc
api
bug
ci-cd
content
dependencies
enhancement
frontend
in-progress
jellyfin
parked
priority: high
priority: low
priority: medium
review
security
One-off / ad-hoc work not tracked by a dedicated issue
REST API / HTTP endpoints
Something isn't working
Build, test, deploy pipeline
Channel content / schedules / playlists
Dependency updates (Renovate)
New feature or improvement
ChicoryTV React SPA frontend
Claimed by an active session — do not pick up
Jellyfin tuner / IPTV integration
Excluded from automatic queue pickup; work only when explicitly selected
Adversarial review finding
Security / vulnerability fix
Milestone
No items
No Milestone
Blazor removal (#91 phase b)
Projects
Clear projects
No projects
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: timothy/ersatztv#235
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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_trasherrors as 500 text/plain.Task
Adopt uniformly for queue-triggering endpoints (Trakt already implements it):
POST /api/channels/{n}/playout/reset,clean_artworkmove from 200).POST /api/playouts/reset-all→ 202 + body reporting skipped playouts (locked / ExternalJson) instead of silent skip (ResetAllPlayoutsHandler.cs:25,36).empty_trash500 text/plain → ProblemDetails.IsPlayoutLockednot 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.SchedulerService.cs:319-328, 343-352) leaks the global Trakt lock if the last message is never processed (WorkerService shutdownbreak,WorkerService.cs:42-45) — make batch release loss-tolerant.ForceSynchronize*ById(id, false)hardcoded; Blazor passestrue); external-collections scan (Synchronize*Collections) has no API trigger. Either add endpoints here or file/gate under the Blazor-removal tracker before deletingLibraries.razor.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 referenced this issue2026-07-11 15:44:36 +02:00
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.tsxis now 2823 lines; the:3064-3109playout-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.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
mainin (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), andtroubleshoot(bare 404). Observability was also further along than the issue said: the list endpoint already exposesisLocked+BuildStatus(#215); only the single-playout GET was missingisLocked(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-collectionson missing ids→404application/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.
Closed — PR #267 merged to
main(4aeabada, fast-forward)What was done (reviewer#20 F7+F8+F9):
empty_trash(500 text/plain→PD),clean_artwork(200→202),scan-show(conflated 400→202/404/409/422 viaQueueShowScanResult), channelreset(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.isLockedadded toGET /api/playouts/{id}(list endpoint already had it via #215).Libraries.razordeletion gate):?deep=on library scan + newPOST /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).WorkerServicereleases infinally).Root cause of the review-found High (Codex): the new
scan-collectionsendpoints acquire a per-provider collections lock and delegate release toScannerService'sfinally, butSchedulerServiceenqueued 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; 3Synchronize{X}Collectionsrecords +ScannerService+SchedulerService(lock fix);WorkerService(F7); SPAlibraries.ts/playouts.ts(+tests); regeneratedv1.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.