mirror of
https://gitlab.com/vyla-entertainment/documentation.git
synced 2026-11-14 22:47:26 -05:00
108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# Operations, Health & Diagnostics
|
|
|
|
<p class="page-description">Monitoring, cluster diagnostics, live health probing, and testing endpoints in Stream API.</p>
|
|
|
|
## The Health Check Endpoint: `GET /health`
|
|
|
|
Stream API provides an automated health probe endpoint that executes live responsiveness checks across all registered scraper modules.
|
|
|
|
```http
|
|
GET /health HTTP/1.1
|
|
Host: your-api.example.com
|
|
```
|
|
|
|
### Response Status Codes
|
|
- **`200 OK`**: All active provider sources passed their health probes.
|
|
- **`207 Multi-Status`**: One or more providers failed their probes (degraded state), but the API gateway remains functional.
|
|
|
|
### Example 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-14T20:30:00.000Z",
|
|
"tmdb": true,
|
|
"cache": 142,
|
|
"probe_id": 155,
|
|
"sources": {
|
|
"vidlink": { "ok": true, "ms": 420 },
|
|
"vixsrc": { "ok": true, "ms": 610 },
|
|
"cinecat": { "ok": true, "ms": 890 },
|
|
"movy": { "ok": false, "ms": null }
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Response Fields
|
|
| Field | Type | Description |
|
|
| :--- | :--- | :--- |
|
|
| `status` | `string` | Overall system state (`"ok"` or `"degraded"`). |
|
|
| `timestamp` | `string` | ISO 8601 timestamp of probe completion. |
|
|
| `tmdb` | `boolean` | `true` if `TMDB_API_KEY` is configured and valid in the environment. |
|
|
| `cache` | `integer` | Current number of active cached titles in the primary LRU cache. |
|
|
| `probe_id` | `integer` | The standard TMDB ID used to probe source responsiveness. |
|
|
| `sources` | `object` | Dictionary of per-source availability (`ok`) and roundtrip latency in milliseconds (`ms`). |
|
|
|
|
---
|
|
|
|
## Direct Source Testing: `GET /test/:source`
|
|
|
|
To test an individual scraper directly without querying all 60 providers:
|
|
|
|
```http
|
|
GET /test/vidlink?id=155 HTTP/1.1
|
|
```
|
|
|
|
For television episodes, pass season and episode query parameters:
|
|
```http
|
|
GET /test/vixsrc?id=1396&s=1&e=1 HTTP/1.1
|
|
```
|
|
|
|
### Response
|
|
Returns the raw resolved candidate object directly from the provider scraper:
|
|
|
|
```json
|
|
{
|
|
"source": "vidlink",
|
|
"url": "https://upstream.example.com/playlist.m3u8",
|
|
"quality": "1080p",
|
|
"type": "hls",
|
|
"server": "vidlink-cf"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Deep Debug Route: `GET /debug/:source`
|
|
|
|
When `ENABLE_DEBUG_ROUTE=true` is set in your environment variables, Stream API exposes a comprehensive diagnostic route:
|
|
|
|
```http
|
|
GET /debug/vidlink?id=155 HTTP/1.1
|
|
```
|
|
|
|
### Diagnostic Output Includes:
|
|
1. **Raw Scraper Payload**: Unmodified JSON or HTML received from the upstream host.
|
|
2. **Extraction Timings**: Milliseconds spent parsing DOM, solving tokens, and resolving URLs.
|
|
3. **Phase 1 Verification**: Status code, response headers, and latency of the `HEAD` request.
|
|
4. **Phase 2 Verification**: First 500 bytes of the master M3U8 playlist and test chunk fetch status.
|
|
5. **Rewritten URLs**: Preview of how chunk URIs will be rewritten by the proxy.
|
|
|
|
:::callout-warning
|
|
**Security Note**: Keep `ENABLE_DEBUG_ROUTE=false` in public production environments to avoid leaking internal scraper tokens or upstream endpoints.
|
|
:::
|
|
|
|
---
|
|
|
|
## Cluster & Cache Architecture
|
|
|
|
### Primary Supervisor & Worker Pool Architecture
|
|
- **Central In-Memory Cache**: Holds up to 1,500 verified title entries in a shared LRU table with a 5-minute TTL.
|
|
- **Periodic Pruner**: Runs every 30 seconds to clean expired keys and enforce memory ceilings.
|
|
- **Worker Lifecycle Supervisor**: Spawns and supervises $N$ worker processes matching CPU core count, automatically restarting terminated workers.
|
|
- **IPC Message Dispatcher**: Routes `cache:get` and `cache:set` messages between worker threads and the primary process.
|
|
|
|
1. **IPC Cache Synchronization**: When a worker resolves a title, it sends a `cache:set` message to the primary process. When another worker receives a request for the same title, it sends a `cache:get` message and receives an instant `cache:hit` without re-scraping upstream hosts.
|
|
2. **Cache Pruning**: The primary process evicts stale items older than 300,000ms (5 minutes). If total cache size exceeds 1,500 items, the oldest entries are evicted immediately.
|
|
3. **Worker Auto-Restart**: If a worker process exits unexpectedly or exceeds memory limits, the primary cluster supervisor automatically spawns a replacement worker.
|