mirror of
https://github.com/4gray/iptvnator.git
synced 2026-10-14 21:26:15 -08:00
4grayandClaude Fable 5
3dbfefa3d8
* test(stalker): enforce portal auth in the mock and cover the full-portal flow
The mock server implemented neither get_profile nor get_events and
validated no auth at all, and the e2e suite imported the portal through
/portal.php — which the app classifies as a *simple* portal. The entire
authenticated branch (handshake, token, watchdog, re-auth) therefore had
zero coverage, right before a series of PRs that reworks exactly that.
Mock server:
- serve the canonical /stalker_portal/server/load.php endpoint, which
enforces the Bearer token and the Infomir MAC format like the real
middleware; /portal.php stays tolerant so the existing suite keeps
covering the simple-portal branch
- auth-store.ts models the parts of Stalker 4.9.35 a client can get
wrong: plain-text auth failures with HTTP 200, a handshake that is not
yet a session, idempotent token re-presentation, and permanent
device_id pinning (including the blank-after-pinned lockout)
- add get_profile (status 0/1/2, device conflict, block_msg) and the
get_events watchdog; profile advertises watchdog_timeout/timeslot
- new login-required scenario MAC and POST /invalidate-session so tests
can force a mid-session token loss
- the /stalker proxy route now forwards the token as a Bearer header and
wraps auth failures in the { payload } envelope, matching web-backend
Also moves extractMac into request-mac.ts: importing it from the
categories handler dragged the whole data generator into any consumer,
which broke unit tests on the workspace alias.
E2E: new stalker-auth.e2e.ts asserts handshake precedes get_profile
precedes content, that content requests carry the token while the
handshake does not, that the plain-text failure body is never rendered,
and that the client re-authenticates after the portal drops the session.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(mock): address CodeQL findings in the new portal auth code
Two genuine defects in the code this PR added:
- readBearerToken's /Bearer\s+(.*)$/ backtracks polynomially on
"bearer" followed by a long run of spaces; require the token to start
with a non-space character instead
- the /stalker proxy route read query params as strings without
narrowing, so a repeated key (?url=a&url=b) arrives as an array and
String.prototype.includes silently changes meaning
The remaining three alerts (missing rate limiting x2, sensitive data in
a GET query) are web-service hygiene rules aimed at internet-facing
services. The mock servers bind to localhost, serve fabricated data,
ship in no artifact, and deliberately mirror the real backend proxy's
token-in-query contract; a rate limiter would break the E2E suite that
hammers them. Exclude only those two apps from analysis via a documented
CodeQL config; every shipped path keeps full coverage.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(mock): tighten portal-auth fidelity per review
Review follow-up on #1324 (Greptile 2xP1, Codex 3xP2), all valid:
- adoptToken only accepts tokens the mock actually issued (or the
already-bound one). The stock server pins any presented Bearer —
handshake is stateless there — but a fixture that does the same
cannot catch a client with a broken token pipeline; documented as a
deliberate strictness divergence.
- /invalidate-session clears tokens but keeps pinned device identity:
losing a token never unpins device_id on a real portal, so changed
identity after re-auth must still hit the device-conflict branch.
- The login-required scenario gates on actual do_auth completion
instead of auth_second_step: the app sends auth_second_step=1 on its
very first get_profile, so the parameter check was trivially
bypassed and the status-2 flow never exercised. do_auth is now the
faithful boolean step (non-empty credentials -> {js:true}, recorded;
empty -> {js:false}).
- /server/load.php — the second URL shape isFullStalkerPortal
recognizes — is now served and enforced, directly and through the
/stalker proxy predicate, so full-portal tests cannot silently fall
into the tolerant branch.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(stalker): prove content actually reloads after re-authentication
Review follow-up on #1324 (Codex P2, valid — the "passes for the wrong
reason" class): the re-auth test only polled for a fresh handshake and
a negative body-text assertion, both of which pass even if the original
content request is never replayed or stays unauthorized. Capture the
content token from the initial import, then assert a post-invalidation
CONTENT request goes out under a DIFFERENT token and that the ITV
categories actually render — the mock only answers content for an
adopted token, so this proves the new token round-tripped through
get_profile. Verified against a live mock that the token genuinely
rotates (old token -> "Authorization failed.", new token -> content).
Also documents the second Codex P2: the mock is deliberately strict on
/server/load.php (a real portal enforces auth there); the import dialog
vs session predicate divergence is a separate app bug the strict
endpoint will let a later PR cover.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(stalker): serialize the portal specs and bind mocks to loopback
Review follow-up on #1324 (Codex, 4xP2):
- Parallel-reset race: under the workspace `fullyParallel` preset the new
auth file ran concurrently with stalker.e2e.ts against one shared mock
process, and each `beforeEach` wiped global state (sessions, favorites)
mid-assertion in the other. Reproduced locally: both suites green in
isolation, two failures when run together. Merged the auth tests into
stalker.e2e.ts and pinned the file to `mode: 'serial'`, which also
removes the pre-existing race between that file's own tests. 19/19
green across three consecutive runs.
- Watchdog was recorded but never asserted, so the suite would stay green
if the full-portal workflow stopped pinging or dropped its token —
`sendWatchdogPing` swallows failures. Now polls for an authenticated
`get_events`.
- Both mock servers listened on every interface (stalker: `listen(PORT)`
with no host; xtream: an explicit `0.0.0.0` default), which made the
CodeQL exclusion's "binds to localhost" rationale untrue. Both now
default to `127.0.0.1` with a `HOST` opt-in, and the config comment
states plainly what the directory-wide ignore trades away.
- Documented that the login-required scenario is HTTP-level only for now:
the client's `do_auth` path is dormant and sends empty credentials, so
the fixture is waiting on that client-side work rather than claiming
end-to-end coverage.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(stalker): force a real auth failure before asserting it stays hidden
Review follow-up on #1324 (Codex 2xP2 + 1xP3), all valid:
- The "never surfaces the plain-text auth failure" test only performed a
successful import, so its negative body assertions were vacuous. It now
imports with a MAC outside the Infomir OUI: the strict endpoint answers
get_profile with a bare {status:1}, no token is ever adopted, and every
content request keeps returning "Authorization failed." Unlike an
invalidated session this cannot be repaired by the client retry, so the
failure is genuinely observed (asserted directly against the proxy) and
only then checked for not leaking into the UI.
- docs/architecture/xtream-mock-server.md still documented the wildcard
bind that 4b31f7167 replaced with a loopback default; it now states the
new default and the HOST=0.0.0.0 opt-in needed for phone/STB/container.
- Removed a dangling "Known app-side gap: the" fragment left in the
stalker mock README.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(mock): scope /reset by MAC so parallel specs stop wiping each other
The re-authentication test passed locally but failed all three CI
attempts: no request carried a token, because self-hosted.e2e.ts issues
a GLOBAL `POST /reset` against the same mock from a parallel Playwright
worker, destroying the session mid-import. Running only stalker.e2e.ts
locally never triggered it.
Serializing within one file (4b31f7167) could not fix this — the
interference is between files. Mock state is per-MAC, so `/reset` now
accepts `?macAddress=` and clears only that MAC's data, favorites,
session and watchdog counters; the unscoped form is kept for callers
that own the whole server. Both spec files now reset only the MACs they
own, so no worker can disturb another.
Verified: a scoped reset of one MAC leaves another MAC's session intact
(and its own dies), and stalker.e2e.ts + self-hosted.e2e.ts run together
23/23 green — the combination that reproduced the CI failure.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(e2e): scope the last global Stalker reset in sources-pwa helpers
Completes 3a93fef0f: that commit scoped self-hosted.e2e.ts but missed
resetPwaMockServers, which still wiped the whole Stalker fixture from a
third spec file. Scope it to the two MACs this suite owns.
The auth tests use dedicated MACs no sibling touches, so portal sessions
— the fragile state — can no longer be cleared by a parallel worker.
Content MACs still overlap between files, which is harmless: that data is
regenerated deterministically from the same seed.
Verified with the full interfering set running together:
stalker.e2e.ts + self-hosted.e2e.ts + sources-pwa.e2e.ts, 26/26 green.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(stalker): await the first authenticated content request
The re-auth test kept failing on CI (3/3 attempts) with an undefined
token while passing locally. My earlier diagnosis — a sibling spec's
global /reset — was wrong: the failure survived the scoped-reset fix.
Real cause is a race in the test itself. `addFullStalkerPortal` only
awaits the route change, so on a slower runner the first authenticated
content request has not been recorded yet when the token is read; the
sibling test that passes happens to await `.category-item` first. Poll
for a content request carrying a token before capturing it.
The scoped-reset work stands on its own merits (cross-file resets were
a real hazard), it just was not what broke this test.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(stalker): drop serial mode, batch resets, cover the auth handlers
Review round on a44f8135f plus a stability regression I introduced.
Codex, both valid:
- The proxy route stripped `token` from the forwarded query, so
`handshake` never saw a presented token and the idempotent-handshake
behaviour I documented was unreachable through the PWA path. The real
backend forwards every param except `targetId` *and* sets the header;
match it. Verified through the proxy: re-handshake now returns the
same token with not_valid 0.
- The login-required scenario had no committed test, so the README claim
was unbacked. Added auth-handlers.spec.ts (status 2 -> do_auth ->
profile, MAC-format rejection, device conflict, idempotent handshake,
watchdog). Handlers are called directly because the dispatcher pulls in
the faker-based generator, which this project's Jest cannot transform.
- Sibling suites now own disjoint MACs (00:1A:79:5F:*) instead of
sharing the Stalker suite's, so no reset can reach another suite's
state at all.
Stability: a baseline run of master passed 23/23 first try while this
branch failed a different test each run, so the flakiness was mine.
`mode: 'serial'` was a stand-in for isolation that per-MAC scoping now
provides properly, and it amplified every flake by aborting the rest of
the file; removed. `beforeEach` also fired seven sequential resets — the
endpoint now accepts repeated `macAddress` params so a suite clears all
of its MACs in one request. Added a retrying POST helper after an
ECONNRESET on a control call.
Verified: three consecutive runs of stalker + self-hosted + sources-pwa,
26/26 each; 28 mock unit tests; lint clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(stalker): restore serial mode for the shared-scenario file
Review follow-up (Codex P2), valid: the previous commit removed
`mode: 'serial'` while every `beforeEach` still resets all OWNED_MACS,
so under fullyParallel one test in this file could clear another's data
or session mid-run.
Of the two suggested fixes, serialize rather than give each test its own
MAC: the tests here are written against scenario fixtures (default,
minimal, embedded-series) whose shapes the assertions encode, so a MAC
per test would mean inventing a scenario per test and rewriting
pre-existing assertions. Cross-file isolation stays with the disjoint
sibling MAC range, which is what serial was wrongly standing in for
before.
The header now states both levels explicitly so the next reader does not
undo one of them.
Verified: three consecutive runs of stalker + self-hosted + sources-pwa,
26/26 each.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
204 lines
11 KiB
Markdown
204 lines
11 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` (tolerant panel-style endpoint)
|
||
or `http://localhost:3210/stalker_portal/server/load.php` (canonical Ministra
|
||
endpoint — see [Two endpoints](#two-endpoints-tolerant-vs-strict) below)
|
||
- **MAC Address**: one of the predefined scenarios below (or any MAC for auto-generated data)
|
||
|
||
## Two endpoints: tolerant vs strict
|
||
|
||
The same actions are served at two paths with deliberately different strictness,
|
||
because the app treats them differently: a URL containing `/stalker_portal` is
|
||
imported as a **full portal** (handshake + token + watchdog), anything else as a
|
||
**simple portal** (no authentication at all).
|
||
|
||
| Path | Behaviour |
|
||
|---|---|
|
||
| `/portal.php` | Tolerant. Ignores the Bearer token and the MAC format, like most reseller panels in the wild. |
|
||
| `/stalker_portal/server/load.php` | Strict. Enforces the token and the MAC format exactly like the real middleware. |
|
||
| `/server/load.php` | Strict. The second full-portal URL shape the app recognizes; enforced identically. |
|
||
|
||
> **Known app inconsistency:** `StalkerSessionService.isFullStalkerPortal`
|
||
> classifies `/server/load.php` as a full portal, but the import dialog's
|
||
> `isFullStalkerPortalUrl` checks only for `/stalker_portal`, so importing a bare
|
||
> `…/server/load.php` URL persists `isFullStalkerPortal: false` and the app skips
|
||
> the handshake. The mock is deliberately faithful to a **real** portal here
|
||
> (that path enforces auth), which makes it the right fixture to drive the
|
||
> upcoming fix that unifies those two predicates. Until then, import full
|
||
> portals through a `/stalker_portal/...` URL.
|
||
|
||
The strict endpoint reproduces the parts of Stalker 4.9.35 that a client can
|
||
actually get wrong:
|
||
|
||
- Every action except `handshake`, `get_profile`, `get_localization` and
|
||
`do_auth` requires `Authorization: Bearer <token>`.
|
||
- A token only counts once `get_profile` has adopted it — a handshake alone is
|
||
not a session. Adoption is deliberately stricter than the stock server:
|
||
only tokens the mock actually issued (or the already-bound one) are
|
||
accepted, so a client with a broken token pipeline fails loudly.
|
||
- Auth failures come back as **HTTP 200 with a plain-text body**
|
||
(`Authorization failed.`, `Unauthorized request.`), never a 401/403. Clients
|
||
that only check status codes will silently render nothing.
|
||
- The handshake is **idempotent**: presenting the MAC's current token returns
|
||
that same token instead of rotating it.
|
||
- `device_id`/`device_id2` are pinned to the MAC on first non-empty value; any
|
||
later change — including sending them empty again — is a permanent
|
||
`device conflict` with the "Your STB is damaged." block message.
|
||
- `signature`, `metrics` and `prehash` are accepted and ignored, exactly as the
|
||
stock server does.
|
||
- The MAC must match the Infomir OUI format (`00:1A:79:XX:XX:XX`) or
|
||
`get_profile` answers with a bare `{ status: 1 }`.
|
||
|
||
## 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 |
|
||
| `00:1A:79:00:00:08` | **login-required** | `get_profile` answers `status: 2` until the client completes `do_auth` with non-empty credentials. The app cannot finish this flow yet (its `do_auth` path is dormant and sends empty credentials), so the scenario is exercised at the HTTP level only — it exists to receive the upcoming client-side `do_auth` work |
|
||
| `<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, favorites, sessions and watchdog counters (useful between test runs) |
|
||
| `/invalidate-session?macAddress=<mac>` | `POST` | Drop that MAC's tokens so the next portal call fails with `Authorization failed.` — lets tests assert the client re-handshakes and retries. Pinned device identity survives, as on a real portal |
|
||
|
||
## API Coverage
|
||
|
||
All endpoints are served at `GET /portal.php?action=<action>&...` matching the real Stalker protocol:
|
||
|
||
| Action | Description |
|
||
|---|---|
|
||
| `handshake` | Issues the access token (idempotent) plus the 5.x `random` nonce and `not_valid` flag |
|
||
| `get_profile` | Turns the handshake token into a session; enforces device-id pinning, and on the strict endpoint the MAC format |
|
||
| `get_events` | Watchdog ping; records the call and returns an empty event set (never affects authorization, as on a real portal) |
|
||
| `do_auth` | Boolean login step: `{js:true}` for non-empty credentials (recorded for the login-required scenario), `{js:false}` otherwise |
|
||
| `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
|
||
```
|