linearvoid/.github/instructions/BACKLOG.md

BACKLOG

Cloudflare Configuration

• Configure DNS for linearvoid.tv apex and www redirect (manual)
• Configure media.linearvoid.tv for split-domain HLS delivery (manual)
• Create R2 bucket (manual)
• Configure Cache Rules: .ts/.m4s + .m3u8 (manual)
• Configure Cloudflare Pages deploy workflow (.gitea/workflows/pages-deploy.yml) and setup docs (docs/operations/cloudflare-pages-setup.md, docs/operations/gitea-cloudflare.pages.md)
• Create Cloudflare Pages project in dashboard and link custom domain (manual)
• Enable Tiered Cache, WAF, rate limiting (manual)
• Implement Worker for immutable cache headers on segment paths
• Enforce HTTPS/WSS, redirect HTTP → HTTPS (manual)

Monitoring & Observability

• Set up Prometheus with chat/playout/nginx/redis/postgres/node scrape targets
• Add nginx-exporter, redis-exporter, postgres-exporter, node-exporter
• Import Grafana app + operational dashboards
• Define Prometheus alerting rules (8 rules: ChatDown, PlayoutDown, RedisDown, etc.)
• Set up UptimeRobot external monitoring

Security

• Implement admin cookie-session auth (HttpOnly, SameSite=Strict, Secure when TLS)
• Implement server-side session expiration
• Enforce HTTPS/WSS at edge and origin
• Implement rate limiting for chat messages (Redis windowing)
• Implement WebSocket connection rate limiting (5/IP/60s)
• Implement admin login rate limiting (5/IP/5min)

Scaling & Performance

• Create scaling/performance playbook (methods, thresholds, execution order)
• Load-test scaffolding: ws-chat.yml, admin-api.js, run-loadtests.ps1, summarizers
• Cache-hit ratio exporter (scripts/cache-hit-ratio.js + .ps1)
• Saturation alerts: chat p95, Redis memory, cache-hit ratio
• Create Cloudflare Pages project and cut over frontend hosting (manual)
• Optimize segment immutability and manifest TTL for cache efficiency
• Measure playback TTFB from multiple US regions
• Execute WebSocket load tests with real infrastructure
• Execute admin API benchmarks with real infrastructure
• Track cache hit ratio and R2 ops in production
• Plan Phase 2 service separation
• Plan Phase 3 multi-origin resilience

Streaming Pipeline

Gaps from 2026-08-10 audit (STREAMING.md contract vs playlist.go implementation):

• Continuous R2 sync during playout (HIGH): syncLatestToR2() runs only after FFmpeg exits. During long playout loops, R2 is stale — viewers see no new segments. Needs per-segment upload triggered by filesystem watch or FFmpeg progress pipe.
• Globally unique segment naming (HIGH): STREAMING.md requires hls/r-{runID}/seg-{seq}.m4s. Current code uses strftime (segment_%Y%m%d_%H%M%S.m4s) with no run ID — same-second collisions on restart; names can be reused. Add run/session UUID and monotonic sequence.
• Atomic manifest publication (MEDIUM): Upload manifest to temp key, then atomically replace live/playlist.m3u8. Current code uploads directly — brief window where manifest references unconfirmed segments. Use R2 copy/rename or write-then-swap.
• Manifest Cache-Control alignment (LOW): STREAMING.md specifies public, max-age=1, s-maxage=2, must-revalidate. Code uses public, max-age=2. Missing must-revalidate and browser/CDN split.
• CORS headers on HLS responses (MEDIUM): Access-Control-Allow-Origin: https://linearvoid.tv required for cross-origin hls.js from media.linearvoid.tv. Neither Worker nor R2 config sets CORS. Add to Worker or R2 custom domain.
• Player error recovery (MEDIUM): STREAMING.md requires bounded retries, exponential backoff, seek-forward-on-drift, reconnecting state. Current main.ts uses basic hls.js init with no custom error handlers. Add hls.on(Hls.Events.ERROR, ...) handler.
• Health endpoint detail (LOW): Add active item, playlist revision, run ID, last segment sequence, last R2 pub timestamp, consecutive failures to /health. Currently only reports mode + restarts.
• Source media contract + validation (H.264/AAC, 30fps, keyframe check) — implemented
• fMP4 HLS packaging (6s segments, 24 window) — implemented
• Slate fallback + recovery (shouldEscalateToSlate) — implemented
• R2 cache headers (immutable segments, short-lived manifest) — implemented
• Cloudflare Worker immutable .m4s headers — implemented