01What it does
| Endpoint | Behaviour |
|---|---|
POST /events | Validates a sensor event and acknowledges it only after PostgreSQL commits |
GET /devices/{id}/health | Latest heartbeat and five-minute availability |
GET /rooms/{id}/occupancy | Current presence and occupancy over 1m, 5m or 1h windows |
GET /alarms?after_id=&wait= | Long-polls for committed alarms, resumable by cursor |
/healthz /readyz /metrics | Process health, database readiness, Prometheus metrics |
02Reliability decisions
Idempotent ingestion
An exact retry returns success with duplicate: true. Reusing the same device, sequence and timestamp with different content returns 409, so a conflicting replay can't silently overwrite history.
Backpressure instead of falling over
Ordinary events go through bounded queues and batched writes. If a request waits four seconds for queue space, it gets 503 with Retry-After.
Falls get their own queue
A backlog of heartbeats can't fill the queue that fall events need.
A fall and its alarm commit together
Repeated reports with the same device, room, timestamp and confidence produce one alarm, not several.
A feed consumers can resume
The live feed follows commit order, and consumers save next_cursor and pass it back after reconnecting. The trade-off: a fall replayed by an offline sensor can appear after a newer fall from the same room.
Occupancy that tolerates replays
Replayed events correct the window using their original timestamps, and time before the first known state is reported as unknown rather than guessed.
03Testing & load
- Go integration tests against real PostgreSQL. Each creates and removes its own schema and runs with the race detector.
- The challenge's upstream smoke evaluator compares its generated falls with every alarm in the database.
- A custom load tool reports scheduled requests, requests actually sent, durable acknowledgements and alarm latency separately, so the numbers can't flatter themselves.
In one five-minute run on a 9-CPU host shared by the service, PostgreSQL and the load tool, every event scheduled across two 30-second bursts at 50,000 events/s was acknowledged. In two further runs the load tool itself only managed to send 90% and 96% of the schedule, but every event it sent was acknowledged and persisted. Repeatable capacity at that rate remains unverified.