Spaces:
Running
Running
| # Producer metadata contract | |
| Every peer registers with `POST /send` `{"type": "setPeerStatus", "roles": [...], "meta": {...}}`. | |
| Central stores `meta` **verbatim** and forwards it unchanged to every | |
| owner-scoped surface: the SSE `list` / `peerStatusChanged` / | |
| `sessionStateChanged` frames, `GET /api/robot-status` and | |
| `GET /api/debug/peers`. Daemons may add fields at any time without a | |
| central change; clients must tolerate unknown keys. | |
| This page lists the few keys central *reads*. Anything not listed is | |
| opaque to the server. | |
| ## Keys interpreted by central | |
| | Key | Sent by | Server-side use | | |
| | --- | --- | --- | | |
| | `name` | producer, consumer | Producer: `robotName` in `/api/robot-status`. Consumer: reported as `activeApp` while it holds a session. Display only. | | |
| | `hardware_id` | producer (daemons >= v1.7.2) | Stable per-robot identity: a new registration with the same `hardware_id` under the same HF user evicts the older producer (last-writer-wins). Its presence also marks the daemon as heartbeat-capable, which opts it into the stale-producer sweep. | | |
| | `install_id` | producer (reserved) | Same dedup semantics as `hardware_id`, checked independently. Not emitted by any shipped daemon yet. | | |
| | `kind` | producer | Robot family, used **only** for the public per-kind counters (`/health` `producers_by_kind`, status page). See below. | | |
| | `robot_type` | producer | Alias for `kind`, consulted only when `kind` is absent or empty. | | |
| Keys such as `transport`, `release` or `api_version` are passed through | |
| untouched and never interpreted. | |
| ## `kind` | |
| - **Missing means Reachy Mini.** Reachy Mini daemons send no `kind` at | |
| all (their meta is `{name, transport, hardware_id}`), so when neither | |
| `kind` nor `robot_type` holds a non-blank string the producer | |
| classifies as `reachy_mini`. A `kind` that is absent, `null`, blank or | |
| not a string falls through to `robot_type`. | |
| - **Known values:** `reachy_mini`, `microduck`. Matching is | |
| case-insensitive and ignores every character outside `a-z0-9`, so | |
| `Micro-Duck`, `micro duck`, `microduck`, `Reachy Mini`, `reachy-mini` | |
| and `reachymini` all resolve to their canonical kind. A raw value | |
| longer than 64 characters is classified as `other` without any | |
| normalisation. | |
| - **`meta` must be a JSON object.** A `setPeerStatus` whose `meta` is | |
| not an object is rejected with HTTP 400 and leaves the previously | |
| registered `meta` untouched. | |
| - **Anything else counts as `other`** on the public counters. `kind` is | |
| untrusted input (any authenticated HF user can send any meta), so the | |
| public surfaces only ever expose the fixed key set | |
| `{reachy_mini, microduck, other}` - an unknown value can bump the | |
| `other` counter and nothing more. The status page labels for those | |
| keys are server-side constants; no meta string is ever rendered there. | |
| - **The raw value is still forwarded verbatim** to the owner's own | |
| listeners and `/api/*` endpoints. Classification is a read-only view | |
| for the public counters; it never rewrites `meta`. | |
| Adding a robot family is a one-line change to `KNOWN_ROBOT_KINDS` (and a | |
| label in `ROBOT_KIND_LABELS`) in `app.py`; the tests in | |
| `test_robot_kind.py` and `test_routes.py` pin the behaviour above. | |
| ## Public counters (`GET /health`) | |
| ```json | |
| { | |
| "status": "healthy", | |
| "peers": 3, | |
| "producers": 2, | |
| "sessions": 1, | |
| "producers_by_kind": {"reachy_mini": 1, "microduck": 1, "other": 0}, | |
| "started_at": "2026-09-16T08:00:00Z", | |
| "uptime_seconds": 12345 | |
| } | |
| ``` | |
| `peers`, `producers` and `producers_by_kind` count **connected** peers | |
| only. `started_at` / `uptime_seconds` are wall-clock and exist so an | |
| operator can tell a fresh redeploy (all counters reset) from a quiet | |
| fleet. Both `/` and `/health` are served with `Cache-Control: no-store`. | |