Docs cleanup

Author: LucasAlvesSoares

src/sap_cloud_sdk/core/bootstrap.py

@@ -9,24 +9,19 @@
 def bootstrap(app: Any, providers: Optional[List[ContextProvider]] = None) -> None:
     """Wire the SDK runtime context into your application framework.
 
-    Call this once at application startup. The SDK will attach a middleware
-    to *app* that populates :class:`~sap_cloud_sdk.core.runtime_context.RequestContext`
-    on every inbound request by running all *providers* against it and merging
-    the results.
+    Call once at startup. On every inbound request the SDK will run all
+    *providers* against the request, merge the results, and make them
+    available via :func:`~sap_cloud_sdk.core.runtime_context.get_context`.
 
-    After bootstrapping, any SDK module (auditlog, telemetry, etc.) can call
-    :func:`~sap_cloud_sdk.core.runtime_context.get_context` to read
-    tenant/user information without knowing about headers or auth providers.
-
-    The framework is detected automatically from the *app* type. Supported
-    frameworks are determined by registered
-    :class:`~sap_cloud_sdk.core.runtime_context.FrameworkAdapter` instances —
-    new frameworks are added by registering an adapter, not by editing this file.
+    The framework is detected automatically from the *app* type via the
+    registered :class:`~sap_cloud_sdk.core.runtime_context.FrameworkAdapter`
+    instances — adding support for a new framework never requires editing
+    this function.
 
     Args:
         app:       The application instance to attach the middleware to.
-        providers: One or more :class:`~sap_cloud_sdk.core.runtime_context.ContextProvider`
-                   instances. Defaults to ``[IASContextProvider()]``.
+        providers: Context providers to run on each request. Defaults to
+                   ``[IASContextProvider(), HeaderContextProvider()]``.
 
     Raises:
         TypeError: If no registered adapter recognises *app*.
@@ -35,10 +30,10 @@ def bootstrap(app: Any, providers: Optional[List[ContextProvider]] = None) -> No
 
         from sap_cloud_sdk import bootstrap
 
-        bootstrap(app)  # IASContextProvider by default
+        bootstrap(app)  # IAS + SAP headers by default
 
-        # multiple providers:
-        bootstrap(app, providers=[IASContextProvider(), MyCustomProvider()])
+        # custom providers:
+        bootstrap(app, providers=[IASContextProvider(), MyProvider()])
     """
     if not providers:
         providers = [IASContextProvider(), HeaderContextProvider()]

src/sap_cloud_sdk/core/runtime_context/__init__.py

@@ -1,30 +1,28 @@
-"""SDK-wide per-request runtime context.
+"""SDK-wide runtime context for the current execution.
 
-Provides a provider-agnostic way for SDK modules to access caller-identity
-fields (tenant, user, trigger type) without coupling to a specific auth
-provider or HTTP framework.
+Lets SDK modules read caller-identity information (tenant, user, trigger type)
+without knowing about the invocation source — HTTP, gRPC, message queue, etc.
 
-Typical usage — wire once at app startup::
+Wire once at startup::
 
     from sap_cloud_sdk import bootstrap
-    from sap_cloud_sdk.core.runtime_context import IASContextProvider
 
-    bootstrap(app, providers=[IASContextProvider()])
+    bootstrap(app)  # defaults to IASContextProvider + HeaderContextProvider
 
-Then read anywhere in the SDK or application code::
+Then read anywhere::
 
-    from sap_cloud_sdk.core.runtime_context import get_context
+    from sap_cloud_sdk.core.runtime_context import get_context, TENANT_ID, USER_ID
 
     ctx = get_context()
-    print(ctx.tenant_id)    # e.g. "abc-123"
-    print(ctx.user_id)      # e.g. "user-uuid"
+    ctx.get(TENANT_ID)   # -> "abc-123" or None
+    ctx.get(USER_ID)     # -> "user-uuid" or None
 
-For tests or CLI usage without HTTP::
+In tests or scripts without a framework::
 
-    from sap_cloud_sdk.core.runtime_context import sdk_context, RequestContext
+    from sap_cloud_sdk.core.runtime_context import sdk_context, RequestContext, TENANT_ID
 
-    with sdk_context(RequestContext(tenant_id="test-tenant")):
-        ...  # get_context() returns that context here
+    with sdk_context(RequestContext({TENANT_ID: "test-tenant"})):
+        ...
 """
 
 from sap_cloud_sdk.core.runtime_context._context import (

src/sap_cloud_sdk/core/runtime_context/_context.py

@@ -10,7 +10,7 @@
 
 
 class RequestContext:
-    """Immutable typed bag of per-request values set by context providers.
+    """Immutable typed bag of caller-identity values for the current execution.
 
     Values are keyed by :class:`ContextKey` instances, which carry the
     expected type. Use :meth:`get` to read a value and :meth:`with_value`

src/sap_cloud_sdk/core/runtime_context/_envelope.py

@@ -6,17 +6,17 @@
 
 @dataclass
 class RequestEnvelope:
-    """Normalized view of an inbound request, independent of framework.
+    """Framework-agnostic view of an inbound request passed to providers.
 
-    Framework middlewares build this from their native request object.
-    :class:`~sap_cloud_sdk.core.runtime_context.ContextProvider` implementations
-    read from it — they never touch framework-specific types.
+    The framework middleware populates this; providers read from it. This
+    means providers work identically regardless of whether the request came
+    from Starlette, Flask, gRPC, or a test.
 
     Attributes:
-        headers:  Case-insensitive HTTP headers (or equivalent for gRPC/etc.).
-        body:     Raw request body bytes. ``None`` if not extracted.
-        metadata: Catch-all for framework extras (query params, gRPC metadata,
-                  connection info, etc.). Reserved for future providers.
+        headers:  Request headers as a plain dict (lowercased keys recommended).
+        body:     Raw request body. ``None`` if not needed by any provider.
+        metadata: Framework-specific extras — query params, gRPC metadata, etc.
+                  Currently unused; reserved for future providers.
     """
 
     headers: Dict[str, str] = field(default_factory=dict)

src/sap_cloud_sdk/core/runtime_context/_protocol.py

@@ -8,21 +8,19 @@
 
 @runtime_checkable
 class ContextProvider(Protocol):
-    """Extract a :class:`RequestContext` from a :class:`RequestEnvelope`.
+    """Extracts a :class:`RequestContext` from a :class:`RequestEnvelope`.
 
-    Implement this protocol to teach the SDK how to read caller-identity
-    information from a specific auth provider (IAS, XSUAA, etc.).
-
-    The envelope is framework-agnostic — providers never touch Starlette,
-    Flask, or gRPC types directly. The framework middleware is responsible
-    for building the envelope.
+    Implement this to add a new auth provider or header convention. The envelope
+    is framework-agnostic — providers never touch Starlette, Flask, or gRPC types.
 
     Example::
 
+        MY_KEY = ContextKey[str]("my_key")
+
         class MyProvider(ContextProvider):
             def extract(self, envelope: RequestEnvelope) -> RequestContext:
-                token = envelope.headers.get("x-my-token", "")
-                return RequestContext(tenant_id=decode(token).tenant)
+                value = envelope.headers.get("x-my-header", "")
+                return RequestContext({MY_KEY: value} if value else {})
     """
 
     def extract(self, envelope: RequestEnvelope) -> RequestContext:  # pragma: no cover

src/sap_cloud_sdk/core/runtime_context/_registry.py

@@ -21,10 +21,10 @@ def get_registry() -> List["FrameworkAdapter"]:
 
 
 class FrameworkAdapter(ABC):
-    """Base class for framework-specific context middleware adapters.
+    """Connects a framework or invocation source to the SDK runtime context.
 
-    Subclasses know how to detect a framework's app object and attach the
-    appropriate context middleware to it. Register at module level so that
+    Subclasses know how to detect a specific app type and attach the SDK's
+    context pipeline to it. Register at module level so that
     :func:`~sap_cloud_sdk.core.bootstrap.bootstrap` can discover them without
     importing framework-specific code directly.
 

src/sap_cloud_sdk/core/runtime_context/user-guide.md

@@ -0,0 +1,181 @@
+# Runtime Context User Guide
+
+## How it works
+
+The runtime context lets SDK modules read caller-identity information (tenant,
+user, trigger type) for the current execution — without knowing where that
+information came from or what framework is running.
+
+- **`bootstrap(app)`** wires the SDK into your framework once at startup.
+- **Providers** extract context from the current invocation (HTTP request, gRPC call, Kubernetes event, etc.).
+- **`get_context()`** lets any module read that context via typed keys.
+
+```
+bootstrap(app)
+  └─ registers middleware on your framework
+       └─ on each invocation: providers extract → RequestContext set in ContextVar
+            └─ anywhere: get_context().get(TENANT_ID)
+```
+
+---
+
+## Quick start
+
+### 1. Bootstrap at app startup
+
+```python
+from starlette.applications import Starlette
+from sap_cloud_sdk import bootstrap
+
+app = Starlette(...)
+bootstrap(app)
+```
+
+By default `bootstrap` registers `IASContextProvider` (reads IAS JWT) and
+`HeaderContextProvider` (reads SAP standard headers like `x-sap-origin`).
+
+### 2. Read context anywhere
+
+```python
+from sap_cloud_sdk.core.runtime_context import get_context, TENANT_ID, USER_ID, TRIGGER_TYPE
+
+ctx = get_context()
+ctx.get(TENANT_ID)    # -> "abc-123" or None
+ctx.get(USER_ID)      # -> "user-uuid" or None
+ctx.get(TRIGGER_TYPE) # -> "ui5" or None
+```
+
+---
+
+## Context keys
+
+Values are stored and retrieved by typed `ContextKey` instances — not strings.
+Each provider owns the keys it defines. Import keys from the provider that
+defined them.
+
+```python
+# IAS-owned keys:
+from sap_cloud_sdk.core.runtime_context import TENANT_ID, USER_ID, IAS_CLAIMS
+
+# SDK-standard keys (not tied to any specific source):
+from sap_cloud_sdk.core.runtime_context import TRIGGER_TYPE
+
+# Define your own:
+from sap_cloud_sdk.core.runtime_context import ContextKey
+
+MY_KEY = ContextKey[str]("my_key")
+```
+
+Keys are identity-based — two `ContextKey("same_name")` instances are different
+keys. Always import the key from the module that defined it.
+
+---
+
+## Providers
+
+A provider extracts a `RequestContext` from a `RequestEnvelope` — a
+framework-agnostic carrier of whatever signals were available at invocation time
+(headers, body, metadata). The provider doesn't know which framework built the
+envelope; the framework adapter doesn't know what the provider does with it.
+
+This means providers are reusable across transports. An `IASContextProvider`
+written for HTTP headers works identically if the same headers appear in gRPC
+metadata or a message queue envelope — as long as the adapter populates
+`RequestEnvelope.headers` consistently.
+
+### Built-in providers
+
+| Provider | Reads | Sets |
+|---|---|---|
+| `IASContextProvider` | `Authorization: Bearer <JWT>` | `TENANT_ID`, `USER_ID`, `IAS_CLAIMS` |
+| `HeaderContextProvider` | `x-sap-origin` | `TRIGGER_TYPE` |
+
+### Custom providers
+
+```python
+from sap_cloud_sdk.core.runtime_context import (
+    ContextKey, ContextProvider, RequestContext, RequestEnvelope
+)
+
+CORRELATION_ID = ContextKey[str]("correlation_id")
+
+class CorrelationIdProvider(ContextProvider):
+    def extract(self, envelope: RequestEnvelope) -> RequestContext:
+        value = envelope.headers.get("x-correlation-id")
+        return RequestContext({CORRELATION_ID: value} if value else {})
+```
+
+Pass it to `bootstrap`:
+
+```python
+from sap_cloud_sdk.core.runtime_context import IASContextProvider, HeaderContextProvider
+
+bootstrap(app, providers=[IASContextProvider(), HeaderContextProvider(), CorrelationIdProvider()])
+```
+
+### Merging
+
+When multiple providers are registered, their results are merged — first writer
+wins per key. Providers that set different keys don't interfere with each other.
+
+---
+
+## Framework adapters
+
+`bootstrap` auto-detects the framework from the `app` type via registered
+`FrameworkAdapter` instances. Each adapter knows how to intercept invocations
+for one framework and build a `RequestEnvelope` from whatever the framework
+exposes. Adding support for a new framework or invocation source never requires
+editing `bootstrap`.
+
+### Currently supported
+
+| Framework | Detected via |
+|---|---|
+| Starlette / FastAPI | `isinstance(app, Starlette)` |
+
+### Adding a new framework or invocation source
+
+```python
+from sap_cloud_sdk.core.runtime_context import ContextProvider, FrameworkAdapter, register
+
+class FlaskContextAdapter(FrameworkAdapter):
+    def _matches(self, app) -> bool:
+        from flask import Flask
+        return isinstance(app, Flask)
+
+    def attach(self, app, providers: list[ContextProvider]) -> None:
+        from my_flask_middleware import FlaskContextMiddleware
+        app.before_request(FlaskContextMiddleware(providers).handle)
+
+register(FlaskContextAdapter())
+```
+
+---
+
+## Manual usage (tests, CLI, scripts)
+
+When there is no framework to bootstrap — unit tests, CLI tools, background
+jobs — set the context directly for the duration of a block:
+
+```python
+from sap_cloud_sdk.core.runtime_context import sdk_context, RequestContext, TENANT_ID, USER_ID
+
+# Sync:
+with sdk_context(RequestContext({TENANT_ID: "test-tenant", USER_ID: "test-user"})):
+    result = some_sdk_call()
+
+# Async:
+from sap_cloud_sdk.core.runtime_context import async_sdk_context
+
+async with async_sdk_context(RequestContext({TENANT_ID: "test-tenant"})):
+    result = await some_async_sdk_call()
+```
+
+---
+
+## Running the tests
+
+```bash
+uv run pytest tests/core/unit/runtime_context/
+```