fix(server): add TestContextMiddleware for integration test replay

Ensures test context from X-LlamaStack-Provider-Data header is available
to FastAPI router routes, enabling deterministic ID generation in replay mode.

Signed-off-by: Matthew F Leader <mleader@redhat.com>

Author: mfleader

src/llama_stack/core/server/server.py

@@ -356,6 +356,36 @@ async def send_version_error(send):
         return await self.app(scope, receive, send)
 
 
+class TestContextMiddleware:
+    """Middleware to propagate test context from request headers to all routes.
+
+    Extracts the test ID from the X-LlamaStack-Provider-Data header and makes it
+    available via get_test_context(). This enables deterministic ID generation
+    during integration test replay mode.
+    """
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            from llama_stack.core.testing_context import (
+                reset_test_context,
+                sync_test_context_from_provider_data,
+            )
+
+            headers = {k.decode(): v.decode() for k, v in scope.get("headers", [])}
+            with request_provider_data_context(headers, None):
+                token = sync_test_context_from_provider_data()
+                try:
+                    return await self.app(scope, receive, send)
+                finally:
+                    if token:
+                        reset_test_context(token)
+
+        return await self.app(scope, receive, send)
+
+
 def create_app() -> StackApp:
     """Create and configure the FastAPI application.
 
@@ -395,6 +425,9 @@ def create_app() -> StackApp:
     if not os.environ.get("LLAMA_STACK_DISABLE_VERSION_CHECK"):
         app.add_middleware(ClientVersionMiddleware)
 
+    if os.environ.get("LLAMA_STACK_TEST_INFERENCE_MODE"):
+        app.add_middleware(TestContextMiddleware)
+
     impls = app.stack.impls
 
     if config.server.auth:

tests/unit/server/test_test_context_middleware.py

@@ -0,0 +1,106 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+import json
+import os
+
+import pytest
+from fastapi import APIRouter, FastAPI
+from starlette.testclient import TestClient
+
+from llama_stack.core.server.server import TestContextMiddleware
+from llama_stack.core.testing_context import get_test_context
+
+
+@pytest.fixture
+def app_with_middleware():
+    """Create a minimal FastAPI app with TestContextMiddleware."""
+    app = FastAPI()
+
+    router = APIRouter()
+
+    @router.get("/test-context")
+    def get_current_test_context():
+        return {"test_id": get_test_context()}
+
+    app.include_router(router)
+    app.add_middleware(TestContextMiddleware)
+
+    return app
+
+
+@pytest.fixture
+def test_mode_env(monkeypatch):
+    """Set environment variables required for test context extraction."""
+    monkeypatch.setenv("LLAMA_STACK_TEST_INFERENCE_MODE", "replay")
+    monkeypatch.setenv("LLAMA_STACK_TEST_STACK_CONFIG_TYPE", "server")
+
+
+def test_middleware_returns_none_without_header(app_with_middleware, test_mode_env):
+    """Without the provider data header, test context should be None."""
+    client = TestClient(app_with_middleware)
+    response = client.get("/test-context")
+
+    assert response.status_code == 200
+    assert response.json()["test_id"] is None
+
+
+def test_middleware_extracts_test_id_from_header(app_with_middleware, test_mode_env):
+    """With the provider data header containing __test_id, it should be extracted."""
+    client = TestClient(app_with_middleware)
+
+    provider_data = json.dumps({"__test_id": "test-abc-123"})
+    response = client.get(
+        "/test-context",
+        headers={"X-LlamaStack-Provider-Data": provider_data},
+    )
+
+    assert response.status_code == 200
+    assert response.json()["test_id"] == "test-abc-123"
+
+
+def test_middleware_handles_empty_provider_data(app_with_middleware, test_mode_env):
+    """Empty provider data should result in None test context."""
+    client = TestClient(app_with_middleware)
+
+    response = client.get(
+        "/test-context",
+        headers={"X-LlamaStack-Provider-Data": "{}"},
+    )
+
+    assert response.status_code == 200
+    assert response.json()["test_id"] is None
+
+
+def test_middleware_handles_invalid_json(app_with_middleware, test_mode_env):
+    """Invalid JSON in header should not crash, test context should be None."""
+    client = TestClient(app_with_middleware)
+
+    response = client.get(
+        "/test-context",
+        headers={"X-LlamaStack-Provider-Data": "not-valid-json"},
+    )
+
+    assert response.status_code == 200
+    assert response.json()["test_id"] is None
+
+
+def test_middleware_noop_without_test_mode(app_with_middleware):
+    """Without test mode env vars, middleware should not extract test context."""
+    # Ensure env vars are not set
+    os.environ.pop("LLAMA_STACK_TEST_INFERENCE_MODE", None)
+    os.environ.pop("LLAMA_STACK_TEST_STACK_CONFIG_TYPE", None)
+
+    client = TestClient(app_with_middleware)
+
+    provider_data = json.dumps({"__test_id": "test-abc-123"})
+    response = client.get(
+        "/test-context",
+        headers={"X-LlamaStack-Provider-Data": provider_data},
+    )
+
+    assert response.status_code == 200
+    assert response.json()["test_id"] is None