310 lines
11 KiB
Python
310 lines
11 KiB
Python
"""Global exception handlers and request-id middleware for FastAPI.
|
|
|
|
This module standardizes two operational behaviors:
|
|
|
|
1) **Request IDs**
|
|
- Every response includes an `X-Request-Id` header.
|
|
- Clients may supply their own request id; otherwise we generate one.
|
|
- The request id is propagated into logs via context vars.
|
|
|
|
2) **Error responses**
|
|
- Errors are returned as JSON with a stable top-level shape:
|
|
`{ "detail": ..., "request_id": ... }`
|
|
- Validation errors (`422`) return structured field errors.
|
|
- Unhandled errors are logged at ERROR and return a generic 500.
|
|
|
|
Design notes:
|
|
- The request-id middleware is installed *outermost* so it runs even when other
|
|
middleware returns early.
|
|
- Health endpoints are excluded from request logs by default to reduce noise.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Awaitable, Callable
|
|
from time import perf_counter
|
|
from typing import TYPE_CHECKING, Any, Final
|
|
from uuid import uuid4
|
|
|
|
from fastapi import FastAPI, Request
|
|
from fastapi.exceptions import RequestValidationError, ResponseValidationError
|
|
from fastapi.responses import JSONResponse
|
|
from starlette.exceptions import HTTPException as StarletteHTTPException
|
|
from starlette.responses import Response
|
|
|
|
from app.core.config import settings
|
|
from app.core.logging import (
|
|
TRACE_LEVEL,
|
|
get_logger,
|
|
reset_request_id,
|
|
reset_request_route_context,
|
|
set_request_id,
|
|
set_request_route_context,
|
|
)
|
|
|
|
if TYPE_CHECKING: # pragma: no cover
|
|
from starlette.types import ASGIApp, Message, Receive, Scope, Send
|
|
|
|
logger = get_logger(__name__)
|
|
|
|
REQUEST_ID_HEADER: Final[str] = "X-Request-Id"
|
|
_HEALTH_CHECK_PATHS: Final[frozenset[str]] = frozenset({"/health", "/healthz", "/readyz"})
|
|
|
|
ExceptionHandler = Callable[[Request, Exception], Response | Awaitable[Response]]
|
|
|
|
|
|
class RequestIdMiddleware:
|
|
"""ASGI middleware that ensures every request has a request-id."""
|
|
|
|
def __init__(self, app: ASGIApp, *, header_name: str = REQUEST_ID_HEADER) -> None:
|
|
"""Initialize middleware with app instance and header name."""
|
|
self._app = app
|
|
self._header_name = header_name
|
|
self._header_name_bytes = header_name.lower().encode("latin-1")
|
|
self._slow_request_ms = settings.request_log_slow_ms
|
|
self._include_health_logs = settings.request_log_include_health
|
|
|
|
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
|
|
"""Inject request-id into request state and response headers."""
|
|
if scope["type"] != "http":
|
|
await self._app(scope, receive, send)
|
|
return
|
|
|
|
method = str(scope.get("method") or "UNKNOWN").upper()
|
|
path = str(scope.get("path") or "")
|
|
client = scope.get("client")
|
|
client_ip: str | None = None
|
|
if isinstance(client, tuple) and client and isinstance(client[0], str):
|
|
client_ip = client[0]
|
|
should_log = self._include_health_logs or path not in _HEALTH_CHECK_PATHS
|
|
started_at = perf_counter()
|
|
status_code: int | None = None
|
|
|
|
request_id = self._get_or_create_request_id(scope)
|
|
context_token = set_request_id(request_id)
|
|
route_context_tokens = set_request_route_context(method, path)
|
|
if should_log:
|
|
logger.log(
|
|
TRACE_LEVEL,
|
|
"http.request.start",
|
|
extra={
|
|
"method": method,
|
|
"path": path,
|
|
"client_ip": client_ip,
|
|
},
|
|
)
|
|
|
|
async def send_with_request_id(message: Message) -> None:
|
|
nonlocal status_code
|
|
if message["type"] == "http.response.start":
|
|
# Starlette uses `list[tuple[bytes, bytes]]` here.
|
|
headers: list[tuple[bytes, bytes]] = message.setdefault("headers", [])
|
|
if not any(key.lower() == self._header_name_bytes for key, _ in headers):
|
|
request_id_bytes = request_id.encode("latin-1")
|
|
headers.append((self._header_name_bytes, request_id_bytes))
|
|
status = message.get("status")
|
|
status_code = status if isinstance(status, int) else 500
|
|
if should_log:
|
|
duration_ms = int((perf_counter() - started_at) * 1000)
|
|
extra = {
|
|
"method": method,
|
|
"path": path,
|
|
"status_code": status_code,
|
|
"duration_ms": duration_ms,
|
|
"client_ip": client_ip,
|
|
}
|
|
if status_code >= 500:
|
|
logger.error("http.request.complete", extra=extra)
|
|
elif status_code >= 400:
|
|
logger.warning("http.request.complete", extra=extra)
|
|
else:
|
|
logger.debug("http.request.complete", extra=extra)
|
|
if self._slow_request_ms and duration_ms >= self._slow_request_ms:
|
|
logger.warning(
|
|
"http.request.slow",
|
|
extra={
|
|
**extra,
|
|
"slow_threshold_ms": self._slow_request_ms,
|
|
},
|
|
)
|
|
await send(message)
|
|
|
|
try:
|
|
await self._app(scope, receive, send_with_request_id)
|
|
finally:
|
|
if should_log and status_code is None:
|
|
logger.warning(
|
|
"http.request.incomplete",
|
|
extra={
|
|
"method": method,
|
|
"path": path,
|
|
"duration_ms": int((perf_counter() - started_at) * 1000),
|
|
"client_ip": client_ip,
|
|
},
|
|
)
|
|
reset_request_route_context(route_context_tokens)
|
|
reset_request_id(context_token)
|
|
|
|
def _get_or_create_request_id(self, scope: Scope) -> str:
|
|
# Accept a client-provided request id if present.
|
|
request_id: str | None = None
|
|
for key, value in scope.get("headers", []):
|
|
if key.lower() == self._header_name_bytes:
|
|
candidate = value.decode("latin-1").strip()
|
|
if candidate:
|
|
request_id = candidate
|
|
break
|
|
|
|
if request_id is None:
|
|
request_id = uuid4().hex
|
|
|
|
# `Request.state` is backed by `scope["state"]`.
|
|
state = scope.setdefault("state", {})
|
|
state["request_id"] = request_id
|
|
return request_id
|
|
|
|
|
|
def install_error_handling(app: FastAPI) -> None:
|
|
"""Install middleware and exception handlers on the FastAPI app."""
|
|
# Important: add request-id middleware last so it's the outermost middleware.
|
|
# This ensures it still runs even if another middleware
|
|
# (e.g. CORS preflight) returns early.
|
|
app.add_middleware(RequestIdMiddleware)
|
|
|
|
app.add_exception_handler(
|
|
RequestValidationError,
|
|
_request_validation_exception_handler,
|
|
)
|
|
app.add_exception_handler(
|
|
ResponseValidationError,
|
|
_response_validation_exception_handler,
|
|
)
|
|
app.add_exception_handler(
|
|
StarletteHTTPException,
|
|
_http_exception_exception_handler,
|
|
)
|
|
app.add_exception_handler(Exception, _unhandled_exception_handler)
|
|
|
|
|
|
async def _request_validation_exception_handler(
|
|
request: Request,
|
|
exc: Exception,
|
|
) -> Response:
|
|
if not isinstance(exc, RequestValidationError):
|
|
msg = "Expected RequestValidationError"
|
|
raise TypeError(msg)
|
|
return await _request_validation_handler(request, exc)
|
|
|
|
|
|
async def _response_validation_exception_handler(
|
|
request: Request,
|
|
exc: Exception,
|
|
) -> Response:
|
|
if not isinstance(exc, ResponseValidationError):
|
|
msg = "Expected ResponseValidationError"
|
|
raise TypeError(msg)
|
|
return await _response_validation_handler(request, exc)
|
|
|
|
|
|
async def _http_exception_exception_handler(
|
|
request: Request,
|
|
exc: Exception,
|
|
) -> Response:
|
|
if not isinstance(exc, StarletteHTTPException):
|
|
msg = "Expected StarletteHTTPException"
|
|
raise TypeError(msg)
|
|
return await _http_exception_handler(request, exc)
|
|
|
|
|
|
def _get_request_id(request: Request) -> str | None:
|
|
request_id = getattr(request.state, "request_id", None)
|
|
if isinstance(request_id, str) and request_id:
|
|
return request_id
|
|
return None
|
|
|
|
|
|
def _error_payload(*, detail: object, request_id: str | None) -> dict[str, object]:
|
|
payload: dict[str, Any] = {"detail": _json_safe(detail)}
|
|
if request_id:
|
|
payload["request_id"] = request_id
|
|
return payload
|
|
|
|
|
|
def _json_safe(value: object) -> object:
|
|
"""Return a JSON-serializable representation for error payloads."""
|
|
if isinstance(value, bytes):
|
|
return value.decode("utf-8", errors="replace")
|
|
if isinstance(value, (bytearray, memoryview)):
|
|
return bytes(value).decode("utf-8", errors="replace")
|
|
if isinstance(value, dict):
|
|
return {str(key): _json_safe(item) for key, item in value.items()}
|
|
if isinstance(value, (list, tuple, set)):
|
|
return [_json_safe(item) for item in value]
|
|
if value is None or isinstance(value, (str, int, float, bool)):
|
|
return value
|
|
return str(value)
|
|
|
|
|
|
async def _request_validation_handler(
|
|
request: Request,
|
|
exc: RequestValidationError,
|
|
) -> JSONResponse:
|
|
# `RequestValidationError` is expected user input; don't log at ERROR.
|
|
request_id = _get_request_id(request)
|
|
return JSONResponse(
|
|
status_code=422,
|
|
content=_error_payload(detail=exc.errors(), request_id=request_id),
|
|
)
|
|
|
|
|
|
async def _response_validation_handler(
|
|
request: Request,
|
|
exc: ResponseValidationError,
|
|
) -> JSONResponse:
|
|
request_id = _get_request_id(request)
|
|
logger.exception(
|
|
"response_validation_error",
|
|
extra={
|
|
"request_id": request_id,
|
|
"method": request.method,
|
|
"path": request.url.path,
|
|
"errors": exc.errors(),
|
|
},
|
|
)
|
|
return JSONResponse(
|
|
status_code=500,
|
|
content=_error_payload(detail="Internal Server Error", request_id=request_id),
|
|
)
|
|
|
|
|
|
async def _http_exception_handler(
|
|
request: Request,
|
|
exc: StarletteHTTPException,
|
|
) -> JSONResponse:
|
|
request_id = _get_request_id(request)
|
|
return JSONResponse(
|
|
status_code=exc.status_code,
|
|
content=_error_payload(detail=exc.detail, request_id=request_id),
|
|
headers=exc.headers,
|
|
)
|
|
|
|
|
|
async def _unhandled_exception_handler(
|
|
request: Request,
|
|
_exc: Exception,
|
|
) -> JSONResponse:
|
|
request_id = _get_request_id(request)
|
|
logger.exception(
|
|
"unhandled_exception",
|
|
extra={
|
|
"request_id": request_id,
|
|
"method": request.method,
|
|
"path": request.url.path,
|
|
},
|
|
)
|
|
return JSONResponse(
|
|
status_code=500,
|
|
content=_error_payload(detail="Internal Server Error", request_id=request_id),
|
|
headers={REQUEST_ID_HEADER: request_id} if request_id else None,
|
|
)
|