debugbundle-python 0.1.0__py3-none-any.whl

debugbundle/integrations/__init__.py

@@ -0,0 +1,16 @@
+from .django import DebugBundleDjangoMiddleware
+from .fastapi import DebugBundleFastAPIMiddleware, instrument_fastapi
+from .flask import instrument_flask
+from .relay_django import create_django_relay_view
+from .relay_fastapi import create_fastapi_relay_handler
+from .relay_flask import create_flask_relay_handler
+
+__all__ = [
+    "DebugBundleDjangoMiddleware",
+    "DebugBundleFastAPIMiddleware",
+    "create_django_relay_view",
+    "create_fastapi_relay_handler",
+    "create_flask_relay_handler",
+    "instrument_fastapi",
+    "instrument_flask",
+]

debugbundle/integrations/common.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any
+
+from ..core import DebugBundleSdk
+
+TRACE_ID_HEADER = "x-debugbundle-trace-id"
+REQUEST_ID_HEADERS = ("x-request-id", "x-correlation-id")
+
+
+def now_seconds() -> float:
+    return time.time()
+
+
+def duration_ms(started_at: float, finished_at: float | None = None) -> int:
+    end = now_seconds() if finished_at is None else finished_at
+    return max(0, int((end - started_at) * 1000))
+
+
+def normalize_headers(headers: Mapping[str, Any]) -> dict[str, str]:
+    normalized: dict[str, str] = {}
+    for key, value in headers.items():
+        normalized[str(key).lower()] = str(value)
+    return normalized
+
+
+def correlation_context(headers: Mapping[str, Any]) -> dict[str, str]:
+    normalized = normalize_headers(headers)
+    context: dict[str, str] = {}
+    trace_id = normalized.get(TRACE_ID_HEADER)
+    if trace_id:
+        context["trace_id"] = trace_id
+    for header_name in REQUEST_ID_HEADERS:
+        request_id = normalized.get(header_name)
+        if request_id:
+            context["request_id"] = request_id
+            break
+    return context
+
+
+def normalize_query_items(items: Mapping[str, Any] | None = None) -> dict[str, str]:
+    if items is None:
+        return {}
+    return {str(key): str(value) for key, value in items.items()}
+
+
+def request_payload(
+    *,
+    method: str,
+    path: str,
+    headers: Mapping[str, Any],
+    query: Mapping[str, Any] | None = None,
+) -> dict[str, object]:
+    return {
+        "method": method,
+        "path": path,
+        "headers": normalize_headers(headers),
+        "query": normalize_query_items(query),
+    }
+
+
+def response_payload(*, status_code: int, started_at: float) -> dict[str, object]:
+    return {
+        "status_code": status_code,
+        "duration_ms": duration_ms(started_at),
+    }
+
+
+def resolve_sdk(sdk: DebugBundleSdk | None) -> DebugBundleSdk:
+    if sdk is not None:
+        return sdk
+
+    from .. import _sdk
+
+    return _sdk

debugbundle/integrations/django.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .common import correlation_context, request_payload, resolve_sdk, response_payload
+
+
+class DebugBundleDjangoMiddleware:
+    def __init__(self, get_response: Any, sdk: Any = None) -> None:
+        self._get_response = get_response
+        self._sdk = resolve_sdk(sdk)
+        self._sdk.capture_logging()
+
+    def __call__(self, request: Any) -> Any:
+        started_at = self._sdk._time_provider()
+        context_token = self._sdk._bind_scoped_context(correlation_context(request.headers))
+        trigger_token = self._sdk.begin_request(
+            request_payload(
+                method=request.method,
+                path=request.path,
+                headers=request.headers,
+                query=request.GET,
+            )
+        )
+        try:
+            response = self._get_response(request)
+        except Exception as error:
+            self._sdk.capture_exception(
+                error,
+                context={
+                    "request": request_payload(
+                        method=request.method,
+                        path=request.path,
+                        headers=request.headers,
+                        query=request.GET,
+                    )
+                },
+            )
+            raise
+        else:
+            self._sdk.capture_request(
+                request_payload(
+                    method=request.method,
+                    path=request.path,
+                    headers=request.headers,
+                    query=request.GET,
+                ),
+                response_payload(status_code=response.status_code, started_at=started_at),
+            )
+            return response
+        finally:
+            self._sdk.end_request(trigger_token)
+            self._sdk._reset_scoped_context(context_token)

debugbundle/integrations/fastapi.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .common import correlation_context, request_payload, resolve_sdk, response_payload
+
+
+class DebugBundleFastAPIMiddleware:
+    def __init__(self, app: Any, sdk: Any) -> None:
+        self.app = app
+        self.sdk = resolve_sdk(sdk)
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = {
+            key.decode("latin-1"): value.decode("latin-1")
+            for key, value in scope.get("headers", [])
+        }
+        query_string = scope.get("query_string", b"").decode("latin-1")
+        query: dict[str, str] = {}
+        if query_string:
+            for pair in query_string.split("&"):
+                if not pair:
+                    continue
+                key, _, value = pair.partition("=")
+                query[key] = value
+
+        started_at = self.sdk._time_provider()
+        status_holder: dict[str, int] = {}
+        context_token = self.sdk._bind_scoped_context(correlation_context(headers))
+        trigger_token = self.sdk.begin_request(
+            request_payload(
+                method=scope.get("method", "GET"),
+                path=scope.get("path", "/"),
+                headers=headers,
+                query=query,
+            )
+        )
+
+        async def wrapped_send(message: dict[str, Any]) -> None:
+            if message.get("type") == "http.response.start":
+                status_holder["status_code"] = int(message.get("status", 200))
+            await send(message)
+
+        try:
+            await self.app(scope, receive, wrapped_send)
+        except Exception as error:
+            self.sdk.capture_request(
+                request_payload(
+                    method=scope.get("method", "GET"),
+                    path=scope.get("path", "/"),
+                    headers=headers,
+                    query=query,
+                ),
+                response_payload(status_code=500, started_at=started_at),
+            )
+            self.sdk.capture_exception(
+                error,
+                context={
+                    "request": request_payload(
+                        method=scope.get("method", "GET"),
+                        path=scope.get("path", "/"),
+                        headers=headers,
+                        query=query,
+                    )
+                },
+            )
+            raise
+        finally:
+            status_code = status_holder.get("status_code")
+            try:
+                if status_code is not None:
+                    self.sdk.capture_request(
+                        request_payload(
+                            method=scope.get("method", "GET"),
+                            path=scope.get("path", "/"),
+                            headers=headers,
+                            query=query,
+                        ),
+                        response_payload(status_code=status_code, started_at=started_at),
+                    )
+            finally:
+                self.sdk.end_request(trigger_token)
+                self.sdk._reset_scoped_context(context_token)
+
+
+def instrument_fastapi(app: Any, sdk: Any = None) -> Any:
+    resolved_sdk = resolve_sdk(sdk)
+    resolved_sdk.capture_logging()
+    app.add_middleware(DebugBundleFastAPIMiddleware, sdk=resolved_sdk)
+    return app

debugbundle/integrations/flask.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .common import correlation_context, request_payload, resolve_sdk, response_payload
+
+
+def instrument_flask(app: Any, sdk: Any = None) -> Any:
+    resolved_sdk = resolve_sdk(sdk)
+    resolved_sdk.capture_logging(app.logger)
+
+    from flask import g, request
+
+    @app.before_request
+    def debugbundle_before_request() -> None:
+        g._debugbundle_started_at = resolved_sdk._time_provider()
+        g._debugbundle_context_token = resolved_sdk._bind_scoped_context(
+            correlation_context(dict(request.headers.items()))
+        )
+        g._debugbundle_trigger_token = resolved_sdk.begin_request(
+            request_payload(
+                method=request.method,
+                path=request.path,
+                headers=dict(request.headers.items()),
+                query=dict(request.args.items()),
+            )
+        )
+
+    @app.after_request
+    def debugbundle_after_request(response: Any) -> Any:
+        started_at = getattr(g, "_debugbundle_started_at", resolved_sdk._time_provider())
+        resolved_sdk.capture_request(
+            request_payload(
+                method=request.method,
+                path=request.path,
+                headers=dict(request.headers.items()),
+                query=dict(request.args.items()),
+            ),
+            response_payload(status_code=response.status_code, started_at=started_at),
+        )
+        return response
+
+    @app.teardown_request
+    def debugbundle_teardown_request(error: BaseException | None) -> None:
+        token = getattr(g, "_debugbundle_context_token", None)
+        trigger_token = getattr(g, "_debugbundle_trigger_token", None)
+        try:
+            if error is None:
+                return
+            resolved_sdk.capture_exception(
+                error,
+                context={
+                    "request": request_payload(
+                        method=request.method,
+                        path=request.path,
+                        headers=dict(request.headers.items()),
+                        query=dict(request.args.items()),
+                    ),
+                },
+            )
+        finally:
+            if trigger_token is not None:
+                resolved_sdk.end_request(trigger_token)
+            if token is not None:
+                resolved_sdk._reset_scoped_context(token)
+
+    return app

debugbundle/integrations/relay_django.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..relay import BrowserRelayHandler
+
+
+def create_django_relay_view(
+    *,
+    allowed_origins: list[str] | None = None,
+    max_body_bytes: int = 262_144,
+    rate_limit_per_minute: int = 60,
+    on_accept: Any = None,
+) -> Any:
+    handler = BrowserRelayHandler(
+        allowed_origins=allowed_origins or [],
+        max_body_bytes=max_body_bytes,
+        rate_limit_per_minute=rate_limit_per_minute,
+        on_accept=on_accept,
+    )
+
+    def view(request: Any) -> Any:
+        from django.http import JsonResponse  # type: ignore[import-untyped]
+
+        headers: dict[str, str] = {}
+        if hasattr(request, "headers"):
+            headers = {str(key).lower(): str(value) for key, value in request.headers.items()}
+
+        response = handler.handle(
+            {
+                "method": request.method,
+                "headers": headers,
+                "body": request.body.decode("utf-8") if isinstance(request.body, bytes) else str(request.body),
+                "ipAddress": _get_client_ip(request),
+            }
+        )
+
+        if response.body is not None:
+            return JsonResponse(response.body, status=response.status, safe=False)
+
+        return JsonResponse({}, status=response.status)
+
+    return view
+
+
+def _get_client_ip(request: Any) -> str | None:
+    forwarded = request.META.get("HTTP_X_FORWARDED_FOR")
+    if forwarded:
+        return str(forwarded).split(",")[0].strip()
+    return request.META.get("REMOTE_ADDR")

debugbundle/integrations/relay_fastapi.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from ..relay import BrowserRelayHandler
+
+
+def create_fastapi_relay_handler(
+    *,
+    allowed_origins: list[str] | None = None,
+    max_body_bytes: int = 262_144,
+    rate_limit_per_minute: int = 60,
+    on_accept: Any = None,
+    route_path: str = "/debugbundle/browser",
+) -> Any:
+    handler = BrowserRelayHandler(
+        allowed_origins=allowed_origins or [],
+        max_body_bytes=max_body_bytes,
+        rate_limit_per_minute=rate_limit_per_minute,
+        on_accept=on_accept,
+    )
+
+    def register(app: Any) -> None:
+        @app.post(route_path)
+        async def debugbundle_browser_relay(request: Request) -> Response:
+            body = await request.body()
+            headers = {str(key): str(value) for key, value in request.headers.items()}
+            ip_address = request.client.host if request.client else None
+
+            response = handler.handle(
+                {
+                    "method": request.method,
+                    "headers": headers,
+                    "body": body.decode("utf-8") if isinstance(body, bytes) else str(body),
+                    "ipAddress": ip_address,
+                }
+            )
+
+            if response.body is not None:
+                return JSONResponse(content=response.body, status_code=response.status)
+            return Response(status_code=response.status)
+
+    return register

debugbundle/integrations/relay_flask.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..relay import BrowserRelayHandler
+
+
+def create_flask_relay_handler(
+    *,
+    allowed_origins: list[str] | None = None,
+    max_body_bytes: int = 262_144,
+    rate_limit_per_minute: int = 60,
+    on_accept: Any = None,
+    route_path: str = "/debugbundle/browser",
+) -> Any:
+    handler = BrowserRelayHandler(
+        allowed_origins=allowed_origins or [],
+        max_body_bytes=max_body_bytes,
+        rate_limit_per_minute=rate_limit_per_minute,
+        on_accept=on_accept,
+    )
+
+    def register(app: Any) -> None:
+        from flask import Response, request
+
+        @app.route(route_path, methods=["POST"])
+        def debugbundle_browser_relay() -> Response:
+            response = handler.handle(
+                {
+                    "method": request.method,
+                    "headers": dict(request.headers.items()),
+                    "body": request.get_data(as_text=True),
+                    "ipAddress": request.remote_addr,
+                }
+            )
+
+            import json
+
+            body = json.dumps(response.body) if response.body is not None else ""
+            return Response(
+                body,
+                status=response.status,
+                content_type="application/json",
+            )
+
+    return register

debugbundle/logger_integrations.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class LogCaptureApi(Protocol):
+    def capture_log(
+        self,
+        message: str,
+        level: str = "warning",
+        context: dict[str, object] | None = None,
+    ) -> None: ...
+
+
+def attach_optional_integrations(
+    sdk: LogCaptureApi,
+    on_diagnostic: Callable[[dict[str, object]], None] | None = None,
+) -> list[Callable[[], None]]:
+    restorers: list[Callable[[], None]] = []
+
+    structlog_restore = _attach_structlog(sdk, on_diagnostic=on_diagnostic)
+    if structlog_restore is not None:
+        restorers.append(structlog_restore)
+
+    loguru_restore = _attach_loguru(sdk, on_diagnostic=on_diagnostic)
+    if loguru_restore is not None:
+        restorers.append(loguru_restore)
+
+    return restorers
+
+
+def _attach_structlog(
+    sdk: LogCaptureApi,
+    on_diagnostic: Callable[[dict[str, object]], None] | None = None,
+) -> Callable[[], None] | None:
+    try:
+        import structlog
+    except Exception:
+        return None
+
+    try:
+        original_get_logger = structlog.get_logger
+        if getattr(original_get_logger, "__debugbundle_structlog_wrapper__", False):
+            return None
+
+        def get_logger(*args: Any, **kwargs: Any) -> Any:
+            return _StructlogLoggerProxy(original_get_logger(*args, **kwargs), sdk)
+
+        setattr(get_logger, "__debugbundle_structlog_wrapper__", True)
+        structlog.get_logger = get_logger
+
+        def restore() -> None:
+            structlog.get_logger = original_get_logger
+
+        return restore
+    except Exception as error:
+        _emit_diagnostic(on_diagnostic, error)
+        return None
+
+
+def _attach_loguru(
+    sdk: LogCaptureApi,
+    on_diagnostic: Callable[[dict[str, object]], None] | None = None,
+) -> Callable[[], None] | None:
+    try:
+        from loguru import logger as loguru_logger
+    except Exception:
+        return None
+
+    try:
+        def sink(message: Any) -> None:
+            record = getattr(message, "record", None)
+            if not isinstance(record, dict):
+                return
+            context = dict(record.get("extra") or {})
+            sdk.capture_log(
+                str(record.get("message") or ""),
+                level=_normalize_level(str(getattr(record.get("level"), "name", "warning"))),
+                context=context or None,
+            )
+
+        sink_id = loguru_logger.add(sink, catch=True)
+
+        def restore() -> None:
+            loguru_logger.remove(sink_id)
+
+        return restore
+    except Exception as error:
+        _emit_diagnostic(on_diagnostic, error)
+        return None
+
+
+def _normalize_level(level: str) -> str:
+    normalized = level.lower().strip()
+    if normalized == "warn":
+        return "warning"
+    if normalized == "exception":
+        return "error"
+    return normalized
+
+
+class _StructlogLoggerProxy:
+    def __init__(self, logger: Any, sdk: LogCaptureApi) -> None:
+        self._logger = logger
+        self._sdk = sdk
+
+    def bind(self, *args: Any, **kwargs: Any) -> _StructlogLoggerProxy:
+        return _StructlogLoggerProxy(self._logger.bind(*args, **kwargs), self._sdk)
+
+    def new(self, *args: Any, **kwargs: Any) -> _StructlogLoggerProxy:
+        return _StructlogLoggerProxy(self._logger.new(*args, **kwargs), self._sdk)
+
+    def __getattr__(self, name: str) -> Any:
+        attribute = getattr(self._logger, name)
+        if name not in {
+            "debug",
+            "info",
+            "warning",
+            "warn",
+            "error",
+            "critical",
+            "exception",
+        } or not callable(attribute):
+            return attribute
+
+        def wrapped(event: Any = None, *args: Any, **kwargs: Any) -> Any:
+            context = dict(kwargs)
+            for index, value in enumerate(args):
+                context[f"arg_{index}"] = value
+            self._sdk.capture_log(str(event or ""), level=_normalize_level(name), context=context or None)
+            return attribute(event, *args, **kwargs)
+
+        return wrapped
+
+
+def _emit_diagnostic(
+    on_diagnostic: Callable[[dict[str, object]], None] | None,
+    error: Exception,
+) -> None:
+    if on_diagnostic is None:
+        return
+    on_diagnostic(
+        {
+            "code": "logger_attach_failed",
+            "message": "sdk-python failed to attach a logger integration",
+            "metadata": {
+                "error": {
+                    "name": type(error).__name__,
+                    "message": str(error),
+                }
+            },
+        }
+    )

debugbundle/redaction.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+DEFAULT_REDACT_FIELDS = {
+    "authorization",
+    "cookie",
+    "credit_card",
+    "password",
+    "secret",
+    "ssn",
+    "token",
+}
+
+REDACTED_VALUE = "[REDACTED]"
+
+
+def redact_value(value: Any, redact_fields: set[str]) -> Any:
+    if isinstance(value, Mapping):
+        return {
+            key: REDACTED_VALUE if key.lower() in redact_fields else redact_value(nested_value, redact_fields)
+            for key, nested_value in value.items()
+        }
+
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [redact_value(item, redact_fields) for item in value]
+
+    return value