log refactor

backend/src/core/middleware/__init__.py

@@ -0,0 +1,5 @@
+# [DEF:middleware_package:Package]
+# @COMPLEXITY: 1
+# @SEMANTICS: middleware, package, starlette, fastapi
+# @PURPOSE: FastAPI/Starlette middleware package for request-level context and tracing.
+# [/DEF:middleware_package:Package]

backend/src/core/middleware/trace.py

@@ -0,0 +1,77 @@
+# [DEF:TraceContextMiddlewareModule:Module]
+# @COMPLEXITY: 3
+# @SEMANTICS: middleware, trace, context, starlette, fastapi
+# @PURPOSE: FastAPI/Starlette middleware that seeds a trace_id for every incoming HTTP request.
+#           Optionally extracts X-Trace-ID header for cross-service trace propagation.
+# @LAYER: Core
+# @RELATION: [DEPENDS_ON] -> [CotLoggerModule]
+# @RELATION: [CALLED_BY] -> [AppModule]
+# @PRE: FastAPI app instance with Starlette middleware support.
+# @POST: Every request gets a trace_id via seed_trace_id(). Existing X-Trace-ID header is
+#        preserved and used as the trace_id when present.
+# @SIDE_EFFECT: Sets ContextVar _trace_id for the duration of the request.
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import ASGIApp
+
+from ..cot_logger import seed_trace_id, set_trace_id
+
+# [DEF:TraceContextMiddleware:Class]
+# @COMPLEXITY: 2
+# @SEMANTICS: middleware, trace, context, dispatch
+# @BRIEF: Starlette BaseHTTPMiddleware that seeds a trace_id per request.
+class TraceContextMiddleware(BaseHTTPMiddleware):
+    """FastAPI/Starlette middleware that seeds a trace_id for every request.
+
+    If the incoming request carries an ``X-Trace-ID`` header, that value is
+    used as the trace_id (enabling cross-service trace chaining). Otherwise a
+    new UUID4 is generated.
+
+    Usage::
+
+        from backend.src.core.middleware.trace import TraceContextMiddleware
+        app.add_middleware(TraceContextMiddleware)
+    """
+
+    # [DEF:TraceContextMiddleware.__init__:Function]
+    # @BRIEF: Standard BaseHTTPMiddleware initialiser.
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    # [/DEF:TraceContextMiddleware.__init__:Function]
+
+    # [DEF:TraceContextMiddleware.dispatch:Function]
+    # @COMPLEXITY: 2
+    # @SEMANTICS: dispatch, trace, seed, header, call_next
+    # @BRIEF: Dispatch handler that seeds trace_id before passing to the next middleware.
+    async def dispatch(
+        self, request: Request, call_next
+    ) -> Response:
+        """Intercept every request, seed the trace_id, and forward.
+
+        If the client sent an ``X-Trace-ID`` header, use it; otherwise
+        ``seed_trace_id()`` generates a new UUID4.
+
+        Args:
+            request: The incoming Starlette Request.
+            call_next: The next middleware or route handler.
+
+        Returns:
+            Response from the downstream handler.
+        """
+        incoming_trace_id = request.headers.get("X-Trace-ID")
+        if incoming_trace_id:
+            set_trace_id(incoming_trace_id)
+        else:
+            seed_trace_id()
+
+        response = await call_next(request)
+        return response
+
+    # [/DEF:TraceContextMiddleware.dispatch:Function]
+
+
+# [/DEF:TraceContextMiddleware:Class]
+# [/DEF:TraceContextMiddlewareModule:Module]