feat(api): error contract, request id, and test harness (#2)

* feat(errors): add AppError and error envelope builder

* feat(api): register error handlers and request id middleware

* test: add conftest harness with test database safety check

app/errors.py

@@ -0,0 +1,30 @@
+from typing import Any
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+class AppError(Exception):
+    def __init__(self, status_code: int, code: str, message: str, details: list[dict] | None = None, headers: dict | None = None):
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.details = details or []
+        self.headers = headers
+
+def error_response(request: Request, status_code: int, code: str, message: str, details: list[dict] | None = None, headers: dict | None = None) -> JSONResponse:
+    request_id = getattr(request.state, "request_id", "unknown")
+    
+    envelope = {
+        "error": {
+            "code": code,
+            "message": message,
+            "status": status_code,
+            "request_id": request_id,
+            "details": details or []
+        }
+    }
+    
+    return JSONResponse(
+        status_code=status_code,
+        content=envelope,
+        headers=headers
+    )

app/main.py

@@ -1,5 +1,11 @@
-from fastapi import FastAPI
+import uuid
+import logging
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from app.errors import AppError, error_response
 
+logger = logging.getLogger("uvicorn.error")
 
 def create_app() -> FastAPI:
     app = FastAPI(
@@ -9,11 +15,62 @@ def create_app() -> FastAPI:
         redoc_url=None,
     )
 
+    # 1. Catch-all middleware (must be inside Request-ID)
+    @app.middleware("http")
+    async def catch_unhandled(request: Request, call_next):
+        try:
+            return await call_next(request)
+        except Exception:
+            logger.exception("unhandled error", extra={"request_id": getattr(request.state, "request_id", "unknown")})
+            return error_response(request, 500, "INTERNAL_ERROR", "Unexpected server error.")
+
+    # 2. Request-ID middleware
+    @app.middleware("http")
+    async def add_request_id(request: Request, call_next):
+        request.state.request_id = str(uuid.uuid4())
+        response = await call_next(request)
+        response.headers["X-Request-ID"] = request.state.request_id
+        return response
+
+    # 3. Exception Handlers
+    @app.exception_handler(AppError)
+    async def app_error_handler(request: Request, exc: AppError):
+        return error_response(request, exc.status_code, exc.code, exc.message, exc.details, exc.headers)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_error_handler(request: Request, exc: RequestValidationError):
+        details = []
+        for error in exc.errors():
+            # error["loc"] looks like ("body", "name")
+            loc = error.get("loc", [])
+            field = ".".join(str(x) for x in loc) if loc else "unknown"
+            
+            details.append({
+                "field": field,
+                "reason": error.get("type", "invalid"),
+                "message": error.get("msg", "Invalid value")
+            })
+            
+        return error_response(
+            request, 
+            422, 
+            "VALIDATION_ERROR", 
+            "Request validation failed.", 
+            details=details
+        )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def http_exception_handler(request: Request, exc: StarletteHTTPException):
+        if exc.status_code == 404:
+            return error_response(request, 404, "ROUTE_NOT_FOUND", "The requested route does not exist.")
+        if exc.status_code == 405:
+            return error_response(request, 405, "METHOD_NOT_ALLOWED", "Method not allowed for this route.")
+        return error_response(request, exc.status_code, "HTTP_ERROR", str(exc.detail))
+
     @app.get("/healthz", tags=["system"])
     def healthz() -> dict[str, str]:
         return {"status": "ok"}
 
     return app
 
-
 app = create_app()

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+pythonpath = .

tests/conftest.py

@@ -0,0 +1,46 @@
+import os
+import subprocess
+from pathlib import Path
+from dotenv import load_dotenv
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import text
+
+# Load .env so we get TEST_DATABASE_URL
+load_dotenv(Path(__file__).resolve().parents[1] / ".env")
+
+# Safety check: Refuse to run if we aren't on a test DB
+test_url = os.environ.get("TEST_DATABASE_URL")
+if not test_url:
+    raise RuntimeError("TEST_DATABASE_URL is not set in .env")
+
+db_name = test_url.rsplit("/", 1)[-1].split("?")[0]
+if not (db_name.endswith("_test") or "localhost" in test_url or "127.0.0.1" in test_url):
+    raise RuntimeError(f"Refusing to run tests on non-test database: {db_name}")
+
+# Override environment variables BEFORE importing app
+os.environ["DATABASE_URL"] = test_url
+os.environ["DIRECT_DATABASE_URL"] = test_url
+os.environ["JWT_SECRET_KEY"] = "test-secret-test-secret-test-secret-123"
+os.environ["GEMINI_API_KEY"] = "test-key"
+
+from app.main import app
+from app.db import engine
+
+@pytest.fixture(scope="session", autouse=True)
+def setup_database():
+    # Run Alembic migrations to set up the schema exactly like production
+    subprocess.run(["alembic", "upgrade", "head"], check=True)
+    yield
+
+@pytest.fixture(autouse=True)
+def clean_tables():
+    # Truncate tables between tests
+    with engine.begin() as conn:
+        conn.execute(text("TRUNCATE idempotency_keys, chunks, documents, hubs, users CASCADE"))
+    yield
+
+@pytest.fixture
+def client():
+    with TestClient(app) as c:
+        yield c