Skip to content

Latest commit

 

History

History
18 lines (13 loc) · 1.95 KB

File metadata and controls

18 lines (13 loc) · 1.95 KB

src/api/

FastAPI HTTP surface for the harness scaffold. Owns request handling, route registration, lifespan hooks, and the in-memory session store. Imports from src/observability/ (instrumentation), src/models/ (Pydantic contracts) — never the other way around (enforced by import-linter).

Key interfaces

  • main.app — the FastAPI() instance with CORS middleware, OTel auto-instrumentation, and the v1 router mounted. Exposed for uvicorn src.api.main:app and the FastAPI TestClient fixtures in tests/conftest.py.
  • main.lifespan(app) — async context manager that runs setup_tracingsetup_logginginstrument_httpxinstrument_fastapi once on startup, then constructs the SessionStore. Single point of "what is process-globally configured?"
  • routes.routerAPIRouter(prefix="/api/v1"). Every route a real client should hit lives here; un-versioned routes live on app directly (only the FastAPI auto-generated docs at /docs and /redoc qualify).
  • routes.healthGET /api/v1/healthHealthResponse (status + importlib.metadata.version-derived build version).
  • routes.echoGET /api/v1/echo?msg=...EchoResponse. Demonstrates the request/response contract pattern that real domain endpoints follow.
  • sessions.SessionStore — single-process in-memory dict mapping session id → conversation history. Plumbed onto app.state.session_store in lifespan; replace with a Redis or DB-backed implementation for multi-process deployments.

Conventions

  • Every route returns a StrictModel subclass — never a raw dict. The extra="forbid" config makes typos and renamed fields fail at construction, not three calls deep.
  • Routes are versioned under /api/v1/. Adding a v2 endpoint = a new router, never a breaking change to v1.
  • The CORS policy is wide-open in the scaffold so the Vite dev server proxy works on first run; tighten via config when a real auth layer arrives.