linearvoid/.github/instructions/TODO.md

TODO

Completed tasks moved to DONE. Full remaining task list in BACKLOG.

Plan

Phase 1: unblock playout test fixtures and lock down the source-media contract

• Create small compliant fixture media in backend/playout/testdata/ for the validator and playout tests
• Create invalid fixture media for codec, framerate, and audio rejection paths
• Create playlist fixtures for empty, comment-only, mixed-validity, and valid playlists
• Document the ffmpeg fixture-generation commands in the relevant test headers

Phase 2: finish frontend coverage for the live viewer experience

• Add tests for HLS player startup, manifest resolution, and cross-origin/local fallback behavior
• Add tests for chat send/receive, presence updates, private DM flow, and reconnect behavior
• Add responsive-layout and accessibility checks for the viewer shell and chat sidebar
• Add coverage reporting and enforce a minimum threshold in CI

Phase 3: finish frontend coverage for the admin experience

• Add tests for playlist management, moderation flows, and dashboard rendering
• Add tests for API integration points with mocked backend responses
• Add responsive-layout and accessibility checks for admin screens
• Add coverage reporting and enforce a minimum threshold in CI

Phase 4: validate the R2 and edge-delivery path

• Add an integration test for upload and retrieval of HLS objects through the R2 path
• Verify segment and manifest cache headers, including immutable media and live manifest freshness
• Validate edge cache hit/miss behavior with repeat requests
• Document any required stubs or mocks so the test can run in CI (putObject mock pattern documented in test)

Phase 5: complete manual Cloudflare and external-service setup

• Apply Cloudflare Pages, Tiered Cache, WAF, rate limiting, and HTTPS/HSTS settings in the dashboard
• Create or verify UptimeRobot monitors for health and HLS manifest availability
• Capture evidence in docs/operations/cloudflare-uptimerobot-checklist.md

Phase 6: rehearse production deployment end to end

• Provision the Hetzner host and prepare the Docker/runtime baseline
• Configure production secrets, remote deployment, and DNS cutover
• Run health, HLS, chat, and admin smoke tests against production-like infrastructure
• Verify backup creation, restore, and integrity checks on the production host

Phase 7: baseline scaling and performance

• Measure manifest TTFB and cache-hit distribution from multiple US regions
• Prepare WebSocket load-test scaffolding and summary artifacts (ws-chat.yml, run-loadtests.ps1, summarize-artillery.ps1)
• Execute WebSocket throughput and chat-latency benchmarks under growing connection counts
• Prepare Admin API benchmark scaffolding and endpoint summary artifacts (admin-api.js, run-loadtests.ps1, summarize-k6.ps1)
• Execute Admin API benchmarks and identify slow paths
• Add saturation thresholds to monitoring (chat p95 latency + Redis memory usage)
• Add cache-hit threshold alert operationalization to monitoring

Status Update (2026-08-10)

• Phase 1 (test fixtures) complete.
• Phase 2 (viewer frontend): player startup, URL resolution, chat send/receive, reconnect, presence, DM flow, message rendering all covered (27 tests).
• Phase 3 (admin frontend): dashboard rendering, API integration, playlist management all covered (31 tests total).
• Phase 4 (R2 validation) partially complete: SyncToR2 cache headers + integration tests done; edge cache hit/miss remains manual.
• Phase 5 (Cloudflare): Pages deploy workflow (.gitea/workflows/pages-deploy.yml) created; Pages/Workers setup docs written; manual dashboard tasks remain.
• Phase 6 (production deployment) pending: Hetzner provisioning, secrets, DNS cutover, smoke tests, backup/restore.
• Phase 7: Loadtest scaffolding complete; run-loadtests.ps1 auto-generates ws-chat-summary.txt and admin-api-endpoint-summary.txt; live benchmark execution pending.
• Version tagged 1.0.11; go vet clean.

Streaming Pipeline Gaps (2026-08-10 audit → 2026-08-10 implemented)

STREAMING.md contract vs playlist.go/main.ts implementation. See Backlog for full details.

• Continuous R2 sync during playout (HIGH) — implemented: fsnotify watcher uploads segments within ~7s
• Globally unique segment naming with run ID (HIGH) — implemented: r-{ISOTIME}/seg-{seq}.m4s
• Atomic manifest publication with temp key (MEDIUM) — implemented: upload to .tmp, then CopyObject
• Manifest Cache-Control: add must-revalidate + s-maxage split (LOW) — implemented: public, max-age=1, s-maxage=2, must-revalidate
• CORS headers on HLS responses from media.linearvoid.tv (MEDIUM) — infrastructure, needs Cloudflare R2 CORS config
• Player error recovery: retries, backoff, reconnecting state (MEDIUM) — implemented: hls.on(ERROR) handler with exponential backoff
• Health endpoint: add active item, revision, run ID, segment info (LOW) — implemented: full STREAMING.md contract fields
• Phase 4 edge cache validation — script scripts/validate-edge-cache.sh created