mobius-tracer-py 1.0.0__tar.gz

mobius_tracer_py-1.0.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: mobius-tracer-py
+Version: 1.0.0
+Summary: Request-context propagation, JWT parsing, security headers and OpenTelemetry enrichment for Mobius Python (FastAPI) services.
+Author: Mobius Platform
+Keywords: tracing,context-propagation,fastapi,mobius,opentelemetry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: starlette>=0.27
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.24; extra == "httpx"
+Provides-Extra: resources
+Requires-Dist: psutil>=5.9; extra == "resources"
+Provides-Extra: banner
+Requires-Dist: pyfiglet>=1.0; extra == "banner"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: starlette>=0.27; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+Requires-Dist: opentelemetry-api>=1.20; extra == "dev"
+
+# mobius-tracer-py
+
+Request-context propagation for Mobius **Python (FastAPI / Starlette)** services.
+
+On every incoming request it extracts identity/trace headers and the JWT
+payload, exposes them request-scoped, forwards them onto downstream calls, sets
+security + trace response headers, and enriches OpenTelemetry spans.
+
+- **PyPI:** `pip install mobius-tracer-py`
+- **Import package:** `mobius_tracer`
+- **Python:** 3.10+
+
+## Install
+
+```bash
+pip install mobius-tracer-py
+
+# optional features
+pip install "mobius-tracer-py[otel]"        # set OTel span attributes
+pip install "mobius-tracer-py[httpx]"       # TracedClient / httpx hook
+pip install "mobius-tracer-py[resources]"   # CPU/mem span metrics (psutil)
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from mobius_tracer import setup_tracer, current
+
+app = FastAPI()
+setup_tracer(app)   # adds middleware + 401 handler for invalid tokens
+
+@app.get("/me")
+async def me():
+    ctx = current()
+    return {"tenant_id": ctx.tenant_id, "txn": ctx.req_transaction_id}
+```
+
+`setup_tracer` installs a middleware that, per request:
+
+1. extracts `x-request-id`, `x-b3-traceid`, `x-b3-spanid`, `Authorization`,
+   `appId`, `platformId`, and `X-Transaction-Id` (generated if absent);
+2. parses the JWT payload into the request context (tenant/agent/user/email …);
+3. derives `action_log_user_id` from the token;
+4. sets security response headers + `x-mb-trace-id` + `X-Transaction-Id`;
+5. sets OpenTelemetry span attributes (`txn.id`, `tenant.id`, `user.id`).
+
+### Options
+
+```python
+setup_tracer(
+    app,
+    skip_paths=("actuator", "health", "metrics", "error", "prometheus",
+                "swagger", "api-docs", "arazzo"),  # paths with no token check
+    require_token=True,          # 401 on protected paths without a valid token
+    set_security_headers=True,   # HSTS/CSP/X-Frame-Options/...
+    propagate_to_otel=True,      # txn/tenant/user span attributes
+    integrate_logging=True,      # mirror fields into mobius-logging-py context
+    measure_resources=True,      # CPU/mem of each request onto the span
+    instrument_httpx=False,      # patch httpx so all outbound calls propagate (opt-in)
+)
+```
+
+## Request context
+
+```python
+from mobius_tracer import current, get, HeadersHolder
+
+ctx = current()           # HeadersHolder for this request
+ctx.tenant_id             # e.g. "tenant-123"
+ctx.action_log_user_id    # derived user id
+get("trace_id")           # field accessor
+```
+
+Fields: `request_id`, `trace_id`, `span_id`, `tenant_id`, `tenant_user_id`,
+`consumer_id`, `email`, `authorization`, `name`, `requester_type`, `platform_id`,
+`parent_tenant_id`, `app_id`, `action_log_user_id`, `agent_id`, `agent_user_id`,
+`req_transaction_id`, `b_agent_id`.
+
+The context uses `contextvars`, so it is isolated per request and correct across
+`async` tasks and threads.
+
+## Propagating to downstream calls
+
+Forward the current context (and a W3C `traceparent`) to outbound requests:
+
+```python
+import httpx
+from mobius_tracer import traced_headers, httpx_auth_hook, TracedClient
+
+# 1) build headers yourself
+httpx.get(url, headers=traced_headers())
+
+# 2) an httpx event hook
+client = httpx.AsyncClient(event_hooks={"request": [httpx_auth_hook()]})
+
+# 3) a ready-made traced client
+with TracedClient(base_url="https://api.internal") as c:
+    c.get("/orders/1")
+
+# 4) globally patch httpx so ALL outbound calls propagate (internal-only!)
+from mobius_tracer import instrument_httpx
+instrument_httpx()   # or setup_tracer(app, instrument_httpx=True)
+```
+
+Forwarded headers: `x-request-id`, `x-b3-traceid`, `x-b3-spanid`, `tenantId`,
+`tenantUserId`, `consumerId`, `email`, `name`, `Authorization`, `platformId`,
+`parentTenantId`, `appId`, `X-Transaction-Id`, plus `traceparent`.
+
+## JWT parsing
+
+```python
+from mobius_tracer import parse_token, TokenError
+
+body = parse_token(jwt_string)   # decodes payload (no signature verification)
+body.tenant_id, body.requester_type, body.email
+```
+
+Raises `TokenError` (HTTP 401) for missing or malformed tokens. A non-empty
+`requester_type` claim is required.
+
+## Resource metrics
+
+With `measure_resources=True` (default), **every request** is measured and the
+metrics are attached to its OpenTelemetry span automatically. For a specific
+function or block:
+
+```python
+from mobius_tracer import measure_resources, measure
+
+@measure_resources
+async def heavy(): ...
+
+with measure():
+    do_work()
+```
+
+Span attributes: `wall_time_ms`, `cpu_used_ms`, `cpu_used_pct`, `cpu_cores`,
+`mem_rss_mb`, `mem_rss_delta_mb`, `mem_system_used_pct`. Best-effort; never
+raises. Uses `psutil` when installed.
+
+## Integrating with mobius-logging-py
+
+```python
+setup_tracer(app, integrate_logging=True)
+```
+
+When `mobius-logging-py` is installed, the middleware mirrors `tenant_id`,
+`trace_id`, `txn_id`, `agent_id`, and `correlation_id` into its logging context,
+so every log line carries the same identity fields.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

mobius_tracer_py-1.0.0/README.md

@@ -0,0 +1,158 @@
+# mobius-tracer-py
+
+Request-context propagation for Mobius **Python (FastAPI / Starlette)** services.
+
+On every incoming request it extracts identity/trace headers and the JWT
+payload, exposes them request-scoped, forwards them onto downstream calls, sets
+security + trace response headers, and enriches OpenTelemetry spans.
+
+- **PyPI:** `pip install mobius-tracer-py`
+- **Import package:** `mobius_tracer`
+- **Python:** 3.10+
+
+## Install
+
+```bash
+pip install mobius-tracer-py
+
+# optional features
+pip install "mobius-tracer-py[otel]"        # set OTel span attributes
+pip install "mobius-tracer-py[httpx]"       # TracedClient / httpx hook
+pip install "mobius-tracer-py[resources]"   # CPU/mem span metrics (psutil)
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI
+from mobius_tracer import setup_tracer, current
+
+app = FastAPI()
+setup_tracer(app)   # adds middleware + 401 handler for invalid tokens
+
+@app.get("/me")
+async def me():
+    ctx = current()
+    return {"tenant_id": ctx.tenant_id, "txn": ctx.req_transaction_id}
+```
+
+`setup_tracer` installs a middleware that, per request:
+
+1. extracts `x-request-id`, `x-b3-traceid`, `x-b3-spanid`, `Authorization`,
+   `appId`, `platformId`, and `X-Transaction-Id` (generated if absent);
+2. parses the JWT payload into the request context (tenant/agent/user/email …);
+3. derives `action_log_user_id` from the token;
+4. sets security response headers + `x-mb-trace-id` + `X-Transaction-Id`;
+5. sets OpenTelemetry span attributes (`txn.id`, `tenant.id`, `user.id`).
+
+### Options
+
+```python
+setup_tracer(
+    app,
+    skip_paths=("actuator", "health", "metrics", "error", "prometheus",
+                "swagger", "api-docs", "arazzo"),  # paths with no token check
+    require_token=True,          # 401 on protected paths without a valid token
+    set_security_headers=True,   # HSTS/CSP/X-Frame-Options/...
+    propagate_to_otel=True,      # txn/tenant/user span attributes
+    integrate_logging=True,      # mirror fields into mobius-logging-py context
+    measure_resources=True,      # CPU/mem of each request onto the span
+    instrument_httpx=False,      # patch httpx so all outbound calls propagate (opt-in)
+)
+```
+
+## Request context
+
+```python
+from mobius_tracer import current, get, HeadersHolder
+
+ctx = current()           # HeadersHolder for this request
+ctx.tenant_id             # e.g. "tenant-123"
+ctx.action_log_user_id    # derived user id
+get("trace_id")           # field accessor
+```
+
+Fields: `request_id`, `trace_id`, `span_id`, `tenant_id`, `tenant_user_id`,
+`consumer_id`, `email`, `authorization`, `name`, `requester_type`, `platform_id`,
+`parent_tenant_id`, `app_id`, `action_log_user_id`, `agent_id`, `agent_user_id`,
+`req_transaction_id`, `b_agent_id`.
+
+The context uses `contextvars`, so it is isolated per request and correct across
+`async` tasks and threads.
+
+## Propagating to downstream calls
+
+Forward the current context (and a W3C `traceparent`) to outbound requests:
+
+```python
+import httpx
+from mobius_tracer import traced_headers, httpx_auth_hook, TracedClient
+
+# 1) build headers yourself
+httpx.get(url, headers=traced_headers())
+
+# 2) an httpx event hook
+client = httpx.AsyncClient(event_hooks={"request": [httpx_auth_hook()]})
+
+# 3) a ready-made traced client
+with TracedClient(base_url="https://api.internal") as c:
+    c.get("/orders/1")
+
+# 4) globally patch httpx so ALL outbound calls propagate (internal-only!)
+from mobius_tracer import instrument_httpx
+instrument_httpx()   # or setup_tracer(app, instrument_httpx=True)
+```
+
+Forwarded headers: `x-request-id`, `x-b3-traceid`, `x-b3-spanid`, `tenantId`,
+`tenantUserId`, `consumerId`, `email`, `name`, `Authorization`, `platformId`,
+`parentTenantId`, `appId`, `X-Transaction-Id`, plus `traceparent`.
+
+## JWT parsing
+
+```python
+from mobius_tracer import parse_token, TokenError
+
+body = parse_token(jwt_string)   # decodes payload (no signature verification)
+body.tenant_id, body.requester_type, body.email
+```
+
+Raises `TokenError` (HTTP 401) for missing or malformed tokens. A non-empty
+`requester_type` claim is required.
+
+## Resource metrics
+
+With `measure_resources=True` (default), **every request** is measured and the
+metrics are attached to its OpenTelemetry span automatically. For a specific
+function or block:
+
+```python
+from mobius_tracer import measure_resources, measure
+
+@measure_resources
+async def heavy(): ...
+
+with measure():
+    do_work()
+```
+
+Span attributes: `wall_time_ms`, `cpu_used_ms`, `cpu_used_pct`, `cpu_cores`,
+`mem_rss_mb`, `mem_rss_delta_mb`, `mem_system_used_pct`. Best-effort; never
+raises. Uses `psutil` when installed.
+
+## Integrating with mobius-logging-py
+
+```python
+setup_tracer(app, integrate_logging=True)
+```
+
+When `mobius-logging-py` is installed, the middleware mirrors `tenant_id`,
+`trace_id`, `txn_id`, `agent_id`, and `correlation_id` into its logging context,
+so every log line carries the same identity fields.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```

mobius_tracer_py-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mobius-tracer-py"
+version = "1.0.0"
+description = "Request-context propagation, JWT parsing, security headers and OpenTelemetry enrichment for Mobius Python (FastAPI) services."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Mobius Platform" }]
+keywords = ["tracing", "context-propagation", "fastapi", "mobius", "opentelemetry"]
+dependencies = [
+    "starlette>=0.27",
+]
+
+[project.optional-dependencies]
+otel = ["opentelemetry-api>=1.20"]
+httpx = ["httpx>=0.24"]
+resources = ["psutil>=5.9"]
+banner = ["pyfiglet>=1.0"]
+dev = [
+    "pytest>=7.4",
+    "starlette>=0.27",
+    "httpx>=0.24",
+    "opentelemetry-api>=1.20",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mobius_tracer = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mobius_tracer_py-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mobius_tracer_py-1.0.0/src/mobius_tracer/__init__.py

@@ -0,0 +1,53 @@
+"""Mobius Tracer for Python.
+
+Request-context propagation for Mobius FastAPI services: extract identity/trace
+headers and the JWT payload from incoming requests, expose them request-scoped,
+forward them onto downstream calls, set security + trace response headers, and
+enrich OpenTelemetry spans.
+"""
+from __future__ import annotations
+
+from . import constants, context
+from .banner import print_banner
+from .bootstrap import setup_tracer
+from .context import HeadersHolder, clear, current, get, set_holder
+from .errors import TokenError
+from .middleware import IncomingRequestsMiddleware
+from .outgoing import (
+    TracedClient,
+    generate_traceparent,
+    httpx_auth_hook,
+    instrument_httpx,
+    outgoing_headers,
+    traced_headers,
+    uninstrument_httpx,
+)
+from .resources import measure, measure_resources
+from .token_parser import TokenBody, parse_token
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "constants",
+    "context",
+    "setup_tracer",
+    "IncomingRequestsMiddleware",
+    "HeadersHolder",
+    "current",
+    "get",
+    "set_holder",
+    "clear",
+    "TokenError",
+    "TokenBody",
+    "parse_token",
+    "outgoing_headers",
+    "traced_headers",
+    "generate_traceparent",
+    "httpx_auth_hook",
+    "instrument_httpx",
+    "uninstrument_httpx",
+    "TracedClient",
+    "measure",
+    "measure_resources",
+    "print_banner",
+]

mobius_tracer_py-1.0.0/src/mobius_tracer/banner.py

@@ -0,0 +1,16 @@
+"""Optional startup ASCII banner."""
+from __future__ import annotations
+
+
+def print_banner(app_name: str = "APPLICATION", version: str = "1.0") -> None:
+    name = app_name.upper()
+    try:
+        import pyfiglet  # type: ignore
+
+        art = pyfiglet.figlet_format(name)
+    except Exception:  # noqa: BLE001 - pyfiglet optional / any render failure
+        art = f":: {name} ::"
+    cyan, yellow, reset = "\033[36m", "\033[33m", "\033[0m"
+    print(f"{cyan}{art}{reset}")
+    print(f"{yellow} :: {name} ::        v{version}{reset}")
+    print("-" * 80)

mobius_tracer_py-1.0.0/src/mobius_tracer/bootstrap.py

@@ -0,0 +1,71 @@
+"""One-call setup for FastAPI services.
+
+Registers the incoming-request middleware and a handler that turns
+:class:`TokenError` into a JSON 401/4xx response.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from . import constants
+from .errors import TokenError
+from .middleware import IncomingRequestsMiddleware
+
+
+def setup_tracer(
+    app: Any,
+    *,
+    skip_paths: Iterable[str] = constants.DEFAULT_SKIP_PATHS,
+    require_token: bool = True,
+    set_security_headers: bool = True,
+    propagate_to_otel: bool = True,
+    integrate_logging: bool = True,
+    measure_resources: bool = True,
+    instrument_httpx: bool = False,
+    register_error_handler: bool = True,
+) -> None:
+    """Wire the tracer into a FastAPI/Starlette ``app``.
+
+    Per request the middleware extracts identity/trace context, sets security +
+    trace response headers, enriches the OpenTelemetry span, and:
+
+    - ``integrate_logging`` (default on): mirror identity/trace fields into the
+      mobius-logging-py context when that package is installed (a no-op
+      otherwise), so every log line carries them.
+    - ``measure_resources`` (default on): record CPU/memory of each request onto
+      the active span.
+    - ``instrument_httpx``: globally patch httpx so ALL outbound calls propagate
+      the context. Off by default - it forwards auth/tenant headers to every
+      httpx call, so only enable it when all outbound calls are internal. For
+      targeted propagation use ``TracedClient`` / ``httpx_auth_hook`` instead.
+    """
+    app.add_middleware(
+        IncomingRequestsMiddleware,
+        skip_paths=skip_paths,
+        require_token=require_token,
+        set_security_headers=set_security_headers,
+        propagate_to_otel=propagate_to_otel,
+        integrate_logging=integrate_logging,
+        measure_resources=measure_resources,
+    )
+
+    if instrument_httpx:
+        from .outgoing import instrument_httpx as _instrument
+
+        _instrument()
+
+    if register_error_handler:
+        _register_error_handler(app)
+
+
+def _register_error_handler(app: Any) -> None:
+    try:
+        from starlette.responses import JSONResponse
+    except ImportError:  # pragma: no cover
+        return
+
+    async def _token_error_handler(_request, exc: TokenError):  # noqa: ANN001
+        return JSONResponse(status_code=exc.status_code, content=exc.to_response())
+
+    # add_exception_handler works on both Starlette and FastAPI apps.
+    app.add_exception_handler(TokenError, _token_error_handler)

mobius_tracer_py-1.0.0/src/mobius_tracer/constants.py

@@ -0,0 +1,55 @@
+"""Header names and security-header values.
+
+Defines the wire headers Mobius services propagate so identity and trace
+context stays consistent across the platform.
+"""
+from __future__ import annotations
+
+# --- incoming / outgoing identity + trace headers ---
+BAGENT_ID_HEADER = "bAgentId"
+TX_ID_HEADER = "X-Transaction-Id"
+MB_TRACE_RESPONSE_HEADER = "x-mb-trace-id"
+HEADER_REQUEST_ID = "x-request-id"
+HEADER_TRACE_ID = "x-b3-traceid"
+HEADER_SPAN_ID = "x-b3-spanid"
+REQUESTER_TYPE = "RequesterType"
+
+HEADER_TOKEN = "token"
+HEADER_AUTHORIZATION = "Authorization"
+HEADER_TENANT_ID = "tenantId"
+HEADER_TENANT_USERID = "tenantUserId"
+HEADER_CONSUMERID = "consumerId"
+HEADER_EMAIL = "email"
+HEADER_NAME = "name"
+HEADER_PLATFORMID = "platformId"
+HEADER_PARENT_TENANTID = "parentTenantId"
+HEADER_APPID = "appId"
+HEADER_ACTIONLOG_USERID = "actionLogUserId"
+HEADER_AGENT_TENANT_ID = "agentId"
+HEADER_AGENT_USER_ID = "agentUserId"
+HEADER_SERVICE_ID = "serviceId"
+
+JWT_PREFIX = "Bearer"
+
+# --- security response headers ---
+SECURITY_HEADERS = {
+    "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+    "Content-Security-Policy": "default-src 'self'",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "X-XSS-Protection": "1; mode=block",
+    "Permissions-Policy": "no-referrer",
+    "Referrer-Policy": "geolocation=(self)",
+}
+
+# Default paths excluded from token validation / context extraction.
+DEFAULT_SKIP_PATHS = (
+    "actuator",
+    "health",
+    "metrics",
+    "error",
+    "prometheus",
+    "swagger",
+    "api-docs",
+    "arazzo",
+)

mobius_tracer_py-1.0.0/src/mobius_tracer/context.py

@@ -0,0 +1,84 @@
+"""Request-scoped header context.
+
+Holds the identity/trace fields extracted from an incoming request. Backed by a
+:class:`contextvars.ContextVar` so each request/task has isolated state across
+threads and ``asyncio`` tasks.
+"""
+from __future__ import annotations
+
+import contextvars
+from dataclasses import asdict, dataclass, fields
+from typing import Dict, Optional
+
+# Field name -> outbound header name (used by the outgoing propagator).
+OUTGOING_HEADER_MAP = {
+    "request_id": "x-request-id",
+    "trace_id": "x-b3-traceid",
+    "span_id": "x-b3-spanid",
+    "tenant_id": "tenantId",
+    "tenant_user_id": "tenantUserId",
+    "consumer_id": "consumerId",
+    "email": "email",
+    "name": "name",
+    "authorization": "Authorization",
+    "platform_id": "platformId",
+    "parent_tenant_id": "parentTenantId",
+    "app_id": "appId",
+    "req_transaction_id": "X-Transaction-Id",
+}
+
+
+@dataclass
+class HeadersHolder:
+    request_id: Optional[str] = None
+    trace_id: Optional[str] = None
+    span_id: Optional[str] = None
+    tenant_id: Optional[str] = None
+    tenant_user_id: Optional[str] = None
+    consumer_id: Optional[str] = None
+    email: Optional[str] = None
+    authorization: Optional[str] = None
+    name: Optional[str] = None
+    requester_type: Optional[str] = None
+    platform_id: Optional[str] = None
+    parent_tenant_id: Optional[str] = None
+    app_id: Optional[str] = None
+    action_log_user_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    agent_user_id: Optional[str] = None
+    req_transaction_id: Optional[str] = None
+    b_agent_id: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Optional[str]]:
+        return asdict(self)
+
+
+_holder: contextvars.ContextVar[Optional[HeadersHolder]] = contextvars.ContextVar(
+    "mobius_tracer_headers", default=None
+)
+
+
+def set_holder(holder: HeadersHolder) -> None:
+    _holder.set(holder)
+
+
+def current() -> HeadersHolder:
+    """Return the holder for the current request (empty one if unset)."""
+    holder = _holder.get()
+    if holder is None:
+        holder = HeadersHolder()
+        _holder.set(holder)
+    return holder
+
+
+def get(field_name: str) -> Optional[str]:
+    return getattr(current(), field_name, None)
+
+
+def clear() -> None:
+    _holder.set(HeadersHolder())
+
+
+# Validate the outgoing map references real fields at import time.
+_VALID = {f.name for f in fields(HeadersHolder)}
+assert set(OUTGOING_HEADER_MAP).issubset(_VALID), "OUTGOING_HEADER_MAP has unknown fields"