HydraIssues

hydracluster: add streaming monitor API endpoint to detect body assignment conflicts
open feature Project: hydracluster Reporter: 17 May 2026 12:03

Description

## Problem

Before starting a stream (e.g. via test or via kiosk assignment), there is no single API call to check whether the target body already has another head streaming to it, or whether a head has a stale assignment pointing to a body that is now serving a different head. This makes it easy to create silent conflicts: two heads assigned to the same body at the same time.

Discovered during mic relay validation 2026-05-17: `turbo-pancake-76` (bxl1/cloud-seven, self-service) had a stale `stream_url` pointing to `cosmic-pretzel-98` (10.10.100.12) while `cheeky-cactus-86` (bxl1-test) was actively streaming to the same body.

Additionally, `PUT /api/v1/heads/{id}` with `{"stream":{}}` does not clear `stream_url` / `stream_url_lan` fields (only `stream_app_id` is cleared), leaving a partial stale assignment that can confuse monitoring.

## Requested

1. `GET /api/v1/streaming-monitor` — returns all heads with a non-empty `stream_url` grouped by body IP. Flags any body IP that has more than one head assigned. Fields: `body_ip`, `heads: [{id, name, district, venue, app, status}]`, `conflict: bool`.

2. Fix `PUT /api/v1/heads/{id}` with `stream: {}` to also clear `stream_url` and `stream_url_lan` (not just `stream_app_id`).

## Use case

Before assigning a head to a body in tests or scripts, call `GET /api/v1/streaming-monitor` to confirm the target body is free. Also useful as a pre-flight check before major events.