mirror of
https://github.com/4gray/iptvnator.git
synced 2026-10-11 02:46:16 -08:00
4gray
e55d55b47f
Moves the fictional movie catalog into `libs/shared/marketing-fixtures` so the
Xtream and Stalker mocks describe the same titles, and adds 20 rendered posters
plus the shared fixture types behind them.
Supporting changes made while getting it green:
- `shared-marketing-fixtures` is classified Tier B in the coverage policy. Not
Tier A: it is fictional fixture data, so a statement percentage over it means
nothing, and a Tier A entry would pull it into the merged coverage map and the
ratchet. Tier B still runs its spec in CI. `stalker-mock-server` needs no entry
of its own — it is already Tier C and the Tier B/C runner falls back to
`pnpm nx test <project>`, so its new `marketing-poster-url.spec.ts` runs.
- Two release-capture defects the catalog reorder introduced, both fixed in
`tools/release/capture-app-driver.ts`:
- VOD stream ids are `MARKETING_VOD_STREAM_ID_BASE + index` and the generator
now lists the showcase movies first, so 62000-62002 became Black Harbor, The
Paper Astronaut and Summer Static while the dashboard seeding still mapped
those ids to the previous titles' backdrops.
- the raw `tsx` spawn of the Xtream mock lacked `--tsconfig
tsconfig.base.json`, so the mock could not resolve
`@iptvnator/shared/marketing-fixtures` and the capture never started. Both
mock projects' own serve targets already passed the flag.
154 lines
6.9 KiB
Markdown
154 lines
6.9 KiB
Markdown
# Stalker Mock Server
|
||
|
||
A local mock implementation of the Stalker/Ministra portal API for development and end-to-end testing of IPTVnator.
|
||
|
||
## Overview
|
||
|
||
The mock server speaks the same `portal.php` HTTP protocol as a real Stalker portal, generating deterministic fake data using `@faker-js/faker` seeded from the connecting MAC address. This means:
|
||
|
||
- The **same MAC address always returns the same data** (consistent across page refreshes and test runs).
|
||
- **Different MAC addresses produce different datasets** — use predefined scenario MACs for specific test conditions.
|
||
- Data is generated once per MAC on first request and cached in memory for the server's lifetime. **Restart to regenerate.**
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Start the mock server (port 3210)
|
||
nx serve stalker-mock-server
|
||
|
||
# Or with file watching (auto-restarts on source changes)
|
||
nx run stalker-mock-server:serve-with-watch
|
||
|
||
# Or run both the mock server + Angular dev server in parallel
|
||
nx run-many --targets=serve --projects=stalker-mock-server,web
|
||
```
|
||
|
||
Then in IPTVnator, add a new Stalker portal:
|
||
|
||
- **Portal URL**: `http://localhost:3210/portal.php`
|
||
- **MAC Address**: one of the predefined scenarios below (or any MAC for auto-generated data)
|
||
|
||
## Predefined Scenario MAC Addresses
|
||
|
||
| MAC Address | Scenario | Description |
|
||
|---|---|---|
|
||
| `00:1A:79:00:00:01` | **default** | 8 categories per type, 40 items each — the balanced go-to for daily dev |
|
||
| `00:1A:79:FF:FF:FF` | **large** | 20 categories, 200 items each — stress-test pagination and virtual scroll |
|
||
| `00:1A:79:00:00:02` | **series-heavy** | 15 series categories with 6 seasons × 10 episodes — test deep series navigation |
|
||
| `00:1A:79:00:00:03` | **minimal** | 2 categories, 5 items — edge case testing (empty states, single items) |
|
||
| `00:1A:79:00:00:04` | **is-series** | 60% of VOD items have `is_series=1` — tests the Ministra lazy-season flow |
|
||
| `00:1A:79:00:00:05` | **embedded-series** | 50% of VOD items have embedded `series[]` arrays — tests the embedded series flow |
|
||
| `00:1A:79:00:00:06` | **legacy-pagination** | No `get_all_channels` support — tests the paginated `get_ordered_list` crawl fallback for the full ITV channel list |
|
||
| `00:1A:79:00:00:07` | **marketing-demo** | 35 original poster movies with the newest 20 first — safe for screenshots and marketing |
|
||
| `<any other MAC>` | **auto** | MAC bytes used as seed → deterministic unique dataset |
|
||
|
||
## Configuration
|
||
|
||
| Environment Variable | Default | Description |
|
||
|---|---|---|
|
||
| `PORT` | `3210` | HTTP port the server listens on |
|
||
| `NODE_ENV` | `development` | Node environment |
|
||
|
||
## Utility Endpoints
|
||
|
||
| Endpoint | Method | Description |
|
||
|---|---|---|
|
||
| `/health` | `GET` | Health check — returns `{ status: "ok" }` |
|
||
| `/reset` | `POST` | Clear all in-memory data and favorites (useful between test runs) |
|
||
|
||
## API Coverage
|
||
|
||
All endpoints are served at `GET /portal.php?action=<action>&...` matching the real Stalker protocol:
|
||
|
||
| Action | Description |
|
||
|---|---|
|
||
| `handshake` | Returns a mock Bearer token |
|
||
| `do_auth` | Returns a mock user profile |
|
||
| `get_categories` | Category list filtered by `type` (itv/vod/series) |
|
||
| `get_genres` | Genre list (mirrors categories) |
|
||
| `get_ordered_list` | Paginated content list; if `movie_id` is present → returns seasons |
|
||
| `get_all_channels` | Complete ITV channel list in one response (`type=itv` only); excludes censored (adult) genres; disabled in the `legacy-pagination` scenario |
|
||
| `create_link` | Returns a real public HLS stream URL for playback |
|
||
| `favorites` | Add / remove / get favorites (in-memory, resets on restart) |
|
||
| `get_short_epg` | Current-and-upcoming EPG window for a channel (`ch_id`, `size`) |
|
||
| `get_epg_info` | Bulk EPG keyed by channel id for a requested `period` window |
|
||
|
||
## Cover Images
|
||
|
||
Generated scenarios use [Picsum Photos](https://picsum.photos) for cover images
|
||
and logos, so they need an internet connection to display artwork. The
|
||
`marketing-demo` scenario instead uses the committed, screenshot-safe poster
|
||
catalog shared with the Xtream mock. Stalker serves those PNGs itself from
|
||
`/assets/marketing/poster/<slug>.png`, so screenshots remain deterministic and
|
||
offline once the repository is checked out.
|
||
|
||
## Stream URLs
|
||
|
||
`create_link` returns real public HLS test streams so video actually plays:
|
||
|
||
- `https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8`
|
||
- `https://devstreaming-cdn.apple.com/videos/streaming/examples/bipbop_4x3/bipbop_4x3_variant.m3u8`
|
||
- `https://playertest.longtailvideo.com/adaptive/oceans/oceans.m3u8`
|
||
- `https://playertest.longtailvideo.com/adaptive/bbbfull/bbbfull.m3u8`
|
||
|
||
The stream chosen for a given item is deterministic based on the item's `cmd` string.
|
||
|
||
## Using with Playwright E2E Tests
|
||
|
||
The Playwright config in `apps/web-e2e/playwright.config.ts` starts the mock server automatically alongside the Angular dev server when running e2e tests. See `apps/web-e2e/src/stalker.e2e.ts` for example stalker tests.
|
||
|
||
```bash
|
||
# Run all e2e tests (starts mock server automatically)
|
||
nx e2e web-e2e
|
||
|
||
# Or run only stalker-specific e2e tests
|
||
nx e2e web-e2e --grep "@stalker"
|
||
```
|
||
|
||
The test suite uses `00:1A:79:00:00:01` (default scenario) for most tests, and calls `POST /reset` in `beforeEach` to ensure a clean state between tests.
|
||
|
||
## EPG Behavior
|
||
|
||
The mock server generates a 7-day EPG schedule for every ITV channel using
|
||
2-hour slots starting at the current UTC day boundary.
|
||
|
||
- `get_short_epg` returns the current program and upcoming items from that
|
||
schedule, limited by `size`
|
||
- `get_epg_info` returns bulk data in the shape
|
||
`{ js: { data: Record<channelId, program[]> } }`
|
||
- `get_epg_info` filters the bulk response from the current UTC day start through
|
||
`now + period`
|
||
|
||
## Architecture
|
||
|
||
See [`docs/architecture/stalker-mock-server.md`](../../docs/architecture/stalker-mock-server.md) for full implementation details.
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
apps/stalker-mock-server/
|
||
├── src/
|
||
│ ├── main.ts # Express bootstrap
|
||
│ └── app/
|
||
│ ├── scenarios.ts # MAC → scenario config mapping
|
||
│ ├── data-generator.ts # Seeded faker data generation
|
||
│ ├── data-store.ts # Lazy per-MAC in-memory cache
|
||
│ ├── routes/
|
||
│ │ ├── portal.route.ts # /portal.php route
|
||
│ │ └── dispatch.ts # Shared Stalker action dispatcher
|
||
│ └── handlers/
|
||
│ ├── handshake.handler.ts
|
||
│ ├── do-auth.handler.ts
|
||
│ ├── get-categories.handler.ts
|
||
│ ├── get-ordered-list.handler.ts
|
||
│ ├── get-seasons.handler.ts
|
||
│ ├── create-link.handler.ts
|
||
│ ├── favorites.handler.ts
|
||
│ ├── get-epg-info.handler.ts
|
||
│ ├── get-short-epg.handler.ts
|
||
│ └── get-genres.handler.ts
|
||
├── project.json
|
||
├── tsconfig.json
|
||
└── README.md
|
||
```
|