XC_VM/docs/xc_fanout.md

# `xc_fanout` — the Go live-delivery daemon (why it exists)

`xc_fanout` is a small, native Go daemon that XC_VM uses to deliver **live**
streams to viewers. This page explains *why* it exists and *how the panel talks
to it*. The decision records are ADR 0001/0002/0003; this is the plain-language
overview.

The daemon's **source** lives in its own repo, **`XC_VM_Fanout`** (`GIT_REPO_FANOUT`),
and its compiled binaries ship as **GitHub Release assets** (never committed to a
tree). It is a single static binary per architecture and is never bundled into the
panel/LB archive.

---

## The problem it solves

Historically PHP was **in the byte path** of every live viewer:

- **Proxy streams** — `Public/stream/live.php` ran a `socket_read → echo → flush`
  loop for the whole session, one PHP-FPM worker pinned per viewer.
- **Non-proxy streams** — `live.php` chase-read the HLS `.ts` segments off tmpfs
  and echoed them as a continuous MPEG-TS, again one worker per viewer.

We measured it (ADR 0001, P0): **~1 PHP-FPM worker + ~25 MB of RAM per viewer.**
That linear RAM law — not `pm.max_children` — is the real ~400-concurrent
ceiling. A 4 GB box walls at ~55 viewers on RAM alone. Every viewer is a blocked,
expensive worker instead of a cheap connection.

The whole redesign is about **getting PHP out of the byte path** so a viewer
becomes a cheap nginx→daemon connection. The daemon is what holds those
connections.

---

## What the daemon does

One process serves many streams. Per stream it holds **one** ingest and fans it
out to many viewers, plus segments the same feed into HLS **entirely in RAM**
(no tmpfs, no files):

- **Live TS fan-out** — `GET /live/<id>`: PAT/PMT + keyframe-aware ring buffer,
  each new viewer gets a clean-join snapshot then the live tail; slow viewers are
  dropped, never blocking the producer or others.
- **In-RAM HLS** — `GET /hls/<id>/index.m3u8` and `/hls/<id>/<seq>.ts`: cuts
  segments at video keyframes with PTS-accurate `EXTINF`, sliding window; can
  AES-128-CBC **encrypt** segments (matching the panel's `encrypt_hls`).
- **Two ways to be fed**:
  - **pull** (proxy streams) — the daemon connects to the source itself
    (direct `video/mp2t`, or spawns ffmpeg to remux other inputs). Replaces
    `Cli/Commands/ProxyCommand.php`.
  - **push / ingest** (non-proxy & LLOD) — the stream's existing producer writes
    MPEG-TS into a per-stream unix socket the daemon listens on. The producer's
    real work (transcode, logo, profiles) stays where it was.
- **On-demand lifecycle** — starts a puller on the first viewer, stops it after a
  grace once the last leaves; HLS requests keep it alive too.

Two unix-socket HTTP surfaces: a **client** surface nginx proxies viewers to, and
a **control** surface only the panel (PHP) talks to.

---

## What the daemon does NOT do

- **It does not replace ffmpeg.** For non-proxy streams the per-stream ffmpeg
  keeps doing the real work (transcode, logo overlay, profiles, timeshift
  recording). The daemon only takes over *delivery*.
- **It does not do auth.** PHP still authenticates every request (tokens, line
  limits, IP match, connection tracking). The daemon only moves bytes.
- **It does not touch the database.** All DB writes stay in PHP — this keeps LB
  nodes privilege-free.
- **Live only.** VOD, series, timeshift/archive are random-access (seek /
  byte-range) over files, not a shared live tail — they keep their own path.

---

## How the panel talks to it

The switch is the **daemon's reachability**, not a settings flag: `live.php`
routes a stream to the daemon when its control socket is present and the stream
is being served; otherwise it runs the legacy path. **Stopping the daemon is the
rollback** — every stream falls back automatically, per node.

Delivery uses the same `X-Accel-Redirect` pattern as P1 HLS: PHP authenticates,
then hands the byte path to nginx, which proxies to the daemon. The FPM worker is
freed the instant PHP returns.

**Client surface** (nginx → daemon, via internal `X-Accel` locations):

| Request | Daemon route |
|---|---|
| live TS | `X-Accel-Redirect: /xc_fanout/<id>?c=<uuid>` → `/live/<id>` |
| HLS segment | `X-Accel-Redirect: /xc_fanout_hls/<id>_<seq>` → `/hls/<id>/<seq>.ts` |
| HLS playlist | PHP fetches `/hls/<id>/index.m3u8`, tokenizes the segment URLs |

**Control surface** (PHP → daemon, `FanoutClient` over the control unix socket):

| Call | Purpose |
|---|---|
| `PUT /streams/<id>` | register a proxy source (urls, ua, proxy, cookie, ffmpeg, key/iv) |
| `PUT /ingest/<id>` | create the push ingest socket for a non-proxy/LLOD producer (+ key/iv) |
| `POST /probe/<id>?wait=` | prewarm + wait for first data → off-air detection |
| `GET /streams/<id>` | status (`running`, `has_data`, `since_data_ms`) |
| `GET /connections` | active live-TS viewer uuids (for `fanout_sync` reconcile) |
| `DELETE /streams/<id>` | stop / drop the stream |

`FanoutClient` (`src/Streaming/Fanout/FanoutClient.php`) is the PHP client.
The **`fanout_sync`** daemon (`console.php fanout_sync`) reconciles connection
records against `GET /connections` so a viewer's disconnect frees their line's
slot (under X-Accel, PHP never sees the disconnect itself).

---

## Where it runs

Supervised from `src/service` (a keepalive loop restarts it on crash). Its
sockets live next to the binary in the app bin tree
(`bin/xc_fanout/sockets/{http,control}.sock`), mirroring the php-fpm sockets
layout nginx already reaches over `unix:`. Installed on MAIN first; LB rollout is
a later phase.

### Install / update

The binary is fetched from the latest `XC_VM_Fanout` release, like the other
distributed binaries:

```
console.php fanout_binary          # install or update to the latest release
console.php fanout_binary force     # reinstall the current version
```

`FanoutBinaryCommand` reads the installed version straight from the binary
(`xc_fanout -version`), compares it to the latest release tag, and — when they
differ — downloads the arch-matched asset (`xc_fanout-linux-<arch>`), verifies its
SHA-256 against the release's `SHA256SUMS`, installs it atomically, and kills the
running daemon so the `service` keepalive respawns it with the new binary.

See `docs/adr/0001-*`, `0002-*`, `0003-*` for the full design and the phased
cutover plan.