Files
documentation/stream-api/reference/operations.md
2026-11-15 17:34:41 -08:00

128 lines
3.5 KiB
Markdown

# Operations, Health & Diagnostics
<p class="page-description">Monitoring, cluster diagnostics, live health probing, and testing endpoints in Stream API.</p>
## Health Check: `GET /health`
Runs responsiveness checks across registered scraper modules. Both `/health` and `/api/health` are supported.
```http
GET /health HTTP/1.1
Host: api.vyla.cc
```
### Status Codes
- `200 OK`: All active scrapers passed their health probes.
- `207 Multi-Status`: One or more providers failed (degraded state), but the gateway is functional.
### Response Payload
```json
{
"note": "This is a health check endpoint. This is extremely unreliable, be sure to test sources directly.",
"status": "ok",
"timestamp": "2026-11-15T12:00:00.000Z",
"sources": {
"vidlink": { "ok": true, "latency": 350 },
"vixsrc": { "ok": true, "latency": 480 },
"cinecat": { "ok": false, "latency": 15000 }
}
}
```
---
## Test Directory: `GET /test`
Calling `GET /test` or `GET /api/test` returns auto-generated test URLs for every registered source:
```http
GET /test HTTP/1.1
Host: api.vyla.cc
```
```json
{
"vidlink": {
"movie": "/api/test/155?source=vidlink",
"tv": "/api/test/1396?season=1&episode=1&source=vidlink"
},
"vixsrc": {
"movie": "/api/test/155?source=vixsrc",
"tv": "/api/test/1396?season=1&episode=1&source=vixsrc"
}
}
```
---
## Direct Source Testing: `GET /test/:tmdb_id`
Tests a single scraper directly without triggering all other providers. Supports `/test/:id` and `/api/test/:id`.
### Movie Test
```http
GET /api/test/155?source=vidlink HTTP/1.1
Host: api.vyla.cc
```
**Parameters:**
- `tmdb_id` *(path, required)* — Numeric TMDB ID (e.g. `155`).
- `source` *(query, required)* — Source key to test (e.g. `vidlink`).
### TV Episode Test
```http
GET /api/test/1396?season=1&episode=1&source=vidlink HTTP/1.1
Host: api.vyla.cc
```
**Parameters:**
- `tmdb_id` *(path, required)* — Numeric TMDB Series ID (e.g. `1396`).
- `source` *(query, required)* — Source key to test (e.g. `vidlink`).
- `season` or `s` *(query, required)* — Season number (e.g. `1`).
- `episode` or `e` *(query, required)* — Episode number (e.g. `1`).
### Response Example
```json
{
"source": "vidlink",
"ok": true,
"stream": {
"url": "https://api.vyla.cc/api?url=https%3A%2F%2Fupstream.example.com%2Fmaster.m3u8",
"quality": "1080p",
"type": "hls",
"server": "vidlink-cf"
}
}
```
---
## Deep Debug Route: `GET /debug/:tmdb_id`
Exposes diagnostic internals when `ENABLE_DEBUG_ROUTE=true` is enabled in `.env`:
```http
GET /api/debug/155?source=vidlink HTTP/1.1
Host: api.vyla.cc
```
**Diagnostics Returned:**
- Raw HTML and JSON payloads from upstream providers.
- Resolution latency and DOM parsing metrics.
- Upstream HTTP status codes and headers from probe checks.
- First 500 bytes of upstream playlist manifests.
- Rewritten proxy segment URLs.
:::callout-warning
Keep `ENABLE_DEBUG_ROUTE=false` in production to prevent leaking upstream tokens and API keys.
:::
---
## Cluster & Cache Architecture
- **In-Memory Cache**: Up to 1,500 entries stored in primary process memory with a 5-minute TTL (`CACHE_TTL`).
- **Pruning Timer**: Runs automatically every 30 seconds to purge expired entries and maintain cache boundaries.
- **Worker Management**: Cluster primary supervises worker processes, automatically respawning workers on process exit.
- **IPC Synchronization**: Workers communicate through `cache:get`, `cache:set`, and `cache:push` IPC messages for fast cross-process cache hits.