feat: Telemetry, reactions, polls, and sync system for stream engagement and quality monitoring

[ayobami-dale]

Overview

This PR implements four major features for real-time streaming engagement and infrastructure:

closes #1141
closes #1142
closes #1143
closes #1144

1. Viewer-Side Network Quality & Latency Telemetry Pipeline

• Client instrumentation: Captures startup time, rebuffer events/ratio, bitrate switches, and playback errors per viewer session
• Client batching: Bounds request volume with 10-second intervals and 50-event threshold
• Backend ingestion: POST /api/telemetry/events receives and stores raw events
• Database schema: Tables for raw events, session metrics, and hourly/daily rollups
• Query API: GET /api/telemetry/stream-health returns aggregated metrics by stream and time window
• Rollup jobs: Aggregates raw events into queryable hourly/daily snapshots
• Integration: React hook usePlaybackTelemetry integrated into MuxVideoPlayer
• Files: lib/telemetry/*, app/api/telemetry/*, db/migrations/005_playback_telemetry.sql

2. Real-Time Reaction Bursts with Abuse Throttling

• Rate limiter: Token bucket (20-tap burst, 1 token/sec refill) per user per stream per reaction type
• Aggregator: Batches high-frequency reactions into counts, broadcasts every 200ms
• Ephemeral channel: Dedicated realtime channel for reactions (never persisted)
• Vote endpoint: POST /api/streams/reactions with rate limiting
• Broadcast endpoint: POST /api/realtime/reactions/broadcast for server-side aggregation
• Client hook: useReactions with keyboard shortcuts (h/l/w/f/c for heart/laugh/wow/fire/clap)
• Components: ReactionBar (buttons + counts) and ReactionBurst (animation density)
• Analytics: Daily reaction counts stored in Redis (30-day TTL)
• Files: lib/reactions/*, app/api/streams/reactions/*, app/api/realtime/reactions/broadcast/*, hooks/useReactions.ts, components/reactions/*

3. Live Poll Widgets with Real-Time Result Aggregation

• Rate limiter: 30 votes/min per user, 10 per stream, 100 per IP (sliding window)
• Vote dedup: Unique constraint at data layer ensures one vote per user per poll
• Aggregator: Debounces vote events (500ms default), batches tally broadcasts
• Poll lifecycle: Create (scoped to live stream), open, close, persist final result
• Creator control: Start/stop polls mid-stream
• Abuse resistance: Per-user, per-stream, per-IP rate limiting with sliding window
• Files: lib/polls/*

4. Real-Time Co-Streaming and Watch-Party Synchronized Playback

• Sync protocol: Host-driven with periodic reference clock broadcast
• Drift correction: Clients compute and correct drift against reference timestamp
• DVR-aware: Handles participants at different points in rewind window
• Late-join: New participants sync to correct position without jarring stall
• Lag handling: Defined behavior for participants falling behind on poor network
• Real-time channel: Distinct sync channel for state events
• Abuse prevention: Rate limiting on seek/pause/play commands
• Files: lib/sync/*

[drips-wave]

@ayobami-dale Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[vercel]

@ayobami-dale is attempting to deploy a commit to the david's projects Team on Vercel.

A member of the Team first needs to authorize it.