Cursor rule

1---
2description: FastAPI route conventions for the events API
3globs: app/api/**/*.py
4alwaysApply: false
5---
6 
7# API Route Conventions
8 
9- Routes are thin: validate input, call a service/store, shape the response.
10  No persistence, aggregation, or business logic in a handler.
11- Pull dependencies off `app.state` via the `Depends(_helper)` pattern (e.g.
12  `_mongo`, `_es`, `_cache`, `_ingestion`); don't reach into globals.
13- The events routes declare a Pydantic `response_model` from
14  `app/api/schemas.py`; `/health` (a status-code-driven `JSONResponse`) and
15  `/metrics` (a loose ops snapshot) are intentionally exempt. Nullable fields are
16  **always present** in the response (return explicit `null`, e.g. `total`,
17  `bucket`, `computed_at`) for a stable shape.
18 
19# Error → status mapping (be consistent)
20 
21Stores raise native exceptions; the route catches and maps them. Log at the
22boundary with the exception type, then raise `HTTPException`.
23 
24| Condition | Status |
25|---|---|
26| Mongo (source of truth) unavailable | `503` |
27| Elasticsearch (derived) unavailable | `502` |
28| Queue full (backpressure) | `429` |
29| Service shutting down | `503` |
30 
31```python
32try:
33    events, has_more, total = await mongo.find_events(...)
34except PyMongoError as exc:
35    logger.error("Mongo query failed (%s): %s", type(exc).__name__, exc)
36    raise HTTPException(status_code=503, detail="Event store temporarily unavailable")
37```
38