keystone-request-context 0.3.0__tar.gz → 0.3.1__tar.gz

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keystone-request-context
-Version: 0.3.0
+Version: 0.3.1
 Summary: Shared request-scoped ContextVar slots + Starlette middleware for Keystone AI services.
 Requires-Python: >=3.12
 Requires-Dist: starlette<2,>=1.3.1

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/__init__.py

@@ -48,11 +48,14 @@ from .middleware import (
     normalize_correlation_id,
 )
 from .vars import (
+    actor_id,
     agent_id_var,
     correlation_id_var,
+    end_user_id_var,
     entity_id_var,
     headers_var,
     request_id_var,
+    service_account_id_var,
     stage_id_var,
     trace_id_var,
     traceparent_var,
@@ -65,8 +68,10 @@ __all__ = [
     "REQUEST_ID_HEADER",
     "LLMCallerIdentity",
     "RequestContextMiddleware",
+    "actor_id",
     "agent_id_var",
     "correlation_id_var",
+    "end_user_id_var",
     "entity_id_var",
     "gateway_identity_headers",
     "get_caller_identity",
@@ -80,6 +85,7 @@ __all__ = [
     "stage_id_var",
     "trace_id_var",
     "traceparent_var",
+    "service_account_id_var",
     "user_id_var",
     "workspace_id_var",
 ]

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/caller_identity.py

@@ -62,6 +62,10 @@ class LLMCallerIdentity:
     # handed to the pod per-request. A CREDENTIAL: repr=False keeps it out of any accidental
     # log/str of this bundle; it is emitted outbound only as X-Invocation-Key.
     invocation_key: str = field(default="", repr=False)
+    # FDP-5466 — the end user this turn serves (inbound ``X-EndUser-ID``). Empty on builder
+    # (Portal) traffic. Forwarded verbatim as ``X-EndUser-ID``; llm-gateway meters the call to
+    # this end user's wallet when present. Last field so positional construction is unchanged.
+    end_user_id: str = ""
 
 
 _caller_identity: ContextVar[LLMCallerIdentity | None] = ContextVar(
@@ -155,6 +159,7 @@ def gateway_identity_headers(*, auth_token: str, operation: str, caller_service:
         user_id = caller.user_id
         correlation_id = caller.correlation_id
     invocation_key = "" if caller is None else caller.invocation_key
+    end_user_id = "" if caller is None else caller.end_user_id
     headers = {
         "Content-Type": "application/json",
         "X-Entity-ID": entity_id,
@@ -178,6 +183,10 @@ def gateway_identity_headers(*, auth_token: str, operation: str, caller_service:
     # header" routing problem Ops raised: the Kong plugin just reads X-Invocation-Key.
     if invocation_key:
         headers["X-Invocation-Key"] = invocation_key
+    # FDP-5466 — forward the end user as-is. Additive: no end user → no header, every other
+    # header unchanged. X-User-ID is NOT dropped or rewritten when both are present.
+    if end_user_id:
+        headers["X-EndUser-ID"] = end_user_id
     self_agent = get_self_agent()
     if self_agent is not None:
         # Agent pod (FDP-3663): name the agent MAKING this hop — its key, budget, model allowlist

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/keystone_request_context.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keystone-request-context
-Version: 0.3.0
+Version: 0.3.1
 Summary: Shared request-scoped ContextVar slots + Starlette middleware for Keystone AI services.
 Requires-Python: >=3.12
 Requires-Dist: starlette<2,>=1.3.1

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/middleware.py

@@ -33,14 +33,16 @@ from contextvars import ContextVar
 from typing import TYPE_CHECKING
 
 import uuid_utils
-from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.datastructures import Headers, MutableHeaders
 
 from .vars import (
     agent_id_var,
     correlation_id_var,
+    end_user_id_var,
     entity_id_var,
     headers_var,
     request_id_var,
+    service_account_id_var,
     stage_id_var,
     trace_id_var,
     traceparent_var,
@@ -49,11 +51,7 @@ from .vars import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Awaitable, Callable
-
-    from starlette.requests import Request
-    from starlette.responses import Response
-    from starlette.types import ASGIApp
+    from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
 REQUEST_ID_HEADER = "X-Request-ID"
 CORRELATION_ID_HEADER = "X-Correlation-ID"
@@ -70,6 +68,11 @@ _HEADER_TO_VAR: tuple[tuple[str, ContextVar[str | None]], ...] = (
     ("x-entity-id", entity_id_var),
     ("x-stage-id", stage_id_var),
     ("x-agent-id", agent_id_var),
+    # FDP-4692 — without this slot an API-key (service-account) caller is
+    # invisible to every downstream client that builds headers from the context.
+    ("x-service-account-id", service_account_id_var),
+    # FDP-5466 — the end user a Front Desk / Headless / channel turn serves.
+    ("x-enduser-id", end_user_id_var),
 )
 
 
@@ -117,26 +120,32 @@ def normalize_correlation_id(value: str | None) -> str | None:
 _normalize_correlation_id = normalize_correlation_id
 
 
-class RequestContextMiddleware(BaseHTTPMiddleware):
+class RequestContextMiddleware:
     """Populate the request-context ``ContextVar`` slots for the request lifetime.
 
     See module docstring for the full contract.
+
+    Pure ASGI (FDP-6889), not ``BaseHTTPMiddleware``. ``BaseHTTPMiddleware`` ran the rest of the
+    stack in a child task and pushed every response chunk through a memory stream. Here the app
+    runs in the caller's task behind a thin ``send`` wrapper: the slots stay set for the whole
+    response (streamed body included) and are reset once it is done, and the two id headers are
+    written on ``http.response.start``. A middleware mounted OUTSIDE this one still writes after
+    it and wins, as before. Non-HTTP scopes (websocket, lifespan) pass through untouched.
     """
 
     def __init__(self, app: ASGIApp) -> None:
-        super().__init__(app)
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
 
-    async def dispatch(
-        self,
-        request: Request,
-        call_next: Callable[[Request], Awaitable[Response]],
-    ) -> Response:
         # 1. Materialize the lowercased-key header snapshot.
         #
-        # Starlette's ``request.headers`` already supports case-insensitive
-        # lookup, but downstream consumers (event_bus DSL, @require) expect
-        # a plain dict so they aren't coupled to Starlette types.
-        headers_snapshot: dict[str, str] = {key.lower(): value for key, value in request.headers.items()}
+        # Downstream consumers (event_bus DSL, @require) expect a plain dict so they aren't
+        # coupled to Starlette types. Later duplicates win, as with ``request.headers.items()``.
+        headers_snapshot: dict[str, str] = {key.lower(): value for key, value in Headers(scope=scope).items()}
 
         # 2. Resolve / mint X-Request-ID (per-API-call) AND X-Correlation-ID
         # (per-turn). Auto-gen UUID v7 for either when absent so logs always
@@ -147,8 +156,7 @@ class RequestContextMiddleware(BaseHTTPMiddleware):
         # (dashes stripped, lowercased) so logs / forward / Langfuse trace_id
         # all share one literal string. Malformed inbound value → re-mint a
         # UUID v7 and normalize that.
-        correlation_raw = headers_snapshot.get("x-correlation-id")
-        correlation_id = _normalize_correlation_id(correlation_raw)
+        correlation_id = _normalize_correlation_id(headers_snapshot.get("x-correlation-id"))
         if correlation_id is None:
             # Either no header sent, or value wasn't UUID-shaped — mint fresh.
             correlation_id = _normalize_correlation_id(_generate_request_id())
@@ -157,16 +165,23 @@ class RequestContextMiddleware(BaseHTTPMiddleware):
         headers_snapshot["x-request-id"] = request_id
         headers_snapshot["x-correlation-id"] = correlation_id
 
+        # 4. Echo resolved IDs so clients can correlate logs across hops.
+        async def send_with_ids(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                response_headers = MutableHeaders(scope=message)
+                response_headers[REQUEST_ID_HEADER] = request_id
+                response_headers[CORRELATION_ID_HEADER] = correlation_id
+            await send(message)
+
         # 3. Set every ContextVar, retaining tokens so we can reset them
         # in ``finally``. Resolved (minted-or-received) values already in
         # ``headers_snapshot`` win for both request_id and correlation_id.
         tokens = [headers_var.set(headers_snapshot)]
         for header_name, ctx_var in _HEADER_TO_VAR:
-            value = headers_snapshot.get(header_name)
-            tokens.append(ctx_var.set(value))
+            tokens.append(ctx_var.set(headers_snapshot.get(header_name)))
 
         try:
-            response = await call_next(request)
+            await self.app(scope, receive, send_with_ids)
         finally:
             # Reset in reverse order — ContextVar.reset is strict about token
             # ordering when nested calls have stacked sets on the same var.
@@ -180,10 +195,5 @@ class RequestContextMiddleware(BaseHTTPMiddleware):
                     # exception into the response path.
                     pass
 
-        # 4. Echo resolved IDs so clients can correlate logs across hops.
-        response.headers[REQUEST_ID_HEADER] = request_id
-        response.headers[CORRELATION_ID_HEADER] = correlation_id
-        return response
-
 
 __all__ = ["CORRELATION_ID_HEADER", "REQUEST_ID_HEADER", "RequestContextMiddleware"]

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keystone-request-context"
-version = "0.3.0"
+version = "0.3.1"
 description = "Shared request-scoped ContextVar slots + Starlette middleware for Keystone AI services."
 requires-python = ">=3.12"
 dependencies = [

{keystone_request_context-0.3.0 → keystone_request_context-0.3.1}/vars.py

@@ -75,6 +75,14 @@ traceparent_var: ContextVar[str | None] = ContextVar("keystone_traceparent", def
 user_id_var: ContextVar[str | None] = ContextVar("keystone_user_id", default=None)
 """Authenticated principal (header ``X-User-ID``)."""
 
+end_user_id_var: ContextVar[str | None] = ContextVar("keystone_end_user_id", default=None)
+"""End user served by this turn (header ``X-EndUser-ID``), FDP-5466.
+
+Set only on end-user traffic (Front Desk, Headless, chat channels): Kong or
+agent-conversations stamps it. Forward it verbatim on every outbound hop that
+reaches llm-gateway, which meters the call to this end user's wallet.
+Builder traffic (Portal) never carries it."""
+
 workspace_id_var: ContextVar[str | None] = ContextVar("keystone_workspace_id", default=None)
 """Active workspace scope (header ``X-Workspace-ID``)."""
 
@@ -88,6 +96,25 @@ agent_id_var: ContextVar[str | None] = ContextVar("keystone_agent_id", default=N
 """Caller agent identifier when traffic originates from another agent
 (header ``X-Agent-ID``)."""
 
+service_account_id_var: ContextVar[str | None] = ContextVar("keystone_service_account_id", default=None)
+"""Caller service account (header ``X-Service-Account-ID``).
+
+FDP-4692. An API-key caller arrives with this header and NO ``X-User-ID``, so a
+service that reads only :data:`user_id_var` sees an anonymous request: it stamps
+no author on the rows it writes and forwards no subject on its s2s hops, which
+made every downstream PEP evaluate the call as a user."""
+
+
+def actor_id() -> str | None:
+    """The id to stamp into ``created_by`` / ``updated_by`` for this request.
+
+    Precedence agent → service_account → user, matching the Java PEP's subject
+    derivation (``AuthzAspect``) so attribution and authorization never
+    disagree about who the caller is.
+    """
+    return agent_id_var.get() or service_account_id_var.get() or user_id_var.get()
+
+
 # ---------------------------------------------------------------------------
 # Escape hatch — full headers snapshot
 # ---------------------------------------------------------------------------
@@ -108,6 +135,7 @@ with a fresh dict to avoid bleeding state across requests.
 __all__ = [
     "agent_id_var",
     "correlation_id_var",
+    "end_user_id_var",
     "entity_id_var",
     "headers_var",
     "request_id_var",