From 9c86d8ed90a7059907518ea99ba847bbcdd17641 Mon Sep 17 00:00:00 2001 From: kushankurdas Date: Wed, 13 May 2026 01:07:14 +0530 Subject: [PATCH] added example for cowatch party room --- cowatch-spoiler-gate/.env.example | 25 + cowatch-spoiler-gate/.gitignore | 2 + cowatch-spoiler-gate/LICENSE.md | 21 + cowatch-spoiler-gate/README.md | 267 ++++++++ cowatch-spoiler-gate/package-lock.json | 878 +++++++++++++++++++++++++ cowatch-spoiler-gate/package.json | 31 + cowatch-spoiler-gate/public/index.html | 65 ++ cowatch-spoiler-gate/public/room.html | 437 ++++++++++++ cowatch-spoiler-gate/server.js | 257 ++++++++ cowatch-spoiler-gate/smoke.mjs | 163 +++++ 10 files changed, 2146 insertions(+) create mode 100644 cowatch-spoiler-gate/.env.example create mode 100644 cowatch-spoiler-gate/.gitignore create mode 100644 cowatch-spoiler-gate/LICENSE.md create mode 100644 cowatch-spoiler-gate/README.md create mode 100644 cowatch-spoiler-gate/package-lock.json create mode 100644 cowatch-spoiler-gate/package.json create mode 100644 cowatch-spoiler-gate/public/index.html create mode 100644 cowatch-spoiler-gate/public/room.html create mode 100644 cowatch-spoiler-gate/server.js create mode 100644 cowatch-spoiler-gate/smoke.mjs diff --git a/cowatch-spoiler-gate/.env.example b/cowatch-spoiler-gate/.env.example new file mode 100644 index 0000000..fff8238 --- /dev/null +++ b/cowatch-spoiler-gate/.env.example @@ -0,0 +1,25 @@ +# Copy this file to .env and fill in real values. +# Source the dashboard: https://dashboard.mux.com +# Settings → Access Tokens (create one with Mux Data permissions). +# Settings → Environments → copy the env-key for the env you want to use. + +# --- Required to enable GET /api/metrics (Mux Data API queries). --- +# A Mux access token. When unset, /api/metrics returns 503 and the Mux Data +# panel in the room view is hidden; the rest of the demo still works. +MUX_TOKEN_ID= +MUX_TOKEN_SECRET= + +# --- Optional — the Mux Data environment key, exposed to the player. --- +# When set, emits Data beacons tagged with the room name and +# viewer display name, so the Mux Data panel can show per-room real-time +# and aggregate metrics. +MUX_DATA_ENV_KEY= + +# --- Optional — pin to a specific Mux playback ID. --- +# Defaults to a public VOD demo asset if unset. Point this at any Mux playback +# ID, including a low-latency Live Stream playback ID if you have one — the +# room view auto-detects live streams and switches to real PDT-based latency. +# MUX_PLAYBACK_ID= + +# --- Optional — HTTP port for the prototype. --- +# PORT=3000 diff --git a/cowatch-spoiler-gate/.gitignore b/cowatch-spoiler-gate/.gitignore new file mode 100644 index 0000000..3ec544c --- /dev/null +++ b/cowatch-spoiler-gate/.gitignore @@ -0,0 +1,2 @@ +node_modules/ +.env \ No newline at end of file diff --git a/cowatch-spoiler-gate/LICENSE.md b/cowatch-spoiler-gate/LICENSE.md new file mode 100644 index 0000000..a57e740 --- /dev/null +++ b/cowatch-spoiler-gate/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Kushankur Das + +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. diff --git a/cowatch-spoiler-gate/README.md b/cowatch-spoiler-gate/README.md new file mode 100644 index 0000000..5e01552 --- /dev/null +++ b/cowatch-spoiler-gate/README.md @@ -0,0 +1,267 @@ +# Latency-equalized co-watch room for Mux + +`cowatch-spoiler-gate` is a small reference application that solves one +specific problem in co-watching ("watch parties", live sports rooms, +Discord movie nights): **fast viewers spoiling moments for slow +viewers**. It is built on top of +[Mux Player](https://www.mux.com/player) and the +[Mux Data API](https://www.mux.com/data), and is intended as a +contributor example for the [Mux OSS program](https://www.mux.com/oss). + +## The problem + +When several people watch the same stream together, their playback drifts +apart. Causes include: + +- A mix of LL-HLS and standard HLS clients in the same room. +- CDN edge variance and network jitter. +- Backgrounded tabs that fall behind on rebuffer. +- Mixed device classes (mobile decoders vs. desktop). + +A spread of one to two seconds is enough for one viewer to type +"OMG goal!" while another viewer is still watching the build-up. The fix +is to give every viewer a common clock and gate reactions to whoever is +furthest behind. + +## How it works + +The room runs two protocol moves on top of a regular Mux Player. + +**1. Sync floor.** Each viewer reports its own latency. The server picks +the slowest viewer's latency and broadcasts it as the room's sync target. +With real LL-HLS, clients are expected to seek to match this floor; the +prototype reports the value so you can see the algorithm at work. + +**2. Spoiler-safe chat.** Every chat message is stamped with the sender's +current Program-Date-Time (PDT) at the moment they hit send. The server +holds that message until **every** viewer's perceived PDT has passed the +sender's stamp. Only then does it broadcast the message to the room. + +The result: a slow viewer cannot be spoiled by a fast viewer's reaction. +A fast viewer's message is held in a queue until the slow viewer has +caught up to the same moment in the stream. + +## Mux integration + +Two Mux surfaces are exercised by this example, on both client and +server. + +| Mux product | Where it is used | What for | +|-------------|------------------|----------| +| **Mux Player** (`@mux/mux-player`) | `public/room.html` | Plays the stream, exposes `player.currentPdt` (EXT-X-PROGRAM-DATE-TIME) for live streams, and emits Mux Data beacons when `env-key` is set. | +| **Mux Data API** (`@mux/mux-node`) | `server.js` → `/api/metrics` | Reads real-time concurrent-viewer count, rebuffer percentage, and video startup time for the room, scoped by `video_id:` (`data.realTime.retrieveTimeseries`, `data.metrics.getOverallValues`). | + +The official `@mux/mux-node` SDK is used for all server-side API calls; +no raw HTTP is hand-rolled. Both surfaces are available on Mux's free +plan. + +## Architecture + +``` + ┌─────────────────────────────────────────────┐ +viewer A ──►│ │ +viewer B ──►│ WebSocket /ws (sync-floor + chat) │ +viewer C ──►│ - tracks latency + PDT per viewer │ + │ - holds chat until every viewer passes │ + │ the sender's PDT │ ┌── Mux Data API ──┐ + │ │──►│ realtime + over- │ + │ HTTP /api/metrics (Mux Data panel) │ │ all metrics │ + │ │ └──────────────────┘ + └─────────────────────────────────────────────┘ +``` + +Per-viewer server state: `{ latencyMs, currentPdt, lastSeen }`. + +Per-pending-message state: `{ from, name, text, releasePdt, recipients }`. +The message is released to all recipients once every eligible recipient +satisfies `currentPdt >= releasePdt`. + +## Project layout + +``` +cowatch-spoiler-gate/ +├── server.js Express + ws server, /api/metrics route, /ws sync server +├── public/ +│ ├── index.html Lobby (join form) +│ └── room.html Mux Player, sync display, synced chat, Mux Data panel +├── smoke.mjs Headless protocol smoke test (no Mux account needed) +├── .env.example Template for the four supported env vars +├── LICENSE.md MIT +└── package.json +``` + +## Modes + +The room view auto-detects which mode it is in from Mux Player's +reported `streamType`. + +| Mode | PDT source | Latency source | +|------|------------|----------------| +| **Live** (LL-HLS, DVR, low-latency DVR) | `player.currentPdt` — the real EXT-X-PROGRAM-DATE-TIME from the manifest | `Date.now() - player.currentPdt` — the real distance between wall-clock and the playhead | +| **VOD demo** | `player.currentTime * 1000` — milliseconds since stream start | A slider, so you can simulate a slower viewer without a live stream | + +In live mode the slider is hidden because latency is observed, not +chosen. To run in live mode, set `MUX_PLAYBACK_ID` to a Mux Live Stream +playback ID you already have (Mux Live Stream creation is a paid +feature, so it is not part of this example). + +## Setup + +```bash +npm install +cp .env.example .env # then edit .env and fill in real values +npm start # http://localhost:3000 +# or, with auto-reload: +npm run dev +``` + +The server auto-loads `.env` on startup using Node's built-in +`process.loadEnvFile()` (Node 20.12 or later). No `dotenv` dependency is +required. You can also export the variables in your shell or pass +`--env-file=.env` to `node` directly — any of the three works. + +On startup the banner reports the wiring state of each integration: + +``` +cowatch-spoiler-gate listening on http://localhost:3000 + playback-id: DS00Spx1CV902MCtPj5WknGlR102V5HFkDe + Mux Data API: wired (/api/metrics active) + Mux Data env-key: wired (player will emit beacons) +``` + +If either says `OFF`, the demo still works — `/api/metrics` returns +`503` and the Mux Data panel is hidden, but the WebSocket-based sync +floor and chat-gate continue to function. + +### Environment variables + +| Variable | Purpose | +|----------|---------| +| `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET` | Mux access token with **Mux Data** read permissions. Required for `GET /api/metrics`. | +| `MUX_DATA_ENV_KEY` | Mux Data environment key (Mux dashboard → *Settings → Environments*). When set, Mux Player emits Data beacons tagged with `metadata-video-id=` and `metadata-viewer-user-id=`. | +| `MUX_PLAYBACK_ID` | Mux playback ID to play. Defaults to a public VOD demo asset. Point this at any playback ID, including a live one if you have access. | +| `PORT` | HTTP port. Defaults to `3000`. | + +`.env` is excluded from git via `.gitignore` so credentials are not +accidentally committed. + +## HTTP endpoints + +| Route | Description | +|-------|-------------| +| `GET /` | Lobby (join form). | +| `GET /room.html?room=…&name=…` | Room view (player + sync stats + chat + Mux Data panel). | +| `GET /config.json` | Player config: playback ID, Data env-key, whether `/api/metrics` is wired. | +| `GET /api/metrics?room=` | Reads three Mux Data values for `video_id:`: real-time concurrent viewers, last-hour rebuffer percentage, last-hour video startup time. Returns `503` if Mux credentials are not set. | +| `WS /ws?room=…&name=…` | Sync floor and chat protocol. Messages: `latency_report`, `pdt_progress`, `chat_send` (in); `hello_ack`, `sync_update`, `chat_release` (out). | + +## How to use it (VOD demo) + +This path needs no Mux account. + +1. Open `http://localhost:3000` in two browser tabs. +2. Join the same room name (for example, `lobby`) using two different + display names (for example, `alice` and `bob`). +3. Each tab plays the VOD asset independently. The "Sim latency" slider + sets that tab's reported latency. The viewer with the higher slider + value is treated as the slower viewer. + +The slowest viewer in the room is marked **◀ floor** in the roster. The +"(N messages held — waiting for slowest viewer)" indicator shows messages +currently held by the server. The sender does **not** see their own +message in the chat list until the server releases it. + +To see the spoiler-gate working: + +1. Set alice's slider to 500ms and bob's slider to 8000ms. +2. Wait until both players have been playing for around 30 seconds. + Alice's perceived PDT will be roughly 29.5s; bob's roughly 22s. +3. Send `"spoiler!"` from alice (the faster viewer). Alice's tab shows + `(1 message held)` and nothing else. +4. Wait. As bob's player advances, his perceived PDT ticks up. Once it + crosses ~29.5s, the message is released to both tabs at the same time. +5. Now send `"reaction"` from bob (the slower viewer). It releases + immediately, because alice's perceived PDT is already past bob's stamp. + +This asymmetry — fast-sender messages held, slow-sender messages +instantaneous — is the spoiler-gate working correctly. + +## How to use it (Live mode) + +If you have a Mux Live Stream available (the Live Stream API is a paid +feature and not exercised by this example), point the demo at it: + +```bash +echo 'MUX_PLAYBACK_ID=' >> .env +npm start +``` + +Mux Player will detect the stream as live, the simulated-latency slider +will disappear, and `player.currentPdt` becomes the source of truth for +both latency and chat gating. You cannot seek ahead of the live edge, +so the cross-tab playback divergence you see in VOD mode is not a +concern. + +## Mux Data panel + +When `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET` are set, the room view shows +a *Mux Data* panel with three values polled every ten seconds from +`GET /api/metrics?room=`: + +- **Concurrent viewers (real-time)** — latest data point from the Mux + Data Realtime API for the `current-concurrent-viewers` metric, + filtered by `video_id:`. Mux Player on each viewer is configured + with `metadata-video-id=` so beacons land under that filter. +- **Rebuffer % (last hour)** — overall value of the + `rebuffer_percentage` metric, scoped by the same `video_id`. +- **Video startup time (last hour)** — overall value of + `video_startup_time` over the same window. + +Mux Data has a processing delay of roughly a minute, so the first time +a viewer joins a fresh room you will see dashes until the first beacons +are ingested. This panel is intentionally read-only — the +WebSocket-reported latency, not the Data metric, is what drives the +sync-floor algorithm. The Data integration is observational. + +## Known limitations of the demo + +- **VOD playback is not synchronized across tabs.** Each tab's player + has its own `currentTime`; pausing or seeking in one tab does not + affect the others. This is intentional in the demo so that you can + produce real PDT divergence with a single asset. In a production + watch-party you would either run on Mux Live (no seeking) or add a + playback-sync layer (broadcast play/pause/seek over the same socket). +- **Stale-viewer eviction at 10 seconds.** If a viewer stops sending + `pdt_progress` for ten seconds — closing the tab, backgrounding on + mobile, or pausing for a long time — the server removes them from the + eligibility set for held messages, which causes those messages to + release to the remaining viewers. This is a deliberate "stuck viewer" + fallback so the room does not freeze permanently. +- **No authentication.** Anyone with the URL can join any room. + +## Production hardening (out of scope for the example) + +- AuthN/Z on room join, with signed Mux playback policies and a real + user identity. +- Rate limiting on `chat_send` per viewer. +- Persistent rooms across server restarts. +- Maximum hold time on a chat message before forcing release, + independent of the stale-viewer timeout. +- Horizontal scale via Redis pub/sub for cross-instance broadcasts. +- Profanity, spoiler-keyword, and image-moderation hooks before release. + +## Smoke test + +A headless multi-viewer protocol test is included: + +```bash +node smoke.mjs +``` + +It spins up two WebSocket clients, exercises latency reporting, the +sync floor, the chat-hold-and-release behavior in both directions, and +the disconnect path. No Mux account is required to run it. + +## License + +[MIT](LICENSE.md). diff --git a/cowatch-spoiler-gate/package-lock.json b/cowatch-spoiler-gate/package-lock.json new file mode 100644 index 0000000..3c862f9 --- /dev/null +++ b/cowatch-spoiler-gate/package-lock.json @@ -0,0 +1,878 @@ +{ + "name": "cowatch-spoiler-gate", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "cowatch-spoiler-gate", + "version": "0.1.0", + "license": "MIT", + "dependencies": { + "@mux/mux-node": "^14.0.0", + "express": "^4.21.2", + "ws": "^8.18.0" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/@mux/mux-node": { + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/@mux/mux-node/-/mux-node-14.0.1.tgz", + "integrity": "sha512-wpLRvxVHEVmwMUInT95gFiQbKp62KpEX5ViG4aaK1W6q2vZMTUNCFLKvWHN0L3q8uVd6KQYHNnAL8e8bHOEWCg==", + "license": "Apache-2.0", + "bin": { + "mux-mux-node": "bin/cli" + } + }, + "node_modules/accepts": { + "version": "1.3.8", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-1.3.8.tgz", + "integrity": "sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==", + "license": "MIT", + "dependencies": { + "mime-types": "~2.1.34", + "negotiator": "0.6.3" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/array-flatten": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/array-flatten/-/array-flatten-1.1.1.tgz", + "integrity": "sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==", + "license": "MIT" + }, + "node_modules/body-parser": { + "version": "1.20.5", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.5.tgz", + "integrity": "sha512-3grm+/2tUOvu2cjJkvsIxrv/wVpfXQW4PsQHYm7yk4vfpu7Ekl6nEsYBoJUL6qDwZUx8wUhQ8tR2qz+ad9c9OA==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "content-type": "~1.0.5", + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "~1.2.0", + "http-errors": "~2.0.1", + "iconv-lite": "~0.4.24", + "on-finished": "~2.4.1", + "qs": "~6.15.1", + "raw-body": "~2.5.3", + "type-is": "~1.6.18", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/body-parser/node_modules/qs": { + "version": "6.15.1", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz", + "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==", + "license": "BSD-3-Clause", + "dependencies": { + "side-channel": "^1.1.0" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/call-bound": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", + "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "get-intrinsic": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/content-disposition": { + "version": "0.5.4", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.4.tgz", + "integrity": "sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==", + "license": "MIT", + "dependencies": { + "safe-buffer": "5.2.1" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", + "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie-signature": { + "version": "1.0.7", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.0.7.tgz", + "integrity": "sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==", + "license": "MIT" + }, + "node_modules/debug": { + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz", + "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==", + "license": "MIT", + "dependencies": { + "ms": "2.0.0" + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/destroy": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/destroy/-/destroy-1.2.0.tgz", + "integrity": "sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==", + "license": "MIT", + "engines": { + "node": ">= 0.8", + "npm": "1.2.8000 || >= 1.4.16" + } + }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "license": "MIT" + }, + "node_modules/encodeurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz", + "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/es-define-property": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-errors": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz", + "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-object-atoms": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz", + "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "license": "MIT" + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/express": { + "version": "4.22.1", + "resolved": "https://registry.npmjs.org/express/-/express-4.22.1.tgz", + "integrity": "sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==", + "license": "MIT", + "dependencies": { + "accepts": "~1.3.8", + "array-flatten": "1.1.1", + "body-parser": "~1.20.3", + "content-disposition": "~0.5.4", + "content-type": "~1.0.4", + "cookie": "~0.7.1", + "cookie-signature": "~1.0.6", + "debug": "2.6.9", + "depd": "2.0.0", + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "finalhandler": "~1.3.1", + "fresh": "~0.5.2", + "http-errors": "~2.0.0", + "merge-descriptors": "1.0.3", + "methods": "~1.1.2", + "on-finished": "~2.4.1", + "parseurl": "~1.3.3", + "path-to-regexp": "~0.1.12", + "proxy-addr": "~2.0.7", + "qs": "~6.14.0", + "range-parser": "~1.2.1", + "safe-buffer": "5.2.1", + "send": "~0.19.0", + "serve-static": "~1.16.2", + "setprototypeof": "1.2.0", + "statuses": "~2.0.1", + "type-is": "~1.6.18", + "utils-merge": "1.0.1", + "vary": "~1.1.2" + }, + "engines": { + "node": ">= 0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/finalhandler": { + "version": "1.3.2", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-1.3.2.tgz", + "integrity": "sha512-aA4RyPcd3badbdABGDuTXCMTtOneUCAYH/gxoYRTZlIJdF0YPWuGqiAsIrhNnnqdXGswYk6dGujem4w80UJFhg==", + "license": "MIT", + "dependencies": { + "debug": "2.6.9", + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "on-finished": "~2.4.1", + "parseurl": "~1.3.3", + "statuses": "~2.0.2", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fresh": { + "version": "0.5.2", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-0.5.2.tgz", + "integrity": "sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-intrinsic": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", + "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", + "function-bind": "^1.1.2", + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "license": "MIT", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/gopd": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/hasown": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz", + "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==", + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/http-errors": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", + "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", + "license": "MIT", + "dependencies": { + "depd": "~2.0.0", + "inherits": "~2.0.4", + "setprototypeof": "~1.2.0", + "statuses": "~2.0.2", + "toidentifier": "~1.0.1" + }, + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/iconv-lite": { + "version": "0.4.24", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz", + "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==", + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/media-typer": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz", + "integrity": "sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/merge-descriptors": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-1.0.3.tgz", + "integrity": "sha512-gaNvAS7TZ897/rVaZ0nMtAyxNyi/pdbjbAwUpFQpN70GqnVfOiXpeUUMKRBmzXaSQ8DdTX4/0ms62r2K+hE6mQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/methods": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/methods/-/methods-1.1.2.tgz", + "integrity": "sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz", + "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==", + "license": "MIT", + "bin": { + "mime": "cli.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/mime-db": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", + "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "2.1.35", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", + "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", + "license": "MIT", + "dependencies": { + "mime-db": "1.52.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/ms": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz", + "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==", + "license": "MIT" + }, + "node_modules/negotiator": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.3.tgz", + "integrity": "sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/object-inspect": { + "version": "1.13.4", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", + "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "license": "MIT", + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/path-to-regexp": { + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-0.1.13.tgz", + "integrity": "sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==", + "license": "MIT" + }, + "node_modules/proxy-addr": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", + "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==", + "license": "MIT", + "dependencies": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/qs": { + "version": "6.14.2", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.2.tgz", + "integrity": "sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==", + "license": "BSD-3-Clause", + "dependencies": { + "side-channel": "^1.1.0" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/range-parser": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", + "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/raw-body": { + "version": "2.5.3", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-2.5.3.tgz", + "integrity": "sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "http-errors": "~2.0.1", + "iconv-lite": "~0.4.24", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/safe-buffer": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz", + "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "license": "MIT" + }, + "node_modules/send": { + "version": "0.19.2", + "resolved": "https://registry.npmjs.org/send/-/send-0.19.2.tgz", + "integrity": "sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==", + "license": "MIT", + "dependencies": { + "debug": "2.6.9", + "depd": "2.0.0", + "destroy": "1.2.0", + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "etag": "~1.8.1", + "fresh": "~0.5.2", + "http-errors": "~2.0.1", + "mime": "1.6.0", + "ms": "2.1.3", + "on-finished": "~2.4.1", + "range-parser": "~1.2.1", + "statuses": "~2.0.2" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/send/node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/serve-static": { + "version": "1.16.3", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-1.16.3.tgz", + "integrity": "sha512-x0RTqQel6g5SY7Lg6ZreMmsOzncHFU7nhnRWkKgWuMTu5NN0DR5oruckMqRvacAN9d5w6ARnRBXl9xhDCgfMeA==", + "license": "MIT", + "dependencies": { + "encodeurl": "~2.0.0", + "escape-html": "~1.0.3", + "parseurl": "~1.3.3", + "send": "~0.19.1" + }, + "engines": { + "node": ">= 0.8.0" + } + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "license": "ISC" + }, + "node_modules/side-channel": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz", + "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.3", + "side-channel-list": "^1.0.0", + "side-channel-map": "^1.0.1", + "side-channel-weakmap": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-list": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz", + "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-map": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", + "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-weakmap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", + "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3", + "side-channel-map": "^1.0.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/statuses": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", + "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "license": "MIT", + "engines": { + "node": ">=0.6" + } + }, + "node_modules/type-is": { + "version": "1.6.18", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-1.6.18.tgz", + "integrity": "sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==", + "license": "MIT", + "dependencies": { + "media-typer": "0.3.0", + "mime-types": "~2.1.24" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/utils-merge": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/utils-merge/-/utils-merge-1.0.1.tgz", + "integrity": "sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==", + "license": "MIT", + "engines": { + "node": ">= 0.4.0" + } + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/ws": { + "version": "8.20.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz", + "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==", + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + } + } +} diff --git a/cowatch-spoiler-gate/package.json b/cowatch-spoiler-gate/package.json new file mode 100644 index 0000000..7bdf472 --- /dev/null +++ b/cowatch-spoiler-gate/package.json @@ -0,0 +1,31 @@ +{ + "name": "cowatch-spoiler-gate", + "version": "0.1.0", + "type": "module", + "description": "Latency-equalized co-watch room with PDT-gated spoiler-safe chat, built on Mux Player and the Mux Data API.", + "scripts": { + "start": "node server.js", + "dev": "node --watch server.js" + }, + "dependencies": { + "@mux/mux-node": "^14.0.0", + "express": "^4.21.2", + "ws": "^8.18.0" + }, + "engines": { + "node": ">=20" + }, + "keywords": [ + "mux", + "mux-player", + "mux-data", + "co-watch", + "watch-party", + "synchronization", + "websocket", + "program-date-time", + "ll-hls" + ], + "author": "Kushankur Das (@kushankurdas)", + "license": "MIT" +} diff --git a/cowatch-spoiler-gate/public/index.html b/cowatch-spoiler-gate/public/index.html new file mode 100644 index 0000000..797c586 --- /dev/null +++ b/cowatch-spoiler-gate/public/index.html @@ -0,0 +1,65 @@ + + + + + +Co-watch room — Mux example + + + +
+

Co-watch room

+

latency-equalized co-watch · Mux Player + WebSocket sync floor

+
+ + + + + +
+

+ Open multiple tabs / devices in the same room. Each tab acts as one viewer + with a configurable simulated latency. The slowest viewer becomes the + group sync floor and chat is gated to that floor — fast viewers can't + react before slow ones reach the same moment. +

+
+ + + diff --git a/cowatch-spoiler-gate/public/room.html b/cowatch-spoiler-gate/public/room.html new file mode 100644 index 0000000..b176398 --- /dev/null +++ b/cowatch-spoiler-gate/public/room.html @@ -0,0 +1,437 @@ + + + + + +Co-watch room + + + + + +
+ +
+
+
Room — · you are —
+
disconnected
+
+ +
+ +
+ +
+

Group sync

+
Sync floor (slowest viewer latency)—
+
Target offset (floor + 500ms safety)—
+
My reported latency—
+
My current PDT (perceived)—
+
+ Sim latency + + 2000ms +
+ + VOD demo mode — slider simulates this client's latency so you can + exercise the algorithm without a live stream. With a Mux Live + playback ID, latency is read from the real distance between + wall-clock and the player's currentPdt and the slider + is hidden. + +
+
+ +
+
+

Roster

+
connecting…
+
+ +
+

Synced chat

+
+
+
+ + +
+ + Each message is stamped with the sender's current PDT, then held by the + server until every viewer has reached that PDT. Slow viewers can never + be spoiled by faster ones. + +
+
+ +
+ + + + diff --git a/cowatch-spoiler-gate/server.js b/cowatch-spoiler-gate/server.js new file mode 100644 index 0000000..98c7288 --- /dev/null +++ b/cowatch-spoiler-gate/server.js @@ -0,0 +1,257 @@ +// cowatch-spoiler-gate — latency-equalized co-watch sync server. +// +// Two protocol moves the room runs: +// +// 1. SYNC FLOOR: every viewer reports its own latency. Server picks +// slowest, broadcasts as the group's sync target. (In real LL-HLS +// the player would seek to match this; the prototype only displays +// it because we use VOD playback.) +// +// 2. SPOILER-SAFE CHAT: a chat message is stamped with the sender's +// current PDT (Program-Date-Time). Server holds the message until +// every recipient's playback has passed that PDT. Fast viewers +// can't react before slow viewers see the moment. +// +// Swap path for real Mux Live: replace the simulated latency in room.html +// with `player.currentPdt` (or HLS.js fragment PDT) and remove the slider. + +import express from 'express'; +import { WebSocketServer } from 'ws'; +import { createServer } from 'node:http'; +import { randomUUID } from 'node:crypto'; +import { existsSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import Mux from '@mux/mux-node'; + +const envPath = join(dirname(fileURLToPath(import.meta.url)), '.env'); +if (existsSync(envPath) && typeof process.loadEnvFile === 'function') { + process.loadEnvFile(envPath); +} + +const PORT = Number(process.env.PORT) || 3000; +const SYNC_BUFFER_MS = 500; +const STALE_VIEWER_MS = 10_000; +const DEFAULT_PLAYBACK_ID = + process.env.MUX_PLAYBACK_ID || 'DS00Spx1CV902MCtPj5WknGlR102V5HFkDe'; + +const MUX_TOKEN_ID = process.env.MUX_TOKEN_ID || null; +const MUX_TOKEN_SECRET = process.env.MUX_TOKEN_SECRET || null; +const MUX_DATA_ENV_KEY = process.env.MUX_DATA_ENV_KEY || null; + +const mux = + MUX_TOKEN_ID && MUX_TOKEN_SECRET + ? new Mux({ tokenId: MUX_TOKEN_ID, tokenSecret: MUX_TOKEN_SECRET }) + : null; + +const app = express(); +app.use(express.json()); +app.use(express.static('public')); + +app.get('/config.json', (_req, res) => { + res.json({ + muxPlaybackId: DEFAULT_PLAYBACK_ID, + muxDataEnvKey: MUX_DATA_ENV_KEY, + muxApiReady: !!mux, + }); +}); + +function requireMux(res) { + if (mux) return true; + res.status(503).json({ + error: + 'MUX_TOKEN_ID and MUX_TOKEN_SECRET are not set; the metrics endpoint is disabled in this server', + }); + return false; +} + +app.get('/api/metrics', async (req, res) => { + if (!requireMux(res)) return; + const videoId = String(req.query.room || 'default').slice(0, 64); + const filters = [`video_id:${videoId}`]; + const now = Math.floor(Date.now() / 1000); + const timeframe = [String(now - 3600), String(now)]; + try { + const [concurrent, rebuffer, startup] = await Promise.allSettled([ + mux.data.realTime.retrieveTimeseries('current-concurrent-viewers', { filters }), + mux.data.metrics.getOverallValues('rebuffer_percentage', { filters, timeframe }), + mux.data.metrics.getOverallValues('video_startup_time', { filters, timeframe }), + ]); + const concurrentPoints = + concurrent.status === 'fulfilled' ? concurrent.value?.data || [] : []; + const latestConcurrent = concurrentPoints.length + ? concurrentPoints[concurrentPoints.length - 1]?.value ?? null + : null; + res.json({ + videoId, + windowSeconds: 3600, + concurrentViewers: latestConcurrent, + rebufferPercentage: + rebuffer.status === 'fulfilled' ? rebuffer.value?.data?.value ?? null : null, + videoStartupTimeMs: + startup.status === 'fulfilled' ? startup.value?.data?.value ?? null : null, + errors: [concurrent, rebuffer, startup] + .filter((r) => r.status === 'rejected') + .map((r) => String(r.reason?.message || r.reason)), + }); + } catch (err) { + res.status(502).json({ error: String(err?.message || err) }); + } +}); + +const server = createServer(app); +const wss = new WebSocketServer({ server, path: '/ws' }); + +// rooms: roomId -> { +// viewers: Map, +// pending: Map }>, +// } +const rooms = new Map(); + +function getRoom(id) { + let room = rooms.get(id); + if (!room) { + room = { viewers: new Map(), pending: new Map() }; + rooms.set(id, room); + } + return room; +} + +function broadcast(room, msg) { + const payload = JSON.stringify(msg); + for (const v of room.viewers.values()) { + if (v.ws.readyState === 1) v.ws.send(payload); + } +} + +function rosterSnapshot(room) { + return [...room.viewers.entries()].map(([id, v]) => ({ + id, + name: v.name, + latencyMs: Number.isFinite(v.latencyMs) ? v.latencyMs : null, + })); +} + +function broadcastSync(room) { + const latencies = [...room.viewers.values()] + .map((v) => v.latencyMs) + .filter((n) => Number.isFinite(n)); + const slowestMs = latencies.length ? Math.max(...latencies) : null; + const targetOffsetMs = slowestMs == null ? null : slowestMs + SYNC_BUFFER_MS; + broadcast(room, { + type: 'sync_update', + slowestMs, + targetOffsetMs, + roster: rosterSnapshot(room), + }); +} + +function tryReleaseMessages(room) { + const now = Date.now(); + for (const [msgId, msg] of room.pending) { + const stillPresent = [...msg.recipients].some((id) => room.viewers.has(id)); + if (!stillPresent) { + room.pending.delete(msgId); + continue; + } + const eligible = [...room.viewers.entries()].filter( + ([id, v]) => + msg.recipients.has(id) && + Number.isFinite(v.currentPdt) && + now - v.lastSeen < STALE_VIEWER_MS, + ); + const allPassed = + eligible.length > 0 && + eligible.every(([, v]) => v.currentPdt >= msg.releasePdt); + if (allPassed) { + broadcast(room, { + type: 'chat_release', + msgId, + from: msg.from, + name: msg.name, + text: msg.text, + releasePdt: msg.releasePdt, + }); + room.pending.delete(msgId); + } + } +} + +setInterval(() => { + for (const room of rooms.values()) tryReleaseMessages(room); +}, 1000); + +wss.on('connection', (ws, req) => { + const url = new URL(req.url, 'http://localhost'); + const roomId = (url.searchParams.get('room') || 'default').slice(0, 64); + const name = (url.searchParams.get('name') || 'anon').slice(0, 32); + const viewerId = randomUUID(); + const room = getRoom(roomId); + + room.viewers.set(viewerId, { + ws, + name, + latencyMs: NaN, + currentPdt: NaN, + lastSeen: Date.now(), + }); + + ws.send(JSON.stringify({ type: 'hello_ack', viewerId, roomId })); + broadcastSync(room); + + ws.on('message', (raw) => { + let msg; + try { + msg = JSON.parse(raw); + } catch { + return; + } + const v = room.viewers.get(viewerId); + if (!v) return; + v.lastSeen = Date.now(); + + if (msg.type === 'latency_report') { + const n = Number(msg.latencyMs); + if (Number.isFinite(n) && n >= 0 && n < 60_000) { + v.latencyMs = n; + broadcastSync(room); + } + } else if (msg.type === 'pdt_progress') { + const n = Number(msg.currentPdt); + if (Number.isFinite(n)) { + v.currentPdt = n; + tryReleaseMessages(room); + } + } else if (msg.type === 'chat_send') { + const text = String(msg.text ?? '').slice(0, 500).trim(); + const senderPdt = v.currentPdt; + if (!text || !Number.isFinite(senderPdt)) return; + const msgId = randomUUID(); + room.pending.set(msgId, { + from: viewerId, + name: v.name, + text, + releasePdt: senderPdt, + recipients: new Set(room.viewers.keys()), + }); + tryReleaseMessages(room); + } + }); + + ws.on('close', () => { + room.viewers.delete(viewerId); + if (room.viewers.size === 0) { + rooms.delete(roomId); + } else { + broadcastSync(room); + tryReleaseMessages(room); + } + }); +}); + +server.listen(PORT, () => { + console.log(`cowatch-spoiler-gate listening on http://localhost:${PORT}`); + console.log(` playback-id: ${DEFAULT_PLAYBACK_ID}`); + console.log(` Mux Data API: ${mux ? 'wired (/api/metrics active)' : 'OFF (set MUX_TOKEN_ID and MUX_TOKEN_SECRET to enable)'}`); + console.log(` Mux Data env-key: ${MUX_DATA_ENV_KEY ? 'wired (player will emit beacons)' : 'OFF (set MUX_DATA_ENV_KEY to enable)'}`); +}); diff --git a/cowatch-spoiler-gate/smoke.mjs b/cowatch-spoiler-gate/smoke.mjs new file mode 100644 index 0000000..9c45c0c --- /dev/null +++ b/cowatch-spoiler-gate/smoke.mjs @@ -0,0 +1,163 @@ +// End-to-end smoke test for cowatch-spoiler-gate. +// Connects two WS clients to the same room, exercises the sync-floor +// algorithm and the spoiler-safe chat gating, and verifies expected +// state transitions. +// +// Run: +// PORT=3987 node server.js & # start server +// PORT=3987 node smoke.mjs + +import WebSocket from 'ws'; +import { setTimeout as sleep } from 'node:timers/promises'; + +const HOST = process.env.HOST || 'localhost'; +const PORT = process.env.PORT || '3000'; +const ROOM = `smoke-${Date.now()}`; + +let failures = 0; +function check(name, ok, info = '') { + const tag = ok ? 'PASS' : 'FAIL'; + if (!ok) failures++; + console.log(` ${tag} ${name}${info ? ' — ' + info : ''}`); +} + +function open(name, latencyMs) { + return new Promise((resolve, reject) => { + const url = `ws://${HOST}:${PORT}/ws?room=${ROOM}&name=${name}`; + const ws = new WebSocket(url); + const events = []; + const state = { viewerId: null, lastSync: null, releases: [] }; + ws.on('message', (raw) => { + const msg = JSON.parse(raw); + events.push(msg); + if (msg.type === 'hello_ack') state.viewerId = msg.viewerId; + if (msg.type === 'sync_update') state.lastSync = msg; + if (msg.type === 'chat_release') state.releases.push(msg); + }); + ws.once('open', () => { + ws.send(JSON.stringify({ type: 'latency_report', latencyMs })); + resolve({ ws, events, state }); + }); + ws.once('error', reject); + }); +} + +function send(ws, payload) { + ws.send(JSON.stringify(payload)); +} + +async function main() { + console.log(`\ncowatch-spoiler-gate smoke test (room=${ROOM})\n`); + + // 1. HTTP sanity + const httpRes = await fetch(`http://${HOST}:${PORT}/`); + check('GET /', httpRes.ok, `status ${httpRes.status}`); + const cfgRes = await fetch(`http://${HOST}:${PORT}/config.json`); + const cfg = cfgRes.ok ? await cfgRes.json() : {}; + check( + 'GET /config.json', + cfgRes.ok && typeof cfg.muxPlaybackId === 'string', + `playback-id=${cfg.muxPlaybackId}`, + ); + + // 2. Two viewers join, different latencies + const fast = await open('fast', 1000); + const slow = await open('slow', 4500); + await sleep(150); + + // 3. Sync floor should equal slowest (4500) + check( + 'sync floor = max latency', + fast.state.lastSync && fast.state.lastSync.slowestMs === 4500, + `slowestMs=${fast.state.lastSync?.slowestMs}`, + ); + check( + 'target offset = floor + 500ms safety', + fast.state.lastSync && fast.state.lastSync.targetOffsetMs === 5000, + `targetOffsetMs=${fast.state.lastSync?.targetOffsetMs}`, + ); + check( + 'roster has both viewers', + fast.state.lastSync && fast.state.lastSync.roster.length === 2, + `n=${fast.state.lastSync?.roster.length}`, + ); + + // 4. Set per-viewer perceived PDTs. + // Fast at 10s, slow at 7s. Fast sends a chat at PDT=10s. + send(fast.ws, { type: 'pdt_progress', currentPdt: 10000 }); + send(slow.ws, { type: 'pdt_progress', currentPdt: 7000 }); + await sleep(80); + send(fast.ws, { type: 'chat_send', text: 'hello from the future' }); + await sleep(150); + + check( + 'chat held while slow viewer behind sender PDT', + fast.state.releases.length === 0 && slow.state.releases.length === 0, + `fast=${fast.state.releases.length}, slow=${slow.state.releases.length}`, + ); + + // 5. Slow viewer advances past 10s. Server should release. + send(slow.ws, { type: 'pdt_progress', currentPdt: 10500 }); + await sleep(200); + + check( + 'fast received release after slow caught up', + fast.state.releases.length === 1, + `n=${fast.state.releases.length}`, + ); + check( + 'slow received release after slow caught up', + slow.state.releases.length === 1, + `n=${slow.state.releases.length}`, + ); + if (fast.state.releases.length === 1) { + const r = fast.state.releases[0]; + check( + 'released msg preserves sender + text', + r.name === 'fast' && r.text === 'hello from the future', + `name=${r.name}, releasePdt=${r.releasePdt}`, + ); + } + + // 6. New send when slow is already past sender's PDT → instant release. + send(slow.ws, { type: 'pdt_progress', currentPdt: 12000 }); + send(fast.ws, { type: 'pdt_progress', currentPdt: 11500 }); + await sleep(80); + send(fast.ws, { type: 'chat_send', text: 'instant' }); + await sleep(150); + check( + 'chat releases immediately when all viewers already past sender PDT', + fast.state.releases.length === 2, + `n=${fast.state.releases.length}`, + ); + + // 7. Sender slowest case: floor follows them, chat releases instantly. + send(slow.ws, { type: 'latency_report', latencyMs: 2000 }); + send(fast.ws, { type: 'latency_report', latencyMs: 6000 }); + await sleep(120); + check( + 'floor moves when latencies change', + fast.state.lastSync.slowestMs === 6000, + `slowestMs=${fast.state.lastSync.slowestMs}`, + ); + + // 8. Disconnect cleanup + fast.ws.close(); + await sleep(120); + check( + 'roster shrinks on disconnect', + slow.state.lastSync.roster.length === 1, + `n=${slow.state.lastSync.roster.length}`, + ); + + slow.ws.close(); + await sleep(80); + + console.log(`\n${failures === 0 ? 'all checks passed' : failures + ' check(s) failed'}\n`); + process.exit(failures === 0 ? 0 : 1); +} + +main().catch((e) => { + console.error('smoke test error:', e); + process.exit(2); +});