mirage-fleet

Central ingest API + database for running multiple mirage-core sensor nodes and seeing their data in one place. See CLAUDE.md for the full context and DECISIONS.md for why it's shaped this way.

What's here

• POST /v1/nodes/register — mint a node identity (UUID) and API key.
• POST /v1/ingest/sessions — a node pushes one session's data (its own session.Session JSON, keyed by session_id). Idempotent: retried pushes overwrite rather than duplicate.
• POST /v1/ingest/heartbeat — liveness ping, mirrors mirage-core's local sensor_heartbeats fleet-wide.

Both ingest routes require Authorization: Bearer <api_key>. The key alone determines which node a write belongs to — nothing in the request body is trusted to say so.

Run it

cp .env.example .env   # set a real DB_PASSWORD
docker compose up -d

Register a node:

curl -s -X POST localhost:8090/v1/nodes/register \
  -d '{"label":"nuremberg-01"}'

Push a session (from whatever mirage-core patch ends up doing this):

curl -s -X POST localhost:8090/v1/ingest/sessions \
  -H "Authorization: Bearer <api_key>" \
  -d '{"session_id":"...", ...rest of session.Session...}'

Backlog

• /v1/nodes/register is currently unauthenticated — anyone who can reach it can mint a node identity. Needs an admin credential in front of it before this leaves a trusted network.
• mirage-core itself doesn't push to this API yet — nothing here changes mirage-core's behavior until that patch lands there.
• No dashboard. Reads against the central DB (per-node and consolidated) are for whatever queries this later — likely mirage-web's /console gaining a node picker, per CLAUDE.md.
• Delivery is currently "node retries/queues locally, ingest API just upserts." If production shows frequent ingest failures, revisit with an actual queue/stream in front of ingestion (see DECISIONS.md).