linearvoid/DEVELOPMENT.md

DEVELOPMENT.md — Linear Void Remaining Tasks

Auto-generated 2026-08-07. All completed items moved to .github/instructions/DONE.md.

Test Fixtures (BLOCKED — requires ffmpeg)

• Create test media fixtures in backend/playout/testdata/:

  • valid_720p30.mp4 — small (1-2s) H.264/AAC compliant file
  • invalid_h265.mp4 — wrong codec
  • invalid_24fps.mp4 — wrong framerate
  • Generate via ffmpeg commands documented in test file headers

• Create test playlist fixtures in backend/playout/testdata/:

  • valid_playlist.txt, empty_playlist.txt, comments_only.txt, mixed_valid_invalid.txt

User Frontend Tests

• Video player behavior (play, pause, seek, buffering, error handling)
• Chat functionality (send/receive messages, presence, rate limiting, moderation)
• State management and data flow
• Responsive design and layout across different screen sizes
• Accessibility testing (keyboard navigation, screen reader support)
• Integration with backend APIs (mocking API responses for testing)
• Test coverage for all critical frontend components and interactions
• Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
• Document test cases and expected outcomes

Admin Frontend Tests

• Playlist management UI (add/remove videos, reorder, normalize)
• User moderation tools (mute/ban/report users, view moderation logs)
• Metrics and monitoring dashboards (Prometheus/Grafana integration)
• State management and data flow
• Responsive design and layout across different screen sizes
• Accessibility testing (keyboard navigation, screen reader support)
• Integration with backend APIs (mocking API responses for testing)
• Test coverage for all critical admin UI components and interactions
• Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
• Document test cases and expected outcomes

Cloudflare R2 Integration Test

• Upload test HLS segments and manifests to R2 bucket
• Verify correct cache headers are applied (immutable segments, TTLs)
• Test retrieval of segments and manifests from R2 via Cloudflare edge
• Validate cache hit/miss behavior and performance metrics
• Ensure integration test can run in CI/CD pipeline with proper mocking/stubbing of R2 API
• Document test cases and expected outcomes

Cloudflare Configuration (manual — Cloudflare dashboard)

Evidence tracker: docs/operations/cloudflare-uptimerobot-checklist.md

• Cloudflare Pages: link Gitea repo, build cd frontend && npm run build, output frontend/dist
• Tiered Cache: enable Smart Tiered Cache, validate Cf-Cache-Status: HIT from upper tier
• WAF: enable OWASP Managed Ruleset, set to Simulate → review 48h → Block, enable Bot Fight Mode
• Rate limiting: /api/admin/login + /api/admin/* → 10 req/10s per IP, Challenge action
• HTTPS/WSS: Always Use HTTPS, HSTS max-age=31536000 includeSubDomains preload, min TLS 1.2
• HTTPS/WSS: enforce at edge (Cloudflare) and origin (nginx), redirect HTTP → HTTPS

External Services

Evidence tracker: docs/operations/cloudflare-uptimerobot-checklist.md

• UptimeRobot: add HTTP monitor for https://linearvoid.tv/health (5min interval)
• UptimeRobot: add keyword monitor for https://linearvoid.tv/hls/playlist.m3u8 (keyword: #EXTM3U, 5min)
• Alert on 2 consecutive failures, notify via email + Discord/Slack webhook

Production Deployment (Hetzner — not provisioned)

• Provision Hetzner CX22 (2 vCPU, 4 GB, 40 GB) in Ashburn VA, Ubuntu 24.04
• Install Docker Engine + Compose plugin, open firewall: 80/443 (public), 2375 (runner IP only)
• Configure Docker daemon for remote TLS access (-H tcp://0.0.0.0:2376 with certs)
• Create /srv/linearvoid/data/{playlist,media,hls,chat,slate} directories
• Add CI_PROD_* secrets to Gitea: DOCKER_HOST, R2 keys, admin password, DB password, Grafana password
• Trigger CD workflow with DOCKER_HOST pointing to Hetzner IP
• Verify all 11 containers start healthy, check /health, /hls/playlist.m3u8, WebSocket
• Update Cloudflare A record linearvoid.tv → Hetzner IP, SSL Full (strict), test HTTPS + WSS
• Smoke test: viewer SPA loads, HLS plays, chat connects, admin login → upload → playlist → playout
• Set up Prometheus alerting notifications + UptimeRobot on production URL
• Run scripts/backup-db.sh + scripts/verify-backups.sh on production host
• Document production IP, SSH access, rollback procedure, scaling thresholds

Scaling & Performance (planning only)

• Tune manifest TTL: measure Cf-Cache-Status distribution, adjust to 0.5× segment duration
• Measure TTFB: WebPageTest from 3+ US regions, target <4s warm cache, document baseline
• Load-test WebSocket: artillery or Go script, ramp 10→100→500→1000 connections, measure p95 latency + errors
• Benchmark admin API: wrk/k6 against /api/admin/*, target p95 <1s, identify slow queries
• Track cache hit ratio: Cloudflare GraphQL → Grafana panel, alert <90%
• Capacity triggers: Prometheus rules for cache-miss >10%/15min, chat p95 >1s/5min, CPU >80%/10min
• Phase 2 plan: document boundaries (playout CPU, chat latency, DB state, monitoring), estimate per-service resources
• Phase 3 plan: research second Hetzner location, design warm standby + DNS failover + DB/Redis replication