chore(release): 1.1.0

- playout: run-scoped R2 manifest URIs (candidate a rewrite via rewriteManifestToRun)
- tests: playlist_rewrite_test.go (rewrite + publish integration + slate guard)
- docs: STREAMING, cloudflare-workers-setup, architecture (incl. Level-2 diagram)
- release housekeeping: TODO->DONE, CHANGELOG 1.1.0, version bump

.editorconfig

@@ -1,55 +1,55 @@
-# EditorConfig is awesome: https://editorconfig.org
+# EditorConfig is awesome: https://editorconfig.org
-root = true
+root = true
-
+
-# -------------------------------------------------
+# -------------------------------------------------
-# General settings – apply to all files
+# General settings – apply to all files
-# -------------------------------------------------
+# -------------------------------------------------
-[*]
+[*]
-charset = utf-8
+charset = utf-8
-end_of_line = lf
+end_of_line = lf
-insert_final_newline = true
+insert_final_newline = true
-trim_trailing_whitespace = true
+trim_trailing_whitespace = true
-
+
-# -------------------------------------------------
+# -------------------------------------------------
-# Markdown (*.md)
+# Markdown (*.md)
-# -------------------------------------------------
+# -------------------------------------------------
-[*.md]
+[*.md]
-max_line_length = off        # Markdown lines can be long
+max_line_length = off        # Markdown lines can be long
-trim_trailing_whitespace = false   # Preserve intentional spaces
+trim_trailing_whitespace = false   # Preserve intentional spaces
-
+
-# -------------------------------------------------
+# -------------------------------------------------
-# Go (*.go)
+# Go (*.go)
-# -------------------------------------------------
+# -------------------------------------------------
-[*.go]
+[*.go]
-indent_style = tab
+indent_style = tab
-indent_size = 4
+indent_size = 4
-trim_trailing_whitespace = true
+trim_trailing_whitespace = true
-max_line_length = 100
+max_line_length = 100
-
+
-# -------------------------------------------------
+# -------------------------------------------------
-# JavaScript & TypeScript (*.js, *.jsx, *.ts, *.tsx)
+# JavaScript & TypeScript (*.js, *.jsx, *.ts, *.tsx)
-# -------------------------------------------------
+# -------------------------------------------------
-[*.{js,jsx,ts,tsx}]
+[*.{js,jsx,ts,tsx}]
-indent_style = space
+indent_style = space
-indent_size = 2
+indent_size = 2
-insert_final_newline = true
+insert_final_newline = true
-trim_trailing_whitespace = true
+trim_trailing_whitespace = true
-max_line_length = 120
+max_line_length = 120
-
+
-# -------------------------------------------------
+# -------------------------------------------------
-# HTML (*.html, *.htm)
+# HTML (*.html, *.htm)
-# -------------------------------------------------
+# -------------------------------------------------
-[*.{html,htm}]
+[*.{html,htm}]
-indent_style = space
+indent_style = space
-indent_size = 2
+indent_size = 2
-max_line_length = 120
+max_line_length = 120
-trim_trailing_whitespace = true
+trim_trailing_whitespace = true
-
+
-# -------------------------------------------------
+# -------------------------------------------------
-# CSS & SCSS (*.css, *.scss)
+# CSS & SCSS (*.css, *.scss)
-# -------------------------------------------------
+# -------------------------------------------------
-[*.{css,scss}]
+[*.{css,scss}]
-indent_style = space
+indent_style = space
-indent_size = 2
+indent_size = 2
-max_line_length = 120
+max_line_length = 120
-trim_trailing_whitespace = true
+trim_trailing_whitespace = true

.env.example

@@ -8,6 +8,8 @@ R2_SECRET_ACCESS_KEY=your-r2-secret-key
 R2_BUCKET_NAME=linearvoid-media
 R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
 R2_REGION=auto
+R2_KEEP_RUNS=2
+R2_MAX_RETENTION_BYTES=10737418240
 
 # Cloudflare (for custom domain, cache rules, Workers if used)
 CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
@@ -47,14 +49,20 @@ DATABASE_URL=postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable
 REDIS_URL=redis://redis:6379/0
 
 # Service Ports (for local docker-compose)
-PLAYOUT_PORT=8080
+# Coolify env: 80/443 (Traefik proxy), 8000 (dashboard/Portainer), 8080 taken.
+PLAYOUT_PORT=8081
 CHAT_PORT=3000
-NGINX_PORT=80
+NGINX_PORT=8082
 
 # Playout configuration
 PLAYLIST_PATH=/app/playlist/playlist.txt
-HLS_SEGMENT_DURATION=6
+HLS_SEGMENT_DURATION=2
-HLS_WINDOW_SIZE=24
+HLS_WINDOW_SIZE=12
+
+# Shared runtime config (written by chat admin via /api/admin/config, read by playout).
+# Both resolve to the same host file through the ./data/playlist volume.
+CONFIG_PATH=/app/playlist/config.json
+PLAYOUT_CONFIG_PATH=/app/playlist/config.json
 
 # Logging / Monitoring
 LOG_LEVEL=info
@@ -63,4 +71,4 @@ GRAFANA_PORT=3001
 
 # Development flags
 NODE_ENV=development
-GO_ENV=development
+GO_ENV=development

.gitea/workflows/cd.yml

@@ -6,12 +6,14 @@
 name: CD
 
 on:
-  push:
+  workflow_run:
-    branches: [main]
+    workflows: [CI]
+    types: [completed]
   workflow_dispatch:
 
 jobs:
   deploy:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: [ubuntu-latest]
     steps:
       - name: Checkout code
@@ -31,16 +33,44 @@ jobs:
       - name: Prepare environment
         run: |
           cat > .env << 'EOF'
+          # Database & Redis
           DATABASE_URL="${{ secrets.DATABASE_URL }}"
           REDIS_URL=redis://redis:6379/0
+
+          # Playout
           PLAYLIST_PATH=/app/playlist/playlist.txt
-          HLS_SEGMENT_DURATION=6
+          HLS_SEGMENT_DURATION=2
-          HLS_WINDOW_SIZE=24
+          HLS_WINDOW_SIZE=12
           LOG_LEVEL=info
+
+          # Cloudflare R2 (required for HLS segment sync)
+          R2_ACCESS_KEY_ID="${{ secrets.R2_ACCESS_KEY_ID }}"
+          R2_SECRET_ACCESS_KEY="${{ secrets.R2_SECRET_ACCESS_KEY }}"
+          R2_BUCKET_NAME="${{ secrets.R2_BUCKET_NAME }}"
+          R2_ENDPOINT="${{ secrets.R2_ENDPOINT }}"
+          R2_REGION=auto
+
+          # Cloudflare
+          CLOUDFLARE_API_TOKEN="${{ secrets.CLOUDFLARE_API_TOKEN }}"
+          CLOUDFLARE_ACCOUNT_ID="${{ secrets.CLOUDFLARE_ACCOUNT_ID }}"
+          MEDIA_DOMAIN=${{ secrets.MEDIA_DOMAIN }}
+
+          # Frontend public URLs
+          VITE_PUBLIC_APP_URL=${{ secrets.VITE_PUBLIC_APP_URL }}
+          VITE_PUBLIC_WS_URL=${{ secrets.VITE_PUBLIC_WS_URL }}
+          VITE_PUBLIC_HLS_URL=${{ secrets.VITE_PUBLIC_HLS_URL }}
+          VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR }}
+          VITE_PUBLIC_ADMIN_DEFAULT_ROOM=${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_ROOM }}
+          VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
+
+          # Admin auth
           ADMIN_USERNAME="${{ secrets.ADMIN_USERNAME }}"
           ADMIN_PASSWORD="${{ secrets.ADMIN_PASSWORD }}"
           ADMIN_SESSION_TTL_HOURS=12
-          NGINX_PORT=80
+
+          # Nginx
+          # Host port 80/443 (Coolify Traefik) and 8080 are taken; nginx publishes on 8082.
+          NGINX_PORT=8082
           EOF
 
       - name: Seed Prometheus config on remote host
@@ -216,7 +246,7 @@ jobs:
           DOCKER_HOST: tcp://192.168.88.40:2375
         run: |
           # Wait for services to stabilize
-          sleep 20
+          sleep 30
 
           # Check chat health (via docker exec — IP-agnostic, works on any DOCKER_HOST)
           echo "Checking chat health..."
@@ -241,8 +271,8 @@ jobs:
               echo "Playout is healthy"
               break
             fi
-            echo "Playout not ready yet (attempt $i/6), waiting 5s..."
+            echo "Playout not ready yet (attempt $i/6), waiting 20s..."
-            sleep 5
+            sleep 20
           done
           if ! docker exec linearvoid-playout curl -sf http://localhost:8081/health; then
             echo "Playout failed to become healthy after 6 attempts"

.gitea/workflows/ci.yml

@@ -1,144 +1,147 @@
-name: CI
+name: CI
-
+
-on:
+on:
-  push:
+  push:
-    branches: [main]
+    branches: [main]
-  pull_request:
+  pull_request:
-    branches: [main]
+    branches: [main]
-
+
-jobs:
+jobs:
-  test:
+  test:
-    runs-on: [ubuntu-latest]
+    runs-on: [ubuntu-latest]
-    steps:
+    steps:
-      - name: Checkout code
+      - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v4
-        with:
+        with:
-          fetch-depth: 0
+          fetch-depth: 0
-
+
-      - name: Setup Node.js
+      - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v4
-        with:
+        with:
-          node-version: "20"
+          node-version: "22"
-
+
-      - name: Install Frontend Dependencies
+      - name: Install Frontend Dependencies
-        run: cd frontend && npm ci
+        run: cd frontend && npm ci
-
+
-      - name: Lint Frontend
+      - name: Lint Frontend
-        run: cd frontend && npm run lint
+        run: cd frontend && npm run lint
-
+
-      - name: Build Frontend
+      - name: Test Frontend with Coverage
-        run: cd frontend && npm run build
+        run: cd frontend && npm run test:coverage
-
+
-      - name: Setup Go
+      - name: Build Frontend
-        uses: actions/setup-go@v5
+        run: cd frontend && npm run build
-        with:
+
-          go-version: "1.25"
+      - name: Setup Go
-        env:
+        uses: actions/setup-go@v5
-          GOTOOLCHAIN: local
+        with:
-
+          go-version: "1.25"
-      - name: Download Go modules
+        env:
-        run: cd backend/chat && GOTOOLCHAIN=local go mod download
+          GOTOOLCHAIN: local
-
+
-      - name: Validate Go
+      - name: Download Go modules
-        run: cd backend/chat && GOTOOLCHAIN=local go vet ./...
+        run: cd backend/chat && GOTOOLCHAIN=local go mod download
-
+
-      - name: Run Tests
+      - name: Validate Go
-        run: cd backend/chat && GOTOOLCHAIN=local go test ./... -v -cover -coverprofile=coverage.out -race
+        run: cd backend/chat && GOTOOLCHAIN=local go vet ./...
-
+
-      - name: Check Coverage
+      - name: Run Tests
-        run: |
+        run: cd backend/chat && GOTOOLCHAIN=local go test ./... -v -cover -coverprofile=coverage.out -race
-          cd backend/chat
+
-          COVERAGE=$(GOTOOLCHAIN=local go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')
+      - name: Check Coverage
-          echo "Coverage: $COVERAGE%"
+        run: |
-          if [ "$(echo "$COVERAGE < 50" | bc)" -eq 1 ]; then
+          cd backend/chat
-            echo "Coverage $COVERAGE% below 50% threshold"
+          COVERAGE=$(GOTOOLCHAIN=local go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')
-            exit 1
+          echo "Coverage: $COVERAGE%"
-          fi
+          if [ "$(echo "$COVERAGE < 50" | bc)" -eq 1 ]; then
-
+            echo "Coverage $COVERAGE% below 50% threshold"
-  docker:
+            exit 1
-    needs: test
+          fi
-    runs-on: [ubuntu-latest]
+
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+  docker:
-    steps:
+    needs: test
-      - name: Checkout code
+    runs-on: [ubuntu-latest]
-        uses: actions/checkout@v4
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        with:
+    steps:
-          fetch-depth: 0
+      - name: Checkout code
-
+        uses: actions/checkout@v4
-      - name: Set up Docker Buildx
+        with:
-        uses: docker/setup-buildx-action@v3
+          fetch-depth: 0
-
+
-      - name: Log in to Gitea Container Registry
+      - name: Set up Docker Buildx
-        uses: docker/login-action@v3
+        uses: docker/setup-buildx-action@v3
-        with:
+
-          registry: git.allucanget.biz
+      - name: Log in to Gitea Container Registry
-          username: ${{ secrets.CI_REGISTRY_USER }}
+        uses: docker/login-action@v3
-          password: ${{ secrets.CI_REGISTRY_TOKEN }}
+        with:
-
+          registry: git.allucanget.biz
-      - name: Extract metadata for Playout
+          username: ${{ secrets.CI_REGISTRY_USER }}
-        id: meta-playout
+          password: ${{ secrets.CI_REGISTRY_TOKEN }}
-        uses: docker/metadata-action@v5
+
-        with:
+      - name: Extract metadata for Playout
-          images: git.allucanget.biz/zwitschi/linearvoid/playout
+        id: meta-playout
-          tags: |
+        uses: docker/metadata-action@v5
-            type=ref,event=branch
+        with:
-            type=ref,event=pr
+          images: git.allucanget.biz/zwitschi/linearvoid/playout
-            type=semver,pattern={{version}}
+          tags: |
-            type=semver,pattern={{major}}.{{minor}}
+            type=ref,event=branch
-            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=pr
-
+            type=semver,pattern={{version}}
-      - name: Build and push Playout image
+            type=semver,pattern={{major}}.{{minor}}
-        uses: docker/build-push-action@v5
+            type=raw,value=latest,enable={{is_default_branch}}
-        with:
+
-          context: ./backend/playout
+      - name: Build and push Playout image
-          file: ./backend/playout/Dockerfile
+        uses: docker/build-push-action@v5
-          push: true
+        with:
-          tags: ${{ steps.meta-playout.outputs.tags }}
+          context: ./backend/playout
-          labels: ${{ steps.meta-playout.outputs.labels }}
+          file: ./backend/playout/Dockerfile
-          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout
+          push: true
-          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout,mode=max
+          tags: ${{ steps.meta-playout.outputs.tags }}
-
+          labels: ${{ steps.meta-playout.outputs.labels }}
-      - name: Extract metadata for Chat
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout
-        id: meta-chat
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout,mode=max
-        uses: docker/metadata-action@v5
+
-        with:
+      - name: Extract metadata for Chat
-          images: git.allucanget.biz/zwitschi/linearvoid/chat
+        id: meta-chat
-          tags: |
+        uses: docker/metadata-action@v5
-            type=ref,event=branch
+        with:
-            type=ref,event=pr
+          images: git.allucanget.biz/zwitschi/linearvoid/chat
-            type=semver,pattern={{version}}
+          tags: |
-            type=semver,pattern={{major}}.{{minor}}
+            type=ref,event=branch
-            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=pr
-
+            type=semver,pattern={{version}}
-      - name: Build and push Chat image
+            type=semver,pattern={{major}}.{{minor}}
-        uses: docker/build-push-action@v5
+            type=raw,value=latest,enable={{is_default_branch}}
-        with:
+
-          context: ./backend/chat
+      - name: Build and push Chat image
-          push: true
+        uses: docker/build-push-action@v5
-          tags: ${{ steps.meta-chat.outputs.tags }}
+        with:
-          labels: ${{ steps.meta-chat.outputs.labels }}
+          context: ./backend/chat
-          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat
+          push: true
-          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat,mode=max
+          tags: ${{ steps.meta-chat.outputs.tags }}
-
+          labels: ${{ steps.meta-chat.outputs.labels }}
-      - name: Extract metadata for Nginx
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat
-        id: meta-nginx
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat,mode=max
-        uses: docker/metadata-action@v5
+
-        with:
+      - name: Extract metadata for Nginx
-          images: git.allucanget.biz/zwitschi/linearvoid/nginx
+        id: meta-nginx
-          tags: |
+        uses: docker/metadata-action@v5
-            type=ref,event=branch
+        with:
-            type=ref,event=pr
+          images: git.allucanget.biz/zwitschi/linearvoid/nginx
-            type=semver,pattern={{version}}
+          tags: |
-            type=semver,pattern={{major}}.{{minor}}
+            type=ref,event=branch
-            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=pr
-
+            type=semver,pattern={{version}}
-      - name: Build and push Nginx image
+            type=semver,pattern={{major}}.{{minor}}
-        uses: docker/build-push-action@v5
+            type=raw,value=latest,enable={{is_default_branch}}
-        with:
+
-          context: .
+      - name: Build and push Nginx image
-          file: infrastructure/nginx/Dockerfile
+        uses: docker/build-push-action@v5
-          push: true
+        with:
-          tags: ${{ steps.meta-nginx.outputs.tags }}
+          context: .
-          labels: ${{ steps.meta-nginx.outputs.labels }}
+          file: infrastructure/nginx/Dockerfile
-          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx
+          push: true
-          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx,mode=max
+          tags: ${{ steps.meta-nginx.outputs.tags }}
+          labels: ${{ steps.meta-nginx.outputs.labels }}
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx,mode=max

.gitea/workflows/workers-deploy.yml

@@ -0,0 +1,41 @@
+name: Deploy to Cloudflare Workers
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: cd frontend && npm ci
+
+      - name: Build
+        env:
+          VITE_PUBLIC_APP_URL: ${{ secrets.VITE_PUBLIC_APP_URL }}
+          VITE_PUBLIC_WS_URL: ${{ secrets.VITE_PUBLIC_WS_URL }}
+          VITE_PUBLIC_HLS_URL: ${{ secrets.VITE_PUBLIC_HLS_URL }}
+          VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR }}
+          VITE_PUBLIC_ADMIN_DEFAULT_ROOM: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_ROOM }}
+          VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT: "50"
+        run: cd frontend && npm run build
+
+      - name: Deploy to Cloudflare Workers
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          cd frontend
+          npx wrangler deploy

.gitea/workflows/workers-media-deploy.yml

@@ -0,0 +1,35 @@
+name: Deploy Media Worker to Cloudflare
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    # Production deploy: only on pushes to main (via CI success) or manual main runs.
+    if: ${{ (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') || (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: cd infrastructure/cloudflare && npm ci
+
+      - name: Test worker
+        run: cd infrastructure/cloudflare && npm test
+
+      - name: Deploy to Cloudflare Workers (production)
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          cd infrastructure/cloudflare
+          npx wrangler deploy --env production

.github/AGENTS.md

@@ -2,10 +2,6 @@
 
 Agents instructions for the linearvoid project.
 
-## Output
-
-- use /caveman skill, latest version from <https://github.com/JuliusBrussee/caveman> is <https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman>
-
 ## General Guidelines
 
 - Use the architecture documentation (arc42 template and ADRs in `docs`) as the source of truth for design decisions.
@@ -14,9 +10,28 @@ Agents instructions for the linearvoid project.
 
 ## Task Management
 
-- Plan any task in the `TODO.md` file with clear steps and mark them as completed when done. Move completed sections to DONE.md. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
+- Plan any task in the `.github/instructions/TODO.md` file with clear steps and mark them as completed when done. Move completed sections to `.github/instructions/DONE.md`. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
 - Before taking any action except for planning and writing `TODO.md`, always ask user for confirmation, accept `go`, `ok`, `yes`, `next`, or `continue` to proceed. If the user says `no`, `stop`, or `cancel`, abort the action and return to planning.
 
+### Required tracking files — update at every development step
+
+These files must be kept current with every change. Do not let them drift.
+
+| File                              | Purpose                                       | When to update                                                     |
+| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
+| `.github/instructions/TODO.md`    | Active implementation plan with checkboxes    | Mark items done as they complete; add new items when scope expands |
+| `.github/instructions/BACKLOG.md` | Deferred, manual, and operational tasks       | Sync whenever TODO items complete or new gaps are identified       |
+| `.github/instructions/DONE.md`    | Archive of completed TODO sections            | Move completed sections here from TODO.md                          |
+| `.github/MEMORY.md`               | Session memory — what was done, when, and why | Append dated entry after each meaningful batch of changes          |
+| `CHANGELOG.md`                    | User-facing release notes                     | Add entry when a phase or significant feature completes            |
+| `docs/STREAMING.md`               | Streaming pipeline contract                   | Update when playout, HLS, or caching behavior changes              |
+| `docs/DEPLOYMENT.md`              | Deploy and infrastructure procedures          | Update when pipeline, topology, or provisioning changes            |
+| `docs/SETUP.md`                   | Environment and onboarding guide              | Update when prerequisites, `.env`, or setup steps change           |
+| `docs/MONITORING.md`              | Observability reference                       | Update when metrics, alerts, or dashboards change                  |
+| `docs/API.md`                     | API contract                                  | Update when endpoints, status codes, or rate limits change         |
+| `docs/SECURITY.md`                | Security posture                              | Update when auth, TLS, or rate limiting changes                    |
+| `docs/operations/*.md`            | Runbooks, checklists, how-to guides           | Keep aligned with actual procedures and dashboard URLs             |
+
 ## Security & Secrets Protection
 
 - **Never commit raw secrets or credentials** to the repository.

.github/MEMORY.md

@@ -0,0 +1,154 @@
+# MEMORY
+
+## 2026-08-07
+
+- Completed runtime validation section from TODO.
+- Runtime video normalization tests executed in running `linearvoid-playout` container using ffmpeg/ffprobe.
+- Verified normalized outputs for MOV, MKV, VFR, and 5.1 inputs: `h264`, `yuv420p`, `30/1`, `aac`, `48000`, `2 channels`.
+- Concat continuity check passed with `CONCAT_OK`; output duration `25.344667` seconds.
+- Responsive viewport test on live viewer (`390x844`, `412x915`) detected 8px horizontal overflow from `100vw` usage in viewer container styles.
+- Fixed overflow in source by changing `.lv-body` and `.viewer-shell` width from `100vw` to `100%` in `frontend/src/style.css`.
+- Redis restart test:
+  - Admin session endpoint returned 200 before and after Redis restart.
+  - Presence key survived Redis restart in test-lab configuration.
+  - Redis health returned to `healthy` post-restart.
+- Files changed:
+  - `.github/instructions/TODO.md`
+  - `.github/instructions/DONE.md`
+  - `frontend/src/style.css`
+  - `CHANGELOG.md`
+
+## 2026-08-07 (continued)
+
+- Completed documentation half of recovery runbook TODO item.
+- Expanded `docs/incident-runbook.md` with quarterly DR drill: prerequisites, outage simulation, restore validation, pass/fail criteria, and evidence template.
+- Split TODO item into:
+  - documented drill (`[x]`)
+  - manual rehearsal execution (`[ ]`)
+- Updated `CHANGELOG.md` with incident runbook drill documentation entry.
+
+## 2026-08-07 (continued 2)
+
+- Added manual operations checklist `docs/operations/cloudflare-uptimerobot-checklist.md` for Cloudflare + UptimeRobot task execution and evidence capture.
+- Linked checklist from `SETUP.md` Cloudflare section and TODO manual sections.
+- Did not mark manual dashboard items complete; checklist is preparation only.
+
+## 2026-08-07 (continued 3)
+
+- Added `docs/operations/scaling-performance-playbook.md` covering manifest TTL tuning, TTFB baseline method, WebSocket/API benchmarking approach, cache ratio tracking, capacity triggers, and Phase 2/3 plans.
+- Updated TODO and BACKLOG to mark playbook creation done while keeping execution/measurement tasks pending.
+- Linked scaling playbook in `README.md` resources.
+
+## 2026-08-09
+
+- Added WebSocket benchmark summary helper `scripts/loadtest/summarize-artillery.ps1`.
+- Updated `scripts/loadtest/run-loadtests.ps1` to auto-generate `ws-chat-summary.txt` for `ws` and `all` scenarios.
+- Updated `scripts/loadtest/summarize-k6.ps1` to produce pipeline-friendly output and integrated automatic `admin-api-endpoint-summary.txt` generation.
+- Expanded `scripts/loadtest/README.md` with PowerShell-first artifact capture and helper usage for both ws and admin scenarios.
+- Updated `.gitignore` to ignore loadtest artifacts (`artifacts/` and `scripts/loadtest/artifacts/`).
+- Added artifact-to-worksheet field mapping section in `docs/operations/scaling-performance-playbook.md` so ws/admin worksheet entries map directly to generated summary files.
+- Updated `docs/DEVELOPMENT.md` and `.github/instructions/TODO.md` to mark ws/admin benchmark scaffolding complete while live benchmark execution remains pending.
+- Added `CHANGELOG.md` entry `1.0.10` summarizing loadtest helper automation and playbook mapping updates.
+
+## 2026-08-09 (continued)
+
+- Completed Phase 1 (test fixtures): documented ffmpeg fixture-generation commands in `playlist_test.go` header comments (valid_720p30, invalid_h265, invalid_24fps).
+- Completed Phase 4 (R2 integration):
+  - Enhanced `SyncToR2` in `playlist.go` to set CacheControl + ContentType based on file extension:
+    - `.m4s`, `.ts`, `.mp4`, `.m4a` -> `public, max-age=31536000, immutable` + `video/MP2T`
+    - `.m3u8` -> `public, max-age=2` + `application/vnd.apple.mpegurl`
+    - unknown extension -> no cache headers
+  - Added three tests: `TestSyncToR2` (segment upload with cache verification), `TestSyncToR2_ManifestCacheHeaders` (manifest upload), `TestSyncToR2_NoCacheHeadersForUnknownExt` (unknown extension).
+  - All 17 playout tests pass (16 pass, 1 pre-existing skip).
+- Updated TODO.md: Phase 1 marked complete, Phase 4 partially complete (edge cache hit/miss remains manual).
+- Updated DEVELOPMENT.md: Test Fixtures marked complete, R2 Integration Test marked partially complete.
+
+## 2026-08-09 (continued 2)
+
+- Completed Phase 2 chat tests in `frontend/src/main.test.ts`:
+  - Presence updates: join/leave system messages add and remove users from presence list, sorted rendering.
+  - Private DM flow: togglePrivateDM creates correct dm: room name from sorted usernames.
+  - Message rendering: system messages, self messages (message-self), and other-user messages (message-other) all render correctly.
+  - Total frontend tests: 27 passing (2 test files).
+- Marked Phase 4 "Document stubs/mocks" done (putObject injection pattern).
+- Updated TODO.md: Phase 2 chat tests checked, Phase 4 stubs checked.
+- Updated DEVELOPMENT.md: User Frontend Tests marked partially complete, R2 stubs checked.
+- Updated CHANGELOG.md with Phase 2 presence/DM/message tests.
+
+## 2026-08-09 (continued 3)
+
+- Completed Phase 3 admin frontend tests in `frontend/src/admin.test.ts`:
+  - Exported `savePlaylist` and `renderPlaylistSortable` from `admin.ts`.
+  - Added playlist save test (verifies PUT /api/admin/playlist with JSON body).
+  - Added playlist save error handling test (verifies failure status).
+  - Added sortable rendering test (verifies index, paths, remove buttons, comment/blank line skip).
+  - Total frontend tests: 31 passing (2 test files).
+- Updated TODO.md: Phase 3 playlist/dashboard/API integration all checked.
+- Updated DEVELOPMENT.md: Admin Frontend Tests marked partially complete.
+
+## 2026-08-10 (continued 2)
+
+- Implemented STREAMING.md production-readiness gaps from plan `.hermes/plans/2026-08-10_164500-production-readiness.md`:
+  - **Task 1-2**: Added `runID` (ISO timestamp format) and monotonic `segSequence` for globally unique segment naming (`r-{ISOTIME}/seg-{seq}.m4s`). Replaced `strftime` pattern with run ID-based path.
+  - **Task 2**: Added `watchAndPublishSegments` using `fsnotify` for real-time per-segment R2 upload (~7s delay). Previously `syncLatestToR2()` only ran after FFmpeg exit.
+  - **Task 3**: Added `publishManifest` with atomic `CopyObject` (temp key → final key) to prevent manifest referencing unconfirmed segments.
+  - **Task 4**: Updated `manifestCacheControl` from `"public, max-age=2"` to `"public, max-age=1, s-maxage=2, must-revalidate"` per STREAMING.md.
+  - **Task 5**: Added `hls.on(Hls.Events.ERROR)` handler in `main.ts` with bounded retries (5x), exponential backoff (2s→32s), reconnecting overlay (spinner + text). Added `showReconnecting`/`hideReconnecting` functions.
+  - **Task 6**: Enriched `HealthHandler` with `run_id`, `active_item`, `playlist_revision`, `last_segment_seq`, `last_r2_pub`, `consecutive_failures`. Added "unhealthy" status when R2 publish is stale (>12s).
+- Files changed: `backend/playout/src/playlist.go`, `playlist_test.go`, `go.mod`, `frontend/src/main.ts`, `main.test.ts`, `style.css`, `index.html`.
+- Updated `.github/instructions/TODO.md`, `BACKLOG.md`, `MEMORY.md`, `DONE.md`.
+- Remaining: CORS on media.linearvoid.tv (Cloudflare R2 config, infrastructure).
+
+## 2026-08-10 (continued 3)
+
+- Completed Phase 2 (viewer) + Phase 3 (admin) responsive/accessibility tests:
+  - 5 viewer accessibility tests: video controls/attributes, chat panel aria-labels, chat toggle aria-expanded, message input label, reconnecting overlay aria-live/role.
+  - 3 viewer responsive tests: chat-collapsed toggle, CSS grid layout detection, now-playing aria-live.
+  - 3 admin accessibility tests: nav aria-label, active tab aria-current, nav button focusability.
+  - 2 admin responsive tests: tab content visibility, essential tab presence.
+  - Total: 45 frontend tests passing (2 test files).
+- Added coverage reporting: `vitest.config.ts` with v8 provider, thresholds at 20/15/15/20 (statements/branches/functions/lines).
+- Added `test:coverage` script to `package.json`.
+- Fixed CI: bumped Node from 20 to 22 in `ci.yml` and `workers-deploy.yml` (jsdom@30 requires Node 22+). Added `engines` to `package.json`.
+- Updated AGENTS.md: added Required tracking files table with 13 docs and update cadence.
+- All Go vet, Go tests, frontend test:coverage passing.
+- CORS on media.linearvoid.tv remains the only streaming pipeline gap (Cloudflare R2 config, not code).
+
+## 2026-08-10 (continued 4)
+
+- Verified all test suites pass after streaming pipeline implementation:
+  - Playout: `go mod tidy` (added fsnotify v1.8.0) → all tests pass
+  - Chat: 7 packages pass (go vet + go test)
+  - Frontend: 45 tests pass (2 files), test:coverage meets thresholds (22.92% / 18.44% / 19.01% / 25.42%)
+- Edge cache validation script `scripts/validate-edge-cache.sh` exists.
+- Remaining: CORS on media.linearvoid.tv (Cloudflare R2 bucket CORS config, not a code change). Phases 5-7 are manual/infrastructure only (Cloudflare dashboard, Hetzner provisioning, live benchmarks).
+
+## 2026-08-11
+
+- Consolidated all development tasks from `DEVELOPMENT.md` and `.github/instructions/TODO.md` into `.github/instructions/BACKLOG.md` as the single source of truth. `DEVELOPMENT.md` now obsolete and removed. `TODO.md` references `BACKLOG.md` and `DONE.md`.
+- Fixed R2 endpoint validation in playout service (`backend/playout/src/playlist.go`):
+  - Added `isR2Configured()` checking all four required env vars (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`).
+  - `initR2Client()` now returns a clear error if R2 is not configured instead of creating an S3 client with an empty endpoint.
+  - Segment watcher (`watchAndPublishSegments`), `syncLatestToR2()`, and `publishManifest()` are now guarded by `r2Client != nil` — no error spam when R2 is unavailable.
+  - Playout gracefully degrades: local HLS via nginx works without R2.
+- Updated `.gitea/workflows/cd.yml` "Prepare environment" step to include all R2* variables sourced from Gitea secrets (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`, `R2_ADMIN*\*`), Cloudflare variables (`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`), and frontend public URL variables.
+- Updated `docs/DEPLOYMENT.md` "Environment File" section: replaced vague "Cloudflare/R2 variables" bullet with explicit variable lists and added a new "Gitea Secrets" table documenting all 15 required secrets.
+- All playout tests pass (20 tests), `go vet` clean.
+
+## 2026-08-13
+
+- Completed all remaining enhancement tasks (only manual/infrastructure phases left):
+  - **Playout**: automatic media normalization on upload (`media.NormalizeVideo`, `*.normalized.mp4`, statuses `ready`/`needs_normalization`/`normalizing`/`normalization_failed`, `POST /api/admin/media/{id}/normalize`); R2 segment retention (`cleanupOldRuns`, keep last `R2_KEEP_RUNS` runs, `R2_MAX_RETENTION_BYTES` cap); seamless looping (playlist SHA-256 fingerprint + `-start_number`); single `start-playout.sh` entrypoint + `-validate` mode; loop/cleanup metrics.
+  - **Application configuration**: thread-safe JSON runtime config store (`backend/chat/src/config/runtime.go`) shared with playout via `/app/playlist/config.json`; `GET/PUT /api/admin/config`; admin UI config form.
+  - **Matomo analytics**: public `GET /api/matomo` + viewer pageview snippet in `index.html`.
+  - **Chat user accounts**: register/login/logout/session endpoints, bcrypt hashing, `linearvoid_user_session` cookie, viewer sign-in UI.
+  - **DM history & search**: `GET /api/dm/history` (paginated) + `GET /api/dm/search` + DM search UI.
+  - **Chat UI**: typing indicator, user-list toggle, media status badges, "Add to playlist" gated to `ready`.
+  - **Prometheus TSDB retention**: `--storage.tsdb.retention.time=30d` + `--storage.tsdb.retention.size=15GB` in both compose files; alert rule count corrected 8 → 10.
+- Updated `docs/architecture/README.md` to reflect all `[Unreleased]` changes (normalization, looping, retention, runtime config, Matomo, user accounts, DM history/search, new API endpoints, module tables).
+- Released **1.0.13**: promoted changelog, bumped version, tagged and pushed.
+- Extended frontend test coverage: added `counter.test.ts`, reconnecting/typing/auth/websocket tests, admin failure + status-badge tests → 56 tests; statements 19.89% → 28.58% (CI coverage threshold passing).
+- Fixed Go test data race in `TestHandleAdminMediaByID_Normalize` (waits for async normalization goroutine) + shared in-memory SQLite via `SetMaxOpenConns(1)`.
+- Fixed viewer crash: `index.html` was missing the `#messages` chat container (stray `</section>`); restored structure + made `addMessage` defensive.
+- Set `Doto` as the body font (`--font-body`) and added Google Fonts links to admin + login pages.
+- Files changed: across `backend/chat`, `backend/playout`, `frontend`, `docs`, `docker-compose*.yml`, `.github/instructions/*`.

.github/instructions/BACKLOG.md

@@ -0,0 +1,136 @@
+# BACKLOG
+
+> All current work is planned in [TODO](./TODO.md) (2026-08-13). This file lists backlog items; new unplanned work is added here.
+
+## Setup phases remaining
+
+### Phase 5: complete manual Cloudflare and external-service setup
+
+- [ ] Apply Cloudflare Workers, Tiered Cache, WAF, rate limiting, and HTTPS/HSTS settings in the dashboard
+- [ ] Cloudflare Workers: link custom domain and cut over frontend hosting
+- [ ] Enable Smart Tiered Cache; validate `Cf-Cache-Status: HIT` from upper tier
+- [ ] WAF: enable OWASP Managed Ruleset (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; enforce at edge and origin
+- [ ] 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)
+- [ ] UptimeRobot: alert on 2 consecutive failures via email + Discord/Slack webhook
+- [ ] Capture evidence in `docs/operations/cloudflare-uptimerobot-checklist.md`
+
+### Phase 6: rehearse production deployment end to end
+
+- [ ] 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-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 healthy: `/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
+
+### Phase 7: baseline scaling and performance
+
+- [ ] Execute WebSocket load tests — ramp 10→100→500→1000 connections; measure p95 latency + errors
+- [ ] Execute admin API benchmarks — `wrk`/`k6` against `/api/admin/*`; target p95 <1s
+- [ ] Measure manifest TTFB and cache-hit distribution from multiple US regions (WebPageTest 3+ regions, <4s warm cache)
+- [ ] Tune manifest TTL to 0.5× segment duration; validate `Cf-Cache-Status` distribution
+- [ ] Track cache-hit ratio and R2 ops in production (Cloudflare GraphQL → Grafana panel, alert <90%)
+- [ ] Capacity triggers: Prometheus rules for cache-miss >10%/15min, CPU >80%/10min
+- [ ] Plan Phase 2 service separation (playout CPU, chat latency, DB state, monitoring)
+- [ ] Plan Phase 3 multi-origin resilience (second Hetzner location, warm standby, DNS failover, DB/Redis replication)
+
+### Phase 8: close out remaining test and validation gaps
+
+- [ ] Admin frontend: user moderation tools tests (mute/ban/report, view moderation logs)
+- [ ] Frontend: coverage for all critical user + admin components and interactions
+- [ ] Frontend: document test cases and expected outcomes
+- [ ] Backend R2: test retrieval of segments/manifests via Cloudflare edge
+- [ ] Backend R2: validate edge cache hit/miss behavior with repeat requests (`scripts/validate-edge-cache.sh`)
+
+### Playout
+
+- [ ] Configure an R2 lifecycle rule on the `hls/` prefix as defense-in-depth (manual)
+- [ ] Full-loop E2E (2-file playlist, assert `Looping...` with no `CRASHED` across the boundary) — manual via `scripts/test-playout-e2e.sh`
+
+## Cloudflare Configuration
+
+### DNS & Workers
+
+- [ ] Cloudflare Workers: link custom domain (manual)
+- [ ] Create Cloudflare Worker and cut over frontend hosting (manual)
+
+### Security & TLS
+
+- [ ] Enable Tiered Cache, WAF, rate limiting (manual)
+- [ ] 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
+
+## Monitoring & Observability
+
+### External Monitoring
+
+- [ ] Set up UptimeRobot external monitoring
+- [ ] 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
+
+## 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
+
+### Host Provisioning (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
+
+### CI/CD & Secrets
+
+- [ ] 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
+
+### Smoke Test & Cutover
+
+- [ ] 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
+
+### Production Operations
+
+- [ ] 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
+
+### Load Testing
+
+- [ ] Execute WebSocket load tests with real infrastructure — ramp 10→100→500→1000 connections, measure p95 latency + errors
+- [ ] Execute admin API benchmarks with real infrastructure — `wrk`/`k6` against `/api/admin/*`, target p95 <1s
+
+### Cache & TTFB Optimization
+
+- [ ] Optimize segment immutability and manifest TTL for cache efficiency
+- [ ] Tune manifest TTL: measure `Cf-Cache-Status` distribution, adjust to 0.5× segment duration
+- [ ] Measure playback TTFB from multiple US regions — WebPageTest from 3+ regions, target <4s warm cache
+- [ ] Track cache hit ratio and R2 ops in production — Cloudflare GraphQL → Grafana panel, alert <90%
+
+### Capacity & Future Planning
+
+- [ ] Capacity triggers: Prometheus rules for cache-miss >10%/15min, CPU >80%/10min
+- [ ] Plan Phase 2 service separation — document boundaries (playout CPU, chat latency, DB state, monitoring), estimate per-service resources
+- [ ] Plan Phase 3 multi-origin resilience — research second Hetzner location, design warm standby + DNS failover + DB/Redis replication

.github/instructions/DONE.md

@@ -0,0 +1,78 @@
+# DONE
+
+> Completed tasks from [TODO](./TODO.md). Product, feature, and release history lives in [CHANGELOG](./CHANGELOG.md); this file keeps only engineering and ops notes not captured there.
+
+## Manifest run-scoped rewrite — candidate (a) (2026-09-03)
+
+- Playout now publishes the live R2 manifest with run-scoped media URIs. `rewriteManifestToRun` in `backend/playout/src/playlist.go` prefixes each bare relative URI (`seg-*.m4s` / `init.mp4`, plus `#EXT-X-MAP:URI`) with `r-{runID}/` before `publishManifest`'s atomic `.tmp` → `CopyObject` commit; skipped in slate mode. Added a stubbable `copyObject` hook for tests (consistent with `putObject`/`listObjects`/`deleteObjects`).
+- Tests: `playlist_rewrite_test.go` — `TestRewriteManifestToRun`, `TestRewriteManifestToRun_AlreadyPrefixedUnchanged`, `TestRewriteManifestToRun_HandlesTSAndComments`, `TestRewriteManifestToRun_EmptyRunID`, `TestIsMediaURI`, `TestPublishManifest_RewritesToRunScopedURIs`, `TestPublishManifest_SlateNotRewritten`.
+- Docs updated: `STREAMING.md`, `operations/cloudflare-workers-setup.md`, `architecture/README.md` (incl. Level-2 diagram showing the R2-bound `linearvoid-media` Worker and run-scoped layout).
+- **Still pending (in TODO): live Validation** — deploy the updated playout to the test lab and confirm manifest/segment URIs resolve via `media.linearvoid.tv`.
+
+## Test infrastructure & refactors (2026-08-07)
+
+- Chat service `main.go` split into 8 packages (config, auth, db, handlers, ws, media, ratelimit, metrics); `db.RedisClient` + `db.PubSub` interfaces added for mocking.
+- 78 tests total (Go + frontend), all passing. Coverage: auth 97.8%, config 100%, metrics 100%, ratelimit 90.3%, ws 79.6%, handlers 47.2%, media 36.8%, db 14.3%.
+- Playout: 12 tests. Frontend: vitest + jsdom, 6 user + 5 admin smoke tests.
+- CI: `go test -race -cover` with a 50% coverage threshold; SQLite switched to pure-Go `github.com/glebarez/sqlite` (CGO-free, works on Windows).
+- Frontend coverage enforcement: vitest v8 provider, 40% statements/lines + 30% branches/functions thresholds, `test:coverage` script + CI step.
+
+## Backups
+
+- `scripts/backup-db.sh` (daily pg_dump → R2, 14-day retention), `scripts/backup-weekly.sh` (weekly full dump + integrity check, 8-week retention), `scripts/verify-backups.sh` (download → temp Postgres → restore + row counts).
+
+## Gitea self-hosting migration
+
+- Migrated repo + CI/CD from GitHub to Gitea Actions (`git.allucanget.biz/zwitschi/linearvoid`): self-hosted runner, Container Registry convention `git.allucanget.biz/zwitschi/linearvoid/<service>:<tag>`, secrets renamed `GITEA_*` → `CI_*`.
+
+## Streaming pipeline gaps (2026-08-10)
+
+- Continuous R2 sync via `fsnotify` (`watchAndPublishSegments`, ~7s delay); run-ID + monotonic segment naming (`r-{ISOTIME}/seg-{seq}.m4s`); atomic manifest publication (upload `.tmp` → `CopyObject`); enriched `/health` (run_id, active_item, playlist_revision, last_segment_seq, last_r2_pub, consecutive_failures); player error recovery (5 retries, 2s→32s exponential backoff, reconnecting overlay).
+- CORS on `media.linearvoid.tv` remains infrastructure-only (Cloudflare R2 config, not code).
+
+## Bug fixes not in CHANGELOG
+
+- **2026-08-13 viewer crash**: `index.html` was missing the `#messages` container, so `addMessage` threw `Cannot read properties of null (reading 'appendChild')` on WebSocket open/message. Restored the chat panel structure and made `addMessage` defensive.
+- **2026-08-15 chat reconnect loop**: after a registered user logged in, the chat panel repeatedly filled with old messages. `connectWebSocket` left the replaced socket's `onclose` handler attached, so each intentional reconnect scheduled another reconnect and every connection re-pulled the room's 50-message history on a 3s loop. Fixed by detaching the old socket's `onclose` before closing and guarding the handler against stale sockets. Regression test added; `npm --prefix frontend test` → 58 tests passing.
+
+## Chat improvements
+
+- Manual smoke: viewer join/leave shows a 3s flash (not a chat row); reconnect <5s shows no duplicate; admin chat-log table has no system rows
+
+## Playout improvements
+
+- Test in Firefox: live playback, rebuffer/recovery, chat sync; record quirks in `docs/STREAMING.md`
+- Rebuild + run playout; confirm `playlist.m3u8` lists ~12 segments at 2s each
+- Manual: verify viewer latency and cache-hit behavior after the change
+
+## Chat sidebar (2026-08-17)
+
+- [x] remove search bar from chat sidebar (not needed for single-room)
+- [x] remove "user" toggle button from chat sidebar (hide for now, add back when user interface is stable)
+- [x] make login/registration form a modal and only toggle it when user is not logged in and clicks "Login" or "Register"
+- [x] when user is logged in, do not show login/registration form
+- [x] make sure each message is only rendered once in the chat log (no duplicates on reconnect or initial load)
+
+### Plan
+
+Files: `frontend/index.html`, `frontend/src/main.ts`, `frontend/src/style.css`.
+
+1. **Remove search bar** (single-room)
+   - `index.html`: delete the `<div id="dm-search-row">` block.
+   - `main.ts`: remove `searchDM()` and the `dm-search-btn` listener; drop the `#dm-search-row` show/hide logic in `switchRoom()` (the `searchRow.hidden = !isDM` lines). Keep `currentDMTarget` only if the "New DM" flow stays.
+
+2. **Remove "Users" toggle button**
+   - `index.html`: delete the `<button id="users-toggle-btn">` button.
+   - `main.ts`: remove `toggleUserList()` and the `users-toggle-btn` listener; drop the now-unused `usersVisible` variable.
+
+3. **Login/registration form as a modal**
+   - `index.html`: wrap the `#auth-panel` form in a modal structure (`.auth-modal` + backdrop) with a close button.
+   - `style.css`: add `.auth-modal` / `.auth-modal-backdrop` styles.
+   - `main.ts`: add `openAuthModal()` / `closeAuthModal()`; change the `auth-toggle-btn` handler to open the modal (only when not authenticated) instead of toggling `#auth-panel` inline; wire a close/backdrop-click to `closeAuthModal()`.
+
+4. **Hide form when logged in**
+   - `main.ts` `updateAuthUI()`: when `authenticated` → hide the "Sign in" button and call `closeAuthModal()`; show the user label + "Sign out" button. When not authenticated → show "Sign in" and hide "Sign out".
+
+5. **No duplicate messages**
+   - `main.ts`: add `clearMessages()` (empties `#messages`) and call it at the top of `connectWebSocket()` so each (re)connect renders history fresh instead of appending.
+   - Fix the initial double-connect: make the initial `connectWebSocket("main")` wait for `refreshUserSession()` (or connect once with the resolved username) so history isn't pushed twice on load.

.github/instructions/TODO.md

@@ -0,0 +1,39 @@
+# TODO
+
+> Completed tasks moved to [DONE](./DONE.md). Remaining tasks in [BACKLOG](./BACKLOG.md).
+
+## Playout / R2 manifest–segment layout mismatch
+
+**Chosen approach: candidate (a)** — rewrite the live manifest so its media URIs point into the current run-scoped folder before the atomic R2 publish. Go change in `backend/playout/src/playlist.go`. The `linearvoid-media` Worker stays a faithful path→R2 mapper (no serve-time rewrite).
+
+### Remaining — Validation
+
+- [ ] Run playout (local or test lab), then:
+  - `curl https://media.linearvoid.tv/hls/playlist.m3u8` → 200, short TTL.
+  - Every URI in the manifest resolves `200` with `Cache-Control: public, max-age=31536000, immutable` (via the `linearvoid-media` Worker).
+  - Confirm manifest refresh + `CF-Cache-Status` progression and no 404 on segment fetch across a run loop.
+- [ ] Verify slate fallback still serves correctly after the rewrite change.
+
+> Implementation (candidate a), Go unit tests, and documentation are complete — see [DONE.md](./DONE.md).
+
+## Frontend Tests
+
+### User Frontend
+
+- [ ] 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
+
+- [ ] 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
+
+## Backend Integration Tests
+
+### Cloudflare R2
+
+- [ ] Test retrieval of segments and manifests from R2 via Cloudflare edge
+- [ ] Validate cache hit/miss behavior and performance metrics
+- [ ] Validate edge cache hit/miss behavior with repeat requests — script `scripts/validate-edge-cache.sh` created

.gitignore

@@ -1,95 +1,95 @@
-# =============================================
+# =============================================
-# Linear Void .gitignore
+# Linear Void .gitignore
-# =============================================
+# =============================================
-
+
-# Environment & Secrets
+# Environment & Secrets
-.env
+.env
-.env.local
+.env.local
-.env.*.local
+.env.*.local
-
+
-# Test coverage
+# Test coverage
-coverage
+coverage
-coverage.out
+coverage.out
-
+
-# Logs
+# Logs
-logs
+logs
-*.log
+*.log
-npm-debug.log*
+npm-debug.log*
-yarn-debug.log*
+yarn-debug.log*
-yarn-error.log*
+yarn-error.log*
-pnpm-debug.log*
+pnpm-debug.log*
-
+
-# Runtime data
+# Benchmark artifacts
-pids
+artifacts/
-*.pid
+scripts/loadtest/artifacts/
-*.seed
+
-*.pid.lock
+# Runtime data
-
+pids
-# Dependency directories
+*.pid
-node_modules/
+*.seed
-jspm_packages/
+*.pid.lock
-
+
-# Build outputs
+# Dependency directories
-dist/
+node_modules/
-build/
+jspm_packages/
-out/
+
-*.min.js
+# Build outputs
-
+dist/
-# Go build artifacts
+build/
-*.exe
+out/
-*.exe~
+*.min.js
-*.dll
+
-*.so
+# Go build artifacts
-*.dylib
+*.exe
-
+*.exe~
-# FFmpeg temporary files
+*.dll
-*.ts.tmp
+*.so
-*.m3u8.tmp
+*.dylib
-*.m4s.tmp
+
-hls/
+# FFmpeg temporary files
-temp/
+*.ts.tmp
-
+*.m3u8.tmp
-# Database & local data
+*.m4s.tmp
-*.db
+hls/
-data/
+temp/
-*.sqlite
+
-*.sqlite3
+# Database & local data
-
+*.db
-# Demo data (tracked in backend/playout/demodata/ for out-of-the-box playout)
+data/
-!backend/playout/demodata/
+*.sqlite
-
+*.sqlite3
-# Docker
+
-.dockerignore
+# Demo data (tracked in backend/playout/demodata/ for out-of-the-box playout)
-**/.dockerignore
+!backend/playout/demodata/
-
+
-# Editor & IDE
+# Docker
-.vscode/
+.dockerignore
-.idea/
+**/.dockerignore
-*.swp
+
-*.swo
+# Editor & IDE
-*~
+.vscode/
-
+.idea/
-# OS generated files
+*.swp
-.DS_Store
+*.swo
-.DS_Store?
+*~
-._*
+
-.Spotlight-V100
+# OS generated files
-.Trashes
+.DS_Store
-ehthumbs.db
+.DS_Store?
-Thumbs.db
+._*
-
+.Spotlight-V100
-# Terraform / IaC state
+.Trashes
-*.tfstate
+ehthumbs.db
-*.tfstate.backup
+Thumbs.db
-.terraform/
+
-
+# Terraform / IaC state
-# Agent / Tool files
+*.tfstate
-.github/agents/
+*.tfstate.backup
-.github/instructions/
+.terraform/
-.github/MEMORY.md
+
-
+
-# Temporary architecture artifacts
+# Temporary architecture artifacts
-**/*.tmp
+**/*.tmp
-**/*.bak
+**/*.bak
-
+
 # Note: .github/instructions/ is partially ignored but AGENTS.md and core docs are committed

.prettierignore

@@ -1,95 +1,95 @@
-# =============================================
+# =============================================
-# Linear Void .prettierignore
+# Linear Void .prettierignore
-# =============================================
+# =============================================
-
+
-# Dependencies
+# Dependencies
-node_modules/
+node_modules/
-
+
-# Build outputs
+# Build outputs
-dist/
+dist/
-build/
+build/
-out/
+out/
-*.min.js
+*.min.js
-
+
-# Test coverage
+# Test coverage
-coverage/
+coverage/
-coverage.out
+coverage.out
-
+
-# Go source (handled by gofmt, not prettier)
+# Go source (handled by gofmt, not prettier)
-*.go
+*.go
-go.mod
+go.mod
-go.sum
+go.sum
-
+
-# Binary / compiled
+# Binary / compiled
-*.exe
+*.exe
-*.dll
+*.dll
-*.so
+*.so
-*.dylib
+*.dylib
-
+
-# Media files
+# Media files
-*.m4s
+*.m4s
-*.m3u8
+*.m3u8
-*.ts.tmp        # FFmpeg temp, not TypeScript
+*.ts.tmp        # FFmpeg temp, not TypeScript
-*.m3u8.tmp
+*.m3u8.tmp
-*.png
+*.png
-*.jpg
+*.jpg
-*.jpeg
+*.jpeg
-*.gif
+*.gif
-*.svg
+*.svg
-*.ico
+*.ico
-*.webp
+*.webp
-*.mp4
+*.mp4
-*.webm
+*.webm
-*.mp3
+*.mp3
-*.ogg
+*.ogg
-
+
-# Runtime data
+# Runtime data
-data/
+data/
-pids
+pids
-*.pid
+*.pid
-*.seed
+*.seed
-*.pid.lock
+*.pid.lock
-
+
-# Databases
+# Databases
-*.db
+*.db
-*.sqlite
+*.sqlite
-*.sqlite3
+*.sqlite3
-
+
-# Lockfile (auto-generated, don't reformat)
+# Lockfile (auto-generated, don't reformat)
-package-lock.json
+package-lock.json
-
+
-# Shell scripts (prettier doesn't handle sh)
+# Shell scripts (prettier doesn't handle sh)
-*.sh
+*.sh
-
+
-# Environment & secrets
+# Environment & secrets
-.env
+.env
-.env.*
+.env.*
-!.env.example
+!.env.example
-
+
-# Logs
+# Logs
-*.log
+*.log
-
+
-# Editor & IDE
+# Editor & IDE
-.vscode/
+.vscode/
-.idea/
+.idea/
-*.swp
+*.swp
-*.swo
+*.swo
-
+
-# OS files
+# OS files
-.DS_Store
+.DS_Store
-Thumbs.db
+Thumbs.db
-
+
-# Git
+# Git
-.git/
+.git/
-
+
-# Terraform / IaC
+# Terraform / IaC
-*.tfstate
+*.tfstate
-*.tfstate.backup
+*.tfstate.backup
-.terraform/
+.terraform/
-
+
-# Temp & backup files
+# Temp & backup files
-**/*.tmp
+**/*.tmp
-**/*.bak
+**/*.bak
-
+
-# Docker
+# Docker
-.dockerignore
+.dockerignore

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 120,
+  "endOfLine": "lf",
+  "proseWrap": "preserve"
+}

API.md

@@ -1,307 +0,0 @@
-# API Reference
-
-This document describes the currently implemented API surfaces in Linear Void.
-
-## Base URLs
-
-- Public app and admin: <https://linearvoid.tv>
-- WebSocket endpoint: <wss://linearvoid.tv/ws>
-- Local fallback: <http://localhost> and <ws://localhost/ws>
-
-## Authentication Model
-
-Admin REST endpoints use a cookie session.
-
-- Cookie name: linearvoid_admin_session
-- Cookie attributes: HttpOnly, SameSite=Strict, Secure when request is HTTPS (or X-Forwarded-Proto=https)
-- Session TTL: controlled by ADMIN_SESSION_TTL_HOURS (default 12h)
-
-## Chat WebSocket API
-
-### Connect
-
-Endpoint:
-
-- GET /ws?username={name}&room={room}
-
-Client sends JSON messages over the socket.
-
-### Message Envelope (client -> server)
-
-```json
-{
-  "room": "main",
-  "username": "viewer123",
-  "text": "hello world",
-  "type": "public"
-}
-```
-
-Notes:
-
-- type is usually public for room chat and private for DM room routing.
-- Private room names are formatted like dm:userA-userB (sorted usernames).
-- Moderation/system events are sent as type=system messages.
-
-### Message Envelope (server -> client)
-
-```json
-{
-  "room": "main",
-  "username": "viewer123",
-  "text": "hello world",
-  "type": "public",
-  "timestamp": "2026-08-04T12:34:56Z"
-}
-```
-
-## Admin Session API
-
-### Login
-
-- POST /api/admin/login
-- Auth: none
-
-Request:
-
-```json
-{
-  "username": "admin",
-  "password": "your-password"
-}
-```
-
-Success response:
-
-```json
-{
-  "authenticated": true,
-  "username": "admin"
-}
-```
-
-### Logout
-
-- POST /api/admin/logout
-- Auth: optional (clears cookie either way)
-
-Response:
-
-```json
-{
-  "authenticated": false
-}
-```
-
-### Session Check
-
-- GET /api/admin/session
-- Auth: cookie required
-
-Success response:
-
-```json
-{
-  "authenticated": true,
-  "username": "admin"
-}
-```
-
-Failure:
-
-- 401 unauthorized
-
-## Admin Data API
-
-All endpoints below require admin authentication.
-
-### Overview
-
-- GET /api/admin/overview
-
-Returns aggregate counters and runtime/system snapshot fields.
-
-### Playlist
-
-- GET /api/admin/playlist
-- PUT /api/admin/playlist
-
-PUT request:
-
-```json
-{
-  "content": "file '/app/media/video1.mp4'\nfile '/app/media/video2.mp4'\n"
-}
-```
-
-### Schedule
-
-- GET /api/admin/schedule
-
-Returns parsed playlist entries plus matched media metadata/runtime.
-
-### Moderation
-
-- GET /api/admin/moderation/logs?limit=50
-- POST /api/admin/moderation/actions
-
-Action request:
-
-```json
-{
-  "action": "mute",
-  "target": "username-or-id",
-  "moderator": "admin",
-  "reason": "spam",
-  "room": "main"
-}
-```
-
-### Analytics
-
-- GET /api/admin/analytics
-
-Returns totals (messages, moderation actions, rooms) and top room summary.
-
-### System
-
-- GET /api/admin/system
-
-Returns service health snapshot for chat/playout/redis/database and config metadata.
-
-### Active Users
-
-- GET /api/admin/users
-
-Returns currently discovered presence users (room + username) when Redis is available.
-
-## Media Library API
-
-### Media Collection
-
-- GET /api/admin/media
-- POST /api/admin/media (multipart upload, legacy path)
-
-Multipart form field name: file
-
-### Media Item
-
-- GET /api/admin/media/{id}
-- PUT /api/admin/media/{id}
-- DELETE /api/admin/media/{id}
-
-PUT request:
-
-```json
-{
-  "status": "ready",
-  "title": "My Clip",
-  "tags": "music,live"
-}
-```
-
-## Resumable Upload API
-
-Maximum file size: 2GB
-
-Default chunk size: 8MB
-
-### Initialize or Resume Session
-
-- POST /api/admin/media/uploads
-
-Request:
-
-```json
-{
-  "uploadId": "optional-existing-id",
-  "fileName": "clip.mp4",
-  "fileSize": 123456789,
-  "mimeType": "video/mp4",
-  "chunkSize": 8388608,
-  "totalChunks": 15
-}
-```
-
-Response:
-
-```json
-{
-  "uploadId": "hex-token",
-  "fileName": "clip.mp4",
-  "fileSize": 123456789,
-  "chunkSize": 8388608,
-  "totalChunks": 15,
-  "uploadedChunks": 3,
-  "progress": 20
-}
-```
-
-### Check Upload Status
-
-- GET /api/admin/media/uploads/{uploadId}
-
-Returns same status envelope as initialize.
-
-### Upload Chunk
-
-- PUT /api/admin/media/uploads/{uploadId}/chunk?index={chunkIndex}
-- Content-Type: application/octet-stream
-
-Response returns updated upload status envelope.
-
-### Complete Upload
-
-- POST /api/admin/media/uploads/{uploadId}/complete
-
-On success returns admin media listing payload (files + generatedAt).
-
-## Metrics and Health
-
-### Chat metrics
-
-- GET /metrics
-
-Prometheus exposition includes connected clients, stored messages, moderation actions, Redis indicators, active admin sessions, and build info.
-
-### Health
-
-- GET /health on chat service
-- GET /health on playout service
-- GET /health on nginx reverse proxy
-
-## HTTP Status Conventions
-
-| Code | Meaning               | When                                                        |
-| ---- | --------------------- | ----------------------------------------------------------- |
-| 200  | OK                    | Successful GET, PUT, or action                              |
-| 201  | Created               | Successful POST (upload init, override created)             |
-| 204  | No Content            | Successful DELETE, CORS preflight                           |
-| 400  | Bad Request           | Malformed JSON, missing required fields, invalid input      |
-| 401  | Unauthorized          | Missing or expired admin session                            |
-| 403  | Forbidden             | Valid session but insufficient permissions                  |
-| 404  | Not Found             | Resource doesn't exist                                      |
-| 405  | Method Not Allowed    | Wrong HTTP method for endpoint                              |
-| 409  | Conflict              | Schedule override overlap, upload ID mismatch               |
-| 413  | Payload Too Large     | Upload exceeds 2 GB limit                                   |
-| 422  | Unprocessable         | File fails normalization check (codec, fps, resolution)     |
-| 429  | Too Many Requests     | Rate limit exceeded (chat messages, WS connections, login)  |
-| 500  | Internal Server Error | Unexpected server failure                                   |
-| 503  | Service Unavailable   | Redis unavailable for user actions, playout health degraded |
-
-## Rate Limiting
-
-All limits are per-IP (from `X-Forwarded-For` or `RemoteAddr`) unless noted.
-
-| Resource              | Limit                              | Window                                   | Response                                               |
-| --------------------- | ---------------------------------- | ---------------------------------------- | ------------------------------------------------------ |
-| Chat messages         | `CHAT_RATE_LIMIT_MAX` (default 10) | `CHAT_RATE_LIMIT_WINDOW_S` (default 10s) | 429 + `{"type":"system","text":"Rate limit exceeded"}` |
-| WebSocket connections | 5                                  | 60s                                      | 429 + `"too many connections from this IP"`            |
-| Admin login           | 5                                  | 5min                                     | 429 + `"too many login attempts, try again later"`     |
-
-Rate limit headers on applicable responses:
-
-- `X-RateLimit-Limit`: maximum requests per window
-- `Retry-After`: seconds until window resets
-- 413: payload too large
-- 500: internal server error

CHANGELOG.md

@@ -2,6 +2,113 @@
 
 <!-- markdownlint-disable MD024 -->
 
+## [1.1.0] - 2026-09-03
+
+### Added
+
+- **Cloudflare media edge worker (`linearvoid-media`)**: new self-contained project under `infrastructure/cloudflare/` — an R2-bound Worker owning `media.linearvoid.tv` that enforces immutable segment caching (`public, max-age=31536000, immutable`) and short-TTL live `.m3u8`, with HLS CORS/OPTIONS, byte-Range, and a `/health` probe. Includes Vitest unit tests + Miniflare/workerd R2 integration tests and production deploy via `.gitea/workflows/workers-media-deploy.yml`. Replaces the ad-hoc `worker.js`.
+- **Bash script ports**: Linux/macOS equivalents of the Windows ops/load-test scripts (`cache-hit-ratio`, `check-env`, `check-tokens`, loadtest run/summarize); `.ps1` files retained.
+- **Transient presence flash**: join/leave events show as a 3-second `#chat-flash` instead of permanent chat rows.
+
+### Changed
+
+- **Cloudflare Workers hosting**: frontend moved from Cloudflare Pages to the `linearvoid-frontend` static-assets Worker; docs now describe `linearvoid-frontend` (SPA) and `linearvoid-media` (edge HLS), correcting stale `worker.js` and R2 custom-domain wording.
+- **Docs de-Windows'd & condensed**: bash-first guides for `SETUP`, `DEPLOYMENT`, `API`, `MONITORING`, `STREAMING`, `COOLIFY`, incident runbook, scaling playbook, architecture README, and Prometheus metrics inventory.
+- **Compose port de-collision**: playout on host port `8081`, nginx moved to `8082` (`NGINX_PORT` default updated) to avoid Coolify-reserved ports.
+- **Playout**: R2 retention now by run count + byte cap (`R2_KEEP_RUNS` default 2, `R2_MAX_RETENTION_BYTES` default 10 GiB, new gauges) replacing the 24h time-based cleanup; default `HLS_SEGMENT_DURATION` 2s / `HLS_WINDOW_SIZE` 12; deduplicated, concurrent startup validation.
+- **Chat/UX**: 5s reconnect grace window (no join/leave spam); `system` messages no longer persisted; smaller `.message-text`; sidebar cleanup (removed DM search + Users toggle, login/register now a modal).
+- **Auth**: viewer session cookie uses `SameSite=None; Secure` over HTTPS (cross-site SPA) and `Lax` over plain HTTP.
+
+### Fixed
+
+- **Run-scoped R2 manifest URIs (playout)**: `publishManifest` now rewrites bare relative media URIs to the current run folder (`r-{runID}/…`) via `rewriteManifestToRun` before the atomic `.tmp` → `CopyObject` publish, so the live `hls/playlist.m3u8` references resolve against the run-scoped segment keys on `media.linearvoid.tv`. Skipped in slate mode. (Live validation pending — see `TODO.md`.)
+- **Cross-origin auth**: login/register API calls now prefix `VITE_PUBLIC_APP_URL` so the Workers-served SPA reaches the app origin.
+- **Duplicate chat history**: `connectWebSocket` clears messages on each (re)connect and the initial connect waits for session resolution.
+
+### Tests
+
+- WebSocket (`TestHub_Broadcast_SystemNotPersisted`, `TestHub_ReconnectGracePeriod`), handlers (`TestHandleAdminChatLog_ExcludesSystem`), frontend presence flash.
+- Playout: `TestCleanupOldRuns(_SizeCap)`, `TestR2KeepRuns`, `TestR2MaxRetentionBytes`, `TestR2RunFromKey`, `TestValidateWorkersConfig`, `TestValidatePlaylist_Dedup`.
+- Playout (run-scoped manifest rewrite): `TestRewriteManifestToRun`, `TestRewriteManifestToRun_AlreadyPrefixedUnchanged`, `TestRewriteManifestToRun_HandlesTSAndComments`, `TestRewriteManifestToRun_EmptyRunID`, `TestIsMediaURI`, `TestPublishManifest_RewritesToRunScopedURIs`, `TestPublishManifest_SlateNotRewritten`.
+- Cloudflare media worker: Vitest unit (`cacheControlForPath`, `contentTypeForPath`, `parseByteRange`) + Miniflare R2 integration (immutable segment, short-TTL manifest, Range `206`, `404`, OPTIONS, method guard).
+
+## [1.0.13] - 2026-08-13
+
+### Added
+
+- **Automatic media normalization on upload**: Chat backend auto-transcodes non-conforming uploads. New `media.NormalizeVideo` wraps ffmpeg with the Linear Void profile (H.264/AAC, 30fps, 2s keyframes, yuv420p, 48kHz stereo), re-verifies output with ffprobe, and writes `*.normalized.mp4`. Media records gain `normalizing` / `normalization_failed` statuses; `POST /api/admin/media/{id}/normalize` re-triggers manually. Admin UI shows a "Normalize" action with status polling.
+- **R2 segment retention**: Playout `cleanupOldSegments` deletes `hls/r-*/*` objects older than `R2_SEGMENT_RETENTION_HOURS` (default 24h), run hourly + at startup, never touching the live manifest. Exposes `linearvoid_playout_r2_cleanup_objects_total` metric. `.env.example` adds `R2_SEGMENT_RETENTION_HOURS`.
+- **Playout loop metrics**: `linearvoid_playout_loops_total` (clean completions) and `linearvoid_playout_run_duration_seconds` (last run duration).
+- **Runtime configuration store**: Thread-safe, JSON-persisted runtime config (`HLS_SEGMENT_DURATION`, `HLS_WINDOW_SIZE`, `MATOMO_URL`, `MATOMO_SITE_ID`) with typed getters/setters + validation, editable via `GET/PUT /api/admin/config`. Playout reads the shared `config.json` as env fallback.
+- **Matomo analytics**: Viewer pageview snippet in `index.html` driven by the public `GET /api/matomo` endpoint.
+- **Chat user accounts**: Register/login/logout (`POST /api/auth/register`, `/login`, `/logout`, `GET /api/auth/session`), bcrypt password hashing, `linearvoid_user_session` cookie, and a viewer sign-in UI.
+- **Private DM history & search**: `GET /api/dm/history` (paginated) and `GET /api/dm/search`, with a DM search UI in the viewer.
+- **Chat UI polish**: Typing indicator, user-list toggle, media status badges, and an "Add to playlist" action gated to `ready` media.
+
+### Changed
+
+- **Playout seamless looping**: `main()` now only resets HLS output when the playlist changed (SHA-256 `playlistRevision`), on crash/slate recovery, or first run; otherwise it continues segment numbering via `-start_number` and prunes stale segments. Eliminates the viewer gap on clean playlist loops.
+- **Single playout entrypoint**: `start-playout.sh` now runs `/app/playlist-manager -validate` then `exec`s the Go binary, removing the duplicate shell ffmpeg loop. Added a `-validate` mode to `main()`.
+- **Admin media library**: Shows status badges (`ready`/`needs_normalization`/`normalizing`/`failed`) and only offers "Add to playlist" for `ready` media; playlist entries show per-item status badges.
+- **Prometheus TSDB retention**: The `prometheus` service now sets `--storage.tsdb.retention.time=30d` and `--storage.tsdb.retention.size=15GB` (in both `docker-compose.yml` and `docker-compose.prod.yml`), so metrics older than 30 days are deleted.
+
+### Tests
+
+- Media: `TestNormalizationArgs`, `TestNormalizeVideo_FFmpegError`.
+- Handlers: `TestNormalizeMediaRecord_Success`, `TestNormalizeMediaRecord_Failure`, `TestHandleAdminMediaByID_Normalize`.
+- Playout: `TestCleanupOldSegments`, `TestR2SegmentRetentionHours`, `TestPlaylistFingerprint`, `TestHLSNextStartNumber`, `TestLoadSharedHLSConfig`.
+- Config: `runtime_test.go` (get/set, persist/reload, env fallback, validation).
+- Auth: `TestUserSessionStore`.
+- Handlers: config GET/PUT + validation, DM history/search, user register/login/session.
+
+## [1.0.12] - 2026-08-11
+
+### Changed
+
+- **Task tracking consolidated**: Removed `DEVELOPMENT.md` and moved all development tasks to `.github/instructions/BACKLOG.md` as the single source of truth. `TODO.md` updated to reference `BACKLOG.md` and `DONE.md`.
+
+### Fixed
+
+- **Playout R2 endpoint validation**: `initR2Client()` now validates all required R2 environment variables (`R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`) before creating the S3 client. Previously, an empty `R2_ENDPOINT` caused cryptic `Custom endpoint '' was not a valid URI` errors on every segment upload attempt. Playout now gracefully degrades when R2 is not configured — local HLS via nginx continues to work.
+- **CD workflow missing R2 secrets**: `.gitea/workflows/cd.yml` "Prepare environment" step now injects all R2\_ variables (`R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`, plus admin variants) from Gitea secrets. Previously the generated `.env` was missing R2 entirely, causing the playout container to start with an empty endpoint.
+- **Deployment docs**: `docs/DEPLOYMENT.md` now includes explicit R2 and Cloudflare variable lists plus a "Gitea Secrets" table documenting all 15 required secrets.
+
+## [1.0.11] - 2026-08-10
+
+### Added
+
+- **Phase 1 test fixtures**: Media and playlist test fixtures in `backend/playout/testdata/` with ffmpeg generation commands documented in test headers.
+- **Phase 4 R2 integration**: `SyncToR2` now sets `CacheControl` + `ContentType` based on file extension (immutable segments, short-lived manifests). Three integration tests added.
+- **Phase 2 viewer tests**: Presence updates (join/leave/sorted), private DM flow, message rendering (system/self/other) in `main.test.ts` (27 total tests).
+- **Phase 3 admin tests**: Playlist management (save via PUT, error handling, sortable rendering) in `admin.test.ts` (31 total tests passing).
+
+### Changed
+
+- Exported `savePlaylist` and `renderPlaylistSortable` from `admin.ts` for testing.
+
+## [1.0.10] - 2026-08-09
+
+### Added
+
+- **WebSocket summary helper**: Added `scripts/loadtest/summarize-artillery.ps1` to extract counters, rates, and available percentile stats from Artillery JSON output.
+- **Playbook worksheet mapping**: Added artifact-to-worksheet mapping section in `docs/operations/scaling-performance-playbook.md` for WebSocket and Admin API benchmark artifacts.
+- **Test fixture generation docs**: Added ffmpeg commands for generating valid and invalid media fixtures as comments in `backend/playout/src/playlist_test.go`. Phase 1 test fixtures now complete.
+- **R2 cache header support**: `SyncToR2` now sets `CacheControl` and `ContentType` based on file extension:
+  - `.m4s`/`.ts`/`.mp4`/`.m4a` → immutable (max-age=31536000)
+  - `.m3u8` → short-lived (max-age=2s)
+  - unknown → no cache headers
+- **R2 integration tests**: Added `TestSyncToR2_ManifestCacheHeaders` and `TestSyncToR2_NoCacheHeadersForUnknownExt` verifying cache header behavior for segment, manifest, and unknown file types.
+
+### Changed
+
+- **Loadtest runner**: `scripts/loadtest/run-loadtests.ps1` now generates `ws-chat-summary.txt` automatically for `ws` and `all` scenarios.
+- **Loadtest docs**: `scripts/loadtest/README.md` now documents `summarize-artillery.ps1` usage and the new `ws-chat-summary.txt` artifact.
+- **Planning status wording**: Updated `docs/DEVELOPMENT.md` and `.github/instructions/TODO.md` to mark ws/admin benchmark scaffolding complete while benchmark execution remains pending.
+- **Phase 1 complete**: Test fixture creation and ffmpeg documentation marked done.
+- **Phase 4 partially complete**: R2 upload + cache header validation done; edge cache hit/miss validation remains manual.
+- **Phase 2 frontend tests**: Added presence updates (join/leave rendering), private DM flow, and message rendering tests in `main.test.ts` (27 total tests passing).
+- **Phase 3 admin frontend tests**: Added playlist management tests (save via PUT, error handling, sortable rendering) in `admin.test.ts` (31 total tests passing).
+
 ## [1.0.9] - 2026-08-06
 
 ### Added

DEPLOYMENT.md

@@ -1,284 +0,0 @@
-# Deployment Guide
-
-## Table of Contents
-
-- [Deployment Guide](#deployment-guide)
-  - [Table of Contents](#table-of-contents)
-  - [Environments](#environments)
-  - [Production Target (Hetzner)](#production-target-hetzner)
-    - [Planned Infrastructure](#planned-infrastructure)
-    - [Cutover Plan](#cutover-plan)
-    - [Firewall / Security Group](#firewall--security-group)
-    - [Pipeline Readiness](#pipeline-readiness)
-  - [Target Topology](#target-topology)
-  - [Prerequisites](#prerequisites)
-  - [Environment File](#environment-file)
-  - [Pull-and-Run Deployment](#pull-and-run-deployment)
-  - [First-Time or Recovery Provisioning](#first-time-or-recovery-provisioning)
-  - [Health Verification](#health-verification)
-  - [Zero/Low-Downtime Update Pattern](#zerolow-downtime-update-pattern)
-  - [Rollback](#rollback)
-  - [Operational Tasks](#operational-tasks)
-    - [View logs](#view-logs)
-    - [Restart one service](#restart-one-service)
-    - [Stop stack](#stop-stack)
-    - [Keep volumes (recommended) vs remove volumes (destructive)](#keep-volumes-recommended-vs-remove-volumes-destructive)
-  - [Nginx and Proxy Considerations](#nginx-and-proxy-considerations)
-  - [Security Baseline](#security-baseline)
-  - [Common Deployment Pitfalls](#common-deployment-pitfalls)
-  - [Troubleshooting](#troubleshooting)
-
-## Environments
-
-Linear Void runs in two separate environments:
-
-| Environment    | Host                       | Docker Target              | Purpose                                        |
-| -------------- | -------------------------- | -------------------------- | ---------------------------------------------- |
-| **Test Lab**   | `192.168.88.40` (internal) | `tcp://192.168.88.40:2375` | Integration testing, staging, CI/CD validation |
-| **Production** | Hetzner VPS (TBD)          | `tcp://<hetzner-ip>:2375`  | Public linearvoid.tv serving real viewers      |
-
-**Current state (2026-08-06):** Test lab is active and receives automated CD deploys. Production Hetzner VPS is **not yet provisioned**. The CD workflow (`cd.yml`) and `docker-compose.prod.yml` currently target the test lab. Switching to production requires only changing `DOCKER_HOST` — see [Production Deployment](#production-target-hetzner) below.
-
-## Production Target (Hetzner)
-
-**Status: Not provisioned.** The production deployment plan is documented and the pipeline is ready — only the VPS needs to be created.
-
-### Planned Infrastructure
-
-| Resource       | Spec                                             |
-| -------------- | ------------------------------------------------ |
-| Provider       | Hetzner Cloud                                    |
-| Region         | Ashburn, VA (us-east)                            |
-| Instance       | CX22 (2 vCPU, 4 GB RAM, 40 GB SSD) or equivalent |
-| OS             | Ubuntu 24.04 LTS or Debian 12                    |
-| Bandwidth      | 20 TB included traffic/month                     |
-| Estimated cost | ~€7–10/month base                                |
-
-### Cutover Plan
-
-1. Provision Hetzner VPS (see [Production Deployment](#production-target-hetzner) section)
-2. Add production secrets to Gitea (`CI_PROD_*` prefix)
-3. Update `DOCKER_HOST` in CD workflow to Hetzner public IP
-4. Trigger deploy → validate health checks
-5. Update Cloudflare A record `linearvoid.tv` → Hetzner IP
-6. Enable HTTPS, WAF, cache rules on production zone
-7. Decommission test lab as public target
-
-### Firewall / Security Group
-
-| Port | Source                | Purpose                        |
-| ---- | --------------------- | ------------------------------ |
-| 22   | Admin IPs             | SSH management                 |
-| 80   | 0.0.0.0/0             | HTTP (redirect to HTTPS)       |
-| 443  | 0.0.0.0/0             | HTTPS (nginx)                  |
-| 2375 | Gitea runner IP only  | Docker remote API (TLS)        |
-| 9090 | Admin IPs or internal | Prometheus (or tunnel via SSH) |
-| 3001 | Admin IPs or internal | Grafana (or tunnel via SSH)    |
-
-### Pipeline Readiness
-
-Three Gitea Actions workflows drive the full pipeline:
-
-| Workflow      | Trigger          | Purpose                                                                                  |
-| ------------- | ---------------- | ---------------------------------------------------------------------------------------- |
-| `ci.yml`      | Push to `main`   | Lint, build frontend, vet Go, build & push Docker images (`:latest`, `:main`)            |
-| `cd.yml`      | Push to `main`   | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI                 |
-| `release.yml` | Tag push `*.*.*` | Build & push versioned Docker images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release |
-
-CI and CD run simultaneously on every push to `main`. The deploy pulls whatever `:latest` images are available in the registry at that moment.
-
-The CD workflow (`cd.yml`) uses `DOCKER_HOST` to target the deployment host. To switch targets:
-
-```bash
-# Test lab (current)
-DOCKER_HOST=tcp://192.168.88.40:2375
-
-# Production (when provisioned)
-DOCKER_HOST=tcp://<hetzner-public-ip>:2375
-```
-
-No code changes needed in the pipeline. See `DEPLOYMENT.md` Production Deployment section for full checklist.
-
-## Target Topology
-
-- Host: Linux server with Docker Engine
-- Reverse proxy: nginx container (linearvoid-nginx)
-- Core services: playout, chat, redis, postgres
-- Observability: prometheus, grafana
-- CDN/edge: Cloudflare
-
-## Prerequisites
-
-- Docker Engine + Docker Compose plugin
-- Network access to git.allucanget.biz
-- A valid .env file with production values
-- DNS configured for linearvoid.tv (and media.linearvoid.tv if split media domain is used)
-
-## Environment File
-
-Use .env with at least:
-
-- CI_REGISTRY_URL
-- CI_REGISTRY_NAMESPACE
-- CHAT_PORT
-- NGINX_PORT
-- DATABASE_URL (if overridden)
-- REDIS_URL (if overridden)
-- ADMIN_USERNAME
-- ADMIN_PASSWORD
-- VITE_PUBLIC_APP_URL
-- VITE_PUBLIC_WS_URL
-- VITE_PUBLIC_HLS_URL
-- Cloudflare/R2 variables when media sync is enabled
-
-See .env.example and SETUP.md for full variable reference.
-
-## Pull-and-Run Deployment
-
-Images are built and pushed automatically by the CI and release workflows (see [CONTRIBUTING.md](CONTRIBUTING.md#versioning-and-releases) for the release procedure).
-
-Every push to `main` triggers CI (builds `:main` and `:latest` tags) and CD (deploys `:latest` to test lab) in parallel. Semantic version tags (`*.*.*`, e.g. `1.0.9`) trigger the release workflow which builds `:X.Y.Z`, `:X.Y`, and `:latest` tags and creates a Gitea Release.
-
-From repository root:
-
-```bash
-docker login git.allucanget.biz
-
-docker compose -f docker-compose.prod.yml pull
-docker compose -f docker-compose.prod.yml up -d --remove-orphans
-```
-
-## First-Time or Recovery Provisioning
-
-1. Ensure host paths exist:
-
-```bash
-mkdir -p data/chat data/playlist data/media data/hls
-```
-
-1. Confirm volumes and networks:
-
-```bash
-docker volume ls
-docker network ls
-```
-
-1. Start stack:
-
-```bash
-docker compose -f docker-compose.prod.yml up -d
-```
-
-## Health Verification
-
-After startup, check service status:
-
-```bash
-docker compose -f docker-compose.prod.yml ps
-```
-
-Endpoint checks:
-
-- App: <http://{host}:8080/>
-- Nginx health: <http://{host}:8080/health>
-- Chat health: <http://{host}:3000/health>
-- Playout health: <http://{host}:8081/health>
-- Prometheus: <http://{host}:9090>
-- Grafana: <http://{host}:3001>
-
-Domain checks:
-
-- <https://linearvoid.tv>
-- <https://linearvoid.tv/admin>
-- <https://linearvoid.tv/metrics>
-
-## Zero/Low-Downtime Update Pattern
-
-1. Pull newest images.
-1. Recreate changed services only:
-
-```bash
-docker compose -f docker-compose.prod.yml pull
-
-docker compose -f docker-compose.prod.yml up -d nginx chat playout
-```
-
-1. Re-run health checks.
-
-## Rollback
-
-If new images are unhealthy:
-
-1. Pin previous tags in docker-compose.prod.yml.
-2. Pull pinned tags.
-3. Restart impacted services.
-
-```bash
-docker compose -f docker-compose.prod.yml pull
-
-docker compose -f docker-compose.prod.yml up -d nginx chat playout
-```
-
-## Operational Tasks
-
-### View logs
-
-```bash
-docker compose -f docker-compose.prod.yml logs -f nginx chat playout
-```
-
-### Restart one service
-
-```bash
-docker compose -f docker-compose.prod.yml restart chat
-```
-
-### Stop stack
-
-```bash
-docker compose -f docker-compose.prod.yml down
-```
-
-### Keep volumes (recommended) vs remove volumes (destructive)
-
-```bash
-# keep data
-docker compose -f docker-compose.prod.yml down
-
-# destructive (remove data)
-docker compose -f docker-compose.prod.yml down -v
-```
-
-## Nginx and Proxy Considerations
-
-- If an external proxy (for example Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx.
-- For resumable admin uploads, ensure client_max_body_size supports chunk requests in both proxy layers.
-
-## Security Baseline
-
-- Use strong ADMIN_PASSWORD and rotate regularly.
-- Keep Docker host access restricted.
-- Prefer HTTPS/WSS through Cloudflare.
-- Restrict exposed ports if only proxy access is needed.
-
-## Common Deployment Pitfalls
-
-- Missing frontend build artifacts in local-only compose workflows.
-- Wrong registry credentials or missing login.
-- Misaligned domain env vars (app/ws/hls) causing mixed-origin errors.
-
-## Troubleshooting
-
-| Symptom                    | Check                                         | Fix                                                           |
-| -------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
-| Service not starting       | `docker logs linearvoid-<svc> --tail 50`      | Check `.env` vars, volume mounts, port conflicts              |
-| Playout stall / slate mode | `curl http://<host>:8081/health` — mode=slate | Check playlist file, media paths, disk space                  |
-| Chat not connecting        | `curl http://<host>:3000/health`              | Check Redis: `docker exec linearvoid-redis redis-cli ping`    |
-| Admin 401 loop             | Cookie not sent                               | Verify `X-Forwarded-Proto: https`, nginx auth_request headers |
-| Upload fails (413)         | File too large                                | Check nginx `client_max_body_size` (should be 64m+)           |
-| HLS not playing            | `curl http://<host>/hls/playlist.m3u8`        | Check playout health, HLS dir permissions                     |
-| Prometheus no targets      | `curl http://<host>:9090/targets`             | Verify container network, scrape config                       |
-| Grafana no data            | Check datasource                              | Verify Prometheus URL `http://prometheus:9090` provisioned    |
-
-- Proxy-layer body size limits returning 413 on upload.
-- Health checks failing before service warmup is complete.

DEVELOPMENT.md

@@ -1,93 +0,0 @@
-# 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

LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2026 linearvoid.tv (Corey Pellizzi, Georg Sinn)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -5,9 +5,9 @@
 **Repository**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid)
 
 [![Build Status](https://git.allucanget.biz/zwitschi/linearvoid/actions/workflows/ci.yml/badge.svg)](https://git.allucanget.biz/zwitschi/linearvoid/actions)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Gitea](https://img.shields.io/badge/Gitea-1.27.1-blue)](https://git.allucanget.biz)
-[![Version](https://img.shields.io/badge/version-1.0.10-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.1.0-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
 [![Release Notes](https://img.shields.io/badge/release-notes-green)](CHANGELOG.md)
 
 ## Architecture
@@ -46,69 +46,180 @@ flowchart TD
     P -->|sync| R2
 ```
 
+A detailed description of the Streaming architecture, playout, and delivery is available in [`docs/STREAMING.md`](docs/STREAMING.md).
+
 ## Project Structure
 
+This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.
+
 ```text
 linearvoid/
-├── frontend/                  # Static Single-Page Application (HTML/CSS/JS)
+├── docs/                   # see Documentation section below
-│   ├── src/
+├── backend/                # see Backend section below
-│   │   ├── components/        # Video player, chat sidebar, now-playing overlay
+├── frontend/               # see Frontend section below
-│   │   ├── js/                # hls.js integration, WebSocket client, UI logic
+├── infrastructure/         # see Infrastructure section below
-│   │   └── styles/            # Tailwind / custom CSS
+├── monitoring/             # see Monitoring section below
-│   ├── index.html
+├── scripts/                # see Scripts section below
-│   └── package.json           # Build tools (Vite recommended)
+├── .editorconfig           # EditorConfig for consistent coding styles
-├── backend/
+├── .env.example            # Example environment variables for local development
-│   ├── playout/               # Continuous HLS generation from playlist
+├── .gitignore              # Ignore node_modules, build artifacts, etc.
-│   │   ├── src/               # FFmpeg orchestration, playlist manager
+├── .prettierignore         # Ignore files for Prettier formatting
-│   │   ├── config/
+├── CHANGELOG.md            # Release notes and version history
-│   │   └── Dockerfile
+├── CONTRIBUTING.md         # Contribution guidelines
-│   ├── chat/                  # Real-time WebSocket service
+├── docker-compose.prod.yml # Production deployment (Hetzner + Cloudflare)
-│   │   ├── src/               # Rooms, DMs, moderation, presence (Node/Go)
+├── docker-compose.yml      # Top-level for dev (playout + chat + nginx)
-│   │   ├── config/
+└── README.md               # This file
-│   │   └── Dockerfile
-│   └── shared/                # Common utilities, types, normalization helpers
-├── infrastructure/            # Deployment, IaC, Cloudflare configs
-│   ├── docker-compose.yml     # Local/dev orchestration
-│   ├── nginx/                 # Proxy, static serving, HLS delivery
-│   ├── cloudflare/            # Cache rule examples, Workers
-│   └── terraform/             # (optional) provisioning
-├── scripts/                   # Automation scripts
-│   ├── normalize-video.sh     # Pre-process MP4s (codec, keyframes, CRF)
-│   ├── sync-to-r2.sh          # Upload segments/manifests to R2
-│   └── backup.sh
-├── monitoring/                # Dashboards, alerts, logging
-│   ├── grafana/
-│   └── prometheus/
-├── docs/
-│   └── architecture/
-│       ├── README.md          # arc42 template (fully populated)
-│       └── adr/
-│           ├── ADR-001.md             # Consolidated decision record
-│           ├── ADR-002-module-structure.md
-│           ├── ADR-003-tech-stack.md
-│           ├── ADR-004-admin-video.md
-│           ├── ADR-005-admin-moderation-analytics.md
-│           ├── ADR-006-data-storage.md
-│           └── ADR-007-redis-usage.md
-├── .env.example
-├── .gitignore
-├── docker-compose.yml         # Top-level for dev (playout + chat + nginx)
-├── README.md
-└── LICENSE
 ```
 
-### Folder Explanations
+### Documentation
 
-- **`frontend/`**: The viewer experience — minimal, modern SPA with Tailwind + Alpine.js (or vanilla). Uses `hls.js` for playback and a WebSocket client for chat.
+- `docs/`: Folder containing all documentation for the project, including architecture, ADRs, operational procedures, and setup guides.
-- **`backend/playout/`**: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
+- `docs/architecture/`: Architecture documentation, including high-level system architecture, component interactions, and decision records (ADRs).
-- **`backend/chat/`**: Independent WebSocket service (Node.js/Socket.io or Go). Handles public rooms, private DMs, presence (Redis), persistence (PostgreSQL/SQLite), rate limiting, and moderation.
-- **`backend/shared/`**: Reusable code (types, utils, video validation).
-- **`infrastructure/`**: Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform).
-- **`scripts/`**: One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management.
-- **`monitoring/`**: Grafana dashboards, Prometheus rules, logging configuration.
-- **`docs/architecture/`**: Complete arc42 documentation + ADRs 001-007 (the single source of truth for all architectural decisions).
 
-This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation.
+see [README.md](docs/README.md) for full architecture, ADRs, and operational documentation.
+
+### Backend
+
+- `backend/playout/`: Core linear engine. FFmpeg consumes a normalized playlist and outputs continuous HLS. Includes normalization validation.
+- `backend/chat/`: Independent WebSocket service (Node.js/Socket.io or Go). Handles public rooms, private DMs, presence (Redis), persistence (PostgreSQL/SQLite), rate limiting, and moderation.
+- `backend/shared/`: Reusable code (types, utils, video validation).
+
+```text
+backend/
+├── chat/                               # WebSocket chat service (Node.js or Go)
+│   ├── src/                            # Chat service source code (rooms, DMs, moderation)
+|   |   ├── auth/                       # Admin authentication and session management
+|   |   |   ├── auth_test.go            # Unit tests for authentication
+|   |   |   └── auth.go                 # Authentication logic (login, session validation)
+|   |   ├── config/                     # Configuration files for chat service
+|   |   |   ├── config_test.go          # Unit tests for configuration
+|   |   |   └── config.go               # Configuration loading and validation
+|   |   ├── db/                         # Database access and models
+|   |   |   ├── db_test.go              # Unit tests for database access
+|   |   |   ├── db.go                   # Database connection and query logic
+|   |   |   ├── models.go               # Database models (users, messages, rooms)
+|   |   |   └── redis.go                # Redis connection and presence management
+|   |   ├── handlers/                   # WebSocket message handlers
+|   |   |   ├── handlers_test.go        # Unit tests for WebSocket message handlers
+|   |   |   └── handlers.go             # WebSocket message handling logic
+|   |   ├── media/                      # Media-related utilities (e.g., video validation)
+|   |   |   ├── media_test.go           # Unit tests for media-related utilities
+|   |   |   └── media.go                # Media-related utility functions
+|   |   ├── metrics/                    # Prometheus metrics endpoints
+|   |   |   ├── metrics_test.go         # Unit tests for Prometheus metrics
+|   |   |   └── metrics.go              # Prometheus metrics collection and exposition
+|   |   ├── ratelimit/                  # Rate limiting logic (Redis-based)
+|   |   |   ├── ratelimit_test.go       # Unit tests for rate limiting
+|   |   |   └── ratelimit.go            # Rate limiting logic using Redis
+|   |   ├── ws/                         # WebSocket handlers
+|   |   |   ├── ws_test.go              # Unit tests for WebSocket handlers
+|   |   |   └── ws.go                   # WebSocket connection and message handling
+|   |   └── main.go                     # Entry point for chat service
+|   ├── Dockerfile                      # Dockerfile for chat service
+|   ├── go.mod                          # Go module file for chat service
+|   └── go.sum                          # Go checksum file for chat service
+└── playout/                            # Continuous HLS generation from playlist (Go)
+    ├── demodata/                       # Sample media and playlist files for testing
+    |   ├── media/                      # Sample media files for testing
+    |   └── playlist/                   # Sample playlist files for testing
+    ├── src/                            # Playout service source code (FFmpeg orchestration)
+    |   ├── go.mod                      # Go module file for playout service
+    |   ├── go.sum                      # Go checksum file for playout service
+    |   ├── playlist_test.go            # Unit tests for playlist management
+    |   └── playlist.go                 # Playlist management logic
+    └── testdata/                       # Test data for playout service (sample playlists, media)
+    |   ├── comments_only.txt           # Sample playlist with comments only
+    |   ├── empty_playlist.txt          # Sample empty playlist
+    |   ├── invalid_24fps.mp4           # Sample invalid 24fps video for testing
+    |   ├── invalid_h265.mp4            # Sample invalid H.265 video for testing
+    |   ├── mixed_valid_invalid.txt     # Sample playlist with mixed valid and invalid entries
+    |   ├── valid_720p30.mp4            # Sample valid 720p30 video for testing
+    |   └── valid_playlist.txt          # Sample valid playlist for testing
+    ├── Dockerfile                      # Dockerfile for the playout service
+    └── start-playout.sh                # Script to start the playout service
+```
+
+### Frontend
+
+The viewer experience — minimal, modern SPA with custom CSS + vanilla JS. Uses `hls.js` for playback and a WebSocket client for chat.
+
+```text
+frontend/
+├── admin/                  # Admin SPA (playlist management, moderation, analytics)
+│   ├── login/              # Login page for admin authentication
+|   |  └── index.html       # Admin login page
+|   └── index.html          # Admin SPA
+├── public/                 # Static assets (favicon, images, etc.)
+│   ├── admin/              # Admin static assets
+|   |  ├── analytics.html   # Analytics dashboard page
+|   |  ├── chat-log.html    # Chat log viewer page
+|   |  ├── dashboard.html   # Admin dashboard page
+|   |  ├── moderation.html  # User moderation page
+|   |  ├── playlist.html    # Playlist management page
+|   |  ├── schedule.html    # Schedule overrides page
+|   |  ├── system.html      # System configuration page
+|   |  ├── upload.html      # Video upload page
+|   |  └── users.html       # User management page
+│   ├── favicon.ico         # Favicon for the SPA
+|   └── icons.svg           # SVG icons for the SPA
+├── src/                    # Source code for the SPA
+│   ├── assets/             # Images, fonts, and other static assets
+|   |  ├── hero.png         # Hero image for the SPA
+|   |  ├── typescript.svg   # TypeScript logo for the SPA
+|   |  └── vite.svg         # Vite logo for the SPA
+│   ├── admin.test.ts       # Admin frontend tests (Vitest)
+│   ├── admin.ts            # Admin SPA logic (playlist, moderation, analytics)
+│   ├── counter.ts          # Counter component for testing
+│   ├── main.test.ts        # Main frontend tests (Vitest)
+│   ├── main.ts             # Main SPA logic (hls.js player, WebSocket chat)
+│   └── style.css           # Custom CSS for the SPA
+├── .gitignore              # Ignore node_modules, build artifacts, etc.
+├── index.html              # Main SPA entry point
+├── package-lock.json       # Lockfile for npm dependencies
+├── package.json            # Build tools (Vite recommended)
+├── tsconfig.json           # TypeScript configuration
+├── vite.config.ts          # Vite configuration
+└── vitest.config.ts        # Vitest configuration
+```
+
+### Infrastructure
+
+Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform).
+
+- Cloudflare
+  - [linearvoid-media worker](infrastructure/cloudflare/) — R2-bound edge Worker serving HLS on `media.linearvoid.tv` (immutable segment caching, CORS, Range)
+  - [linearvoid-frontend worker](frontend/wrangler.toml) — serves the static SPA on `linearvoid.tv`
+- Nginx
+  - [Dockerfile](infrastructure/nginx/Dockerfile) — builds Nginx with custom config
+  - [nginx.conf](infrastructure/nginx/nginx.conf) — reverse proxy, static SPA, HLS delivery
+
+### Monitoring
+
+Grafana dashboards, Prometheus rules, logging configuration.
+
+- Grafana
+  - dashboards
+    - [dashboard.json](monitoring//grafana/dashboards/dashboard.json) — operational dashboards for playout, chat, and Redis
+    - [dashboard.yml](monitoring//grafana/dashboards/dashboard.yml) — operational dashboards for playout, chat, and Redis
+  - datasources
+    - [datasource.yml](monitoring/grafana/datasources/datasource.yml) — Prometheus datasource configuration
+  - [dashboard.json](monitoring/grafana/dashboard.json) — operational dashboards for playout, chat, and Redis
+- Prometheus
+  - [alerts.yml](monitoring/prometheus/alerts.yml) — alerting rules for playout, chat, Redis, and system health
+  - [prometheus.yml](monitoring/prometheus/prometheus.yml) — scrape targets for playout, chat, Redis, and system metrics
+
+### Scripts
+
+One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management.
+
+- loadtest/
+  - [admin-api.js](scripts/loadtest/admin-api.js) — admin API load test script
+  - [run-loadtests.sh](scripts/loadtest/run-loadtests.sh) — bash script to run ws and/or admin load tests
+  - [summarize-artillery.sh](scripts/loadtest/summarize-artillery.sh) — summarize Artillery JSON results
+  - [summarize-k6.sh](scripts/loadtest/summarize-k6.sh) — summarize k6 JSON results
+  - [ws-chat.yml](scripts/loadtest/ws-chat.yml) — WebSocket chat load test configuration
+
+  PowerShell equivalents (`*.ps1`) of the three load-test scripts are kept alongside them.
 
 ## Getting Started
 
@@ -154,8 +265,8 @@ See the [architecture docs](docs/architecture/README.md) for detailed architectu
 | `VITE_PUBLIC_HLS_URL`  | `https://media.linearvoid.tv/hls/playlist.m3u8` | HLS playlist URL                 |
 | `ADMIN_USERNAME`       | `admin`                                         | Admin panel username             |
 | `ADMIN_PASSWORD`       | —                                               | Admin panel password             |
-| `HLS_SEGMENT_DURATION` | `6`                                             | HLS segment duration in seconds  |
+| `HLS_SEGMENT_DURATION` | `2`                                             | HLS segment duration in seconds  |
-| `HLS_WINDOW_SIZE`      | `24`                                            | HLS playlist window size         |
+| `HLS_WINDOW_SIZE`      | `12`                                            | HLS playlist window size         |
 
 Full reference: [`.env.example`](.env.example).
 
@@ -206,11 +317,11 @@ Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE)
 
 - [CHANGELOG.md](CHANGELOG.md) - Version history and completed features.
 - [CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines for contributing to the project.
-- [SETUP.md](SETUP.md) - Complete setup guide with prerequisites, environment configuration, running the application, and troubleshooting.
+- [SETUP.md](docs/SETUP.md) - Complete setup guide with prerequisites, environment configuration, running the application, and troubleshooting.
-- [API.md](API.md) - Implemented WebSocket and REST API reference.
+- [API.md](docs/API.md) - Implemented WebSocket and REST API reference.
-- [DEPLOYMENT.md](DEPLOYMENT.md) - Production deployment and operations guide.
+- [DEPLOYMENT.md](docs/DEPLOYMENT.md) - Production deployment and operations guide.
-- [MONITORING.md](MONITORING.md) - Prometheus and Grafana setup and troubleshooting.
+- [MONITORING.md](docs/MONITORING.md) - Prometheus and Grafana setup and troubleshooting.
-- [SECURITY.md](SECURITY.md) - Security controls, hardening checklist, and incident baseline.
+- [SECURITY.md](docs/SECURITY.md) - Security controls, hardening checklist, and incident baseline.
 - [Scaling Playbook](docs/operations/scaling-performance-playbook.md) - Performance test method, thresholds, and scaling decision flow.
 - [Architecture Documentation](docs/architecture/README.md) - Full arc42 template with diagrams and decisions.
 - [ADRs](docs/architecture/adr/) - Detailed decision records (ADR-001 to ADR-007).
@@ -232,4 +343,4 @@ Since this is a linear project, we also rely on a linear development and release
 
 [MIT License](LICENSE)
 
-The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions.
+The project is ready for use. See [`SETUP.md`](docs/SETUP.md) for detailed installation instructions.

SETUP.md

@@ -1,588 +0,0 @@
-# Linear Void Setup Guide
-
-This guide covers prerequisites, environment setup, running the application locally and in production, and troubleshooting. It references the [architecture documentation](./docs/architecture/README.md)(`docs/architecture/README.md`).
-
-## Prerequisites
-
-- **Docker & Docker Compose**: Required for running the full stack (playout, chat, nginx, redis, db, prometheus, grafana). Install from [docker.com](https://www.docker.com).
-- **Node.js 20+**: Required for frontend development and production builds (`cd frontend && npm install && npm run build`).
-- **npm**: Installed with Node.js and used for the frontend dependency installation and Vite workflow.
-- **Go 1.23+**: Recommended when working on the Go services outside Docker (`backend/chat`, `backend/playout`).
-- **FFmpeg**: Used by the playout service for HLS generation. Install via `apt install ffmpeg` (Linux), Homebrew (macOS), or Winget (Windows).
-- **Git**: For cloning and version control.
-- **Cloudflare Account**: For R2 storage and CDN (free tier sufficient for most use cases).
-- **Gitea Account**: Required if you want to push images to the self-hosted registry or use the repository's CI/CD flow.
-  - Set up the required Actions secrets in Gitea at: [https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets](https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets)
-  - Add the following secrets:
-    - `CI_REGISTRY_USER`: Your Gitea username (e.g., `zwitschi`)
-    - `CI_REGISTRY_TOKEN`: A Gitea Personal Access Token with `write:packages` scope
-    - `ADMIN_USERNAME`: The administrator username for the production admin panel (e.g., `admin`)
-    - `ADMIN_PASSWORD`: A strong password for the production admin panel
-    - `DATABASE_URL`: The production database connection string (e.g., `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`)
-- **Hetzner Cloud Account** (optional for production): For the US-East VPS (Ashburn, VA recommended per ADR-001).
-
-## Network Environments
-
-Linear Void operates in two distinct environments. Know which one you're targeting.
-
-```mermaid
-flowchart LR
-    subgraph Test_Lab["Test Lab (192.168.88.0/24)"]
-        TEST_HOST["192.168.88.40<br/>Docker Engine :2375"]
-    end
-
-    subgraph Prod["Production (Hetzner — NOT provisioned)"]
-        PROD_HOST["Hetzner CX22 Ashburn, VA<br/>Public IP TBD"]
-    end
-
-    subgraph Gitea["Gitea CI/CD"]
-        CI["CI: build + push images"]
-        CD["CD: deploy via DOCKER_HOST"]
-    end
-
-    subgraph CF["Cloudflare"]
-        DNS["linearvoid.tv"]
-        R2["R2 Bucket"]
-    end
-
-    CD -->|"DOCKER_HOST=tcp://192.168.88.40:2375"| TEST_HOST
-    CD -.->|"DOCKER_HOST=tcp://&lt;hetzner-ip&gt;:2375<br/>(when provisioned)"| PROD_HOST
-    TEST_HOST -->|"test traffic"| DNS
-    PROD_HOST -.->|"production traffic"| DNS
-    TEST_HOST --> R2
-    PROD_HOST -.-> R2
-```
-
-**Test Lab (active):** Internal network `192.168.88.0/24`, host `192.168.88.40`. Receives automated CD deploys from Gitea Actions. Used for integration testing and staging validation.
-
-**Production (pending):** Hetzner Cloud VPS, Ashburn VA. Not yet provisioned. CD workflow and compose files are ready — only `DOCKER_HOST` needs changing. See Production Deployment section in [DEPLOYMENT.md](./DEPLOYMENT.md) for cutover plan.
-
-## Development Prerequisites
-
-- **Frontend dependencies**: Run `cd frontend && npm install` before `npm run dev` or `npm run build`.
-- **Docker build support**: Local development expects Docker to be able to build the `chat`, `playout`, and `nginx` images referenced in `docker-compose.yml`.
-- **Data directories**: Create `data/playlist`, `data/media`, `data/hls`, and `data/chat` before the first run so bind mounts resolve cleanly.
-- **Database choice**: The stack defaults to PostgreSQL in `docker-compose.yml`. If you want SQLite for local-only development, update `DATABASE_URL` in `.env` accordingly.
-- **Redis availability**: Chat presence, rate limiting, and pub/sub require Redis. The compose stack provides it automatically.
-- **Video inputs**: Source videos should be normalized before playout. If the playlist contains invalid files, the playout container will fail its validation flow.
-
-## Environment Setup
-
-1. **Clone the Repository** (if not already done):
-
-   ```bash
-   git clone https://git.allucanget.biz/zwitschi/linearvoid.git
-   cd linearvoid
-   ```
-
-2. **Copy Environment File**:
-
-   ```bash
-   cp .env.example .env
-   ```
-
-3. **Configure `.env`** (edit with your values):
-
-   ```env
-   # Cloudflare R2 (required for video storage and $0 egress)
-   R2_ACCESS_KEY_ID=your-r2-access-key
-   R2_SECRET_ACCESS_KEY=your-r2-secret-key
-   R2_BUCKET_NAME=linearvoid-media
-   R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
-   R2_REGION=auto
-
-   # Cloudflare (for custom domain and cache rules)
-   CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
-   CLOUDFLARE_ACCOUNT_ID=your-account-id
-   MEDIA_DOMAIN=media.linearvoid.tv
-
-   # Public frontend URLs
-   # Preferred local setup uses the real public domains through Cloudflare and Nginx Proxy Manager.
-   VITE_PUBLIC_APP_URL=https://linearvoid.tv
-   VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws
-   VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8
-   VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=admin
-   VITE_PUBLIC_ADMIN_DEFAULT_ROOM=main
-   VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
-   ADMIN_USERNAME=admin
-   ADMIN_PASSWORD=change-me
-   ADMIN_SESSION_TTL_HOURS=12
-   # Optional direct-local fallback when bypassing the public proxy:
-   # VITE_PUBLIC_APP_URL=http://localhost
-   # VITE_PUBLIC_WS_URL=ws://localhost/ws
-   # VITE_PUBLIC_HLS_URL=http://localhost/hls/playlist.m3u8
-
-   # Gitea Container Registry (for self-hosted Docker images)
-   CI_REGISTRY_URL=git.allucanget.biz
-   CI_REGISTRY_USER=your-gitea-username
-   CI_REGISTRY_TOKEN=your-gitea-token
-   CI_REGISTRY_NAMESPACE=zwitschi/linearvoid
-   # Gitea API access (optional, for CI/release automation)
-   CI_SERVER_URL=https://git.allucanget.biz
-
-   # Chat / Database
-   DATABASE_URL=postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable
-   # or for SQLite-only local development:
-   # DATABASE_URL=sqlite://./data/chat.db
-   REDIS_URL=redis://redis:6379/0
-
-   # Ports (for local development)
-   PLAYOUT_PORT=8080
-   CHAT_PORT=3000
-   NGINX_PORT=80
-
-   # Playout Configuration
-   PLAYLIST_PATH=/app/playlist.txt
-   HLS_SEGMENT_DURATION=6
-   HLS_WINDOW_SIZE=24
-
-   # Logging / Monitoring
-   LOG_LEVEL=info
-   PROMETHEUS_PORT=9090
-   GRAFANA_PORT=3001
-
-   # Development flags
-   NODE_ENV=development
-   GO_ENV=development
-   ```
-
-4. **Check local value overrides for Docker Compose**:
-   - `docker-compose.yml` builds images locally and maps the frontend build output from `frontend/dist` into nginx.
-   - `docker-compose.prod.yml` pulls prebuilt images from the Gitea registry.
-   - Internal container-to-container URLs should use compose hostnames, for example `REDIS_URL=redis://redis:6379/0` and `DATABASE_URL=postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`.
-   - For production public routing, set `VITE_PUBLIC_APP_URL=https://linearvoid.tv`, `VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws`, and `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`.
-
-5. **Create Data Directories**:
-
-   ```bash
-   mkdir -p data/playlist data/media data/hls data/chat
-   ```
-
-6. **Prepare Sample Videos** (optional):
-   - Place normalized MP4 files in `data/media/`.
-   - Create a `data/playlist/playlist.txt` with paths (see ADR-001 for normalization requirements).
-
-## Gitea Setup
-
-1. **Create or verify a Gitea user**:
-   - The user should have access to the repository and permission to read from the container registry.
-
-2. **Create an access token**:
-   - Generate a token with the scopes needed for package/registry access and, if applicable, repository automation.
-   - Store it as `CI_REGISTRY_TOKEN` in `.env`.
-
-3. **Configure Gitea Actions Secrets**:
-   - Go to the repository settings page: [https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets](https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets)
-   - Add the following secrets to enable automated CI/CD and production deployment:
-     - `CI_REGISTRY_USER`: Your Gitea username (e.g., `zwitschi`).
-     - `CI_REGISTRY_TOKEN`: Your Gitea Personal Access Token with `write:packages` scope.
-     - `ADMIN_USERNAME`: The administrator username for the production admin panel (e.g., `admin`).
-     - `ADMIN_PASSWORD`: A strong password for the production admin panel.
-     - `DATABASE_URL`: The production database connection string (e.g., `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`).
-
-4. **Configure registry variables**:
-   - Set `CI_REGISTRY_URL` to the Gitea host.
-   - Set `CI_REGISTRY_NAMESPACE` to the image namespace, for example `zwitschi/linearvoid`.
-   - Set `CI_REGISTRY_USER` to the account that will push or pull images.
-
-5. **Authenticate Docker to the registry**:
-
-   ```bash
-   docker login git.allucanget.biz
-   ```
-
-6. **Build and publish images when needed**:
-   - Local development uses `docker-compose.yml`, which builds from source.
-   - Production uses `docker-compose.prod.yml`, which expects the `playout`, `chat`, and `nginx` images to exist in the configured Gitea registry namespace.
-
-7. **Validate image availability**:
-   - Before a production rollout, verify that the expected `:latest` tags can be pulled from the registry on the target server.
-
-## Cloudflare R2 Setup
-
-1. **Create an R2 bucket**:
-   - Create a bucket such as `linearvoid-media` in Cloudflare R2.
-   - Keep the bucket name aligned with `R2_BUCKET_NAME` in `.env`.
-
-2. **Generate R2 API credentials**:
-   - Create an access key pair with read/write permissions for the bucket.
-   - Set `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, and `R2_REGION=auto` in `.env`.
-
-3. **Find the S3 endpoint**:
-   - Use the account-scoped endpoint format `https://<account-id>.r2.cloudflarestorage.com`.
-   - Store the account ID in both `R2_ENDPOINT` and `CLOUDFLARE_ACCOUNT_ID` where applicable.
-
-4. **Bind a custom media domain**:
-   - Attach a domain such as `media.linearvoid.tv` to the bucket.
-   - Set `MEDIA_DOMAIN` to that hostname.
-
-5. **Configure app-domain DNS and TLS**:
-   - Point `linearvoid.tv` to the public entrypoint serving nginx.
-   - Point `www.linearvoid.tv` to the same target and redirect it to `https://linearvoid.tv`.
-   - Keep `media.linearvoid.tv` on the R2 custom domain path so HLS delivery stays split from the app origin.
-   - Use Cloudflare proxied DNS with Full (strict) TLS so browser traffic uses `https://linearvoid.tv`, `wss://linearvoid.tv/ws`, and `https://media.linearvoid.tv`.
-
-6. **Apply cache behavior**:
-   - Configure the `.m4s` and `.m3u8` cache rules from `infrastructure/cloudflare/cache-rules.md`.
-   - Enable Smart Tiered Cache for the R2-backed hostname.
-   - If you need header normalization for immutable segment caching, deploy `infrastructure/cloudflare/worker.js` to the same zone.
-
-7. **Verify access**:
-   - Confirm uploads with an S3-compatible client such as `aws s3 ls --endpoint-url <R2_ENDPOINT>`.
-   - After deployment, check Cloudflare analytics for cache hit ratio and origin request volume.
-
-## Cloudflare
-
-Use this section for full edge setup (DNS, Pages, cache, security, and monitoring).
-
-Execution tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`.
-
-### 1. DNS Setup
-
-1. Add apex record for `linearvoid.tv` pointing to Cloudflare Pages target.
-2. Add `www` CNAME to Cloudflare Pages and configure redirect to `https://linearvoid.tv`.
-3. Add `media.linearvoid.tv` for split-domain HLS delivery.
-4. Keep all records proxied (orange cloud) unless troubleshooting requires DNS-only mode.
-
-### 2. R2 Bucket
-
-1. Create bucket `linearvoid-media`.
-2. Set location hint to `enam` (US-East).
-3. Attach custom domain `media.linearvoid.tv` to the bucket.
-4. Verify object read works from the custom domain.
-
-### 3. Cache Rules
-
-Configure Cloudflare Cache Rules:
-
-1. HLS segment files (`*.ts`, `*.m4s`):
-   - Cache: eligible
-   - Edge TTL: `31536000`
-   - Browser TTL: long-lived
-   - Cache key: include full path
-2. HLS manifests (`*.m3u8`):
-   - Cache: eligible
-   - Edge TTL: `2s`
-   - Revalidation: enabled
-3. Static assets (`*.js`, `*.css`):
-   - Cache: eligible
-   - Edge TTL: `1y`
-   - Browser TTL: long-lived
-   - Cache key: include full path
-4. Validate behavior using response headers:
-   - `Cf-Cache-Status` should move from `MISS` to `HIT` for hot objects
-
-Reference: `infrastructure/cloudflare/cache-rules.md`.
-
-### 4. Cloudflare Pages
-
-1. Connect Gitea repository to Cloudflare Pages.
-2. Build command:
-
-   ```bash
-   cd frontend && npm run build
-   ```
-
-3. Output directory:
-
-   ```text
-   frontend/dist
-   ```
-
-4. Configure production domain to `linearvoid.tv`.
-
-### 5. Tiered Cache
-
-1. Enable Smart Tiered Cache in Cloudflare dashboard.
-2. Warm a segment and manifest path.
-3. Confirm tiered behavior through repeated requests and `Cf-Cache-Status: HIT`.
-
-### 6. WAF and Bot Protection
-
-1. Enable OWASP Managed Ruleset.
-2. Start in `Simulate` mode.
-3. Review events for 48 hours.
-4. Switch to `Block` once false positives are addressed.
-5. Enable Bot Fight Mode.
-
-### 7. Rate Limiting
-
-Create rules:
-
-1. Path: `/api/admin/login`
-2. Path: `/api/admin/*`
-3. Threshold: `10 requests / 10 seconds / IP`
-4. Action: `Managed Challenge`
-
-### 8. HTTPS and WSS
-
-1. Enable `Always Use HTTPS`.
-2. Enable HSTS with:
-   - `max-age=31536000`
-   - `includeSubDomains`
-   - `preload`
-3. Minimum TLS version: `1.2`.
-4. Keep SSL mode at `Full (strict)` when origin certs are valid.
-5. Enforce HTTPS redirect at both layers:
-   - Cloudflare edge
-   - nginx origin
-6. Validate websocket endpoint uses `wss://linearvoid.tv/ws`.
-
-### 9. UptimeRobot Monitors
-
-Create external monitors:
-
-1. HTTP monitor:
-   - URL: `https://linearvoid.tv/health`
-   - Interval: 5 minutes
-2. Keyword monitor:
-   - URL: `https://linearvoid.tv/hls/playlist.m3u8`
-   - Keyword: `#EXTM3U`
-   - Interval: 5 minutes
-3. Alert policy:
-   - Trigger on 2 consecutive failures
-   - Notify via email and Discord/Slack webhook
-
-### 10. Verification Checklist
-
-1. DNS resolves for `linearvoid.tv`, `www.linearvoid.tv`, and `media.linearvoid.tv`.
-2. Pages serves frontend for apex and `www` redirects correctly.
-3. HLS segments are cacheable long-term, manifests refresh every ~2s.
-4. Admin paths are rate-limited and WAF events are visible.
-5. HTTPS and WSS both succeed with valid certificates.
-6. UptimeRobot alerts fire as expected when endpoints are intentionally made unavailable.
-
-## Running the Application
-
-### Local Development
-
-1. **Start All Services**:
-
-   ```bash
-   docker compose up --build
-   ```
-
-2. **Access the Application**:
-   - Preferred local access with the documented proxy setup: <https://linearvoid.tv>
-   - Admin Interface: <https://linearvoid.tv/admin> (redirects to `/admin/login/` until authenticated)
-   - Chat WebSocket: `wss://linearvoid.tv/ws`
-   - Direct-local fallback when bypassing Cloudflare/Nginx Proxy Manager: <http://localhost>, <http://localhost/admin>, and `ws://localhost/ws`
-   - Health Checks:
-     - Playout: <http://localhost:8081/health>
-     - Chat: <http://localhost:3000/health>
-   - Monitoring:
-     - Prometheus: <http://localhost:9090>
-     - Grafana: <http://localhost:3001> (default login: admin/admin)
-
-3. **Frontend Development** (optional, for UI changes):
-
-   ```bash
-   cd frontend
-   npm install
-   npm run dev
-   ```
-
-   The dev server runs on <http://localhost:5173>. It proxies API calls to the backend services.
-
-4. **Build frontend assets for nginx-backed local runs**:
-
-   ```bash
-   cd frontend
-   npm install
-   npm run build
-   ```
-
-   The local nginx container serves `frontend/dist`, so rebuilding the frontend is required before validating production-like static output.
-
-5. **Stop Services**:
-
-   ```bash
-   docker compose down
-   ```
-
-### Local Test Environment Deployment (Remote Docker Host)
-
-For testing deployments on a local network server without setting up a full production VPS, you can deploy directly to a remote Docker host (e.g., a home lab server or test machine) using Docker's TCP socket.
-
-#### Test Environment Prerequisites
-
-- A remote server running Docker at IP `192.168.88.40` (running Alpine Linux).
-- Docker TCP socket enabled and listening on port `2375` on the remote server.
-
-##### Enabling Docker TCP Socket on Alpine Linux
-
-To allow the Gitea Actions runner (or your local machine) to deploy to the remote Alpine host, you must configure the Docker daemon to listen on the TCP socket:
-
-1. Edit `/etc/conf.d/docker` on the Alpine host:
-
-   ```bash
-   vi /etc/conf.d/docker
-   ```
-
-2. Update the `DOCKER_OPTS` line to include both the unix socket and the TCP socket:
-
-   ```bash
-   DOCKER_OPTS="-H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375"
-   ```
-
-3. Restart the Docker service:
-
-   ```bash
-   rc-service docker restart
-   ```
-
-4. Verify that Docker is listening on port `2375`:
-
-   ```bash
-   netstat -tlnp | grep 2375
-   ```
-
-5. Ensure any firewall (like `awall` or `iptables`) on the Alpine host allows incoming traffic on port `2375` from your local network subnet (e.g., `192.168.88.0/24`).
-
-#### Deployment Steps
-
-1. **Configure Docker CLI to use the Remote Host**:
-   You can point your local Docker CLI to the remote server by setting the `DOCKER_HOST` environment variable:
-   - **PowerShell (Windows)**:
-
-     ```powershell
-     $env:DOCKER_HOST="tcp://192.168.88.40:2375"
-     ```
-
-   - **Bash (Linux/macOS)**:
-
-     ```bash
-     export DOCKER_HOST="tcp://192.168.88.40:2375"
-     ```
-
-2. **Verify Connection**:
-   Run `docker info` to confirm your local CLI is communicating with the remote server at `192.168.88.40`:
-
-   ```bash
-   docker info
-   ```
-
-   The output should show the remote server's hostname and system details.
-
-3. **Deploy the Stack**:
-   With `DOCKER_HOST` set, any `docker` or `docker compose` commands you run locally will execute directly on the remote server.
-   - **Deploy from Registry (Production-like)**:
-
-     ```bash
-     docker compose -f docker-compose.prod.yml pull
-     docker compose -f docker-compose.prod.yml up -d --remove-orphans
-     ```
-
-   - **Build and Deploy from Source**:
-
-     ```bash
-     docker compose up -d --build
-     ```
-
-4. **Access the Test Environment**:
-   - Playout Health: `http://192.168.88.40:8081/health`
-   - Chat Health: `http://192.168.88.40:3000/health`
-   - Nginx Entrypoint: `http://192.168.88.40:8080` (or the port mapped to `NGINX_PORT` in `.env`)
-
-5. **Reset to Local Docker Host**:
-   Once testing is complete, clear the `DOCKER_HOST` variable to point back to your local machine:
-   - **PowerShell**:
-
-     ```powershell
-     Remove-Item env:DOCKER_HOST
-     ```
-
-   - **Bash**:
-
-     ```bash
-     unset DOCKER_HOST
-     ```
-
-### Production Setup Guide
-
-1. **Prepare the target host**:
-   - Provision a Linux VPS with Docker Engine, Docker Compose, Git, and enough disk for media, HLS output, PostgreSQL, Redis persistence, and monitoring data.
-   - Open the ports required for HTTP/HTTPS and any restricted monitoring access you intend to expose.
-
-2. **Clone the repository and create the environment file**:
-
-   ```bash
-   git clone https://git.allucanget.biz/zwitschi/linearvoid.git
-   cd linearvoid
-   cp .env.example .env
-   ```
-
-3. **Set production-safe `.env` values**:
-   - Replace placeholder secrets.
-   - Use compose-network hostnames for internal services, for example `redis` and `db`.
-   - Set strong values for `POSTGRES_PASSWORD` and `GRAFANA_PASSWORD`.
-   - Keep `MEDIA_DOMAIN`, R2 credentials, and Gitea registry values consistent with the external infrastructure.
-   - Set `MEDIA_DOMAIN=media.linearvoid.tv`.
-   - Set `VITE_PUBLIC_APP_URL=https://linearvoid.tv`, `VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws`, and `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`.
-   - If you intentionally bypass the public proxy for local-only testing, switch those values to `http://localhost`, `ws://localhost/ws`, and `http://localhost/hls/playlist.m3u8`.
-
-4. **Create runtime directories on the server**:
-
-   ```bash
-   mkdir -p data/playlist data/media data/hls data/chat
-   ```
-
-5. **Publish or verify required images in Gitea**:
-   - Ensure the `playout`, `chat`, and `nginx` images exist under `${CI_REGISTRY_URL}/${CI_REGISTRY_NAMESPACE}`.
-   - Log in to the registry from the VPS before pulling.
-
-6. **Deploy the production stack**:
-
-   ```bash
-   docker compose -f docker-compose.prod.yml pull
-   docker compose -f docker-compose.prod.yml up -d
-   ```
-
-7. **Run post-deploy verification**:
-   - Check `docker compose -f docker-compose.prod.yml ps`.
-   - Confirm nginx, chat, and playout health endpoints respond.
-   - Verify that HLS output is being written to `data/hls` and that the media domain serves manifests and segments through Cloudflare.
-
-8. **Harden and operate the deployment**:
-   - Put HTTPS in front of nginx using Cloudflare or another reverse proxy, with `linearvoid.tv` as canonical app host and `www.linearvoid.tv` redirected.
-   - Restrict Grafana and Prometheus exposure to trusted IPs or a private network.
-   - Run the stack under systemd or another service manager if you need auto-start behavior outside Docker restart policies.
-
-### Production Deployment (Hetzner VPS + Cloudflare)
-
-1. **Provision VPS**: Use Hetzner Cloud CX22 in Ashburn, VA (per ADR-001).
-2. **Configure Cloudflare**:
-   - Create R2 bucket with `enam` location hint.
-   - Set up custom media domain (`media.linearvoid.tv`) with the cache rules from `infrastructure/cloudflare/cache-rules.md`.
-   - Point `linearvoid.tv` and `www.linearvoid.tv` at the app entrypoint, then redirect `www` to the apex domain.
-   - Use Full (strict) TLS for both app and media hostnames.
-   - Apply the Worker from `infrastructure/cloudflare/worker.js` for advanced header management.
-3. **Deploy**:
-   - Copy the project to the VPS.
-   - Use production compose: `docker compose -f docker-compose.prod.yml up -d`
-   - Or pull from Gitea registry: `docker compose -f docker-compose.prod.yml pull && docker compose -f docker-compose.prod.yml up -d`
-   - Configure systemd to manage the Docker Compose stack.
-4. **Monitoring**: Access Grafana at the exposed port for dashboards (included in `monitoring/grafana/dashboard.json`).
-
-See `docs/architecture/README.md` for the full arc42 documentation and the ADRs for architectural decisions.
-
-## Troubleshooting
-
-- **R2 Upload Fails**: Check credentials in `.env` and ensure the bucket exists. Verify with `aws s3 ls --endpoint-url=$R2_ENDPOINT`.
-- **Normalization Errors**: Run `backend/playout/start-playout.sh` manually to see ffprobe output. All videos must be H.264/AAC, 30 fps constant, 2s keyframes (ADR-001).
-- **Chat Not Connecting**: Check Redis connection and WebSocket URL. The health check at `/health` should return 200.
-- **Cache Not Working**: Verify Cloudflare cache rules (`.m4s` = long TTL immutable, `.m3u8` = short TTL). Check cache hit ratio in Cloudflare dashboard.
-- **Docker Issues**: Run `docker compose logs` for service-specific errors. Ensure ports are not in use.
-- **Admin Interface**: Ensure `ADMIN_USERNAME`, `ADMIN_PASSWORD`, and `ADMIN_SESSION_TTL_HOURS` are set. `/admin/` and `/api/admin/*` are protected by a session-based login flow.
-- **Production Pull Fails**: Confirm `docker login` to Gitea succeeded on the server and the image tags referenced by `docker-compose.prod.yml` exist.
-
-## Further Reading
-
-- Architecture: `docs/architecture/README.md` (arc42 template with diagrams).
-- Decisions: `docs/architecture/adr/` (ADR-001 to ADR-007).
-- Contributing: `CONTRIBUTING.md`.
-- Project Structure: Root `README.md`.
-
-The system is ready for use. For production, review ADR-001 for cost estimates and scaling guidance.
-
-**Last Updated**: 2026-08-03

backend/chat/Dockerfile

@@ -1,17 +1,17 @@
-FROM golang:1.25-alpine AS builder
+FROM golang:1.25-alpine AS builder
-
+
-RUN apk add --no-cache gcc musl-dev
+RUN apk add --no-cache gcc musl-dev
-
+
-WORKDIR /app
+WORKDIR /app
-COPY go.mod ./
+COPY go.mod ./
-COPY src/ ./src/
+COPY src/ ./src/
-RUN go mod tidy
+RUN go mod tidy
-RUN CGO_ENABLED=1 GOOS=linux go build -o /chat-server ./src/main.go
+RUN CGO_ENABLED=1 GOOS=linux go build -o /chat-server ./src/main.go
-
+
-FROM alpine:3.20
+FROM alpine:3.20
-RUN apk --no-cache add ca-certificates curl ffmpeg
+RUN apk --no-cache add ca-certificates curl ffmpeg
-WORKDIR /app
+WORKDIR /app
-COPY --from=builder /chat-server /usr/local/bin/chat-server
+COPY --from=builder /chat-server /usr/local/bin/chat-server
-
+
-EXPOSE 3000
+EXPOSE 3000
 CMD ["/usr/local/bin/chat-server"]

backend/chat/go.mod

@@ -6,6 +6,7 @@ require (
 	github.com/glebarez/sqlite v1.11.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/redis/go-redis/v9 v9.7.0
+	golang.org/x/crypto v0.37.0
 	gorm.io/driver/postgres v1.5.11
 	gorm.io/gorm v1.25.12
 )
@@ -24,7 +25,6 @@ require (
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/mattn/go-isatty v0.0.17 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
-	golang.org/x/crypto v0.37.0 // indirect
 	golang.org/x/sync v0.13.0 // indirect
 	golang.org/x/sys v0.32.0 // indirect
 	golang.org/x/text v0.24.0 // indirect

backend/chat/src/auth/auth.go

@@ -1,140 +1,207 @@
-package auth
+package auth
-
+
-import (
+import (
-	"crypto/rand"
+	"crypto/rand"
-	"encoding/hex"
+	"encoding/hex"
-	"net/http"
+	"net/http"
-	"strings"
+	"strings"
-	"sync"
+	"sync"
-	"time"
+	"time"
-)
+)
-
+
-// SessionStore manages admin authentication sessions.
+// SessionStore manages admin authentication sessions.
-type SessionStore struct {
+type SessionStore struct {
-	mu       sync.Mutex
+	mu       sync.Mutex
-	sessions map[string]time.Time
+	sessions map[string]time.Time
-}
+}
-
+
-// NewSessionStore creates a new session store.
+// NewSessionStore creates a new session store.
-func NewSessionStore() *SessionStore {
+func NewSessionStore() *SessionStore {
-	return &SessionStore{
+	return &SessionStore{
-		sessions: make(map[string]time.Time),
+		sessions: make(map[string]time.Time),
-	}
+	}
-}
+}
-
+
-// GenerateToken creates a cryptographically random 64-char hex session token.
+// GenerateToken creates a cryptographically random 64-char hex session token.
-func GenerateToken() (string, error) {
+func GenerateToken() (string, error) {
-	buf := make([]byte, 32)
+	buf := make([]byte, 32)
-	if _, err := rand.Read(buf); err != nil {
+	if _, err := rand.Read(buf); err != nil {
-		return "", err
+		return "", err
-	}
+	}
-	return hex.EncodeToString(buf), nil
+	return hex.EncodeToString(buf), nil
-}
+}
-
+
-// Validate checks if a session token is valid and not expired.
+// Validate checks if a session token is valid and not expired.
-// Returns true if valid, false otherwise. Expired sessions are cleaned up.
+// Returns true if valid, false otherwise. Expired sessions are cleaned up.
-func (s *SessionStore) Validate(token string) bool {
+func (s *SessionStore) Validate(token string) bool {
-	if token == "" {
+	if token == "" {
-		return false
+		return false
-	}
+	}
-
+
-	s.mu.Lock()
+	s.mu.Lock()
-	defer s.mu.Unlock()
+	defer s.mu.Unlock()
-
+
-	expiresAt, ok := s.sessions[token]
+	expiresAt, ok := s.sessions[token]
-	if !ok {
+	if !ok {
-		return false
+		return false
-	}
+	}
-	if time.Now().After(expiresAt) {
+	if time.Now().After(expiresAt) {
-		delete(s.sessions, token)
+		delete(s.sessions, token)
-		return false
+		return false
-	}
+	}
-	return true
+	return true
-}
+}
-
+
-// Add stores a session token with expiry.
+// Add stores a session token with expiry.
-func (s *SessionStore) Add(token string, expiresAt time.Time) {
+func (s *SessionStore) Add(token string, expiresAt time.Time) {
-	s.mu.Lock()
+	s.mu.Lock()
-	defer s.mu.Unlock()
+	defer s.mu.Unlock()
-	s.sessions[token] = expiresAt
+	s.sessions[token] = expiresAt
-}
+}
-
+
-// Remove deletes a session token.
+// Remove deletes a session token.
-func (s *SessionStore) Remove(token string) {
+func (s *SessionStore) Remove(token string) {
-	s.mu.Lock()
+	s.mu.Lock()
-	defer s.mu.Unlock()
+	defer s.mu.Unlock()
-	delete(s.sessions, token)
+	delete(s.sessions, token)
-}
+}
-
+
-// CountActive returns the number of unexpired sessions.
+// CountActive returns the number of unexpired sessions.
-func (s *SessionStore) CountActive() int {
+func (s *SessionStore) CountActive() int {
-	now := time.Now()
+	now := time.Now()
-	s.mu.Lock()
+	s.mu.Lock()
-	defer s.mu.Unlock()
+	defer s.mu.Unlock()
-
+
-	for token, expiresAt := range s.sessions {
+	for token, expiresAt := range s.sessions {
-		if now.After(expiresAt) {
+		if now.After(expiresAt) {
-			delete(s.sessions, token)
+			delete(s.sessions, token)
-		}
+		}
-	}
+	}
-	return len(s.sessions)
+	return len(s.sessions)
-}
+}
-
+
-// CookieSecure determines if the session cookie should have Secure flag.
+// CookieSecure determines if the session cookie should have Secure flag.
-func CookieSecure(r *http.Request) bool {
+func CookieSecure(r *http.Request) bool {
-	if forwardedProto := strings.TrimSpace(r.Header.Get("X-Forwarded-Proto")); forwardedProto != "" {
+	if forwardedProto := strings.TrimSpace(r.Header.Get("X-Forwarded-Proto")); forwardedProto != "" {
-		return strings.EqualFold(forwardedProto, "https")
+		return strings.EqualFold(forwardedProto, "https")
-	}
+	}
-	return r.TLS != nil
+	return r.TLS != nil
-}
+}
-
+
-// SetCookie writes the admin session cookie.
+// SameSiteForUserCookie returns the SameSite policy for the viewer session cookie.
-func SetCookie(w http.ResponseWriter, r *http.Request, cookieName, token string, expiresAt time.Time) {
+// Over HTTPS it returns SameSite=None so the cookie is sent cross-site from the
-	http.SetCookie(w, &http.Cookie{
+// Workers-served SPA; over plain HTTP (local dev) it falls back to Lax.
-		Name:     cookieName,
+func SameSiteForUserCookie(r *http.Request) http.SameSite {
-		Value:    token,
+	if CookieSecure(r) {
-		Path:     "/",
+		return http.SameSiteNoneMode
-		HttpOnly: true,
+	}
-		SameSite: http.SameSiteStrictMode,
+	return http.SameSiteLaxMode
-		Secure:   CookieSecure(r),
+}
-		Expires:  expiresAt,
+
-		MaxAge:   int(time.Until(expiresAt).Seconds()),
+// SetCookie writes a session cookie with the given SameSite policy.
-	})
+// SameSite=None is only valid together with Secure, which is enforced here.
-}
+func SetCookie(w http.ResponseWriter, r *http.Request, cookieName, token string, expiresAt time.Time, sameSite http.SameSite) {
-
+	secure := CookieSecure(r)
-// ClearCookie removes the admin session cookie.
+	if sameSite == http.SameSiteNoneMode {
-func ClearCookie(w http.ResponseWriter, r *http.Request, cookieName string) {
+		secure = true
-	http.SetCookie(w, &http.Cookie{
+	}
-		Name:     cookieName,
+	http.SetCookie(w, &http.Cookie{
-		Value:    "",
+		Name:     cookieName,
-		Path:     "/",
+		Value:    token,
-		HttpOnly: true,
+		Path:     "/",
-		SameSite: http.SameSiteStrictMode,
+		HttpOnly: true,
-		Secure:   CookieSecure(r),
+		SameSite: sameSite,
-		Expires:  time.Unix(0, 0),
+		Secure:   secure,
-		MaxAge:   -1,
+		Expires:  expiresAt,
-	})
+		MaxAge:   int(time.Until(expiresAt).Seconds()),
-}
+	})
-
+}
-// GetTokenFromCookie extracts the session token from the request cookie.
+
-func GetTokenFromCookie(r *http.Request, cookieName string) (string, bool) {
+// ClearCookie removes a session cookie with the given SameSite policy.
-	cookie, err := r.Cookie(cookieName)
+func ClearCookie(w http.ResponseWriter, r *http.Request, cookieName string, sameSite http.SameSite) {
-	if err != nil || cookie.Value == "" {
+	secure := CookieSecure(r)
-		return "", false
+	if sameSite == http.SameSiteNoneMode {
-	}
+		secure = true
-	return cookie.Value, true
+	}
-}
+	http.SetCookie(w, &http.Cookie{
-
+		Name:     cookieName,
-// RequireAdmin returns middleware that checks for a valid admin session.
+		Value:    "",
-func RequireAdmin(store *SessionStore, cookieName string) func(http.HandlerFunc) http.HandlerFunc {
+		Path:     "/",
-	return func(next http.HandlerFunc) http.HandlerFunc {
+		HttpOnly: true,
-		return func(w http.ResponseWriter, r *http.Request) {
+		SameSite: sameSite,
-			token, ok := GetTokenFromCookie(r, cookieName)
+		Secure:   secure,
-			if !ok || !store.Validate(token) {
+		Expires:  time.Unix(0, 0),
-				http.Error(w, "unauthorized", http.StatusUnauthorized)
+		MaxAge:   -1,
-				return
+	})
-			}
+}
-			next(w, r)
+
-		}
+// GetTokenFromCookie extracts the session token from the request cookie.
-	}
+func GetTokenFromCookie(r *http.Request, cookieName string) (string, bool) {
+	cookie, err := r.Cookie(cookieName)
+	if err != nil || cookie.Value == "" {
+		return "", false
+	}
+	return cookie.Value, true
+}
+
+// RequireAdmin returns middleware that checks for a valid admin session.
+func RequireAdmin(store *SessionStore, cookieName string) func(http.HandlerFunc) http.HandlerFunc {
+	return func(next http.HandlerFunc) http.HandlerFunc {
+		return func(w http.ResponseWriter, r *http.Request) {
+			token, ok := GetTokenFromCookie(r, cookieName)
+			if !ok || !store.Validate(token) {
+				http.Error(w, "unauthorized", http.StatusUnauthorized)
+				return
+			}
+			next(w, r)
+		}
+	}
+}
+
+// UserSessionStore maps user session tokens to usernames with expiry.
+type UserSessionStore struct {
+	mu       sync.Mutex
+	sessions map[string]userSession
+}
+
+type userSession struct {
+	Username  string
+	ExpiresAt time.Time
+}
+
+// NewUserSessionStore creates a new user session store.
+func NewUserSessionStore() *UserSessionStore {
+	return &UserSessionStore{sessions: make(map[string]userSession)}
+}
+
+// Add stores a user session token with username and expiry.
+func (s *UserSessionStore) Add(token, username string, expiresAt time.Time) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.sessions[token] = userSession{Username: username, ExpiresAt: expiresAt}
+}
+
+// Username returns the username for a valid, unexpired token.
+func (s *UserSessionStore) Username(token string) (string, bool) {
+	if token == "" {
+		return "", false
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	sess, ok := s.sessions[token]
+	if !ok {
+		return "", false
+	}
+	if time.Now().After(sess.ExpiresAt) {
+		delete(s.sessions, token)
+		return "", false
+	}
+	return sess.Username, true
+}
+
+// Remove deletes a user session token.
+func (s *UserSessionStore) Remove(token string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.sessions, token)
 }

backend/chat/src/auth/auth_test.go

@@ -1,248 +1,309 @@
-package auth
+package auth
-
+
-import (
+import (
-	"crypto/tls"
+	"crypto/tls"
-	"net/http"
+	"net/http"
-	"net/http/httptest"
+	"net/http/httptest"
-	"testing"
+	"testing"
-	"time"
+	"time"
-)
+)
-
+
-func TestGenerateToken(t *testing.T) {
+func TestGenerateToken(t *testing.T) {
-	token, err := GenerateToken()
+	token, err := GenerateToken()
-	if err != nil {
+	if err != nil {
-		t.Fatalf("GenerateToken() error = %v", err)
+		t.Fatalf("GenerateToken() error = %v", err)
-	}
+	}
-	if len(token) != 64 {
+	if len(token) != 64 {
-		t.Errorf("GenerateToken() length = %d, want 64", len(token))
+		t.Errorf("GenerateToken() length = %d, want 64", len(token))
-	}
+	}
-
+
-	// Uniqueness check
+	// Uniqueness check
-	tokens := make(map[string]bool)
+	tokens := make(map[string]bool)
-	for i := 0; i < 1000; i++ {
+	for i := 0; i < 1000; i++ {
-		tok, err := GenerateToken()
+		tok, err := GenerateToken()
-		if err != nil {
+		if err != nil {
-			t.Fatalf("GenerateToken() iteration %d error = %v", i, err)
+			t.Fatalf("GenerateToken() iteration %d error = %v", i, err)
-		}
+		}
-		if tokens[tok] {
+		if tokens[tok] {
-			t.Errorf("GenerateToken() produced duplicate token at iteration %d", i)
+			t.Errorf("GenerateToken() produced duplicate token at iteration %d", i)
-		}
+		}
-		tokens[tok] = true
+		tokens[tok] = true
-	}
+	}
-}
+}
-
+
-func TestSessionStore_Validate(t *testing.T) {
+func TestSessionStore_Validate(t *testing.T) {
-	store := NewSessionStore()
+	store := NewSessionStore()
-
+
-	// Empty token
+	// Empty token
-	if store.Validate("") {
+	if store.Validate("") {
-		t.Error("Validate(\"\") = true, want false")
+		t.Error("Validate(\"\") = true, want false")
-	}
+	}
-
+
-	// Missing token
+	// Missing token
-	if store.Validate("nonexistent") {
+	if store.Validate("nonexistent") {
-		t.Error("Validate(\"nonexistent\") = true, want false")
+		t.Error("Validate(\"nonexistent\") = true, want false")
-	}
+	}
-
+
-	// Valid token
+	// Valid token
-	token, _ := GenerateToken()
+	token, _ := GenerateToken()
-	store.Add(token, time.Now().Add(1*time.Hour))
+	store.Add(token, time.Now().Add(1*time.Hour))
-	if !store.Validate(token) {
+	if !store.Validate(token) {
-		t.Error("Validate(valid) = false, want true")
+		t.Error("Validate(valid) = false, want true")
-	}
+	}
-
+
-	// Expired token
+	// Expired token
-	expiredToken, _ := GenerateToken()
+	expiredToken, _ := GenerateToken()
-	store.Add(expiredToken, time.Now().Add(-1*time.Hour))
+	store.Add(expiredToken, time.Now().Add(-1*time.Hour))
-	if store.Validate(expiredToken) {
+	if store.Validate(expiredToken) {
-		t.Error("Validate(expired) = true, want false")
+		t.Error("Validate(expired) = true, want false")
-	}
+	}
-
+
-	// Expired token should be cleaned up
+	// Expired token should be cleaned up
-	if store.Validate(expiredToken) {
+	if store.Validate(expiredToken) {
-		t.Error("Validate(expired) second call = true, want false (should be cleaned)")
+		t.Error("Validate(expired) second call = true, want false (should be cleaned)")
-	}
+	}
-}
+}
-
+
-func TestSessionStore_AddRemove(t *testing.T) {
+func TestSessionStore_AddRemove(t *testing.T) {
-	store := NewSessionStore()
+	store := NewSessionStore()
-	token, _ := GenerateToken()
+	token, _ := GenerateToken()
-
+
-	store.Add(token, time.Now().Add(1*time.Hour))
+	store.Add(token, time.Now().Add(1*time.Hour))
-	if !store.Validate(token) {
+	if !store.Validate(token) {
-		t.Error("Validate after Add = false, want true")
+		t.Error("Validate after Add = false, want true")
-	}
+	}
-
+
-	store.Remove(token)
+	store.Remove(token)
-	if store.Validate(token) {
+	if store.Validate(token) {
-		t.Error("Validate after Remove = true, want false")
+		t.Error("Validate after Remove = true, want false")
-	}
+	}
-}
+}
-
+
-func TestSessionStore_CountActive(t *testing.T) {
+func TestSessionStore_CountActive(t *testing.T) {
-	store := NewSessionStore()
+	store := NewSessionStore()
-
+
-	if count := store.CountActive(); count != 0 {
+	if count := store.CountActive(); count != 0 {
-		t.Errorf("CountActive() = %d, want 0", count)
+		t.Errorf("CountActive() = %d, want 0", count)
-	}
+	}
-
+
-	t1, _ := GenerateToken()
+	t1, _ := GenerateToken()
-	t2, _ := GenerateToken()
+	t2, _ := GenerateToken()
-	t3, _ := GenerateToken()
+	t3, _ := GenerateToken()
-
+
-	store.Add(t1, time.Now().Add(1*time.Hour))
+	store.Add(t1, time.Now().Add(1*time.Hour))
-	store.Add(t2, time.Now().Add(1*time.Hour))
+	store.Add(t2, time.Now().Add(1*time.Hour))
-	store.Add(t3, time.Now().Add(-1*time.Hour)) // expired
+	store.Add(t3, time.Now().Add(-1*time.Hour)) // expired
-
+
-	if count := store.CountActive(); count != 2 {
+	if count := store.CountActive(); count != 2 {
-		t.Errorf("CountActive() = %d, want 2 (expired should be cleaned)", count)
+		t.Errorf("CountActive() = %d, want 2 (expired should be cleaned)", count)
-	}
+	}
-}
+}
-
+
-func TestCookieSecure(t *testing.T) {
+func TestCookieSecure(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name           string
+		name           string
-		forwardedProto string
+		forwardedProto string
-		tls            bool
+		tls            bool
-		expected       bool
+		expected       bool
-	}{
+	}{
-		{"https forwarded", "https", false, true},
+		{"https forwarded", "https", false, true},
-		{"http forwarded", "http", false, false},
+		{"http forwarded", "http", false, false},
-		{"empty forwarded, no TLS", "", false, false},
+		{"empty forwarded, no TLS", "", false, false},
-		{"empty forwarded, TLS", "", true, true},
+		{"empty forwarded, TLS", "", true, true},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			req := httptest.NewRequest("GET", "/", nil)
+			req := httptest.NewRequest("GET", "/", nil)
-			if tt.forwardedProto != "" {
+			if tt.forwardedProto != "" {
-				req.Header.Set("X-Forwarded-Proto", tt.forwardedProto)
+				req.Header.Set("X-Forwarded-Proto", tt.forwardedProto)
-			}
+			}
-			if tt.tls {
+			if tt.tls {
-				req.TLS = &tls.ConnectionState{}
+				req.TLS = &tls.ConnectionState{}
-			}
+			}
-			if got := CookieSecure(req); got != tt.expected {
+			if got := CookieSecure(req); got != tt.expected {
-				t.Errorf("CookieSecure() = %v, want %v", got, tt.expected)
+				t.Errorf("CookieSecure() = %v, want %v", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestSetCookie(t *testing.T) {
+func TestSetCookie(t *testing.T) {
-	req := httptest.NewRequest("GET", "/", nil)
+	req := httptest.NewRequest("GET", "/", nil)
-	req.Header.Set("X-Forwarded-Proto", "https")
+	req.Header.Set("X-Forwarded-Proto", "https")
-	w := httptest.NewRecorder()
+	w := httptest.NewRecorder()
-
+
-	expiresAt := time.Now().Add(1 * time.Hour)
+	expiresAt := time.Now().Add(1 * time.Hour)
-	SetCookie(w, req, "test_cookie", "abc123", expiresAt)
+	SetCookie(w, req, "test_cookie", "abc123", expiresAt, http.SameSiteStrictMode)
-
+
-	cookies := w.Result().Cookies()
+	cookies := w.Result().Cookies()
-	if len(cookies) != 1 {
+	if len(cookies) != 1 {
-		t.Fatalf("expected 1 cookie, got %d", len(cookies))
+		t.Fatalf("expected 1 cookie, got %d", len(cookies))
-	}
+	}
-	c := cookies[0]
+	c := cookies[0]
-	if c.Name != "test_cookie" {
+	if c.Name != "test_cookie" {
-		t.Errorf("cookie name = %q, want test_cookie", c.Name)
+		t.Errorf("cookie name = %q, want test_cookie", c.Name)
-	}
+	}
-	if c.Value != "abc123" {
+	if c.Value != "abc123" {
-		t.Errorf("cookie value = %q, want abc123", c.Value)
+		t.Errorf("cookie value = %q, want abc123", c.Value)
-	}
+	}
-	if !c.HttpOnly {
+	if !c.HttpOnly {
-		t.Error("cookie HttpOnly = false, want true")
+		t.Error("cookie HttpOnly = false, want true")
-	}
+	}
-	if c.SameSite != http.SameSiteStrictMode {
+	if c.SameSite != http.SameSiteStrictMode {
-		t.Errorf("cookie SameSite = %v, want Strict", c.SameSite)
+		t.Errorf("cookie SameSite = %v, want Strict", c.SameSite)
-	}
+	}
-	if !c.Secure {
+	if !c.Secure {
-		t.Error("cookie Secure = false, want true (X-Forwarded-Proto: https)")
+		t.Error("cookie Secure = false, want true (X-Forwarded-Proto: https)")
-	}
+	}
-	if c.Path != "/" {
+	if c.Path != "/" {
-		t.Errorf("cookie Path = %q, want /", c.Path)
+		t.Errorf("cookie Path = %q, want /", c.Path)
-	}
+	}
-}
+}
-
+
-func TestClearCookie(t *testing.T) {
+func TestClearCookie(t *testing.T) {
-	req := httptest.NewRequest("GET", "/", nil)
+	req := httptest.NewRequest("GET", "/", nil)
-	w := httptest.NewRecorder()
+	w := httptest.NewRecorder()
-
+
-	ClearCookie(w, req, "test_cookie")
+	ClearCookie(w, req, "test_cookie", http.SameSiteStrictMode)
-
+
-	cookies := w.Result().Cookies()
+	cookies := w.Result().Cookies()
-	if len(cookies) != 1 {
+	if len(cookies) != 1 {
-		t.Fatalf("expected 1 cookie, got %d", len(cookies))
+		t.Fatalf("expected 1 cookie, got %d", len(cookies))
-	}
+	}
-	c := cookies[0]
+	c := cookies[0]
-	if c.Name != "test_cookie" {
+	if c.Name != "test_cookie" {
-		t.Errorf("cookie name = %q, want test_cookie", c.Name)
+		t.Errorf("cookie name = %q, want test_cookie", c.Name)
-	}
+	}
-	if c.Value != "" {
+	if c.Value != "" {
-		t.Errorf("cookie value = %q, want empty", c.Value)
+		t.Errorf("cookie value = %q, want empty", c.Value)
-	}
+	}
-	if c.MaxAge != -1 {
+	if c.MaxAge != -1 {
-		t.Errorf("cookie MaxAge = %d, want -1", c.MaxAge)
+		t.Errorf("cookie MaxAge = %d, want -1", c.MaxAge)
-	}
+	}
-}
+}
-
+
-func TestGetTokenFromCookie(t *testing.T) {
+func TestSameSiteForUserCookie(t *testing.T) {
-	req := httptest.NewRequest("GET", "/", nil)
+	req := httptest.NewRequest("GET", "/", nil)
-	req.AddCookie(&http.Cookie{Name: "session", Value: "token123"})
+	req.Header.Set("X-Forwarded-Proto", "https")
-
+	if got := SameSiteForUserCookie(req); got != http.SameSiteNoneMode {
-	token, ok := GetTokenFromCookie(req, "session")
+		t.Errorf("SameSiteForUserCookie(https) = %v, want None", got)
-	if !ok {
+	}
-		t.Error("GetTokenFromCookie() ok = false, want true")
+
-	}
+	req2 := httptest.NewRequest("GET", "/", nil)
-	if token != "token123" {
+	if got := SameSiteForUserCookie(req2); got != http.SameSiteLaxMode {
-		t.Errorf("GetTokenFromCookie() = %q, want token123", token)
+		t.Errorf("SameSiteForUserCookie(http) = %v, want Lax", got)
-	}
+	}
-
+}
-	// Missing cookie
+
-	_, ok = GetTokenFromCookie(req, "nonexistent")
+func TestSetCookie_NoneForcesSecure(t *testing.T) {
-	if ok {
+	req := httptest.NewRequest("GET", "/", nil)
-		t.Error("GetTokenFromCookie() for missing cookie ok = true, want false")
+	w := httptest.NewRecorder()
-	}
+	expiresAt := time.Now().Add(1 * time.Hour)
-
+	SetCookie(w, req, "test_cookie", "abc123", expiresAt, http.SameSiteNoneMode)
-	// Empty value
+
-	req2 := httptest.NewRequest("GET", "/", nil)
+	cookies := w.Result().Cookies()
-	req2.AddCookie(&http.Cookie{Name: "session", Value: ""})
+	if len(cookies) != 1 {
-	_, ok = GetTokenFromCookie(req2, "session")
+		t.Fatalf("expected 1 cookie, got %d", len(cookies))
-	if ok {
+	}
-		t.Error("GetTokenFromCookie() for empty value ok = true, want false")
+	c := cookies[0]
-	}
+	if c.SameSite != http.SameSiteNoneMode {
-}
+		t.Errorf("cookie SameSite = %v, want None", c.SameSite)
-
+	}
-func TestRequireAdmin(t *testing.T) {
+	if !c.Secure {
-	store := NewSessionStore()
+		t.Error("cookie Secure = false, want true (SameSite=None requires Secure)")
-	token, _ := GenerateToken()
+	}
-	store.Add(token, time.Now().Add(1*time.Hour))
+}
-
+
-	handler := RequireAdmin(store, "session")(func(w http.ResponseWriter, r *http.Request) {
+func TestGetTokenFromCookie(t *testing.T) {
-		w.WriteHeader(http.StatusOK)
+	req := httptest.NewRequest("GET", "/", nil)
-		w.Write([]byte("ok"))
+	req.AddCookie(&http.Cookie{Name: "session", Value: "token123"})
-	})
+
-
+	token, ok := GetTokenFromCookie(req, "session")
-	// Valid session
+	if !ok {
-	req := httptest.NewRequest("GET", "/", nil)
+		t.Error("GetTokenFromCookie() ok = false, want true")
-	req.AddCookie(&http.Cookie{Name: "session", Value: token})
+	}
-	w := httptest.NewRecorder()
+	if token != "token123" {
-	handler(w, req)
+		t.Errorf("GetTokenFromCookie() = %q, want token123", token)
-	if w.Code != http.StatusOK {
+	}
-		t.Errorf("status = %d, want 200", w.Code)
+
-	}
+	// Missing cookie
-
+	_, ok = GetTokenFromCookie(req, "nonexistent")
-	// No cookie
+	if ok {
-	req2 := httptest.NewRequest("GET", "/", nil)
+		t.Error("GetTokenFromCookie() for missing cookie ok = true, want false")
-	w2 := httptest.NewRecorder()
+	}
-	handler(w2, req2)
+
-	if w2.Code != http.StatusUnauthorized {
+	// Empty value
-		t.Errorf("status = %d, want 401", w2.Code)
+	req2 := httptest.NewRequest("GET", "/", nil)
-	}
+	req2.AddCookie(&http.Cookie{Name: "session", Value: ""})
-
+	_, ok = GetTokenFromCookie(req2, "session")
-	// Invalid token
+	if ok {
-	req3 := httptest.NewRequest("GET", "/", nil)
+		t.Error("GetTokenFromCookie() for empty value ok = true, want false")
-	req3.AddCookie(&http.Cookie{Name: "session", Value: "invalid"})
+	}
-	w3 := httptest.NewRecorder()
+}
-	handler(w3, req3)
+
-	if w3.Code != http.StatusUnauthorized {
+func TestRequireAdmin(t *testing.T) {
-		t.Errorf("status = %d, want 401", w3.Code)
+	store := NewSessionStore()
-	}
+	token, _ := GenerateToken()
+	store.Add(token, time.Now().Add(1*time.Hour))
+
+	handler := RequireAdmin(store, "session")(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("ok"))
+	})
+
+	// Valid session
+	req := httptest.NewRequest("GET", "/", nil)
+	req.AddCookie(&http.Cookie{Name: "session", Value: token})
+	w := httptest.NewRecorder()
+	handler(w, req)
+	if w.Code != http.StatusOK {
+		t.Errorf("status = %d, want 200", w.Code)
+	}
+
+	// No cookie
+	req2 := httptest.NewRequest("GET", "/", nil)
+	w2 := httptest.NewRecorder()
+	handler(w2, req2)
+	if w2.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w2.Code)
+	}
+
+	// Invalid token
+	req3 := httptest.NewRequest("GET", "/", nil)
+	req3.AddCookie(&http.Cookie{Name: "session", Value: "invalid"})
+	w3 := httptest.NewRecorder()
+	handler(w3, req3)
+	if w3.Code != http.StatusUnauthorized {
+		t.Errorf("status = %d, want 401", w3.Code)
+	}
+}
+
+func TestUserSessionStore(t *testing.T) {
+	store := NewUserSessionStore()
+
+	if _, ok := store.Username(""); ok {
+		t.Error("Username(\"\") = true, want false")
+	}
+
+	token, _ := GenerateToken()
+	store.Add(token, "alice", time.Now().Add(1*time.Hour))
+
+	username, ok := store.Username(token)
+	if !ok || username != "alice" {
+		t.Errorf("Username() = %q, %v; want alice, true", username, ok)
+	}
+
+	// Expired session
+	expired, _ := GenerateToken()
+	store.Add(expired, "bob", time.Now().Add(-1*time.Hour))
+	if _, ok := store.Username(expired); ok {
+		t.Error("Username(expired) = true, want false")
+	}
+
+	// Remove
+	store.Remove(token)
+	if _, ok := store.Username(token); ok {
+		t.Error("Username after Remove = true, want false")
+	}
 }

backend/chat/src/config/config.go

@@ -1,118 +1,132 @@
-package config
+package config
-
+
-import (
+import (
-	"os"
+	"os"
-	"strconv"
+	"strconv"
-	"strings"
+	"strings"
-	"time"
+	"time"
-)
+)
-
+
-// Defaults and constants
+// Defaults and constants
-const (
+const (
-	AdminSessionCookieName = "linearvoid_admin_session"
+	AdminSessionCookieName = "linearvoid_admin_session"
-	MaxAdminUploadBytes    int64 = 2 * 1024 * 1024 * 1024
+	MaxAdminUploadBytes    int64 = 2 * 1024 * 1024 * 1024
-	DefaultAdminChunkSize  int64 = 8 * 1024 * 1024
+	DefaultAdminChunkSize  int64 = 8 * 1024 * 1024
-	MaxAdminChunkSize      int64 = 32 * 1024 * 1024
+	MaxAdminChunkSize      int64 = 32 * 1024 * 1024
-	DefaultRateLimitMax          = 10
+	DefaultRateLimitMax          = 10
-	DefaultRateLimitWindow       = 10 * time.Second
+	DefaultRateLimitWindow       = 10 * time.Second
-	DefaultAdminSessionTTL       = 12 * time.Hour
+	DefaultAdminSessionTTL       = 12 * time.Hour
-	DefaultChatPort              = "3000"
+	DefaultUserSessionTTL        = 30 * 24 * time.Hour
-)
+	DefaultChatPort              = "3000"
-
+)
-// PlaylistPath returns the playlist file path from env or default.
+
-func PlaylistPath() string {
+// PlaylistPath returns the playlist file path from env or default.
-	p := strings.TrimSpace(os.Getenv("PLAYLIST_PATH"))
+func PlaylistPath() string {
-	if p == "" {
+	p := strings.TrimSpace(os.Getenv("PLAYLIST_PATH"))
-		return "/app/playlist/playlist.txt"
+	if p == "" {
-	}
+		return "/app/playlist/playlist.txt"
-	return p
+	}
-}
+	return p
-
+}
-// MediaDir returns the media directory from env or default.
+
-func MediaDir() string {
+// MediaDir returns the media directory from env or default.
-	d := strings.TrimSpace(os.Getenv("MEDIA_DIR"))
+func MediaDir() string {
-	if d == "" {
+	d := strings.TrimSpace(os.Getenv("MEDIA_DIR"))
-		return "/app/media"
+	if d == "" {
-	}
+		return "/app/media"
-	return d
+	}
-}
+	return d
-
+}
-// AdminUsername returns the admin username from env or default.
+
-func AdminUsername() string {
+// AdminUsername returns the admin username from env or default.
-	u := strings.TrimSpace(os.Getenv("ADMIN_USERNAME"))
+func AdminUsername() string {
-	if u == "" {
+	u := strings.TrimSpace(os.Getenv("ADMIN_USERNAME"))
-		return "admin"
+	if u == "" {
-	}
+		return "admin"
-	return u
+	}
-}
+	return u
-
+}
-// AdminPassword returns the admin password from env or default.
+
-func AdminPassword() string {
+// AdminPassword returns the admin password from env or default.
-	p := strings.TrimSpace(os.Getenv("ADMIN_PASSWORD"))
+func AdminPassword() string {
-	if p == "" {
+	p := strings.TrimSpace(os.Getenv("ADMIN_PASSWORD"))
-		return "admin"
+	if p == "" {
-	}
+		return "admin"
-	return p
+	}
-}
+	return p
-
+}
-// AdminSessionTTL returns the admin session TTL from env or default.
+
-func AdminSessionTTL() time.Duration {
+// AdminSessionTTL returns the admin session TTL from env or default.
-	raw := strings.TrimSpace(os.Getenv("ADMIN_SESSION_TTL_HOURS"))
+func AdminSessionTTL() time.Duration {
-	if raw == "" {
+	raw := strings.TrimSpace(os.Getenv("ADMIN_SESSION_TTL_HOURS"))
-		return DefaultAdminSessionTTL
+	if raw == "" {
-	}
+		return DefaultAdminSessionTTL
-	hours, err := strconv.Atoi(raw)
+	}
-	if err != nil || hours <= 0 {
+	hours, err := strconv.Atoi(raw)
-		return DefaultAdminSessionTTL
+	if err != nil || hours <= 0 {
-	}
+		return DefaultAdminSessionTTL
-	return time.Duration(hours) * time.Hour
+	}
-}
+	return time.Duration(hours) * time.Hour
-
+}
-// RateLimitMax returns the chat rate limit max messages per window.
+
-func RateLimitMax() int {
+// UserSessionTTL returns the user session TTL from env or default (30 days).
-	raw := strings.TrimSpace(os.Getenv("CHAT_RATE_LIMIT_MAX"))
+func UserSessionTTL() time.Duration {
-	if raw == "" {
+	raw := strings.TrimSpace(os.Getenv("USER_SESSION_TTL_HOURS"))
-		return DefaultRateLimitMax
+	if raw == "" {
-	}
+		return DefaultUserSessionTTL
-	v, err := strconv.Atoi(raw)
+	}
-	if err != nil || v <= 0 {
+	hours, err := strconv.Atoi(raw)
-		return DefaultRateLimitMax
+	if err != nil || hours <= 0 {
-	}
+		return DefaultUserSessionTTL
-	return v
+	}
-}
+	return time.Duration(hours) * time.Hour
-
+}
-// RateLimitWindow returns the chat rate limit window duration.
+
-func RateLimitWindow() time.Duration {
+// RateLimitMax returns the chat rate limit max messages per window.
-	raw := strings.TrimSpace(os.Getenv("CHAT_RATE_LIMIT_WINDOW_S"))
+func RateLimitMax() int {
-	if raw == "" {
+	raw := strings.TrimSpace(os.Getenv("CHAT_RATE_LIMIT_MAX"))
-		return DefaultRateLimitWindow
+	if raw == "" {
-	}
+		return DefaultRateLimitMax
-	v, err := strconv.Atoi(raw)
+	}
-	if err != nil || v <= 0 {
+	v, err := strconv.Atoi(raw)
-		return DefaultRateLimitWindow
+	if err != nil || v <= 0 {
-	}
+		return DefaultRateLimitMax
-	return time.Duration(v) * time.Second
+	}
-}
+	return v
-
+}
-// ChatPort returns the chat service port from env or default.
+
-func ChatPort() string {
+// RateLimitWindow returns the chat rate limit window duration.
-	p := strings.TrimSpace(os.Getenv("CHAT_PORT"))
+func RateLimitWindow() time.Duration {
-	if p == "" {
+	raw := strings.TrimSpace(os.Getenv("CHAT_RATE_LIMIT_WINDOW_S"))
-		return DefaultChatPort
+	if raw == "" {
-	}
+		return DefaultRateLimitWindow
-	return p
+	}
-}
+	v, err := strconv.Atoi(raw)
-
+	if err != nil || v <= 0 {
-// RedisAddress returns the Redis address from env or default.
+		return DefaultRateLimitWindow
-func RedisAddress() string {
+	}
-	a := strings.TrimSpace(os.Getenv("REDIS_URL"))
+	return time.Duration(v) * time.Second
-	if a == "" {
+}
-		return "redis:6379"
+
-	}
+// ChatPort returns the chat service port from env or default.
-	return a
+func ChatPort() string {
-}
+	p := strings.TrimSpace(os.Getenv("CHAT_PORT"))
-
+	if p == "" {
-// DatabaseURL returns the database URL from env (empty = SQLite default).
+		return DefaultChatPort
-func DatabaseURL() string {
+	}
-	return strings.TrimSpace(os.Getenv("DATABASE_URL"))
+	return p
+}
+
+// RedisAddress returns the Redis address from env or default.
+func RedisAddress() string {
+	a := strings.TrimSpace(os.Getenv("REDIS_URL"))
+	if a == "" {
+		return "redis:6379"
+	}
+	return a
+}
+
+// DatabaseURL returns the database URL from env (empty = SQLite default).
+func DatabaseURL() string {
+	return strings.TrimSpace(os.Getenv("DATABASE_URL"))
 }

backend/chat/src/config/config_test.go

@@ -1,267 +1,267 @@
-package config
+package config
-
+
-import (
+import (
-	"os"
+	"os"
-	"testing"
+	"testing"
-	"time"
+	"time"
-)
+)
-
+
-func TestPlaylistPath(t *testing.T) {
+func TestPlaylistPath(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", "/app/playlist/playlist.txt"},
+		{"default", "", "/app/playlist/playlist.txt"},
-		{"custom", "/custom/playlist.txt", "/custom/playlist.txt"},
+		{"custom", "/custom/playlist.txt", "/custom/playlist.txt"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("PLAYLIST_PATH", tt.env)
+				os.Setenv("PLAYLIST_PATH", tt.env)
-				defer os.Unsetenv("PLAYLIST_PATH")
+				defer os.Unsetenv("PLAYLIST_PATH")
-			} else {
+			} else {
-				os.Unsetenv("PLAYLIST_PATH")
+				os.Unsetenv("PLAYLIST_PATH")
-			}
+			}
-			if got := PlaylistPath(); got != tt.expected {
+			if got := PlaylistPath(); got != tt.expected {
-				t.Errorf("PlaylistPath() = %q, want %q", got, tt.expected)
+				t.Errorf("PlaylistPath() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestMediaDir(t *testing.T) {
+func TestMediaDir(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", "/app/media"},
+		{"default", "", "/app/media"},
-		{"custom", "/data/media", "/data/media"},
+		{"custom", "/data/media", "/data/media"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("MEDIA_DIR", tt.env)
+				os.Setenv("MEDIA_DIR", tt.env)
-				defer os.Unsetenv("MEDIA_DIR")
+				defer os.Unsetenv("MEDIA_DIR")
-			} else {
+			} else {
-				os.Unsetenv("MEDIA_DIR")
+				os.Unsetenv("MEDIA_DIR")
-			}
+			}
-			if got := MediaDir(); got != tt.expected {
+			if got := MediaDir(); got != tt.expected {
-				t.Errorf("MediaDir() = %q, want %q", got, tt.expected)
+				t.Errorf("MediaDir() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestAdminUsername(t *testing.T) {
+func TestAdminUsername(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", "admin"},
+		{"default", "", "admin"},
-		{"custom", "superadmin", "superadmin"},
+		{"custom", "superadmin", "superadmin"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("ADMIN_USERNAME", tt.env)
+				os.Setenv("ADMIN_USERNAME", tt.env)
-				defer os.Unsetenv("ADMIN_USERNAME")
+				defer os.Unsetenv("ADMIN_USERNAME")
-			} else {
+			} else {
-				os.Unsetenv("ADMIN_USERNAME")
+				os.Unsetenv("ADMIN_USERNAME")
-			}
+			}
-			if got := AdminUsername(); got != tt.expected {
+			if got := AdminUsername(); got != tt.expected {
-				t.Errorf("AdminUsername() = %q, want %q", got, tt.expected)
+				t.Errorf("AdminUsername() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestAdminPassword(t *testing.T) {
+func TestAdminPassword(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", "admin"},
+		{"default", "", "admin"},
-		{"custom", "secret123", "secret123"},
+		{"custom", "secret123", "secret123"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("ADMIN_PASSWORD", tt.env)
+				os.Setenv("ADMIN_PASSWORD", tt.env)
-				defer os.Unsetenv("ADMIN_PASSWORD")
+				defer os.Unsetenv("ADMIN_PASSWORD")
-			} else {
+			} else {
-				os.Unsetenv("ADMIN_PASSWORD")
+				os.Unsetenv("ADMIN_PASSWORD")
-			}
+			}
-			if got := AdminPassword(); got != tt.expected {
+			if got := AdminPassword(); got != tt.expected {
-				t.Errorf("AdminPassword() = %q, want %q", got, tt.expected)
+				t.Errorf("AdminPassword() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestAdminSessionTTL(t *testing.T) {
+func TestAdminSessionTTL(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected time.Duration
+		expected time.Duration
-	}{
+	}{
-		{"default", "", 12 * time.Hour},
+		{"default", "", 12 * time.Hour},
-		{"custom", "24", 24 * time.Hour},
+		{"custom", "24", 24 * time.Hour},
-		{"zero", "0", 12 * time.Hour},
+		{"zero", "0", 12 * time.Hour},
-		{"negative", "-5", 12 * time.Hour},
+		{"negative", "-5", 12 * time.Hour},
-		{"invalid", "abc", 12 * time.Hour},
+		{"invalid", "abc", 12 * time.Hour},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("ADMIN_SESSION_TTL_HOURS", tt.env)
+				os.Setenv("ADMIN_SESSION_TTL_HOURS", tt.env)
-				defer os.Unsetenv("ADMIN_SESSION_TTL_HOURS")
+				defer os.Unsetenv("ADMIN_SESSION_TTL_HOURS")
-			} else {
+			} else {
-				os.Unsetenv("ADMIN_SESSION_TTL_HOURS")
+				os.Unsetenv("ADMIN_SESSION_TTL_HOURS")
-			}
+			}
-			if got := AdminSessionTTL(); got != tt.expected {
+			if got := AdminSessionTTL(); got != tt.expected {
-				t.Errorf("AdminSessionTTL() = %v, want %v", got, tt.expected)
+				t.Errorf("AdminSessionTTL() = %v, want %v", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestRateLimitMax(t *testing.T) {
+func TestRateLimitMax(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected int
+		expected int
-	}{
+	}{
-		{"default", "", 10},
+		{"default", "", 10},
-		{"custom", "20", 20},
+		{"custom", "20", 20},
-		{"zero", "0", 10},
+		{"zero", "0", 10},
-		{"negative", "-5", 10},
+		{"negative", "-5", 10},
-		{"invalid", "abc", 10},
+		{"invalid", "abc", 10},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("CHAT_RATE_LIMIT_MAX", tt.env)
+				os.Setenv("CHAT_RATE_LIMIT_MAX", tt.env)
-				defer os.Unsetenv("CHAT_RATE_LIMIT_MAX")
+				defer os.Unsetenv("CHAT_RATE_LIMIT_MAX")
-			} else {
+			} else {
-				os.Unsetenv("CHAT_RATE_LIMIT_MAX")
+				os.Unsetenv("CHAT_RATE_LIMIT_MAX")
-			}
+			}
-			if got := RateLimitMax(); got != tt.expected {
+			if got := RateLimitMax(); got != tt.expected {
-				t.Errorf("RateLimitMax() = %d, want %d", got, tt.expected)
+				t.Errorf("RateLimitMax() = %d, want %d", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestRateLimitWindow(t *testing.T) {
+func TestRateLimitWindow(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected time.Duration
+		expected time.Duration
-	}{
+	}{
-		{"default", "", 10 * time.Second},
+		{"default", "", 10 * time.Second},
-		{"custom", "30", 30 * time.Second},
+		{"custom", "30", 30 * time.Second},
-		{"zero", "0", 10 * time.Second},
+		{"zero", "0", 10 * time.Second},
-		{"negative", "-5", 10 * time.Second},
+		{"negative", "-5", 10 * time.Second},
-		{"invalid", "abc", 10 * time.Second},
+		{"invalid", "abc", 10 * time.Second},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("CHAT_RATE_LIMIT_WINDOW_S", tt.env)
+				os.Setenv("CHAT_RATE_LIMIT_WINDOW_S", tt.env)
-				defer os.Unsetenv("CHAT_RATE_LIMIT_WINDOW_S")
+				defer os.Unsetenv("CHAT_RATE_LIMIT_WINDOW_S")
-			} else {
+			} else {
-				os.Unsetenv("CHAT_RATE_LIMIT_WINDOW_S")
+				os.Unsetenv("CHAT_RATE_LIMIT_WINDOW_S")
-			}
+			}
-			if got := RateLimitWindow(); got != tt.expected {
+			if got := RateLimitWindow(); got != tt.expected {
-				t.Errorf("RateLimitWindow() = %v, want %v", got, tt.expected)
+				t.Errorf("RateLimitWindow() = %v, want %v", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestChatPort(t *testing.T) {
+func TestChatPort(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", "3000"},
+		{"default", "", "3000"},
-		{"custom", "8080", "8080"},
+		{"custom", "8080", "8080"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("CHAT_PORT", tt.env)
+				os.Setenv("CHAT_PORT", tt.env)
-				defer os.Unsetenv("CHAT_PORT")
+				defer os.Unsetenv("CHAT_PORT")
-			} else {
+			} else {
-				os.Unsetenv("CHAT_PORT")
+				os.Unsetenv("CHAT_PORT")
-			}
+			}
-			if got := ChatPort(); got != tt.expected {
+			if got := ChatPort(); got != tt.expected {
-				t.Errorf("ChatPort() = %q, want %q", got, tt.expected)
+				t.Errorf("ChatPort() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestRedisAddress(t *testing.T) {
+func TestRedisAddress(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", "redis:6379"},
+		{"default", "", "redis:6379"},
-		{"custom", "redis.example.com:6380", "redis.example.com:6380"},
+		{"custom", "redis.example.com:6380", "redis.example.com:6380"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("REDIS_URL", tt.env)
+				os.Setenv("REDIS_URL", tt.env)
-				defer os.Unsetenv("REDIS_URL")
+				defer os.Unsetenv("REDIS_URL")
-			} else {
+			} else {
-				os.Unsetenv("REDIS_URL")
+				os.Unsetenv("REDIS_URL")
-			}
+			}
-			if got := RedisAddress(); got != tt.expected {
+			if got := RedisAddress(); got != tt.expected {
-				t.Errorf("RedisAddress() = %q, want %q", got, tt.expected)
+				t.Errorf("RedisAddress() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
-}
+}
-
+
-func TestDatabaseURL(t *testing.T) {
+func TestDatabaseURL(t *testing.T) {
-	tests := []struct {
+	tests := []struct {
-		name     string
+		name     string
-		env      string
+		env      string
-		expected string
+		expected string
-	}{
+	}{
-		{"default", "", ""},
+		{"default", "", ""},
-		{"sqlite", "sqlite://test.db", "sqlite://test.db"},
+		{"sqlite", "sqlite://test.db", "sqlite://test.db"},
-		{"postgres", "postgres://user:pass@localhost/db", "postgres://user:pass@localhost/db"},
+		{"postgres", "postgres://user:pass@localhost/db", "postgres://user:pass@localhost/db"},
-	}
+	}
-
+
-	for _, tt := range tests {
+	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
+		t.Run(tt.name, func(t *testing.T) {
-			if tt.env != "" {
+			if tt.env != "" {
-				os.Setenv("DATABASE_URL", tt.env)
+				os.Setenv("DATABASE_URL", tt.env)
-				defer os.Unsetenv("DATABASE_URL")
+				defer os.Unsetenv("DATABASE_URL")
-			} else {
+			} else {
-				os.Unsetenv("DATABASE_URL")
+				os.Unsetenv("DATABASE_URL")
-			}
+			}
-			if got := DatabaseURL(); got != tt.expected {
+			if got := DatabaseURL(); got != tt.expected {
-				t.Errorf("DatabaseURL() = %q, want %q", got, tt.expected)
+				t.Errorf("DatabaseURL() = %q, want %q", got, tt.expected)
-			}
+			}
-		})
+		})
-	}
+	}
 }

backend/chat/src/config/runtime.go

@@ -0,0 +1,221 @@
+package config
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+)
+
+// Runtime configuration keys stored in the runtime config file.
+const (
+	keyMatomoURL     = "matomo_url"
+	keyMatomoSiteID  = "matomo_site_id"
+	keyHLSSegmentDur = "hls_segment_duration"
+	keyHLSWindowSize = "hls_window_size"
+)
+
+// Default HLS values used when neither env nor persisted config is set.
+const (
+	defaultHLSSegmentDuration = 2
+	defaultHLSWindowSize      = 12
+)
+
+var (
+	runtimeMu    sync.RWMutex
+	runtimeStore = map[string]string{}
+)
+
+// ConfigPath returns the runtime config JSON file path from env or default.
+// The default lives in the shared playlist volume so the playout service can
+// read the same file (chat has read-write, playout read-only).
+func ConfigPath() string {
+	p := strings.TrimSpace(os.Getenv("CONFIG_PATH"))
+	if p == "" {
+		return "/app/playlist/config.json"
+	}
+	return p
+}
+
+// GetRuntime returns a value from the runtime store and whether it is present.
+func GetRuntime(key string) (string, bool) {
+	runtimeMu.RLock()
+	defer runtimeMu.RUnlock()
+	v, ok := runtimeStore[key]
+	return v, ok
+}
+
+// SetRuntime stores a value in the runtime store (in-memory only).
+func SetRuntime(key, value string) {
+	runtimeMu.Lock()
+	defer runtimeMu.Unlock()
+	runtimeStore[key] = value
+}
+
+// LoadRuntimeConfig loads the persisted runtime config from disk. If the file does
+// not exist, it seeds the store from environment variables.
+func LoadRuntimeConfig() error {
+	data, err := os.ReadFile(ConfigPath())
+	if err != nil {
+		if os.IsNotExist(err) {
+			runtimeMu.Lock()
+			runtimeStore = map[string]string{}
+			runtimeMu.Unlock()
+			seedRuntimeDefaults()
+			return nil
+		}
+		return fmt.Errorf("read runtime config: %w", err)
+	}
+
+	values := map[string]string{}
+	if err := json.Unmarshal(data, &values); err != nil {
+		return fmt.Errorf("parse runtime config: %w", err)
+	}
+
+	runtimeMu.Lock()
+	defer runtimeMu.Unlock()
+	runtimeStore = values
+	return nil
+}
+
+// SaveRuntimeConfig persists the runtime store to disk as JSON.
+func SaveRuntimeConfig() error {
+	runtimeMu.RLock()
+	data, err := json.MarshalIndent(runtimeStore, "", "  ")
+	runtimeMu.RUnlock()
+	if err != nil {
+		return fmt.Errorf("marshal runtime config: %w", err)
+	}
+	if dir := filepath.Dir(ConfigPath()); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			return fmt.Errorf("create runtime config dir: %w", err)
+		}
+	}
+	if err := os.WriteFile(ConfigPath(), append(data, '\n'), 0o644); err != nil {
+		return fmt.Errorf("write runtime config: %w", err)
+	}
+	return nil
+}
+
+// seedRuntimeDefaults populates the store from environment variables.
+func seedRuntimeDefaults() {
+	if v := strings.TrimSpace(os.Getenv("MATOMO_URL")); v != "" {
+		SetRuntime(keyMatomoURL, v)
+	}
+	if v := strings.TrimSpace(os.Getenv("MATOMO_SITE_ID")); v != "" {
+		SetRuntime(keyMatomoSiteID, v)
+	}
+	if v := strings.TrimSpace(os.Getenv("HLS_SEGMENT_DURATION")); v != "" {
+		SetRuntime(keyHLSSegmentDur, v)
+	}
+	if v := strings.TrimSpace(os.Getenv("HLS_WINDOW_SIZE")); v != "" {
+		SetRuntime(keyHLSWindowSize, v)
+	}
+}
+
+// MatomoURL returns the Matomo analytics URL.
+func MatomoURL() string {
+	if v, ok := GetRuntime(keyMatomoURL); ok && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return strings.TrimSpace(os.Getenv("MATOMO_URL"))
+}
+
+// MatomoSiteID returns the Matomo site ID.
+func MatomoSiteID() string {
+	if v, ok := GetRuntime(keyMatomoSiteID); ok && strings.TrimSpace(v) != "" {
+		return strings.TrimSpace(v)
+	}
+	return strings.TrimSpace(os.Getenv("MATOMO_SITE_ID"))
+}
+
+// HLSSegmentDuration returns the HLS segment duration in seconds.
+func HLSSegmentDuration() int {
+	raw := ""
+	if v, ok := GetRuntime(keyHLSSegmentDur); ok {
+		raw = strings.TrimSpace(v)
+	}
+	if raw == "" {
+		raw = strings.TrimSpace(os.Getenv("HLS_SEGMENT_DURATION"))
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n <= 0 {
+		return defaultHLSSegmentDuration
+	}
+	return n
+}
+
+// HLSWindowSize returns the HLS playlist window size in segments.
+func HLSWindowSize() int {
+	raw := ""
+	if v, ok := GetRuntime(keyHLSWindowSize); ok {
+		raw = strings.TrimSpace(v)
+	}
+	if raw == "" {
+		raw = strings.TrimSpace(os.Getenv("HLS_WINDOW_SIZE"))
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n <= 0 {
+		return defaultHLSWindowSize
+	}
+	return n
+}
+
+// SetMatomoURL validates and stores the Matomo URL.
+func SetMatomoURL(raw string) error {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		SetRuntime(keyMatomoURL, "")
+		return nil
+	}
+	u, err := url.Parse(raw)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+		return fmt.Errorf("matomo URL must be an absolute http(s) URL")
+	}
+	SetRuntime(keyMatomoURL, raw)
+	return nil
+}
+
+// SetMatomoSiteID validates and stores the Matomo site ID.
+func SetMatomoSiteID(raw string) error {
+	raw = strings.TrimSpace(raw)
+	if raw != "" {
+		if _, err := strconv.Atoi(raw); err != nil {
+			return fmt.Errorf("matomo site ID must be numeric")
+		}
+	}
+	SetRuntime(keyMatomoSiteID, raw)
+	return nil
+}
+
+// SetHLSSegmentDuration validates (2–15s) and stores the HLS segment duration.
+func SetHLSSegmentDuration(seconds int) error {
+	if seconds < 2 || seconds > 15 {
+		return fmt.Errorf("HLS segment duration must be between 2 and 15 seconds")
+	}
+	SetRuntime(keyHLSSegmentDur, strconv.Itoa(seconds))
+	return nil
+}
+
+// SetHLSWindowSize validates (3–100) and stores the HLS window size.
+func SetHLSWindowSize(size int) error {
+	if size < 3 || size > 100 {
+		return fmt.Errorf("HLS window size must be between 3 and 100 segments")
+	}
+	SetRuntime(keyHLSWindowSize, strconv.Itoa(size))
+	return nil
+}
+
+// RuntimeConfigSnapshot returns the resolved runtime configuration values.
+func RuntimeConfigSnapshot() map[string]any {
+	return map[string]any{
+		"matomoUrl":          MatomoURL(),
+		"matomoSiteId":       MatomoSiteID(),
+		"hlsSegmentDuration": HLSSegmentDuration(),
+		"hlsWindowSize":      HLSWindowSize(),
+	}
+}

backend/chat/src/config/runtime_test.go

@@ -0,0 +1,181 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func resetRuntime(t *testing.T) {
+	t.Helper()
+	runtimeMu.Lock()
+	runtimeStore = map[string]string{}
+	runtimeMu.Unlock()
+	os.Unsetenv("CONFIG_PATH")
+	os.Unsetenv("MATOMO_URL")
+	os.Unsetenv("MATOMO_SITE_ID")
+	os.Unsetenv("HLS_SEGMENT_DURATION")
+	os.Unsetenv("HLS_WINDOW_SIZE")
+}
+
+func TestConfigPath(t *testing.T) {
+	resetRuntime(t)
+	if got := ConfigPath(); got != "/app/playlist/config.json" {
+		t.Errorf("ConfigPath() = %q, want default /app/playlist/config.json", got)
+	}
+
+	os.Setenv("CONFIG_PATH", "/tmp/custom.json")
+	defer os.Unsetenv("CONFIG_PATH")
+	if got := ConfigPath(); got != "/tmp/custom.json" {
+		t.Errorf("ConfigPath() = %q, want /tmp/custom.json", got)
+	}
+}
+
+func TestGetSetRuntime(t *testing.T) {
+	resetRuntime(t)
+	if _, ok := GetRuntime("foo"); ok {
+		t.Errorf("expected missing key")
+	}
+	SetRuntime("foo", "bar")
+	v, ok := GetRuntime("foo")
+	if !ok || v != "bar" {
+		t.Errorf("GetRuntime() = %q, %v; want bar, true", v, ok)
+	}
+}
+
+func TestGettersDefaults(t *testing.T) {
+	resetRuntime(t)
+	if got := MatomoURL(); got != "" {
+		t.Errorf("MatomoURL() = %q, want empty", got)
+	}
+	if got := MatomoSiteID(); got != "" {
+		t.Errorf("MatomoSiteID() = %q, want empty", got)
+	}
+	if got := HLSSegmentDuration(); got != 2 {
+		t.Errorf("HLSSegmentDuration() = %d, want 2", got)
+	}
+	if got := HLSWindowSize(); got != 12 {
+		t.Errorf("HLSWindowSize() = %d, want 12", got)
+	}
+}
+
+func TestGettersEnvFallback(t *testing.T) {
+	resetRuntime(t)
+	os.Setenv("HLS_SEGMENT_DURATION", "4")
+	os.Setenv("HLS_WINDOW_SIZE", "30")
+	os.Setenv("MATOMO_URL", "https://analytics.example.com")
+	os.Setenv("MATOMO_SITE_ID", "7")
+
+	if got := HLSSegmentDuration(); got != 4 {
+		t.Errorf("HLSSegmentDuration() = %d, want 4", got)
+	}
+	if got := HLSWindowSize(); got != 30 {
+		t.Errorf("HLSWindowSize() = %d, want 30", got)
+	}
+	if got := MatomoURL(); got != "https://analytics.example.com" {
+		t.Errorf("MatomoURL() = %q", got)
+	}
+	if got := MatomoSiteID(); got != "7" {
+		t.Errorf("MatomoSiteID() = %q", got)
+	}
+}
+
+func TestLoadRuntimeConfigSeedsFromEnv(t *testing.T) {
+	resetRuntime(t)
+	dir := t.TempDir()
+	os.Setenv("CONFIG_PATH", filepath.Join(dir, "config.json"))
+	os.Setenv("HLS_SEGMENT_DURATION", "8")
+
+	if err := LoadRuntimeConfig(); err != nil {
+		t.Fatalf("LoadRuntimeConfig error: %v", err)
+	}
+	if got := HLSSegmentDuration(); got != 8 {
+		t.Errorf("HLSSegmentDuration() = %d, want 8 (seeded from env)", got)
+	}
+}
+
+func TestSaveAndLoadRuntimeConfig(t *testing.T) {
+	resetRuntime(t)
+	dir := t.TempDir()
+	os.Setenv("CONFIG_PATH", filepath.Join(dir, "config.json"))
+
+	if err := SetHLSSegmentDuration(5); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetHLSWindowSize(30); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetMatomoURL("https://stats.example.com"); err != nil {
+		t.Fatal(err)
+	}
+	if err := SetMatomoSiteID("42"); err != nil {
+		t.Fatal(err)
+	}
+
+	if err := SaveRuntimeConfig(); err != nil {
+		t.Fatalf("SaveRuntimeConfig error: %v", err)
+	}
+
+	// Reset the store and reload from disk.
+	runtimeMu.Lock()
+	runtimeStore = map[string]string{}
+	runtimeMu.Unlock()
+
+	if err := LoadRuntimeConfig(); err != nil {
+		t.Fatalf("LoadRuntimeConfig error: %v", err)
+	}
+
+	if got := HLSSegmentDuration(); got != 5 {
+		t.Errorf("HLSSegmentDuration() = %d, want 5", got)
+	}
+	if got := HLSWindowSize(); got != 30 {
+		t.Errorf("HLSWindowSize() = %d, want 30", got)
+	}
+	if got := MatomoURL(); got != "https://stats.example.com" {
+		t.Errorf("MatomoURL() = %q", got)
+	}
+	if got := MatomoSiteID(); got != "42" {
+		t.Errorf("MatomoSiteID() = %q", got)
+	}
+}
+
+func TestSettersValidation(t *testing.T) {
+	resetRuntime(t)
+
+	if err := SetHLSSegmentDuration(1); err == nil {
+		t.Error("expected error for duration 1")
+	}
+	if err := SetHLSSegmentDuration(20); err == nil {
+		t.Error("expected error for duration 20")
+	}
+	if err := SetHLSSegmentDuration(6); err != nil {
+		t.Errorf("unexpected error for duration 6: %v", err)
+	}
+
+	if err := SetHLSWindowSize(2); err == nil {
+		t.Error("expected error for window 2")
+	}
+	if err := SetHLSWindowSize(101); err == nil {
+		t.Error("expected error for window 101")
+	}
+	if err := SetHLSWindowSize(24); err != nil {
+		t.Errorf("unexpected error for window 24: %v", err)
+	}
+
+	if err := SetMatomoURL("not-a-url"); err == nil {
+		t.Error("expected error for invalid URL")
+	}
+	if err := SetMatomoURL("ftp://example.com"); err == nil {
+		t.Error("expected error for non-http URL")
+	}
+	if err := SetMatomoURL("https://stats.example.com"); err != nil {
+		t.Errorf("unexpected error for valid URL: %v", err)
+	}
+
+	if err := SetMatomoSiteID("abc"); err == nil {
+		t.Error("expected error for non-numeric site ID")
+	}
+	if err := SetMatomoSiteID("99"); err != nil {
+		t.Errorf("unexpected error for numeric site ID: %v", err)
+	}
+}

backend/chat/src/db/db.go

@@ -1,82 +1,82 @@
-package db
+package db
-
+
-import (
+import (
-	"context"
+	"context"
-	"log"
+	"log"
-	"strings"
+	"strings"
-	"time"
+	"time"
-
+
-	"github.com/glebarez/sqlite"
+	"github.com/glebarez/sqlite"
-	"gorm.io/driver/postgres"
+	"gorm.io/driver/postgres"
-	"gorm.io/gorm"
+	"gorm.io/gorm"
-)
+)
-
+
-// DBClient wraps gorm.DB for testability.
+// DBClient wraps gorm.DB for testability.
-type DBClient struct {
+type DBClient struct {
-	*gorm.DB
+	*gorm.DB
-}
+}
-
+
-// InitDB initializes configured SQL storage for chat, moderation, and admin metadata (ADR-006).
+// InitDB initializes configured SQL storage for chat, moderation, and admin metadata (ADR-006).
-// Returns the client and the driver name.
+// Returns the client and the driver name.
-func InitDB(databaseURL string) (*DBClient, string, error) {
+func InitDB(databaseURL string) (*DBClient, string, error) {
-	var (
+	var (
-		gormDB *gorm.DB
+		gormDB *gorm.DB
-		err    error
+		err    error
-		driver = "sqlite"
+		driver = "sqlite"
-	)
+	)
-
+
-	switch {
+	switch {
-	case databaseURL == "":
+	case databaseURL == "":
-		gormDB, err = gorm.Open(sqlite.Open("chat.db"), &gorm.Config{})
+		gormDB, err = gorm.Open(sqlite.Open("chat.db"), &gorm.Config{})
-	case strings.HasPrefix(databaseURL, "sqlite://"):
+	case strings.HasPrefix(databaseURL, "sqlite://"):
-		sqlitePath := strings.TrimPrefix(databaseURL, "sqlite://")
+		sqlitePath := strings.TrimPrefix(databaseURL, "sqlite://")
-		if sqlitePath == "" {
+		if sqlitePath == "" {
-			sqlitePath = "chat.db"
+			sqlitePath = "chat.db"
-		}
+		}
-		gormDB, err = gorm.Open(sqlite.Open(sqlitePath), &gorm.Config{})
+		gormDB, err = gorm.Open(sqlite.Open(sqlitePath), &gorm.Config{})
-	case strings.HasPrefix(databaseURL, "postgres://") || strings.HasPrefix(databaseURL, "postgresql://"):
+	case strings.HasPrefix(databaseURL, "postgres://") || strings.HasPrefix(databaseURL, "postgresql://"):
-		driver = "postgres"
+		driver = "postgres"
-		gormDB, err = gorm.Open(postgres.Open(databaseURL), &gorm.Config{})
+		gormDB, err = gorm.Open(postgres.Open(databaseURL), &gorm.Config{})
-	default:
+	default:
-		log.Fatalf("Unsupported DATABASE_URL scheme: %s", databaseURL)
+		log.Fatalf("Unsupported DATABASE_URL scheme: %s", databaseURL)
-	}
+	}
-
+
-	if err != nil {
+	if err != nil {
-		return nil, driver, err
+		return nil, driver, err
-	}
+	}
-
+
-	gormDB.AutoMigrate(&Message{}, &ModerationLog{}, &Media{}, &ScheduleOverride{})
+	gormDB.AutoMigrate(&Message{}, &ModerationLog{}, &Media{}, &ScheduleOverride{}, &User{})
-	log.Printf("%s database initialized (chat history, moderation log, media metadata)", strings.Title(driver))
+	log.Printf("%s database initialized (chat history, moderation log, media metadata)", strings.Title(driver))
-
+
-	return &DBClient{DB: gormDB}, driver, nil
+	return &DBClient{DB: gormDB}, driver, nil
-}
+}
-
+
-// RedisClient wraps the Redis client for testability.
+// RedisClient wraps the Redis client for testability.
-// Interface defined for mocking in tests.
+// Interface defined for mocking in tests.
-type RedisClient interface {
+type RedisClient interface {
-	Ping(ctx context.Context) error
+	Ping(ctx context.Context) error
-	Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error
+	Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error
-	Get(ctx context.Context, key string) (string, error)
+	Get(ctx context.Context, key string) (string, error)
-	Del(ctx context.Context, keys ...string) error
+	Del(ctx context.Context, keys ...string) error
-	Incr(ctx context.Context, key string) (int64, error)
+	Incr(ctx context.Context, key string) (int64, error)
-	Decr(ctx context.Context, key string) (int64, error)
+	Decr(ctx context.Context, key string) (int64, error)
-	Expire(ctx context.Context, key string, expiration time.Duration) error
+	Expire(ctx context.Context, key string, expiration time.Duration) error
-	Exists(ctx context.Context, keys ...string) (int64, error)
+	Exists(ctx context.Context, keys ...string) (int64, error)
-	Publish(ctx context.Context, channel string, message interface{}) error
+	Publish(ctx context.Context, channel string, message interface{}) error
-	PSubscribe(ctx context.Context, channels ...string) PubSub
+	PSubscribe(ctx context.Context, channels ...string) PubSub
-	Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error)
+	Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error)
-	Info(ctx context.Context, sections ...string) (string, error)
+	Info(ctx context.Context, sections ...string) (string, error)
-	Close() error
+	Close() error
-}
+}
-
+
-// PubSub wraps Redis pub/sub subscription.
+// PubSub wraps Redis pub/sub subscription.
-type PubSub interface {
+type PubSub interface {
-	ReceiveMessage(ctx context.Context) (*PubSubMessage, error)
+	ReceiveMessage(ctx context.Context) (*PubSubMessage, error)
-	Close() error
+	Close() error
-}
+}
-
+
-// PubSubMessage represents a received pub/sub message.
+// PubSubMessage represents a received pub/sub message.
-type PubSubMessage struct {
+type PubSubMessage struct {
-	Channel string
+	Channel string
-	Payload string
+	Payload string
 }

backend/chat/src/db/db_test.go

@@ -1,179 +1,179 @@
-package db
+package db
-
+
-import (
+import (
-	"testing"
+	"testing"
-	"time"
+	"time"
-)
+)
-
+
-func TestInitDB_SQLite(t *testing.T) {
+func TestInitDB_SQLite(t *testing.T) {
-	client, driver, err := InitDB("sqlite://:memory:")
+	client, driver, err := InitDB("sqlite://:memory:")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("InitDB() error = %v", err)
+		t.Fatalf("InitDB() error = %v", err)
-	}
+	}
-	if driver != "sqlite" {
+	if driver != "sqlite" {
-		t.Errorf("InitDB() driver = %q, want sqlite", driver)
+		t.Errorf("InitDB() driver = %q, want sqlite", driver)
-	}
+	}
-	if client == nil {
+	if client == nil {
-		t.Fatal("InitDB() client = nil")
+		t.Fatal("InitDB() client = nil")
-	}
+	}
-
+
-	// Verify tables exist by running AutoMigrate (idempotent)
+	// Verify tables exist by running AutoMigrate (idempotent)
-	err = client.DB.AutoMigrate(&Message{}, &ModerationLog{}, &Media{}, &ScheduleOverride{})
+	err = client.DB.AutoMigrate(&Message{}, &ModerationLog{}, &Media{}, &ScheduleOverride{})
-	if err != nil {
+	if err != nil {
-		t.Errorf("AutoMigrate error = %v", err)
+		t.Errorf("AutoMigrate error = %v", err)
-	}
+	}
-
+
-	// Verify CRUD on Message
+	// Verify CRUD on Message
-	msg := Message{
+	msg := Message{
-		Room:      "test",
+		Room:      "test",
-		Username:  "user1",
+		Username:  "user1",
-		Text:      "hello",
+		Text:      "hello",
-		Timestamp: time.Now(),
+		Timestamp: time.Now(),
-		Type:      "public",
+		Type:      "public",
-	}
+	}
-	if err := client.DB.Create(&msg).Error; err != nil {
+	if err := client.DB.Create(&msg).Error; err != nil {
-		t.Fatalf("Create message error = %v", err)
+		t.Fatalf("Create message error = %v", err)
-	}
+	}
-	if msg.ID == 0 {
+	if msg.ID == 0 {
-		t.Error("Create message did not set ID")
+		t.Error("Create message did not set ID")
-	}
+	}
-
+
-	var count int64
+	var count int64
-	client.DB.Model(&Message{}).Count(&count)
+	client.DB.Model(&Message{}).Count(&count)
-	if count != 1 {
+	if count != 1 {
-		t.Errorf("Message count = %d, want 1", count)
+		t.Errorf("Message count = %d, want 1", count)
-	}
+	}
-
+
-	// Verify read
+	// Verify read
-	var read Message
+	var read Message
-	if err := client.DB.First(&read, msg.ID).Error; err != nil {
+	if err := client.DB.First(&read, msg.ID).Error; err != nil {
-		t.Fatalf("First message error = %v", err)
+		t.Fatalf("First message error = %v", err)
-	}
+	}
-	if read.Text != "hello" {
+	if read.Text != "hello" {
-		t.Errorf("read.Text = %q, want hello", read.Text)
+		t.Errorf("read.Text = %q, want hello", read.Text)
-	}
+	}
-
+
-	// Verify delete
+	// Verify delete
-	client.DB.Delete(&Message{}, msg.ID)
+	client.DB.Delete(&Message{}, msg.ID)
-	client.DB.Model(&Message{}).Count(&count)
+	client.DB.Model(&Message{}).Count(&count)
-	if count != 0 {
+	if count != 0 {
-		t.Errorf("Message count after delete = %d, want 0", count)
+		t.Errorf("Message count after delete = %d, want 0", count)
-	}
+	}
-}
+}
-
+
-func TestInitDB_ModerationLog(t *testing.T) {
+func TestInitDB_ModerationLog(t *testing.T) {
-	client, _, err := InitDB("sqlite://:memory:")
+	client, _, err := InitDB("sqlite://:memory:")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("InitDB() error = %v", err)
+		t.Fatalf("InitDB() error = %v", err)
-	}
+	}
-
+
-	log := ModerationLog{
+	log := ModerationLog{
-		Action:    "mute",
+		Action:    "mute",
-		Target:    "user1",
+		Target:    "user1",
-		Moderator: "admin",
+		Moderator: "admin",
-		Reason:    "spam",
+		Reason:    "spam",
-		Timestamp: time.Now(),
+		Timestamp: time.Now(),
-	}
+	}
-	if err := client.DB.Create(&log).Error; err != nil {
+	if err := client.DB.Create(&log).Error; err != nil {
-		t.Fatalf("Create moderation log error = %v", err)
+		t.Fatalf("Create moderation log error = %v", err)
-	}
+	}
-	if log.ID == 0 {
+	if log.ID == 0 {
-		t.Error("Create moderation log did not set ID")
+		t.Error("Create moderation log did not set ID")
-	}
+	}
-
+
-	var count int64
+	var count int64
-	client.DB.Model(&ModerationLog{}).Count(&count)
+	client.DB.Model(&ModerationLog{}).Count(&count)
-	if count != 1 {
+	if count != 1 {
-		t.Errorf("ModerationLog count = %d, want 1", count)
+		t.Errorf("ModerationLog count = %d, want 1", count)
-	}
+	}
-}
+}
-
+
-func TestInitDB_Media(t *testing.T) {
+func TestInitDB_Media(t *testing.T) {
-	client, _, err := InitDB("sqlite://:memory:")
+	client, _, err := InitDB("sqlite://:memory:")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("InitDB() error = %v", err)
+		t.Fatalf("InitDB() error = %v", err)
-	}
+	}
-
+
-	media := Media{
+	media := Media{
-		Filename:        "test.mp4",
+		Filename:        "test.mp4",
-		OriginalName:    "test.mp4",
+		OriginalName:    "test.mp4",
-		Path:            "/media/test.mp4",
+		Path:            "/media/test.mp4",
-		SizeBytes:       1024,
+		SizeBytes:       1024,
-		DurationSeconds: 60,
+		DurationSeconds: 60,
-		Status:          "ready",
+		Status:          "ready",
-		Title:           "Test Video",
+		Title:           "Test Video",
-		Tags:            "tag1,tag2",
+		Tags:            "tag1,tag2",
-	}
+	}
-	if err := client.DB.Create(&media).Error; err != nil {
+	if err := client.DB.Create(&media).Error; err != nil {
-		t.Fatalf("Create media error = %v", err)
+		t.Fatalf("Create media error = %v", err)
-	}
+	}
-	if media.ID == 0 {
+	if media.ID == 0 {
-		t.Error("Create media did not set ID")
+		t.Error("Create media did not set ID")
-	}
+	}
-
+
-	// Verify update
+	// Verify update
-	client.DB.Model(&media).Update("status", "needs_normalization")
+	client.DB.Model(&media).Update("status", "needs_normalization")
-	var updated Media
+	var updated Media
-	client.DB.First(&updated, media.ID)
+	client.DB.First(&updated, media.ID)
-	if updated.Status != "needs_normalization" {
+	if updated.Status != "needs_normalization" {
-		t.Errorf("updated.Status = %q, want needs_normalization", updated.Status)
+		t.Errorf("updated.Status = %q, want needs_normalization", updated.Status)
-	}
+	}
-}
+}
-
+
-func TestInitDB_ScheduleOverride(t *testing.T) {
+func TestInitDB_ScheduleOverride(t *testing.T) {
-	client, _, err := InitDB("sqlite://:memory:")
+	client, _, err := InitDB("sqlite://:memory:")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("InitDB() error = %v", err)
+		t.Fatalf("InitDB() error = %v", err)
-	}
+	}
-
+
-	now := time.Now()
+	now := time.Now()
-	ov := ScheduleOverride{
+	ov := ScheduleOverride{
-		MediaID:   1,
+		MediaID:   1,
-		StartTime: now,
+		StartTime: now,
-		EndTime:   now.Add(1 * time.Hour),
+		EndTime:   now.Add(1 * time.Hour),
-		Reason:    "special event",
+		Reason:    "special event",
-	}
+	}
-	if err := client.DB.Create(&ov).Error; err != nil {
+	if err := client.DB.Create(&ov).Error; err != nil {
-		t.Fatalf("Create schedule override error = %v", err)
+		t.Fatalf("Create schedule override error = %v", err)
-	}
+	}
-	if ov.ID == 0 {
+	if ov.ID == 0 {
-		t.Error("Create schedule override did not set ID")
+		t.Error("Create schedule override did not set ID")
-	}
+	}
-
+
-	// Conflict detection
+	// Conflict detection
-	var conflict int64
+	var conflict int64
-	client.DB.Model(&ScheduleOverride{}).
+	client.DB.Model(&ScheduleOverride{}).
-		Where("start_time < ? AND end_time > ?", ov.EndTime, ov.StartTime).
+		Where("start_time < ? AND end_time > ?", ov.EndTime, ov.StartTime).
-		Count(&conflict)
+		Count(&conflict)
-	if conflict != 1 {
+	if conflict != 1 {
-		t.Errorf("conflict count = %d, want 1", conflict)
+		t.Errorf("conflict count = %d, want 1", conflict)
-	}
+	}
-}
+}
-
+
-func TestInitDB_EmptyURL(t *testing.T) {
+func TestInitDB_EmptyURL(t *testing.T) {
-	// Empty URL should default to SQLite chat.db
+	// Empty URL should default to SQLite chat.db
-	// This creates a file, clean up after
+	// This creates a file, clean up after
-	client, driver, err := InitDB("")
+	client, driver, err := InitDB("")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("InitDB(\"\") error = %v", err)
+		t.Fatalf("InitDB(\"\") error = %v", err)
-	}
+	}
-	if driver != "sqlite" {
+	if driver != "sqlite" {
-		t.Errorf("InitDB(\"\") driver = %q, want sqlite", driver)
+		t.Errorf("InitDB(\"\") driver = %q, want sqlite", driver)
-	}
+	}
-	if client == nil {
+	if client == nil {
-		t.Fatal("InitDB(\"\") client = nil")
+		t.Fatal("InitDB(\"\") client = nil")
-	}
+	}
-}
+}
-
+
-func TestInitDB_SQLitePath(t *testing.T) {
+func TestInitDB_SQLitePath(t *testing.T) {
-	client, driver, err := InitDB("sqlite://:memory:?cache=shared")
+	client, driver, err := InitDB("sqlite://:memory:?cache=shared")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("InitDB() error = %v", err)
+		t.Fatalf("InitDB() error = %v", err)
-	}
+	}
-	if driver != "sqlite" {
+	if driver != "sqlite" {
-		t.Errorf("InitDB() driver = %q, want sqlite", driver)
+		t.Errorf("InitDB() driver = %q, want sqlite", driver)
-	}
+	}
-	if client == nil {
+	if client == nil {
-		t.Fatal("InitDB() client = nil")
+		t.Fatal("InitDB() client = nil")
-	}
+	}
 }

backend/chat/src/db/models.go

@@ -1,57 +1,65 @@
-package db
+package db
-
+
-import (
+import (
-	"time"
+	"time"
-)
+)
-
+
-// Message represents a chat message (persisted in SQL DB per ADR-006)
+// Message represents a chat message (persisted in SQL DB per ADR-006)
-type Message struct {
+type Message struct {
-	ID        uint      `gorm:"primarykey" json:"id"`
+	ID        uint      `gorm:"primarykey" json:"id"`
-	Room      string    `json:"room"`
+	Room      string    `json:"room"`
-	Username  string    `json:"username"`
+	Username  string    `json:"username"`
-	Text      string    `json:"text"`
+	Text      string    `json:"text"`
-	Timestamp time.Time `json:"timestamp"`
+	Timestamp time.Time `json:"timestamp"`
-	Type      string    `json:"type"` // "public", "private", "system", "moderation"
+	Type      string    `json:"type"` // "public", "private", "system", "moderation"
-}
+}
-
+
-// ModerationLog for audit trail (immutable per ADR-005)
+// ModerationLog for audit trail (immutable per ADR-005)
-type ModerationLog struct {
+type ModerationLog struct {
-	ID        uint      `gorm:"primarykey" json:"id"`
+	ID        uint      `gorm:"primarykey" json:"id"`
-	Action    string    `json:"action"` // "mute", "ban", "delete", "timeout"
+	Action    string    `json:"action"` // "mute", "ban", "delete", "timeout"
-	Target    string    `json:"target"`
+	Target    string    `json:"target"`
-	Moderator string    `json:"moderator"`
+	Moderator string    `json:"moderator"`
-	Reason    string    `json:"reason"`
+	Reason    string    `json:"reason"`
-	Timestamp time.Time `json:"timestamp"`
+	Timestamp time.Time `json:"timestamp"`
-}
+}
-
+
-// Media stores admin media library metadata (filesystem + DB model per ADR-006)
+// Media stores admin media library metadata (filesystem + DB model per ADR-006)
-type Media struct {
+type Media struct {
-	ID              uint      `gorm:"primarykey" json:"id"`
+	ID              uint      `gorm:"primarykey" json:"id"`
-	Filename        string    `gorm:"index" json:"filename"`
+	Filename        string    `gorm:"index" json:"filename"`
-	OriginalName    string    `json:"originalName"`
+	OriginalName    string    `json:"originalName"`
-	Path            string    `json:"path"`
+	Path            string    `json:"path"`
-	SizeBytes       int64     `json:"sizeBytes"`
+	SizeBytes       int64     `json:"sizeBytes"`
-	DurationSeconds int       `json:"durationSeconds"`
+	DurationSeconds int       `json:"durationSeconds"`
-	Status          string    `gorm:"index" json:"status"`
+	Status          string    `gorm:"index" json:"status"`
-	Title           string    `json:"title"`
+	Title           string    `json:"title"`
-	Tags            string    `json:"tags"`
+	Tags            string    `json:"tags"`
-	UploadedAt      time.Time `gorm:"autoCreateTime" json:"uploadedAt"`
+	UploadedAt      time.Time `gorm:"autoCreateTime" json:"uploadedAt"`
-	UpdatedAt       time.Time `gorm:"autoUpdateTime" json:"updatedAt"`
+	UpdatedAt       time.Time `gorm:"autoUpdateTime" json:"updatedAt"`
-}
+}
-
+
-// ScheduleOverride represents a scheduled playlist override (ADR-004)
+// User represents a registered chat user account (ADR-006).
-type ScheduleOverride struct {
+type User struct {
-	ID        uint      `gorm:"primarykey" json:"id"`
+	ID           uint      `gorm:"primarykey" json:"id"`
-	MediaID   uint      `json:"mediaId"`
+	Username     string    `gorm:"uniqueIndex;size:32" json:"username"`
-	StartTime time.Time `json:"startTime"`
+	PasswordHash string    `json:"-"`
-	EndTime   time.Time `json:"endTime"`
+	CreatedAt    time.Time `gorm:"autoCreateTime" json:"createdAt"`
-	Reason    string    `json:"reason"`
+}
-	CreatedAt time.Time `json:"createdAt"`
+
-}
+// ScheduleOverride represents a scheduled playlist override (ADR-004)
-
+type ScheduleOverride struct {
-// Presence tracks online users per room (using Redis per ADR-007)
+	ID        uint      `gorm:"primarykey" json:"id"`
-type Presence struct {
+	MediaID   uint      `json:"mediaId"`
-	Username string `json:"username"`
+	StartTime time.Time `json:"startTime"`
-	Room     string `json:"room"`
+	EndTime   time.Time `json:"endTime"`
-	Online   bool   `json:"online"`
+	Reason    string    `json:"reason"`
+	CreatedAt time.Time `json:"createdAt"`
+}
+
+// Presence tracks online users per room (using Redis per ADR-007)
+type Presence struct {
+	Username string `json:"username"`
+	Room     string `json:"room"`
+	Online   bool   `json:"online"`
 }

backend/chat/src/db/redis.go

@@ -1,163 +1,163 @@
-package db
+package db
-
+
-import (
+import (
-	"context"
+	"context"
-	"log"
+	"log"
-	"strings"
+	"strings"
-	"time"
+	"time"
-
+
-	"github.com/redis/go-redis/v9"
+	"github.com/redis/go-redis/v9"
-)
+)
-
+
-// RedisWrapper wraps go-redis client to implement RedisClient interface.
+// RedisWrapper wraps go-redis client to implement RedisClient interface.
-type RedisWrapper struct {
+type RedisWrapper struct {
-	client *redis.Client
+	client *redis.Client
-}
+}
-
+
-// NewRedisWrapper creates a RedisWrapper from a go-redis client.
+// NewRedisWrapper creates a RedisWrapper from a go-redis client.
-func NewRedisWrapper(client *redis.Client) *RedisWrapper {
+func NewRedisWrapper(client *redis.Client) *RedisWrapper {
-	return &RedisWrapper{client: client}
+	return &RedisWrapper{client: client}
-}
+}
-
+
-// InitRedis initializes Redis for presence, rate limiting, and pub/sub (ADR-007).
+// InitRedis initializes Redis for presence, rate limiting, and pub/sub (ADR-007).
-// Returns nil if Redis is unavailable (non-fatal).
+// Returns nil if Redis is unavailable (non-fatal).
-func InitRedis(redisAddress string) *RedisWrapper {
+func InitRedis(redisAddress string) *RedisWrapper {
-	var options *redis.Options
+	var options *redis.Options
-	var err error
+	var err error
-
+
-	if strings.Contains(redisAddress, "://") {
+	if strings.Contains(redisAddress, "://") {
-		options, err = redis.ParseURL(redisAddress)
+		options, err = redis.ParseURL(redisAddress)
-		if err != nil {
+		if err != nil {
-			log.Printf("Redis configuration warning: %v (rate limiting and presence will be disabled)", err)
+			log.Printf("Redis configuration warning: %v (rate limiting and presence will be disabled)", err)
-			return nil
+			return nil
-		}
+		}
-	} else {
+	} else {
-		options = &redis.Options{Addr: redisAddress}
+		options = &redis.Options{Addr: redisAddress}
-	}
+	}
-
+
-	client := redis.NewClient(options)
+	client := redis.NewClient(options)
-	if err := client.Ping(context.Background()).Err(); err != nil {
+	if err := client.Ping(context.Background()).Err(); err != nil {
-		log.Printf("Redis connection warning: %v (rate limiting and presence will be disabled)", err)
+		log.Printf("Redis connection warning: %v (rate limiting and presence will be disabled)", err)
-		client.Close()
+		client.Close()
-		// Start auto-reconnect goroutine
+		// Start auto-reconnect goroutine
-		go redisReconnectLoop(redisAddress, options)
+		go redisReconnectLoop(redisAddress, options)
-		return nil
+		return nil
-	}
+	}
-
+
-	log.Println("Redis connected successfully (presence, rate limiting, pub/sub enabled)")
+	log.Println("Redis connected successfully (presence, rate limiting, pub/sub enabled)")
-	return &RedisWrapper{client: client}
+	return &RedisWrapper{client: client}
-}
+}
-
+
-// redisReconnectLoop attempts to reconnect to Redis with exponential backoff.
+// redisReconnectLoop attempts to reconnect to Redis with exponential backoff.
-func redisReconnectLoop(addr string, baseOptions *redis.Options) {
+func redisReconnectLoop(addr string, baseOptions *redis.Options) {
-	backoff := 2 * time.Second
+	backoff := 2 * time.Second
-	maxBackoff := 60 * time.Second
+	maxBackoff := 60 * time.Second
-	for {
+	for {
-		time.Sleep(backoff)
+		time.Sleep(backoff)
-		testClient := redis.NewClient(baseOptions)
+		testClient := redis.NewClient(baseOptions)
-		if err := testClient.Ping(context.Background()).Err(); err != nil {
+		if err := testClient.Ping(context.Background()).Err(); err != nil {
-			log.Printf("Redis reconnect failed: %v (retry in %v)", err, backoff)
+			log.Printf("Redis reconnect failed: %v (retry in %v)", err, backoff)
-			backoff *= 2
+			backoff *= 2
-			if backoff > maxBackoff {
+			if backoff > maxBackoff {
-				backoff = maxBackoff
+				backoff = maxBackoff
-			}
+			}
-			testClient.Close()
+			testClient.Close()
-			continue
+			continue
-		}
+		}
-		// Reconnected — caller must replace their reference.
+		// Reconnected — caller must replace their reference.
-		// This is a best-effort background reconnect; the wrapper
+		// This is a best-effort background reconnect; the wrapper
-		// returned by InitRedis remains nil until a new InitRedis call.
+		// returned by InitRedis remains nil until a new InitRedis call.
-		log.Println("Redis reconnected successfully (background)")
+		log.Println("Redis reconnected successfully (background)")
-		testClient.Close()
+		testClient.Close()
-		return
+		return
-	}
+	}
-}
+}
-
+
-// Ping checks Redis connectivity.
+// Ping checks Redis connectivity.
-func (r *RedisWrapper) Ping(ctx context.Context) error {
+func (r *RedisWrapper) Ping(ctx context.Context) error {
-	if r == nil || r.client == nil {
+	if r == nil || r.client == nil {
-		return redis.ErrClosed
+		return redis.ErrClosed
-	}
+	}
-	return r.client.Ping(ctx).Err()
+	return r.client.Ping(ctx).Err()
-}
+}
-
+
-// Set stores a key with TTL.
+// Set stores a key with TTL.
-func (r *RedisWrapper) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error {
+func (r *RedisWrapper) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error {
-	return r.client.Set(ctx, key, value, expiration).Err()
+	return r.client.Set(ctx, key, value, expiration).Err()
-}
+}
-
+
-// Get retrieves a key.
+// Get retrieves a key.
-func (r *RedisWrapper) Get(ctx context.Context, key string) (string, error) {
+func (r *RedisWrapper) Get(ctx context.Context, key string) (string, error) {
-	return r.client.Get(ctx, key).Result()
+	return r.client.Get(ctx, key).Result()
-}
+}
-
+
-// Del removes keys.
+// Del removes keys.
-func (r *RedisWrapper) Del(ctx context.Context, keys ...string) error {
+func (r *RedisWrapper) Del(ctx context.Context, keys ...string) error {
-	return r.client.Del(ctx, keys...).Err()
+	return r.client.Del(ctx, keys...).Err()
-}
+}
-
+
-// Incr increments a key.
+// Incr increments a key.
-func (r *RedisWrapper) Incr(ctx context.Context, key string) (int64, error) {
+func (r *RedisWrapper) Incr(ctx context.Context, key string) (int64, error) {
-	return r.client.Incr(ctx, key).Result()
+	return r.client.Incr(ctx, key).Result()
-}
+}
-
+
-// Decr decrements a key.
+// Decr decrements a key.
-func (r *RedisWrapper) Decr(ctx context.Context, key string) (int64, error) {
+func (r *RedisWrapper) Decr(ctx context.Context, key string) (int64, error) {
-	return r.client.Decr(ctx, key).Result()
+	return r.client.Decr(ctx, key).Result()
-}
+}
-
+
-// Expire sets TTL on a key.
+// Expire sets TTL on a key.
-func (r *RedisWrapper) Expire(ctx context.Context, key string, expiration time.Duration) error {
+func (r *RedisWrapper) Expire(ctx context.Context, key string, expiration time.Duration) error {
-	return r.client.Expire(ctx, key, expiration).Err()
+	return r.client.Expire(ctx, key, expiration).Err()
-}
+}
-
+
-// Exists checks if keys exist.
+// Exists checks if keys exist.
-func (r *RedisWrapper) Exists(ctx context.Context, keys ...string) (int64, error) {
+func (r *RedisWrapper) Exists(ctx context.Context, keys ...string) (int64, error) {
-	return r.client.Exists(ctx, keys...).Result()
+	return r.client.Exists(ctx, keys...).Result()
-}
+}
-
+
-// Publish publishes a message to a channel.
+// Publish publishes a message to a channel.
-func (r *RedisWrapper) Publish(ctx context.Context, channel string, message interface{}) error {
+func (r *RedisWrapper) Publish(ctx context.Context, channel string, message interface{}) error {
-	return r.client.Publish(ctx, channel, message).Err()
+	return r.client.Publish(ctx, channel, message).Err()
-}
+}
-
+
-// PSubscribe subscribes to channels by pattern.
+// PSubscribe subscribes to channels by pattern.
-func (r *RedisWrapper) PSubscribe(ctx context.Context, channels ...string) PubSub {
+func (r *RedisWrapper) PSubscribe(ctx context.Context, channels ...string) PubSub {
-	ps := r.client.PSubscribe(ctx, channels...)
+	ps := r.client.PSubscribe(ctx, channels...)
-	return &redisPubSubWrapper{ps: ps}
+	return &redisPubSubWrapper{ps: ps}
-}
+}
-
+
-// Scan scans keys matching a pattern.
+// Scan scans keys matching a pattern.
-func (r *RedisWrapper) Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error) {
+func (r *RedisWrapper) Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error) {
-	return r.client.Scan(ctx, cursor, match, count).Result()
+	return r.client.Scan(ctx, cursor, match, count).Result()
-}
+}
-
+
-// Info returns Redis server info.
+// Info returns Redis server info.
-func (r *RedisWrapper) Info(ctx context.Context, sections ...string) (string, error) {
+func (r *RedisWrapper) Info(ctx context.Context, sections ...string) (string, error) {
-	return r.client.Info(ctx, sections...).Result()
+	return r.client.Info(ctx, sections...).Result()
-}
+}
-
+
-// Close closes the Redis connection.
+// Close closes the Redis connection.
-func (r *RedisWrapper) Close() error {
+func (r *RedisWrapper) Close() error {
-	if r == nil || r.client == nil {
+	if r == nil || r.client == nil {
-		return nil
+		return nil
-	}
+	}
-	return r.client.Close()
+	return r.client.Close()
-}
+}
-
+
-// redisPubSubWrapper wraps go-redis PubSub.
+// redisPubSubWrapper wraps go-redis PubSub.
-type redisPubSubWrapper struct {
+type redisPubSubWrapper struct {
-	ps *redis.PubSub
+	ps *redis.PubSub
-}
+}
-
+
-func (w *redisPubSubWrapper) ReceiveMessage(ctx context.Context) (*PubSubMessage, error) {
+func (w *redisPubSubWrapper) ReceiveMessage(ctx context.Context) (*PubSubMessage, error) {
-	msg, err := w.ps.ReceiveMessage(ctx)
+	msg, err := w.ps.ReceiveMessage(ctx)
-	if err != nil {
+	if err != nil {
-		return nil, err
+		return nil, err
-	}
+	}
-	return &PubSubMessage{Channel: msg.Channel, Payload: msg.Payload}, nil
+	return &PubSubMessage{Channel: msg.Channel, Payload: msg.Payload}, nil
-}
+}
-
+
-func (w *redisPubSubWrapper) Close() error {
+func (w *redisPubSubWrapper) Close() error {
-	return w.ps.Close()
+	return w.ps.Close()
 }

backend/chat/src/main.go

@@ -1,97 +1,111 @@
-package main
+package main
-
+
-import (
+import (
-	"crypto/rand"
+	"crypto/rand"
-	"encoding/hex"
+	"encoding/hex"
-	"fmt"
+	"fmt"
-	"log"
+	"log"
-	"net/http"
+	"net/http"
-
+
-	"chat/src/auth"
+	"chat/src/auth"
-	"chat/src/config"
+	"chat/src/config"
-	"chat/src/db"
+	"chat/src/db"
-	"chat/src/handlers"
+	"chat/src/handlers"
-	"chat/src/metrics"
+	"chat/src/metrics"
-	"chat/src/ws"
+	"chat/src/ws"
-)
+)
-
+
-func generateShortID() string {
+func generateShortID() string {
-	b := make([]byte, 6)
+	b := make([]byte, 6)
-	rand.Read(b)
+	rand.Read(b)
-	return hex.EncodeToString(b)
+	return hex.EncodeToString(b)
-}
+}
-
+
-func main() {
+func main() {
-	instanceID := fmt.Sprintf("chat-%s", generateShortID())
+	instanceID := fmt.Sprintf("chat-%s", generateShortID())
-
+
-	rateLimitMax := config.RateLimitMax()
+	rateLimitMax := config.RateLimitMax()
-	rateLimitWindow := config.RateLimitWindow()
+	rateLimitWindow := config.RateLimitWindow()
-	log.Printf("Rate limit: %d messages per %v", rateLimitMax, rateLimitWindow)
+	log.Printf("Rate limit: %d messages per %v", rateLimitMax, rateLimitWindow)
-
+
-	// Initialize Redis
+	// Load persisted runtime configuration (Matomo + HLS settings)
-	redisWrapper := db.InitRedis(config.RedisAddress())
+	if err := config.LoadRuntimeConfig(); err != nil {
-
+		log.Printf("Warning: failed to load runtime config: %v", err)
-	// Initialize DB
+	}
-	dbClient, dbDriver, err := db.InitDB(config.DatabaseURL())
+
-	if err != nil {
+	// Initialize Redis
-		log.Fatalf("Failed to initialize database: %v", err)
+	redisWrapper := db.InitRedis(config.RedisAddress())
-	}
+
-
+	// Initialize DB
-	// Initialize session store
+	dbClient, dbDriver, err := db.InitDB(config.DatabaseURL())
-	sessionStore := auth.NewSessionStore()
+	if err != nil {
-
+		log.Fatalf("Failed to initialize database: %v", err)
-	// Initialize WebSocket hub
+	}
-	hub := ws.NewHub(dbClient.DB, redisWrapper, instanceID, rateLimitMax, rateLimitWindow, config.AdminUsername())
+
-
+	// Initialize session store
-	// Start Redis pub/sub subscriber
+	sessionStore := auth.NewSessionStore()
-	go hub.SubscribeRoomMessages()
+	userSessions := auth.NewUserSessionStore()
-
+
-	log.Printf("Instance ID: %s", instanceID)
+	// Initialize WebSocket hub
-
+	hub := ws.NewHub(dbClient.DB, redisWrapper, instanceID, rateLimitMax, rateLimitWindow, config.AdminUsername())
-	// Build dependencies
+
-	deps := &handlers.Dependencies{
+	// Start Redis pub/sub subscriber
-		DB:           dbClient.DB,
+	go hub.SubscribeRoomMessages()
-		Redis:        redisWrapper,
+
-		Hub:          hub,
+	log.Printf("Instance ID: %s", instanceID)
-		SessionStore: sessionStore,
+
-		DBDriver:     dbDriver,
+	// Build dependencies
-	}
+	deps := &handlers.Dependencies{
-
+		DB:           dbClient.DB,
-	// Auth middleware
+		Redis:        redisWrapper,
-	requireAdmin := auth.RequireAdmin(sessionStore, config.AdminSessionCookieName)
+		Hub:          hub,
-
+		SessionStore: sessionStore,
-	// Register routes
+		UserSessions: userSessions,
-	http.HandleFunc("/ws", hub.HandleConnection)
+		DBDriver:     dbDriver,
-	http.HandleFunc("/api/admin/login", handlers.HandleAdminLogin(deps))
+	}
-	http.HandleFunc("/api/admin/logout", handlers.HandleAdminLogout(deps))
+
-	http.HandleFunc("/api/admin/session", handlers.HandleAdminSession(deps))
+	// Auth middleware
-	http.HandleFunc("/api/admin/overview", requireAdmin(handlers.HandleAdminOverview(deps)))
+	requireAdmin := auth.RequireAdmin(sessionStore, config.AdminSessionCookieName)
-	http.HandleFunc("/api/admin/playlist", requireAdmin(handlers.HandleAdminPlaylist(deps)))
+
-	http.HandleFunc("/api/admin/moderation/logs", requireAdmin(handlers.HandleAdminModerationLogs(deps)))
+	// Register routes
-	http.HandleFunc("/api/admin/moderation/actions", requireAdmin(handlers.HandleAdminModerationAction(deps)))
+	http.HandleFunc("/ws", hub.HandleConnection)
-	http.HandleFunc("/api/admin/analytics", requireAdmin(handlers.HandleAdminAnalytics(deps)))
+	http.HandleFunc("/api/auth/register", metrics.WrapRequestTiming(handlers.HandleUserRegister(deps)))
-	http.HandleFunc("/api/admin/system", requireAdmin(handlers.HandleAdminSystemSummary(deps)))
+	http.HandleFunc("/api/auth/login", metrics.WrapRequestTiming(handlers.HandleUserLogin(deps)))
-	http.HandleFunc("/api/admin/config", requireAdmin(handlers.HandleAdminConfig(deps)))
+	http.HandleFunc("/api/auth/session", metrics.WrapRequestTiming(handlers.HandleUserSession(deps)))
-	http.HandleFunc("/api/admin/restart", requireAdmin(handlers.HandleAdminRestart(deps)))
+	http.HandleFunc("/api/auth/logout", metrics.WrapRequestTiming(handlers.HandleUserLogout(deps)))
-	http.HandleFunc("/api/admin/users", requireAdmin(handlers.HandleAdminUsers(deps)))
+	http.HandleFunc("/api/dm/history", metrics.WrapRequestTiming(handlers.HandleUserDMHistory(deps)))
-	http.HandleFunc("/api/admin/schedule", requireAdmin(handlers.HandleAdminSchedule(deps)))
+	http.HandleFunc("/api/dm/search", metrics.WrapRequestTiming(handlers.HandleUserDMSearch(deps)))
-	http.HandleFunc("/api/admin/schedule/overrides", requireAdmin(handlers.HandleAdminScheduleOverrides(deps)))
+	http.HandleFunc("/api/admin/login", metrics.WrapRequestTiming(handlers.HandleAdminLogin(deps)))
-	http.HandleFunc("/api/schedule", handlers.HandlePublicSchedule(deps))
+	http.HandleFunc("/api/admin/logout", metrics.WrapRequestTiming(handlers.HandleAdminLogout(deps)))
-	http.HandleFunc("/api/admin/media", requireAdmin(handlers.HandleAdminMedia(deps)))
+	http.HandleFunc("/api/admin/session", metrics.WrapRequestTiming(handlers.HandleAdminSession(deps)))
-	http.HandleFunc("/api/admin/media/uploads", requireAdmin(handlers.HandleAdminMediaUploads(deps)))
+	http.HandleFunc("/api/admin/overview", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminOverview(deps))))
-	http.HandleFunc("/api/admin/media/uploads/", requireAdmin(handlers.HandleAdminMediaUploads(deps)))
+	http.HandleFunc("/api/admin/playlist", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminPlaylist(deps))))
-	http.HandleFunc("/api/admin/media/", requireAdmin(handlers.HandleAdminMediaByID(deps)))
+	http.HandleFunc("/api/admin/moderation/logs", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminModerationLogs(deps))))
-	http.HandleFunc("/api/admin/chat-log/bulk", requireAdmin(handlers.HandleAdminChatLogBulk(deps)))
+	http.HandleFunc("/api/admin/moderation/actions", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminModerationAction(deps))))
-	http.HandleFunc("/api/admin/chat-log/export", requireAdmin(handlers.HandleAdminChatLogExport(deps)))
+	http.HandleFunc("/api/admin/analytics", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminAnalytics(deps))))
-	http.HandleFunc("/api/admin/chat-log/", requireAdmin(handlers.HandleAdminChatLogByID(deps)))
+	http.HandleFunc("/api/admin/system", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminSystemSummary(deps))))
-	http.HandleFunc("/api/admin/chat-log", requireAdmin(handlers.HandleAdminChatLog(deps)))
+	http.HandleFunc("/api/admin/config", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminConfig(deps))))
-	http.HandleFunc("/metrics", metrics.HandleMetrics(dbClient.DB, redisWrapper, hub, sessionStore, dbDriver, instanceID))
+	http.HandleFunc("/api/admin/restart", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminRestart(deps))))
-	http.HandleFunc("/health", metrics.HandleHealth())
+	http.HandleFunc("/api/admin/users", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminUsers(deps))))
-	http.HandleFunc("/", metrics.HandleNotFound())
+	http.HandleFunc("/api/admin/schedule", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminSchedule(deps))))
-
+	http.HandleFunc("/api/admin/schedule/overrides", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminScheduleOverrides(deps))))
-	port := config.ChatPort()
+	http.HandleFunc("/api/schedule", metrics.WrapRequestTiming(handlers.HandlePublicSchedule(deps)))
-	log.Printf("Chat service starting on :%s", port)
+	http.HandleFunc("/api/matomo", metrics.WrapRequestTiming(handlers.HandlePublicMatomo()))
-	if err := http.ListenAndServe(":"+port, nil); err != nil {
+	http.HandleFunc("/api/admin/media", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMedia(deps))))
-		log.Fatalf("Server failed: %v", err)
+	http.HandleFunc("/api/admin/media/uploads", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMediaUploads(deps))))
-	}
+	http.HandleFunc("/api/admin/media/uploads/", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMediaUploads(deps))))
+	http.HandleFunc("/api/admin/media/", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminMediaByID(deps))))
+	http.HandleFunc("/api/admin/chat-log/bulk", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminChatLogBulk(deps))))
+	http.HandleFunc("/api/admin/chat-log/export", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminChatLogExport(deps))))
+	http.HandleFunc("/api/admin/chat-log/", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminChatLogByID(deps))))
+	http.HandleFunc("/api/admin/chat-log", metrics.WrapRequestTiming(requireAdmin(handlers.HandleAdminChatLog(deps))))
+	http.HandleFunc("/metrics", metrics.HandleMetrics(dbClient.DB, redisWrapper, hub, sessionStore, dbDriver, instanceID))
+	http.HandleFunc("/health", metrics.WrapRequestTiming(metrics.HandleHealth()))
+	http.HandleFunc("/", metrics.WrapRequestTiming(metrics.HandleNotFound()))
+
+	port := config.ChatPort()
+	log.Printf("Chat service starting on :%s", port)
+	if err := http.ListenAndServe(":"+port, nil); err != nil {
+		log.Fatalf("Server failed: %v", err)
+	}
 }

backend/chat/src/media/media.go

@@ -1,385 +1,450 @@
-package media
+package media
-
+
-import (
+import (
-	"context"
+	"context"
-	"encoding/json"
+	"encoding/json"
-	"fmt"
+	"fmt"
-	"io"
+	"io"
-	"net/http"
+	"net/http"
-	"os"
+	"os"
-	"os/exec"
+	"os/exec"
-	"path/filepath"
+	"path/filepath"
-	"sort"
+	"sort"
-	"strconv"
+	"strconv"
-	"strings"
+	"strings"
-	"time"
+	"time"
-
+
-	"gorm.io/gorm"
+	"gorm.io/gorm"
-)
+)
-
+
-// FormatDuration converts seconds to HH:MM:SS string.
+// FormatDuration converts seconds to HH:MM:SS string.
-func FormatDuration(seconds int) string {
+func FormatDuration(seconds int) string {
-	if seconds < 0 {
+	if seconds < 0 {
-		seconds = 0
+		seconds = 0
-	}
+	}
-	hours := seconds / 3600
+	hours := seconds / 3600
-	minutes := (seconds % 3600) / 60
+	minutes := (seconds % 3600) / 60
-	remainingSeconds := seconds % 60
+	remainingSeconds := seconds % 60
-	return fmt.Sprintf("%02d:%02d:%02d", hours, minutes, remainingSeconds)
+	return fmt.Sprintf("%02d:%02d:%02d", hours, minutes, remainingSeconds)
-}
+}
-
+
-// NormalizationResult holds ffprobe validation output for admin uploads.
+// NormalizationResult holds ffprobe validation output for admin uploads.
-type NormalizationResult struct {
+type NormalizationResult struct {
-	Valid  bool     `json:"valid"`
+	Valid  bool     `json:"valid"`
-	Errors []string `json:"errors"`
+	Errors []string `json:"errors"`
-}
+}
-
+
-// ValidateNormalization runs ffprobe against a media file and checks
+// ValidateNormalization runs ffprobe against a media file and checks
-// conformance with the Linear Void normalization profile (ADR-001).
+// conformance with the Linear Void normalization profile (ADR-001).
-func ValidateNormalization(mediaPath string) NormalizationResult {
+func ValidateNormalization(mediaPath string) NormalizationResult {
-	result := NormalizationResult{Valid: true, Errors: []string{}}
+	result := NormalizationResult{Valid: true, Errors: []string{}}
-
+
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	defer cancel()
+	defer cancel()
-
+
-	out, err := exec.CommandContext(ctx,
+	out, err := exec.CommandContext(ctx,
-		"ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", mediaPath,
+		"ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", mediaPath,
-	).CombinedOutput()
+	).CombinedOutput()
-
+
-	if ctx.Err() == context.DeadlineExceeded {
+	if ctx.Err() == context.DeadlineExceeded {
-		return NormalizationResult{Valid: false, Errors: []string{"ffprobe timed out"}}
+		return NormalizationResult{Valid: false, Errors: []string{"ffprobe timed out"}}
-	}
+	}
-	if err != nil {
+	if err != nil {
-		return NormalizationResult{Valid: false, Errors: []string{fmt.Sprintf("ffprobe failed: %v (%s)", err, strings.TrimSpace(string(out)))}}
+		return NormalizationResult{Valid: false, Errors: []string{fmt.Sprintf("ffprobe failed: %v (%s)", err, strings.TrimSpace(string(out)))}}
-	}
+	}
-
+
-	var probe struct {
+	var probe struct {
-		Streams []struct {
+		Streams []struct {
-			CodecName  string `json:"codec_name"`
+			CodecName  string `json:"codec_name"`
-			CodecType  string `json:"codec_type"`
+			CodecType  string `json:"codec_type"`
-			Width      int    `json:"width"`
+			Width      int    `json:"width"`
-			Height     int    `json:"height"`
+			Height     int    `json:"height"`
-			RFrameRate string `json:"r_frame_rate"`
+			RFrameRate string `json:"r_frame_rate"`
-			PixFmt     string `json:"pix_fmt"`
+			PixFmt     string `json:"pix_fmt"`
-			SampleRate string `json:"sample_rate"`
+			SampleRate string `json:"sample_rate"`
-		} `json:"streams"`
+		} `json:"streams"`
-	}
+	}
-	if err := json.Unmarshal(out, &probe); err != nil {
+	if err := json.Unmarshal(out, &probe); err != nil {
-		return NormalizationResult{Valid: false, Errors: []string{"ffprobe JSON parse failed: " + err.Error()}}
+		return NormalizationResult{Valid: false, Errors: []string{"ffprobe JSON parse failed: " + err.Error()}}
-	}
+	}
-
+
-	var hasVideo, hasAudio bool
+	var hasVideo, hasAudio bool
-	for _, s := range probe.Streams {
+	for _, s := range probe.Streams {
-		switch s.CodecType {
+		switch s.CodecType {
-		case "video":
+		case "video":
-			hasVideo = true
+			hasVideo = true
-			if s.CodecName != "h264" {
+			if s.CodecName != "h264" {
-				result.Errors = append(result.Errors, fmt.Sprintf("video codec must be h264, got %s", s.CodecName))
+				result.Errors = append(result.Errors, fmt.Sprintf("video codec must be h264, got %s", s.CodecName))
-			}
+			}
-			if s.RFrameRate != "30/1" {
+			if s.RFrameRate != "30/1" {
-				result.Errors = append(result.Errors, fmt.Sprintf("framerate must be 30 fps constant, got %s", s.RFrameRate))
+				result.Errors = append(result.Errors, fmt.Sprintf("framerate must be 30 fps constant, got %s", s.RFrameRate))
-			}
+			}
-			if s.Width != 1280 && s.Width != 1920 {
+			if s.Width != 1280 && s.Width != 1920 {
-				result.Errors = append(result.Errors, fmt.Sprintf("width must be 1280 or 1920, got %d", s.Width))
+				result.Errors = append(result.Errors, fmt.Sprintf("width must be 1280 or 1920, got %d", s.Width))
-			}
+			}
-			if s.Height != 720 && s.Height != 1080 {
+			if s.Height != 720 && s.Height != 1080 {
-				result.Errors = append(result.Errors, fmt.Sprintf("height must be 720 or 1080, got %d", s.Height))
+				result.Errors = append(result.Errors, fmt.Sprintf("height must be 720 or 1080, got %d", s.Height))
-			}
+			}
-			if s.PixFmt != "yuv420p" {
+			if s.PixFmt != "yuv420p" {
-				result.Errors = append(result.Errors, fmt.Sprintf("pixel format must be yuv420p, got %s", s.PixFmt))
+				result.Errors = append(result.Errors, fmt.Sprintf("pixel format must be yuv420p, got %s", s.PixFmt))
-			}
+			}
-		case "audio":
+		case "audio":
-			hasAudio = true
+			hasAudio = true
-			if s.CodecName != "aac" {
+			if s.CodecName != "aac" {
-				result.Errors = append(result.Errors, fmt.Sprintf("audio codec must be aac, got %s", s.CodecName))
+				result.Errors = append(result.Errors, fmt.Sprintf("audio codec must be aac, got %s", s.CodecName))
-			}
+			}
-			if s.SampleRate != "48000" {
+			if s.SampleRate != "48000" {
-				result.Errors = append(result.Errors, fmt.Sprintf("sample rate must be 48000 Hz, got %s", s.SampleRate))
+				result.Errors = append(result.Errors, fmt.Sprintf("sample rate must be 48000 Hz, got %s", s.SampleRate))
-			}
+			}
-		}
+		}
-	}
+	}
-
+
-	if !hasVideo {
+	if !hasVideo {
-		result.Errors = append(result.Errors, "no video stream found")
+		result.Errors = append(result.Errors, "no video stream found")
-	}
+	}
-	if !hasAudio {
+	if !hasAudio {
-		result.Errors = append(result.Errors, "no audio stream found")
+		result.Errors = append(result.Errors, "no audio stream found")
-	}
+	}
-
+
-	if len(result.Errors) > 0 {
+	if len(result.Errors) > 0 {
-		result.Valid = false
+		result.Valid = false
-	}
+	}
-
+
-	return result
+	return result
-}
+}
-
+
-// ProbeDurationSeconds returns the duration of a media file in seconds.
+// ProbeDurationSeconds returns the duration of a media file in seconds.
-func ProbeDurationSeconds(mediaPath string) (int, error) {
+func ProbeDurationSeconds(mediaPath string) (int, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
-	defer cancel()
+	defer cancel()
-
+
-	out, err := exec.CommandContext(
+	out, err := exec.CommandContext(
-		ctx,
+		ctx,
-		"ffprobe",
+		"ffprobe",
-		"-v", "error",
+		"-v", "error",
-		"-show_entries", "format=duration",
+		"-show_entries", "format=duration",
-		"-of", "default=noprint_wrappers=1:nokey=1",
+		"-of", "default=noprint_wrappers=1:nokey=1",
-		mediaPath,
+		mediaPath,
-	).CombinedOutput()
+	).CombinedOutput()
-
+
-	if ctx.Err() == context.DeadlineExceeded {
+	if ctx.Err() == context.DeadlineExceeded {
-		return 0, fmt.Errorf("ffprobe timed out")
+		return 0, fmt.Errorf("ffprobe timed out")
-	}
+	}
-	if err != nil {
+	if err != nil {
-		return 0, fmt.Errorf("ffprobe failed: %w (%s)", err, strings.TrimSpace(string(out)))
+		return 0, fmt.Errorf("ffprobe failed: %w (%s)", err, strings.TrimSpace(string(out)))
-	}
+	}
-
+
-	rawDuration := strings.TrimSpace(string(out))
+	rawDuration := strings.TrimSpace(string(out))
-	if rawDuration == "" {
+	if rawDuration == "" {
-		return 0, fmt.Errorf("ffprobe returned empty duration")
+		return 0, fmt.Errorf("ffprobe returned empty duration")
-	}
+	}
-
+
-	secondsFloat, err := strconv.ParseFloat(rawDuration, 64)
+	secondsFloat, err := strconv.ParseFloat(rawDuration, 64)
-	if err != nil {
+	if err != nil {
-		return 0, fmt.Errorf("failed to parse duration %q: %w", rawDuration, err)
+		return 0, fmt.Errorf("failed to parse duration %q: %w", rawDuration, err)
-	}
+	}
-	if secondsFloat < 0 {
+	if secondsFloat < 0 {
-		secondsFloat = 0
+		secondsFloat = 0
-	}
+	}
-
+
-	seconds := int(secondsFloat + 0.5)
+	seconds := int(secondsFloat + 0.5)
-	if secondsFloat > 0 && seconds == 0 {
+	if secondsFloat > 0 && seconds == 0 {
-		seconds = 1
+		seconds = 1
-	}
+	}
-
+
-	return seconds, nil
+	return seconds, nil
-}
+}
-
+
-// DetectMime reads the first 512 bytes of a file to detect its MIME type.
+// Media status values (ADR-006 media library states).
-func DetectMime(filePath string) (string, error) {
+const (
-	f, err := os.Open(filePath)
+	StatusReady               = "ready"
-	if err != nil {
+	StatusNeedsNormalization  = "needs_normalization"
-		return "", err
+	StatusNormalizing         = "normalizing"
-	}
+	StatusNormalizationFailed = "normalization_failed"
-	defer f.Close()
+)
-
+
-	head := make([]byte, 512)
+// runCommand executes an external command and returns its combined output on failure.
-	n, err := f.Read(head)
+// It is a package variable so tests can substitute a stub.
-	if err != nil && err != io.EOF {
+var runCommand = func(ctx context.Context, name string, args ...string) error {
-		return "", err
+	out, err := exec.CommandContext(ctx, name, args...).CombinedOutput()
-	}
+	if err != nil {
-
+		return fmt.Errorf("%s failed: %v (%s)", name, err, strings.TrimSpace(string(out)))
-	return strings.SplitN(http.DetectContentType(head[:n]), ";", 2)[0], nil
+	}
-}
+	return nil
-
+}
-// IsAllowedExtension checks if the file extension is a supported video format.
+
-func IsAllowedExtension(fileName string) bool {
+// normalizationArgs builds the ffmpeg arguments for the Linear Void normalization profile.
-	ext := strings.ToLower(filepath.Ext(fileName))
+func normalizationArgs(srcPath, dstPath string) []string {
-	switch ext {
+	return []string{
-	case ".mp4", ".mov", ".mkv", ".webm", ".m4v", ".ts":
+		"-y",
-		return true
+		"-i", srcPath,
-	default:
+		"-map", "0:v:0", "-map", "0:a:0?",
-		return false
+		"-vf", "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p",
-	}
+		"-c:v", "libx264", "-preset", "medium", "-crf", "21",
-}
+		"-pix_fmt", "yuv420p",
-
+		"-r", "30", "-g", "60", "-keyint_min", "60", "-sc_threshold", "0",
-// IsAllowedMime checks if the MIME type is a supported video type.
+		"-c:a", "aac", "-b:a", "160k", "-ar", "48000", "-ac", "2",
-func IsAllowedMime(mime string) bool {
+		"-avoid_negative_ts", "make_zero", "-max_muxing_queue_size", "1024",
-	mime = strings.TrimSpace(strings.ToLower(mime))
+		"-movflags", "+faststart",
-	if mime == "" {
+		dstPath,
-		return true
+	}
-	}
+}
-	if strings.HasPrefix(mime, "video/") {
+
-		return true
+// normalizeVideo transcodes srcPath to the Linear Void normalization profile,
-	}
+// re-verifies the output with ffprobe, and returns its duration (seconds) and size (bytes).
-	return mime == "application/octet-stream"
+func normalizeVideo(srcPath, dstPath string) (int, int64, error) {
-}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Hour)
-
+	defer cancel()
-// UniqueTargetPath returns a unique file path in mediaDir, appending -N if needed.
+
-func UniqueTargetPath(mediaDir, fileName string) string {
+	if err := runCommand(ctx, "ffmpeg", normalizationArgs(srcPath, dstPath)...); err != nil {
-	baseName := filepath.Base(fileName)
+		return 0, 0, err
-	ext := filepath.Ext(baseName)
+	}
-	nameOnly := strings.TrimSuffix(baseName, ext)
+
-	candidate := filepath.Join(mediaDir, baseName)
+	if res := ValidateNormalization(dstPath); !res.Valid {
-
+		return 0, 0, fmt.Errorf("normalized output failed validation: %s", strings.Join(res.Errors, "; "))
-	for i := 1; ; i++ {
+	}
-		if _, err := os.Stat(candidate); os.IsNotExist(err) {
+
-			return candidate
+	duration, err := ProbeDurationSeconds(dstPath)
-		}
+	if err != nil {
-		candidate = filepath.Join(mediaDir, fmt.Sprintf("%s-%d%s", nameOnly, i, ext))
+		return 0, 0, fmt.Errorf("probe duration failed: %w", err)
-	}
+	}
-}
+
-
+	info, err := os.Stat(dstPath)
-// FileEntry represents a media file for API responses.
+	if err != nil {
-type FileEntry struct {
+		return 0, 0, fmt.Errorf("stat output failed: %w", err)
-	ID              uint   `json:"id"`
+	}
-	Name            string `json:"name"`
+
-	OriginalName    string `json:"originalName"`
+	return duration, info.Size(), nil
-	Path            string `json:"path"`
+}
-	Size            int64  `json:"size"`
+
-	DurationSeconds int    `json:"durationSeconds"`
+// NormalizeVideo is the injectable normalization entry point.
-	Runtime         string `json:"runtime"`
+var NormalizeVideo = normalizeVideo
-	Status          string `json:"status"`
+
-	Title           string `json:"title"`
+// DetectMime reads the first 512 bytes of a file to detect its MIME type.
-	Tags            string `json:"tags"`
+func DetectMime(filePath string) (string, error) {
-	UploadedAt      string `json:"uploadedAt"`
+	f, err := os.Open(filePath)
-	ModifiedAt      string `json:"modifiedAt"`
+	if err != nil {
-}
+		return "", err
-
+	}
-// MediaRecord is the interface for media DB records.
+	defer f.Close()
-type MediaRecord interface {
+
-	GetID() uint
+	head := make([]byte, 512)
-	GetFilename() string
+	n, err := f.Read(head)
-	GetOriginalName() string
+	if err != nil && err != io.EOF {
-	GetPath() string
+		return "", err
-	GetSizeBytes() int64
+	}
-	GetDurationSeconds() int
+
-	GetStatus() string
+	return strings.SplitN(http.DetectContentType(head[:n]), ";", 2)[0], nil
-	GetTitle() string
+}
-	GetTags() string
+
-	GetUploadedAt() time.Time
+// IsAllowedExtension checks if the file extension is a supported video format.
-	GetUpdatedAt() time.Time
+func IsAllowedExtension(fileName string) bool {
-}
+	ext := strings.ToLower(filepath.Ext(fileName))
-
+	switch ext {
-// ListFiles returns all media files sorted by upload date descending.
+	case ".mp4", ".mov", ".mkv", ".webm", ".m4v", ".ts":
-func ListFiles(db *gorm.DB) ([]FileEntry, error) {
+		return true
-	type record struct {
+	default:
-		ID              uint
+		return false
-		Filename        string
+	}
-		OriginalName    string
+}
-		Path            string
+
-		SizeBytes       int64
+// IsAllowedMime checks if the MIME type is a supported video type.
-		DurationSeconds int
+func IsAllowedMime(mime string) bool {
-		Status          string
+	mime = strings.TrimSpace(strings.ToLower(mime))
-		Title           string
+	if mime == "" {
-		Tags            string
+		return true
-		UploadedAt      time.Time
+	}
-		UpdatedAt       time.Time
+	if strings.HasPrefix(mime, "video/") {
-	}
+		return true
-
+	}
-	var records []record
+	return mime == "application/octet-stream"
-	if err := db.Table("media").Order("uploaded_at desc").Find(&records).Error; err != nil {
+}
-		return nil, err
+
-	}
+// UniqueTargetPath returns a unique file path in mediaDir, appending -N if needed.
-
+func UniqueTargetPath(mediaDir, fileName string) string {
-	files := make([]FileEntry, 0, len(records))
+	baseName := filepath.Base(fileName)
-	for _, r := range records {
+	ext := filepath.Ext(baseName)
-		files = append(files, FileEntry{
+	nameOnly := strings.TrimSuffix(baseName, ext)
-			ID:              r.ID,
+	candidate := filepath.Join(mediaDir, baseName)
-			Name:            r.Filename,
+
-			OriginalName:    r.OriginalName,
+	for i := 1; ; i++ {
-			Path:            r.Path,
+		if _, err := os.Stat(candidate); os.IsNotExist(err) {
-			Size:            r.SizeBytes,
+			return candidate
-			DurationSeconds: r.DurationSeconds,
+		}
-			Runtime:         FormatDuration(r.DurationSeconds),
+		candidate = filepath.Join(mediaDir, fmt.Sprintf("%s-%d%s", nameOnly, i, ext))
-			Status:          r.Status,
+	}
-			Title:           r.Title,
+}
-			Tags:            r.Tags,
+
-			UploadedAt:      r.UploadedAt.UTC().Format(time.RFC3339),
+// FileEntry represents a media file for API responses.
-			ModifiedAt:      r.UpdatedAt.UTC().Format(time.RFC3339),
+type FileEntry struct {
-		})
+	ID              uint   `json:"id"`
-	}
+	Name            string `json:"name"`
-
+	OriginalName    string `json:"originalName"`
-	sort.Slice(files, func(i, j int) bool {
+	Path            string `json:"path"`
-		if files[i].UploadedAt == files[j].UploadedAt {
+	Size            int64  `json:"size"`
-			return files[i].Name < files[j].Name
+	DurationSeconds int    `json:"durationSeconds"`
-		}
+	Runtime         string `json:"runtime"`
-		return files[i].UploadedAt > files[j].UploadedAt
+	Status          string `json:"status"`
-	})
+	Title           string `json:"title"`
-
+	Tags            string `json:"tags"`
-	return files, nil
+	UploadedAt      string `json:"uploadedAt"`
-}
+	ModifiedAt      string `json:"modifiedAt"`
-
+}
-// ParsePlaylistEntries parses playlist content into schedule entries.
+
-type ScheduleEntry struct {
+// MediaRecord is the interface for media DB records.
-	Index           int    `json:"index"`
+type MediaRecord interface {
-	Path            string `json:"path"`
+	GetID() uint
-	Label           string `json:"label"`
+	GetFilename() string
-	DurationSeconds int    `json:"durationSeconds"`
+	GetOriginalName() string
-	Runtime         string `json:"runtime"`
+	GetPath() string
-	Status          string `json:"status"`
+	GetSizeBytes() int64
-	Title           string `json:"title"`
+	GetDurationSeconds() int
-}
+	GetStatus() string
-
+	GetTitle() string
-// ParsePlaylist parses playlist text content into entries.
+	GetTags() string
-func ParsePlaylist(content string) []ScheduleEntry {
+	GetUploadedAt() time.Time
-	entries := []ScheduleEntry{}
+	GetUpdatedAt() time.Time
-	lines := strings.Split(content, "\n")
+}
-	for _, rawLine := range lines {
+
-		line := strings.TrimSpace(rawLine)
+// ListFiles returns all media files sorted by upload date descending.
-		if line == "" || strings.HasPrefix(line, "#") {
+func ListFiles(db *gorm.DB) ([]FileEntry, error) {
-			continue
+	type record struct {
-		}
+		ID              uint
-
+		Filename        string
-		if strings.HasPrefix(line, "file ") {
+		OriginalName    string
-			line = strings.TrimSpace(strings.TrimPrefix(line, "file "))
+		Path            string
-			line = strings.Trim(line, "'\"")
+		SizeBytes       int64
-		}
+		DurationSeconds int
-
+		Status          string
-		entries = append(entries, ScheduleEntry{
+		Title           string
-			Index: len(entries) + 1,
+		Tags            string
-			Path:  line,
+		UploadedAt      time.Time
-			Label: filepath.Base(line),
+		UpdatedAt       time.Time
-		})
+	}
-	}
+
-
+	var records []record
-	return entries
+	if err := db.Table("media").Order("uploaded_at desc").Find(&records).Error; err != nil {
-}
+		return nil, err
-
+	}
-// UploadSessionDir returns the directory for an upload session's chunks.
+
-func UploadSessionDir(mediaDir, uploadID string) string {
+	files := make([]FileEntry, 0, len(records))
-	return filepath.Join(mediaDir, ".uploads", uploadID)
+	for _, r := range records {
-}
+		files = append(files, FileEntry{
-
+			ID:              r.ID,
-// UploadSessionMetaPath returns the path to the session metadata file.
+			Name:            r.Filename,
-func UploadSessionMetaPath(mediaDir, uploadID string) string {
+			OriginalName:    r.OriginalName,
-	return filepath.Join(UploadSessionDir(mediaDir, uploadID), "session.json")
+			Path:            r.Path,
-}
+			Size:            r.SizeBytes,
-
+			DurationSeconds: r.DurationSeconds,
-// UploadChunkPath returns the path for a specific chunk file.
+			Runtime:         FormatDuration(r.DurationSeconds),
-func UploadChunkPath(mediaDir, uploadID string, chunkIndex int) string {
+			Status:          r.Status,
-	return filepath.Join(UploadSessionDir(mediaDir, uploadID), fmt.Sprintf("chunk-%06d.part", chunkIndex))
+			Title:           r.Title,
-}
+			Tags:            r.Tags,
-
+			UploadedAt:      r.UploadedAt.UTC().Format(time.RFC3339),
-// CountUploadedChunks counts how many chunks exist for a session.
+			ModifiedAt:      r.UpdatedAt.UTC().Format(time.RFC3339),
-func CountUploadedChunks(mediaDir, uploadID string, totalChunks int) int {
+		})
-	uploaded := 0
+	}
-	for i := 0; i < totalChunks; i++ {
+
-		if _, err := os.Stat(UploadChunkPath(mediaDir, uploadID, i)); err == nil {
+	sort.Slice(files, func(i, j int) bool {
-			uploaded++
+		if files[i].UploadedAt == files[j].UploadedAt {
-		}
+			return files[i].Name < files[j].Name
-	}
+		}
-	return uploaded
+		return files[i].UploadedAt > files[j].UploadedAt
-}
+	})
-
+
-// ValidateUploadID checks that an upload ID is a valid hex string of appropriate length.
+	return files, nil
-func ValidateUploadID(uploadID string) bool {
+}
-	if len(uploadID) < 16 || len(uploadID) > 128 {
+
-		return false
+// ParsePlaylistEntries parses playlist content into schedule entries.
-	}
+type ScheduleEntry struct {
-	for _, r := range uploadID {
+	Index           int    `json:"index"`
-		if (r < 'a' || r > 'f') && (r < '0' || r > '9') {
+	Path            string `json:"path"`
-			return false
+	Label           string `json:"label"`
-		}
+	DurationSeconds int    `json:"durationSeconds"`
-	}
+	Runtime         string `json:"runtime"`
-	return true
+	Status          string `json:"status"`
-}
+	Title           string `json:"title"`
-
+}
-// GetMediaIDFromPath extracts a media ID from a URL path like /api/admin/media/123.
+
-func GetMediaIDFromPath(path, prefix string) (uint, error) {
+// ParsePlaylist parses playlist text content into entries.
-	if !strings.HasPrefix(path, prefix) {
+func ParsePlaylist(content string) []ScheduleEntry {
-		return 0, fmt.Errorf("invalid media path")
+	entries := []ScheduleEntry{}
-	}
+	lines := strings.Split(content, "\n")
-	idPart := strings.TrimPrefix(path, prefix)
+	for _, rawLine := range lines {
-	idPart = strings.TrimSpace(idPart)
+		line := strings.TrimSpace(rawLine)
-	if idPart == "" || strings.Contains(idPart, "/") {
+		if line == "" || strings.HasPrefix(line, "#") {
-		return 0, fmt.Errorf("invalid media id")
+			continue
-	}
+		}
-
+
-	id, err := strconv.ParseUint(idPart, 10, 64)
+		if strings.HasPrefix(line, "file ") {
-	if err != nil || id == 0 {
+			line = strings.TrimSpace(strings.TrimPrefix(line, "file "))
-		return 0, fmt.Errorf("invalid media id")
+			line = strings.Trim(line, "'\"")
-	}
+		}
-
+
-	return uint(id), nil
+		entries = append(entries, ScheduleEntry{
+			Index: len(entries) + 1,
+			Path:  line,
+			Label: filepath.Base(line),
+		})
+	}
+
+	return entries
+}
+
+// UploadSessionDir returns the directory for an upload session's chunks.
+func UploadSessionDir(mediaDir, uploadID string) string {
+	return filepath.Join(mediaDir, ".uploads", uploadID)
+}
+
+// UploadSessionMetaPath returns the path to the session metadata file.
+func UploadSessionMetaPath(mediaDir, uploadID string) string {
+	return filepath.Join(UploadSessionDir(mediaDir, uploadID), "session.json")
+}
+
+// UploadChunkPath returns the path for a specific chunk file.
+func UploadChunkPath(mediaDir, uploadID string, chunkIndex int) string {
+	return filepath.Join(UploadSessionDir(mediaDir, uploadID), fmt.Sprintf("chunk-%06d.part", chunkIndex))
+}
+
+// CountUploadedChunks counts how many chunks exist for a session.
+func CountUploadedChunks(mediaDir, uploadID string, totalChunks int) int {
+	uploaded := 0
+	for i := 0; i < totalChunks; i++ {
+		if _, err := os.Stat(UploadChunkPath(mediaDir, uploadID, i)); err == nil {
+			uploaded++
+		}
+	}
+	return uploaded
+}
+
+// ValidateUploadID checks that an upload ID is a valid hex string of appropriate length.
+func ValidateUploadID(uploadID string) bool {
+	if len(uploadID) < 16 || len(uploadID) > 128 {
+		return false
+	}
+	for _, r := range uploadID {
+		if (r < 'a' || r > 'f') && (r < '0' || r > '9') {
+			return false
+		}
+	}
+	return true
+}
+
+// GetMediaIDFromPath extracts a media ID from a URL path like /api/admin/media/123.
+func GetMediaIDFromPath(path, prefix string) (uint, error) {
+	if !strings.HasPrefix(path, prefix) {
+		return 0, fmt.Errorf("invalid media path")
+	}
+	idPart := strings.TrimPrefix(path, prefix)
+	idPart = strings.TrimSpace(idPart)
+	if idPart == "" || strings.Contains(idPart, "/") {
+		return 0, fmt.Errorf("invalid media id")
+	}
+
+	id, err := strconv.ParseUint(idPart, 10, 64)
+	if err != nil || id == 0 {
+		return 0, fmt.Errorf("invalid media id")
+	}
+
+	return uint(id), nil
 }

backend/chat/src/media/media_test.go

@@ -1,204 +1,246 @@
-package media
+package media
-
+
-import (
+import (
-	"path/filepath"
+	"context"
-	"testing"
+	"fmt"
-)
+	"path/filepath"
-
+	"strings"
-func TestFormatDuration(t *testing.T) {
+	"testing"
-	tests := []struct {
+)
-		name     string
+
-		seconds  int
+func TestFormatDuration(t *testing.T) {
-		expected string
+	tests := []struct {
-	}{
+		name     string
-		{"zero", 0, "00:00:00"},
+		seconds  int
-		{"one second", 1, "00:00:01"},
+		expected string
-		{"one minute", 60, "00:01:00"},
+	}{
-		{"one hour", 3600, "01:00:00"},
+		{"zero", 0, "00:00:00"},
-		{"mixed", 3661, "01:01:01"},
+		{"one second", 1, "00:00:01"},
-		{"large", 86399, "23:59:59"},
+		{"one minute", 60, "00:01:00"},
-		{"negative", -5, "00:00:00"},
+		{"one hour", 3600, "01:00:00"},
-	}
+		{"mixed", 3661, "01:01:01"},
-
+		{"large", 86399, "23:59:59"},
-	for _, tt := range tests {
+		{"negative", -5, "00:00:00"},
-		t.Run(tt.name, func(t *testing.T) {
+	}
-			if got := FormatDuration(tt.seconds); got != tt.expected {
+
-				t.Errorf("FormatDuration(%d) = %q, want %q", tt.seconds, got, tt.expected)
+	for _, tt := range tests {
-			}
+		t.Run(tt.name, func(t *testing.T) {
-		})
+			if got := FormatDuration(tt.seconds); got != tt.expected {
-	}
+				t.Errorf("FormatDuration(%d) = %q, want %q", tt.seconds, got, tt.expected)
-}
+			}
-
+		})
-func TestIsAllowedExtension(t *testing.T) {
+	}
-	tests := []struct {
+}
-		name     string
+
-		expected bool
+func TestIsAllowedExtension(t *testing.T) {
-	}{
+	tests := []struct {
-		{"video.mp4", true},
+		name     string
-		{"video.mov", true},
+		expected bool
-		{"video.mkv", true},
+	}{
-		{"video.webm", true},
+		{"video.mp4", true},
-		{"video.m4v", true},
+		{"video.mov", true},
-		{"video.ts", true},
+		{"video.mkv", true},
-		{"video.MP4", true},
+		{"video.webm", true},
-		{"video.avi", false},
+		{"video.m4v", true},
-		{"video.flv", false},
+		{"video.ts", true},
-		{"video.wmv", false},
+		{"video.MP4", true},
-		{"video", false},
+		{"video.avi", false},
-		{"", false},
+		{"video.flv", false},
-	}
+		{"video.wmv", false},
-
+		{"video", false},
-	for _, tt := range tests {
+		{"", false},
-		t.Run(tt.name, func(t *testing.T) {
+	}
-			if got := IsAllowedExtension(tt.name); got != tt.expected {
+
-				t.Errorf("IsAllowedExtension(%q) = %v, want %v", tt.name, got, tt.expected)
+	for _, tt := range tests {
-			}
+		t.Run(tt.name, func(t *testing.T) {
-		})
+			if got := IsAllowedExtension(tt.name); got != tt.expected {
-	}
+				t.Errorf("IsAllowedExtension(%q) = %v, want %v", tt.name, got, tt.expected)
-}
+			}
-
+		})
-func TestIsAllowedMime(t *testing.T) {
+	}
-	tests := []struct {
+}
-		mime     string
+
-		expected bool
+func TestIsAllowedMime(t *testing.T) {
-	}{
+	tests := []struct {
-		{"video/mp4", true},
+		mime     string
-		{"video/quicktime", true},
+		expected bool
-		{"video/x-matroska", true},
+	}{
-		{"video/webm", true},
+		{"video/mp4", true},
-		{"application/octet-stream", true},
+		{"video/quicktime", true},
-		{"", true},
+		{"video/x-matroska", true},
-		{"image/jpeg", false},
+		{"video/webm", true},
-		{"audio/mpeg", false},
+		{"application/octet-stream", true},
-		{"text/plain", false},
+		{"", true},
-	}
+		{"image/jpeg", false},
-
+		{"audio/mpeg", false},
-	for _, tt := range tests {
+		{"text/plain", false},
-		t.Run(tt.mime, func(t *testing.T) {
+	}
-			if got := IsAllowedMime(tt.mime); got != tt.expected {
+
-				t.Errorf("IsAllowedMime(%q) = %v, want %v", tt.mime, got, tt.expected)
+	for _, tt := range tests {
-			}
+		t.Run(tt.mime, func(t *testing.T) {
-		})
+			if got := IsAllowedMime(tt.mime); got != tt.expected {
-	}
+				t.Errorf("IsAllowedMime(%q) = %v, want %v", tt.mime, got, tt.expected)
-}
+			}
-
+		})
-func TestValidateUploadID(t *testing.T) {
+	}
-	tests := []struct {
+}
-		id       string
+
-		expected bool
+func TestValidateUploadID(t *testing.T) {
-	}{
+	tests := []struct {
-		{"abcdef0123456789", true},           // 16 hex chars
+		id       string
-		{"abcdef0123456789abcdef0123456789", true}, // 32 hex chars
+		expected bool
-		{"abc", false},                        // too short
+	}{
-		{"abcdef012345678", false},            // 15 chars (too short)
+		{"abcdef0123456789", true},           // 16 hex chars
-		{"abcdef0123456789g", false},          // non-hex char
+		{"abcdef0123456789abcdef0123456789", true}, // 32 hex chars
-		{"ABCDEF0123456789", false},           // uppercase (not allowed)
+		{"abc", false},                        // too short
-		{"", false},
+		{"abcdef012345678", false},            // 15 chars (too short)
-	}
+		{"abcdef0123456789g", false},          // non-hex char
-
+		{"ABCDEF0123456789", false},           // uppercase (not allowed)
-	for _, tt := range tests {
+		{"", false},
-		t.Run(tt.id, func(t *testing.T) {
+	}
-			if got := ValidateUploadID(tt.id); got != tt.expected {
+
-				t.Errorf("ValidateUploadID(%q) = %v, want %v", tt.id, got, tt.expected)
+	for _, tt := range tests {
-			}
+		t.Run(tt.id, func(t *testing.T) {
-		})
+			if got := ValidateUploadID(tt.id); got != tt.expected {
-	}
+				t.Errorf("ValidateUploadID(%q) = %v, want %v", tt.id, got, tt.expected)
-}
+			}
-
+		})
-func TestParsePlaylist(t *testing.T) {
+	}
-	tests := []struct {
+}
-		name     string
+
-		content  string
+func TestParsePlaylist(t *testing.T) {
-		expected int
+	tests := []struct {
-		first    string
+		name     string
-	}{
+		content  string
-		{
+		expected int
-			name:     "simple",
+		first    string
-			content:  "/videos/video1.mp4\n/videos/video2.mp4\n",
+	}{
-			expected: 2,
+		{
-			first:    "/videos/video1.mp4",
+			name:     "simple",
-		},
+			content:  "/videos/video1.mp4\n/videos/video2.mp4\n",
-		{
+			expected: 2,
-			name:     "with file prefix",
+			first:    "/videos/video1.mp4",
-			content:  "file /videos/video1.mp4\nfile '/videos/video2.mp4'\n",
+		},
-			expected: 2,
+		{
-			first:    "/videos/video1.mp4",
+			name:     "with file prefix",
-		},
+			content:  "file /videos/video1.mp4\nfile '/videos/video2.mp4'\n",
-		{
+			expected: 2,
-			name:     "with comments and blanks",
+			first:    "/videos/video1.mp4",
-			content:  "# comment\n\n/videos/video1.mp4\n\n# another comment\n/videos/video2.mp4\n",
+		},
-			expected: 2,
+		{
-			first:    "/videos/video1.mp4",
+			name:     "with comments and blanks",
-		},
+			content:  "# comment\n\n/videos/video1.mp4\n\n# another comment\n/videos/video2.mp4\n",
-		{
+			expected: 2,
-			name:     "empty",
+			first:    "/videos/video1.mp4",
-			content:  "",
+		},
-			expected: 0,
+		{
-		},
+			name:     "empty",
-		{
+			content:  "",
-			name:     "only comments",
+			expected: 0,
-			content:  "# comment\n# another\n",
+		},
-			expected: 0,
+		{
-		},
+			name:     "only comments",
-	}
+			content:  "# comment\n# another\n",
-
+			expected: 0,
-	for _, tt := range tests {
+		},
-		t.Run(tt.name, func(t *testing.T) {
+	}
-			entries := ParsePlaylist(tt.content)
+
-			if len(entries) != tt.expected {
+	for _, tt := range tests {
-				t.Errorf("ParsePlaylist() len = %d, want %d", len(entries), tt.expected)
+		t.Run(tt.name, func(t *testing.T) {
-			}
+			entries := ParsePlaylist(tt.content)
-			if tt.expected > 0 && entries[0].Path != tt.first {
+			if len(entries) != tt.expected {
-				t.Errorf("ParsePlaylist()[0].Path = %q, want %q", entries[0].Path, tt.first)
+				t.Errorf("ParsePlaylist() len = %d, want %d", len(entries), tt.expected)
-			}
+			}
-			// Check indices
+			if tt.expected > 0 && entries[0].Path != tt.first {
-			for i, e := range entries {
+				t.Errorf("ParsePlaylist()[0].Path = %q, want %q", entries[0].Path, tt.first)
-				if e.Index != i+1 {
+			}
-					t.Errorf("ParsePlaylist()[%d].Index = %d, want %d", i, e.Index, i+1)
+			// Check indices
-				}
+			for i, e := range entries {
-			}
+				if e.Index != i+1 {
-		})
+					t.Errorf("ParsePlaylist()[%d].Index = %d, want %d", i, e.Index, i+1)
-	}
+				}
-}
+			}
-
+		})
-func TestGetMediaIDFromPath(t *testing.T) {
+	}
-	tests := []struct {
+}
-		path      string
+
-		prefix    string
+func TestGetMediaIDFromPath(t *testing.T) {
-		expected  uint
+	tests := []struct {
-		expectErr bool
+		path      string
-	}{
+		prefix    string
-		{"/api/admin/media/123", "/api/admin/media/", 123, false},
+		expected  uint
-		{"/api/admin/media/1", "/api/admin/media/", 1, false},
+		expectErr bool
-		{"/api/admin/media/", "/api/admin/media/", 0, true},
+	}{
-		{"/api/admin/media/abc", "/api/admin/media/", 0, true},
+		{"/api/admin/media/123", "/api/admin/media/", 123, false},
-		{"/api/admin/media/0", "/api/admin/media/", 0, true},
+		{"/api/admin/media/1", "/api/admin/media/", 1, false},
-		{"/other/path", "/api/admin/media/", 0, true},
+		{"/api/admin/media/", "/api/admin/media/", 0, true},
-	}
+		{"/api/admin/media/abc", "/api/admin/media/", 0, true},
-
+		{"/api/admin/media/0", "/api/admin/media/", 0, true},
-	for _, tt := range tests {
+		{"/other/path", "/api/admin/media/", 0, true},
-		t.Run(tt.path, func(t *testing.T) {
+	}
-			id, err := GetMediaIDFromPath(tt.path, tt.prefix)
+
-			if tt.expectErr && err == nil {
+	for _, tt := range tests {
-				t.Errorf("GetMediaIDFromPath(%q) expected error, got nil", tt.path)
+		t.Run(tt.path, func(t *testing.T) {
-			}
+			id, err := GetMediaIDFromPath(tt.path, tt.prefix)
-			if !tt.expectErr && err != nil {
+			if tt.expectErr && err == nil {
-				t.Errorf("GetMediaIDFromPath(%q) error = %v", tt.path, err)
+				t.Errorf("GetMediaIDFromPath(%q) expected error, got nil", tt.path)
-			}
+			}
-			if id != tt.expected {
+			if !tt.expectErr && err != nil {
-				t.Errorf("GetMediaIDFromPath(%q) = %d, want %d", tt.path, id, tt.expected)
+				t.Errorf("GetMediaIDFromPath(%q) error = %v", tt.path, err)
-			}
+			}
-		})
+			if id != tt.expected {
-	}
+				t.Errorf("GetMediaIDFromPath(%q) = %d, want %d", tt.path, id, tt.expected)
-}
+			}
-
+		})
-func TestUniqueTargetPath(t *testing.T) {
+	}
-	// Test that the function returns a path with the mediaDir prefix
+}
-	// and the correct filename. We can't easily test collision behavior
+
-	// without filesystem setup, but we can verify the basic path.
+func TestUniqueTargetPath(t *testing.T) {
-	expected := filepath.Join("/tmp/media", "video.mp4")
+	// Test that the function returns a path with the mediaDir prefix
-	path := UniqueTargetPath("/tmp/media", "video.mp4")
+	// and the correct filename. We can't easily test collision behavior
-	if path != expected {
+	// without filesystem setup, but we can verify the basic path.
-		t.Errorf("UniqueTargetPath() = %q, want %q", path, expected)
+	expected := filepath.Join("/tmp/media", "video.mp4")
-	}
+	path := UniqueTargetPath("/tmp/media", "video.mp4")
+	if path != expected {
+		t.Errorf("UniqueTargetPath() = %q, want %q", path, expected)
+	}
+}
+
+func TestNormalizationArgs(t *testing.T) {
+	args := normalizationArgs("/in/movie.mov", "/out/movie.normalized.mp4")
+	joined := strings.Join(args, " ")
+	for _, want := range []string{
+		"-map 0:v:0",
+		"-map 0:a:0?",
+		"-c:v libx264",
+		"-r 30",
+		"-g 60",
+		"-keyint_min 60",
+		"-pix_fmt yuv420p",
+		"-c:a aac",
+		"-ar 48000",
+		"-ac 2",
+		"-avoid_negative_ts make_zero",
+		"/out/movie.normalized.mp4",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("normalization args missing %q: %v", want, args)
+		}
+	}
+}
+
+func TestNormalizeVideo_FFmpegError(t *testing.T) {
+	origRun := runCommand
+	t.Cleanup(func() { runCommand = origRun })
+
+	runCommand = func(ctx context.Context, name string, args ...string) error {
+		if name != "ffmpeg" {
+			t.Errorf("runCommand name = %q, want ffmpeg", name)
+		}
+		return fmt.Errorf("simulated ffmpeg failure")
+	}
+
+	if _, _, err := normalizeVideo("/in/a.mov", "/out/a.normalized.mp4"); err == nil {
+		t.Fatal("expected error when ffmpeg fails")
+	}
 }

backend/chat/src/metrics/metrics.go

@@ -1,128 +1,278 @@
-package metrics
+package metrics
-
+
-import (
+import (
-	"context"
+	"context"
-	"fmt"
+	"fmt"
-	"net/http"
+	"math"
-	"strconv"
+	"net/http"
-	"strings"
+	"strconv"
-	"time"
+	"strings"
-
+	"sync"
-	"gorm.io/gorm"
+	"time"
-
+
-	"chat/src/auth"
+	"gorm.io/gorm"
-	"chat/src/db"
+
-	"chat/src/ws"
+	"chat/src/auth"
-)
+	"chat/src/db"
-
+	"chat/src/ws"
-// HandleMetrics returns Prometheus-format metrics for the chat service.
+)
-func HandleMetrics(gormDB *gorm.DB, redis db.RedisClient, hub *ws.Hub, sessionStore *auth.SessionStore, dbDriver, instanceID string) http.HandlerFunc {
+
-	return func(w http.ResponseWriter, r *http.Request) {
+var requestDurationBuckets = []float64{0.05, 0.1, 0.25, 0.5, 1, 2, 5}
-		if r.Method != http.MethodGet {
+
-			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+var chatRequestDurationHistogram = newRequestDurationHistogram(requestDurationBuckets)
-			return
+
-		}
+type requestDurationHistogram struct {
-
+	mu     sync.Mutex
-		var storedMessages int64
+	buckets []float64
-		if gormDB != nil {
+	counts  []uint64
-			_ = gormDB.Model(&db.Message{}).Count(&storedMessages).Error
+	sum     float64
-		}
+	total   uint64
-
+}
-		var moderationActions int64
+
-		if gormDB != nil {
+func newRequestDurationHistogram(buckets []float64) *requestDurationHistogram {
-			_ = gormDB.Model(&db.ModerationLog{}).Count(&moderationActions).Error
+	return &requestDurationHistogram{
-		}
+		buckets: append([]float64(nil), buckets...),
-
+		counts:  make([]uint64, len(buckets)+1),
-		redisEnabled := 0
+	}
-		redisUp := 0
+}
-		redisClients := 0
+
-		if redis != nil {
+func (h *requestDurationHistogram) observe(durationSeconds float64) {
-			redisEnabled = 1
+	h.mu.Lock()
-			if err := redis.Ping(context.Background()); err == nil {
+	defer h.mu.Unlock()
-				redisUp = 1
+
-				if info, err := redis.Info(context.Background(), "clients"); err == nil {
+	h.total++
-					for _, line := range strings.Split(info, "\n") {
+	h.sum += durationSeconds
-						if strings.HasPrefix(line, "connected_clients:") {
+	for index, bucket := range h.buckets {
-							if value, err := strconv.Atoi(strings.TrimSpace(strings.TrimPrefix(line, "connected_clients:"))); err == nil {
+		if durationSeconds <= bucket {
-								redisClients = value
+			h.counts[index]++
-							}
+			return
-							break
+		}
-						}
+	}
-					}
+	h.counts[len(h.counts)-1]++
-				}
+}
-			}
+
-		}
+func (h *requestDurationHistogram) snapshot() (counts []uint64, sum float64, total uint64) {
-
+	h.mu.Lock()
-		connectedClients := 0
+	defer h.mu.Unlock()
-		dmsSent := int64(0)
+
-		if hub != nil {
+	counts = append([]uint64(nil), h.counts...)
-			connectedClients = hub.ConnectedClients()
+	return counts, h.sum, h.total
-			dmsSent = hub.DMsSent
+}
-		}
+
-
+// ObserveRequestDuration records a chat HTTP request duration in seconds.
-		activeSessions := 0
+func ObserveRequestDuration(duration time.Duration) {
-		if sessionStore != nil {
+	chatRequestDurationHistogram.observe(duration.Seconds())
-			activeSessions = sessionStore.CountActive()
+}
-		}
+
-
+// WrapRequestTiming records request duration for the provided handler.
-		w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+func WrapRequestTiming(next http.HandlerFunc) http.HandlerFunc {
-
+	return func(w http.ResponseWriter, r *http.Request) {
-		writeLine := func(name string, value any) {
+		startedAt := time.Now()
-			fmt.Fprintf(w, "%s %v\n", name, value)
+		defer func() { ObserveRequestDuration(time.Since(startedAt)) }()
-		}
+		next(w, r)
-
+	}
-		fmt.Fprintln(w, "# HELP linearvoid_chat_connected_clients Current connected WebSocket clients.")
+}
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_connected_clients gauge")
+
-		writeLine("linearvoid_chat_connected_clients", connectedClients)
+// HandleMetrics returns Prometheus-format metrics for the chat service.
-
+func HandleMetrics(gormDB *gorm.DB, redis db.RedisClient, hub *ws.Hub, sessionStore *auth.SessionStore, dbDriver, instanceID string) http.HandlerFunc {
-		fmt.Fprintln(w, "# HELP linearvoid_chat_messages_total Total stored chat messages.")
+	return func(w http.ResponseWriter, r *http.Request) {
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_messages_total gauge")
+		if r.Method != http.MethodGet {
-		writeLine("linearvoid_chat_messages_total", storedMessages)
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
-
+			return
-		fmt.Fprintln(w, "# HELP linearvoid_chat_dms_total Total private messages sent.")
+		}
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_dms_total counter")
+
-		writeLine("linearvoid_chat_dms_total", dmsSent)
+		var storedMessages int64
-
+		if gormDB != nil {
-		fmt.Fprintln(w, "# HELP linearvoid_chat_moderation_actions_total Total moderation log entries.")
+			_ = gormDB.Model(&db.Message{}).Count(&storedMessages).Error
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_moderation_actions_total gauge")
+		}
-		writeLine("linearvoid_chat_moderation_actions_total", moderationActions)
+
-
+		var moderationActions int64
-		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_enabled Redis configured for chat service.")
+		if gormDB != nil {
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_enabled gauge")
+			_ = gormDB.Model(&db.ModerationLog{}).Count(&moderationActions).Error
-		writeLine("linearvoid_chat_redis_enabled", redisEnabled)
+		}
-
+
-		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_up Redis reachable from chat service.")
+		redisEnabled := 0
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_up gauge")
+		redisUp := 0
-		writeLine("linearvoid_chat_redis_up", redisUp)
+		redisClients := 0
-
+		redisMemoryUsedBytes := int64(0)
-		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_connected_clients Redis connected client count seen by chat service.")
+		redisMemoryMaxBytes := int64(0)
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_connected_clients gauge")
+		redisMemoryUsageRatio := 0.0
-		writeLine("linearvoid_chat_redis_connected_clients", redisClients)
+		if redis != nil {
-
+			redisEnabled = 1
-		fmt.Fprintln(w, "# HELP linearvoid_chat_admin_sessions_active Active unexpired admin sessions.")
+			if err := redis.Ping(context.Background()); err == nil {
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_admin_sessions_active gauge")
+				redisUp = 1
-		writeLine("linearvoid_chat_admin_sessions_active", activeSessions)
+				if info, err := redis.Info(context.Background(), "clients"); err == nil {
-
+					for _, line := range strings.Split(info, "\n") {
-		fmt.Fprintln(w, "# HELP linearvoid_chat_build_info Static build info for chat service.")
+						if strings.HasPrefix(line, "connected_clients:") {
-		fmt.Fprintln(w, "# TYPE linearvoid_chat_build_info gauge")
+							if value, err := strconv.Atoi(strings.TrimSpace(strings.TrimPrefix(line, "connected_clients:"))); err == nil {
-		fmt.Fprintf(w, "linearvoid_chat_build_info{service=\"chat\",database_driver=\"%s\",instance_id=\"%s\"} 1\n", dbDriver, instanceID)
+								redisClients = value
-	}
+							}
-}
+							break
-
+						}
-// HandleHealth returns a simple health check endpoint.
+					}
-func HandleHealth() http.HandlerFunc {
+				}
-	return func(w http.ResponseWriter, r *http.Request) {
+				if info, err := redis.Info(context.Background(), "memory"); err == nil {
-		w.Header().Set("Content-Type", "application/json")
+					if value := parseRedisMemoryBytes(info, "used_memory_human"); value > 0 {
-		w.WriteHeader(http.StatusOK)
+						redisMemoryUsedBytes = value
-		fmt.Fprint(w, `{"status":"healthy","service":"chat","timestamp":"`+time.Now().UTC().Format(time.RFC3339)+`"}`)
+					}
-	}
+					if value := parseRedisMemoryBytes(info, "maxmemory_human"); value > 0 {
-}
+						redisMemoryMaxBytes = value
-
+					} else if value := parseRedisMemoryBytes(info, "maxmemory"); value > 0 {
-// HandleNotFound returns a 404 JSON response for all unhandled paths.
+						redisMemoryMaxBytes = value
-func HandleNotFound() http.HandlerFunc {
+					}
-	return func(w http.ResponseWriter, r *http.Request) {
+					if redisMemoryMaxBytes > 0 {
-		w.Header().Set("Content-Type", "application/json")
+						redisMemoryUsageRatio = math.Min(float64(redisMemoryUsedBytes)/float64(redisMemoryMaxBytes), 1.0)
-		w.WriteHeader(http.StatusNotFound)
+					}
-		fmt.Fprint(w, `{"error":"not found"}`)
+				}
-	}
+			}
+		}
+
+		connectedClients := 0
+		dmsSent := int64(0)
+		if hub != nil {
+			connectedClients = hub.ConnectedClients()
+			dmsSent = hub.DMsSent
+		}
+
+		activeSessions := 0
+		if sessionStore != nil {
+			activeSessions = sessionStore.CountActive()
+		}
+
+		w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+
+		writeLine := func(name string, value any) {
+			fmt.Fprintf(w, "%s %v\n", name, value)
+		}
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_connected_clients Current connected WebSocket clients.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_connected_clients gauge")
+		writeLine("linearvoid_chat_connected_clients", connectedClients)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_messages_total Total stored chat messages.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_messages_total gauge")
+		writeLine("linearvoid_chat_messages_total", storedMessages)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_dms_total Total private messages sent.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_dms_total counter")
+		writeLine("linearvoid_chat_dms_total", dmsSent)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_moderation_actions_total Total moderation log entries.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_moderation_actions_total gauge")
+		writeLine("linearvoid_chat_moderation_actions_total", moderationActions)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_enabled Redis configured for chat service.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_enabled gauge")
+		writeLine("linearvoid_chat_redis_enabled", redisEnabled)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_up Redis reachable from chat service.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_up gauge")
+		writeLine("linearvoid_chat_redis_up", redisUp)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_connected_clients Redis connected client count seen by chat service.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_connected_clients gauge")
+		writeLine("linearvoid_chat_redis_connected_clients", redisClients)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_memory_used_bytes Redis used memory reported by INFO memory.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_memory_used_bytes gauge")
+		writeLine("linearvoid_chat_redis_memory_used_bytes", redisMemoryUsedBytes)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_memory_max_bytes Redis maxmemory limit reported by INFO memory.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_memory_max_bytes gauge")
+		writeLine("linearvoid_chat_redis_memory_max_bytes", redisMemoryMaxBytes)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_redis_memory_usage_ratio Redis memory usage ratio (used / max).")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_redis_memory_usage_ratio gauge")
+		writeLine("linearvoid_chat_redis_memory_usage_ratio", redisMemoryUsageRatio)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_admin_sessions_active Active unexpired admin sessions.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_admin_sessions_active gauge")
+		writeLine("linearvoid_chat_admin_sessions_active", activeSessions)
+
+		fmt.Fprintln(w, "# HELP linearvoid_chat_build_info Static build info for chat service.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_build_info gauge")
+		fmt.Fprintf(w, "linearvoid_chat_build_info{service=\"chat\",database_driver=\"%s\",instance_id=\"%s\"} 1\n", dbDriver, instanceID)
+
+		counts, sum, total := chatRequestDurationHistogram.snapshot()
+		fmt.Fprintln(w, "# HELP linearvoid_chat_request_duration_seconds HTTP request duration for chat API handlers.")
+		fmt.Fprintln(w, "# TYPE linearvoid_chat_request_duration_seconds histogram")
+		cumulative := uint64(0)
+		for index, bucket := range requestDurationBuckets {
+			cumulative += counts[index]
+			fmt.Fprintf(w, "linearvoid_chat_request_duration_seconds_bucket{le=\"%g\"} %d\n", bucket, cumulative)
+		}
+		cumulative += counts[len(counts)-1]
+		fmt.Fprintf(w, "linearvoid_chat_request_duration_seconds_bucket{le=\"+Inf\"} %d\n", cumulative)
+		fmt.Fprintf(w, "linearvoid_chat_request_duration_seconds_sum %g\n", sum)
+		fmt.Fprintf(w, "linearvoid_chat_request_duration_seconds_count %d\n", total)
+	}
+}
+
+// HandleHealth returns a simple health check endpoint.
+func HandleHealth() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		fmt.Fprint(w, `{"status":"healthy","service":"chat","timestamp":"`+time.Now().UTC().Format(time.RFC3339)+`"}`)
+	}
+}
+
+// HandleNotFound returns a 404 JSON response for all unhandled paths.
+func HandleNotFound() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusNotFound)
+		fmt.Fprint(w, `{"error":"not found"}`)
+	}
+}
+
+func parseRedisMemoryBytes(info, key string) int64 {
+	for _, line := range strings.Split(info, "\n") {
+		if !strings.HasPrefix(line, key+":") {
+			continue
+		}
+		value := strings.TrimSpace(strings.TrimPrefix(line, key+":"))
+		if value == "" {
+			return 0
+		}
+		if raw, err := strconv.ParseInt(value, 10, 64); err == nil {
+			return raw
+		}
+		return parseHumanBytes(value)
+	}
+	return 0
+}
+
+func parseHumanBytes(value string) int64 {
+	value = strings.TrimSpace(strings.ToUpper(value))
+	if value == "" {
+		return 0
+	}
+
+	multiplier := float64(1)
+	suffixes := map[string]float64{
+		"B": 1,
+		"K": 1024,
+		"KB": 1024,
+		"M": 1024 * 1024,
+		"MB": 1024 * 1024,
+		"G": 1024 * 1024 * 1024,
+		"GB": 1024 * 1024 * 1024,
+		"T": 1024 * 1024 * 1024 * 1024,
+		"TB": 1024 * 1024 * 1024 * 1024,
+	}
+
+	for suffix, factor := range suffixes {
+		if strings.HasSuffix(value, suffix) {
+			multiplier = factor
+			value = strings.TrimSpace(strings.TrimSuffix(value, suffix))
+			break
+		}
+	}
+
+	parsed, err := strconv.ParseFloat(value, 64)
+	if err != nil {
+		return 0
+	}
+	return int64(parsed * multiplier)
 }

backend/chat/src/metrics/metrics_test.go

@@ -1,190 +1,216 @@
-package metrics
+package metrics
-
+
-import (
+import (
-	"context"
+	"context"
-	"net/http"
+	"net/http"
-	"net/http/httptest"
+	"net/http/httptest"
-	"strings"
+	"strings"
-	"testing"
+	"testing"
-	"time"
+	"time"
-
+
-	"github.com/glebarez/sqlite"
+	"github.com/glebarez/sqlite"
-	"gorm.io/gorm"
+	"gorm.io/gorm"
-
+
-	"chat/src/auth"
+	"chat/src/auth"
-	"chat/src/db"
+	"chat/src/db"
-	"chat/src/ws"
+	"chat/src/ws"
-)
+)
-
+
-func TestHandleHealth(t *testing.T) {
+func TestHandleHealth(t *testing.T) {
-	handler := HandleHealth()
+	handler := HandleHealth()
-	req := httptest.NewRequest("GET", "/health", nil)
+	req := httptest.NewRequest("GET", "/health", nil)
-	w := httptest.NewRecorder()
+	w := httptest.NewRecorder()
-
+
-	handler(w, req)
+	handler(w, req)
-
+
-	if w.Code != http.StatusOK {
+	if w.Code != http.StatusOK {
-		t.Errorf("status = %d, want 200", w.Code)
+		t.Errorf("status = %d, want 200", w.Code)
-	}
+	}
-
+
-	body := w.Body.String()
+	body := w.Body.String()
-	if !strings.Contains(body, `"healthy"`) {
+	if !strings.Contains(body, `"healthy"`) {
-		t.Errorf("body missing healthy: %s", body)
+		t.Errorf("body missing healthy: %s", body)
-	}
+	}
-	if !strings.Contains(body, `"chat"`) {
+	if !strings.Contains(body, `"chat"`) {
-		t.Errorf("body missing service name: %s", body)
+		t.Errorf("body missing service name: %s", body)
-	}
+	}
-}
+}
-
+
-func TestHandleNotFound(t *testing.T) {
+func TestHandleNotFound(t *testing.T) {
-	handler := HandleNotFound()
+	handler := HandleNotFound()
-	req := httptest.NewRequest("GET", "/nonexistent", nil)
+	req := httptest.NewRequest("GET", "/nonexistent", nil)
-	w := httptest.NewRecorder()
+	w := httptest.NewRecorder()
-
+
-	handler(w, req)
+	handler(w, req)
-
+
-	if w.Code != http.StatusNotFound {
+	if w.Code != http.StatusNotFound {
-		t.Errorf("status = %d, want 404", w.Code)
+		t.Errorf("status = %d, want 404", w.Code)
-	}
+	}
-
+
-	body := w.Body.String()
+	body := w.Body.String()
-	if !strings.Contains(body, `"not found"`) {
+	if !strings.Contains(body, `"not found"`) {
-		t.Errorf("body missing not found: %s", body)
+		t.Errorf("body missing not found: %s", body)
-	}
+	}
-}
+}
-
+
-func TestHandleMetrics(t *testing.T) {
+func TestHandleMetrics(t *testing.T) {
-	gormDB, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+	chatRequestDurationHistogram = newRequestDurationHistogram(requestDurationBuckets)
-	if err != nil {
+	ObserveRequestDuration(100 * time.Millisecond)
-		t.Fatalf("failed to open test DB: %v", err)
+	ObserveRequestDuration(750 * time.Millisecond)
-	}
+
-	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{})
+	gormDB, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-
+	if err != nil {
-	// Add some test data
+		t.Fatalf("failed to open test DB: %v", err)
-	gormDB.Create(&db.Message{Room: "main", Username: "u1", Text: "hi", Timestamp: time.Now(), Type: "public"})
+	}
-	gormDB.Create(&db.ModerationLog{Action: "mute", Target: "u2", Moderator: "admin", Reason: "spam", Timestamp: time.Now()})
+	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{})
-
+
-	sessionStore := auth.NewSessionStore()
+	// Add some test data
-	hub := ws.NewHub(gormDB, nil, "test-instance", 10, 10*time.Second, "admin")
+	gormDB.Create(&db.Message{Room: "main", Username: "u1", Text: "hi", Timestamp: time.Now(), Type: "public"})
-	hub.DMsSent = 5
+	gormDB.Create(&db.ModerationLog{Action: "mute", Target: "u2", Moderator: "admin", Reason: "spam", Timestamp: time.Now()})
-
+
-	handler := HandleMetrics(gormDB, nil, hub, sessionStore, "sqlite", "test-instance")
+	sessionStore := auth.NewSessionStore()
-	req := httptest.NewRequest("GET", "/metrics", nil)
+	hub := ws.NewHub(gormDB, nil, "test-instance", 10, 10*time.Second, "admin")
-	w := httptest.NewRecorder()
+	hub.DMsSent = 5
-
+
-	handler(w, req)
+	handler := HandleMetrics(gormDB, nil, hub, sessionStore, "sqlite", "test-instance")
-
+	req := httptest.NewRequest("GET", "/metrics", nil)
-	if w.Code != http.StatusOK {
+	w := httptest.NewRecorder()
-		t.Errorf("status = %d, want 200", w.Code)
+
-	}
+	handler(w, req)
-
+
-	body := w.Body.String()
+	if w.Code != http.StatusOK {
-
+		t.Errorf("status = %d, want 200", w.Code)
-	// Check required metric names
+	}
-	requiredMetrics := []string{
+
-		"linearvoid_chat_connected_clients",
+	body := w.Body.String()
-		"linearvoid_chat_messages_total",
+
-		"linearvoid_chat_dms_total",
+	// Check required metric names
-		"linearvoid_chat_moderation_actions_total",
+	requiredMetrics := []string{
-		"linearvoid_chat_redis_enabled",
+		"linearvoid_chat_connected_clients",
-		"linearvoid_chat_redis_up",
+		"linearvoid_chat_messages_total",
-		"linearvoid_chat_redis_connected_clients",
+		"linearvoid_chat_dms_total",
-		"linearvoid_chat_admin_sessions_active",
+		"linearvoid_chat_moderation_actions_total",
-		"linearvoid_chat_build_info",
+		"linearvoid_chat_redis_enabled",
-	}
+		"linearvoid_chat_redis_up",
-
+		"linearvoid_chat_redis_connected_clients",
-	for _, metric := range requiredMetrics {
+		"linearvoid_chat_redis_memory_used_bytes",
-		if !strings.Contains(body, metric) {
+		"linearvoid_chat_redis_memory_max_bytes",
-			t.Errorf("body missing metric %s", metric)
+		"linearvoid_chat_redis_memory_usage_ratio",
-		}
+		"linearvoid_chat_admin_sessions_active",
-	}
+		"linearvoid_chat_build_info",
-
+		"linearvoid_chat_request_duration_seconds",
-	// Check build_info has instance_id label
+	}
-	if !strings.Contains(body, `instance_id="test-instance"`) {
+
-		t.Error("build_info missing instance_id label")
+	for _, metric := range requiredMetrics {
-	}
+		if !strings.Contains(body, metric) {
-
+			t.Errorf("body missing metric %s", metric)
-	// Check values
+		}
-	if !strings.Contains(body, "linearvoid_chat_messages_total 1") {
+	}
-		t.Error("messages_total should be 1")
+
-	}
+	// Check build_info has instance_id label
-	if !strings.Contains(body, "linearvoid_chat_moderation_actions_total 1") {
+	if !strings.Contains(body, `instance_id="test-instance"`) {
-		t.Error("moderation_actions_total should be 1")
+		t.Error("build_info missing instance_id label")
-	}
+	}
-	if !strings.Contains(body, "linearvoid_chat_dms_total 5") {
+
-		t.Error("dms_total should be 5")
+	// Check values
-	}
+	if !strings.Contains(body, "linearvoid_chat_messages_total 1") {
-	if !strings.Contains(body, "linearvoid_chat_redis_enabled 0") {
+		t.Error("messages_total should be 1")
-		t.Error("redis_enabled should be 0 (nil redis)")
+	}
-	}
+	if !strings.Contains(body, "linearvoid_chat_moderation_actions_total 1") {
-}
+		t.Error("moderation_actions_total should be 1")
-
+	}
-func TestHandleMetrics_WrongMethod(t *testing.T) {
+	if !strings.Contains(body, "linearvoid_chat_dms_total 5") {
-	handler := HandleMetrics(nil, nil, nil, nil, "", "")
+		t.Error("dms_total should be 5")
-	req := httptest.NewRequest("POST", "/metrics", nil)
+	}
-	w := httptest.NewRecorder()
+	if !strings.Contains(body, "linearvoid_chat_redis_enabled 0") {
-
+		t.Error("redis_enabled should be 0 (nil redis)")
-	handler(w, req)
+	}
-
+	if !strings.Contains(body, "linearvoid_chat_request_duration_seconds_bucket{le=\"1\"} 2") {
-	if w.Code != http.StatusMethodNotAllowed {
+		t.Error("request duration histogram should include both observed samples by the 1s bucket")
-		t.Errorf("status = %d, want 405", w.Code)
+	}
-	}
+	if !strings.Contains(body, "linearvoid_chat_request_duration_seconds_count 2") {
-}
+		t.Error("request duration count should be 2")
-
+	}
-func TestHandleMetrics_WithRedis(t *testing.T) {
+}
-	gormDB, _ := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+
-	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{})
+func TestHandleMetrics_WrongMethod(t *testing.T) {
-
+	handler := HandleMetrics(nil, nil, nil, nil, "", "")
-	// mockRedis for metrics test
+	req := httptest.NewRequest("POST", "/metrics", nil)
-	mr := &metricsMockRedis{}
+	w := httptest.NewRecorder()
-	sessionStore := auth.NewSessionStore()
+
-	hub := ws.NewHub(gormDB, mr, "test-instance", 10, 10*time.Second, "admin")
+	handler(w, req)
-
+
-	handler := HandleMetrics(gormDB, mr, hub, sessionStore, "sqlite", "inst-123")
+	if w.Code != http.StatusMethodNotAllowed {
-	req := httptest.NewRequest("GET", "/metrics", nil)
+		t.Errorf("status = %d, want 405", w.Code)
-	w := httptest.NewRecorder()
+	}
-
+}
-	handler(w, req)
+
-
+func TestHandleMetrics_WithRedis(t *testing.T) {
-	if w.Code != http.StatusOK {
+	chatRequestDurationHistogram = newRequestDurationHistogram(requestDurationBuckets)
-		t.Errorf("status = %d, want 200", w.Code)
+	ObserveRequestDuration(250 * time.Millisecond)
-	}
+
-
+	gormDB, _ := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
-	body := w.Body.String()
+	gormDB.AutoMigrate(&db.Message{}, &db.ModerationLog{})
-	if !strings.Contains(body, "linearvoid_chat_redis_enabled 1") {
+
-		t.Error("redis_enabled should be 1")
+	// mockRedis for metrics test
-	}
+	mr := &metricsMockRedis{}
-	if !strings.Contains(body, "linearvoid_chat_redis_up 1") {
+	sessionStore := auth.NewSessionStore()
-		t.Error("redis_up should be 1")
+	hub := ws.NewHub(gormDB, mr, "test-instance", 10, 10*time.Second, "admin")
-	}
+
-	if !strings.Contains(body, "linearvoid_chat_redis_connected_clients 5") {
+	handler := HandleMetrics(gormDB, mr, hub, sessionStore, "sqlite", "inst-123")
-		t.Error("redis_connected_clients should be 5")
+	req := httptest.NewRequest("GET", "/metrics", nil)
-	}
+	w := httptest.NewRecorder()
-}
+
-
+	handler(w, req)
-// metricsMockRedis is a minimal mock for metrics tests.
+
-type metricsMockRedis struct{}
+	if w.Code != http.StatusOK {
-
+		t.Errorf("status = %d, want 200", w.Code)
-func (m *metricsMockRedis) Ping(ctx context.Context) error { return nil }
+	}
-func (m *metricsMockRedis) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error {
+
-	return nil
+	body := w.Body.String()
-}
+	if !strings.Contains(body, "linearvoid_chat_redis_enabled 1") {
-func (m *metricsMockRedis) Get(ctx context.Context, key string) (string, error) { return "", nil }
+		t.Error("redis_enabled should be 1")
-func (m *metricsMockRedis) Del(ctx context.Context, keys ...string) error       { return nil }
+	}
-func (m *metricsMockRedis) Incr(ctx context.Context, key string) (int64, error) { return 0, nil }
+	if !strings.Contains(body, "linearvoid_chat_redis_up 1") {
-func (m *metricsMockRedis) Decr(ctx context.Context, key string) (int64, error) { return 0, nil }
+		t.Error("redis_up should be 1")
-func (m *metricsMockRedis) Expire(ctx context.Context, key string, expiration time.Duration) error {
+	}
-	return nil
+	if !strings.Contains(body, "linearvoid_chat_redis_connected_clients 5") {
-}
+		t.Error("redis_connected_clients should be 5")
-func (m *metricsMockRedis) Exists(ctx context.Context, keys ...string) (int64, error) { return 0, nil }
+	}
-func (m *metricsMockRedis) Publish(ctx context.Context, channel string, message interface{}) error {
+	if !strings.Contains(body, "linearvoid_chat_redis_memory_used_bytes 1048576") {
-	return nil
+		t.Error("redis_memory_used_bytes should be 1048576")
-}
+	}
-func (m *metricsMockRedis) PSubscribe(ctx context.Context, channels ...string) db.PubSub { return nil }
+	if !strings.Contains(body, "linearvoid_chat_redis_memory_usage_ratio 1") {
-func (m *metricsMockRedis) Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error) {
+		t.Error("redis_memory_usage_ratio should be 1 when maxmemory is unavailable or equal to used memory in tests")
-	return nil, 0, nil
+	}
-}
+	if !strings.Contains(body, "linearvoid_chat_request_duration_seconds_count 1") {
-func (m *metricsMockRedis) Info(ctx context.Context, sections ...string) (string, error) {
+		t.Error("request duration count should be 1")
-	return "connected_clients:5\nused_memory_human:1M\n", nil
+	}
-}
+}
+
+// metricsMockRedis is a minimal mock for metrics tests.
+type metricsMockRedis struct{}
+
+func (m *metricsMockRedis) Ping(ctx context.Context) error { return nil }
+func (m *metricsMockRedis) Set(ctx context.Context, key string, value interface{}, expiration time.Duration) error {
+	return nil
+}
+func (m *metricsMockRedis) Get(ctx context.Context, key string) (string, error) { return "", nil }
+func (m *metricsMockRedis) Del(ctx context.Context, keys ...string) error       { return nil }
+func (m *metricsMockRedis) Incr(ctx context.Context, key string) (int64, error) { return 0, nil }
+func (m *metricsMockRedis) Decr(ctx context.Context, key string) (int64, error) { return 0, nil }
+func (m *metricsMockRedis) Expire(ctx context.Context, key string, expiration time.Duration) error {
+	return nil
+}
+func (m *metricsMockRedis) Exists(ctx context.Context, keys ...string) (int64, error) { return 0, nil }
+func (m *metricsMockRedis) Publish(ctx context.Context, channel string, message interface{}) error {
+	return nil
+}
+func (m *metricsMockRedis) PSubscribe(ctx context.Context, channels ...string) db.PubSub { return nil }
+func (m *metricsMockRedis) Scan(ctx context.Context, cursor uint64, match string, count int64) ([]string, uint64, error) {
+	return nil, 0, nil
+}
+func (m *metricsMockRedis) Info(ctx context.Context, sections ...string) (string, error) {
+	return "connected_clients:5\nused_memory_human:1M\nmaxmemory_human:1M\n", nil
+}
 func (m *metricsMockRedis) Close() error { return nil }

backend/chat/src/ratelimit/ratelimit.go

@@ -1,75 +1,75 @@
-package ratelimit
+package ratelimit
-
+
-import (
+import (
-	"context"
+	"context"
-	"fmt"
+	"fmt"
-	"time"
+	"time"
-)
+)
-
+
-// RedisClient is the subset of Redis operations needed for rate limiting.
+// RedisClient is the subset of Redis operations needed for rate limiting.
-type RedisClient interface {
+type RedisClient interface {
-	Incr(ctx context.Context, key string) (int64, error)
+	Incr(ctx context.Context, key string) (int64, error)
-	Expire(ctx context.Context, key string, expiration time.Duration) error
+	Expire(ctx context.Context, key string, expiration time.Duration) error
-	Decr(ctx context.Context, key string) (int64, error)
+	Decr(ctx context.Context, key string) (int64, error)
-}
+}
-
+
-// CheckMessageRate checks if a user has exceeded the message rate limit.
+// CheckMessageRate checks if a user has exceeded the message rate limit.
-// Returns true if allowed, false if rate limited.
+// Returns true if allowed, false if rate limited.
-func CheckMessageRate(ctx context.Context, redis RedisClient, username string, max int, window time.Duration) (bool, error) {
+func CheckMessageRate(ctx context.Context, redis RedisClient, username string, max int, window time.Duration) (bool, error) {
-	if redis == nil {
+	if redis == nil {
-		return true, nil // No Redis = no rate limiting
+		return true, nil // No Redis = no rate limiting
-	}
+	}
-	key := fmt.Sprintf("rate:%s", username)
+	key := fmt.Sprintf("rate:%s", username)
-	count, err := redis.Incr(ctx, key)
+	count, err := redis.Incr(ctx, key)
-	if err != nil {
+	if err != nil {
-		return true, err // Fail open on Redis error
+		return true, err // Fail open on Redis error
-	}
+	}
-	if count == 1 {
+	if count == 1 {
-		_ = redis.Expire(ctx, key, window)
+		_ = redis.Expire(ctx, key, window)
-	}
+	}
-	return count <= int64(max), nil
+	return count <= int64(max), nil
-}
+}
-
+
-// CheckLoginRate checks if an IP has exceeded the login attempt limit.
+// CheckLoginRate checks if an IP has exceeded the login attempt limit.
-// Returns true if allowed, false if rate limited.
+// Returns true if allowed, false if rate limited.
-func CheckLoginRate(ctx context.Context, redis RedisClient, clientIP string) (bool, error) {
+func CheckLoginRate(ctx context.Context, redis RedisClient, clientIP string) (bool, error) {
-	if redis == nil {
+	if redis == nil {
-		return true, nil
+		return true, nil
-	}
+	}
-	key := fmt.Sprintf("login_attempts:%s", clientIP)
+	key := fmt.Sprintf("login_attempts:%s", clientIP)
-	count, err := redis.Incr(ctx, key)
+	count, err := redis.Incr(ctx, key)
-	if err != nil {
+	if err != nil {
-		return true, err
+		return true, err
-	}
+	}
-	if count == 1 {
+	if count == 1 {
-		_ = redis.Expire(ctx, key, 5*time.Minute)
+		_ = redis.Expire(ctx, key, 5*time.Minute)
-	}
+	}
-	return count <= 5, nil
+	return count <= 5, nil
-}
+}
-
+
-// CheckWSConnRate checks if an IP has exceeded the WebSocket connection limit.
+// CheckWSConnRate checks if an IP has exceeded the WebSocket connection limit.
-// Returns true if allowed, false if rate limited.
+// Returns true if allowed, false if rate limited.
-// Caller must call Decr on disconnect.
+// Caller must call Decr on disconnect.
-func CheckWSConnRate(ctx context.Context, redis RedisClient, clientIP string) (bool, error) {
+func CheckWSConnRate(ctx context.Context, redis RedisClient, clientIP string) (bool, error) {
-	if redis == nil {
+	if redis == nil {
-		return true, nil
+		return true, nil
-	}
+	}
-	key := fmt.Sprintf("ws_conn:%s", clientIP)
+	key := fmt.Sprintf("ws_conn:%s", clientIP)
-	count, err := redis.Incr(ctx, key)
+	count, err := redis.Incr(ctx, key)
-	if err != nil {
+	if err != nil {
-		return true, err
+		return true, err
-	}
+	}
-	if count == 1 {
+	if count == 1 {
-		_ = redis.Expire(ctx, key, 60*time.Second)
+		_ = redis.Expire(ctx, key, 60*time.Second)
-	}
+	}
-	return count <= 5, nil
+	return count <= 5, nil
-}
+}
-
+
-// DecrWSConn decrements the WebSocket connection counter for an IP.
+// DecrWSConn decrements the WebSocket connection counter for an IP.
-func DecrWSConn(ctx context.Context, redis RedisClient, clientIP string) {
+func DecrWSConn(ctx context.Context, redis RedisClient, clientIP string) {
-	if redis == nil {
+	if redis == nil {
-		return
+		return
-	}
+	}
-	key := fmt.Sprintf("ws_conn:%s", clientIP)
+	key := fmt.Sprintf("ws_conn:%s", clientIP)
-	_, _ = redis.Decr(ctx, key)
+	_, _ = redis.Decr(ctx, key)
 }

backend/chat/src/ratelimit/ratelimit_test.go

@@ -1,190 +1,190 @@
-package ratelimit
+package ratelimit
-
+
-import (
+import (
-	"context"
+	"context"
-	"sync"
+	"sync"
-	"testing"
+	"testing"
-	"time"
+	"time"
-)
+)
-
+
-// mockRedis implements RedisClient for testing.
+// mockRedis implements RedisClient for testing.
-type mockRedis struct {
+type mockRedis struct {
-	mu    sync.Mutex
+	mu    sync.Mutex
-	store map[string]int64
+	store map[string]int64
-}
+}
-
+
-func newMockRedis() *mockRedis {
+func newMockRedis() *mockRedis {
-	return &mockRedis{store: make(map[string]int64)}
+	return &mockRedis{store: make(map[string]int64)}
-}
+}
-
+
-func (m *mockRedis) Incr(ctx context.Context, key string) (int64, error) {
+func (m *mockRedis) Incr(ctx context.Context, key string) (int64, error) {
-	m.mu.Lock()
+	m.mu.Lock()
-	defer m.mu.Unlock()
+	defer m.mu.Unlock()
-	m.store[key]++
+	m.store[key]++
-	return m.store[key], nil
+	return m.store[key], nil
-}
+}
-
+
-func (m *mockRedis) Expire(ctx context.Context, key string, expiration time.Duration) error {
+func (m *mockRedis) Expire(ctx context.Context, key string, expiration time.Duration) error {
-	return nil
+	return nil
-}
+}
-
+
-func (m *mockRedis) Decr(ctx context.Context, key string) (int64, error) {
+func (m *mockRedis) Decr(ctx context.Context, key string) (int64, error) {
-	m.mu.Lock()
+	m.mu.Lock()
-	defer m.mu.Unlock()
+	defer m.mu.Unlock()
-	m.store[key]--
+	m.store[key]--
-	return m.store[key], nil
+	return m.store[key], nil
-}
+}
-
+
-func TestCheckMessageRate(t *testing.T) {
+func TestCheckMessageRate(t *testing.T) {
-	redis := newMockRedis()
+	redis := newMockRedis()
-	ctx := context.Background()
+	ctx := context.Background()
-
+
-	// First 10 messages allowed
+	// First 10 messages allowed
-	for i := 0; i < 10; i++ {
+	for i := 0; i < 10; i++ {
-		allowed, err := CheckMessageRate(ctx, redis, "user1", 10, 10*time.Second)
+		allowed, err := CheckMessageRate(ctx, redis, "user1", 10, 10*time.Second)
-		if err != nil {
+		if err != nil {
-			t.Fatalf("CheckMessageRate #%d error = %v", i+1, err)
+			t.Fatalf("CheckMessageRate #%d error = %v", i+1, err)
-		}
+		}
-		if !allowed {
+		if !allowed {
-			t.Errorf("CheckMessageRate #%d = false, want true", i+1)
+			t.Errorf("CheckMessageRate #%d = false, want true", i+1)
-		}
+		}
-	}
+	}
-
+
-	// 11th message blocked
+	// 11th message blocked
-	allowed, err := CheckMessageRate(ctx, redis, "user1", 10, 10*time.Second)
+	allowed, err := CheckMessageRate(ctx, redis, "user1", 10, 10*time.Second)
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckMessageRate #11 error = %v", err)
+		t.Fatalf("CheckMessageRate #11 error = %v", err)
-	}
+	}
-	if allowed {
+	if allowed {
-		t.Error("CheckMessageRate #11 = true, want false (rate limited)")
+		t.Error("CheckMessageRate #11 = true, want false (rate limited)")
-	}
+	}
-
+
-	// Different user not affected
+	// Different user not affected
-	allowed, err = CheckMessageRate(ctx, redis, "user2", 10, 10*time.Second)
+	allowed, err = CheckMessageRate(ctx, redis, "user2", 10, 10*time.Second)
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckMessageRate user2 error = %v", err)
+		t.Fatalf("CheckMessageRate user2 error = %v", err)
-	}
+	}
-	if !allowed {
+	if !allowed {
-		t.Error("CheckMessageRate user2 = false, want true")
+		t.Error("CheckMessageRate user2 = false, want true")
-	}
+	}
-}
+}
-
+
-func TestCheckMessageRate_NilRedis(t *testing.T) {
+func TestCheckMessageRate_NilRedis(t *testing.T) {
-	allowed, err := CheckMessageRate(context.Background(), nil, "user1", 10, 10*time.Second)
+	allowed, err := CheckMessageRate(context.Background(), nil, "user1", 10, 10*time.Second)
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckMessageRate nil redis error = %v", err)
+		t.Fatalf("CheckMessageRate nil redis error = %v", err)
-	}
+	}
-	if !allowed {
+	if !allowed {
-		t.Error("CheckMessageRate nil redis = false, want true (fail open)")
+		t.Error("CheckMessageRate nil redis = false, want true (fail open)")
-	}
+	}
-}
+}
-
+
-func TestCheckLoginRate(t *testing.T) {
+func TestCheckLoginRate(t *testing.T) {
-	redis := newMockRedis()
+	redis := newMockRedis()
-	ctx := context.Background()
+	ctx := context.Background()
-
+
-	// First 5 attempts allowed
+	// First 5 attempts allowed
-	for i := 0; i < 5; i++ {
+	for i := 0; i < 5; i++ {
-		allowed, err := CheckLoginRate(ctx, redis, "192.168.1.1")
+		allowed, err := CheckLoginRate(ctx, redis, "192.168.1.1")
-		if err != nil {
+		if err != nil {
-			t.Fatalf("CheckLoginRate #%d error = %v", i+1, err)
+			t.Fatalf("CheckLoginRate #%d error = %v", i+1, err)
-		}
+		}
-		if !allowed {
+		if !allowed {
-			t.Errorf("CheckLoginRate #%d = false, want true", i+1)
+			t.Errorf("CheckLoginRate #%d = false, want true", i+1)
-		}
+		}
-	}
+	}
-
+
-	// 6th attempt blocked
+	// 6th attempt blocked
-	allowed, err := CheckLoginRate(ctx, redis, "192.168.1.1")
+	allowed, err := CheckLoginRate(ctx, redis, "192.168.1.1")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckLoginRate #6 error = %v", err)
+		t.Fatalf("CheckLoginRate #6 error = %v", err)
-	}
+	}
-	if allowed {
+	if allowed {
-		t.Error("CheckLoginRate #6 = true, want false (rate limited)")
+		t.Error("CheckLoginRate #6 = true, want false (rate limited)")
-	}
+	}
-
+
-	// Different IP not affected
+	// Different IP not affected
-	allowed, err = CheckLoginRate(ctx, redis, "10.0.0.1")
+	allowed, err = CheckLoginRate(ctx, redis, "10.0.0.1")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckLoginRate other IP error = %v", err)
+		t.Fatalf("CheckLoginRate other IP error = %v", err)
-	}
+	}
-	if !allowed {
+	if !allowed {
-		t.Error("CheckLoginRate other IP = false, want true")
+		t.Error("CheckLoginRate other IP = false, want true")
-	}
+	}
-}
+}
-
+
-func TestCheckLoginRate_NilRedis(t *testing.T) {
+func TestCheckLoginRate_NilRedis(t *testing.T) {
-	allowed, err := CheckLoginRate(context.Background(), nil, "192.168.1.1")
+	allowed, err := CheckLoginRate(context.Background(), nil, "192.168.1.1")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckLoginRate nil redis error = %v", err)
+		t.Fatalf("CheckLoginRate nil redis error = %v", err)
-	}
+	}
-	if !allowed {
+	if !allowed {
-		t.Error("CheckLoginRate nil redis = false, want true (fail open)")
+		t.Error("CheckLoginRate nil redis = false, want true (fail open)")
-	}
+	}
-}
+}
-
+
-func TestCheckWSConnRate(t *testing.T) {
+func TestCheckWSConnRate(t *testing.T) {
-	redis := newMockRedis()
+	redis := newMockRedis()
-	ctx := context.Background()
+	ctx := context.Background()
-
+
-	// First 5 connections allowed
+	// First 5 connections allowed
-	for i := 0; i < 5; i++ {
+	for i := 0; i < 5; i++ {
-		allowed, err := CheckWSConnRate(ctx, redis, "192.168.1.1")
+		allowed, err := CheckWSConnRate(ctx, redis, "192.168.1.1")
-		if err != nil {
+		if err != nil {
-			t.Fatalf("CheckWSConnRate #%d error = %v", i+1, err)
+			t.Fatalf("CheckWSConnRate #%d error = %v", i+1, err)
-		}
+		}
-		if !allowed {
+		if !allowed {
-			t.Errorf("CheckWSConnRate #%d = false, want true", i+1)
+			t.Errorf("CheckWSConnRate #%d = false, want true", i+1)
-		}
+		}
-	}
+	}
-
+
-	// 6th connection blocked
+	// 6th connection blocked
-	allowed, err := CheckWSConnRate(ctx, redis, "192.168.1.1")
+	allowed, err := CheckWSConnRate(ctx, redis, "192.168.1.1")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckWSConnRate #6 error = %v", err)
+		t.Fatalf("CheckWSConnRate #6 error = %v", err)
-	}
+	}
-	if allowed {
+	if allowed {
-		t.Error("CheckWSConnRate #6 = true, want false (rate limited)")
+		t.Error("CheckWSConnRate #6 = true, want false (rate limited)")
-	}
+	}
-}
+}
-
+
-func TestCheckWSConnRate_NilRedis(t *testing.T) {
+func TestCheckWSConnRate_NilRedis(t *testing.T) {
-	allowed, err := CheckWSConnRate(context.Background(), nil, "192.168.1.1")
+	allowed, err := CheckWSConnRate(context.Background(), nil, "192.168.1.1")
-	if err != nil {
+	if err != nil {
-		t.Fatalf("CheckWSConnRate nil redis error = %v", err)
+		t.Fatalf("CheckWSConnRate nil redis error = %v", err)
-	}
+	}
-	if !allowed {
+	if !allowed {
-		t.Error("CheckWSConnRate nil redis = false, want true (fail open)")
+		t.Error("CheckWSConnRate nil redis = false, want true (fail open)")
-	}
+	}
-}
+}
-
+
-func TestDecrWSConn(t *testing.T) {
+func TestDecrWSConn(t *testing.T) {
-	redis := newMockRedis()
+	redis := newMockRedis()
-	ctx := context.Background()
+	ctx := context.Background()
-
+
-	// Increment to 5
+	// Increment to 5
-	for i := 0; i < 5; i++ {
+	for i := 0; i < 5; i++ {
-		CheckWSConnRate(ctx, redis, "192.168.1.1")
+		CheckWSConnRate(ctx, redis, "192.168.1.1")
-	}
+	}
-
+
-	// 6th should be blocked
+	// 6th should be blocked
-	allowed, _ := CheckWSConnRate(ctx, redis, "192.168.1.1")
+	allowed, _ := CheckWSConnRate(ctx, redis, "192.168.1.1")
-	if allowed {
+	if allowed {
-		t.Error("6th connection should be blocked")
+		t.Error("6th connection should be blocked")
-	}
+	}
-
+
-	// Decrement twice (simulate 2 disconnects)
+	// Decrement twice (simulate 2 disconnects)
-	DecrWSConn(ctx, redis, "192.168.1.1")
+	DecrWSConn(ctx, redis, "192.168.1.1")
-	DecrWSConn(ctx, redis, "192.168.1.1")
+	DecrWSConn(ctx, redis, "192.168.1.1")
-
+
-	// Now should be allowed again (counter 6→4, then incr→5)
+	// Now should be allowed again (counter 6→4, then incr→5)
-	allowed, _ = CheckWSConnRate(ctx, redis, "192.168.1.1")
+	allowed, _ = CheckWSConnRate(ctx, redis, "192.168.1.1")
-	if !allowed {
+	if !allowed {
-		t.Error("after 2x DecrWSConn, connection should be allowed")
+		t.Error("after 2x DecrWSConn, connection should be allowed")
-	}
+	}
-}
+}
-
+
-func TestDecrWSConn_NilRedis(t *testing.T) {
+func TestDecrWSConn_NilRedis(t *testing.T) {
-	// Should not panic
+	// Should not panic
-	DecrWSConn(context.Background(), nil, "192.168.1.1")
+	DecrWSConn(context.Background(), nil, "192.168.1.1")
 }

backend/chat/src/ws/ws.go

@@ -1,434 +1,500 @@
-package ws
+package ws
-
+
-import (
+import (
-	"context"
+	"context"
-	"encoding/json"
+	"encoding/json"
-	"fmt"
+	"fmt"
-	"log"
+	"log"
-	"net/http"
+	"net/http"
-	"strconv"
+	"strconv"
-	"strings"
+	"strings"
-	"sync"
+	"sync"
-	"time"
+	"time"
-
+
-	"github.com/gorilla/websocket"
+	"github.com/gorilla/websocket"
-	"gorm.io/gorm"
+	"gorm.io/gorm"
-
+
-	"chat/src/db"
+	"chat/src/db"
-	"chat/src/ratelimit"
+	"chat/src/ratelimit"
-)
+)
-
+
-// Upgrader is the WebSocket upgrader configuration.
+// Upgrader is the WebSocket upgrader configuration.
-var Upgrader = websocket.Upgrader{
+var Upgrader = websocket.Upgrader{
-	CheckOrigin: func(r *http.Request) bool { return true },
+	CheckOrigin: func(r *http.Request) bool { return true },
-}
+}
-
+
-// ClientInfo stores metadata about a connected WebSocket client.
+// ClientInfo stores metadata about a connected WebSocket client.
-type ClientInfo struct {
+type ClientInfo struct {
-	Username string
+	Username string
-	Room     string
+	Room     string
-}
+}
-
+
-// Hub manages all WebSocket connections and message routing.
+// Hub manages all WebSocket connections and message routing.
-type Hub struct {
+type Hub struct {
-	mu          sync.Mutex
+	mu          sync.Mutex
-	clients     map[*websocket.Conn]bool
+	clients     map[*websocket.Conn]bool
-	clientMeta  map[*websocket.Conn]ClientInfo
+	clientMeta  map[*websocket.Conn]ClientInfo
-	DB          *gorm.DB
+	DB          *gorm.DB
-	Redis       db.RedisClient
+	Redis       db.RedisClient
-	InstanceID  string
+	InstanceID  string
-	RateLimitMax    int
+	RateLimitMax    int
-	RateLimitWindow time.Duration
+	RateLimitWindow time.Duration
-	AdminUsername   string
+	AdminUsername   string
-	DMsSent         int64
+	DMsSent         int64
-}
+
-
+	presenceMu          sync.Mutex
-// NewHub creates a new WebSocket hub.
+	presenceTimers      map[string]*time.Timer
-func NewHub(gormDB *gorm.DB, redis db.RedisClient, instanceID string, rateMax int, rateWindow time.Duration, adminUser string) *Hub {
+	PresenceGracePeriod time.Duration
-	return &Hub{
+}
-		clients:         make(map[*websocket.Conn]bool),
+
-		clientMeta:      make(map[*websocket.Conn]ClientInfo),
+// NewHub creates a new WebSocket hub.
-		DB:              gormDB,
+func NewHub(gormDB *gorm.DB, redis db.RedisClient, instanceID string, rateMax int, rateWindow time.Duration, adminUser string) *Hub {
-		Redis:           redis,
+	return &Hub{
-		InstanceID:      instanceID,
+		clients:            make(map[*websocket.Conn]bool),
-		RateLimitMax:    rateMax,
+		clientMeta:         make(map[*websocket.Conn]ClientInfo),
-		RateLimitWindow: rateWindow,
+		DB:                 gormDB,
-		AdminUsername:   adminUser,
+		Redis:              redis,
-	}
+		InstanceID:         instanceID,
-}
+		RateLimitMax:       rateMax,
-
+		RateLimitWindow:    rateWindow,
-// ConnectedClients returns the number of currently connected clients.
+		AdminUsername:      adminUser,
-func (h *Hub) ConnectedClients() int {
+		presenceTimers:     make(map[string]*time.Timer),
-	h.mu.Lock()
+		PresenceGracePeriod: 5 * time.Second,
-	defer h.mu.Unlock()
+	}
-	return len(h.clients)
+}
-}
+
-
+// ConnectedClients returns the number of currently connected clients.
-// Broadcast sends a message to all connected clients and persists to DB.
+func (h *Hub) ConnectedClients() int {
-func (h *Hub) Broadcast(msg db.Message) {
+	h.mu.Lock()
-	h.mu.Lock()
+	defer h.mu.Unlock()
-	defer h.mu.Unlock()
+	return len(h.clients)
-
+}
-	// Persist to configured SQL backend.
+
-	if h.DB != nil {
+// Broadcast sends a message to all connected clients and persists to DB.
-		h.DB.Create(&msg)
+// System messages (join/leave announcements, moderation notices) fan out but
-	}
+// are not persisted, so the chat-log table only holds real chat messages.
-
+func (h *Hub) Broadcast(msg db.Message) {
-	// Local fan-out
+	h.mu.Lock()
-	for client := range h.clients {
+	defer h.mu.Unlock()
-		if err := client.WriteJSON(msg); err != nil {
+
-			client.Close()
+	// Persist to configured SQL backend (chat messages only).
-			delete(h.clients, client)
+	if h.DB != nil && msg.Type != "system" {
-			delete(h.clientMeta, client)
+		h.DB.Create(&msg)
-		}
+	}
-	}
+
-
+	// Local fan-out
-	// Redis pub/sub for multi-instance fan-out
+	for client := range h.clients {
-	if h.Redis != nil && msg.Room != "" {
+		if err := client.WriteJSON(msg); err != nil {
-		payload, _ := json.Marshal(map[string]any{
+			client.Close()
-			"instance": h.InstanceID,
+			delete(h.clients, client)
-			"msg":      msg,
+			delete(h.clientMeta, client)
-		})
+		}
-		_ = h.Redis.Publish(context.Background(), fmt.Sprintf("room:%s:messages", msg.Room), payload)
+	}
-	}
+
-}
+	// Redis pub/sub for multi-instance fan-out
-
+	if h.Redis != nil && msg.Room != "" {
-// PushChatHistory sends the last N messages for a room via WebSocket.
+		payload, _ := json.Marshal(map[string]any{
-func (h *Hub) PushChatHistory(conn *websocket.Conn, room string, limit int) {
+			"instance": h.InstanceID,
-	if h.DB == nil || room == "" {
+			"msg":      msg,
-		return
+		})
-	}
+		_ = h.Redis.Publish(context.Background(), fmt.Sprintf("room:%s:messages", msg.Room), payload)
-	var messages []db.Message
+	}
-	h.DB.Where("room = ?", room).Order("timestamp desc").Limit(limit).Find(&messages)
+}
-	// Reverse to chronological order
+
-	for i := len(messages)/2 - 1; i >= 0; i-- {
+// scheduleLeaveAnnouncement broadcasts a "left" message after a short grace
-		opp := len(messages) - 1 - i
+// period so quick reconnects don't produce join/leave spam.
-		messages[i], messages[opp] = messages[opp], messages[i]
+func (h *Hub) scheduleLeaveAnnouncement(room, username string) {
-	}
+	key := room + "\x00" + username
-	for _, msg := range messages {
+	h.presenceMu.Lock()
-		conn.WriteJSON(msg)
+	if h.presenceTimers == nil {
-	}
+		h.presenceTimers = make(map[string]*time.Timer)
-}
+	}
-
+	grace := h.PresenceGracePeriod
-// HandleConnection handles a new WebSocket connection.
+	if grace <= 0 {
-func (h *Hub) HandleConnection(w http.ResponseWriter, r *http.Request) {
+		grace = 5 * time.Second
-	clientIP := r.Header.Get("X-Forwarded-For")
+	}
-	if clientIP == "" {
+	h.presenceTimers[key] = time.AfterFunc(grace, func() {
-		clientIP = r.RemoteAddr
+		h.presenceMu.Lock()
-	}
+		delete(h.presenceTimers, key)
-
+		h.presenceMu.Unlock()
-	// IP-based connection rate limiting
+		h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " left " + room, Type: "system", Timestamp: time.Now()})
-	allowed, err := ratelimit.CheckWSConnRate(context.Background(), h.Redis, clientIP)
+	})
-	if err != nil {
+	h.presenceMu.Unlock()
-		log.Printf("WS rate limit check error: %v", err)
+}
-	}
+
-	if !allowed {
+// cancelLeaveAnnouncement cancels a pending "left" announcement for a
-		http.Error(w, "too many connections from this IP", http.StatusTooManyRequests)
+// room+user and reports whether one existed (i.e. a reconnect within grace).
-		return
+func (h *Hub) cancelLeaveAnnouncement(room, username string) bool {
-	}
+	key := room + "\x00" + username
-	defer ratelimit.DecrWSConn(context.Background(), h.Redis, clientIP)
+	h.presenceMu.Lock()
-
+	defer h.presenceMu.Unlock()
-	conn, err := Upgrader.Upgrade(w, r, nil)
+	if timer, ok := h.presenceTimers[key]; ok {
-	if err != nil {
+		timer.Stop()
-		log.Println("Upgrade error:", err)
+		delete(h.presenceTimers, key)
-		return
+		return true
-	}
+	}
-
+	return false
-	username := r.URL.Query().Get("username")
+}
-	room := r.URL.Query().Get("room")
+
-	if username == "" {
+// BroadcastTyping notifies other users in the room that a user is typing.
-		username = fmt.Sprintf("anon_%d", time.Now().UnixNano()%10000)
+func (h *Hub) BroadcastTyping(username, room string) {
-	}
+	h.mu.Lock()
-
+	defer h.mu.Unlock()
-	h.mu.Lock()
+	for conn, info := range h.clientMeta {
-	h.clients[conn] = true
+		if info.Room == room && info.Username != username {
-	h.clientMeta[conn] = ClientInfo{Username: username, Room: room}
+			_ = conn.WriteJSON(db.Message{Room: room, Username: username, Text: "", Type: "typing", Timestamp: time.Now()})
-	h.mu.Unlock()
+		}
-
+	}
-	// Announce presence (ADR-007)
+}
-	if h.Redis != nil && room != "" {
+
-		_ = h.Redis.Set(context.Background(), fmt.Sprintf("presence:%s:%s", room, username), "online", 60*time.Second)
+// PushChatHistory sends the last N messages for a room via WebSocket.
-		h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " joined " + room, Type: "system", Timestamp: time.Now()})
+func (h *Hub) PushChatHistory(conn *websocket.Conn, room string, limit int) {
-	}
+	if h.DB == nil || room == "" {
-
+		return
-	// Push chat history on join (last 50 messages)
+	}
-	h.PushChatHistory(conn, room, 50)
+	var messages []db.Message
-
+	h.DB.Where("room = ? AND type <> ?", room, "system").Order("timestamp desc").Limit(limit).Find(&messages)
-	// Heartbeat goroutine: refresh presence TTL every 30s
+	// Reverse to chronological order
-	heartbeatStop := make(chan struct{})
+	for i := len(messages)/2 - 1; i >= 0; i-- {
-	go func() {
+		opp := len(messages) - 1 - i
-		ticker := time.NewTicker(30 * time.Second)
+		messages[i], messages[opp] = messages[opp], messages[i]
-		defer ticker.Stop()
+	}
-		for {
+	h.mu.Lock()
-			select {
+	for _, msg := range messages {
-			case <-ticker.C:
+		conn.WriteJSON(msg)
-				if h.Redis != nil && room != "" {
+	}
-					_ = h.Redis.Set(context.Background(), fmt.Sprintf("presence:%s:%s", room, username), "online", 60*time.Second)
+	h.mu.Unlock()
-				}
+}
-				// Ping to detect dead connections
+
-				if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
+// HandleConnection handles a new WebSocket connection.
-					return
+func (h *Hub) HandleConnection(w http.ResponseWriter, r *http.Request) {
-				}
+	clientIP := r.Header.Get("X-Forwarded-For")
-			case <-heartbeatStop:
+	if clientIP == "" {
-				return
+		clientIP = r.RemoteAddr
-			}
+	}
-		}
+
-	}()
+	// IP-based connection rate limiting
-
+	allowed, err := ratelimit.CheckWSConnRate(context.Background(), h.Redis, clientIP)
-	defer func() {
+	if err != nil {
-		close(heartbeatStop)
+		log.Printf("WS rate limit check error: %v", err)
-		h.mu.Lock()
+	}
-		delete(h.clients, conn)
+	if !allowed {
-		delete(h.clientMeta, conn)
+		http.Error(w, "too many connections from this IP", http.StatusTooManyRequests)
-		h.mu.Unlock()
+		return
-		if h.Redis != nil && room != "" {
+	}
-			_ = h.Redis.Del(context.Background(), fmt.Sprintf("presence:%s:%s", room, username))
+	defer ratelimit.DecrWSConn(context.Background(), h.Redis, clientIP)
-			h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " left " + room, Type: "system", Timestamp: time.Now()})
+
-		}
+	conn, err := Upgrader.Upgrade(w, r, nil)
-		conn.Close()
+	if err != nil {
-	}()
+		log.Println("Upgrade error:", err)
-
+		return
-	for {
+	}
-		var msg db.Message
+
-		if err := conn.ReadJSON(&msg); err != nil {
+	username := r.URL.Query().Get("username")
-			break
+	room := r.URL.Query().Get("room")
-		}
+	if username == "" {
-
+		username = fmt.Sprintf("anon_%d", time.Now().UnixNano()%10000)
-		msg.Timestamp = time.Now()
+	}
-		msg.Username = username // enforce from query param for security
+
-
+	h.mu.Lock()
-		// Check if banned before processing
+	h.clients[conn] = true
-		if h.Redis != nil {
+	h.clientMeta[conn] = ClientInfo{Username: username, Room: room}
-			if isBanned, _ := h.Redis.Exists(context.Background(), fmt.Sprintf("banned:%s", username)); isBanned > 0 {
+	h.mu.Unlock()
-				conn.WriteJSON(db.Message{Type: "system", Text: "You are banned from chat.", Timestamp: time.Now()})
+
-				continue
+	// Announce presence (ADR-007). A reconnect within the grace window cancels
-			}
+	// the pending "left" announcement and skips a redundant "joined".
-			if isMuted, _ := h.Redis.Exists(context.Background(), fmt.Sprintf("muted:%s", username)); isMuted > 0 {
+	rejoined := h.cancelLeaveAnnouncement(room, username)
-				conn.WriteJSON(db.Message{Type: "system", Text: "You are muted.", Timestamp: time.Now()})
+	if h.Redis != nil && room != "" {
-				continue
+		_ = h.Redis.Set(context.Background(), fmt.Sprintf("presence:%s:%s", room, username), "online", 60*time.Second)
-			}
+		if !rejoined {
-		}
+			h.Broadcast(db.Message{Room: room, Username: "system", Text: username + " joined " + room, Type: "system", Timestamp: time.Now()})
-
+		}
-		// Rate limiting check
+	}
-		allowed, _ := ratelimit.CheckMessageRate(context.Background(), h.Redis, msg.Username, h.RateLimitMax, h.RateLimitWindow)
+
-		if !allowed {
+	// Push chat history on join (last 50 messages)
-			conn.WriteJSON(db.Message{Type: "system", Text: "Rate limit exceeded. Please slow down.", Timestamp: time.Now()})
+	h.PushChatHistory(conn, room, 50)
-			continue
+
-		}
+	// Heartbeat goroutine: refresh presence TTL every 30s
-
+	heartbeatStop := make(chan struct{})
-		// Handle moderation commands
+	go func() {
-		if strings.HasPrefix(msg.Text, "/mod ") || strings.HasPrefix(msg.Text, "/mute ") || strings.HasPrefix(msg.Text, "/ban ") {
+		ticker := time.NewTicker(30 * time.Second)
-			h.handleModerationCommand(msg, conn)
+		defer ticker.Stop()
-			continue
+		for {
-		}
+			select {
-
+			case <-ticker.C:
-		// Handle private DMs
+				if h.Redis != nil && room != "" {
-		if strings.HasPrefix(msg.Room, "dm:") {
+					_ = h.Redis.Set(context.Background(), fmt.Sprintf("presence:%s:%s", room, username), "online", 60*time.Second)
-			h.handlePrivateDM(msg)
+				}
-			continue
+				// Ping to detect dead connections
-		}
+				if err := conn.WriteMessage(websocket.PingMessage, nil); err != nil {
-
+					return
-		msg.Type = "public"
+				}
-		log.Printf("Chat message in room %s from %s: %s", msg.Room, msg.Username, msg.Text)
+			case <-heartbeatStop:
-		h.Broadcast(msg)
+				return
-	}
+			}
-}
+		}
-
+	}()
-// handlePrivateDM routes private messages to the specific user pair.
+
-func (h *Hub) handlePrivateDM(msg db.Message) {
+	defer func() {
-	msg.Type = "private"
+		close(heartbeatStop)
-	h.DMsSent++
+		h.mu.Lock()
-
+		delete(h.clients, conn)
-	// Persist for history
+		delete(h.clientMeta, conn)
-	if h.DB != nil {
+		h.mu.Unlock()
-		h.DB.Create(&msg)
+		if h.Redis != nil && room != "" {
-	}
+			_ = h.Redis.Del(context.Background(), fmt.Sprintf("presence:%s:%s", room, username))
-
+			h.scheduleLeaveAnnouncement(room, username)
-	// Deliver to target if online
+		}
-	h.mu.Lock()
+		conn.Close()
-	targetOnline := false
+	}()
-	for conn, info := range h.clientMeta {
+
-		if info.Username == msg.Room || strings.Contains(msg.Room, info.Username) {
+	for {
-			if err := conn.WriteJSON(msg); err == nil {
+		var msg db.Message
-				targetOnline = true
+		if err := conn.ReadJSON(&msg); err != nil {
-			}
+			break
-		}
+		}
-	}
+
-	h.mu.Unlock()
+		msg.Timestamp = time.Now()
-
+		msg.Username = username // enforce from query param for security
-	if !targetOnline {
+
-		log.Printf("DM stored for offline user: %s -> room %s", msg.Username, msg.Room)
+		// Check if banned before processing
-	}
+		if h.Redis != nil {
-
+			if isBanned, _ := h.Redis.Exists(context.Background(), fmt.Sprintf("banned:%s", username)); isBanned > 0 {
-	// Also deliver to sender for confirmation
+				conn.WriteJSON(db.Message{Type: "system", Text: "You are banned from chat.", Timestamp: time.Now()})
-	h.mu.Lock()
+				continue
-	for conn, info := range h.clientMeta {
+			}
-		if info.Username == msg.Username {
+			if isMuted, _ := h.Redis.Exists(context.Background(), fmt.Sprintf("muted:%s", username)); isMuted > 0 {
-			conn.WriteJSON(msg)
+				conn.WriteJSON(db.Message{Type: "system", Text: "You are muted.", Timestamp: time.Now()})
-			break
+				continue
-		}
+			}
-	}
+		}
-	h.mu.Unlock()
+
-
+		// Rate limiting check
-	log.Printf("Private DM from %s to room %s: %s", msg.Username, msg.Room, msg.Text)
+		allowed, _ := ratelimit.CheckMessageRate(context.Background(), h.Redis, msg.Username, h.RateLimitMax, h.RateLimitWindow)
-}
+		if !allowed {
-
+			conn.WriteJSON(db.Message{Type: "system", Text: "Rate limit exceeded. Please slow down.", Timestamp: time.Now()})
-// logModerationAction logs an action to the immutable ModerationLog table.
+			continue
-func (h *Hub) logModerationAction(action, target, moderator, reason string) {
+		}
-	logEntry := db.ModerationLog{
+
-		Action:    action,
+		// Handle moderation commands
-		Target:    target,
+		if strings.HasPrefix(msg.Text, "/mod ") || strings.HasPrefix(msg.Text, "/mute ") || strings.HasPrefix(msg.Text, "/ban ") {
-		Moderator: moderator,
+			h.handleModerationCommand(msg, conn)
-		Reason:    reason,
+			continue
-		Timestamp: time.Now(),
+		}
-	}
+
-	if h.DB != nil {
+		// Handle typing indicator (ephemeral — not persisted, not rate-limited)
-		h.DB.Create(&logEntry)
+		if msg.Type == "typing" {
-	}
+			h.BroadcastTyping(msg.Username, msg.Room)
-	log.Printf("Moderation action logged: %s %s by %s - %s", action, target, moderator, reason)
+			continue
-}
+		}
-
+
-// handleModerationCommand processes /mod, /mute, /ban commands.
+		// Handle private DMs
-func (h *Hub) handleModerationCommand(msg db.Message, conn *websocket.Conn) {
+		if strings.HasPrefix(msg.Room, "dm:") {
-	parts := strings.Fields(msg.Text)
+			h.handlePrivateDM(msg)
-	if len(parts) < 3 {
+			continue
-		conn.WriteJSON(db.Message{Type: "system", Text: "Usage: /mute <user> <duration_m> <reason> or /ban <user> <reason>", Timestamp: time.Now()})
+		}
-		return
+
-	}
+		msg.Type = "public"
-
+		log.Printf("Chat message in room %s from %s: %s", msg.Room, msg.Username, msg.Text)
-	if msg.Username != h.AdminUsername {
+		h.Broadcast(msg)
-		conn.WriteJSON(db.Message{Type: "system", Text: "Only moderators can use moderation commands.", Timestamp: time.Now()})
+	}
-		return
+}
-	}
+
-
+// handlePrivateDM routes private messages to the specific user pair.
-	action := strings.TrimPrefix(parts[0], "/")
+func (h *Hub) handlePrivateDM(msg db.Message) {
-	target := parts[1]
+	msg.Type = "private"
-	reason := strings.Join(parts[2:], " ")
+	h.DMsSent++
-
+
-	if h.Redis != nil {
+	// Persist for history
-		switch action {
+	if h.DB != nil {
-		case "mute", "mod":
+		h.DB.Create(&msg)
-			durationMinutes := 10 // default
+	}
-			if len(parts) >= 3 {
+
-				if d, err := strconv.Atoi(parts[2]); err == nil && d > 0 {
+	// Deliver to target if online
-					durationMinutes = d
+	h.mu.Lock()
-					if len(parts) > 3 {
+	targetOnline := false
-						reason = strings.Join(parts[3:], " ")
+	for conn, info := range h.clientMeta {
-					} else {
+		if info.Username == msg.Room || strings.Contains(msg.Room, info.Username) {
-						reason = "no reason given"
+			if err := conn.WriteJSON(msg); err == nil {
-					}
+				targetOnline = true
-				}
+			}
-			}
+		}
-			_ = h.Redis.Set(context.Background(), fmt.Sprintf("muted:%s", target), "1", time.Duration(durationMinutes)*time.Minute)
+	}
-		case "ban":
+	h.mu.Unlock()
-			_ = h.Redis.Set(context.Background(), fmt.Sprintf("banned:%s", target), "1", 0) // no expiry
+
-		}
+	if !targetOnline {
-	}
+		log.Printf("DM stored for offline user: %s -> room %s", msg.Username, msg.Room)
-
+	}
-	h.logModerationAction(action, target, msg.Username, reason)
+
-
+	// Also deliver to sender for confirmation
-	h.Broadcast(db.Message{
+	h.mu.Lock()
-		Room:      msg.Room,
+	for conn, info := range h.clientMeta {
-		Username:  "system",
+		if info.Username == msg.Username {
-		Type:      "system",
+			conn.WriteJSON(msg)
-		Text:      fmt.Sprintf("%s was %s by %s: %s", target, action, msg.Username, reason),
+			break
-		Timestamp: time.Now(),
+		}
-	})
+	}
-}
+	h.mu.Unlock()
-
+
-// SubscribeRoomMessages listens for Redis pub/sub messages and fans out locally.
+	log.Printf("Private DM from %s to room %s: %s", msg.Username, msg.Room, msg.Text)
-func (h *Hub) SubscribeRoomMessages() {
+}
-	if h.Redis == nil {
+
-		return
+// logModerationAction logs an action to the immutable ModerationLog table.
-	}
+func (h *Hub) logModerationAction(action, target, moderator, reason string) {
-	pubsub := h.Redis.PSubscribe(context.Background(), "room:*:messages")
+	logEntry := db.ModerationLog{
-	defer pubsub.Close()
+		Action:    action,
-
+		Target:    target,
-	log.Printf("Redis pub/sub subscriber started (instance %s)", h.InstanceID)
+		Moderator: moderator,
-
+		Reason:    reason,
-	for {
+		Timestamp: time.Now(),
-		msg, err := pubsub.ReceiveMessage(context.Background())
+	}
-		if err != nil {
+	if h.DB != nil {
-			log.Printf("Redis pub/sub error: %v — retrying in 5s", err)
+		h.DB.Create(&logEntry)
-			time.Sleep(5 * time.Second)
+	}
-			pubsub = h.Redis.PSubscribe(context.Background(), "room:*:messages")
+	log.Printf("Moderation action logged: %s %s by %s - %s", action, target, moderator, reason)
-			continue
+}
-		}
+
-
+// handleModerationCommand processes /mod, /mute, /ban commands.
-		var envelope struct {
+func (h *Hub) handleModerationCommand(msg db.Message, conn *websocket.Conn) {
-			Instance string     `json:"instance"`
+	parts := strings.Fields(msg.Text)
-			Msg      db.Message `json:"msg"`
+	if len(parts) < 3 {
-		}
+		conn.WriteJSON(db.Message{Type: "system", Text: "Usage: /mute <user> <duration_m> <reason> or /ban <user> <reason>", Timestamp: time.Now()})
-		if err := json.Unmarshal([]byte(msg.Payload), &envelope); err != nil {
+		return
-			continue
+	}
-		}
+
-
+	if msg.Username != h.AdminUsername {
-		// Skip messages originating from this instance
+		conn.WriteJSON(db.Message{Type: "system", Text: "Only moderators can use moderation commands.", Timestamp: time.Now()})
-		if envelope.Instance == h.InstanceID {
+		return
-			continue
+	}
-		}
+
-
+	action := strings.TrimPrefix(parts[0], "/")
-		// Fan out to local clients
+	target := parts[1]
-		h.mu.Lock()
+	reason := strings.Join(parts[2:], " ")
-		for client := range h.clients {
+
-			client.WriteJSON(envelope.Msg)
+	if h.Redis != nil {
-		}
+		switch action {
-		h.mu.Unlock()
+		case "mute", "mod":
-	}
+			durationMinutes := 10 // default
-}
+			if len(parts) >= 3 {
-
+				if d, err := strconv.Atoi(parts[2]); err == nil && d > 0 {
-// ScanPresence returns all active presence entries from Redis.
+					durationMinutes = d
-func (h *Hub) ScanPresence(ctx context.Context) ([]db.Presence, error) {
+					if len(parts) > 3 {
-	if h.Redis == nil {
+						reason = strings.Join(parts[3:], " ")
-		return nil, nil
+					} else {
-	}
+						reason = "no reason given"
-	keys, _, err := h.Redis.Scan(ctx, 0, "presence:*", 200)
+					}
-	if err != nil {
+				}
-		return nil, err
+			}
-	}
+			_ = h.Redis.Set(context.Background(), fmt.Sprintf("muted:%s", target), "1", time.Duration(durationMinutes)*time.Minute)
-	var presences []db.Presence
+		case "ban":
-	for _, key := range keys {
+			_ = h.Redis.Set(context.Background(), fmt.Sprintf("banned:%s", target), "1", 0) // no expiry
-		parts := strings.SplitN(key, ":", 3)
+		}
-		if len(parts) != 3 {
+	}
-			continue
+
-		}
+	h.logModerationAction(action, target, msg.Username, reason)
-		presences = append(presences, db.Presence{
+
-			Room:     parts[1],
+	h.Broadcast(db.Message{
-			Username: parts[2],
+		Room:      msg.Room,
-			Online:   true,
+		Username:  "system",
-		})
+		Type:      "system",
-	}
+		Text:      fmt.Sprintf("%s was %s by %s: %s", target, action, msg.Username, reason),
-	return presences, nil
+		Timestamp: time.Now(),
-}
+	})
-
+}
-// MuteUser mutes a user for a duration.
+
-func (h *Hub) MuteUser(ctx context.Context, username string, duration time.Duration) error {
+// SubscribeRoomMessages listens for Redis pub/sub messages and fans out locally.
-	if h.Redis == nil {
+func (h *Hub) SubscribeRoomMessages() {
-		return fmt.Errorf("redis unavailable")
+	if h.Redis == nil {
-	}
+		return
-	return h.Redis.Set(ctx, fmt.Sprintf("muted:%s", username), "1", duration)
+	}
-}
+	pubsub := h.Redis.PSubscribe(context.Background(), "room:*:messages")
-
+	defer pubsub.Close()
-// UnmuteUser removes a mute.
+
-func (h *Hub) UnmuteUser(ctx context.Context, username string) error {
+	log.Printf("Redis pub/sub subscriber started (instance %s)", h.InstanceID)
-	if h.Redis == nil {
+
-		return fmt.Errorf("redis unavailable")
+	for {
-	}
+		msg, err := pubsub.ReceiveMessage(context.Background())
-	return h.Redis.Del(ctx, fmt.Sprintf("muted:%s", username))
+		if err != nil {
-}
+			log.Printf("Redis pub/sub error: %v — retrying in 5s", err)
-
+			time.Sleep(5 * time.Second)
-// BanUser bans a user permanently.
+			pubsub = h.Redis.PSubscribe(context.Background(), "room:*:messages")
-func (h *Hub) BanUser(ctx context.Context, username string) error {
+			continue
-	if h.Redis == nil {
+		}
-		return fmt.Errorf("redis unavailable")
+
-	}
+		var envelope struct {
-	return h.Redis.Set(ctx, fmt.Sprintf("banned:%s", username), "1", 0)
+			Instance string     `json:"instance"`
-}
+			Msg      db.Message `json:"msg"`
-
+		}
-// UnbanUser removes a ban.
+		if err := json.Unmarshal([]byte(msg.Payload), &envelope); err != nil {
-func (h *Hub) UnbanUser(ctx context.Context, username string) error {
+			continue
-	if h.Redis == nil {
+		}
-		return fmt.Errorf("redis unavailable")
+
-	}
+		// Skip messages originating from this instance
-	return h.Redis.Del(ctx, fmt.Sprintf("banned:%s", username))
+		if envelope.Instance == h.InstanceID {
+			continue
+		}
+
+		// Fan out to local clients
+		h.mu.Lock()
+		for client := range h.clients {
+			client.WriteJSON(envelope.Msg)
+		}
+		h.mu.Unlock()
+	}
+}
+
+// ScanPresence returns all active presence entries from Redis.
+func (h *Hub) ScanPresence(ctx context.Context) ([]db.Presence, error) {
+	if h.Redis == nil {
+		return nil, nil
+	}
+	keys, _, err := h.Redis.Scan(ctx, 0, "presence:*", 200)
+	if err != nil {
+		return nil, err
+	}
+	var presences []db.Presence
+	for _, key := range keys {
+		parts := strings.SplitN(key, ":", 3)
+		if len(parts) != 3 {
+			continue
+		}
+		presences = append(presences, db.Presence{
+			Room:     parts[1],
+			Username: parts[2],
+			Online:   true,
+		})
+	}
+	return presences, nil
+}
+
+// MuteUser mutes a user for a duration.
+func (h *Hub) MuteUser(ctx context.Context, username string, duration time.Duration) error {
+	if h.Redis == nil {
+		return fmt.Errorf("redis unavailable")
+	}
+	return h.Redis.Set(ctx, fmt.Sprintf("muted:%s", username), "1", duration)
+}
+
+// UnmuteUser removes a mute.
+func (h *Hub) UnmuteUser(ctx context.Context, username string) error {
+	if h.Redis == nil {
+		return fmt.Errorf("redis unavailable")
+	}
+	return h.Redis.Del(ctx, fmt.Sprintf("muted:%s", username))
+}
+
+// BanUser bans a user permanently.
+func (h *Hub) BanUser(ctx context.Context, username string) error {
+	if h.Redis == nil {
+		return fmt.Errorf("redis unavailable")
+	}
+	return h.Redis.Set(ctx, fmt.Sprintf("banned:%s", username), "1", 0)
+}
+
+// UnbanUser removes a ban.
+func (h *Hub) UnbanUser(ctx context.Context, username string) error {
+	if h.Redis == nil {
+		return fmt.Errorf("redis unavailable")
+	}
+	return h.Redis.Del(ctx, fmt.Sprintf("banned:%s", username))
 }

backend/playout/Dockerfile

@@ -1,34 +1,33 @@
-FROM golang:1.25-alpine AS builder
+FROM golang:1.25-alpine AS builder
-
+
-WORKDIR /app
+WORKDIR /app
-COPY src/ ./src/
+COPY src/ ./src/
-
+COPY src/go.mod src/go.sum ./
-# Initialize Go module if not present
+
-RUN go mod init playout || true
+# Download dependencies and build
-RUN go mod tidy
+RUN go mod download
-
+RUN CGO_ENABLED=0 GOOS=linux GOFLAGS=-mod=mod go build -o /playlist-manager ./src/playlist.go
-RUN CGO_ENABLED=0 GOOS=linux go build -o /playlist-manager ./src/playlist.go
+
-
+FROM alpine:3.20
-FROM alpine:3.20
+
-
+# Install FFmpeg, curl for health checks, and basic tools
-# Install FFmpeg, curl for health checks, and basic tools
+RUN apk add --no-cache \
-RUN apk add --no-cache \
+    ffmpeg \
-    ffmpeg \
+    curl \
-    curl \
+    bash
-    bash
+# Set working directory for playout
-# Set working directory for playout
+WORKDIR /app
-WORKDIR /app
+# Create directories for playlist, media, HLS output, and emergency slate
-# Create directories for playlist, media, HLS output, and emergency slate
+RUN mkdir -p /app/hls /app/media /app/playlists /app/slate
-RUN mkdir -p /app/hls /app/media /app/playlists /app/slate
+# Copy the playout start script and the built playlist manager binary
-# Copy the playout start script and the built playlist manager binary
+COPY start-playout.sh /app/
-COPY start-playout.sh /app/
+# Copy demo data for out-of-the-box playout
-# Copy demo data for out-of-the-box playout
+COPY demodata/ /app/
-COPY demodata/ /app/
+# Copy the built playlist manager binary from the builder stage
-# Copy the built playlist manager binary from the builder stage
+COPY --from=builder /playlist-manager /app/playlist-manager
-COPY --from=builder /playlist-manager /app/playlist-manager
+# Set execute permissions for the start script and playlist manager binary
-# Set execute permissions for the start script and playlist manager binary
+RUN chmod +x /app/start-playout.sh /app/playlist-manager
-RUN chmod +x /app/start-playout.sh /app/playlist-manager
+# Expose HLS directory (will be served by nginx)
-# Expose HLS directory (will be served by nginx)
+VOLUME ["/app/hls"]
-VOLUME ["/app/hls"]
+# Default command runs the playout loop (which calls the Go validator)
-# Default command runs the playout loop (which calls the Go validator)
 CMD ["./start-playout.sh"]

backend/playout/demodata/playlist/playlist.txt

@@ -1,3 +1,3 @@
-# Linear Void Demo Playlist
+# Linear Void Demo Playlist
-file '/app/media/demo1.mp4'
+file '/app/media/demo1.mp4'
 file '/app/media/demo2.mp4'

backend/playout/src/go.mod

@@ -1,11 +1,12 @@
 module playout
 
-go 1.26.5
+go 1.25.0
 
 require (
 	github.com/aws/aws-sdk-go-v2 v1.43.4
 	github.com/aws/aws-sdk-go-v2/config v1.32.35
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.107.0
+	github.com/fsnotify/fsnotify v1.8.0
 )
 
 require (
@@ -24,4 +25,5 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.38.4 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.45.4 // indirect
 	github.com/aws/smithy-go v1.27.6 // indirect
+	golang.org/x/sys v0.13.0 // indirect
 )

backend/playout/src/go.sum

@@ -34,3 +34,7 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.45.4 h1:w/AryDYMjSUANSQ2uoZxJovUsMTw
 github.com/aws/aws-sdk-go-v2/service/sts v1.45.4/go.mod h1:WeBiAa67azG7Su9Vf+ChGDBLiAozJCXzdjXiPBUwtbc=
 github.com/aws/smithy-go v1.27.6 h1:0zjT8jgK3jbrTT7JJ3EE6JsMhX8JTrZ+f1sEndYDXrA=
 github.com/aws/smithy-go v1.27.6/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M=
+github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

backend/playout/src/playlist_rewrite_test.go

@@ -0,0 +1,227 @@
+package main
+
+import (
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+)
+
+const sampleManifest = `#EXTM3U
+#EXT-X-VERSION:7
+#EXT-X-TARGETDURATION:2
+#EXT-X-MEDIA-SEQUENCE:0
+#EXT-X-INDEPENDENT-SEGMENTS
+#EXT-X-MAP:URI="init.mp4"
+#EXTINF:2.000000,
+seg-000000.m4s
+#EXTINF:2.000000,
+seg-000001.m4s
+#EXT-X-ENDLIST
+`
+
+func TestRewriteManifestToRun(t *testing.T) {
+	runID := "r-20260903T120000Z"
+	out := string(rewriteManifestToRun(runID, []byte(sampleManifest)))
+
+	wants := []string{
+		`#EXT-X-MAP:URI="r-20260903T120000Z/init.mp4"`,
+		"r-20260903T120000Z/seg-000000.m4s",
+		"r-20260903T120000Z/seg-000001.m4s",
+		"#EXTM3U",
+		"#EXT-X-VERSION:7",
+		"#EXT-X-TARGETDURATION:2",
+		"#EXT-X-MEDIA-SEQUENCE:0",
+		"#EXT-X-INDEPENDENT-SEGMENTS",
+		"#EXT-X-ENDLIST",
+		"#EXTINF:2.000000,",
+	}
+	for _, want := range wants {
+		if !contains(out, want) {
+			t.Errorf("output missing %q\noutput:\n%s", want, out)
+		}
+	}
+
+	// Media URIs must be prefixed (no bare segments left).
+	for _, bare := range []string{"\nseg-000000.m4s\n", "\nseg-000001.m4s\n", `URI="init.mp4"`} {
+		if contains(out, bare) {
+			t.Errorf("output still contains bare %q\noutput:\n%s", bare, out)
+		}
+	}
+}
+
+func TestRewriteManifestToRun_AlreadyPrefixedUnchanged(t *testing.T) {
+	manifest := "#EXTM3U\n#EXT-X-MAP:URI=\"r-old/init.mp4\"\nseg-000000.m4s\nr-old/seg-000001.m4s\n#EXT-X-ENDLIST\n"
+	out := string(rewriteManifestToRun("r-new", []byte(manifest)))
+
+	if !contains(out, `#EXT-X-MAP:URI="r-old/init.mp4"`) {
+		t.Errorf("EXT-X-MAP already-prefixed URI was rewritten: %s", out)
+	}
+	// A URI line that already contains a path is left alone.
+	if !contains(out, "r-old/seg-000001.m4s") {
+		t.Errorf("already-prefixed segment URI was changed:\n%s", out)
+	}
+	// Bare URI still gets the run prefix.
+	if !contains(out, "r-new/seg-000000.m4s") {
+		t.Errorf("bare segment not prefixed:\n%s", out)
+	}
+}
+
+func TestRewriteManifestToRun_HandlesTSAndComments(t *testing.T) {
+	manifest := "#EXTM3U\n# a comment\nvideo-1.ts\ninit.mp4\n#EXT-X-ENDLIST\n"
+	out := string(rewriteManifestToRun("r-x", []byte(manifest)))
+
+	for _, want := range []string{"r-x/video-1.ts", "r-x/init.mp4", "# a comment", "#EXTM3U", "#EXT-X-ENDLIST"} {
+		if !contains(out, want) {
+			t.Errorf("output missing %q\noutput:\n%s", want, out)
+		}
+	}
+}
+
+func TestRewriteManifestToRun_EmptyRunID(t *testing.T) {
+	out := rewriteManifestToRun("", []byte(sampleManifest))
+	if string(out) != sampleManifest {
+		t.Errorf("empty runID should return input unchanged")
+	}
+}
+
+func TestIsMediaURI(t *testing.T) {
+	for _, ok := range []string{"seg-000001.m4s", "init.mp4", "a.ts", "x.m4a"} {
+		if !isMediaURI(ok) {
+			t.Errorf("isMediaURI(%q) = false, want true", ok)
+		}
+	}
+	for _, notOK := range []string{"playlist.m3u8", "readme.txt", "seg-000001.m4s?x=1"} {
+		// Note: query strings are stripped; '?x=1' on m4s should still be media.
+		if notOK == "seg-000001.m4s?x=1" {
+			continue
+		}
+		if isMediaURI(notOK) {
+			t.Errorf("isMediaURI(%q) = true, want false", notOK)
+		}
+	}
+	if !isMediaURI("seg-000001.m4s?token=abc") {
+		t.Errorf("isMediaURI with query should strip query and be true")
+	}
+}
+
+func TestPublishManifest_RewritesToRunScopedURIs(t *testing.T) {
+	prevClient, prevBucket := r2Client, bucket
+	prevRunID, prevMode := runID, playoutMode
+	prevPut, prevCopy := putObject, copyObject
+	defer func() {
+		r2Client, bucket = prevClient, prevBucket
+		runID, playoutMode = prevRunID, prevMode
+		putObject, copyObject = prevPut, prevCopy
+	}()
+
+	tmpDir := t.TempDir()
+	mp := filepath.Join(tmpDir, "playlist.m3u8")
+	if err := os.WriteFile(mp, []byte(sampleManifest), 0o644); err != nil {
+		t.Fatalf("write manifest: %v", err)
+	}
+
+	bucket = "linearvoid-media"
+	runID = "r-20260903T120000Z"
+	playoutMode = "live"
+	r2Client = &s3.Client{}
+
+	var gotKey, gotCopySource, gotCopyKey string
+	var gotBody []byte
+	putObject = func(_ *s3.Client, in *s3.PutObjectInput) (*s3.PutObjectOutput, error) {
+		gotKey = aws.ToString(in.Key)
+		b, err := io.ReadAll(in.Body)
+		if err != nil {
+			return nil, err
+		}
+		gotBody = b
+		return &s3.PutObjectOutput{}, nil
+	}
+	copyObject = func(_ *s3.Client, in *s3.CopyObjectInput) (*s3.CopyObjectOutput, error) {
+		gotCopySource = aws.ToString(in.CopySource)
+		gotCopyKey = aws.ToString(in.Key)
+		return &s3.CopyObjectOutput{}, nil
+	}
+
+	if err := publishManifest(mp); err != nil {
+		t.Fatalf("publishManifest error: %v", err)
+	}
+
+	if gotKey != "hls/playlist.m3u8.tmp" {
+		t.Errorf("temp upload key = %q, want hls/playlist.m3u8.tmp", gotKey)
+	}
+	if gotCopySource != "linearvoid-media/hls/playlist.m3u8.tmp" {
+		t.Errorf("CopySource = %q, want linearvoid-media/hls/playlist.m3u8.tmp", gotCopySource)
+	}
+	if gotCopyKey != "hls/playlist.m3u8" {
+		t.Errorf("final key = %q, want hls/playlist.m3u8", gotCopyKey)
+	}
+
+	body := string(gotBody)
+	for _, want := range []string{
+		"r-20260903T120000Z/seg-000000.m4s",
+		"r-20260903T120000Z/seg-000001.m4s",
+		`#EXT-X-MAP:URI="r-20260903T120000Z/init.mp4"`,
+	} {
+		if !contains(body, want) {
+			t.Errorf("published manifest missing %q:\n%s", want, body)
+		}
+	}
+	for _, bare := range []string{"\nseg-000000.m4s\n", "\nseg-000001.m4s\n"} {
+		if contains(body, bare) {
+			t.Errorf("published manifest still contains bare %q:\n%s", bare, body)
+		}
+	}
+}
+
+func TestPublishManifest_SlateNotRewritten(t *testing.T) {
+	prevClient, prevBucket := r2Client, bucket
+	prevRunID, prevMode := runID, playoutMode
+	prevPut, prevCopy := putObject, copyObject
+	defer func() {
+		r2Client, bucket = prevClient, prevBucket
+		runID, playoutMode = prevRunID, prevMode
+		putObject, copyObject = prevPut, prevCopy
+	}()
+
+	tmpDir := t.TempDir()
+	mp := filepath.Join(tmpDir, "playlist.m3u8")
+	if err := os.WriteFile(mp, []byte(sampleManifest), 0o644); err != nil {
+		t.Fatalf("write manifest: %v", err)
+	}
+
+	bucket = "linearvoid-media"
+	runID = "r-20260903T120000Z"
+	playoutMode = "slate"
+	r2Client = &s3.Client{}
+
+	var gotBody []byte
+	putObject = func(_ *s3.Client, in *s3.PutObjectInput) (*s3.PutObjectOutput, error) {
+		b, _ := io.ReadAll(in.Body)
+		gotBody = b
+		return &s3.PutObjectOutput{}, nil
+	}
+	copyObject = func(_ *s3.Client, _ *s3.CopyObjectInput) (*s3.CopyObjectOutput, error) {
+		return &s3.CopyObjectOutput{}, nil
+	}
+
+	if err := publishManifest(mp); err != nil {
+		t.Fatalf("publishManifest error: %v", err)
+	}
+
+	if string(gotBody) != sampleManifest {
+		t.Errorf("slate manifest should be published unmodified; got:\n%s", string(gotBody))
+	}
+}
+
+func contains(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

backend/playout/start-playout.sh

@@ -3,8 +3,8 @@ set -e
 
 echo "=== Linear Void Playout Service Starting ==="
 echo "Playlist path: ${PLAYLIST_PATH:=/app/playlist/playlist.txt}"
-echo "HLS segment duration: ${HLS_SEGMENT_DURATION:-6}s"
+echo "HLS segment duration: ${HLS_SEGMENT_DURATION:-2}s"
-echo "HLS window size: ${HLS_WINDOW_SIZE:-24}"
+echo "HLS window size: ${HLS_WINDOW_SIZE:-12}"
 
 # Ensure playlist directory and file exist
 mkdir -p "$(dirname "$PLAYLIST_PATH")"
@@ -17,38 +17,7 @@ file '/app/media/demo2.mp4'
 EOF
 fi
 
-# Run normalization validation using the Go tool
+# Single source of truth: the Go binary validates the playlist (ADR-001/ADR-003
-echo "Validating playlist and enforcing normalization (ADR-001/ADR-003)..."
+# normalization enforcement) and runs the full loop (HLS, R2 sync, slate
-if ! /app/playlist-manager "$PLAYLIST_PATH"; then
+# fallback, health server). Validation runs once inside the binary.
-  echo "ERROR: Playlist validation failed. Check logs."
+exec /app/playlist-manager "$PLAYLIST_PATH"
-  exit 1
-fi
-
-echo "Playlist validated successfully. Starting continuous HLS playout..."
-
-mkdir -p /app/hls
-rm -f /app/hls/playlist.m3u8 /app/hls/init.mp4 /app/hls/segment_*.ts /app/hls/segment_*.m4s
-
-# Run FFmpeg in a loop for continuous playback
-while true; do
-  echo "[$(date)] Starting FFmpeg playout with browser-safe HLS encoding..."
-  ffmpeg -re -f concat -safe 0 -i "$PLAYLIST_PATH" \
-    -map 0:v:0 -map 0:a:0? \
-    -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p" \
-    -c:v libx264 -preset veryfast -pix_fmt yuv420p \
-    -profile:v high -level 4.0 \
-    -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
-    -c:a aac -ar 48000 -ac 2 -b:a 128k \
-    -f hls \
-    -hls_time "${HLS_SEGMENT_DURATION}" \
-    -hls_list_size "${HLS_WINDOW_SIZE}" \
-    -hls_segment_type fmp4 \
-    -hls_fmp4_init_filename init.mp4 \
-    -strftime 1 \
-    -hls_flags delete_segments+independent_segments \
-    -hls_segment_filename "/app/hls/segment_%Y%m%d_%H%M%S.m4s" \
-    "/app/hls/playlist.m3u8" || echo "FFmpeg exited with error (will restart in 5s per ADR-001 resilience requirements)..."
-
-  echo "Playout loop crashed or ended. Restarting in 5 seconds..."
-  sleep 5
-done

backend/playout/testdata/comments_only.txt

@@ -0,0 +1,2 @@
+# Linear Void test playlist
+# No media entries here

backend/playout/testdata/empty_playlist.txt

@@ -0,0 +1 @@
+

backend/playout/testdata/mixed_valid_invalid.txt

@@ -0,0 +1,6 @@
+# Valid entries should still parse
+file '/app/media/demo1.mp4'
+
+# Invalid or malformed lines are preserved as literal paths by the parser
+not-a-file-entry
+file '/app/media/demo2.mp4'

backend/playout/testdata/valid_playlist.txt

@@ -0,0 +1,2 @@
+file '/app/media/demo1.mp4'
+file '/app/media/demo2.mp4'

docker-compose.prod.yml

@@ -11,6 +11,8 @@ services:
     restart: unless-stopped
     env_file:
       - .env
+    ports:
+      - "${PLAYOUT_PORT:-8081}:8081"
     volumes:
       - ./data/playlist:/app/playlist:rw
       - ./data/media:/app/media:ro
@@ -56,7 +58,7 @@ services:
     container_name: linearvoid-nginx
     restart: unless-stopped
     ports:
-      - "${NGINX_PORT:-8080}:80"
+      - "${NGINX_PORT:-8082}:80"
     volumes:
       - ./data/hls:/srv/hls:ro
     networks:
@@ -168,6 +170,8 @@ services:
     command:
       - "--config.file=/etc/prometheus/prometheus.yml"
       - "--storage.tsdb.path=/prometheus"
+      - "--storage.tsdb.retention.time=30d"
+      - "--storage.tsdb.retention.size=15GB"
       - "--web.console.libraries=/etc/prometheus/console_libraries"
       - "--web.console.templates=/etc/prometheus/consoles"
       - "--web.enable-lifecycle"

docker-compose.yml

@@ -13,6 +13,8 @@ services:
     restart: unless-stopped
     env_file:
       - .env
+    ports:
+      - "${PLAYOUT_PORT:-8081}:8081"
     volumes:
       - ./data/playlist:/app/playlist:ro
       - ./data/media:/app/media:ro
@@ -64,7 +66,7 @@ services:
     container_name: linearvoid-nginx
     restart: unless-stopped
     ports:
-      - "${NGINX_PORT:-8080}:80"
+      - "${NGINX_PORT:-8082}:80"
     volumes:
       - ./frontend/dist:/srv/frontend:ro
       - ./data/hls:/srv/hls:ro
@@ -162,6 +164,8 @@ services:
     command:
       - "--config.file=/etc/prometheus/prometheus.yml"
       - "--storage.tsdb.path=/prometheus"
+      - "--storage.tsdb.retention.time=30d"
+      - "--storage.tsdb.retention.size=15GB"
       - "--web.console.libraries=/etc/prometheus/console_libraries"
       - "--web.console.templates=/etc/prometheus/consoles"
       - "--web.enable-lifecycle"

docs/API.md

@@ -0,0 +1,159 @@
+# Linear Void API Reference
+
+Base URLs: Public/admin app `https://linearvoid.tv` · WebSocket `wss://linearvoid.tv/ws` · Local fallback `http://localhost` / `ws://localhost/ws`
+
+## Authentication
+
+Admin REST endpoints use a cookie session:
+
+- Cookie: `linearvoid_admin_session` — `HttpOnly`, `SameSite=Strict`, `Secure` when request is HTTPS (or `X-Forwarded-Proto=https`)
+- Session TTL: `ADMIN_SESSION_TTL_HOURS` (default 12h)
+
+## Chat WebSocket API
+
+Connect: `GET /ws?username={name}&room={room}` — client/server exchange JSON messages.
+
+| Message (client→server) | Field                                                                            | Notes |
+| ----------------------- | -------------------------------------------------------------------------------- | ----- |
+| `type`                  | `public` for room chat, `private` for DM routing; `system` for moderation/events |       |
+| `room`                  | `main`; private DMs use `dm:userA-userB` (usernames sorted)                      |       |
+| `username`              | sender                                                                           |       |
+| `text`                  | message body                                                                     |       |
+
+Server→client envelope adds `"timestamp"` (ISO-8601, e.g. `2026-08-04T12:34:56Z`).
+
+```json
+{ "room": "main", "username": "viewer123", "text": "hello world", "type": "public" }
+```
+
+## Admin Session API
+
+| Method & Path            | Auth                                | Description                   |
+| ------------------------ | ----------------------------------- | ----------------------------- |
+| `POST /api/admin/login`  | none                                | Authenticate                  |
+| `POST /api/admin/logout` | optional (clears cookie either way) | Logout                        |
+| `GET /api/admin/session` | cookie required                     | Session check; 401 if invalid |
+
+Login request:
+
+```json
+{ "username": "admin", "password": "your-password" }
+```
+
+Login/logout/session success response (session returns 401 on failure):
+
+```json
+{ "authenticated": true, "username": "admin" }
+```
+
+Logout response: `{ "authenticated": false }`
+
+## Admin Data API (auth required)
+
+| Method & Path                             | Returns                                                                                              |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `GET /api/admin/overview`                 | Aggregate counters + runtime/system snapshot                                                         |
+| `GET /api/admin/playlist`                 | Playlist                                                                                             |
+| `PUT /api/admin/playlist`                 | Set playlist (body: `{ "content": "file '/app/media/video1.mp4'\nfile '/app/media/video2.mp4'\n" }`) |
+| `GET /api/admin/schedule`                 | Parsed playlist entries + matched media metadata/runtime                                             |
+| `GET /api/admin/moderation/logs?limit=50` | Moderation logs                                                                                      |
+| `POST /api/admin/moderation/actions`      | Perform moderation action                                                                            |
+| `GET /api/admin/analytics`                | Totals (messages, moderation actions, rooms) + top room summary                                      |
+| `GET /api/admin/system`                   | Health snapshot (chat/playout/redis/database) + config metadata                                      |
+| `GET /api/admin/users`                    | Presence users (room + username) when Redis available                                                |
+
+Moderation action request:
+
+```json
+{ "action": "mute", "target": "username-or-id", "moderator": "admin", "reason": "spam", "room": "main" }
+```
+
+## Media Library API
+
+| Method & Path                  | Description                                       |
+| ------------------------------ | ------------------------------------------------- |
+| `GET /api/admin/media`         | List media                                        |
+| `POST /api/admin/media`        | Multipart upload (legacy), form field name `file` |
+| `GET /api/admin/media/{id}`    | Get item                                          |
+| `PUT /api/admin/media/{id}`    | Update item                                       |
+| `DELETE /api/admin/media/{id}` | Delete item                                       |
+
+PUT media body:
+
+```json
+{ "status": "ready", "title": "My Clip", "tags": "music,live" }
+```
+
+## Resumable Upload API
+
+Max file size: **2GB** · Default chunk size: **8MB**
+
+| Method & Path                                                      | Description                                                       |
+| ------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| `POST /api/admin/media/uploads`                                    | Initialize or resume session                                      |
+| `GET /api/admin/media/uploads/{uploadId}`                          | Check upload status                                               |
+| `PUT /api/admin/media/uploads/{uploadId}/chunk?index={chunkIndex}` | Upload chunk (`Content-Type: application/octet-stream`)           |
+| `POST /api/admin/media/uploads/{uploadId}/complete`                | Complete upload → returns media listing (`files` + `generatedAt`) |
+
+Initialize request:
+
+```json
+{
+  "uploadId": "optional-existing-id",
+  "fileName": "clip.mp4",
+  "fileSize": 123456789,
+  "mimeType": "video/mp4",
+  "chunkSize": 8388608,
+  "totalChunks": 15
+}
+```
+
+Status envelope (returned by init, status check, and chunk upload):
+
+```json
+{
+  "uploadId": "hex-token",
+  "fileName": "clip.mp4",
+  "fileSize": 123456789,
+  "chunkSize": 8388608,
+  "totalChunks": 15,
+  "uploadedChunks": 3,
+  "progress": 20
+}
+```
+
+## Metrics & Health
+
+- `GET /metrics` (chat) — Prometheus: connected clients, stored messages, moderation actions, Redis indicators, active admin sessions, build info
+- `GET /health` — chat service, playout service, and nginx reverse proxy each expose it
+
+## HTTP Status Conventions
+
+| Code | Meaning               | When                                                        |
+| ---- | --------------------- | ----------------------------------------------------------- |
+| 200  | OK                    | Successful GET, PUT, action                                 |
+| 201  | Created               | Successful POST (upload init, override created)             |
+| 204  | No Content            | Successful DELETE, CORS preflight                           |
+| 400  | Bad Request           | Malformed JSON, missing required fields, invalid input      |
+| 401  | Unauthorized          | Missing/expired admin session                               |
+| 403  | Forbidden             | Valid session, insufficient permissions                     |
+| 404  | Not Found             | Resource doesn't exist                                      |
+| 405  | Method Not Allowed    | Wrong method for endpoint                                   |
+| 409  | Conflict              | Schedule override overlap, upload ID mismatch               |
+| 413  | Payload Too Large     | Upload exceeds 2 GB limit                                   |
+| 422  | Unprocessable         | File fails normalization check (codec, fps, resolution)     |
+| 429  | Too Many Requests     | Rate limit exceeded (chat, WS, login)                       |
+| 500  | Internal Server Error | Unexpected server failure                                   |
+| 503  | Service Unavailable   | Redis unavailable for user actions, playout health degraded |
+
+## Rate Limiting
+
+Per-IP (from `X-Forwarded-For` or `RemoteAddr`) unless noted.
+
+| Resource              | Limit                              | Window                                   | Response                                               |
+| --------------------- | ---------------------------------- | ---------------------------------------- | ------------------------------------------------------ |
+| Chat messages         | `CHAT_RATE_LIMIT_MAX` (default 10) | `CHAT_RATE_LIMIT_WINDOW_S` (default 10s) | 429 + `{"type":"system","text":"Rate limit exceeded"}` |
+| WebSocket connections | 5                                  | 60s                                      | 429 + `"too many connections from this IP"`            |
+| Admin login           | 5                                  | 5min                                     | 429 + `"too many login attempts, try again later"`     |
+
+Rate limit headers (applicable responses): `X-RateLimit-Limit` (max requests/window), `Retry-After` (seconds until reset). 413 = payload too large; 500 = internal server error.

docs/COOLIFY.md

@@ -0,0 +1,148 @@
+# Coolify Deployment
+
+*Last Updated: 2026-08-28*
+
+Alternative deployment path for Linear Void using [Coolify](https://github.com/coollabsio/coolify/tree/v4.3.14) (v4.3.14), an open-source self-hostable PaaS that manages servers, apps, and databases over SSH. Drop-in alternative to the flows in [SETUP.md](./SETUP.md): local dev (`docker-compose.yml`) and test-lab/prod (`docker-compose.prod.yml` via Gitea Actions CD). Coolify deploys the same Compose stack through a web UI and its own Traefik reverse proxy for automatic HTTPS, domain routing, and one-click redeploys (no manual `DOCKER_HOST`).
+
+## Why Coolify
+
+- **Single control plane**: manage playout, chat, nginx, redis, db (plus exporters/monitoring) from one dashboard.
+- **Automatic TLS**: Let's Encrypt provisioning/renewal per app/domain, replacing the manual Cloudflare + nginx origin TLS setup for the app hostname.
+- **No vendor lock-in**: config lives on your server; containers keep running if you stop using Coolify — you only lose automation.
+- **Simpler cutover**: on Hetzner VPS provisioning, point Coolify at the new server and redeploy instead of editing CD `DOCKER_HOST`.
+
+> Replaces the *deployment orchestration* layer only. Cloudflare DNS, R2 media bucket, cache rules, and the edge Worker from [SETUP.md](./SETUP.md) are unchanged.
+
+## Prerequisites
+
+- Linux server with **Docker Engine** (any supported distro).
+- **SSH access** (root or passwordless `sudo`) from the Coolify install machine — Coolify provisions the target over SSH.
+- **2 GB RAM / 20 GB disk** minimum for Coolify itself (plus resources for the stack).
+- A domain pointed at the server for HTTPS (e.g. `linearvoid.tv`).
+- Ports `80` and `443` reachable for Traefik.
+- Gitea registry credentials (`CI_REGISTRY_USER` / `CI_REGISTRY_TOKEN`) if pulling prebuilt `playout`, `chat`, `nginx` images.
+
+## Installation
+
+Recommended on a dedicated server:
+
+```bash
+curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash
+```
+
+The installer boots a Docker-based Coolify instance and prints the URL and default credentials. Complete first-run setup in the dashboard. For non-interactive/offline installs, see the [installation docs](https://coolify.io/docs/installation) and [install script source](https://github.com/coollabsio/coolify/blob/v4.3.14/scripts/install.sh).
+
+## Add the Linear Void server
+
+1. **Servers → Add**.
+2. Choose your provider (or **Localhost** if Coolify runs on the same host as the stack).
+3. Provide SSH details; for a remote host Coolify validates and installs its agent.
+4. Confirm the server shows **Reachable** before creating resources.
+
+### Current topology (verified 2026-08-30)
+
+Active test-lab setup is **two-tier**:
+
+| Component | Host | Exposes | Docker TCP | Notes |
+|---|---|---|---|---|
+| **Coolify dashboard** | `192.168.88.18` | `https://coolify.allucanget.biz` via Cloudflare tunnel (`coolify-cloudflared`); dashboard at `8000` | No | Manages target servers over SSH |
+| **Deployment target** | `192.168.88.40` | `coolify-proxy` = Traefik on 80/443; port `8000` bound by Portainer, not Coolify | Yes | Per-server helpers (`coolify-proxy`, `coolify-sentinel`, `coolify-cloudflared`) + the stack via `docker-compose.prod.yml` (`linearvoid` compose project, 11 containers) |
+
+The main `coolify` app container runs only on the dashboard host `192.168.88.18`; Compose-resource services land on the target `192.168.88.40`. The dashboard host exposes no Docker TCP socket, so run the checks below against the **target** `192.168.88.40`:
+
+```bash
+./scripts/check-env.sh      # env/deployment health on target (containers, helpers, health)
+./scripts/check-tokens.sh   # Gitea registry, Cloudflare, R2, admin credential access
+```
+
+## Deploy the stack
+
+Deploy as a **Docker Compose** resource (not individual apps):
+
+1. **Projects → Add → Docker Compose**.
+2. Select the target server.
+3. In **Build Settings**, set the compose file source:
+   - **Git Repository** → point at `https://git.allucanget.biz/zwitschi/linearvoid.git`, compose file `docker-compose.prod.yml` (Coolify pulls on each redeploy).
+   - **Raw Compose** → paste `docker-compose.prod.yml` directly to manage manually.
+4. For the Git source, add the Gitea registry login as a **Deployment Key / environment secret** so `playout`, `chat`, `nginx` images can be pulled. Alternatively switch those services to `build:` blocks (as in `docker-compose.yml`) to build from source on the server.
+
+### Environment variables
+
+Map Linear Void's `.env` values into Coolify's **Environment Variables** tab:
+
+| Variable | Purpose |
+|---|---|
+| `DATABASE_URL` | `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable` |
+| `REDIS_URL` | `redis://redis:6379/0` |
+| `POSTGRES_PASSWORD` | DB password (used by `db` service) |
+| `ADMIN_USERNAME` / `ADMIN_PASSWORD` | Admin panel credentials |
+| `ADMIN_SESSION_TTL_HOURS` | Admin session lifetime |
+| `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` | Cloudflare R2 credentials |
+| `R2_BUCKET_NAME` / `R2_ENDPOINT` / `R2_REGION` | R2 bucket config (`R2_REGION=auto`) |
+| `MEDIA_DOMAIN` | `media.linearvoid.tv` |
+| `VITE_PUBLIC_APP_URL` | `https://linearvoid.tv` |
+| `VITE_PUBLIC_WS_URL` | `wss://linearvoid.tv/ws` |
+| `VITE_PUBLIC_HLS_URL` | `https://media.linearvoid.tv/hls/playlist.m3u8` |
+
+Keep internal service URLs on compose hostnames (`redis`, `db`) exactly as in `docker-compose.prod.yml`.
+
+### Persistent storage
+
+Named volumes (`redis-data`, `postgres-data`) and bind mounts under `./data` must be configured under **Persistent Storage** to survive redeploys:
+
+| Mount | Purpose |
+|---|---|
+| `data/playlist` | Playout playlist file |
+| `data/media` | Normalized source videos (read-only to playout) |
+| `data/hls` | Generated HLS manifests/segments |
+| `data/chat` | Chat service working data |
+| `data/slate` | Slate media |
+| `redis-data` | Redis append-only persistence |
+| `postgres-data` | PostgreSQL data directory |
+
+If Coolify doesn't auto-create the dirs, create them before first deploy:
+
+```bash
+mkdir -p data/playlist data/media data/hls data/chat
+```
+
+### Domains and proxy
+
+1. Assign the **nginx** service a public domain (e.g. `linearvoid.tv`); Traefik terminates TLS and forwards to `nginx`.
+2. Set **Ports Exposes** so Traefik targets the nginx port (`80` inside container, mapped from `${NGINX_PORT:-8082}:80`).
+3. Do **not** publicly expose playout (`8081`) or chat (`3000`) health ports — keep them internal and route through nginx.
+4. For `media.linearvoid.tv`, keep serving HLS from the R2 custom domain (per SETUP.md) rather than routing through Coolify, so segments stay on Cloudflare's edge cache.
+
+## Post-deploy verification
+
+- `docker compose ps` on the server shows all services healthy.
+- Playout health: `https://<host>/health` via nginx (internal `:8081/health`).
+- Chat health: internal `:3000/health`.
+- HLS written to `data/hls` and served from `media.linearvoid.tv`.
+- Chat WebSocket connects over `wss://linearvoid.tv/ws`.
+- Admin login works at `/admin` with configured credentials.
+
+## Monitoring
+
+Coolify exposes container logs/basic metrics per resource. The stack ships Prometheus + Grafana (`monitoring/`) plus nginx/redis exporters. To reach them via Coolify, expose Grafana on a restricted subdomain (e.g. `grafana.linearvoid.tv`) and keep Prometheus internal, mirroring SETUP.md access guidance.
+
+## Cutover from Gitea CD
+
+1. Deploy the stack as a Coolify compose resource (above).
+2. Point Cloudflare DNS for `linearvoid.tv` / `www` at the server IP (proxied).
+3. Disable (or keep as fallback) the `cd` job in the Gitea workflow so the two orchestrators don't fight over the same `DOCKER_HOST`.
+4. Keep the Gitea **CI** (build + push images) job so Coolify keeps pulling `:latest` from the registry.
+
+## Troubleshooting
+
+- **Image pull fails**: set Gitea registry credentials in the compose secret store, or switch services to `build:` blocks.
+- **Healthchecks fail**: confirm `curl` exists in the built images (healthchecks rely on it).
+- **TLS errors**: check the domain's DNS points at the Coolify server and ports `80`/`443` are open.
+- **HLS not updating**: verify `data/hls` is writable and playout restarts cleanly; see SETUP.md normalization troubleshooting.
+- **Ports conflict**: Coolify's Traefik binds `80`/`443`; do not also map those to the host in the compose file.
+
+## Further reading
+
+- Coolify repo (v4.3.14): <https://github.com/coollabsio/coolify/tree/v4.3.14>
+- Coolify docs: <https://coolify.io/docs>
+- [DEPLOYMENT.md](./DEPLOYMENT.md) · [SETUP.md](./SETUP.md)

docs/DEPLOYMENT.md

@@ -0,0 +1,231 @@
+# Deployment Guide
+
+## Environments
+
+| Environment    | Host                       | Docker Target              | Purpose                                        |
+| -------------- | -------------------------- | -------------------------- | ---------------------------------------------- |
+| **Test Lab**   | `192.168.88.40` (internal) | `tcp://192.168.88.40:2375` | Integration testing, staging, CI/CD validation |
+| **Production** | Hetzner VPS (TBD)          | `tcp://<hetzner-ip>:2375`  | Public linearvoid.tv                           |
+
+**Current state (2026-08-06):** Test lab is active and receives automated CD deploys. Production Hetzner VPS is **not yet provisioned**. `cd.yml` and `docker-compose.prod.yml` target the test lab; switching to production only requires changing `DOCKER_HOST`.
+
+## Production Target (Hetzner)
+
+**Status: Not provisioned.** Plan documented and pipeline ready; only the VPS needs creation.
+
+### Planned Infrastructure
+
+- Provider: Hetzner Cloud, Region: Ashburn, VA (us-east)
+- Instance: CX22 (2 vCPU, 4 GB RAM, 40 GB SSD) or equivalent
+- OS: Ubuntu 24.04 LTS or Debian 12
+- Bandwidth: 20 TB included traffic/month; Estimated cost: ~€7–10/month base
+
+### Cutover Plan
+
+1. Provision Hetzner VPS
+2. Add production secrets to Gitea (`CI_PROD_*` prefix)
+3. Update `DOCKER_HOST` in CD workflow to Hetzner public IP
+4. Trigger deploy → validate health checks
+5. Update Cloudflare A record `linearvoid.tv` → Hetzner IP
+6. Enable HTTPS, WAF, cache rules on production zone
+7. Decommission test lab as public target
+
+### Production Preflight (minimum readiness gate)
+
+1. Verify Hetzner host reachable over SSH and Docker remote API TLS works for the Gitea runner
+2. Confirm all production secrets exist under `CI_PROD_*` prefix
+3. Confirm `linearvoid.tv`, `www.linearvoid.tv`, `media.linearvoid.tv` DNS targets match intended phase
+4. Complete manual Cloudflare/UptimeRobot checklist (see `docs/operations/cloudflare-uptimerobot-checklist.md`)
+5. Run production smoke path end-to-end: viewer SPA, HLS playback, chat connect, admin login, upload, playlist save, playout health
+6. Verify rollback possible before final DNS switch
+
+### Firewall / Security Group
+
+| Port | Source                | Purpose                        |
+| ---- | --------------------- | ------------------------------ |
+| 22   | Admin IPs             | SSH management                 |
+| 80   | 0.0.0.0/0             | HTTP (redirect to HTTPS)       |
+| 443  | 0.0.0.0/0             | HTTPS (nginx)                  |
+| 2375 | Gitea runner IP only  | Docker remote API (TLS)        |
+| 9090 | Admin IPs or internal | Prometheus (or tunnel via SSH) |
+| 3001 | Admin IPs or internal | Grafana (or tunnel via SSH)    |
+
+### Pipeline Readiness
+
+| Workflow             | Trigger           | Purpose                                                                           |
+| -------------------- | ----------------- | --------------------------------------------------------------------------------- |
+| `ci.yml`             | Push to `main`    | Lint, build frontend, vet Go, build & push images (`:latest`, `:main`)            |
+| `cd.yml`             | Push to `main`    | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI          |
+| `release.yml`        | Tag push `*.*.*`  | Build & push versioned images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release |
+| `workers-deploy.yml` | After CI succeeds | Deploy frontend to Cloudflare Workers                                             |
+
+CI and CD run simultaneously on every push to `main`. Deploy pulls whatever `:latest` images are available at that moment. `cd.yml` uses `DOCKER_HOST` to target the host:
+
+```bash
+# Test lab (current)
+DOCKER_HOST=tcp://192.168.88.40:2375
+
+# Production (when provisioned)
+DOCKER_HOST=tcp://<hetzner-public-ip>:2375
+```
+
+No pipeline code changes needed to switch targets.
+
+## Target Topology
+
+- Host: Linux server with Docker Engine
+- Reverse proxy: nginx container (linearvoid-nginx)
+- Core services: playout, chat, redis, postgres
+- Observability: prometheus, grafana
+- CDN/edge: Cloudflare
+
+## Prerequisites
+
+- Docker Engine + Docker Compose plugin
+- Network access to git.allucanget.biz
+- Valid `.env` file with production values
+- DNS configured for `linearvoid.tv` (and `media.linearvoid.tv` if split media domain used)
+
+## Environment File
+
+`.env` requires at minimum:
+
+- `DATABASE_URL` — PostgreSQL connection string
+- `REDIS_URL` — Redis connection string
+- `ADMIN_USERNAME` / `ADMIN_PASSWORD` — admin dashboard credentials
+- `ADMIN_SESSION_TTL_HOURS` — session expiry (default 12)
+- `VITE_PUBLIC_APP_URL` / `VITE_PUBLIC_WS_URL` / `VITE_PUBLIC_HLS_URL` — frontend URLs
+
+**Cloudflare R2 (required for HLS segment sync to edge):**
+
+- `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY`
+- `R2_BUCKET_NAME` (e.g. `linearvoid-media`)
+- `R2_ENDPOINT` — S3-compatible endpoint URL
+- `R2_REGION` — set to `auto`
+
+**Cloudflare (optional, for Workers):**
+
+- `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID`
+- `MEDIA_DOMAIN` — split media domain (e.g. `media.linearvoid.tv`)
+
+See `.env.example` and `SETUP.md` for full variable reference.
+
+### Gitea Secrets
+
+`cd.yml` injects sensitive values from Gitea secrets into `.env` at deploy time. Configure in the Gitea repository:
+
+`DATABASE_URL`, `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`, `R2_ENDPOINT`, `R2_ADMIN_ACCESS_KEY_ID` (optional), `R2_ADMIN_SECRET_ACCESS_KEY` (optional), `R2_ADMIN_ENDPOINT` (optional), `CLOUDFLARE_API_TOKEN` (optional), `CLOUDFLARE_ACCOUNT_ID` (optional), `CI_REGISTRY_USER`, `CI_REGISTRY_TOKEN`
+
+## Pull-and-Run Deployment
+
+Images are built/pushed automatically by CI and release workflows. Every push to `main` triggers CI (`:main`, `:latest`) and CD (deploys `:latest` to test lab) in parallel. Semantic version tags (`*.*.*`, e.g. `1.0.9`) trigger the release workflow (`:X.Y.Z`, `:X.Y`, `:latest` + Gitea Release).
+
+```bash
+docker login git.allucanget.biz
+docker compose -f docker-compose.prod.yml pull
+docker compose -f docker-compose.prod.yml up -d --remove-orphans
+```
+
+## First-Time or Recovery Provisioning
+
+```bash
+mkdir -p data/chat data/playlist data/media data/hls
+docker volume ls
+docker network ls
+docker compose -f docker-compose.prod.yml up -d
+```
+
+## Health Verification
+
+```bash
+docker compose -f docker-compose.prod.yml ps
+```
+
+Endpoint checks:
+
+- App: `http://{host}:8080/`
+- Nginx health: `http://{host}:8080/health`
+- Chat health: `http://{host}:3000/health`
+- Playout health: `http://{host}:8081/health`
+- Prometheus: `http://{host}:9090`
+- Grafana: `http://{host}:3001`
+
+Domain checks:
+
+- `https://linearvoid.tv`
+- `https://linearvoid.tv/admin`
+- `https://linearvoid.tv/metrics`
+
+## Zero/Low-Downtime Update Pattern
+
+1. Pull newest images.
+2. Recreate changed services only:
+
+   ```bash
+   docker compose -f docker-compose.prod.yml pull
+   docker compose -f docker-compose.prod.yml up -d nginx chat playout
+   ```
+
+3. Re-run health checks.
+
+## Rollback
+
+If new images are unhealthy:
+
+1. Pin previous tags in `docker-compose.prod.yml`.
+2. Pull pinned tags.
+3. Restart impacted services:
+
+```bash
+docker compose -f docker-compose.prod.yml pull
+docker compose -f docker-compose.prod.yml up -d nginx chat playout
+```
+
+## Operational Tasks
+
+```bash
+# View logs
+docker compose -f docker-compose.prod.yml logs -f nginx chat playout
+
+# Restart one service
+docker compose -f docker-compose.prod.yml restart chat
+
+# Stop stack (keep data)
+docker compose -f docker-compose.prod.yml down
+
+# Stop stack — destructive (remove data)
+docker compose -f docker-compose.prod.yml down -v
+```
+
+## Nginx and Proxy Considerations
+
+- If an external proxy (e.g. Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx (see `infrastructure/nginx/nginx.conf`).
+- For resumable admin uploads, ensure `client_max_body_size` supports chunk requests in both proxy layers.
+
+## Security Baseline
+
+- Use a strong `ADMIN_PASSWORD` and rotate regularly.
+- Keep Docker host access restricted.
+- Prefer HTTPS/WSS through Cloudflare.
+- Restrict exposed ports if only proxy access is needed.
+
+## Common Deployment Pitfalls
+
+- Missing frontend build artifacts in local-only compose workflows.
+- Wrong registry credentials or missing login.
+- Misaligned domain env vars (app/ws/hls) causing mixed-origin errors.
+
+## Troubleshooting
+
+| Symptom                    | Check                                         | Fix                                                           |
+| -------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| Service not starting       | `docker logs linearvoid-<svc> --tail 50`      | Check `.env` vars, volume mounts, port conflicts              |
+| Playout stall / slate mode | `curl http://<host>:8081/health` — mode=slate | Check playlist file, media paths, disk space                  |
+| Chat not connecting        | `curl http://<host>:3000/health`              | Check Redis: `docker exec linearvoid-redis redis-cli ping`    |
+| Admin 401 loop             | Cookie not sent                               | Verify `X-Forwarded-Proto: https`, nginx auth_request headers |
+| Upload fails (413)         | File too large                                | Check nginx `client_max_body_size` (should be 64m+)           |
+| HLS not playing            | `curl http://<host>/hls/playlist.m3u8`        | Check playout health, HLS dir permissions                     |
+| Prometheus no targets      | `curl http://<host>:9090/targets`             | Verify container network, scrape config                       |
+| Grafana no data            | Check datasource                              | Verify Prometheus URL `http://prometheus:9090` provisioned    |
+
+Additional notes: proxy-layer body size limits can return 413 on upload; health checks may fail before service warmup completes.

docs/MONITORING.md

@@ -52,6 +52,12 @@ Config: `monitoring/prometheus/prometheus.yml` (15s scrape interval)
 - **Linear Void app**: `monitoring/grafana/dashboard.json` — clients, messages, moderation, Redis, sessions, scrape health
 - **Prometheus ops**: `monitoring/grafana/dashboards/dashboard.json` — TSDB, CPU/memory, WAL, compactions, query latency
 
+## Metrics Checking
+
+See detailed scripts for querying Prometheus scrape targets:
+
+- [Linux/macOS](./infrastructure/monitoring/prometheus_curl.md)
+
 ## Key Metrics
 
 - `linearvoid_chat_connected_clients` — active WebSocket connections
@@ -72,20 +78,13 @@ Config: `monitoring/prometheus/prometheus.yml` (15s scrape interval)
 | Prometheus targets down | Check container network: all must be on `linearvoid-net`             |
 | Alert not firing        | Check Prometheus → Alerts tab, verify `rule_files` in prometheus.yml |
 
-### Grafana shows no data
+**Grafana no data**: ensure datasource points to `http://prometheus:9090`; confirm Prometheus is healthy; check dashboard query labels match active jobs.
 
-- Ensure datasource points to <http://prometheus:9090>.
+**High cardinality / slow queries**: reduce unneeded labels; limit expensive panels; tune retention and query windows.
-- Confirm Prometheus is healthy.
-- Check dashboard query labels match active jobs.
-
-### High cardinality or query slowness
-
-- Reduce unneeded labels.
-- Limit expensive dashboard panels.
-- Tune retention and query windows.
 
 ## Operational Recommendations
 
 - Keep alert thresholds tied to actual user impact.
 - Review dashboards after each release that changes endpoints or metrics names.
 - Periodically test alert routing and incident response flow.
+- Retention: **30 days** time-based plus **15GB** size cap (`--storage.tsdb.retention.time=30d --storage.tsdb.retention.size=15GB` on the `prometheus` service in `docker-compose.yml` and `docker-compose.prod.yml`). Increase the size cap before extending the time window so the TSDB does not hit the disk limit first.

docs/README.md

@@ -0,0 +1,55 @@
+# Docs Folder
+
+This folder contains the documentation for the Linear Void project. The documentation is organized into several markdown files, each covering different aspects of the project.
+
+## Architecture
+
+- [Architecture](architecture/README.md) - High-level system architecture and component interactions.
+
+## Infrastructure
+
+- Cloudflare
+  - [Cache Rules](./infrastructure/cloudflare/cache-rules.md) - Cache rules for Cloudflare Workers.
+  - [Account Troubleshooting](./infrastructure/cloudflare/cloudflare-account-troubleshooting.md) - Troubleshooting Cloudflare account issues.
+- Monitoring
+  - [Prometheus CURL](./infrastructure/monitoring/prometheus_curl.md) - Prometheus metrics endpoint testing with curl and jq. Doocumentation of available metrics and their meanings.
+
+## API
+
+- [API](API.md) - Implemented WebSocket and REST API reference.
+
+## Deployment
+
+- [Deployment](DEPLOYMENT.md) - Production deployment and operational runbook.
+
+## Monitoring
+
+- [Monitoring](MONITORING.md) - Metrics, dashboards, and monitoring troubleshooting.
+
+## Security
+
+- [Security](SECURITY.md) - Security model, controls, and hardening baseline.
+
+## Setup
+
+- [Setup](SETUP.md) - Test lab setup, local development, and CI/CD workflow.
+
+## Streaming
+
+- [Streaming](STREAMING.md) - Streaming architecture, playout, and delivery details.
+
+## Additional Resources
+
+- [Marketing](marketing/README.md) - Marketing materials and resources.
+- [Operations](operations/README.md) - Operational procedures and checklists.
+- [Incident Runbook](incident-runbook.md) - Incident response and disaster recovery procedures.
+
+## Other Documents
+
+- [CHANGELOG](../CHANGELOG.md) - Release notes and version history.
+- [CONTRIBUTING](../CONTRIBUTING.md) - Contribution guidelines and code of conduct.
+- [TODO](../.github/instructions/TODO.md) - Active implementation plan with checkboxes.
+- [Backlog](../.github/instructions/BACKLOG.md) - Consolidated list of all development tasks.
+- [Agents](../.github/AGENTS.md) - Instructions for agents and task management.
+- [Memory](../.github/MEMORY.md) - Session memory and development progress tracking.
+- [README](../README.md) - Project overview and high-level information.

docs/SETUP.md

@@ -0,0 +1,150 @@
+# Linear Void Setup Guide
+
+**Last Updated**: 2026-08-03
+
+Prerequisites, environment setup, and running the app locally and in production. Architecture: [`docs/architecture/README.md`](./architecture/README.md).
+
+## Prerequisites
+
+- **Docker + Docker Compose** — runs the full stack (playout, chat, nginx, redis, db, prometheus, grafana).
+- **Node.js 22+ / npm** — frontend dev and builds (`cd frontend && npm install && npm run build`).
+- **Go 1.25+** — working on the Go services outside Docker.
+- **FFmpeg** — playout HLS generation (`apt install ffmpeg`).
+- **Git**.
+- **Cloudflare account** — R2 storage + CDN.
+- **Gitea account** — image registry + CI/CD. Set Actions secrets at `https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets`: `CI_REGISTRY_USER`, `CI_REGISTRY_TOKEN` (scope `write:packages`), `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `DATABASE_URL`.
+- **Hetzner Cloud (optional, prod)** — US-East VPS (Ashburn, VA per ADR-001).
+
+## Network Environments
+
+Two distinct targets; know which one you're using.
+
+```mermaid
+flowchart LR
+    subgraph Test_Lab["Test Lab (192.168.88.0/24)"]
+        TEST_HOST["192.168.88.40<br/>Docker Engine :2375"]
+    end
+    subgraph Prod["Production (Hetzner — NOT provisioned)"]
+        PROD_HOST["Hetzner CX22 Ashburn, VA<br/>Public IP TBD"]
+    end
+    subgraph Gitea["Gitea CI/CD"]
+        CI["CI: build + push images"]
+        CD["CD: deploy via DOCKER_HOST"]
+    end
+    subgraph CF["Cloudflare"]
+        DNS["linearvoid.tv"]
+        R2["R2 Bucket"]
+    end
+    CD -->|"DOCKER_HOST=tcp://192.168.88.40:2375"| TEST_HOST
+    CD -.->|"DOCKER_HOST=tcp://&lt;hetzner-ip&gt;:2375 (when provisioned)"| PROD_HOST
+    TEST_HOST -->|"test traffic"| DNS
+    PROD_HOST -.->|"production traffic"| DNS
+    TEST_HOST --> R2
+    PROD_HOST -.-> R2
+```
+
+- **Test Lab (active):** internal `192.168.88.0/24`, host `192.168.88.40`; receives automated CD deploys from Gitea Actions. Used for staging validation.
+- **Production (pending):** Hetzner CX22, Ashburn VA — not yet provisioned. Compose/CD are ready; only `DOCKER_HOST` needs changing. See [DEPLOYMENT.md](./DEPLOYMENT.md).
+
+## Environment Setup
+
+1. `git clone https://git.allucanget.biz/zwitschi/linearvoid.git && cd linearvoid`
+2. `cp .env.example .env` then replace placeholders.
+3. Compose overrides: `docker-compose.yml` builds images locally and mounts `frontend/dist` into nginx; `docker-compose.prod.yml` pulls prebuilt images from Gitea.
+   - Internal URLs use compose hostnames: `REDIS_URL=redis://redis:6379/0`, `DATABASE_URL=postgres://linearvoid:<pw>@db:5432/linearvoid?sslmode=disable`.
+   - Public routing: `VITE_PUBLIC_APP_URL=https://linearvoid.tv`, `VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws`, `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`.
+4. Create data dirs: `mkdir -p data/playlist data/media data/hls data/chat`
+5. Optional: place normalized MP4s in `data/media/` and create `data/playlist/playlist.txt` (see ADR-001 for normalization).
+
+## Gitea Setup
+
+1. User with repo + registry access; generate a token (scope `write:packages`) stored as `CI_REGISTRY_TOKEN`.
+2. Set Actions secrets (see Prerequisites) to enable automated CI/CD and deploys.
+3. Set registry vars: `CI_REGISTRY_URL`, `CI_REGISTRY_NAMESPACE` (e.g. `zwitschi/linearvoid`), `CI_REGISTRY_USER`.
+4. Auth: `docker login git.allucanget.biz`.
+5. Local dev builds from source; prod pulls `playout`, `chat`, `nginx` images from the registry namespace. Verify `:latest` tags exist before rollout.
+
+## Cloudflare R2 Setup
+
+1. Create R2 bucket (e.g. `linearvoid-media`, matching `R2_BUCKET_NAME`); generate an access key pair → `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_REGION=auto`.
+2. S3 endpoint: `https://<account-id>.r2.cloudflarestorage.com` → `R2_ENDPOINT`.
+3. Attach `media.linearvoid.tv` as custom media domain → `MEDIA_DOMAIN`; add CORS allowing `https://linearvoid.tv` GET for HLS delivery.
+4. Point `linearvoid.tv` (+ `www` redirect) at the app entrypoint; keep `media.*` on R2. Proxied DNS, TLS **Full (strict)**.
+5. Apply the `.m4s`/`.m3u8` cache rules from [`cache-rules.md`](./infrastructure/cloudflare/cache-rules.md); enable Smart Tiered Cache; deploy the [`linearvoid-media` worker](../infrastructure/cloudflare/) on `media.linearvoid.tv` (replace the R2 bucket's direct custom-domain binding on that host) to enforce immutable segment caching + HLS CORS.
+6. Verify: `aws s3 ls --endpoint-url $R2_ENDPOINT`; check cache hit ratio after serving traffic.
+
+## Running the Application
+
+### Local development
+
+```bash
+docker compose up --build      # start all services
+docker compose down            # stop
+```
+
+Access: app/admin `https://linearvoid.tv` (via proxy) or `http://localhost`; WS `wss://linearvoid.tv/ws` / `ws://localhost/ws`. Health: playout `:8081/health`, chat `:3000/health`. Monitoring: Prometheus `:9090`, Grafana `:3001` (default `admin/admin`).
+
+Frontend dev (optional): `cd frontend && npm install && npm run dev` (http://localhost:5173, proxies API). For nginx-backed local runs: `npm run build` (nginx serves `frontend/dist`).
+
+### Test lab (remote Docker host)
+
+Deploy to `192.168.88.40` over Docker's TCP socket (port `2375`).
+
+Enable TCP on Alpine host — edit `/etc/conf.d/docker`:
+
+```bash
+DOCKER_OPTS="-H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375"
+```
+
+Then `rc-service docker restart`; verify with `netstat -tlnp | grep 2375`; allow port `2375` from `192.168.88.0/24` in the firewall.
+
+Deploy from a machine with the Docker CLI:
+
+```bash
+export DOCKER_HOST="tcp://192.168.88.40:2375"
+docker info                                   # confirm remote host
+docker compose -f docker-compose.prod.yml pull
+docker compose -f docker-compose.prod.yml up -d --remove-orphans   # registry images
+# or build from source: docker compose up -d --build
+unset DOCKER_HOST                             # back to local
+```
+
+Health: `http://192.168.88.40:8081/health` (playout), `:3000/health` (chat), nginx entrypoint `:8080`.
+
+### Coolify deployment
+
+Coolify replaces the Gitea CD `DOCKER_HOST` orchestration (Cloudflare DNS/R2/cache unchanged). Install (`curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash`), add the target server via SSH, create a Docker Compose resource from `docker-compose.prod.yml` (or the repo), configure env vars in Coolify's store, map persistent `data/` and named volumes, and assign `linearvoid.tv` to nginx for Traefik TLS. Full walkthrough: [`COOLIFY.md`](./COOLIFY.md).
+
+### Production setup
+
+1. Provision a Linux VPS (Docker, Compose, Git); open HTTP/HTTPS ports.
+2. `git clone … && cd linearvoid && cp .env.example .env`.
+3. Set production `.env`: strong `POSTGRES_PASSWORD`/`GRAFANA_PASSWORD`, compose-hostname internal URLs, `MEDIA_DOMAIN=media.linearvoid.tv`, public `VITE_PUBLIC_*` URLs. For local-only testing bypassing the proxy, use `http://localhost`/`ws://localhost/ws`/`http://localhost/hls/playlist.m3u8`.
+4. `mkdir -p data/playlist data/media data/hls data/chat`.
+5. Ensure `playout`, `chat`, `nginx` images exist in the registry; `docker login` from the VPS.
+6. Deploy: `docker compose -f docker-compose.prod.yml pull && docker compose -f docker-compose.prod.yml up -d`.
+7. Verify: `docker compose -f docker-compose.prod.yml ps`, health endpoints, HLS written to `data/hls`, media domain serves via Cloudflare.
+8. Harden: HTTPS in front of nginx (Cloudflare, `www` → apex), restrict Grafana/Prometheus to trusted IPs, run under systemd for auto-start.
+
+### Production (Hetzner VPS + Cloudflare)
+
+1. Provision CX22 in Ashburn, VA (ADR-001).
+2. Cloudflare: R2 bucket (`enam` hint), deploy the [`linearvoid-media` worker](../infrastructure/cloudflare/) on `media.linearvoid.tv` + cache rules, `linearvoid.tv`/`www` at the app entrypoint with `www`→apex redirect, Full (strict) TLS.
+3. Deploy from the project: `docker compose -f docker-compose.prod.yml up -d` (or pull from Gitea registry); manage under systemd.
+4. Monitoring: Grafana dashboards from `monitoring/grafana/`.
+
+See `docs/architecture/README.md` (arc42) and the ADRs for decisions and cost/scaling guidance (ADR-001).
+
+## Troubleshooting
+
+- **R2 upload fails** — check `.env` creds/bucket; `aws s3 ls --endpoint-url=$R2_ENDPOINT`.
+- **Normalization errors** — run `backend/playout/start-playout.sh` to see ffprobe output. Video must be H.264/AAC, 30 fps constant, 2s keyframes (ADR-001).
+- **Chat won't connect** — check Redis and WS URL; `/health` should return 200.
+- **Cache not working** — verify `.m4s` long-TTL / `.m3u8` short-TTL cache rules and hit ratio.
+- **Docker issues** — `docker compose logs`; check port conflicts.
+- **Admin interface** — `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `ADMIN_SESSION_TTL_HOURS` set; session-based login protects `/admin/` and `/api/admin/*`.
+- **Prod pull fails** — `docker login` to Gitea succeeded and image tags exist.
+
+## Further Reading
+
+Architecture: `docs/architecture/README.md` · Decisions: `docs/architecture/adr/` (ADR-001…007) · Contributing: `CONTRIBUTING.md` · Overview: root `README.md`.

docs/STREAMING.md

@@ -0,0 +1,189 @@
+# Streaming Pipeline
+
+Operational contract for Linear Void video ingest, playout, publication, caching, and browser playback. Deployment, chat, admin details live in `DEPLOYMENT.md`, `SETUP.md`, `API.md`.
+
+## Production flow
+
+```mermaid
+flowchart TD
+    A["Normalized MP4 assets"] --> B["Playlist and schedule"]
+    B --> C["Playout service and FFmpeg"]
+    C --> D["Local HLS staging"]
+    D --> E["R2 object storage"]
+    E --> F["Cloudflare edge"]
+    F --> G["hls.js or native HLS"]
+```
+
+The playout service is the timeline authority. It reads the ordered playlist, runs FFmpeg continuously, stages a live HLS window under `data/hls/`, and publishes complete objects to R2. Viewers read only the public R2 custom domain through Cloudflare:
+
+```text
+https://media.linearvoid.tv/hls/playlist.m3u8
+```
+
+Nginx `/hls/` is a local/test fallback, not the production origin. The SPA, admin API, and chat use `linearvoid.tv`; media uses `media.linearvoid.tv`.
+
+## Source-media contract
+
+Only validated files may enter the production playlist.
+
+| Property   | Required profile                                                        |
+| ---------- | ----------------------------------------------------------------------- |
+| Container  | MP4                                                                     |
+| Video      | H.264/AVC, `yuv420p`                                                    |
+| Resolution | 1280x720 or 1920x1080; avoid resolution changes within a playlist block |
+| Frame rate | Constant 30 fps                                                         |
+| GOP        | Closed, fixed 2 seconds: `-g 60 -keyint_min 60 -sc_threshold 0`         |
+| Audio      | AAC-LC, stereo, 48 kHz, 128–192 kbit/s                                  |
+
+The ingest gate uses `ffprobe` to reject incompatible codecs, variable frame rate, missing audio, invalid dimensions, or wrong keyframe cadence. Assets are immutable after acceptance; corrections create a new asset ID/object key.
+
+Reference normalization:
+
+```bash
+ffmpeg -i input.mov \
+  -c:v libx264 -preset medium -crf 21 \
+  -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
+  -pix_fmt yuv420p \
+  -c:a aac -b:a 160k -ar 48000 -ac 2 \
+  -movflags +faststart \
+  output-normalized.mp4
+```
+
+## Playlist and timeline
+
+- `data/playlist/playlist.txt`: one local media path per line; blank lines and `#` comments ignored.
+- Service validates the complete playlist before activating a revision.
+- Playlist edits are atomic and get a revision ID. The active FFmpeg run keeps its current item and adopts the new revision at the next item boundary.
+- All viewers follow the same live manifest; clients never calculate the schedule independently.
+- Schedule metadata derives from the same active revision/timeline so "now/next" agrees with the video.
+- When the last item ends, playout returns to the first unless an active schedule override says otherwise.
+
+## Playout and HLS packaging
+
+The playout service wraps FFmpeg, tracks the active item/revision, restarts failed processes, and exposes `/health` plus Prometheus metrics.
+
+| Setting          | Value                                                                    |
+| ---------------- | ------------------------------------------------------------------------ |
+| Protocol         | Standard live HLS, not LL-HLS                                            |
+| Segment format   | fMP4 (`.m4s`) with init segment; `.ts` may be supported during migration |
+| Segment target   | 2 seconds (`HLS_SEGMENT_DURATION=2`)                                     |
+| Live window      | 12 segments (`HLS_WINDOW_SIZE=12`), ~24 seconds                          |
+| Codec path       | Stream copy for conforming assets; no per-viewer transcoding             |
+| Expected latency | 15–35 seconds                                                            |
+
+Segment boundaries must align with keyframes; timestamps must stay monotonic across item boundaries. If FFmpeg cannot preserve a seamless timeline, insert `#EXT-X-DISCONTINUITY` and publish the corresponding new init segment.
+
+**Segment duration rationale**: 2s lowers latency and keeps the window small (12 × 2s = 24s) while staying above the manifest TTL (1–2s). The 2s GOP (30fps, `-g 60`) already matches the target, so segments cut cleanly on keyframes. Longer (4–6s) raises latency and window depth; shorter than 2s inflates segment/request overhead and R2 Class B ops with little gain.
+
+Every segment name is globally unique and never reused, including after restart or playlist loop — use a run/session ID plus a monotonically increasing media sequence:
+
+```text
+hls/r-20260807T170412Z/init-000001.mp4
+hls/r-20260807T170412Z/seg-000001234.m4s
+```
+
+A URL advertised as immutable must never later contain different bytes.
+
+## Safe publication to R2
+
+Order prevents a manifest referencing an unavailable segment:
+
+1. FFmpeg writes a segment to a temp local name and closes it.
+2. Publisher uploads the init segment (if new) and media segment to final immutable R2 keys.
+3. Verify upload success; record object size/checksum.
+4. Render the next manifest referencing only confirmed objects.
+5. Upload the manifest to a temp key, then replace `hls/playlist.m3u8` as the final commit step.
+
+Never upload an actively written segment or publish the manifest first. Use a single publisher (or fencing/leader election) so two workers can't update the live manifest concurrently.
+
+**Run-scoped manifest URIs.** Segments and the init file are stored run-scoped under `hls/r-{runID}/…`, so the live `hls/playlist.m3u8` must reference them with that run prefix. Before the final commit step, the publisher rewrites each bare relative media URI (segments plus `#EXT-X-MAP:URI`) to `r-{runID}/<name>`. `publishManifest` in `backend/playout/src/playlist.go` does this via `rewriteManifestToRun`, using the same `runID` under which the segments were uploaded; the rewrite is skipped in slate mode (its manifest is served as-is). The published manifest therefore contains, e.g.:
+
+```m3u8
+#EXT-X-MAP:URI="r-20260807T170412Z/init.mp4"
+#EXTINF:2.000000,
+r-20260807T170412Z/seg-000001234.m4s
+```
+
+The `linearvoid-media` Worker on `media.linearvoid.tv` is a faithful path→R2 mapper and serves these run-scoped paths directly; it does **not** rewrite URIs at serve time.
+
+`data/hls/` is regenerable staging. Source media, playlist revisions, and schedule state are authoritative; generated HLS is not backed up as application state.
+
+## Cache contract
+
+| Objects                    | Edge policy                 | Browser policy                          | Required headers/behavior                                                    |
+| -------------------------- | --------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
+| `.m4s`, `.ts`, init `.mp4` | Cache eligible; TTL 1 year  | TTL 1 year                              | `Cache-Control: public, max-age=31536000, immutable`; full path in cache key |
+| Live `.m3u8`               | Cache eligible; edge TTL 2s | Do not retain beyond freshness interval | `Cache-Control: public, max-age=1, s-maxage=2, must-revalidate`              |
+| Versioned JS/CSS           | Cache eligible; TTL 1 year  | TTL 1 year                              | Content-hashed filenames and `immutable`                                     |
+
+Further rules:
+
+- No query-string cache busters on segment URLs; uniqueness belongs in the path.
+- Cache keys preserve hostname and full path; ignore only explicitly approved tracking params.
+- HLS responses need `Access-Control-Allow-Origin: https://linearvoid.tv` (or reviewed allowlist), `GET`/`HEAD`/`OPTIONS`, and correct MIME types.
+- Enable Smart Tiered Cache for `media.linearvoid.tv` to cut R2 reads on regional misses.
+- Purge manifests when necessary, never immutable segments during normal operation.
+- Retain expired-window segments at least max manifest TTL + retry/grace time; practical minimum 1 hour; lifecycle deletion may run later per storage policy.
+
+Validation:
+
+```bash
+curl -I https://media.linearvoid.tv/hls/playlist.m3u8
+curl -I https://media.linearvoid.tv/hls/<segment>.m4s
+```
+
+The manifest must refresh within seconds; repeated segment requests should progress `CF-Cache-Status: MISS` → `HIT`, keep the same ETag/content length, and carry the immutable cache header.
+
+## Player behavior
+
+SPA uses native HLS where supported, hls.js elsewhere.
+
+- Firefox has no native HLS → hls.js/MSE path; fMP4 (`.m4s` + init) is supported. Autoplay needs `muted` + `playsinline`, already set on the `<video>` element.
+- Start at the live edge with a conservative buffer; do not seek to playlist start.
+- Treat the manifest as the sync source; target ~3 segments behind the newest unless testing supports a smaller margin.
+- Recover transient network/media errors with bounded retries + exponential backoff.
+- On fatal hls.js network error, reload the manifest; on fatal media error, attempt media recovery once before recreating the player.
+- If tab suspension/drift leaves playback materially behind the target, seek forward rather than play the backlog.
+- Surface a clear reconnecting state; never silently loop stale media.
+- Schedule/chat timestamps should account for measured player latency, not wall-clock playout.
+
+## Failure and recovery
+
+The service retries an item failure with bounded backoff. Past the failure threshold it switches to a pre-normalized looping slate and reports `mode=slate`, periodically retrying normal playout, returning only after a segment and committed manifest publish successfully.
+
+On process/host restart:
+
+- create a new run/session ID and continue with unique segment paths;
+- resume from schedule-derived current position when reliable state exists, else start the current playlist item;
+- never overwrite old segment objects;
+- keep the last valid manifest available until the replacement is playable;
+- emit a discontinuity when timeline continuity isn't guaranteed.
+
+`/health` must report more than "process running": at least mode (`live`/`slate`/`starting`/`degraded`), active item, playlist revision, run ID, last segment sequence/time, last successful R2 publication, consecutive failures, uptime. Mark unhealthy if the manifest or media sequence hasn't advanced for more than two segment durations.
+
+## Monitoring and acceptance
+
+Monitor/alert on: manifest age and media-sequence advancement; time since last published segment; FFmpeg restarts and consecutive failures; live/slate mode; R2 upload latency/errors; segment 404/5xx and manifest/segment latency; Cloudflare cache-hit ratio, origin requests, R2 Class B ops; player startup, fatal errors, rebuffer ratio, live-edge drift; local staging disk usage.
+
+A release is streaming-ready only when: one full playlist boundary plays without timestamp errors; the manifest never references a missing object; a second viewer joins the same timeline; cache headers match the table; a forced FFmpeg failure activates slate; and normal playout recovers without reusing an object URL.
+
+## Required configuration
+
+| Variable                                   | Purpose                               |
+| ------------------------------------------ | ------------------------------------- |
+| `PLAYLIST_PATH`                            | Active playlist file                  |
+| `HLS_SEGMENT_DURATION`                     | Target segment duration; baseline `2` |
+| `HLS_WINDOW_SIZE`                          | Manifest window; baseline `12`        |
+| `R2_ENDPOINT`, `R2_REGION`                 | S3-compatible publication endpoint    |
+| `R2_BUCKET_NAME`                           | Media bucket                          |
+| `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY` | Write credentials, publisher only     |
+| `R2_KEEP_RUNS`                             | Run folders to retain (default `2`)   |
+| `R2_MAX_RETENTION_BYTES`                   | Max bytes across run folders (10 GiB) |
+| `MEDIA_DOMAIN`                             | Public R2 custom domain               |
+| `VITE_PUBLIC_HLS_URL`                      | Public live manifest URL              |
+
+Production values: `MEDIA_DOMAIN=media.linearvoid.tv`, `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`. Local fallback may use `http://localhost/hls/playlist.m3u8`.
+
+## Explicitly deferred
+
+ABR ladders, LL-HLS, DVR/catch-up, multi-origin playout, and regional chat affinity are outside the v1 contract. Adding any requires an ADR and an update to this document.

docs/architecture/adr/ADR-001.md

@@ -69,7 +69,7 @@ Adopt a **self-managed US-East playout + Cloudflare R2 + edge-cached HLS** archi
 
 ### 3. Frontend
 
-- Static SPA (HTML/CSS/JS + Tailwind + Alpine.js or vanilla) hosted on Cloudflare Pages or same VPS/Nginx.
+- Static SPA (HTML + custom CSS + vanilla JS) hosted on Cloudflare Workers or same VPS/Nginx.
 - Video player: `hls.js` (Chromium/Firefox) or native HLS (Safari). Single live `master.m3u8`.
 - Embedded chat sidebar with room switcher, private DMs, now-playing overlay.
 
@@ -82,7 +82,7 @@ Adopt a **self-managed US-East playout + Cloudflare R2 + edge-cached HLS** archi
 
 ### 5. Infrastructure Summary & Cost Model
 
-- **Primary**: Hetzner Ashburn VPS (playout + chat + Nginx) + Cloudflare R2 + Pages.
+- **Primary**: Hetzner Ashburn VPS (playout + chat + Nginx) + Cloudflare R2 + Workers.
 - **Monitoring**: MediaMTX/SRS dashboard, UptimeRobot, systemd logs, Cloudflare analytics.
 - **Backup**: Weekly R2/S3-compatible snapshots of playlist, DB, config.
 - **Fallback**: Emergency slate/loop playlist, automated restart.

docs/architecture/adr/ADR-003-tech-stack.md

@@ -25,7 +25,7 @@ We must explicitly document language/runtime choices per module and the assumpti
 
 | Layer               | Technology                                 | Language                | Rationale                                                                                                              |
 | ------------------- | ------------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Frontend SPA**    | HTML + Tailwind + Alpine.js + hls.js       | TypeScript / JavaScript | Minimal bundle, excellent HLS support, fast iteration. Vite for build.                                                 |
+| **Frontend SPA**    | HTML + custom CSS + vanilla JS + hls.js    | TypeScript / JavaScript | Minimal bundle, excellent HLS support, fast iteration. Vite for build.                                                 |
 | **Playout Service** | FFmpeg + MediaMTX (or SRS)                 | Bash + Go (wrapper)     | FFmpeg is the proven tool for continuous playlist HLS. Go wrapper for reliability and monitoring.                      |
 | **Chat Backend**    | Go (preferred) or Node.js + Socket.io      | Go                      | High-performance WebSockets, low memory, excellent Redis/PostgreSQL clients. Node.js acceptable for rapid prototyping. |
 | **Shared Code**     | TypeScript definitions + Go structs        | TS + Go                 | Clear contracts between frontend and backend.                                                                          |
@@ -38,7 +38,7 @@ We must explicitly document language/runtime choices per module and the assumpti
 
 1. All video assets **must** be normalized before being added to any playlist (H.264, AAC, 30 fps constant, 2s keyframes, CRF encoding).
 2. Deployment is **Docker-first**; services will be containerized.
-3. Cloudflare is the primary CDN and will be configured with specific [Cache Rules](../../../infrastructure/cloudflare/cache-rules.md).
+3. Cloudflare is the primary CDN and will be configured with specific [Cache Rules](../../infrastructure/cloudflare/cache-rules.md) for HLS segments and manifests.
 4. Chat does **not** require end-to-end encryption in v1 (separate ADR if needed).
 5. Single VPS origin initially; multi-region is a later evolution.
 6. Monitoring focuses on playout health, cache hit ratio, and R2 operation counts.

docs/architecture/adr/ADR-004-admin-video.md

@@ -19,7 +19,7 @@ This interface must be lightweight, secure, and integrated with the playout serv
 
 ## Decision Drivers
 
-1. **Lightweight & Maintainable** – Prefer server-rendered or minimal JS (HTMX + Tailwind) over heavy SPA frameworks to align with ADR-003's "lightweight" principle.
+1. **Lightweight & Maintainable** – Prefer server-rendered or minimal JS (HTMX + custom CSS) over heavy SPA frameworks to align with ADR-003's "lightweight" principle.
 2. **Security** – Strict authentication, file type/size validation, and R2 upload permissions.
 3. **Usability** – Drag-and-drop playlist editor, progress indicators for normalization and upload, real-time playout status.
 4. **Integration** – Must call playout service APIs for validation and playlist updates; upload directly to R2 with metadata.
@@ -31,7 +31,7 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 
 **Tech Stack (per ADR-003)**:
 
-- **Frontend**: HTMX + Tailwind CSS + Alpine.js (minimal JS, server-rendered HTML). Alternative: React if complex interactions are needed later.
+- **Frontend**: HTMX + custom CSS + minimal JS (server-rendered HTML). Alternative: React if complex interactions are needed later.
 - **Backend**: Go (or Node.js) API endpoints exposed by the playout service or a dedicated `backend/admin/` service.
 - **Authentication**: JWT or session-based (admin roles only). Use Cloudflare Access or simple OAuth for production.
 - **File Handling**: Upload → validate with ffprobe (codec, fps, keyframes, duration) → normalize if needed → store in R2 with metadata.
@@ -48,7 +48,7 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 
 **Folder Placement** (per ADR-002):
 
-- `frontend/admin/` – Admin-specific HTML/JS components (HTMX + Tailwind).
+- `frontend/admin/` – Admin-specific HTML/JS components (HTMX + custom CSS).
 - `backend/admin/` – Dedicated API handlers for validation, playlist updates, and configuration (or extend playout/chat services).
 - Protected route in nginx with authentication (JWT or Cloudflare Access).
 - Documentation and API specs added to `docs/architecture/`.
@@ -95,7 +95,7 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 
 - ADR-001: Normalization requirements, HLS playout, R2 usage.
 - ADR-002: Folder structure (admin UI belongs under frontend or a protected route).
-- ADR-003: Lightweight frontend preference (HTMX/Tailwind over heavy frameworks).
+- ADR-003: Lightweight frontend preference (HTMX/custom CSS over heavy frameworks).
 - arc42 documentation: Building Block View (admin as part of the overall system).
 
 This ADR ensures all admin interface decisions are documented before code is written.

docs/architecture/adr/ADR-005-admin-moderation-analytics.md

@@ -17,7 +17,7 @@ These interfaces must be secure, auditable, and integrated with the chat backend
 
 ## Decision Drivers
 
-1. **Consistency** – Use the same lightweight tech stack decided in ADR-004 (HTMX + Tailwind + Alpine.js) to avoid introducing new frameworks.
+1. **Consistency** – Use the same lightweight tech stack decided in ADR-004 (HTMX + custom CSS + vanilla JS) to avoid introducing new frameworks.
 2. **Security & Auditability** – All actions must require admin authentication and be logged immutably.
 3. **Real-time Needs** – Moderation dashboard should show live chat activity (WebSocket integration).
 4. **Simplicity** – Analytics should use existing Prometheus/Grafana data where possible rather than building a duplicate system.
@@ -29,7 +29,7 @@ Extend the admin interface started in ADR-004 with additional protected sections
 
 **Tech Stack (consistent with ADR-003 and ADR-004)**:
 
-- **Frontend**: HTMX + Tailwind + Alpine.js for all admin pages. Shared layout with sidebar navigation.
+- **Frontend**: HTMX + custom CSS + vanilla JS for all admin pages. Shared layout with sidebar navigation.
 - **Backend**: Go API endpoints (protected by JWT/session middleware) in `backend/admin/` or extended from the chat/playout services.
 - **Authentication**: Role-based (admin, moderator, viewer). Use Cloudflare Access or JWT with short expiry for production.
 - **Data Sources**:
@@ -54,7 +54,7 @@ Extend the admin interface started in ADR-004 with additional protected sections
 
 ## Rationale
 
-- Reusing HTMX/Tailwind from ADR-004 keeps the admin interface lightweight and consistent.
+- Reusing HTMX/custom CSS from ADR-004 keeps the admin interface lightweight and consistent.
 - Centralizing admin functionality under `/admin/` reduces maintenance overhead.
 - Leveraging Prometheus/Grafana for analytics avoids duplicating metrics collection.
 - Immutable audit logging supports future compliance and moderation review (key requirement for a public chat system).
@@ -94,7 +94,7 @@ Extend the admin interface started in ADR-004 with additional protected sections
 
 - ADR-001: Chat features, moderation requirements, monitoring needs.
 - ADR-002: Folder structure – admin UI belongs under `frontend/admin/`.
-- ADR-003: Lightweight frontend (HTMX/Tailwind) and Go backend preference.
+- ADR-003: Lightweight frontend (HTMX/custom CSS) and Go backend preference.
 - ADR-004: Video admin interface (shared layout and authentication approach).
 - arc42 documentation: Cross-cutting Concepts (security, monitoring) and Building Block View (admin as extension of the system).
 

docs/incident-runbook.md

@@ -4,155 +4,101 @@ Triage order for Linear Void incidents. Work top-to-bottom — each tier depends
 
 ## Triage Order
 
-1. Edge Reachability (Cloudflare)
+1. **Edge Reachability** (Cloudflare)
-2. Origin Health (VPS/Docker)
+2. **Origin Health** (VPS/Docker)
-3. Playout Progression (HLS)
+3. **Playout Progression** (HLS)
-4. Chat Connectivity (WebSocket)
+4. **Chat Connectivity** (WebSocket)
-5. Data-Plane (Redis/DB)
+5. **Data-Plane** (Redis/DB)
 
 ## 1. Edge Reachability (Cloudflare)
 
 **Symptoms:** `linearvoid.tv` not resolving, SSL errors, 5xx from Cloudflare.
 
 ```bash
-# Check DNS
 dig linearvoid.tv
 dig www.linearvoid.tv
-
-# Check Cloudflare status
 curl -I https://linearvoid.tv/health
 ```
 
-**Common causes:**
+**Common causes:** DNS misconfiguration (A record → wrong IP); Cloudflare proxy disabled (grey cloud exposes origin); SSL certificate expired (Cloudflare → SSL/TLS); Cloudflare outage ([cloudflarestatus.com](https://www.cloudflarestatus.com)).
 
-- DNS misconfiguration (A record pointing to wrong IP)
+**Mitigation:** Verify A record points `linearvoid.tv` → origin IP (proxied, orange cloud). Bypass Cloudflare temporarily:
-- Cloudflare proxy disabled (grey cloud → origin exposed directly)
-- SSL certificate expired (check Cloudflare dashboard → SSL/TLS)
-- Cloudflare outage → check [https://www.cloudflarestatus.com](https://www.cloudflarestatus.com)
 
-**Mitigation:**
+```bash
-
+curl -H "Host: linearvoid.tv" http://<origin-ip>/health
-- Verify A record: `linearvoid.tv` → origin IP (proxied, orange cloud)
+```
-- Bypass Cloudflare temporarily: `curl -H "Host: linearvoid.tv" http://<origin-ip>/health`
 
 ## 2. Origin Health (VPS/Docker)
 
-**Symptoms:** Cloudflare returns 502/504, containers down.
+**Symptoms:** Cloudflare 502/504, containers down.
 
 ```bash
-# Remote Docker (test lab)
 docker -H tcp://192.168.88.40:2375 ps
 docker -H tcp://192.168.88.40:2375 logs linearvoid-nginx --tail 50
-
-# Direct health check
 curl http://192.168.88.40/health
 ```
 
-**Common causes:**
+**Common causes:** Host disk full (`df -h`); Docker daemon stopped (`systemctl status docker`); container restart loop (`docker ps -a --filter "status=exited"`); OOM (`dmesg | grep -i oom`).
-
-- Host out of disk space: `df -h`
-- Docker daemon stopped: `systemctl status docker`
-- Container restart loop: `docker ps -a --filter "status=exited"`
-- Resource exhaustion (OOM): `dmesg | grep -i oom`
 
 **Mitigation:**
 
-- Restart stack: `docker compose -f docker-compose.prod.yml up -d`
+```bash
-- Free disk: `docker system prune -f`
+docker compose -f docker-compose.prod.yml up -d   # restart stack
-- Check logs per service: `docker logs linearvoid-<service> --tail 100`
+docker system prune -f                            # free disk
+docker logs linearvoid-<service> --tail 100       # per-service logs
+```
 
 ## 3. Playout Progression (HLS)
 
 **Symptoms:** Viewer sees slate or buffering, playlist not advancing.
 
 ```bash
-# Check playout health
+curl http://192.168.88.40:8081/health             # "mode": "live" or "slate"
-curl http://192.168.88.40:8081/health
-# Response includes "mode": "live" or "slate"
-
-# Check HLS output
 curl -I http://192.168.88.40/hls/playlist.m3u8
 ls -la data/hls/
-
-# Check playout logs
 docker logs linearvoid-playout --tail 100
 ```
 
-**Common causes:**
+**Common causes:** FFmpeg crash → slate fallback (health `degraded`); playlist empty/missing (`cat data/playlist/playlist.txt`); media file missing (`ls data/media/`); disk full → HLS segments can't write.
 
-- FFmpeg crash → slate fallback active (health shows `degraded`)
+**Mitigation:** Validate playlist entries and media paths; restart playout (`docker compose restart playout`); regenerate demo playlist if empty (see `backend/playout/start-playout.sh`).
-- Playlist file empty/missing: `cat data/playlist/playlist.txt`
-- Media file missing from playlist: `ls data/media/`
-- Disk full → HLS segments can't write
-
-**Mitigation:**
-
-- Verify playlist has valid entries
-- Check media files exist at paths in playlist
-- Restart playout: `docker compose restart playout`
-- Generate demo playlist if empty: see `backend/playout/start-playout.sh`
 
 ## 4. Chat Connectivity (WebSocket)
 
 **Symptoms:** Chat not loading, messages not sending, presence broken.
 
 ```bash
-# Check chat health
 curl http://192.168.88.40:3000/health
-
-# Test WebSocket
 wscat -c ws://192.168.88.40/ws?username=test&room=main
-
-# Check chat logs
 docker logs linearvoid-chat --tail 100
 ```
 
-**Common causes:**
+**Common causes:** Redis down → presence/rate-limiting degraded (chat still works); DB down → messages not persisting; port not exposed (`docker port linearvoid-chat`).
 
-- Redis down → presence/rate-limiting degraded (chat still works)
+**Mitigation:** Restart chat (`docker compose restart chat`); check Redis (`docker exec linearvoid-redis redis-cli ping`); check DB (`docker exec linearvoid-db pg_isready -U linearvoid`). Chat degrades gracefully without Redis — look for "Redis connection warning" in logs.
-- Database down → messages not persisting
-- Port not exposed: `docker port linearvoid-chat`
-
-**Mitigation:**
-
-- Restart chat: `docker compose restart chat`
-- Check Redis: `docker exec linearvoid-redis redis-cli ping`
-- Check DB: `docker exec linearvoid-db pg_isready -U linearvoid`
-- Chat works without Redis (graceful degradation) — check logs for "Redis connection warning"
 
 ## 5. Data-Plane (Redis/DB)
 
 **Symptoms:** Chat works but no persistence/presence, admin stats empty.
 
 ```bash
-# Redis
 docker exec linearvoid-redis redis-cli ping
 docker exec linearvoid-redis redis-cli info memory
-
-# PostgreSQL
 docker exec linearvoid-db pg_isready -U linearvoid
 docker exec linearvoid-db psql -U linearvoid -c "SELECT count(*) FROM messages;"
 ```
 
-**Common causes:**
+**Common causes:** Redis OOM (check `maxmemory`); PostgreSQL connection limit; disk full on volume mount.
 
-- Redis OOM (check `maxmemory` setting)
+**Mitigation:** Restart redis (`docker compose restart redis`, AOF persist enabled); restart db (`docker compose restart db`); restore from backup (see `scripts/verify-backups.sh`).
-- PostgreSQL connection limit reached
-- Disk full on volume mount
-
-**Mitigation:**
-
-- Redis: `docker compose restart redis` (AOF persist enabled)
-- PostgreSQL: `docker compose restart db`
-- Restore from backup: see `scripts/verify-backups.sh` for procedure
 
 ## Escalation
 
-| Severity | When                                 | Action                                             |
+| Severity | When                                 | Action                                      |
-| -------- | ------------------------------------ | -------------------------------------------------- |
+| -------- | ------------------------------------ | ------------------------------------------- |
-| Critical | Slate active >30min, complete outage | Trigger DR plan, provision fallback host           |
+| Critical | Slate active >30min, complete outage | Trigger DR plan, provision fallback host    |
-| Warning  | Redis down, high CPU >30min          | Investigate during business hours, restart service |
+| Warning  | Redis down, high CPU >30min          | Investigate business hours, restart service |
-| Info     | Single service blip                  | Monitor, no action unless recurring                |
+| Info     | Single service blip                  | Monitor; no action unless recurring         |
 
 ## Post-Incident
 
@@ -163,67 +109,52 @@ docker exec linearvoid-db psql -U linearvoid -c "SELECT count(*) FROM messages;"
 
 ## Quarterly Disaster Recovery Drill
 
-Goal: validate recovery targets under controlled host-loss simulation.
+Validate recovery targets under controlled host-loss simulation: **RPO ≤ 24h, RTO ≤ 60min**.
-
-**Recovery targets:** RPO <= 24h, RTO <= 60min.
 
 ### Prerequisites
 
-- Latest backup artifacts available from `scripts/backup-db.sh` and `scripts/backup-weekly.sh`
+- Latest backups from `scripts/backup-db.sh` and `scripts/backup-weekly.sh`
 - Operator access to Docker host and DNS controls
-- Current deployment variables available (`.env`, compose file, image tags)
+- Current deployment variables (`.env`, compose file, image tags)
 
-### Drill Scope
+### Scope
 
 - Simulate complete origin loss (all app containers unavailable)
 - Rebuild stack on clean host
 - Restore DB and media/playlist mounts
 - Verify viewer playback, chat, admin auth, monitoring targets
 
-### Drill Steps
+### Steps
 
 1. Record drill start timestamp and on-call participants.
 2. Capture pre-drill baseline:
-   - `curl -fsS http://<origin>/health`
+   ```bash
-   - `curl -fsS http://<origin>:3000/health`
+   curl -fsS http://<origin>/health
-   - `curl -fsS http://<origin>:8081/health`
+   curl -fsS http://<origin>:3000/health
-3. Simulate origin outage:
+   curl -fsS http://<origin>:8081/health
-   - `docker compose -f docker-compose.prod.yml down`
+   ```
-4. Provision clean recovery host (or clean test-lab VM) and copy deployment bundle.
+3. Simulate outage: `docker compose -f docker-compose.prod.yml down`
-5. Restore required data paths:
+4. Provision clean recovery host (or clean test-lab VM); copy deployment bundle.
-   - `data/playlist/`
+5. Restore data paths: `data/playlist/`, `data/media/`, `data/chat/`, `data/hls/` (optional warm cache).
-   - `data/media/`
-   - `data/chat/`
-   - `data/hls/` (optional warm cache)
 6. Restore database from latest backup dump.
-7. Start stack:
+7. Start stack: `docker compose -f docker-compose.prod.yml up -d`
-   - `docker compose -f docker-compose.prod.yml up -d`
+8. Validate health and runtime:
-8. Validate service health and runtime:
+   ```bash
-   - `docker ps --format "table {{.Names}}\t{{.Status}}"`
+   docker ps --format "table {{.Names}}\t{{.Status}}"
-   - `curl -fsS http://<origin>/health`
+   curl -fsS http://<origin>/health
-   - `curl -fsS http://<origin>/hls/playlist.m3u8 | head -n 5`
+   curl -fsS http://<origin>/hls/playlist.m3u8 | head -n 5
-   - `curl -fsS http://<origin>:9090/-/ready`
+   curl -fsS http://<origin>:9090/-/ready
-9. Validate app behavior:
+   ```
-   - Viewer SPA loads and HLS plays
+9. Validate app behavior: viewer SPA loads and HLS plays; WebSocket chat connects with message round-trip; admin login/session endpoint succeeds.
-   - WebSocket chat connects and message round-trip works
+10. Run backup integrity check: `scripts/verify-backups.sh`
-   - Admin login/session endpoint returns success
+11. Record drill end timestamp; compute measured RTO/RPO.
-10. Run backup integrity check:
-    - `scripts/verify-backups.sh`
-11. Record drill end timestamp and compute measured RTO/RPO.
 
 ### Pass/Fail Criteria
 
-- Pass if all core services healthy and functional in <= 60 minutes.
+- **Pass:** all core services healthy and functional in ≤ 60 min.
-- Pass if latest recoverable data point is <= 24 hours old.
+- **Pass:** latest recoverable data point ≤ 24 h old.
-- Fail if any critical path remains degraded (playout, chat, admin auth, monitoring).
+- **Fail:** any critical path remains degraded (playout, chat, admin auth, monitoring).
 
 ### Evidence Template
 
-Document each drill in incident tracker with:
+Record in incident tracker: date/time window; environment (test-lab, staging, production); backup artifact IDs and timestamps; measured RTO and RPO; issues found and remediation owner; follow-up ticket links.
-
-- Date/time window
-- Environment (test-lab, staging, production)
-- Backup artifact IDs and timestamps
-- Measured RTO and RPO
-- Issues found and remediation owner
-- Follow-up ticket links

docs/infrastructure/cloudflare/cloudflare-account-troubleshooting.md

@@ -0,0 +1,24 @@
+# Cloudflare Account Troubleshooting
+
+Reference for Cloudflare account and API token troubleshooting.
+
+Use `wrangler whoami` to verify the account ID and API token are valid, or query the Workers API at `https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/workers/scripts`.
+
+## Validate Cloudflare account and API token
+
+```bash
+# Validate Cloudflare account and API token in .env
+cd /path/to/linearvoid
+grep -E 'CLOUDFLARE_API_TOKEN|CLOUDFLARE_ACCOUNT_ID' .env
+
+# Test API token with wrangler
+npx wrangler whoami
+
+# Or verify with the Workers API directly
+export CLOUDFLARE_API_TOKEN="$(grep '^CLOUDFLARE_API_TOKEN=' .env | cut -d= -f2-)"
+export CLOUDFLARE_ACCOUNT_ID="$(grep '^CLOUDFLARE_ACCOUNT_ID=' .env | cut -d= -f2-)"
+
+# List all Workers for the account
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/scripts" \
+  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" -H "Content-Type: application/json"
+```

docs/infrastructure/monitoring/prometheus_curl.md

@@ -0,0 +1,62 @@
+# Prometheus scrape target metric names
+
+Here are ready‑to‑run **cURL** commands you can use to query each Prometheus scrape target and list the metric names they expose.  
+The Prometheus HTTP API endpoint `http://localhost:9090/api/v1/label/__name__/values` returns all metric names currently known for the target’s job/instance.
+
+## 1. Chat (`http://chat:3000/metrics`)
+
+[Browse `chat`](http://192.168.88.40:9090/api/v1/label/__name__/values?match[]={job=%22chat%22})
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="chat",instance="chat:3000"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#chat-metrics) for full output of all 20+ metric names exposed by the Chat service.
+
+## 2. NGINX exporter (`http://nginx-exporter:9113/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="nginx",instance="nginx-exporter:9113"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#nginx-metrics) for full output of all 40+ metric names exposed by the NGINX exporter.
+
+## 3. Node exporter (`http://node-exporter:9100/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="node",instance="node-exporter:9100"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#node-metrics) for full output of all 200+ metric names exposed by the Node exporter.
+
+## 4. Playout (`http://playout:8081/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="playout",instance="playout:8081"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#playout-metrics) for full output of all 10+ metric names exposed by the Playout service.
+
+## 5. Postgres exporter (`http://postgres-exporter:9187/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="postgres",instance="postgres-exporter:9187"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#postgres-metrics) for full output of all 100+ metric names exposed by the Postgres exporter.
+
+## 6. Prometheus itself (`http://prometheus:9090/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="prometheus",instance="prometheus:9090"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#prometheus-metrics) for full output of all 100+ metric names exposed by Prometheus itself.
+
+## 7. Redis exporter (`http://redis-exporter:9121/metrics`)
+
+```bash
+curl -s 'http://localhost:9090/api/v1/label/__name__/values?match[]={job="redis",instance="redis-exporter:9121"}' | jq .
+```
+
+see [Prometheus Results](./prometheus_results.md#redis-metrics) for full output of all 100+ metric names exposed by the Redis exporter.

docs/infrastructure/monitoring/prometheus_results.md

@@ -0,0 +1,124 @@
+# Prometheus Metrics — Linear Void
+
+Raw scrape-target metric inventories captured for the monitoring setup. This file
+lists which metric names are exposed by each target. No threshold values, alert
+rules, or query results are present beyond the metric inventory itself.
+
+Standard boilerplate metrics are exposed by every Go-based target and are omitted
+below where noted: `go_*` (gc/memstats/sched/goroutines), `process_*` (cpu, fds,
+memory, network), `promhttp_metric_handler_*`, and Prometheus scrape internals
+(`scrape_duration_seconds`, `scrape_samples_scraped`, `scrape_samples_post_metric_relabeling`,
+`scrape_series_added`, `up`).
+
+## Chat Target (`linearvoid_chat_*`)
+Application metrics for the chat service:
+- `linearvoid_chat_admin_sessions_active`
+- `linearvoid_chat_build_info`
+- `linearvoid_chat_connected_clients`
+- `linearvoid_chat_dms_total`
+- `linearvoid_chat_messages_total`
+- `linearvoid_chat_moderation_actions_total`
+- `linearvoid_chat_redis_connected_clients`
+- `linearvoid_chat_redis_enabled`
+- `linearvoid_chat_redis_memory_max_bytes`
+- `linearvoid_chat_redis_memory_usage_ratio`
+- `linearvoid_chat_redis_memory_used_bytes`
+- `linearvoid_chat_redis_up`
+- `linearvoid_chat_request_duration_seconds_bucket/_count/_sum` (histogram)
+- Plus `ALERTS`, `ALERTS_FOR_STATE` (alert state series).
+
+## Playout Target (`linearvoid_playout_*`)
+- `linearvoid_playout_mode`
+- `linearvoid_playout_restarts_total`
+- Plus `ALERTS`, `ALERTS_FOR_STATE`.
+
+## Nginx Target (`nginx_*`)
+Nginx (Go-based nginx exporter) metrics. Key operational series:
+- `nginx_connections_accepted`, `nginx_connections_active`, `nginx_connections_handled`
+- `nginx_connections_reading`, `nginx_connections_waiting`, `nginx_connections_writing`
+- `nginx_http_requests_total`
+- `nginx_exporter_build_info`, `nginx_up`
+- Standard Go/process/promhttp/scrape boilerplate.
+
+## Node Target (node_exporter, ZFS host)
+Exposes the full standard node_exporter metric set plus ZFS (`node_zfs_*`) and
+hwmon (`node_hwmon_*`) collectors. Operationally meaningful series include:
+- **CPU/load:** `node_load1/5/15`, `node_cpu_seconds_total`, `node_cpu_scaling_frequency_hertz`,
+  `node_procs_running`, `node_procs_blocked`, `node_context_switches_total`
+- **Memory:** `node_memory_MemTotal_bytes`, `node_memory_MemAvailable_bytes`,
+  `node_memory_MemFree_bytes`, `node_memory_SwapTotal_bytes`, `node_memory_SwapFree_bytes`,
+  `node_vmstat_oom_kill`
+- **Filesystem/disk:** `node_filesystem_avail_bytes`, `node_filesystem_free_bytes`,
+  `node_filesystem_size_bytes`, `node_filesystem_readonly`, `node_disk_read_bytes_total`,
+  `node_disk_written_bytes_total`, `node_disk_io_time_seconds_total`
+- **Network:** `node_network_receive_bytes_total`, `node_network_transmit_bytes_total`,
+  `node_network_up`, plus full `node_netstat_*` TCP/UDP/ICMP series
+- **Files/fds:** `node_filefd_allocated`, `node_filefd_maximum`
+- **Time:** `node_time_seconds`, `node_time_zone_offset_seconds`, `node_timex_sync_status`
+- **ZFS ARC/L2ARC:** extensive `node_zfs_arc_*`/`node_zfs_l2_*` hit/miss/size series,
+  `node_zfs_zil_*`, `node_zfs_dbuf_*`, `node_zfs_dnode_*`, `node_zfs_zfetch_*`
+- **Thermals:** `node_hwmon_temp_celsius`, `node_hwmon_temp_crit_celsius`
+- `node_exporter_build_info`, `node_uname_info`, `node_os_info`, `node_boot_time_seconds`.
+
+## Postgres Target (`pg_*` / postgres_exporter)
+Go-based postgres exporter. Key operational series:
+- **Health/replication:** `pg_up`, `pg_database_size_bytes`, `pg_database_connection_limit`,
+  `pg_replication_is_replica`, `pg_replication_lag_seconds`, `pg_replication_last_replay_seconds`,
+  `pg_locks_count`, `pg_wal_segments`, `pg_wal_size_bytes`
+- **Settings (config-as-metric):** `pg_settings_*` (autovacuum, bgwriter, checkpoints,
+  max_connections, shared_buffers, work_mem, wal_*, etc.)
+- **Activity/statistics:** `pg_stat_activity_count`, `pg_stat_activity_max_tx_duration`,
+  `pg_stat_bgwriter_*` (checkpoints, buffers, fsync), `pg_stat_database_*` (commits,
+  rollbacks, deadlocks, temp files, cache hit/read, tuple ops), `pg_stat_archiver_*`
+- **Tables:** `pg_stat_user_tables_*` (live/dead tuples, seq/index scans, vacuum/analyze
+  counts), `pg_statio_user_tables_*` (heap/index block hits & reads, incl. TOAST)
+- `pg_exporter_*` scrape health series, `postgres_exporter_build_info`, and Go/process boilerplate.
+
+## Prometheus Target (self-scrape)
+Prometheus' own metrics. Operationally meaningful series include:
+- **Health/status:** `prometheus_build_info`, `prometheus_ready`,
+  `prometheus_config_last_reload_successful` (+ timestamp), `prometheus_tsdb_clean_start`
+- **TSDB:** `prometheus_tsdb_head_series`, `prometheus_tsdb_head_samples_appended_total`,
+  `prometheus_tsdb_blocks_loaded`, `prometheus_tsdb_retention_limit_seconds`,
+  `prometheus_tsdb_storage_blocks_bytes`, `prometheus_tsdb_wal_storage_size_bytes`,
+  `prometheus_tsdb_lowest_timestamp`/`_seconds`, `prometheus_tsdb_head_max_time`
+- **Scraping:** `prometheus_sd_discovered_targets`, `prometheus_sd_failed_configs`,
+  `prometheus_sd_last_update_timestamp_seconds`, `prometheus_target_scrape_pool_targets`,
+  `prometheus_target_scrape_pool_target_limit`, `prometheus_target_interval_length_seconds`
+- **Rules/alerting:** `prometheus_rule_group_*` (evaluation duration/failures/interval/
+  rules), `prometheus_rule_evaluation_failures_total`, `prometheus_evaluations_total`,
+  `prometheus_notifications_alertmanagers_discovered`, `prometheus_notifications_queue_capacity`
+- **Engine/HTTP:** `prometheus_engine_queries`, `prometheus_http_requests_total`,
+  `prometheus_http_request_duration_seconds_*`, `prometheus_remote_storage_*` (if remote write enabled)
+- Standard Go/process/promhttp/scrape boilerplate.
+
+## Redis Target (redis_exporter)
+Go-based redis exporter. Key operational series:
+- **Health:** `redis_up`, `redis_instance_info`, `redis_uptime_in_seconds`,
+  `redis_start_time_seconds`, `redis_exporter_last_scrape_error`
+- **Memory:** `redis_memory_used_bytes`, `redis_memory_used_peak_bytes`,
+  `redis_memory_max_bytes`, `redis_memory_used_rss_bytes`, `redis_mem_fragmentation_ratio`,
+  `redis_mem_fragmentation_bytes`
+- **Clients/connections:** `redis_connected_clients`, `redis_max_clients`,
+  `redis_connections_received_total`, `redis_rejected_connections_total`,
+  `redis_blocked_clients`
+- **Commands/latency:** `redis_commands_processed_total`, `redis_commands_failed_calls_total`,
+  `redis_commands_duration_seconds_total`, `redis_commands_latencies_usec_*`,
+  `redis_latency_percentiles_usec`, `redis_errors_total`
+- **Keys/eviction/expiry:** `redis_db_keys`, `redis_db_keys_expiring`, `redis_db_avg_ttl_seconds`,
+  `redis_keyspace_hits_total`, `redis_keyspace_misses_total`, `redis_evicted_keys_total`,
+  `redis_expired_keys_total`
+- **Persistence:** `redis_rdb_last_bgsave_status`, `redis_rdb_last_bgsave_duration_sec`,
+  `redis_aof_enabled`, `redis_aof_last_write_status`, `redis_aof_current_size_bytes`
+- **Replication/pubsub:** `redis_connected_slaves`, `redis_master_repl_offset`,
+  `redis_replication_backlog_bytes`, `redis_pubsub_channels`, `redis_pubsub_clients`
+- **Config:** `redis_config_maxmemory`, `redis_config_maxclients`
+- Standard process/promhttp/scrape boilerplate.
+
+## Notes
+- The only alert-related series present are Prometheus' standard `ALERTS` and
+  `ALERTS_FOR_STATE` on the Chat and Playout targets; no concrete rule thresholds
+  are recorded in this file.
+- No dashboard definitions, alert thresholds, curl outputs, or numeric sample
+  values are captured here — this document is purely the exposed-metric inventory
+  per target.

docs/operations/cloudflare-uptimerobot-checklist.md

@@ -2,22 +2,31 @@
 
 Purpose: execute and record all manual dashboard tasks that cannot be automated from repository workflows.
 
+Recommended execution order:
+
+1. Bind `media.linearvoid.tv` and confirm the HLS origin is separate from the app origin.
+2. Enable Workers, Tiered Cache, and cache behavior for the media zone.
+3. Apply WAF, bot, rate limiting, HTTPS, and HSTS settings.
+4. Verify monitor targets and alert delivery in UptimeRobot.
+5. Capture evidence and fill in the sign-off block.
+
 ## Status Legend
 
 - [ ] Pending
 - [x] Done
 
-## 1) Cloudflare Pages Link and Build
+## 1) Cloudflare Workers Deploy and Custom Domain
 
-- [ ] Connect repo to Cloudflare Pages project
+- [ ] Create a Cloudflare Worker for the SPA and bind the build output
 - [ ] Build command set to: `cd frontend && npm run build`
 - [ ] Output directory set to: `frontend/dist`
 - [ ] Production domain attached to `linearvoid.tv`
 
 Evidence to capture:
 
-- Screenshot of Pages deployment settings
+- Screenshot of Worker deployment settings
 - Deployment URL and latest deployment timestamp
+- Confirmed production build output path in the Worker
 
 ## 2) Tiered Cache Enablement and Validation
 
@@ -37,6 +46,7 @@ Evidence to capture:
 
 - Headers from first request (expected MISS)
 - Headers from repeated request (expected HIT)
+- Screenshot or export showing Smart Tiered Cache enabled
 
 ## 3) WAF and Bot Protection
 
@@ -50,6 +60,7 @@ Evidence to capture:
 
 - WAF ruleset status screenshot
 - Count of blocked/challenged events after cutover
+- Note on any false positives and the final allow/exception rules applied
 
 ## 4) Rate Limiting Rules
 
@@ -67,6 +78,7 @@ Evidence to capture:
 
 - Rule definitions screenshot
 - Test result notes (challenge seen / no lockout)
+- Keep a copy of the test source IP and timestamps used during validation
 
 ## 5) HTTPS and WSS Hardening
 
@@ -89,6 +101,7 @@ Evidence to capture:
 
 - Response headers showing HSTS
 - Successful browser WebSocket connect in devtools
+- TLS mode screenshot from Cloudflare showing Full (strict)
 
 ## 6) UptimeRobot Monitors
 
@@ -101,6 +114,7 @@ Evidence to capture:
 
 - Monitor dashboard screenshot
 - Test alert delivery confirmation
+- List of recipients/webhook destinations verified during the alert test
 
 ## 7) Sign-Off
 
@@ -109,6 +123,15 @@ Evidence to capture:
 - [ ] TODO items updated to done
 - [ ] Changelog entry added for completion batch
 
+Completion summary:
+
+- Worker build URL:
+- Cache validation result:
+- WAF/rate-limit status:
+- HTTPS/HSTS status:
+- UptimeRobot monitor status:
+- Evidence folder or note link:
+
 Sign-off fields:
 
 - Owner:

docs/operations/cloudflare-workers-setup.md

@@ -0,0 +1,71 @@
+# Cloudflare Workers Setup — Linear Void
+
+Linear Void uses Cloudflare Workers for two purposes:
+
+| Product     | Purpose            | What                                                                                         |
+| ----------- | ------------------ | -------------------------------------------------------------------------------------------- |
+| **Workers** | Static SPA hosting | `linearvoid-frontend` (`frontend/wrangler.toml`) — Vite SPA (`frontend/dist`) static assets  |
+| **Workers** | Edge HLS delivery  | `linearvoid-media` (`infrastructure/cloudflare/`) — R2-bound Worker on `media.linearvoid.tv` |
+
+Both are managed under **Workers & Pages** in the Cloudflare dashboard.
+
+## Dashboard URLs
+
+| Resource                 | URL                                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| Workers & Pages overview | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers-and-pages`                                          |
+| Worker: linearvoid-media | `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers/services/view/linearvoid-media/production/settings` |
+| API tokens               | <https://dash.cloudflare.com/profile/api-tokens>                                                                          |
+
+## Worker: `linearvoid-media` (edge HLS delivery)
+
+The Worker in [`infrastructure/cloudflare/`](../../infrastructure/cloudflare/) runs on the `linearvoid-media` Workers service. It owns the `media.linearvoid.tv` host, serves HLS objects from the R2 bucket (bound as `MEDIA_BUCKET`), and stamps immutable `Cache-Control` on segments plus a short TTL on live manifests (CORS + Range supported). See its [README](../../infrastructure/cloudflare/README.md).
+
+**Run-scoped layout.** R2 objects are stored run-scoped (`hls/r-{runID}/seg-*.m4s`, `…/init.mp4`), and the live `hls/playlist.m3u8` references them with the run prefix (the playout rewrites bare URIs before publishing — see [`docs/STREAMING.md`](../STREAMING.md)). The Worker is a faithful path→R2 mapper: it serves whatever key the request path resolves to (e.g. `/hls/r-…/seg-*.m4s`), adds the cache headers by file type, and does not rewrite manifest URIs at serve time.
+
+Test / deploy:
+
+```bash
+cd infrastructure/cloudflare
+npm install && npm test              # unit + Miniflare R2 tests
+npx wrangler deploy                  # preview/test target
+npx wrangler deploy --env production # attach media.linearvoid.tv
+```
+
+Attach the production custom domain only after removing `media.linearvoid.tv` from the R2 bucket's direct custom-domain binding. Automated production deploy: [`.gitea/workflows/workers-media-deploy.yml`](../../.gitea/workflows/workers-media-deploy.yml).
+
+## Worker: static frontend
+
+Serve the Vite-built SPA (`frontend/dist`) as Worker static assets:
+
+1. Build the frontend: `cd frontend && npm run build`.
+2. Bind `frontend/dist` to the Worker as static assets (Workers Static Assets / `assets` in `wrangler.toml`).
+3. Attach the `linearvoid.tv` custom domain to the Worker.
+
+See [gitea-cloudflare-workers.md](./gitea-cloudflare-workers.md) for the automated deployment workflow.
+
+### Build-time variables
+
+The `VITE_PUBLIC_*` values are baked into the bundle at build time by Vite (`vite.config.ts` uses `envDir: ".."` to read them from the repo root). They are supplied by the Gitea Actions build environment from Gitea secrets — not as Worker runtime variables. The static-assets Worker has no runtime JavaScript, so it reads no `env` at request time.
+
+| Name                                     | Value                                           |
+| ---------------------------------------- | ----------------------------------------------- |
+| `VITE_PUBLIC_APP_URL`                    | `https://linearvoid.tv`                         |
+| `VITE_PUBLIC_WS_URL`                     | `wss://linearvoid.tv/ws`                        |
+| `VITE_PUBLIC_HLS_URL`                    | `https://media.linearvoid.tv/hls/playlist.m3u8` |
+| `VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR`    | `boogers`                                       |
+| `VITE_PUBLIC_ADMIN_DEFAULT_ROOM`         | `main`                                          |
+| `VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT` | `50`                                            |
+
+Backend services (playout, chat, nginx) read their own runtime variables (`ADMIN_*`, `HLS_*`, `PLAYLIST_PATH`, `R2_*`, `DATABASE_URL`, `REDIS_URL`) from the container environment — see [`.env.example`](../../.env.example).
+
+## Custom domains
+
+- `linearvoid.tv` → Worker (static SPA, `linearvoid-frontend`)
+- `www.linearvoid.tv` → redirect to `linearvoid.tv`
+- `media.linearvoid.tv` → Worker (`linearvoid-media`, R2-bound) serving the `linearvoid-media` bucket
+
+## Related
+
+- [Gitea to Cloudflare Workers deployment guide](./gitea-cloudflare-workers.md)
+- [Cloudflare & UptimeRobot checklist](./cloudflare-uptimerobot-checklist.md)

docs/operations/gitea-cloudflare-workers.md

@@ -0,0 +1,107 @@
+# Gitea to Cloudflare Workers — Linear Void
+
+## Goal
+
+Deploy the Linear Void frontend (Vite + TypeScript SPA) from Gitea to Cloudflare Workers using Gitea Actions and Wrangler.
+
+## Prerequisites
+
+1. **Cloudflare Worker** for the SPA:
+   - Dashboard → Workers & Pages → Create → Worker (or Workers Static Assets).
+   - Name it `linearvoid-frontend` (the edge-cache Worker already uses the `linearvoid` name).
+2. **API token** with Workers permissions:
+   - Create at <https://dash.cloudflare.com/profile/api-tokens>
+   - Permission: `Account → Workers Scripts → Edit` and `Account → Workers Routes → Edit`
+   - Store in Gitea → Settings → Secrets as `CLOUDFLARE_API_TOKEN`
+3. **Account ID** from Cloudflare dashboard overview → store as `CLOUDFLARE_ACCOUNT_ID`
+4. **Wrangler config** (`frontend/wrangler.toml`) binding the `frontend/dist` output as static assets.
+
+> **Naming:** Workers share a namespace under "Workers & Pages". The media edge Worker is `linearvoid-media` ([`infrastructure/cloudflare/`](../../infrastructure/cloudflare/wrangler.toml), deployed via `.gitea/workflows/workers-media-deploy.yml`) and the SPA Worker is `linearvoid-frontend` (`frontend/wrangler.toml`, deployed via `.gitea/workflows/workers-deploy.yml`).
+
+## Project-specific values
+
+| Setting            | Value                                                      |
+| ------------------ | ---------------------------------------------------------- |
+| Framework          | Vite + TypeScript                                          |
+| Build command      | `cd frontend && npm install && npm run build`              |
+| Output directory   | `frontend/dist`                                            |
+| Node version       | 22                                                         |
+| Multi-page entries | `index.html`, `admin/index.html`, `admin/login/index.html` |
+
+## Gitea Actions workflow
+
+Build the SPA and deploy with Wrangler:
+
+```yaml
+name: Deploy to Cloudflare Workers
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: cd frontend && npm ci
+
+      - name: Build
+        env:
+          VITE_PUBLIC_APP_URL: ${{ secrets.VITE_PUBLIC_APP_URL }}
+          VITE_PUBLIC_WS_URL: ${{ secrets.VITE_PUBLIC_WS_URL }}
+          VITE_PUBLIC_HLS_URL: ${{ secrets.VITE_PUBLIC_HLS_URL }}
+          VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR }}
+          VITE_PUBLIC_ADMIN_DEFAULT_ROOM: ${{ secrets.VITE_PUBLIC_ADMIN_DEFAULT_ROOM }}
+          VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT: "50"
+        run: cd frontend && npm run build
+
+      - name: Deploy to Cloudflare Workers
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+        run: |
+          cd frontend
+          npx wrangler deploy
+```
+
+## Secrets to add in Gitea
+
+| Secret                                | Value                                |
+| ------------------------------------- | ------------------------------------ |
+| `CLOUDFLARE_API_TOKEN`                | API token with Workers permissions   |
+| `CLOUDFLARE_ACCOUNT_ID`               | Cloudflare account ID from dashboard |
+| `VITE_PUBLIC_APP_URL`                 | Public viewer URL                    |
+| `VITE_PUBLIC_WS_URL`                  | WebSocket endpoint                   |
+| `VITE_PUBLIC_HLS_URL`                 | HLS playlist URL                     |
+| `VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR` | Default moderator username           |
+| `VITE_PUBLIC_ADMIN_DEFAULT_ROOM`      | Default chat room                    |
+
+## Verify deployment
+
+1. Push to `main` or trigger manually from Gitea Actions.
+2. Check **Gitea Actions** → job logs for the deploy step.
+3. Check **Cloudflare Workers** → `linearvoid-frontend` → Deployments for the new version.
+4. Visit `https://linearvoid-frontend.zwitschi82.workers.dev`, then attach `linearvoid.tv` when ready.
+
+## Notes
+
+- The existing `ci.yml` already builds the frontend; the Workers deploy workflow is additive and independent.
+- Multi-page SPA (`vite.config.ts`) produces three entry points — Workers static assets serve them correctly.
+- For SPA fallback routing, set Workers static assets `not_found_handling` to `single-page-application` (serve `index.html` for unknown paths).
+- The deploy workflow lives in `.gitea/workflows/workers-deploy.yml` (triggered after CI succeeds).
+
+## Related resources
+
+- Cloudflare Workers dashboard: `https://dash.cloudflare.com/deb11491c54ec53a24772e98ac6d8128/workers/services/view/linearvoid/production/settings` — for managing the `infrastructure/cloudflare/worker.js` deployment and the SPA Worker

docs/operations/scaling-performance-playbook.md

@@ -1,199 +1,156 @@
 # Scaling and Performance Playbook
 
-Purpose: define repeatable method to measure performance, capture baseline data, and decide scaling actions.
+Purpose: define a repeatable method to measure performance, capture baselines, and decide scaling actions for the "Linear Void" streaming app. Scope: planning/execution for the "Scaling & Performance (planning only)" TODO items.
-
-Scope: planning and execution guide for TODO items under "Scaling & Performance (planning only)".
 
 ## 1) Manifest TTL Tuning Plan
 
-Goal: tune `.m3u8` TTL to about `0.5x` segment duration while keeping playback stable.
+Goal: tune the `.m3u8` TTL to ~`0.5x` segment duration while keeping playback stable.
 
-Inputs:
+Inputs: segment duration (`HLS_SEGMENT_DURATION`), current manifest TTL (Cloudflare cache rule), cache outcome distribution (`Cf-Cache-Status`).
-
-- Segment duration (`HLS_SEGMENT_DURATION`)
-- Current manifest TTL (Cloudflare cache rule)
-- Cache outcome distribution (`Cf-Cache-Status`)
 
 Procedure:
-
 1. Start from current manifest TTL (2s).
 2. Capture 24h baseline headers from repeated `playlist.m3u8` requests.
 3. Test candidate TTLs: 1s, 2s, 3s.
-4. Compare:
+4. Compare rebuffer events (player logs), origin request increase/decrease, and HIT ratio changes.
-   - rebuffer events from player logs
+5. Select the lowest TTL that keeps playback stable and origin load acceptable.
-   - origin request increase/decrease
-   - HIT ratio changes
-5. Select lowest TTL that keeps playback stable and origin load acceptable.
 
-Acceptance:
+Acceptance: no material increase in rebuffer rate; manifest staleness not observable by users.
-
-- No material increase in rebuffer rate.
-- Manifest staleness not observable by users.
 
 ## 2) TTFB Baseline Plan
 
 Goal: measure warm-cache TTFB from 3+ US regions with target `< 4s`.
 
-Suggested regions:
+Regions: US East (Virginia), US Central, US West (California/Oregon).
-
-- US East (Virginia)
-- US Central
-- US West (California/Oregon)
 
 Method:
-
 1. Use WebPageTest with repeat view enabled.
 2. Run at least 5 samples per region.
 3. Record median and p95 TTFB.
-4. Store results in table (date, region, median, p95, test URL).
+4. Store results in a table (date, region, median, p95, test URL).
 
-Acceptance:
+Acceptance: warm-cache median < 4s in all regions; outliers documented with likely cause.
 
-- Warm-cache median < 4s in all tested regions.
+### TTFB Baseline Worksheet
-- Outliers documented with likely cause.
+Use one row per region; keep the raw WebPageTest result URL with the summary for comparison.
+
+- US East (Virginia) / US Central / US West (California/Oregon): Date/time, Test URL `https://linearvoid.tv`, WebPageTest result URL, Median TTFB, p95 TTFB, Notes.
+
+Capture notes: use repeat view for warm-cache; keep the same browser profile and test URL across regions; note any CDN cache-rule changes or deploys between samples.
 
 ## 3) WebSocket Load-Test Plan
 
-Goal: characterize chat service behavior across 10 -> 100 -> 500 -> 1000 concurrent clients.
+Goal: characterize chat behavior across 10 → 100 → 500 → 1000 concurrent clients.
 
 Tooling option A (Artillery):
-
 ```bash
 npx artillery run scripts/loadtest/ws-chat.yml
 ```
 
-Tooling option B (custom Go harness):
+Tooling option B (custom Go harness): open N concurrent WS clients, send a message every X seconds, measure round-trip latency and failures.
 
-- open N concurrent WebSocket clients
+Metrics: p50/p95 message latency; error rate (connect/send/receive); dropped connections; CPU/memory for `chat`, `redis`, `nginx`.
-- send message every X seconds
-- measure round-trip latency and failures
 
-Metrics to capture:
+Acceptance: p95 chat latency ≤ 1s at target concurrency tier; error rate ≤ 1% during steady state.
 
-- p50/p95 message latency
+### WebSocket Load-Test Worksheet
-- error rate (connect, send, receive)
+Date/time, Environment, Commit SHA/image tag, Test URL, Tool used, Scenario duration, Concurrency tiers reached, p50 message latency, p95 message latency, Error rate, Dropped connections, CPU/memory notes for chat/redis/nginx, Raw results location, Conclusion, Next action.
-- dropped connections
-- CPU/memory for `chat`, `redis`, `nginx`
-
-Acceptance:
-
-- p95 chat latency <= 1s at target concurrency tier.
-- error rate <= 1% during steady state.
 
 ## 4) Admin API Benchmark Plan
 
 Goal: measure admin API p95 and identify slow endpoints.
 
-Tooling option A (`k6`):
+Endpoints: `/api/admin/overview`, `/api/admin/analytics`, `/api/admin/chat-log`, `/api/admin/users`.
 
+Tooling option A (`k6`):
 ```bash
 k6 run scripts/loadtest/admin-api.js
 ```
 
 Tooling option B (`wrk`):
-
 ```bash
 wrk -t4 -c100 -d60s http://<host>/api/admin/overview
 ```
 
-Endpoints:
+Acceptance: p95 < 1s for primary admin endpoints; slow endpoint list with remediation notes.
 
-- `/api/admin/overview`
+### Admin API Benchmark Worksheet
-- `/api/admin/analytics`
+Date/time, Environment, Commit SHA/image tag, Test URL, Tool used, Scenario duration, Concurrency/virtual users, `/api/admin/overview|analytics|chat-log|users` p95, Error rate, Slowest endpoint, Cache or DB notes, Raw results location, Conclusion, Next action.
-- `/api/admin/chat-log`
-- `/api/admin/users`
-
-Acceptance:
-
-- p95 < 1s for primary admin endpoints.
-- slow endpoint list with remediation notes.
 
 ## 5) Cache Hit Ratio Tracking Plan
 
 Goal: track Cloudflare cache hit ratio and alert when below threshold.
 
-Implementation outline:
+Implementation:
-
 1. Pull Cloudflare GraphQL analytics on schedule.
-2. Export to Prometheus-compatible metric path.
+2. Export to a Prometheus-compatible metric path.
-3. Add Grafana panel with 5m/1h/24h windows.
+3. Add a Grafana panel with 5m/1h/24h windows.
 4. Alert when hit ratio < 90% for 15m.
 
-Metric target:
+Reference exporter:
+- `scripts/cache-hit-ratio.js`
+- `scripts/cache-hit-ratio.sh` for scheduled tasks / manual runs
+- Example run: `export CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ZONE_TAG=... CLOUDFLARE_HOSTNAME=media.linearvoid.tv; node scripts/cache-hit-ratio.js`
+- Intended output: Prometheus text format on stdout, suitable for cron, a Node wrapper, or a small scrape endpoint.
 
-- `cache_hit_ratio >= 0.90`
+Metric target: `cache_hit_ratio >= 0.90`.
+
+### Cache Hit Ratio Worksheet
+Date/time, Environment, Commit SHA/image tag, Hostname, Window minutes, Cloudflare zone tag, Export command, Raw exporter output location, Hit requests, Total requests, Cache hit ratio, Threshold met, Notes.
 
 ## 6) Capacity Trigger Rules
 
-Define operational triggers:
+Operational triggers:
-
 - Cache miss ratio > 10% for 15m
 - Chat p95 latency > 1s for 5m
 - Host CPU > 80% for 10m
-- Redis memory > 85% sustained
+- Redis memory usage ratio (`linearvoid_chat_redis_memory_usage_ratio`) > 0.85 for 10m
 
 Action mapping:
-
 - Level 1: investigate + restart non-critical components
 - Level 2: scale service resources (CPU/RAM)
 - Level 3: activate standby planning path
 
+### Capacity Trigger Review
+Date/time, Environment, Commit SHA/image tag, Trigger hit, Threshold value, Observed value, Duration above threshold, Level selected, Immediate action taken, Services involved, Follow-up owner, Raw metrics/alert link, Notes.
+
 ## 7) Phase 2 Service Separation Plan
 
-Objective: separate bottlenecked services while keeping simple ops.
+Objective: separate bottlenecked services while keeping ops simple.
 
 Boundaries:
-
 - `playout` isolated first (CPU-heavy)
 - `chat` + `redis` grouped for latency
 - `db` isolated for IO stability
 - monitoring stack optionally separated after sustained load
 
-Initial sizing guidance:
+Initial sizing:
-
 - playout host: 4 vCPU / 8 GB
-- chat host: 2-4 vCPU / 4-8 GB
+- chat host: 2–4 vCPU / 4–8 GB
 - db host: 2 vCPU / 4 GB + fast disk
 
-Exit criteria for Phase 2:
+Exit criteria: repeated trigger events over 7 days; capacity saturation despite tuning.
 
-- repeated trigger events over 7 days
+### Phase 2 Boundary Worksheet
-- capacity saturation despite tuning
+Date/time, Environment, Commit SHA/image tag, Trigger history summary, Repeated trigger count over 7 days, Primary bottleneck, Proposed split, `playout`/`chat`/`db` target host size, Monitoring separation needed, Data/state migration notes, Implementation owner, Review decision, Next action.
 
 ## 8) Phase 3 Warm Standby Plan
 
 Objective: second-region resilience with DNS failover.
 
-Candidate layout:
+Layout:
-
 - Primary: Hetzner Ashburn (US-East)
 - Standby: Hetzner Hillsboro (US-West)
 
-Design:
+Design: warm standby stack deployed and health-checked; Redis replication or fallback mode documented; Postgres replication strategy selected (streaming replica or periodic snapshot restore); Cloudflare DNS failover policy defined (health-based or manual emergency switch).
 
-- Warm standby stack deployed and health-checked
+### Phase 3 Warm Standby Worksheet
-- Redis replication or fallback mode documented
+Date/time, Environment, Commit SHA/image tag, Primary region, Standby region, DNS failover mode, Redis strategy, Postgres strategy, Health check endpoints, Simulated cutover performed, Measured RTO, Measured RPO, Open risks, Implementation owner, Review decision, Notes.
-- Postgres replication strategy selected (streaming replica or periodic snapshot restore)
-- Cloudflare DNS failover policy defined (health-based or manual emergency switch)
-
-Failover drill requirements:
-
-- periodic simulated cutover
-- measured RTO/RPO logged in incident records
 
 ## 9) Data Capture Template
-
+For each benchmark run capture: Date/time, Environment (test-lab/staging/production), Commit SHA/image tag, Test scenario and duration, Raw metrics (latency, errors, resource usage), Conclusion and next action.
-For each benchmark run, capture:
-
-- Date/time
-- Environment (test-lab/staging/production)
-- Commit SHA / image tag
-- Test scenario and duration
-- Raw metrics (latency, errors, resource usage)
-- Conclusion and next action
 
 ## 10) Execution Order
-
 1. TTFB baseline
 2. WebSocket load profile
 3. Admin API benchmark
@@ -201,3 +158,68 @@ For each benchmark run, capture:
 5. Trigger tuning
 6. Phase 2 boundary decision
 7. Phase 3 standby design review
+
+## 11) Benchmark Run Sheet
+Use the same worksheet for every baseline/re-test so results stay comparable.
+
+Preconditions: confirm target environment and commit SHA/image tag; confirm Cloudflare cache rules are active when testing TTFB or manifest TTL; confirm chat, admin, and playout services are healthy before load testing.
+
+Run template:
+
+| Item                       | Value |
+| -------------------------- | ----- |
+| Date/time                  |       |
+| Environment                |       |
+| Commit SHA / image tag     |       |
+| Test scenario              |       |
+| Concurrency / sample count |       |
+| Command or tool            |       |
+| Raw results location       |       |
+| Conclusion                 |       |
+| Next action                |       |
+
+Suggested command mapping:
+- TTFB baseline: WebPageTest repeat-view run against `https://linearvoid.tv`.
+- WebSocket profile: `npx artillery run scripts/loadtest/ws-chat.yml` or the Go harness referenced above.
+- Admin API benchmark: `k6 run scripts/loadtest/admin-api.js` or `wrk -t4 -c100 -d60s http://<host>/api/admin/overview`.
+
+## 12) Scaling Decision Gate
+
+Default review gate after any benchmark batch:
+1. If warm-cache TTFB meets target but cache hit ratio falls below 90%, tune cache behavior before increasing capacity.
+2. If chat or admin latency exceeds target while CPU and memory remain low, prioritize query or handler optimization.
+3. If CPU, memory, or Redis saturation appears first, treat the Phase 2 service boundary guidance as the next action.
+4. If the same threshold trips on multiple runs across 7 days, open the Phase 2 or Phase 3 planning path instead of tuning in place.
+
+Decision note: keep the smallest change that restores the target metric and record the reason in the run sheet.
+
+## 13) Artifact-to-Worksheet Field Mapping
+Use when filling the WebSocket and Admin API worksheets from helper-generated artifacts.
+
+### WebSocket worksheet mapping
+Artifact sources: `artifacts/<timestamp>/ws-chat-report.json`, `artifacts/<timestamp>/ws-chat-summary.txt`.
+
+Field mapping:
+- `Tool used` → `artillery` (or `scripts/loadtest/run-loadtests.sh -s ws`)
+- `Raw results location` → artifact folder path for this run
+- `Concurrency tiers reached` → `ws-chat.yml` phases (`warmup-10`, `sustain-100`, `sustain-500`, `sustain-1000`)
+- `Error rate` → `vusers.failure_rate_percent` from `ws-chat-summary.txt`
+- `Dropped connections` → derive from `vusers.created - vusers.completed` (use `vusers.failed` as failure signal)
+- `p95 message latency` → first latency line under `summary.*` in `ws-chat-summary.txt` containing `p95=...`
+- `p50 message latency` → first latency line under `summary.*` in `ws-chat-summary.txt` containing `median=...`
+
+Notes: the exact `summary.*` metric names in Artillery output can vary by engine/plugins; if no latency summary field is emitted, record this explicitly and use server-side latency metrics as fallback evidence.
+
+### Admin API worksheet mapping
+Artifact sources: `artifacts/<timestamp>/admin-api-summary.json`, `artifacts/<timestamp>/admin-api-output.txt`, `artifacts/<timestamp>/admin-api-endpoint-summary.txt`.
+
+Field mapping:
+- `Tool used` → `k6` (or `scripts/loadtest/run-loadtests.sh -s admin`)
+- `Raw results location` → artifact folder path for this run
+- `/api/admin/overview|analytics|chat-log|users` p95 → `overview|analytics|chat_log|users` row `P95Ms` in `admin-api-endpoint-summary.txt`
+- `Error rate` → `Global failure rate` in `admin-api-endpoint-summary.txt`
+- `Slowest endpoint` → endpoint row with highest `P95Ms`
+
+Notes: keep the raw `admin-api-summary.json` file for audits and re-parsing; if an endpoint row is missing, treat it as a test/data issue and re-run with full endpoint coverage.
+
+Summary helper (bash): run `scripts/loadtest/summarize-artillery.sh <report.json>` after an Artillery WS run, and `scripts/loadtest/summarize-k6.sh <summary.json>` after a k6 admin run, to produce the artifact files used in the mappings above.

frontend/admin/index.html

@@ -1,130 +1,63 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Linear Void Admin</title>
-    <link rel="stylesheet" href="../src/style.css" />
-  </head>
 
-  <body class="admin-body">
+<head>
-    <div class="admin-shell">
+  <meta charset="UTF-8" />
-      <aside class="admin-sidebar" aria-label="Primary">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <div class="brand-block">
+  <title>Linear Void Admin</title>
-          <div class="brand-badge" aria-hidden="true">LV</div>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
-          <div class="brand-text">Admin</div>
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-        </div>
+  <link href="https://fonts.googleapis.com/css2?family=Doto:wght@100..900&family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Space+Grotesk:wght@300..700&family=Tektur:wght@400..900&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="../src/style.css" />
+</head>
 
-        <button id="logout-btn" type="button" class="btn btn-secondary btn-block">Sign out</button>
+<body class="admin-body">
+  <div class="admin-shell">
+    <aside class="admin-sidebar" aria-label="Primary">
+      <div class="brand-block">
+        <div class="brand-badge" aria-hidden="true">LV</div>
+        <div class="brand-text">Admin</div>
+      </div>
 
-        <nav class="admin-nav" aria-label="Admin sections" role="tablist" aria-orientation="vertical">
+      <button id="logout-btn" type="button" class="btn btn-secondary btn-block">Sign out</button>
-          <button
-            type="button"
-            id="tab-trigger-dashboard"
-            role="tab"
-            class="tab-trigger is-active"
-            data-tab="dashboard"
-            aria-controls="tab-dashboard"
-            aria-selected="true"
-          >
-            Dashboard
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-upload"
-            role="tab"
-            class="tab-trigger"
-            data-tab="upload"
-            aria-controls="tab-upload"
-            aria-selected="false"
-          >
-            Upload Video
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-playlist"
-            role="tab"
-            class="tab-trigger"
-            data-tab="playlist"
-            aria-controls="tab-playlist"
-            aria-selected="false"
-          >
-            Playlist
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-schedule"
-            role="tab"
-            class="tab-trigger"
-            data-tab="schedule"
-            aria-controls="tab-schedule"
-            aria-selected="false"
-          >
-            Schedule
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-moderation"
-            role="tab"
-            class="tab-trigger"
-            data-tab="moderation"
-            aria-controls="tab-moderation"
-            aria-selected="false"
-          >
-            Moderation
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-chat-log"
-            role="tab"
-            class="tab-trigger"
-            data-tab="chat-log"
-            aria-controls="tab-chat-log"
-            aria-selected="false"
-          >
-            Chat Log
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-users"
-            role="tab"
-            class="tab-trigger"
-            data-tab="users"
-            aria-controls="tab-users"
-            aria-selected="false"
-          >
-            Users
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-analytics"
-            role="tab"
-            class="tab-trigger"
-            data-tab="analytics"
-            aria-controls="tab-analytics"
-            aria-selected="false"
-          >
-            Analytics
-          </button>
-          <button
-            type="button"
-            id="tab-trigger-system"
-            role="tab"
-            class="tab-trigger"
-            data-tab="system"
-            aria-controls="tab-system"
-            aria-selected="false"
-          >
-            System
-          </button>
-        </nav>
-      </aside>
 
-      <main class="admin-main" id="admin-main" tabindex="-1">
+      <nav class="admin-nav" aria-label="Admin sections" role="tablist" aria-orientation="vertical">
-        <div id="tab-content-container" aria-live="polite">Loading...</div>
+        <button type="button" id="tab-trigger-dashboard" role="tab" class="tab-trigger is-active" data-tab="dashboard" aria-controls="tab-dashboard" aria-selected="true">
-      </main>
+          Dashboard
-    </div>
+        </button>
+        <button type="button" id="tab-trigger-upload" role="tab" class="tab-trigger" data-tab="upload" aria-controls="tab-upload" aria-selected="false">
+          Upload Video
+        </button>
+        <button type="button" id="tab-trigger-playlist" role="tab" class="tab-trigger" data-tab="playlist" aria-controls="tab-playlist" aria-selected="false">
+          Playlist
+        </button>
+        <button type="button" id="tab-trigger-schedule" role="tab" class="tab-trigger" data-tab="schedule" aria-controls="tab-schedule" aria-selected="false">
+          Schedule
+        </button>
+        <button type="button" id="tab-trigger-moderation" role="tab" class="tab-trigger" data-tab="moderation" aria-controls="tab-moderation" aria-selected="false">
+          Moderation
+        </button>
+        <button type="button" id="tab-trigger-chat-log" role="tab" class="tab-trigger" data-tab="chat-log" aria-controls="tab-chat-log" aria-selected="false">
+          Chat Log
+        </button>
+        <button type="button" id="tab-trigger-users" role="tab" class="tab-trigger" data-tab="users" aria-controls="tab-users" aria-selected="false">
+          Users
+        </button>
+        <button type="button" id="tab-trigger-analytics" role="tab" class="tab-trigger" data-tab="analytics" aria-controls="tab-analytics" aria-selected="false">
+          Analytics
+        </button>
+        <button type="button" id="tab-trigger-system" role="tab" class="tab-trigger" data-tab="system" aria-controls="tab-system" aria-selected="false">
+          System
+        </button>
+      </nav>
+    </aside>
 
-    <script type="module" src="/src/admin.ts"></script>
+    <main class="admin-main" id="admin-main" tabindex="-1">
-  </body>
+      <div id="tab-content-container" aria-live="polite">Loading...</div>
-</html>
+    </main>
+  </div>
+
+  <script type="module" src="/src/admin.ts"></script>
+</body>
+
+</html>

frontend/admin/login/index.html

@@ -1,65 +1,70 @@
 <!doctype html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Linear Void Admin Login</title>
-    <link rel="stylesheet" href="../../src/style.css" />
-  </head>
 
-  <body class="auth-body">
+<head>
-    <main class="auth-shell" aria-label="Admin authentication">
+  <meta charset="UTF-8" />
-      <section class="auth-card" aria-labelledby="auth-title">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <p class="auth-kicker">Linear Void</p>
+  <title>Linear Void Admin Login</title>
-        <h1 id="auth-title">Admin Login</h1>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
-        <p class="auth-subtitle">Authenticate to access protected admin controls.</p>
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Doto:wght@100..900&family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Space+Grotesk:wght@300..700&family=Tektur:wght@400..900&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="../../src/style.css" />
+</head>
 
-        <form id="login-form" class="form-stack" novalidate>
+<body class="auth-body">
-          <label for="username">Username</label>
+  <main class="auth-shell" aria-label="Admin authentication">
-          <input id="username" type="text" class="text-input" autocomplete="username" required />
+    <section class="auth-card" aria-labelledby="auth-title">
+      <p class="auth-kicker">Linear Void</p>
+      <h1 id="auth-title">Admin Login</h1>
+      <p class="auth-subtitle">Authenticate to access protected admin controls.</p>
 
-          <label for="password">Password</label>
+      <form id="login-form" class="form-stack" novalidate>
-          <input id="password" type="password" class="text-input" autocomplete="current-password" required />
+        <label for="username">Username</label>
+        <input id="username" type="text" class="text-input" autocomplete="username" required />
 
-          <button id="submit" type="submit" class="btn btn-primary btn-block">Sign in</button>
+        <label for="password">Password</label>
-          <p id="status" class="status-line" aria-live="polite"></p>
+        <input id="password" type="password" class="text-input" autocomplete="current-password" required />
-        </form>
-      </section>
-    </main>
 
-    <script>
+        <button id="submit" type="submit" class="btn btn-primary btn-block">Sign in</button>
-      const form = document.getElementById("login-form");
+        <p id="status" class="status-line" aria-live="polite"></p>
-      const username = document.getElementById("username");
+      </form>
-      const password = document.getElementById("password");
+    </section>
-      const submit = document.getElementById("submit");
+  </main>
-      const status = document.getElementById("status");
 
-      form.addEventListener("submit", async (event) => {
+  <script>
-        event.preventDefault();
+    const form = document.getElementById("login-form");
-        submit.disabled = true;
+    const username = document.getElementById("username");
-        status.textContent = "Signing in...";
+    const password = document.getElementById("password");
-        status.className = "status-line";
+    const submit = document.getElementById("submit");
+    const status = document.getElementById("status");
 
-        try {
+    form.addEventListener("submit", async (event) => {
-          const response = await fetch("/api/admin/login", {
+      event.preventDefault();
-            method: "POST",
+      submit.disabled = true;
-            headers: { "Content-Type": "application/json" },
+      status.textContent = "Signing in...";
-            body: JSON.stringify({ username: username.value, password: password.value }),
+      status.className = "status-line";
-          });
 
-          if (!response.ok) {
+      try {
-            throw new Error(`HTTP ${response.status}`);
+        const response = await fetch("/api/admin/login", {
-          }
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ username: username.value, password: password.value }),
+        });
 
-          window.location.href = "/admin/";
+        if (!response.ok) {
-        } catch (error) {
+          throw new Error(`HTTP ${response.status}`);
-          console.error("Failed to sign in", error);
-          status.textContent = "Login failed. Check your credentials.";
-          status.className = "status-line status-error";
-        } finally {
-          submit.disabled = false;
         }
-      });
+
-    </script>
+        window.location.href = "/admin/";
-  </body>
+      } catch (error) {
-</html>
+        console.error("Failed to sign in", error);
+        status.textContent = "Login failed. Check your credentials.";
+        status.className = "status-line status-error";
+      } finally {
+        submit.disabled = false;
+      }
+    });
+  </script>
+</body>
+
+</html>

frontend/index.html

@@ -1,76 +1,122 @@
-<!doctype html>
+<!doctype html>
-<html lang="en">
+<html lang="en">
-  <head>
+
-    <meta charset="UTF-8" />
+<head>
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta charset="UTF-8" />
-    <title>Linear Void - 24/7 Synchronized Channel</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="stylesheet" href="/src/style.css" />
+  <title>Linear Void - 24/7 Synchronized Channel</title>
-  </head>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
-
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <body class="lv-body">
+  <link href="https://fonts.googleapis.com/css2?family=Doto:wght@100..900&family=IBM+Plex+Mono:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Space+Grotesk:wght@300..700&family=Tektur:wght@400..900&display=swap" rel="stylesheet">
-    <main class="viewer-shell" aria-label="Live player and chat">
+  <link rel="stylesheet" href="/src/style.css" />
-      <header class="viewer-header">
+</head>
-        <div class="viewer-brand-group">
+
-          <div class="brand-badge" aria-hidden="true">LV</div>
+<body class="lv-body">
-          <div>
+  <main class="viewer-shell" aria-label="Live player and chat">
-            <h1 class="viewer-title">Linear Void</h1>
+    <header class="viewer-header">
-            <p class="viewer-subtitle">24/7 Synchronized Channel • Live</p>
+      <div class="viewer-brand-group">
-          </div>
+        <div class="brand-badge" aria-hidden="true">LV</div>
-        </div>
+        <div>
-        <button
+          <h1 class="viewer-title">Linear Void</h1>
-          id="chat-toggle"
+          <p class="viewer-subtitle">24/7 Synchronized Channel • Live</p>
-          type="button"
+        </div>
-          class="btn btn-secondary chat-toggle-btn"
+      </div>
-          onclick="toggleChatPanel()"
+      <button id="chat-toggle" type="button" class="btn btn-secondary chat-toggle-btn" onclick="toggleChatPanel()" aria-controls="chat-panel" aria-expanded="true">
-          aria-controls="chat-panel"
+        Hide Chat
-          aria-expanded="true"
+      </button>
-        >
+    </header>
-          Hide Chat
+
-        </button>
+    <section class="viewer-content" aria-label="Live stream and chat layout">
-      </header>
+      <section class="player-stage" aria-label="Video stage">
-
+        <video id="player" class="player" controls autoplay muted playsinline></video>
-      <section class="viewer-content" aria-label="Live stream and chat layout">
+        <div id="now-playing" class="now-playing-overlay" aria-live="polite">
-        <section class="player-stage" aria-label="Video stage">
+          <span id="np-title">Loading...</span>
-          <video id="player" class="player" controls autoplay muted playsinline></video>
+          <span id="np-next" class="np-next"></span>
-          <div id="now-playing" class="now-playing-overlay" aria-live="polite">
+        </div>
-            <span id="np-title">Loading...</span>
+      </section>
-            <span id="np-next" class="np-next"></span>
+
-          </div>
+      <aside id="chat-panel" class="chat-sidebar" aria-label="Chat panel">
-        </section>
+        <header class="chat-header">
-
+          <div class="chat-room-title">
-        <aside id="chat-panel" class="chat-sidebar" aria-label="Chat panel">
+            <span class="chat-live-marker" aria-hidden="true">●</span>
-          <header class="chat-header">
+            <span id="room-name">Main Channel</span>
-            <div class="chat-room-title">
+          </div>
-              <span class="chat-live-marker" aria-hidden="true">●</span>
+          <div class="chat-header-actions">
-              <span id="room-name">Main Channel</span>
+            <span id="chat-user-label" class="chat-user-label" hidden></span>
-            </div>
+            <button id="auth-toggle-btn" type="button" class="btn btn-secondary">Sign in</button>
-            <button type="button" class="btn btn-secondary" onclick="togglePrivateDM()">New DM</button>
+            <button id="auth-logout-btn" type="button" class="btn btn-secondary" hidden>Sign out</button>
-          </header>
+            <button type="button" class="btn btn-secondary" onclick="togglePrivateDM()">New DM</button>
-
+          </div>
-          <section id="messages" class="chat-messages" aria-live="polite" aria-label="Message stream"></section>
+        </header>
-
+
-          <section id="presence-panel" class="presence-panel" aria-label="Online users">
+        <div id="auth-panel" class="auth-modal" hidden>
-            <div id="presence-list" class="presence-list"></div>
+          <div id="auth-backdrop" class="auth-modal-backdrop"></div>
-          </section>
+          <div class="auth-modal-content">
-
+            <button id="auth-close-btn" type="button" class="btn auth-close" aria-label="Close sign in">×</button>
-          <div class="chat-input-area">
+            <h2 class="auth-modal-title">Sign in</h2>
-            <div class="chat-input-row">
+            <input id="auth-username" type="text" class="input" placeholder="Username" autocomplete="username" />
-              <label for="message-input" class="sr-only">Message input</label>
+            <input id="auth-password" type="password" class="input" placeholder="Password" autocomplete="current-password" />
-              <input
+            <div class="button-row">
-                id="message-input"
+              <button id="auth-login-btn" type="button" class="btn btn-primary">Log in</button>
-                type="text"
+              <button id="auth-register-btn" type="button" class="btn btn-secondary">Register</button>
-                placeholder="Type a message..."
+            </div>
-                class="input"
+            <p id="auth-status" class="status-line" aria-live="polite"></p>
-                onkeydown="if (event.key === 'Enter') sendMessage();"
+          </div>
-              />
+        </div>
-              <button type="button" class="btn btn-primary" onclick="sendMessage()">Send</button>
+
-            </div>
+        <div id="chat-flash" class="chat-flash" aria-live="polite" hidden></div>
-            <p class="chat-note">Synced with video • Moderation active</p>
+
-          </div>
+        <section id="messages" class="chat-messages" aria-live="polite"></section>
-        </aside>
+
-      </section>
+        <section id="presence-panel" class="presence-panel">
-    </main>
+          <div id="presence-list" class="presence-list"></div>
-
+        </section>
-    <script type="module" src="/src/main.ts"></script>
+
-  </body>
+        <div class="chat-input-area">
-</html>
+          <div class="chat-input-row">
+            <label for="message-input" class="sr-only">Message input</label>
+            <input id="message-input" type="text" placeholder="Type a message..." class="input" onkeydown="if (event.key === 'Enter') sendMessage();" />
+            <button type="button" class="btn btn-primary" onclick="sendMessage()">Send</button>
+          </div>
+          <p class="chat-note">Synced with video • Moderation active</p>
+        </div>
+      </aside>
+    </section>
+  </main>
+
+  <div id="reconnecting-overlay" class="reconnecting-overlay hidden" role="alert" aria-live="assertive">
+    <div class="reconnecting-spinner"></div>
+    <span id="reconnecting-text">Reconnecting...</span>
+  </div>
+
+  <script>
+    (function () {
+      // Load Matomo analytics when configured via the admin runtime config.
+      fetch("/api/matomo")
+        .then(function (r) {
+          return r.ok ? r.json() : null;
+        })
+        .then(function (cfg) {
+          if (!cfg || !cfg.matomoUrl || !cfg.matomoSiteId) return;
+          var _paq = (window._paq = window._paq || []);
+          _paq.push(["trackPageView"]);
+          _paq.push(["enableLinkTracking"]);
+          var base = String(cfg.matomoUrl).replace(/\/+$/, "");
+          _paq.push(["setTrackerUrl", base + "/matomo.php"]);
+          _paq.push(["setSiteId", String(cfg.matomoSiteId)]);
+          var d = document;
+          var g = d.createElement("script");
+          var s = d.getElementsByTagName("script")[0];
+          g.async = true;
+          g.src = base + "/matomo.js";
+          s.parentNode.insertBefore(g, s);
+        })
+        .catch(function () {
+          /* analytics is optional */
+        });
+    })();
+  </script>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+
+</html>

frontend/package.json

@@ -1,24 +1,29 @@
-{
+{
-  "name": "frontend",
+  "name": "frontend",
-  "private": true,
+  "private": true,
-  "version": "1.0.10",
+  "version": "1.1.0",
-  "type": "module",
+  "type": "module",
-  "scripts": {
+  "engines": {
-    "dev": "vite",
+    "node": ">=22.0.0"
-    "build": "tsc && vite build",
+  },
-    "preview": "vite preview",
+  "scripts": {
-    "lint": "tsc --noEmit",
+    "dev": "vite",
-    "test": "vitest run",
+    "build": "tsc && vite build",
-    "test:watch": "vitest"
+    "preview": "vite preview",
-  },
+    "lint": "tsc --noEmit",
-  "devDependencies": {
+    "test": "vitest run",
-    "@vitest/ui": "^4.1.10",
+    "test:coverage": "vitest run --coverage",
-    "jsdom": "^30.0.1",
+    "test:watch": "vitest"
-    "typescript": "~6.0.2",
+  },
-    "vite": "^8.2.0",
+  "devDependencies": {
-    "vitest": "^4.1.10"
+    "@vitest/coverage-v8": "^4.1.10",
-  },
+    "@vitest/ui": "^4.1.10",
-  "dependencies": {
+    "jsdom": "^30.0.1",
-    "hls.js": "^1.6.16"
+    "typescript": "~6.0.2",
-  }
+    "vite": "^8.2.0",
-}
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "hls.js": "^1.6.16"
+  }
+}

frontend/public/admin/chat-log.html

@@ -21,7 +21,7 @@
 
 <div class="panel-card">
   <div class="table-wrap">
-    <table class="data-table">
+    <table class="data-table chat-log-table">
       <thead>
         <tr>
           <th><input type="checkbox" id="chat-log-select-all" title="Select all" /></th>
@@ -43,4 +43,4 @@
     <button id="chat-log-next-btn" type="button" class="btn btn-secondary" disabled>Next</button>
   </div>
   <p id="chat-log-status" class="status-line" aria-live="polite">Loading chat log...</p>
-</div>
+</div>

frontend/public/admin/system.html

@@ -56,8 +56,13 @@
 <div class="panel-card">
   <h2>Runtime Configuration</h2>
   <form id="config-form" class="form-stack" style="max-width: 400px">
+    <label>HLS Segment Duration (seconds) <input id="config-hls-duration" type="number" min="2" max="15" class="text-input" /></label>
+    <label>HLS Window Size (segments) <input id="config-hls-window" type="number" min="3" max="100" class="text-input" /></label>
+    <label>Matomo URL <input id="config-matomo-url" type="url" class="text-input" placeholder="https://..." /></label>
+    <label>Matomo Site ID <input id="config-matomo-site-id" type="text" class="text-input" /></label>
     <label>Rate Limit Max <input id="config-rate-max" type="number" class="text-input" /></label>
     <label>Rate Limit Window (seconds) <input id="config-rate-window" type="number" class="text-input" /></label>
+    <p class="small-muted">HLS changes take effect after restarting the playout service.</p>
     <button type="submit" class="btn btn-primary">Save Config</button>
   </form>
   <p id="config-status" class="status-line" aria-live="polite"></p>

frontend/src/admin.test.ts

@@ -1,142 +1,378 @@
-/// <reference types="vitest" />
+/// <reference types="vitest" />
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-
+import { refreshAnalytics, refreshOverview, renderPlaylistSortable, savePlaylist } from "../src/admin";
-// Mock fetch globally
+
-let fetchCalls: { url: string; options?: RequestInit }[] = [];
+// Mock fetch globally
-let mockFetchResponse: any = { ok: true, json: () => Promise.resolve({}) };
+let fetchCalls: { url: string; options?: RequestInit }[] = [];
-
+let mockFetchResponse: any = { ok: true, payload: {} };
-beforeEach(() => {
+
-  fetchCalls = [];
+beforeEach(() => {
-  globalThis.fetch = vi.fn((url: string, options?: RequestInit) => {
+  fetchCalls = [];
-    fetchCalls.push({ url, options });
+  globalThis.fetch = vi.fn(async (url: string, options?: RequestInit) => {
-    return Promise.resolve(
+    fetchCalls.push({ url, options });
-      new Response(JSON.stringify(mockFetchResponse.json ? mockFetchResponse.json() : mockFetchResponse), {
+    const payload = mockFetchResponse.payload ?? {};
-        status: mockFetchResponse.ok ? 200 : mockFetchResponse.status || 500,
+    return Promise.resolve(
-        headers: { "Content-Type": "application/json" },
+      new Response(JSON.stringify(payload), {
-      }),
+        status: mockFetchResponse.ok ? 200 : mockFetchResponse.status || 500,
-    );
+        headers: { "Content-Type": "application/json" },
-  }) as any;
+      }),
-
+    );
-  // Mock localStorage
+  }) as any;
-  const storage = new Map<string, string>();
+
-  Object.defineProperty(window, "localStorage", {
+  // Mock localStorage
-    value: {
+  const storage = new Map<string, string>();
-      getItem: vi.fn((key: string) => storage.get(key) ?? null),
+  Object.defineProperty(window, "localStorage", {
-      setItem: vi.fn((key: string, val: string) => storage.set(key, val)),
+    value: {
-      removeItem: vi.fn((key: string) => storage.delete(key)),
+      getItem: vi.fn((key: string) => storage.get(key) ?? null),
-    },
+      setItem: vi.fn((key: string, val: string) => storage.set(key, val)),
-    writable: true,
+      removeItem: vi.fn((key: string) => storage.delete(key)),
-  });
+    },
-
+    writable: true,
-  // Mock window.confirm/prompt
+  });
-  vi.spyOn(window, "confirm").mockReturnValue(true);
+
-  vi.spyOn(window, "prompt").mockReturnValue(null);
+  // Mock window.confirm/prompt
-  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(window, "confirm").mockReturnValue(true);
-});
+  vi.spyOn(window, "prompt").mockReturnValue(null);
-
+  vi.spyOn(console, "error").mockImplementation(() => {});
-afterEach(() => {
+});
-  vi.restoreAllMocks();
+
-});
+afterEach(() => {
-
+  vi.restoreAllMocks();
-// Import after mocks are set
+});
-import "../src/admin";
+
-
+// Import after mocks are set
-describe("admin.ts initialization", () => {
+import "../src/admin";
-  it("loads and exposes tab switching", () => {
+
-    // After import, init() runs on DOMContentLoaded
+describe("admin.ts initialization", () => {
-    // Test that the document has admin page structure
+  it("loads and exposes tab switching", () => {
-    expect(document.body).toBeDefined();
+    // After import, init() runs on DOMContentLoaded
-  });
+    // Test that the document has admin page structure
-});
+    expect(document.body).toBeDefined();
-
+  });
-describe("upload progress helpers", () => {
+});
-  it("renders upload progress correctly", async () => {
+
-    // Set up DOM for upload page
+describe("upload progress helpers", () => {
-    document.body.innerHTML = `
+  it("renders upload progress correctly", async () => {
-      <div id="media-upload-progress-wrap" hidden>
+    // Set up DOM for upload page
-        <progress id="media-upload-progress" max="100" value="0"></progress>
+    document.body.innerHTML = `
-        <span id="media-upload-progress-text"></span>
+      <div id="media-upload-progress-wrap" hidden>
-      </div>
+        <progress id="media-upload-progress" max="100" value="0"></progress>
-      <div id="tab-content"></div>
+        <span id="media-upload-progress-text"></span>
-    `;
+      </div>
-
+      <div id="tab-content"></div>
-    // Re-import triggers init again — but we need fresh module state
+    `;
-    // For now test internal helper access via body
+
-    const wrap = document.getElementById("media-upload-progress-wrap")!;
+    // Re-import triggers init again — but we need fresh module state
-    const bar = document.getElementById("media-upload-progress") as HTMLProgressElement;
+    // For now test internal helper access via body
-    const text = document.getElementById("media-upload-progress-text")!;
+    const wrap = document.getElementById("media-upload-progress-wrap")!;
-
+    const bar = document.getElementById("media-upload-progress") as HTMLProgressElement;
-    expect(wrap.hidden).toBe(true);
+    const text = document.getElementById("media-upload-progress-text")!;
-
+
-    // Simulate what setUploadProgress would do
+    expect(wrap.hidden).toBe(true);
-    wrap.hidden = false;
+
-    bar.max = 100;
+    // Simulate what setUploadProgress would do
-    bar.value = 50;
+    wrap.hidden = false;
-    text.textContent = "Uploading (50%)";
+    bar.max = 100;
-
+    bar.value = 50;
-    expect(wrap.hidden).toBe(false);
+    text.textContent = "Uploading (50%)";
-    expect(bar.value).toBe(50);
+
-    expect(text.textContent).toBe("Uploading (50%)");
+    expect(wrap.hidden).toBe(false);
-  });
+    expect(bar.value).toBe(50);
-});
+    expect(text.textContent).toBe("Uploading (50%)");
-
+  });
-describe("file fingerprint", () => {
+});
-  it("generates unique fingerprints for different files", () => {
+
-    const f1 = new File(["a"], "video1.mp4", { lastModified: 1 });
+describe("file fingerprint", () => {
-    const f2 = new File(["b"], "video2.mp4", { lastModified: 2 });
+  it("generates unique fingerprints for different files", () => {
-
+    const f1 = new File(["a"], "video1.mp4", { lastModified: 1 });
-    const fp1 = `${f1.name}:${f1.size}:${f1.lastModified}`;
+    const f2 = new File(["b"], "video2.mp4", { lastModified: 2 });
-    const fp2 = `${f2.name}:${f2.size}:${f2.lastModified}`;
+
-
+    const fp1 = `${f1.name}:${f1.size}:${f1.lastModified}`;
-    expect(fp1).not.toBe(fp2);
+    const fp2 = `${f2.name}:${f2.size}:${f2.lastModified}`;
-    expect(fp1).toBe("video1.mp4:1:1");
+
-    expect(fp2).toBe("video2.mp4:1:2");
+    expect(fp1).not.toBe(fp2);
-  });
+    expect(fp1).toBe("video1.mp4:1:1");
-});
+    expect(fp2).toBe("video2.mp4:1:2");
-
+  });
-describe("MAX_UPLOAD_BYTES constant", () => {
+});
-  it("equals 2GB", () => {
+
-    expect(2 * 1024 * 1024 * 1024).toBe(2147483648);
+describe("MAX_UPLOAD_BYTES constant", () => {
-  });
+  it("equals 2GB", () => {
-});
+    expect(2 * 1024 * 1024 * 1024).toBe(2147483648);
-
+  });
-describe("API calls on tab load", () => {
+});
-  beforeEach(() => {
+
-    document.body.innerHTML = `
+describe("API calls on tab load", () => {
-      <div id="tab-content"><div id="overview-content"></div></div>
+  beforeEach(() => {
-      <nav class="admin-nav">
+    document.body.innerHTML = `
-        <button data-tab="dashboard">Dashboard</button>
+      <div id="tab-content"><div id="overview-content"></div></div>
-        <button data-tab="analytics">Analytics</button>
+      <nav class="admin-nav">
-        <button data-tab="playlist">Playlist</button>
+        <button data-tab="dashboard">Dashboard</button>
-        <button data-tab="schedule">Schedule</button>
+        <button data-tab="analytics">Analytics</button>
-        <button data-tab="system">System</button>
+        <button data-tab="playlist">Playlist</button>
-        <button data-tab="upload">Upload</button>
+        <button data-tab="schedule">Schedule</button>
-        <button data-tab="users">Users</button>
+        <button data-tab="system">System</button>
-        <button data-tab="moderation">Moderation</button>
+        <button data-tab="upload">Upload</button>
-        <button data-tab="chat-log">Chat Log</button>
+        <button data-tab="users">Users</button>
-      </nav>
+        <button data-tab="moderation">Moderation</button>
-      <div id="overview-stats"></div>
+        <button data-tab="chat-log">Chat Log</button>
-      <div id="analytics-stats"></div>
+      </nav>
-      <div id="playlist-editor"></div>
+      <div id="overview-stats"></div>
-      <div id="schedule-list"></div>
+      <div id="analytics-stats"></div>
-      <div id="system-summary"></div>
+      <div id="playlist-editor"></div>
-      <div id="media-upload-progress-wrap" hidden>
+      <div id="schedule-list"></div>
-        <progress id="media-upload-progress"></progress>
+      <div id="system-summary"></div>
-        <span id="media-upload-progress-text"></span>
+      <div id="media-upload-progress-wrap" hidden>
-      </div>
+        <progress id="media-upload-progress"></progress>
-      <div id="media-table-body"></div>
+        <span id="media-upload-progress-text"></span>
-      <div id="users-table-body"></div>
+      </div>
-      <div id="moderation-log-table-body"></div>
+      <div id="media-table-body"></div>
-      <div id="chat-log-table-body"></div>
+      <div id="users-table-body"></div>
-      <div id="chat-log-pagination"></div>
+      <div id="moderation-log-table-body"></div>
-      <div id="config-editor"></div>
+      <div id="chat-log-table-body"></div>
-      <span id="restart-status"></span>
+      <div id="chat-log-pagination"></div>
-      <div id="schedule-override-list"></div>
+      <div id="config-editor"></div>
-    `;
+      <span id="restart-status"></span>
-  });
+      <div id="schedule-override-list"></div>
-
+    `;
-  it("can be imported without crashing", () => {
+  });
-    // admin.ts initialization should not throw
+
-    expect(true).toBe(true);
+  it("can be imported without crashing", () => {
-  });
+    // admin.ts initialization should not throw
-});
+    expect(true).toBe(true);
+  });
+});
+
+describe("admin data refresh", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="overview-status"></div>
+      <span id="stat-viewers"></span>
+      <span id="stat-stored-messages"></span>
+      <span id="stat-moderation-actions"></span>
+      <span id="stat-media-runtime"></span>
+      <span id="stat-media-count"></span>
+      <span id="system-stored-messages"></span>
+      <span id="system-redis-clients"></span>
+      <span id="system-redis-enabled"></span>
+      <span id="system-redis-memory"></span>
+      <span id="system-db-driver"></span>
+      <span id="system-generated-at"></span>
+      <div id="analytics-status"></div>
+      <span id="analytics-total-messages"></span>
+      <span id="analytics-messages-24h"></span>
+      <span id="analytics-distinct-rooms"></span>
+      <span id="analytics-moderation-actions"></span>
+      <span id="analytics-generated-at"></span>
+      <table><tbody id="analytics-table-body"></tbody></table>
+    `;
+  });
+
+  it("renders overview stats from the admin overview API", async () => {
+    mockFetchResponse = {
+      ok: true,
+      payload: {
+        viewers: 12,
+        storedMessages: 345,
+        moderationActions: 9,
+        mediaTotalRuntime: "01:23:45",
+        mediaCount: 7,
+        redisClients: 4,
+        redisEnabled: true,
+        redisMemoryUsed: "18 MB",
+        databaseDriver: "sqlite",
+        generatedAt: "2026-08-08T12:00:00Z",
+      },
+    };
+
+    await refreshOverview();
+
+    expect(document.getElementById("stat-viewers")?.textContent).toBe("12");
+    expect(document.getElementById("stat-stored-messages")?.textContent).toBe("345");
+    expect(document.getElementById("system-redis-enabled")?.textContent).toBe("yes");
+    expect(document.getElementById("overview-status")?.textContent).toContain("2026-08-08T12:00:00Z");
+  });
+
+  it("renders analytics rows from the analytics API", async () => {
+    mockFetchResponse = {
+      ok: true,
+      payload: {
+        totalMessages: 1000,
+        messagesLast24Hours: 75,
+        distinctRooms: 3,
+        moderationActions: 11,
+        generatedAt: "2026-08-08T12:30:00Z",
+        topRooms: [
+          { room: "main", messageCount: 55 },
+          { room: "lobby", messageCount: 20 },
+        ],
+      },
+    };
+
+    await refreshAnalytics();
+
+    expect(document.getElementById("analytics-total-messages")?.textContent).toBe("1000");
+    expect(document.getElementById("analytics-messages-24h")?.textContent).toBe("75");
+    expect(document.getElementById("analytics-table-body")?.textContent).toContain("main");
+    expect(document.getElementById("analytics-table-body")?.textContent).toContain("lobby");
+  });
+});
+
+describe("playlist management", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="playlist-status"></div>
+      <textarea id="playlist-content">file '/app/media/demo1.mp4'
+file '/app/media/demo2.mp4'
+</textarea>
+      <ul id="playlist-sortable"></ul>
+      <div id="playlist-warnings" hidden></div>
+    `;
+  });
+
+  it("saves playlist via PUT request", async () => {
+    mockFetchResponse = { ok: true, payload: {} };
+
+    await savePlaylist();
+
+    const putCall = fetchCalls.find((c) => c.options?.method === "PUT");
+    expect(putCall).toBeDefined();
+    expect(putCall?.url).toBe("/api/admin/playlist");
+    expect(putCall?.options?.headers).toEqual({ "Content-Type": "application/json" });
+    const body = JSON.parse(putCall?.options?.body as string);
+    expect(body.content).toContain("demo1.mp4");
+  });
+
+  it("sets error status on save failure", async () => {
+    mockFetchResponse = { ok: false, status: 500, payload: {} };
+
+    await savePlaylist();
+
+    const status = document.getElementById("playlist-status");
+    expect(status?.textContent).toContain("Failed");
+  });
+
+  it("renders sortable playlist with indexes and paths", () => {
+    renderPlaylistSortable("file '/app/media/demo1.mp4'\nfile '/app/media/demo2.mp4'\n");
+
+    const list = document.getElementById("playlist-sortable")!;
+    expect(list.children).toHaveLength(2);
+    expect(list.innerHTML).toContain("demo1.mp4");
+    expect(list.innerHTML).toContain("demo2.mp4");
+    expect(list.querySelector(".sortable-index")?.textContent).toBe("1");
+    expect(list.querySelector("[data-remove]")).toBeTruthy();
+  });
+
+  it("skips comment and blank lines in sortable", () => {
+    renderPlaylistSortable("# comment\n\nfile '/app/media/demo1.mp4'\n");
+
+    const list = document.getElementById("playlist-sortable")!;
+    expect(list.children).toHaveLength(1);
+    expect(list.innerHTML).toContain("demo1.mp4");
+  });
+});
+
+describe("admin accessibility", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <nav class="admin-nav" aria-label="Admin navigation">
+        <button data-tab="dashboard" aria-current="page">Dashboard</button>
+        <button data-tab="playlist">Playlist</button>
+        <button data-tab="users">Users</button>
+        <button data-tab="moderation">Moderation</button>
+      </nav>
+      <div id="tab-content"></div>
+    `;
+  });
+
+  it("nav has aria-label for screen readers", () => {
+    const nav = document.querySelector(".admin-nav");
+    expect(nav?.getAttribute("aria-label")).toBe("Admin navigation");
+  });
+
+  it("active tab has aria-current attribute", () => {
+    const active = document.querySelector("[aria-current]");
+    expect(active).toBeTruthy();
+    expect(active?.getAttribute("aria-current")).toBe("page");
+  });
+
+  it("all nav buttons are focusable", () => {
+    const buttons = document.querySelectorAll(".admin-nav button");
+    buttons.forEach((btn) => {
+      expect(btn.getAttribute("tabindex")).toBeNull();
+      expect(btn.getAttribute("disabled")).toBeNull();
+    });
+  });
+});
+
+describe("admin responsive layout", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <nav class="admin-nav"><button data-tab="dashboard">Dashboard</button></nav>
+      <div id="tab-content"><div id="overview-content">Overview data</div></div>
+    `;
+  });
+
+  it("tab content is present and visible", () => {
+    const tabContent = document.getElementById("tab-content");
+    expect(tabContent).toBeTruthy();
+    const style = window.getComputedStyle(tabContent!);
+    expect(style.display).not.toBe("none");
+  });
+
+  it("admin nav contains essential tabs", () => {
+    const buttons = document.querySelectorAll(".admin-nav button");
+    const tabs = Array.from(buttons).map((b) => b.textContent?.trim());
+    expect(tabs).toContain("Dashboard");
+  });
+});
+
+describe("admin data refresh failures", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="overview-status"></div>
+      <div id="analytics-status"></div>
+    `;
+  });
+
+  it("sets error status when overview fails", async () => {
+    mockFetchResponse = { ok: false, status: 500, payload: {} };
+    await refreshOverview();
+    expect(document.getElementById("overview-status")?.textContent).toContain("Failed");
+  });
+
+  it("sets error status when analytics fails", async () => {
+    mockFetchResponse = { ok: false, status: 500, payload: {} };
+    await refreshAnalytics();
+    expect(document.getElementById("analytics-status")?.textContent).toContain("Failed");
+  });
+});
+
+describe("playlist status badges", () => {
+  beforeEach(() => {
+    document.body.innerHTML = `<ul id="playlist-sortable"></ul>`;
+  });
+
+  it("renders badges for every media status", () => {
+    const statusMap = new Map<string, string>([
+      ["/app/media/ready.mp4", "ready"],
+      ["/app/media/needs.mp4", "needs_normalization"],
+      ["/app/media/normalizing.mp4", "normalizing"],
+      ["/app/media/failed.mp4", "normalization_failed"],
+      ["/app/media/other.mp4", "weird"],
+    ]);
+
+    renderPlaylistSortable(
+      "file '/app/media/ready.mp4'\nfile '/app/media/needs.mp4'\nfile '/app/media/normalizing.mp4'\nfile '/app/media/failed.mp4'\nfile '/app/media/other.mp4'\nfile '/app/media/nopath.mp4'\n",
+      statusMap,
+    );
+
+    const list = document.getElementById("playlist-sortable")!;
+    expect(list.innerHTML).toContain("badge-ok");
+    expect(list.innerHTML).toContain("badge-warn");
+    expect(list.innerHTML).toContain("badge-info");
+    expect(list.innerHTML).toContain("badge-danger");
+    expect(list.innerHTML).toContain("badge-muted"); // default + unknown fall back to muted
+    expect(list.children).toHaveLength(6);
+  });
+});

frontend/src/admin.ts

@@ -16,6 +16,7 @@ type MediaEntry = {
   runtime?: string;
   modifiedAt?: string;
   tags?: string;
+  path?: string;
 };
 
 const bodyDataset = document.body.dataset;
@@ -30,6 +31,7 @@ const adminConfig = {
 const MAX_UPLOAD_BYTES = 2 * 1024 * 1024 * 1024;
 const UPLOAD_CHUNK_BYTES = 8 * 1024 * 1024;
 const UPLOAD_RESUME_KEY_PREFIX = "linearvoid-upload-resume:";
+const API_URL = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
 
 const state = {
   mediaUploading: false,
@@ -130,7 +132,7 @@ const pageCache: Record<string, string> = {};
 async function loadPageContent(tabName: string): Promise<string> {
   if (pageCache[tabName]) return pageCache[tabName];
 
-  const response = await fetch(`/admin/${tabName}.html`);
+  const response = await fetch(`${API_URL}/admin/${tabName}.html`);
   if (!response.ok) throw new Error(`Failed to load page: ${tabName}`);
   const html = await response.text();
   pageCache[tabName] = html;
@@ -172,9 +174,9 @@ async function switchTab(tabName: string) {
   if (tabName === "system") refreshSystemSummary();
 }
 
-async function refreshOverview() {
+export async function refreshOverview() {
   try {
-    const response = await fetch("/api/admin/overview");
+    const response = await fetch(`${API_URL}/api/admin/overview`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
 
     const payload = await response.json();
@@ -198,10 +200,10 @@ async function refreshOverview() {
   }
 }
 
-async function refreshAnalytics() {
+export async function refreshAnalytics() {
   setStatus("analytics-status", "Loading analytics...");
   try {
-    const response = await fetch("/api/admin/analytics");
+    const response = await fetch(`${API_URL}/api/admin/analytics`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
 
     const payload = await response.json();
@@ -239,14 +241,15 @@ async function refreshAnalytics() {
 async function refreshPlaylist() {
   setStatus("playlist-status", "Loading playlist...");
   try {
-    const response = await fetch("/api/admin/playlist");
+    const response = await fetch(`${API_URL}/api/admin/playlist`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
 
     const payload = await response.json();
     const content: string = payload.content || "";
     const textarea = document.getElementById("playlist-content") as HTMLTextAreaElement | null;
     if (textarea) textarea.value = content;
-    renderPlaylistSortable(content);
+    const statusMap = await fetchMediaStatusMap();
+    renderPlaylistSortable(content, statusMap);
     await showPlaylistWarnings(content);
     setStatus("playlist-status", "Playlist loaded.");
   } catch (error) {
@@ -255,7 +258,7 @@ async function refreshPlaylist() {
   }
 }
 
-function renderPlaylistSortable(content: string) {
+export function renderPlaylistSortable(content: string, statusMap?: Map<string, string>) {
   const list = document.getElementById("playlist-sortable");
   if (!list) return;
   const lines = content.split("\n").filter((l) => l.trim() && !l.startsWith("#"));
@@ -265,10 +268,12 @@ function renderPlaylistSortable(content: string) {
         .replace(/^file\s+/, "")
         .replace(/['"]/g, "")
         .trim();
+      const badge = statusMap ? statusBadge(statusMap.get(path)) : "";
       return `<li class="sortable-item" draggable="true" data-index="${i}">
         <span class="drag-handle" aria-hidden="true">⋮⋮</span>
         <span class="sortable-index">${i + 1}</span>
         <span class="sortable-path">${path}</span>
+        ${badge}
         <button type="button" class="btn btn-secondary btn-sm" data-remove="${i}">✕</button>
       </li>`;
     })
@@ -352,7 +357,81 @@ async function showPlaylistWarnings(content: string) {
   }
 }
 
-async function savePlaylist() {
+function statusBadge(status: string | undefined): string {
+  if (!status) return `<span class="badge badge-muted">unknown</span>`;
+  switch (status) {
+    case "ready":
+      return `<span class="badge badge-ok">ready</span>`;
+    case "needs_normalization":
+      return `<span class="badge badge-warn">needs normalization</span>`;
+    case "normalizing":
+      return `<span class="badge badge-info">normalizing</span>`;
+    case "normalization_failed":
+      return `<span class="badge badge-danger">failed</span>`;
+    default:
+      return `<span class="badge badge-muted">${status}</span>`;
+  }
+}
+
+async function fetchMediaStatusMap(): Promise<Map<string, string>> {
+  const map = new Map<string, string>();
+  try {
+    const resp = await fetch("/api/admin/media");
+    if (!resp.ok) return map;
+    const payload = await resp.json();
+    for (const f of payload.files || []) {
+      if (f.path) map.set(f.path, f.status || "unknown");
+    }
+  } catch {
+    /* ignore */
+  }
+  return map;
+}
+
+async function addMediaToPlaylist(file: MediaEntry) {
+  if (file.status !== "ready") {
+    setStatus("media-status", "Only ready media can be added to the playlist.", true);
+    return;
+  }
+  if (!file.path) {
+    setStatus("media-status", "Cannot add media without a path.", true);
+    return;
+  }
+  setStatus("media-status", `Adding ${file.name} to playlist...`);
+  try {
+    const getResp = await fetch("/api/admin/playlist");
+    if (!getResp.ok) throw new Error(await readErrorMessage(getResp));
+    const payload = await getResp.json();
+    const content: string = payload.content || "";
+    const lines = content.split("\n").filter((l) => l.trim());
+    const entry = `file '${file.path}'`;
+    const exists = lines.some(
+      (l) =>
+        l
+          .replace(/^file\s+/, "")
+          .replace(/['"]/g, "")
+          .trim() === file.path,
+    );
+    if (exists) {
+      setStatus("media-status", `${file.name} is already in the playlist.`, true);
+      return;
+    }
+    lines.push(entry);
+    const putResp = await fetch("/api/admin/playlist", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ content: lines.join("\n") + "\n" }),
+    });
+    if (!putResp.ok) throw new Error(await readErrorMessage(putResp));
+    setStatus("media-status", `${file.name} added to playlist.`);
+  } catch (error) {
+    console.error("Failed to add media to playlist", error);
+    const details = error instanceof Error ? error.message : "Unknown error.";
+    setStatus("media-status", `Failed to add ${file.name} to playlist. (${details})`, true);
+  }
+}
+
+export async function savePlaylist() {
   if (state.playlistSaving) return;
   state.playlistSaving = true;
   setStatus("playlist-status", "Saving playlist...");
@@ -444,7 +523,7 @@ async function submitOverride(e: Event) {
   const endTime = (document.getElementById("override-end") as HTMLInputElement).value;
   const reason = (document.getElementById("override-reason") as HTMLInputElement).value;
   try {
-    const resp = await fetch("/api/admin/schedule/overrides", {
+    const resp = await fetch(`${API_URL}/api/admin/schedule/overrides`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -473,13 +552,48 @@ async function submitOverride(e: Event) {
 
 async function deleteOverride(id: number) {
   try {
-    await fetch(`/api/admin/schedule/overrides?id=${id}`, { method: "DELETE" });
+    await fetch(`${API_URL}/api/admin/schedule/overrides?id=${id}`, { method: "DELETE" });
     refreshOverrides();
   } catch {
     /* ignore */
   }
 }
 
+async function renderServiceRow(service: any) {
+  const svcDetail = service.detail || "";
+
+  // playout service returns json detail, all others return `local process` or `ping ok`
+  if (service.name === "playout" && svcDetail) {
+    try {
+      // create a list of key-value pairs for each property in the JSON object
+      const detailObj = JSON.parse(svcDetail);
+      // create a table of key-value pairs for each property in the JSON object
+      const detailTable = Object.entries(detailObj)
+        .map(([key, value]) => `<tr><td><strong>${key}</strong></td><td>${value}</td></tr>`)
+        .join("");
+      service.detail = `<p><table class="service-detail-table">${detailTable}</table></p>`;
+    } catch {
+      // ignore JSON parse errors
+    }
+  } else {
+    service.detail = `<p>${service.detail}</p>`;
+  }
+
+  const row = document.createElement("article");
+  row.className = "service-row";
+  row.innerHTML = `
+    <div>
+      <h3>${service.name}</h3>
+      <p class="small-muted">${service.checked}</p>
+    </div>
+    <div class="service-row-right">
+      <p class="service-status service-status-${service.status}">${service.status}</p>
+      ${service.detail}
+    </div>
+  `;
+  return row;
+}
+
 async function refreshSystemSummary() {
   setStatus("system-status", "Loading system summary...");
   try {
@@ -499,19 +613,9 @@ async function refreshSystemSummary() {
       servicesEl.innerHTML = "";
       const services = (payload.services || []) as ServiceHealth[];
       services.forEach((service) => {
-        const row = document.createElement("article");
+        renderServiceRow(service).then((row) => {
-        row.className = "service-row";
+          servicesEl.appendChild(row);
-        row.innerHTML = `
+        });
-          <div>
-            <h3>${service.name}</h3>
-            <p class="small-muted">${service.checked}</p>
-          </div>
-          <div class="service-row-right">
-            <p class="service-status service-status-${service.status}">${service.status}</p>
-            <p>${service.detail}</p>
-          </div>
-        `;
-        servicesEl.appendChild(row);
       });
     }
 
@@ -534,19 +638,29 @@ function renderMediaRows(files: MediaEntry[]) {
 
   files.forEach((file) => {
     const tr = document.createElement("tr");
+    const canNormalize = file.status === "needs_normalization" || file.status === "normalization_failed";
+    const canAdd = file.status === "ready";
     tr.innerHTML = `
       <td>${file.name}</td>
       <td>${file.title || "-"}</td>
       <td>${file.runtime || "00:00:00"}</td>
-      <td>${file.status || "unknown"}</td>
+      <td>${statusBadge(file.status)}</td>
       <td>${fmtSize(file.size)}</td>
       <td>${file.modifiedAt || "-"}</td>
       <td class="action-cell">
         <button type="button" class="btn btn-secondary btn-small" data-action="edit" data-id="${file.id || ""}">Edit</button>
+        ${canNormalize ? `<button type="button" class="btn btn-secondary btn-small" data-action="normalize" data-id="${file.id || ""}">Normalize</button>` : ""}
+        ${canAdd ? `<button type="button" class="btn btn-secondary btn-small" data-action="add" data-id="${file.id || ""}">Add to playlist</button>` : ""}
         <button type="button" class="btn btn-danger btn-small" data-action="delete" data-id="${file.id || ""}">Delete</button>
       </td>
     `;
     tr.querySelector('[data-action="edit"]')?.addEventListener("click", () => editMedia(file));
+    if (canNormalize) {
+      tr.querySelector('[data-action="normalize"]')?.addEventListener("click", () => normalizeMedia(file));
+    }
+    if (canAdd) {
+      tr.querySelector('[data-action="add"]')?.addEventListener("click", () => addMediaToPlaylist(file));
+    }
     tr.querySelector('[data-action="delete"]')?.addEventListener("click", () => deleteMedia(file));
     tbody.appendChild(tr);
   });
@@ -640,9 +754,12 @@ async function uploadVideo(file: File) {
       setStatus("media-status", `Uploading ${file.name} (${chunkIndex + 1}/${effectiveTotalChunks} chunks)...`);
     }
 
-    const completeResponse = await fetch(`/api/admin/media/uploads/${encodeURIComponent(uploadId)}/complete`, {
+    const completeResponse = await fetch(
-      method: "POST",
+      `${API_URL}/api/admin/media/uploads/${encodeURIComponent(uploadId)}/complete`,
-    });
+      {
+        method: "POST",
+      },
+    );
 
     if (!completeResponse.ok) {
       throw new Error(await readErrorMessage(completeResponse));
@@ -682,7 +799,7 @@ async function editMedia(file: MediaEntry) {
 
   setStatus("media-status", `Saving metadata for ${file.name}...`);
   try {
-    const response = await fetch(`/api/admin/media/${file.id}`, {
+    const response = await fetch(`${API_URL}/api/admin/media/${file.id}`, {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ title, status, tags }),
@@ -699,6 +816,55 @@ async function editMedia(file: MediaEntry) {
   }
 }
 
+async function normalizeMedia(file: MediaEntry) {
+  if (!file.id) {
+    setStatus("media-status", "Cannot normalize media item without id.", true);
+    return;
+  }
+
+  setStatus("media-status", `Normalizing ${file.name}...`);
+  try {
+    const response = await fetch(`${API_URL}/api/admin/media/${file.id}/normalize`, { method: "POST" });
+    if (!response.ok) throw new Error(await readErrorMessage(response));
+
+    setStatus("media-status", `Normalization started for ${file.name}.`);
+    await refreshMediaLibrary();
+    pollNormalizationStatus(file.id, 0);
+  } catch (error) {
+    console.error("Failed to normalize media", error);
+    const details = error instanceof Error ? error.message : "Unknown error.";
+    setStatus("media-status", `Failed to normalize ${file.name}. (${details})`, true);
+  }
+}
+
+function pollNormalizationStatus(id: number, attempt: number) {
+  if (attempt >= 60) {
+    setStatus("media-status", "Normalization is taking longer than expected. Reload the library to check.", true);
+    return;
+  }
+  window.setTimeout(async () => {
+    try {
+      const response = await fetch(`${API_URL}/api/admin/media/${id}`);
+      if (!response.ok) return;
+      const file = (await response.json()) as MediaEntry;
+      if (file.status === "normalizing" || file.status === "needs_normalization") {
+        pollNormalizationStatus(id, attempt + 1);
+        return;
+      }
+      await refreshMediaLibrary();
+      await refreshOverview();
+      await refreshSchedule();
+      setStatus(
+        "media-status",
+        file.status === "ready" ? `Normalization complete for ${file.name}.` : `Normalization failed for ${file.name}.`,
+        file.status !== "ready",
+      );
+    } catch {
+      // Stop polling on error; the user can reload the library manually.
+    }
+  }, 3000);
+}
+
 async function deleteMedia(file: MediaEntry) {
   if (!file.id) {
     setStatus("media-status", "Cannot delete media item without id.", true);
@@ -711,7 +877,7 @@ async function deleteMedia(file: MediaEntry) {
 
   setStatus("media-status", `Deleting ${file.name}...`);
   try {
-    const response = await fetch(`/api/admin/media/${file.id}`, {
+    const response = await fetch(`${API_URL}/api/admin/media/${file.id}`, {
       method: "DELETE",
     });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -729,7 +895,7 @@ async function deleteMedia(file: MediaEntry) {
 async function refreshModerationLogs() {
   setStatus("moderation-status", "Loading moderation logs...");
   try {
-    const response = await fetch(`/api/admin/moderation/logs?limit=${adminConfig.moderationLogLimit}`);
+    const response = await fetch(`${API_URL}/api/admin/moderation/logs?limit=${adminConfig.moderationLogLimit}`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
 
     const payload = await response.json();
@@ -830,7 +996,7 @@ async function refreshChatLog() {
     if (chatLogState.username) params.set("username", chatLogState.username);
     if (chatLogState.text) params.set("text", chatLogState.text);
 
-    const response = await fetch(`/api/admin/chat-log?${params}`);
+    const response = await fetch(`${API_URL}/api/admin/chat-log?${params}`);
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
 
     const payload = await response.json();
@@ -960,7 +1126,7 @@ async function deleteChatEntry(id: number) {
 
   setStatus("chat-log-status", `Deleting message #${id}...`);
   try {
-    const response = await fetch(`/api/admin/chat-log/${id}`, {
+    const response = await fetch(`${API_URL}/api/admin/chat-log/${id}`, {
       method: "DELETE",
     });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -1068,6 +1234,10 @@ async function loadConfig() {
     const cfg = await resp.json();
     (document.getElementById("config-rate-max") as HTMLInputElement).value = cfg.rateLimitMax;
     (document.getElementById("config-rate-window") as HTMLInputElement).value = cfg.rateLimitWindowSec;
+    (document.getElementById("config-hls-duration") as HTMLInputElement).value = cfg.hlsSegmentDuration;
+    (document.getElementById("config-hls-window") as HTMLInputElement).value = cfg.hlsWindowSize;
+    (document.getElementById("config-matomo-url") as HTMLInputElement).value = cfg.matomoUrl || "";
+    (document.getElementById("config-matomo-site-id") as HTMLInputElement).value = cfg.matomoSiteId || "";
   } catch {
     /* non-critical */
   }
@@ -1082,11 +1252,13 @@ async function saveConfig(e: Event) {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
-        rateLimitMax: Number((document.getElementById("config-rate-max") as HTMLInputElement).value),
+        hlsSegmentDuration: Number((document.getElementById("config-hls-duration") as HTMLInputElement).value),
-        rateLimitWindowSec: Number((document.getElementById("config-rate-window") as HTMLInputElement).value),
+        hlsWindowSize: Number((document.getElementById("config-hls-window") as HTMLInputElement).value),
+        matomoUrl: (document.getElementById("config-matomo-url") as HTMLInputElement).value.trim(),
+        matomoSiteId: (document.getElementById("config-matomo-site-id") as HTMLInputElement).value.trim(),
       }),
     });
-    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+    if (!resp.ok) throw new Error(await readErrorMessage(resp));
     if (status) {
       status.textContent = "Config saved.";
       status.className = "status-line";
@@ -1104,7 +1276,7 @@ async function restartService(service: string) {
   const status = document.getElementById("restart-status");
   if (status) status.textContent = `Requesting restart of ${service}...`;
   try {
-    const resp = await fetch(`/api/admin/restart?service=${service}`, { method: "POST" });
+    const resp = await fetch(`${API_URL}/api/admin/restart?service=${service}`, { method: "POST" });
     const data = await resp.json();
     if (status) status.textContent = data.message;
   } catch (err) {

frontend/src/counter.test.ts

@@ -0,0 +1,23 @@
+/// <reference types="vitest" />
+import { describe, it, expect } from "vitest";
+import { setupCounter } from "../src/counter";
+
+describe("setupCounter", () => {
+  it("initializes the button with count 0", () => {
+    const btn = document.createElement("button");
+    setupCounter(btn);
+    expect(btn.innerHTML).toBe("Count is 0");
+  });
+
+  it("increments the counter on each click", () => {
+    const btn = document.createElement("button");
+    setupCounter(btn);
+
+    btn.click();
+    expect(btn.innerHTML).toBe("Count is 1");
+
+    btn.click();
+    btn.click();
+    expect(btn.innerHTML).toBe("Count is 3");
+  });
+});

frontend/src/main.test.ts

@@ -1,161 +1,598 @@
-/// <reference types="vitest" />
+/// <reference types="vitest" />
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-
+import {
-// Mock hls.js
+  resetViewerStateForTests,
-vi.mock("hls.js", () => ({
+  resolveManifestUrl,
-  default: vi.fn().mockImplementation(() => ({
+  resolveWebSocketBaseUrl,
-    loadSource: vi.fn(),
+  showReconnecting,
-    attachMedia: vi.fn(),
+  hideReconnecting,
-    on: vi.fn(),
+} from "../src/main";
-    destroy: vi.fn(),
+
-  })),
+const hlsInstance = {
-  Events: { MANIFEST_PARSED: "hlsManifestParsed" },
+  loadSource: vi.fn(),
-}));
+  attachMedia: vi.fn(),
-
+  on: vi.fn(),
-// Mock WebSocket
+  destroy: vi.fn(),
-class MockWebSocket {
+};
-  url: string;
+
-  readyState = 0;
+const HlsMock = Object.assign(
-  onopen: (() => void) | null = null;
+  vi.fn().mockImplementation(() => hlsInstance),
-  onmessage: ((e: { data: string }) => void) | null = null;
+  {
-  onclose: (() => void) | null = null;
+    isSupported: vi.fn(() => true),
-  send = vi.fn();
+    Events: {
-  close = vi.fn();
+      MANIFEST_PARSED: "hlsManifestParsed",
-
+      ERROR: "hlsError",
-  constructor(url: string) {
+      LEVEL_UPDATED: "hlsLevelUpdated",
-    this.url = url;
+    },
-  }
+    ErrorTypes: {
-}
+      NETWORK_ERROR: "networkError",
-
+      MEDIA_ERROR: "mediaError",
-// Suppress console noise
+      MUX_ERROR: "muxError",
-beforeEach(() => {
+      OTHER_ERROR: "otherError",
-  vi.spyOn(console, "warn").mockImplementation(() => {});
+    },
-  vi.spyOn(console, "error").mockImplementation(() => {});
+  },
-  vi.spyOn(console, "log").mockImplementation(() => {});
+);
-});
+
-
+// Mock hls.js
-let origWebSocket: any;
+vi.mock("hls.js", () => ({
-let origFetch: any;
+  default: HlsMock,
-
+}));
-beforeEach(() => {
+
-  origWebSocket = (globalThis as any).WebSocket;
+// Mock WebSocket
-  origFetch = globalThis.fetch;
+const websocketInstances: MockWebSocket[] = [];
-  (globalThis as any).WebSocket = MockWebSocket;
+class MockWebSocket {
-
+  url: string;
-  // Mock fetch (schedule, etc.) — return empty schedule
+  readyState = 0;
-  globalThis.fetch = vi.fn().mockResolvedValue({
+  onopen: (() => void) | null = null;
-    ok: true,
+  onmessage: ((e: { data: string }) => void) | null = null;
-    json: () => Promise.resolve({ entries: [], total: 0, generatedAt: "" }),
+  onclose: (() => void) | null = null;
-  });
+  send = vi.fn();
-
+  close = vi.fn();
-  // Set up DOM from index.html
+
-  document.body.innerHTML = `
+  constructor(url: string) {
-    <main class="viewer-shell">
+    this.url = String(url);
-      <header class="viewer-header">
+    websocketInstances.push(this);
-        <button id="chat-toggle" type="button">Hide Chat</button>
+  }
-      </header>
+}
-      <section class="viewer-content">
+
-        <section class="player-stage">
+// Suppress console noise
-          <video id="player" class="player" controls autoplay muted playsinline></video>
+beforeEach(() => {
-          <div id="now-playing">
+  vi.spyOn(console, "warn").mockImplementation(() => {});
-            <span id="np-title">Loading...</span>
+  vi.spyOn(console, "error").mockImplementation(() => {});
-            <span id="np-next" class="np-next"></span>
+  vi.spyOn(console, "log").mockImplementation(() => {});
-          </div>
+});
-        </section>
+
-        <aside id="chat-panel" class="chat-sidebar">
+let origWebSocket: any;
-          <div class="chat-header">
+let origFetch: any;
-            <span id="room-name">Main Channel</span>
+
-            <button type="button" onclick="togglePrivateDM()">New DM</button>
+beforeEach(() => {
-          </div>
+  origWebSocket = (globalThis as any).WebSocket;
-          <section id="messages" class="chat-messages"></section>
+  origFetch = globalThis.fetch;
-          <section id="presence-panel" class="presence-panel">
+  (globalThis as any).WebSocket = MockWebSocket;
-            <div id="presence-list" class="presence-list"></div>
+  websocketInstances.length = 0;
-          </section>
+  resetViewerStateForTests();
-          <div class="chat-input-area">
+
-            <input id="message-input" type="text" placeholder="Type a message..." />
+  // Mock fetch (schedule, etc.) — return empty schedule
-            <button type="button" onclick="sendMessage()">Send</button>
+  globalThis.fetch = vi.fn().mockResolvedValue({
-          </div>
+    ok: true,
-        </aside>
+    json: () => Promise.resolve({ entries: [], total: 0, generatedAt: "" }),
-      </section>
+  });
-    </main>
+
-  `;
+  // Set up DOM from index.html
-
+  // Inject minimal CSS for jsdom layout tests (external style.css not loaded)
-  // Stub prompt for DM
+  document.head.innerHTML = `
-  (globalThis as any).prompt = vi.fn();
+    <style>
-});
+      .viewer-content { display: grid; grid-template-columns: minmax(0, 1fr) minmax(300px, 420px); }
-
+      .viewer-shell.chat-collapsed .chat-sidebar { display: none; }
-afterEach(() => {
+    </style>
-  (globalThis as any).WebSocket = origWebSocket;
+  `;
-  globalThis.fetch = origFetch;
+
-  vi.restoreAllMocks();
+  document.body.innerHTML = `
-});
+    <main class="viewer-shell">
-
+      <header class="viewer-header">
-// Must import after DOM setup
+        <button id="chat-toggle" type="button" aria-expanded="true">Hide Chat</button>
-import "../src/main";
+      </header>
-
+      <section class="viewer-content">
-describe("chat toggle", () => {
+        <section class="player-stage">
-  it("toggles chat panel visibility", () => {
+          <video id="player" class="player" controls autoplay muted playsinline></video>
-    const panel = document.getElementById("chat-panel")!;
+          <div id="now-playing" aria-live="polite">
-    const toggle = document.getElementById("chat-toggle")!;
+            <span id="np-title">Loading...</span>
-
+            <span id="np-next" class="np-next"></span>
-    expect(toggle.textContent).toBe("Hide Chat");
+          </div>
-
+        </section>
-    window.toggleChatPanel();
+        <aside id="chat-panel" class="chat-sidebar" role="complementary" aria-label="Chat panel">
-    expect(toggle.textContent).toBe("Show Chat");
+          <div class="chat-header">
-
+            <span id="room-name">Main Channel</span>
-    window.toggleChatPanel();
+            <button type="button" onclick="togglePrivateDM()">New DM</button>
-    expect(toggle.textContent).toBe("Hide Chat");
+          </div>
-  });
+          <div id="chat-flash" class="chat-flash" aria-live="polite" hidden></div>
-});
+          <section id="messages" class="chat-messages" aria-live="polite"></section>
-
+          <section id="presence-panel" class="presence-panel">
-describe("sendMessage", () => {
+            <div id="presence-list" class="presence-list"></div>
-  it("clears input after sending non-empty text", () => {
+          </section>
-    const input = document.getElementById("message-input") as HTMLInputElement;
+          <div class="chat-input-area">
-    input.value = "hello!";
+            <label for="message-input">Message input</label>
-
+            <input id="message-input" type="text" placeholder="Type a message..." />
-    // sendMessage requires ws to be non-null — ws set in initPlayerAndChat
+            <button type="button" onclick="sendMessage()">Send</button>
-    // The DOMContentLoaded triggers initPlayerAndChat which creates ws
+          </div>
-    // Wait for async init, then set ws manually
+        </aside>
-    // For now just verify input state logic
+      </section>
-    window.sendMessage();
+    </main>
-    // ws is null at this point, so message won't send but input won't clear either
+    <div id="reconnecting-overlay" role="alert" aria-live="assertive" hidden>
-    // Verify input not cleared (ws check fails before clear)
+      <span id="reconnecting-text">Reconnecting...</span>
-    expect(input.value).toBe("hello!");
+    </div>
-  });
+    <div id="chat-user-label" hidden></div>
-
+    <button id="auth-toggle-btn" type="button">Sign in</button>
-  it("does nothing with empty input", () => {
+    <button id="auth-logout-btn" type="button" hidden>Logout</button>
-    const input = document.getElementById("message-input") as HTMLInputElement;
+    <div id="auth-panel" class="auth-modal" hidden>
-    input.value = "   ";
+      <div id="auth-backdrop" class="auth-modal-backdrop"></div>
-    window.sendMessage();
+      <div class="auth-modal-content">
-    // No error thrown = pass
+        <button id="auth-close-btn" type="button">×</button>
-  });
+        <input id="auth-username" type="text" />
-});
+        <input id="auth-password" type="password" />
-
+        <span id="auth-status"></span>
-describe("switchRoom", () => {
+        <button id="auth-login-btn" type="button">Login</button>
-  it("updates room name on switch", () => {
+        <button id="auth-register-btn" type="button">Register</button>
-    window.switchRoom("lobby");
+      </div>
-    const roomName = document.getElementById("room-name")!;
+    </div>
-    expect(roomName.textContent).toBe("Lobby Room");
+    <div id="typing-indicator" hidden></div>
-  });
+  `;
-
+
-  it("shows Main Channel for main room", () => {
+  // Stub prompt for DM
-    window.switchRoom("main");
+  (globalThis as any).prompt = vi.fn();
-    const roomName = document.getElementById("room-name")!;
+
-    expect(roomName.textContent).toBe("Main Channel");
+  vi.useRealTimers();
-  });
+});
-});
+
-
+afterEach(() => {
-describe("togglePrivateDM", () => {
+  (globalThis as any).WebSocket = origWebSocket;
-  it("prompts for username and switches room", () => {
+  globalThis.fetch = origFetch;
-    // Stub prompt to return a value this time
+  vi.useRealTimers();
-    vi.spyOn(window, "prompt").mockReturnValue("bob");
+  vi.restoreAllMocks();
-
+});
-    const switchRoomSpy = vi.spyOn(window, "switchRoom");
+
-    window.togglePrivateDM();
+describe("player startup", () => {
-
+  it("starts native HLS playback on loadedmetadata", async () => {
-    expect(window.prompt).toHaveBeenCalled();
+    const video = document.getElementById("player") as HTMLVideoElement;
-    expect(switchRoomSpy).not.toHaveBeenCalled(); // username is "viewerNNN" which gets set randomly
+    vi.spyOn(video, "canPlayType").mockReturnValue("probably");
-
+    const playSpy = vi.spyOn(video, "play").mockResolvedValue(undefined as any);
-    switchRoomSpy.mockRestore();
+
-  });
+    await import("../src/main").then((mod) => mod.initPlayerAndChat());
-});
+
+    expect(video.src).toContain("/hls/playlist.m3u8?stream=");
+    video.dispatchEvent(new Event("loadedmetadata"));
+    expect(playSpy).toHaveBeenCalled();
+  });
+
+  it("starts hls.js playback when native HLS is unavailable", async () => {
+    const video = document.getElementById("player") as HTMLVideoElement;
+    Object.defineProperty(video, "canPlayType", {
+      value: vi.fn(() => ""),
+      configurable: true,
+    });
+    vi.spyOn(video, "play").mockResolvedValue(undefined as any);
+
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    expect(HlsMock.isSupported).toHaveBeenCalled();
+    expect(HlsMock).toHaveBeenCalled();
+  });
+});
+
+describe("chat toggle", () => {
+  it("toggles chat panel visibility", () => {
+    const toggle = document.getElementById("chat-toggle")!;
+
+    expect(toggle.textContent).toBe("Hide Chat");
+
+    window.toggleChatPanel();
+    expect(toggle.textContent).toBe("Show Chat");
+
+    window.toggleChatPanel();
+    expect(toggle.textContent).toBe("Hide Chat");
+  });
+});
+
+describe("sendMessage", () => {
+  it("clears input after sending non-empty text", () => {
+    const input = document.getElementById("message-input") as HTMLInputElement;
+    input.value = "hello!";
+
+    window.sendMessage();
+    expect(input.value).toBe("hello!");
+  });
+
+  it("does nothing with empty input", () => {
+    const input = document.getElementById("message-input") as HTMLInputElement;
+    input.value = "   ";
+    window.sendMessage();
+    // No error thrown = pass
+  });
+});
+
+describe("switchRoom", () => {
+  it("updates room name on switch", () => {
+    window.switchRoom("lobby");
+    const roomName = document.getElementById("room-name")!;
+    expect(roomName.textContent).toBe("Lobby Room");
+  });
+
+  it("shows Main Channel for main room", () => {
+    window.switchRoom("main");
+    const roomName = document.getElementById("room-name")!;
+    expect(roomName.textContent).toBe("Main Channel");
+  });
+});
+
+describe("togglePrivateDM", () => {
+  it("prompts for username and switches room", () => {
+    // Stub prompt to return a value this time
+    vi.spyOn(window, "prompt").mockReturnValue("bob");
+
+    const switchRoomSpy = vi.spyOn(window, "switchRoom");
+    window.togglePrivateDM();
+
+    expect(window.prompt).toHaveBeenCalled();
+    expect(switchRoomSpy).not.toHaveBeenCalled(); // username is "viewerNNN" which gets set randomly
+
+    switchRoomSpy.mockRestore();
+  });
+});
+
+describe("WebSocket reconnect", () => {
+  it("reconnects after onclose", async () => {
+    vi.useFakeTimers();
+
+    window.switchRoom("lobby");
+    expect(websocketInstances).toHaveLength(1);
+
+    websocketInstances[0].onclose?.();
+    await vi.advanceTimersByTimeAsync(3000);
+
+    expect(websocketInstances).toHaveLength(2);
+    expect(websocketInstances[1].url).toContain("room=lobby");
+  });
+
+  it("does not reconnect from a socket that was intentionally replaced", async () => {
+    vi.useFakeTimers();
+
+    window.switchRoom("lobby");
+    expect(websocketInstances).toHaveLength(1);
+    const replaced = websocketInstances[0];
+
+    // A room switch intentionally replaces the socket; the old socket must not
+    // schedule its own reconnect, otherwise history is re-pulled on a loop.
+    window.switchRoom("main");
+    expect(websocketInstances).toHaveLength(2);
+    expect(replaced.onclose).toBeNull();
+
+    replaced.onclose?.();
+    await vi.advanceTimersByTimeAsync(3000);
+
+    expect(websocketInstances).toHaveLength(2);
+  });
+});
+
+describe("URL resolution", () => {
+  it("falls back to same-origin manifest and websocket URLs", () => {
+    vi.stubEnv("VITE_PUBLIC_HLS_URL", "");
+    vi.stubEnv("VITE_PUBLIC_WS_URL", "");
+    vi.stubEnv("VITE_PUBLIC_HLS_CROSS_ORIGIN", "");
+
+    Object.defineProperty(window, "location", {
+      value: new URL("https://linearvoid.tv/viewer"),
+      writable: true,
+    });
+
+    expect(resolveManifestUrl()).toMatch(/^https:\/\/linearvoid\.tv\/hls\/playlist\.m3u8\?stream=/);
+    expect(resolveWebSocketBaseUrl()).toBe("wss://linearvoid.tv/ws");
+  });
+
+  it("preserves an allowed cross-origin manifest URL", () => {
+    vi.stubEnv("VITE_PUBLIC_HLS_URL", "https://media.linearvoid.tv/hls/playlist.m3u8");
+    vi.stubEnv("VITE_PUBLIC_HLS_CROSS_ORIGIN", "true");
+
+    expect(resolveManifestUrl()).toMatch(/^https:\/\/media\.linearvoid\.tv\/hls\/playlist\.m3u8\?stream=/);
+  });
+
+  it("falls back to same-origin manifest when cross-origin is not allowed", () => {
+    vi.stubEnv("VITE_PUBLIC_HLS_URL", "https://media.linearvoid.tv/hls/playlist.m3u8");
+    vi.stubEnv("VITE_PUBLIC_HLS_CROSS_ORIGIN", "false");
+
+    expect(resolveManifestUrl()).toMatch(/^https:\/\/linearvoid\.tv\/hls\/playlist\.m3u8\?stream=/);
+  });
+
+  it("uses configured websocket URL when present", () => {
+    vi.stubEnv("VITE_PUBLIC_WS_URL", "wss://chat.linearvoid.tv/ws");
+
+    expect(resolveWebSocketBaseUrl()).toBe("wss://chat.linearvoid.tv/ws");
+  });
+});
+
+describe("presence updates", () => {
+  it("adds user to presence list on join system message", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice joined the room", username: "system" }) });
+
+    const presenceList = document.getElementById("presence-list")!;
+    expect(presenceList.textContent).toContain("alice");
+  });
+
+  it("removes user from presence list on leave system message", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice joined the room", username: "system" }) });
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice left the room", username: "system" }) });
+
+    const presenceList = document.getElementById("presence-list")!;
+    expect(presenceList.textContent).not.toContain("alice");
+  });
+
+  it("renders multiple users sorted", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "zoe joined the room", username: "system" }) });
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice joined the room", username: "system" }) });
+
+    const presenceList = document.getElementById("presence-list")!;
+    const text = presenceList.textContent ?? "";
+    const aliceIdx = text.indexOf("alice");
+    const zoeIdx = text.indexOf("zoe");
+    expect(aliceIdx).toBeLessThan(zoeIdx);
+  });
+});
+
+describe("private DM flow", () => {
+  it("creates dm: room name from sorted usernames", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    vi.spyOn(window, "prompt").mockReturnValue("bob");
+    window.togglePrivateDM();
+
+    const roomName = document.getElementById("room-name")!;
+    // username is "viewer" (reset by tests), bob is target -> sorted = "bob-viewer"
+    // switchRoom capitalizes first char: "Dm:bob-viewer Room"
+    expect(roomName.textContent).toContain("bob-viewer");
+  });
+});
+
+describe("message rendering", () => {
+  it("renders system messages", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "Server restarting", username: "system" }) });
+
+    const messages = document.getElementById("messages")!;
+    expect(messages.innerHTML).toContain("Server restarting");
+    expect(messages.querySelector(".message-system")).toBeTruthy();
+  });
+
+  it("renders self messages as message-self", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({
+      data: JSON.stringify({ type: "public", text: "hello world", username: "viewer", timestamp: Date.now() }),
+    });
+
+    const messages = document.getElementById("messages")!;
+    expect(messages.innerHTML).toContain("hello world");
+    expect(messages.querySelector(".message-self")).toBeTruthy();
+  });
+
+  it("renders other-user messages as message-other", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({
+      data: JSON.stringify({ type: "public", text: "hey", username: "alice", timestamp: Date.now() }),
+    });
+
+    const messages = document.getElementById("messages")!;
+    expect(messages.innerHTML).toContain("hey");
+    expect(messages.innerHTML).toContain("alice");
+    expect(messages.querySelector(".message-other")).toBeTruthy();
+  });
+});
+
+describe("reconnecting overlay", () => {
+  it("shows and hides the overlay with a custom message", () => {
+    showReconnecting("Custom message");
+    const overlay = document.getElementById("reconnecting-overlay")!;
+    expect(overlay.classList.contains("hidden")).toBe(false);
+    expect(document.getElementById("reconnecting-text")!.textContent).toBe("Custom message");
+
+    hideReconnecting();
+    expect(overlay.classList.contains("hidden")).toBe(true);
+  });
+});
+
+describe("typing indicator", () => {
+  it("shows typing on a typing event and clears on the next message", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "typing", username: "alice" }) });
+
+    const indicator = document.getElementById("typing-indicator")!;
+    expect(indicator.textContent).toBe("alice is typing...");
+    expect(indicator.hidden).toBe(false);
+
+    ws.onmessage?.({ data: JSON.stringify({ type: "public", text: "hi", username: "alice", timestamp: Date.now() }) });
+    expect(indicator.hidden).toBe(true);
+    expect(indicator.textContent).toBe("");
+  });
+
+  it("ignores typing events from the current user", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "typing", username: "viewer" }) });
+
+    const indicator = document.getElementById("typing-indicator")!;
+    expect(indicator.textContent).toBe("");
+    expect(indicator.hidden).toBe(true);
+  });
+});
+
+describe("sendMessage over websocket", () => {
+  it("sends a JSON message and clears the input", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const input = document.getElementById("message-input") as HTMLInputElement;
+    input.value = "hello world";
+    window.sendMessage();
+
+    const ws = websocketInstances[0];
+    expect(ws.send).toHaveBeenCalledTimes(1);
+    expect(ws.send).toHaveBeenCalledWith(expect.stringContaining("hello world"));
+    expect(input.value).toBe("");
+  });
+});
+
+describe("auth wiring", () => {
+  it("logs in and updates the auth UI", async () => {
+    await import("../src/main");
+
+    globalThis.fetch = vi.fn(async (url: any) => {
+      const u = String(url);
+      if (u.includes("/api/auth/login")) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ username: "alice", authenticated: true }),
+          text: async () => "",
+        };
+      }
+      return { ok: true, status: 200, json: async () => ({ authenticated: false }), text: async () => "" };
+    }) as any;
+
+    document.dispatchEvent(new Event("DOMContentLoaded"));
+
+    const usernameInput = document.getElementById("auth-username") as HTMLInputElement;
+    const passwordInput = document.getElementById("auth-password") as HTMLInputElement;
+    usernameInput.value = "alice";
+    passwordInput.value = "secret";
+
+    document.getElementById("auth-login-btn")!.click();
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(document.getElementById("auth-status")!.textContent).toContain("Signed in as alice");
+    expect(document.getElementById("chat-user-label")!.textContent).toBe("alice");
+  });
+});
+
+describe("player error recovery", () => {
+  it("shows reconnecting overlay on fatal network error", async () => {
+    const main = await import("../src/main");
+    await main.initPlayerAndChat(async () => ({ default: HlsMock }) as any);
+
+    // Find the error handler registered by initPlayerAndChat
+    const errorHandler = (hlsInstance.on as any).mock.calls.find((c: any) => c[0] === "hlsError") as
+      | [string, Function]
+      | undefined;
+
+    if (errorHandler) {
+      const handler = errorHandler[1];
+      handler("hlsError", {
+        type: "networkError",
+        details: "manifestLoadError",
+        fatal: true,
+      });
+
+      const overlay = document.getElementById("reconnecting-overlay")!;
+      expect(overlay.classList.contains("hidden")).toBe(false);
+      expect(document.getElementById("reconnecting-text")?.textContent).toBe("Reconnecting...");
+    }
+  });
+});
+
+describe("accessibility", () => {
+  it("player video has controls and aria attributes", () => {
+    const video = document.getElementById("player") as HTMLVideoElement;
+    expect(video.controls).toBe(true);
+    expect(video.hasAttribute("autoplay")).toBe(true);
+    expect(video.hasAttribute("playsinline")).toBe(true);
+  });
+
+  it("chat panel has aria-labels for live region", () => {
+    const messages = document.getElementById("messages");
+    expect(messages?.getAttribute("aria-live")).toBe("polite");
+
+    const chatPanel = document.getElementById("chat-panel");
+    expect(chatPanel?.getAttribute("aria-label")).toBe("Chat panel");
+  });
+
+  it("chat toggle exposes aria-expanded state", () => {
+    const toggle = document.getElementById("chat-toggle")!;
+    expect(toggle.getAttribute("aria-expanded")).toBe("true");
+
+    window.toggleChatPanel();
+    expect(toggle.getAttribute("aria-expanded")).toBe("false");
+  });
+
+  it("message input has associated label", () => {
+    const input = document.getElementById("message-input") as HTMLInputElement;
+    expect(input.getAttribute("type")).toBe("text");
+    expect(input.placeholder).toBe("Type a message...");
+    const label = document.querySelector("label[for='message-input']");
+    expect(label).toBeTruthy();
+    expect(label?.textContent).toBe("Message input");
+  });
+
+  it("reconnecting overlay is an aria-live assertive region", () => {
+    const overlay = document.getElementById("reconnecting-overlay");
+    expect(overlay?.getAttribute("role")).toBe("alert");
+    expect(overlay?.getAttribute("aria-live")).toBe("assertive");
+  });
+});
+
+describe("responsive layout", () => {
+  it("chat-collapsed class hides sidebar at narrow viewport", () => {
+    const shell = document.querySelector(".viewer-shell")!;
+    expect(shell.classList.contains("chat-collapsed")).toBe(false);
+
+    window.toggleChatPanel();
+    expect(shell.classList.contains("chat-collapsed")).toBe(true);
+
+    window.toggleChatPanel();
+    expect(shell.classList.contains("chat-collapsed")).toBe(false);
+  });
+
+  it("viewer-shell uses CSS grid for content layout", () => {
+    const content = document.querySelector(".viewer-content");
+    expect(content).toBeTruthy();
+    const style = window.getComputedStyle(content!);
+    expect(style.display).toBe("grid");
+  });
+
+  it("now-playing overlay is accessible at small sizes", () => {
+    const np = document.getElementById("now-playing");
+    expect(np?.getAttribute("aria-live")).toBe("polite");
+  });
+});
+
+describe("presence flash", () => {
+  it("flashes join/leave messages instead of appending chat rows", async () => {
+    await import("../src/main").then((mod) => mod.initPlayerAndChat(async () => ({ default: HlsMock }) as any));
+
+    const ws = websocketInstances[0];
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice joined the room", username: "system" }) });
+
+    const flash = document.getElementById("chat-flash")!;
+    expect(flash.textContent).toBe("alice joined");
+    expect(flash.hidden).toBe(false);
+
+    // Join/leave must not be rendered as chat rows.
+    const messages = document.getElementById("messages")!;
+    expect(messages.textContent).not.toContain("joined");
+
+    ws.onmessage?.({ data: JSON.stringify({ type: "system", text: "alice left the room", username: "system" }) });
+    expect(flash.textContent).toBe("alice left");
+  });
+});

frontend/src/main.ts

@@ -1,223 +1,519 @@
-import "./style.css";
+import "./style.css";
-
+
-type HlsClass = (typeof import("hls.js"))["default"];
+type HlsClass = (typeof import("hls.js"))["default"];
-
+
-declare global {
+declare global {
-  interface Window {
+  interface Window {
-    switchRoom: (room: string) => void;
+    switchRoom: (room: string) => void;
-    sendMessage: () => void;
+    sendMessage: () => void;
-    togglePrivateDM: () => void;
+    togglePrivateDM: () => void;
-    toggleChatPanel: () => void;
+    toggleChatPanel: () => void;
-  }
+  }
-}
+}
-
+
-let hls: InstanceType<HlsClass> | null = null;
+let hls: InstanceType<HlsClass> | null = null;
-let ws: WebSocket | null = null;
+let ws: WebSocket | null = null;
-let currentRoom = "main";
+let currentRoom = "main";
-let username = "viewer" + Math.floor(Math.random() * 1000);
+let username = "viewer" + Math.floor(Math.random() * 1000);
-let chatVisible = true;
+let authenticated = false;
-const onlineUsers = new Set<string>();
+let chatVisible = true;
-
+let typingUser = "";
-function resolveWebSocketBaseUrl() {
+let lastTypingSent = 0;
-  const configuredUrl = import.meta.env.VITE_PUBLIC_WS_URL?.trim();
+let typingTimeout: number | undefined;
-
+let flashTimeout: number | undefined;
-  if (configuredUrl) {
+let flashFadeTimeout: number | undefined;
-    return configuredUrl;
+const onlineUsers = new Set<string>();
-  }
+
-
+// Player error recovery state (STREAMING.md contract)
-  const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+let playerErrorCount = 0;
-  return `${protocol}//${window.location.host}/ws`;
+const PLAYER_MAX_RETRIES = 5;
-}
+const PLAYER_BASE_DELAY_MS = 2000;
-
+
-function resolveManifestUrl() {
+export function resetViewerStateForTests() {
-  const configuredUrl = import.meta.env.VITE_PUBLIC_HLS_URL?.trim();
+  hls = null;
-  const cacheBust = `stream=${Date.now()}`;
+  ws = null;
-  const sameOriginManifestUrl = new URL("/hls/playlist.m3u8", window.location.origin);
+  currentRoom = "main";
-  sameOriginManifestUrl.searchParams.set("stream", cacheBust);
+  username = "viewer";
-
+  authenticated = false;
-  const allowCrossOriginManifest = import.meta.env.VITE_PUBLIC_HLS_CROSS_ORIGIN?.trim().toLowerCase() === "true";
+  chatVisible = true;
-
+  typingUser = "";
-  if (configuredUrl) {
+  lastTypingSent = 0;
-    const manifestUrl = new URL(configuredUrl);
+  onlineUsers.clear();
-    manifestUrl.searchParams.set("stream", cacheBust);
+  playerErrorCount = 0;
-
+}
-    if (!allowCrossOriginManifest && manifestUrl.origin !== window.location.origin) {
+
-      return sameOriginManifestUrl.toString();
+export function resolveWebSocketBaseUrl() {
-    }
+  const configuredUrl = import.meta.env.VITE_PUBLIC_WS_URL?.trim();
-
+
-    return manifestUrl.toString();
+  if (configuredUrl) {
-  }
+    return configuredUrl;
-
+  }
-  return sameOriginManifestUrl.toString();
+
-}
+  const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-
+  return `${protocol}//${window.location.host}/ws`;
-function connectWebSocket(room: string) {
+}
-  if (ws) ws.close();
+
-
+export function resolveManifestUrl() {
-  const socketUrl = new URL(resolveWebSocketBaseUrl());
+  const configuredUrl = import.meta.env.VITE_PUBLIC_HLS_URL?.trim();
-  socketUrl.searchParams.set("username", username);
+  const cacheBust = `stream=${Date.now()}`;
-  socketUrl.searchParams.set("room", room);
+  const sameOriginManifestUrl = new URL("/hls/playlist.m3u8", window.location.origin);
-  ws = new WebSocket(socketUrl);
+  sameOriginManifestUrl.searchParams.set("stream", cacheBust);
-
+
-  ws.onopen = () => {
+  const allowCrossOriginManifest = import.meta.env.VITE_PUBLIC_HLS_CROSS_ORIGIN?.trim().toLowerCase() === "true";
-    console.log(`Connected to chat room: ${room}`);
+
-    addMessage("system", "Connected to " + room);
+  if (configuredUrl) {
-  };
+    const manifestUrl = new URL(configuredUrl);
-
+    manifestUrl.searchParams.set("stream", cacheBust);
-  ws.onmessage = (event) => {
+
-    const msg = JSON.parse(event.data);
+    if (!allowCrossOriginManifest && manifestUrl.origin !== window.location.origin) {
-    addMessage(msg.type || "public", msg.text, msg.username, msg.timestamp);
+      return sameOriginManifestUrl.toString();
-
+    }
-    // Track presence from system join/leave messages
+
-    if (msg.type === "system" && msg.username === "system") {
+    return manifestUrl.toString();
-      const joined = msg.text?.match(/^(\S+) joined /);
+  }
-      const left = msg.text?.match(/^(\S+) left /);
+
-      if (joined) {
+  return sameOriginManifestUrl.toString();
-        onlineUsers.add(joined[1]);
+}
-        renderPresence();
+
-      } else if (left) {
+function connectWebSocket(room: string) {
-        onlineUsers.delete(left[1]);
+  // Clear previous messages so reconnects render a fresh history instead of
-        renderPresence();
+  // appending duplicates on top of the old log.
-      }
+  clearMessages();
-    }
+
-  };
+  // Detach the old socket's close handler before closing it. Otherwise an
-
+  // intentional reconnect (login/logout/room switch/session refresh) would
-  ws.onclose = () => {
+  // have the replaced socket schedule yet another reconnect, and each new
-    console.log("Chat disconnected. Reconnecting in 3s...");
+  // connection re-pulls the room's history — filling the panel with old
-    setTimeout(() => connectWebSocket(room), 3000);
+  // messages on a loop.
-  };
+  if (ws) {
-}
+    ws.onclose = null;
-
+    ws.close();
-function addMessage(type: string, text: string, sender = "", timestamp = new Date()) {
+  }
-  const messages = document.getElementById("messages")!;
+
-  const div = document.createElement("div");
+  const socketUrl = new URL(resolveWebSocketBaseUrl());
-  div.className = "message-row";
+  socketUrl.searchParams.set("username", username);
-
+  socketUrl.searchParams.set("room", room);
-  if (type === "system") {
+  const socket = new WebSocket(socketUrl);
-    div.classList.add("message-system-row");
+  ws = socket;
-    div.innerHTML = `<div class="message-system">${text}</div>`;
+
-  } else {
+  socket.onopen = () => {
-    div.classList.add(sender === username ? "message-self-row" : "message-other-row");
+    console.log(`Connected to chat room: ${room}`);
-    div.innerHTML = `
+    addMessage("system", "Connected to " + room);
-      <article class="message-bubble ${sender === username ? "message-self" : "message-other"}">
+  };
-        ${sender && sender !== username ? `<div class="message-sender">${sender}</div>` : ""}
+
-        <div class="message-text">${text}</div>
+  socket.onmessage = (event) => {
-        <time class="message-time">${new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time>
+    const msg = JSON.parse(event.data);
-      </article>
+    if (msg.type === "typing") {
-    `;
+      showTyping(msg.username);
-  }
+      return;
-
+    }
-  messages.appendChild(div);
+    hideTyping(msg.username);
-  messages.scrollTop = messages.scrollHeight;
+
-}
+    // Presence join/leave announcements become transient flashes, not chat rows.
-
+    if (msg.type === "system" && msg.username === "system") {
-function renderPresence() {
+      const joined = msg.text?.match(/^(\S+) joined /);
-  const list = document.getElementById("presence-list");
+      const left = msg.text?.match(/^(\S+) left /);
-  if (!list) return;
+      if (joined) {
-  const sorted = [...onlineUsers].sort();
+        onlineUsers.add(joined[1]);
-  list.innerHTML = sorted
+        renderPresence();
-    .map((u) => `<span class="presence-dot" title="${u}"><span class="presence-indicator"></span>${u}</span>`)
+        showFlash(`${joined[1]} joined`);
-    .join("");
+        return;
-}
+      } else if (left) {
-
+        onlineUsers.delete(left[1]);
-async function refreshSchedule() {
+        renderPresence();
-  try {
+        showFlash(`${left[1]} left`);
-    const res = await fetch("/api/schedule");
+        return;
-    if (!res.ok) return;
+      }
-    const data = await res.json();
+    }
-    const entries = data.entries as Array<{ title: string; status: string }>;
+
-    if (entries.length > 0) {
+    addMessage(msg.type || "public", msg.text, msg.username, msg.timestamp);
-      const np = document.getElementById("np-title");
+  };
-      const nn = document.getElementById("np-next");
+
-      if (np) np.textContent = `Now: ${entries[0].title}`;
+  socket.onclose = () => {
-      if (nn && entries.length > 1) {
+    // Ignore close events from sockets that were intentionally replaced.
-        nn.textContent = `Up next: ${entries[1].title}`;
+    if (ws !== socket) return;
-      }
+    ws = null;
-    }
+    console.log("Chat disconnected. Reconnecting in 3s...");
-  } catch {
+    setTimeout(() => connectWebSocket(room), 3000);
-    // Schedule unavailable — non-critical
+  };
-  }
+}
-}
+
-
+function clearMessages() {
-async function initPlayerAndChat() {
+  const messages = document.getElementById("messages");
-  const video = document.getElementById("player") as HTMLVideoElement;
+  if (messages) messages.innerHTML = "";
-  const manifestUrl = resolveManifestUrl();
+}
-
+
-  if (video.canPlayType("application/vnd.apple.mpegurl")) {
+function addMessage(type: string, text: string, sender = "", timestamp = new Date()) {
-    video.src = manifestUrl;
+  const messages = document.getElementById("messages");
-    video.addEventListener("loadedmetadata", () => video.play());
+  if (!messages) return;
-  } else {
+  const div = document.createElement("div");
-    try {
+  div.className = "message-row";
-      const { default: Hls } = await import("hls.js");
+
-      if (Hls.isSupported()) {
+  if (type === "system") {
-        hls = new Hls();
+    div.classList.add("message-system-row");
-        hls.loadSource(manifestUrl);
+    div.innerHTML = `<div class="message-system">${text}</div>`;
-        hls.attachMedia(video);
+  } else {
-        hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
+    div.classList.add(sender === username ? "message-self-row" : "message-other-row");
-      }
+    div.innerHTML = `
-    } catch (error) {
+      <article class="message-bubble ${sender === username ? "message-self" : "message-other"}">
-      console.error("Failed to load HLS player", error);
+        ${sender && sender !== username ? `<div class="message-sender">${sender}</div>` : ""}
-      addMessage("system", "Unable to initialize video player.");
+        <div class="message-text">${text}</div>
-    }
+        <time class="message-time">${new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time>
-  }
+      </article>
-
+    `;
-  connectWebSocket("main");
+  }
-
+
-  // Start schedule polling
+  messages.appendChild(div);
-  refreshSchedule();
+  messages.scrollTop = messages.scrollHeight;
-  setInterval(refreshSchedule, 30000);
+}
-
+
-  console.log("Linear Void Frontend initialized - HLS Player + Chat Sidebar ready");
+function showFlash(text: string) {
-}
+  const el = document.getElementById("chat-flash");
-
+  if (!el) return;
-function toggleChatPanel() {
+  el.textContent = text;
-  const shell = document.querySelector(".viewer-shell");
+  el.hidden = false;
-  const toggle = document.getElementById("chat-toggle");
+  el.classList.remove("fade-out");
-  if (!shell || !toggle) return;
+  window.clearTimeout(flashTimeout);
-
+  window.clearTimeout(flashFadeTimeout);
-  chatVisible = !chatVisible;
+  flashTimeout = window.setTimeout(() => {
-  shell.classList.toggle("chat-collapsed", !chatVisible);
+    el.classList.add("fade-out");
-  toggle.textContent = chatVisible ? "Hide Chat" : "Show Chat";
+    flashFadeTimeout = window.setTimeout(() => {
-  toggle.setAttribute("aria-expanded", String(chatVisible));
+      el.hidden = true;
-}
+      el.classList.remove("fade-out");
-
+    }, 500);
-function sendMessage() {
+  }, 3000);
-  const input = document.getElementById("message-input") as HTMLInputElement;
+}
-  const text = input.value.trim();
+
-  if (!text || !ws) return;
+function renderPresence() {
-
+  const list = document.getElementById("presence-list");
-  const msg = {
+  if (!list) return;
-    room: currentRoom,
+  const sorted = [...onlineUsers].sort();
-    username: username,
+  list.innerHTML = sorted
-    text: text,
+    .map((u) => `<span class="presence-dot" title="${u}"><span class="presence-indicator"></span>${u}</span>`)
-    type: currentRoom.startsWith("dm:") ? "private" : "public",
+    .join("");
-  };
+}
-
+
-  ws.send(JSON.stringify(msg));
+async function refreshSchedule() {
-  input.value = "";
+  try {
-}
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
-
+    const res = await fetch(`${apiUrl}/api/schedule`);
-function switchRoom(room: string) {
+    if (!res.ok) return;
-  currentRoom = room;
+    const data = await res.json();
-  document.getElementById("room-name")!.textContent =
+    const entries = data.entries as Array<{ title: string; status: string }>;
-    room === "main" ? "Main Channel" : room.charAt(0).toUpperCase() + room.slice(1) + " Room";
+    if (entries.length > 0) {
-  addMessage("system", `Switched to ${room} room`);
+      const np = document.getElementById("np-title");
-  connectWebSocket(room);
+      const nn = document.getElementById("np-next");
-}
+      if (np) np.textContent = `Now: ${entries[0].title}`;
-
+      if (nn && entries.length > 1) {
-function togglePrivateDM() {
+        nn.textContent = `Up next: ${entries[1].title}`;
-  const target = prompt("Enter username to start private chat with:");
+      }
-  if (target && target !== username) {
+    }
-    const dmRoom = `dm:${[username, target].sort().join("-")}`;
+  } catch {
-    switchRoom(dmRoom);
+    // Schedule unavailable — non-critical
-  }
+  }
-}
+}
-
+
-window.switchRoom = switchRoom;
+export async function initPlayerAndChat(loadHlsModule: () => Promise<{ default: HlsClass }> = () => import("hls.js")) {
-window.sendMessage = sendMessage;
+  const video = document.getElementById("player") as HTMLVideoElement;
-window.togglePrivateDM = togglePrivateDM;
+  const manifestUrl = resolveManifestUrl();
-window.toggleChatPanel = toggleChatPanel;
+
-
+  if (video.canPlayType("application/vnd.apple.mpegurl")) {
-document.addEventListener("DOMContentLoaded", () => {
+    video.src = manifestUrl;
-  void initPlayerAndChat();
+    video.addEventListener("loadedmetadata", () => video.play());
-});
+  } else {
+    try {
+      const { default: Hls } = await loadHlsModule();
+      if (Hls.isSupported()) {
+        hls = new Hls({
+          liveDurationInfinity: true,
+          liveSyncDurationCount: 3,
+        });
+        hls.loadSource(manifestUrl);
+        hls.attachMedia(video);
+        hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
+
+        // Player error recovery (STREAMING.md contract)
+        hls.on(Hls.Events.ERROR, (_event, data) => {
+          if (!data.fatal) return;
+
+          playerErrorCount++;
+
+          switch (data.type) {
+            case Hls.ErrorTypes.NETWORK_ERROR:
+              if (playerErrorCount <= PLAYER_MAX_RETRIES) {
+                const delay = PLAYER_BASE_DELAY_MS * Math.pow(2, playerErrorCount - 1);
+                console.warn(
+                  `HLS network error (attempt ${playerErrorCount}/${PLAYER_MAX_RETRIES}), retrying in ${delay}ms...`,
+                );
+                showReconnecting("Reconnecting...");
+                setTimeout(() => {
+                  hls?.startLoad();
+                }, delay);
+              } else {
+                console.error("HLS network error: max retries exhausted");
+                showReconnecting("Stream temporarily unavailable");
+              }
+              break;
+
+            case Hls.ErrorTypes.MEDIA_ERROR:
+              if (playerErrorCount <= 1) {
+                console.warn("HLS media error, attempting recovery...");
+                showReconnecting("Recovering...");
+                hls!.recoverMediaError();
+              } else {
+                console.error("HLS media error: recovery failed");
+                hls!.destroy();
+                showReconnecting("Stream temporarily unavailable");
+              }
+              break;
+
+            default:
+              console.error("HLS fatal error:", data.type, data.details);
+              hls!.destroy();
+              showReconnecting("Stream temporarily unavailable");
+              break;
+          }
+        });
+
+        // Reset error count on successful manifest parse
+        hls.on(Hls.Events.MANIFEST_PARSED, () => {
+          playerErrorCount = 0;
+          hideReconnecting();
+        });
+      }
+    } catch (error) {
+      console.error("Failed to load HLS player", error);
+      addMessage("system", "Unable to initialize video player.");
+    }
+  }
+
+  // Resolve the user session first so we connect once with the correct username
+  // (avoids pushing chat history twice on initial load).
+  await sessionReady;
+  connectWebSocket("main");
+
+  // Start schedule polling
+  refreshSchedule();
+  setInterval(refreshSchedule, 30000);
+
+  console.log("Linear Void Frontend initialized - HLS Player + Chat Sidebar ready");
+}
+
+export function showReconnecting(message = "Reconnecting...") {
+  const overlay = document.getElementById("reconnecting-overlay");
+  const text = document.getElementById("reconnecting-text");
+  if (overlay) {
+    overlay.classList.remove("hidden");
+  }
+  if (text) {
+    text.textContent = message;
+  }
+}
+
+export function hideReconnecting() {
+  const overlay = document.getElementById("reconnecting-overlay");
+  if (overlay) {
+    overlay.classList.add("hidden");
+  }
+}
+
+function toggleChatPanel() {
+  const shell = document.querySelector(".viewer-shell");
+  const toggle = document.getElementById("chat-toggle");
+  if (!shell || !toggle) return;
+
+  chatVisible = !chatVisible;
+  shell.classList.toggle("chat-collapsed", !chatVisible);
+  toggle.textContent = chatVisible ? "Hide Chat" : "Show Chat";
+  toggle.setAttribute("aria-expanded", String(chatVisible));
+}
+
+function sendMessage() {
+  const input = document.getElementById("message-input") as HTMLInputElement;
+  const text = input.value.trim();
+  if (!text || !ws) return;
+
+  const msg = {
+    room: currentRoom,
+    username: username,
+    text: text,
+    type: currentRoom.startsWith("dm:") ? "private" : "public",
+  };
+
+  ws.send(JSON.stringify(msg));
+  input.value = "";
+}
+
+function switchRoom(room: string) {
+  currentRoom = room;
+  document.getElementById("room-name")!.textContent =
+    room === "main" ? "Main Channel" : room.charAt(0).toUpperCase() + room.slice(1) + " Room";
+  connectWebSocket(room);
+}
+
+function togglePrivateDM() {
+  const target = prompt("Enter username to start private chat with:");
+  if (target && target !== username) {
+    const dmRoom = `dm:${[username, target].sort().join("-")}`;
+    switchRoom(dmRoom);
+  }
+}
+
+window.switchRoom = switchRoom;
+window.sendMessage = sendMessage;
+window.togglePrivateDM = togglePrivateDM;
+window.toggleChatPanel = toggleChatPanel;
+
+function openAuthModal() {
+  const panel = document.getElementById("auth-panel");
+  if (panel) panel.hidden = false;
+}
+
+function closeAuthModal() {
+  const panel = document.getElementById("auth-panel");
+  if (panel) panel.hidden = true;
+}
+
+function updateAuthUI() {
+  const label = document.getElementById("chat-user-label");
+  const toggle = document.getElementById("auth-toggle-btn");
+  const logoutBtn = document.getElementById("auth-logout-btn");
+  const panel = document.getElementById("auth-panel");
+  if (label) {
+    label.textContent = authenticated ? username : "";
+    label.hidden = !authenticated;
+  }
+  if (toggle) toggle.hidden = authenticated;
+  if (logoutBtn) logoutBtn.hidden = !authenticated;
+  if (panel) panel.hidden = true;
+}
+
+let sessionReady: Promise<void> = Promise.resolve();
+
+function refreshUserSession(): void {
+  sessionReady = (async () => {
+    try {
+      const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+      const res = await fetch(`${apiUrl}/api/auth/session`, { credentials: "include" });
+      if (!res.ok) return;
+      const data = await res.json();
+      if (data.authenticated && data.username) {
+        authenticated = true;
+        username = data.username;
+      } else {
+        authenticated = false;
+      }
+      updateAuthUI();
+    } catch {
+      /* non-critical */
+    }
+  })();
+}
+
+async function submitAuth(path: string) {
+  const u = (document.getElementById("auth-username") as HTMLInputElement).value.trim();
+  const p = (document.getElementById("auth-password") as HTMLInputElement).value;
+  const status = document.getElementById("auth-status");
+  if (!u || !p) {
+    if (status) {
+      status.textContent = "Username and password required.";
+      status.className = "status-line status-error";
+    }
+    return;
+  }
+  try {
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+    const res = await fetch(`${apiUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ username: u, password: p }),
+    });
+    if (!res.ok) {
+      const text = (await res.text()).trim();
+      throw new Error(text || `HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    username = data.username || u;
+    authenticated = true;
+    updateAuthUI();
+    if (status) {
+      status.textContent = `Signed in as ${username}.`;
+      status.className = "status-line";
+    }
+    connectWebSocket(currentRoom);
+  } catch (err) {
+    if (status) {
+      status.textContent = `Failed: ${err instanceof Error ? err.message : String(err)}`;
+      status.className = "status-line status-error";
+    }
+  }
+}
+
+function login() {
+  void submitAuth("/api/auth/login");
+}
+
+function register() {
+  void submitAuth("/api/auth/register");
+}
+
+async function logout() {
+  try {
+    const apiUrl = import.meta.env.VITE_PUBLIC_APP_URL?.trim() || window.location.origin;
+    await fetch(`${apiUrl}/api/auth/logout`, { method: "POST", credentials: "include" });
+  } catch {
+    /* ignore */
+  }
+  authenticated = false;
+  username = "viewer" + Math.floor(Math.random() * 1000);
+  updateAuthUI();
+  connectWebSocket(currentRoom);
+}
+
+function showTyping(name: string) {
+  if (name === username) return;
+  const el = document.getElementById("typing-indicator");
+  if (!el) return;
+  typingUser = name;
+  el.textContent = `${name} is typing...`;
+  el.hidden = false;
+  window.clearTimeout(typingTimeout);
+  typingTimeout = window.setTimeout(() => {
+    typingUser = "";
+    el.hidden = true;
+    el.textContent = "";
+  }, 3000);
+}
+
+function hideTyping(name: string) {
+  if (name !== typingUser) return;
+  const el = document.getElementById("typing-indicator");
+  typingUser = "";
+  window.clearTimeout(typingTimeout);
+  if (el) {
+    el.hidden = true;
+    el.textContent = "";
+  }
+}
+
+function sendTyping() {
+  if (!ws || ws.readyState !== WebSocket.OPEN) return;
+  const now = Date.now();
+  if (now - lastTypingSent < 2000) return;
+  lastTypingSent = now;
+  ws.send(JSON.stringify({ room: currentRoom, username, text: "", type: "typing" }));
+}
+
+document.addEventListener("DOMContentLoaded", () => {
+  void initPlayerAndChat();
+  refreshUserSession();
+  document.getElementById("auth-toggle-btn")?.addEventListener("click", () => {
+    if (!authenticated) openAuthModal();
+  });
+  document.getElementById("auth-close-btn")?.addEventListener("click", closeAuthModal);
+  document.getElementById("auth-backdrop")?.addEventListener("click", closeAuthModal);
+  document.getElementById("auth-login-btn")?.addEventListener("click", login);
+  document.getElementById("auth-register-btn")?.addEventListener("click", register);
+  document.getElementById("auth-logout-btn")?.addEventListener("click", logout);
+  document.getElementById("message-input")?.addEventListener("input", sendTyping);
+});

frontend/vitest.config.ts

@@ -1,8 +1,20 @@
-import { defineConfig } from "vitest/config";
+import { defineConfig } from "vitest/config";
-
+
-export default defineConfig({
+export default defineConfig({
-  test: {
+  test: {
-    environment: "jsdom",
+    environment: "jsdom",
-    include: ["src/**/*.test.ts"],
+    include: ["src/**/*.test.ts"],
-  },
+    coverage: {
-});
+      provider: "v8",
+      reporter: ["text", "text-summary"],
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts"],
+      thresholds: {
+        statements: 20,
+        branches: 15,
+        functions: 15,
+        lines: 20,
+      },
+    },
+  },
+});

frontend/wrangler.toml

@@ -0,0 +1,6 @@
+name = "linearvoid-frontend"
+compatibility_date = "2025-08-01"
+
+[assets]
+directory = "./dist"
+not_found_handling = "single-page-application"

infrastructure/cloudflare/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.wrangler/
+dist/
+coverage/
+*.log

infrastructure/cloudflare/README.md

@@ -0,0 +1,65 @@
+# linearvoid-media Worker
+
+Cloudflare Worker that owns **`media.linearvoid.tv`** and serves the HLS objects
+stored in the `linearvoid-media` R2 bucket, applying the edge cache policy in code:
+
+| Object                                      | Cache-Control                                    |
+| ------------------------------------------- | ------------------------------------------------ |
+| `.m4s` / `.ts` / `.mp4` / `.m4a` (segments) | `public, max-age=31536000, immutable`            |
+| `.m3u8` (live manifest)                     | `public, max-age=1, s-maxage=2, must-revalidate` |
+
+It also adds HLS CORS (`Access-Control-Allow-Origin: *`), OPTIONS preflight, a
+`/health` probe, and Range-request support. This worker replaces direct R2
+custom-domain serving on the media host so cache headers/CORS are controlled in
+code (cache rules on the same host remain the origin baseline).
+
+## Layout
+
+```text
+infrastructure/cloudflare/
+├── wrangler.toml        # name/binding + production custom-domain route
+├── package.json
+├── src/worker.js        # worker module (exports default.fetch + pure helpers)
+└── test/                # Vitest unit tests + Miniflare (workerd) R2 tests
+```
+
+## Local dev / test
+
+```bash
+cd infrastructure/cloudflare
+npm install
+npm test                 # unit + Miniflare R2 integration tests
+npx wrangler dev         # run locally against your account's R2 bucket
+```
+
+## Deploy
+
+**Preview / test target** (default environment → `*.workers.dev`):
+
+```bash
+cd infrastructure/cloudflare
+npx wrangler deploy
+```
+
+**Production** (attaches `media.linearvoid.tv` as a custom domain on this worker):
+
+```bash
+cd infrastructure/cloudflare
+npx wrangler deploy --env production
+```
+
+Both need `CLOUDFLARE_API_TOKEN` (Workers Scripts/Routes edit) and
+`CLOUDFLARE_ACCOUNT_ID` in the environment. The media host must first be removed
+from the R2 bucket's direct custom-domain binding, otherwise the route collides.
+
+Automated production deploys run via
+[`.gitea/workflows/workers-media-deploy.yml`](../../.gitea/workflows/workers-media-deploy.yml)
+after CI succeeds on `main`.
+
+## Verify
+
+```bash
+curl -I https://media.linearvoid.tv/hls/playlist.m3u8   # short TTL
+curl -I https://media.linearvoid.tv/hls/<segment>.m4s   # immutable + CORS
+curl https://media.linearvoid.tv/health                 # {"status":"ok",...}
+```