# Xtream Codes Mock Server A lightweight Express server that simulates the Xtream Codes API for local development and end-to-end testing. Uses `@faker-js/faker` with deterministic seeding so every credential pair always produces the same data. --- ## Quick Start ```bash # Start on port 3211 pnpm nx run xtream-mock-server:serve # Start with file-watch (auto-restart on code changes) pnpm nx run xtream-mock-server:serve-with-watch # Start the mock server plus the Electron app pnpm run serve:marketing-demo # Start the mock server plus the browser web app pnpm run serve:marketing-demo:web ``` --- ## Local Performance Mode The benchmark control plane is opt-in and binds only to an explicit loopback address. Use a dedicated port; do not reuse the normal E2E server on `3211`. ```bash HOST=127.0.0.1 \ PORT=3221 \ IPTVNATOR_XTREAM_MOCK_CONTROL=1 \ IPTVNATOR_XTREAM_MOCK_CONTROL_TOKEN=local-benchmark-token \ pnpm nx run xtream-mock-server:serve ``` When enabled, every `/__control/*` request requires the exact `x-iptvnator-performance-token` header, including `OPTIONS` preflight requests. The server refuses non-loopback binds and an empty token. The control routes do not exist when the flag is absent or is any value other than `1`. The Nx serve targets preserve an explicit shell `PORT`; when it is omitted, the server parser falls back to `XTREAM_MOCK_PORT` — the client-side knob `apps/web-e2e/playwright.config.ts` and the specs read, so one variable moves the mock and the tests together — and then to `3211`. Prepare the fixed synthetic fixture before starting a capture: ```bash curl -X POST http://127.0.0.1:3221/__control/prepare \ -H 'content-type: application/json' \ -H 'x-iptvnator-performance-token: local-benchmark-token' \ -d '{"scenario":"performance-100k"}' ``` The response contains only `epoch`, `scenario`, `seed`, `counts`, `bytes`, and `catalogSha256`. `counts.categories` is `60/20/20` live/VOD/series (100 total) and `counts.items` is `60000/20000/20000` (100,000 total). `bytes` and the SHA-256 cover fixed-order UTF-8 JSON containing, in order, the live, VOD, and series category arrays followed by the live, VOD, and series catalogs. The hash input contains no credentials or server origin. Control endpoints: | Method | Path | Purpose | | ------ | --------------------------------- | ---------------------------------------------------------------------- | | POST | `/__control/prepare` | Materialize `performance-100k` and return its safe manifest | | POST | `/__control/reset` | Reset `observations` or `all` state | | POST | `/__control/barriers` | Add a one-shot, abort-aware request barrier | | POST | `/__control/barriers/:id/release` | Release a request that reached a barrier | | POST | `/__control/delays` | Add a one-shot delay of `0..5000` ms for control/smoke tests only | | GET | `/__control/state` | Read bounded rules, held IDs, occurrences, lifecycle ledger, and epoch | Rules match the exact tuple `(epoch, scenario, transport, action, categoryId, occurrence)`. Occurrences are counted independently per tuple without `occurrence`, so parallel category arrival order cannot change which rule matches. Empty Xtream actions are recorded as `get_account_info`; unknown actions are recorded only as `unknown`. Numeric category IDs use canonical decimal spelling: signs, whitespace, leading zeroes, non-decimal notation, and unsafe integers are rejected. The state never includes the token, credentials, raw URL/query, response payloads, titles, or catalog arrays. `reset` with mode `observations` clears rules, occurrences, held requests, and the ledger while preserving the prepared manifest and epoch. Mode `all` also clears fixture caches and the prepared manifest, then increments the epoch. Held clients are settled during either reset. The legacy unauthenticated `POST /reset` returns `410` in performance mode so it cannot invalidate fixture caches without also invalidating the prepared control manifest; use the token-authenticated control reset instead. JSON bodies are strict and limited to 16 KiB. A state epoch accepts at most 32 rules; the ledger retains 128 entries, and occurrence state has 512 slots for the complete allowlisted identity domain without eviction or counter restart. Duplicate IDs/matches, past occurrences, arbitrary scenarios/actions/category IDs, unknown fields, and invalid delays are rejected. Performance mode is local-only: `/playlist.m3u` and every performance-fixture stream/timeshift URL return `410` without redirecting or contacting external media. Barriers and delays are coordination tools, not timing inputs. **Formal benchmark captures must start with zero barrier and delay rules.** --- ## Available Scenarios (credential pairs) | Username | Password | Scenario | Live cats | VOD cats | Series cats | Items/cat | Status | | ------------- | ------------- | -------------------------- | --------- | -------- | ----------- | --------- | -------- | | `user1` | `pass1` | default | 8 | 8 | 8 | 40 | active | | `large` | `large` | large catalog | 20 | 20 | 20 | 200 | active | | `stress` | `stress` | stress catalog | 16 | 16 | 16 | 120 | active | | `performance` | `performance` | performance-100k | 60 | 20 | 20 | 1,000 | active | | `series` | `series` | series-heavy | 3 | 4 | 15 | 30 | active | | `minimal` | `minimal` | minimal (edge cases) | 2 | 2 | 2 | 5 | active | | `epg` | `epg` | EPG fixture | 2 | 1 | 1 | 3 | active | | `tzoffset` | `tzoffset` | EPG fixture, `UTC+3` clock | 2 | 1 | 1 | 3 | active | | `emptyvod` | `emptyvod` | empty VOD metadata | 2 | 2 | 2 | 5 | active | | `marketing` | `marketing` | fictional release demo | 4 | 4 | 4 | curated | active | | `marketing2` | `marketing2` | same catalog, 2nd copy | 4 | 4 | 4 | curated | active | | `multisrc1` | `multisrc1` | multi-source portal A | 1 | 2 | 1 | 5 | active | | `multisrc2` | `multisrc2` | multi-source portal B | 1 | 2 | 1 | 5 | active | | `expired` | `expired` | expired account | 4 | 4 | 4 | 10 | Expired | | `inactive` | `inactive` | disabled account | 4 | 4 | 4 | 10 | Disabled | | `silent` | `silent` | silent detail endpoints | 2 | 2 | 2 | 5 | active | Any other credential pair is auto-generated using a hash of `username:password` as the faker seed (6 categories, 30 items each, active account). `silent` imports and browses normally, but `get_vod_info` and `get_series_info` accept the connection and never answer — the client's own timeout (30 s in the app) ends each request. It models a live but overloaded panel, which is what the host connectivity guard must NOT mistake for a dead host: open two movie details and the guard has to stay closed. A dead host is reproduced with a non-routable address instead (`http://10.255.255.1:8080`). `multisrc1` and `multisrc2` deliberately share one faker seed, so both portals generate an identical catalog. That overlap is what the VOD multi-source E2E needs — the same movie present in two different playlists. --- ## API Endpoints ### Direct Xtream Protocol `GET /player_api.php?action=&username=&password=

[&...]` | Action | Description | | ---------------------------------------- | --------------------------------------------------- | | (none) / `get_account_info` | User info + server info | | `get_live_categories` | Live TV categories | | `get_vod_categories` | VOD (movie) categories | | `get_series_categories` | Series categories | | `get_live_streams` | Live streams (optionally filtered by `category_id`) | | `get_vod_streams` | VOD streams (optionally filtered by `category_id`) | | `get_series` | Series list (optionally filtered by `category_id`) | | `get_vod_info?vod_id=` | Full movie details | | `get_series_info?series_id=` | Full series info (seasons + episodes) | | `get_short_epg?stream_id=[&limit=N]` | EPG listings for a live channel | | `get_simple_data_table?stream_id=` | Full per-channel EPG schedule | | `get_simple_date_table?stream_id=` | Legacy typo alias for full per-channel EPG schedule | ### PWA CORS Proxy Endpoint IPTVnator's PWA routes Xtream calls through a backend proxy: ``` GET /xtream?url=&action=&username=&password=

``` Response: `{ payload: , action: }` ### Stream URLs (stub redirects) ``` GET /live///.m3u8 → HLS test stream GET /movie///. → HLS test stream GET /series///. → HLS test stream ``` ### Utility Endpoints ``` GET /health → { status: "ok", server: "xtream-mock-server", port: 3211 } POST /reset → clears all in-memory caches; data regenerates on next request ``` --- ## Example Requests ```bash # Account info (direct) curl "http://localhost:3211/player_api.php?username=user1&password=pass1" # Live categories (direct) curl "http://localhost:3211/player_api.php?username=user1&password=pass1&action=get_live_categories" # VOD details (direct) curl "http://localhost:3211/player_api.php?username=user1&password=pass1&action=get_vod_info&vod_id=20000" # Series info (direct) curl "http://localhost:3211/player_api.php?username=user1&password=pass1&action=get_series_info&series_id=30000" # EPG for stream (direct) curl "http://localhost:3211/player_api.php?username=user1&password=pass1&action=get_short_epg&stream_id=10000" # Full EPG schedule (direct) curl "http://localhost:3211/player_api.php?username=epg&password=epg&action=get_simple_data_table&stream_id=10000" # Via PWA proxy curl "http://localhost:3211/xtream?url=http://localhost:3211&username=user1&password=pass1&action=get_live_categories" ``` --- ## Playwright Integration The mock server starts automatically with `nx e2e web-e2e`. Run only Xtream tests using the `@xtream` tag: ```bash nx e2e web-e2e --grep "@xtream" ``` Test files: `apps/web-e2e/src/xtream.e2e.ts` Electron Xtream EPG coverage lives in `apps/electron-backend-e2e/src/xtream-epg.e2e.ts`. The Playwright tests use `page.route()` to redirect the app's backend proxy calls (`localhost:3000/xtream**`) to the mock server without modifying any application code. --- ## Data Characteristics - **Deterministic**: Same credentials → same data every time (seeded faker) - **Cached per session**: Data generated once on first request, reused until `/reset` - **EPG**: Titles and descriptions are base64-encoded (matches real Xtream API) - **Dedicated EPG fixture**: `epg:epg` returns stable live channels plus deterministic `get_short_epg` and `get_simple_data_table` payloads for timezone-focused tests - **Unusable timezone name**: `tzoffset:tzoffset` serves the same EPG fixture behind a panel whose `server_info.timezone` is the ICU-unknown spelling `UTC+3`, while its `time_now` / `timestamp_now` clock pair reveals a +03:00 offset — the catch-up URL must be derived from the clock pair (issue #1562) - **Release screenshot fixture**: `marketing:marketing` returns fictional live, VOD, and series data with local generated artwork under `apps/xtream-mock-server/public/marketing` - **Demo XMLTV guide**: `GET /demo/guide.xml` returns an XMLTV file for the marketing live channels (ids such as `aurora-news.fictional`, eight half-hour programmes around now, logos from the local asset route), so the desktop app can import an EPG source hermetically; guide screenshots use it for the manual channel-mapping flow - **Alternative-source fixture**: `marketing2:marketing2` returns the identical marketing catalog under a second credential pair, so a movie added from both looks like the same film in two playlists (the premise of the VOD multi-source chip); guide screenshots seed it as a "backup subscription" - **Local download media**: `marketing:marketing` also serves `/movie/...`, `/series/...` and `/live/...` stream URLs from generated bytes (`downloadStreamFixture: 'local-media'`; movies finish in under a second, episodes trickle for about 20 s) so release and guide screenshots of the download manager complete without any request leaving the machine. Other scenarios keep redirecting streams to the public HLS stub. - **Performance fixture**: `performance:performance` returns exactly 100,000 local-only catalog items from index-derived values; it does not use Faker, `Date.now()`, `Math.random()`, external artwork, or external media URLs - **Timestamp precedence coverage**: The `epg:epg` scenario intentionally shifts raw `start` / `end` strings away from `start_timestamp` / `stop_timestamp` so UI tests can prove timestamps drive rendering - **Stream IDs**: Live 10,000+, VOD 20,000+, Series 30,000+ - **Category IDs**: Live 101+, VOD 201+, Series 301+ --- ## Release Demo Artwork The `marketing:marketing` fixture uses 65 original fictional titles for release screenshots. Its core 30-title artwork pack includes matched posters and backdrops; 35 additional movie-poster showcase titles use approved local poster PNGs and the deterministic SVG fallback for missing backdrops. The newest 20 showcase movies are ordered first so they appear immediately in screenshot catalog grids. Assets are served from: ```text apps/xtream-mock-server/public/marketing/{poster,backdrop}/ ``` Generate or validate those assets with: ```bash pnpm release:artwork:dry-run pnpm release:artwork:generate pnpm release:artwork:validate ``` `release:artwork:generate` uses `gpt-image-2` through the OpenAI Image API and requires `OPENAI_API_KEY`. The screenshot capture workflow only reads committed local assets; it does not call OpenAI. If a local PNG is missing, the mock server falls back to its deterministic SVG renderer for development continuity. The prompt manifest deliberately varies genres and visual media across titles so the catalog does not collapse into one superhero/poster style. --- ## Architecture See `docs/architecture/xtream-mock-server.md` for a full description of the data pipeline, response shapes, and extension points.