# 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.