debugbundle-python 2.0.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

debugbundle/__init__.py

@@ -33,6 +33,9 @@ def init(
     on_diagnostic: Callable[[dict[str, object]], None] | None = None,
     before_send: BeforeSendHook | None = None,
     probes_poll_interval: int = 60_000,
+    capture_exception_evidence: bool = True,
+    evidence_capabilities: object = None,
+    capture_recovery_observations: bool = False,
 ) -> None:
     _sdk.init(
         project_token=project_token,
@@ -52,6 +55,9 @@ def init(
         on_diagnostic=on_diagnostic,
         before_send=before_send,
         probes_poll_interval=probes_poll_interval,
+        capture_exception_evidence=capture_exception_evidence,
+        evidence_capabilities=evidence_capabilities,
+        capture_recovery_observations=capture_recovery_observations,
     )
 
 
@@ -63,6 +69,14 @@ def capture_error(error: BaseException, context: dict[str, object] | None = None
     _sdk.capture_error(error, context=context)
 
 
+def operation_context(options: object) -> Any:
+    return _sdk.operation_context(options)
+
+
+def capture_recovery(observation: object) -> None:
+    _sdk.capture_recovery(observation)
+
+
 def capture_log(message: str, level: str = "warning", context: dict[str, object] | None = None) -> None:
     _sdk.capture_log(message, level=level, context=context)
 
@@ -155,6 +169,7 @@ __all__ = [
     "capture_logging",
     "capture_message",
     "capture_request",
+    "capture_recovery",
     "create_django_relay_view",
     "create_fastapi_relay_handler",
     "create_flask_relay_handler",
@@ -164,5 +179,6 @@ __all__ = [
     "instrument_fastapi",
     "instrument_flask",
     "probe",
+    "operation_context",
     "set_context",
 ]

debugbundle/before_send.py

@@ -1,75 +1,37 @@
+"""Canonical, owned hook results with explicit invalid and exhausted outcomes."""
+
 from __future__ import annotations
 
 import copy
-import uuid
-from collections.abc import Callable, Mapping
-from datetime import datetime
+from collections.abc import Callable
+from typing import cast
+
+from .canonical_event import EXHAUSTED, INVALID, ValidationBudgetExceeded, own_json, valid_owned_event
+from .evidence_wire import validate_evidence
 
 BeforeSendHook = Callable[[dict[str, object]], dict[str, object] | None]
+_MOBILE = ("@debugbundle/sdk-android", "@debugbundle/sdk-swift", "@debugbundle/sdk-react-native")
 
-_EVENT_PAYLOAD_FIELDS: dict[str, tuple[str, ...]] = {
-    "backend_exception": ("name", "message", "stack", "handled", "request", "response", "runtime"),
-    "request_event": ("method", "path", "query", "headers", "response_status", "duration_ms"),
-    "log_event": ("level", "message", "attributes"),
-    "frontend_breadcrumb": ("breadcrumb_type", "data"),
-    "frontend_exception": ("name", "message", "stack"),
-    "deploy_metadata": ("commit_sha", "version", "branch", "environment", "deployed_at"),
-    "error_suppressed": (
-        "fingerprint",
-        "suppressed_count",
-        "window_seconds",
-        "first_seen",
-        "last_seen",
-    ),
-    "probe_event": ("label", "data", "activation_id", "probe_label_pattern"),
-}
-_EVENT_PAYLOAD_ALLOWED_FIELDS: dict[str, frozenset[str]] = {
-    "backend_exception": frozenset((*_EVENT_PAYLOAD_FIELDS["backend_exception"], "probe_data")),
-    "request_event": frozenset(
-        (
-            *_EVENT_PAYLOAD_FIELDS["request_event"],
-            "body",
-            "route_template",
-            "response_headers",
-            "response_body",
-            "device",
-        )
-    ),
-    "log_event": frozenset((*_EVENT_PAYLOAD_FIELDS["log_event"], "device")),
-    "frontend_breadcrumb": frozenset((*_EVENT_PAYLOAD_FIELDS["frontend_breadcrumb"], "route", "device")),
-    "frontend_exception": frozenset(
-        (
-            *_EVENT_PAYLOAD_FIELDS["frontend_exception"],
-            "route",
-            "browser",
-            "breadcrumbs",
-            "device",
-            "browser_event",
-            "rejection_reason",
-            "dom_context",
-            "probe_data",
-        )
-    ),
-    "deploy_metadata": frozenset(_EVENT_PAYLOAD_FIELDS["deploy_metadata"]),
-    "error_suppressed": frozenset((*_EVENT_PAYLOAD_FIELDS["error_suppressed"], "device")),
-    "probe_event": frozenset((*_EVENT_PAYLOAD_FIELDS["probe_event"], "device")),
-}
-_ROOT_FIELDS = frozenset(
-    (
-        "schema_version",
-        "event_id",
-        "event_type",
-        "project_token",
-        "project_id",
-        "sdk_name",
-        "sdk_version",
-        "service",
-        "occurred_at",
-        "correlation",
-        "context",
-        "payload",
-    )
-)
+
+def _normalized(event: object) -> object:
+    if type(event) is not dict:
+        return INVALID
+    owned = own_json(event)
+    if owned is INVALID or owned is EXHAUSTED:
+        return owned
+    try:
+        if not valid_owned_event(owned) or not validate_evidence(owned):
+            return INVALID
+        # The accepting Zod contract refines this condition outside JSON Schema.
+        if owned["event_type"] == "frontend_exception":
+            field = "device" if owned["sdk_name"] in _MOBILE else "browser"
+            if field not in owned["payload"] or type(owned["payload"][field]) is not dict:
+                return INVALID
+        return owned
+    except ValidationBudgetExceeded:
+        return EXHAUSTED
+    except Exception:
+        return INVALID
 
 
 def apply_before_send(
@@ -79,140 +41,22 @@ def apply_before_send(
 ) -> dict[str, object] | None:
     if hook is None:
         return event
-
     try:
         result = hook(copy.deepcopy(event))
     except Exception:
         emit_diagnostic("before_send_failed", "Python before_send hook failed")
         return event
-
     if result is None:
         return None
-    if not _is_valid_event(result):
+    checked = _normalized(result)
+    if checked is EXHAUSTED:
+        return None
+    if checked is INVALID:
         emit_diagnostic("before_send_invalid_event", "Python before_send returned an invalid event")
         return event
-    return result
+    return cast(dict[str, object], checked)
 
 
 def _is_valid_event(event: object) -> bool:
-    if not isinstance(event, dict):
-        return False
-    if not set(event).issubset(_ROOT_FIELDS):
-        return False
-    event_type = event.get("event_type")
-    if not isinstance(event_type, str) or event_type not in _EVENT_PAYLOAD_FIELDS:
-        return False
-    if not all(
-        isinstance(event.get(field), str) and event[field]
-        for field in ("schema_version", "sdk_name", "sdk_version", "occurred_at")
-    ):
-        return False
-    if not _timestamp(event["occurred_at"]):
-        return False
-    try:
-        uuid.UUID(str(event.get("event_id")))
-    except (ValueError, TypeError, AttributeError):
-        return False
-    service = event.get("service")
-    if (
-        not isinstance(service, dict)
-        or not isinstance(service.get("name"), str)
-        or not service["name"]
-        or not isinstance(service.get("environment"), str)
-        or not service["environment"]
-    ):
-        return False
-    payload = event.get("payload")
-    if not isinstance(payload, dict):
-        return False
-    if not set(payload).issubset(_EVENT_PAYLOAD_ALLOWED_FIELDS[event_type]):
-        return False
-    if not all(field in payload for field in _EVENT_PAYLOAD_FIELDS[event_type]):
-        return False
-    return _has_valid_payload_shape(event_type, payload)
-
-
-def _has_valid_payload_shape(event_type: str, payload: Mapping[object, object]) -> bool:
-    if event_type == "backend_exception":
-        return (
-            _has_nonempty_strings(payload, "name", "message", "stack")
-            and isinstance(payload["handled"], bool)
-            and all(isinstance(payload[field], dict) for field in ("request", "response", "runtime"))
-            and _optional_dict(payload, "probe_data")
-        )
-    if event_type == "request_event":
-        return (
-            _has_nonempty_strings(payload, "method", "path")
-            and all(isinstance(payload[field], dict) for field in ("query", "headers"))
-            and _nonnegative_number(payload["response_status"])
-            and _nonnegative_number(payload["duration_ms"])
-            and _optional_dict(payload, "response_headers")
-        )
-    if event_type == "log_event":
-        return _has_nonempty_strings(payload, "level", "message") and isinstance(payload["attributes"], dict)
-    if event_type == "frontend_breadcrumb":
-        return _has_nonempty_strings(payload, "breadcrumb_type") and isinstance(payload["data"], dict)
-    if event_type == "frontend_exception":
-        return (
-            _has_nonempty_strings(payload, "name", "message", "stack")
-            and (payload.get("breadcrumbs") is None or isinstance(payload["breadcrumbs"], list))
-            and _optional_dict(payload, "probe_data")
-        )
-    if event_type == "deploy_metadata":
-        return _has_nonempty_strings(payload, "commit_sha", "version", "branch", "environment") and _timestamp(
-            payload["deployed_at"]
-        )
-    if event_type == "error_suppressed":
-        return (
-            _has_nonempty_strings(payload, "fingerprint")
-            and _nonnegative_integer(payload["suppressed_count"])
-            and _positive_integer(payload["window_seconds"])
-            and _timestamp(payload["first_seen"])
-            and _timestamp(payload["last_seen"])
-        )
-    if event_type == "probe_event":
-        activation_id = payload["activation_id"]
-        return (
-            _has_nonempty_strings(payload, "label", "probe_label_pattern")
-            and isinstance(payload["data"], dict)
-            and (activation_id is None or _uuid(activation_id))
-        )
-    return False
-
-
-def _has_nonempty_strings(payload: Mapping[object, object], *fields: str) -> bool:
-    return all(isinstance(payload.get(field), str) and bool(str(payload[field]).strip()) for field in fields)
-
-
-def _optional_dict(payload: Mapping[object, object], field: str) -> bool:
-    return field not in payload or isinstance(payload[field], dict)
-
-
-def _nonnegative_number(value: object) -> bool:
-    return isinstance(value, (int, float)) and not isinstance(value, bool) and value >= 0
-
-
-def _nonnegative_integer(value: object) -> bool:
-    return isinstance(value, int) and not isinstance(value, bool) and value >= 0
-
-
-def _positive_integer(value: object) -> bool:
-    return isinstance(value, int) and not isinstance(value, bool) and value > 0
-
-
-def _uuid(value: object) -> bool:
-    try:
-        uuid.UUID(str(value))
-    except (ValueError, TypeError, AttributeError):
-        return False
-    return isinstance(value, str)
-
-
-def _timestamp(value: object) -> bool:
-    if not isinstance(value, str):
-        return False
-    try:
-        datetime.fromisoformat(value.replace("Z", "+00:00"))
-    except ValueError:
-        return False
-    return True
+    result = _normalized(event)
+    return result is not INVALID and result is not EXHAUSTED

debugbundle/canonical_event.py

@@ -0,0 +1,202 @@
+"""Owned JSON and a closed interpreter for the vendored accepting Draft 7 schema.
+
+Only native containers/scalars are inspected. No application serializers, remote
+references or optional runtime dependencies participate in hook validation.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from .evidence_wire import _timestamp, _uuid
+
+MAX_OWNED_BYTES = 8 * 1024 * 1024
+INVALID = object()
+EXHAUSTED = object()
+
+
+class ValidationBudgetExceeded(Exception):
+    """Withhold hook output rather than restore content it may have removed."""
+
+
+def own_json(value: object) -> Any:
+    remaining = MAX_OWNED_BYTES
+    nodes = 4096
+
+    def copy(item: Any, depth: int) -> Any:
+        nonlocal remaining, nodes
+        nodes -= 1
+        if nodes < 0 or depth > 16 or remaining < 0:
+            raise ValidationBudgetExceeded
+        kind = type(item)
+        if item is None or kind is bool:
+            remaining -= 5
+            return item
+        if kind is str:
+            if len(item) > remaining:
+                raise ValidationBudgetExceeded
+            remaining -= len(item.encode("utf-8")) + 2
+            if remaining < 0:
+                raise ValidationBudgetExceeded
+            return item
+        if kind is int or kind is float:
+            # The accepting JavaScript number domain is finite IEEE-754.
+            if not -1.7976931348623157e308 <= item <= 1.7976931348623157e308 or not math.isfinite(item):
+                raise ValueError("non-finite number")
+            remaining -= 24
+            return item
+        if kind is list:
+            if len(item) > nodes:
+                raise ValidationBudgetExceeded
+            remaining -= 2 + len(item)
+            return [copy(child, depth + 1) for child in item]
+        if kind is dict:
+            if len(item) * 2 > nodes:
+                raise ValidationBudgetExceeded
+            remaining -= 2 + 2 * len(item)
+            result = {}
+            for key, child in item.items():
+                if type(key) is not str:
+                    raise ValueError("non-string key")
+                result[copy(key, depth + 1)] = copy(child, depth + 1)
+            return result
+        raise ValueError("non-native JSON value")
+
+    try:
+        return copy(value, 0)
+    except ValidationBudgetExceeded:
+        return EXHAUSTED
+    except (ValueError, UnicodeError, OverflowError):
+        return INVALID
+
+
+class CanonicalEventSchema:
+    KEYWORDS = frozenset(
+        "$schema $id $comment $ref type anyOf const enum properties required additionalProperties "
+        "items minimum maximum exclusiveMinimum minLength maxLength minItems maxItems format pattern".split()
+    )
+    TYPES = frozenset("null boolean number integer string array object".split())
+
+    def __init__(self, schema: dict[str, Any]) -> None:
+        self.root = schema
+        self.references: dict[str, Any] = {}
+        self.patterns: dict[str, re.Pattern[str]] = {}
+        self._compile(schema)
+
+    def _resolve(self, reference: str) -> Any:
+        if not reference.startswith("#/"):
+            raise ValueError("external schema ref")
+        if reference not in self.references:
+            node: Any = self.root
+            for part in reference[2:].split("/"):
+                key = part.replace("~1", "/").replace("~0", "~")
+                node = node[int(key)] if type(node) is list else node[key]
+            self.references[reference] = node
+        return self.references[reference]
+
+    def _compile(self, node: Any) -> None:
+        if type(node) is bool:
+            return
+        if not set(node).issubset(self.KEYWORDS):
+            raise ValueError("unsupported schema keyword")
+        kinds = node.get("type", [])
+        if not set([kinds] if type(kinds) is str else kinds).issubset(self.TYPES):
+            raise ValueError("unsupported schema type")
+        if node.get("format") not in (None, "uuid", "date-time"):
+            raise ValueError("unsupported schema format")
+        if "pattern" in node:
+            self.patterns[node["pattern"]] = re.compile(node["pattern"])
+        if "$ref" in node:
+            self._resolve(node["$ref"])
+        for child in node.get("properties", {}).values():
+            self._compile(child)
+        for child in node.get("anyOf", []):
+            self._compile(child)
+        for key in ("items", "additionalProperties"):
+            if key in node:
+                self._compile(node[key])
+
+    def accepts(self, value: Any) -> bool:
+        return self._check(self.root, value, [100_000], 0)
+
+    def _check(self, node: Any, value: Any, budget: list[int], depth: int) -> bool:
+        budget[0] -= 1
+        if depth > 64 or budget[0] < 0:
+            raise ValidationBudgetExceeded
+        if type(node) is bool:
+            return node
+        if "$ref" in node:
+            return self._check(self._resolve(node["$ref"]), value, budget, depth + 1)
+        if "anyOf" in node and not any(self._check(child, value, budget, depth + 1) for child in node["anyOf"]):
+            return False
+        if "type" in node:
+            kinds = node["type"] if type(node["type"]) is list else [node["type"]]
+            if not any(self._type(value, kind) for kind in kinds):
+                return False
+        if "const" in node and not self._equal(value, node["const"]):
+            return False
+        if "enum" in node and not any(self._equal(value, choice) for choice in node["enum"]):
+            return False
+        if type(value) is dict:
+            properties = node.get("properties", {})
+            return all(key in value for key in node.get("required", [])) and all(
+                self._check(properties.get(key, node.get("additionalProperties", True)), child, budget, depth + 1)
+                for key, child in value.items()
+            )
+        if type(value) is list:
+            return (
+                len(value) >= node.get("minItems", 0)
+                and len(value) <= node.get("maxItems", len(value))
+                and (
+                    "items" not in node or all(self._check(node["items"], child, budget, depth + 1) for child in value)
+                )
+            )
+        if type(value) is str:
+            length = len(value.encode("utf-16-le")) // 2  # Zod counts JavaScript UTF-16 code units.
+            return (
+                length >= node.get("minLength", 0)
+                and length <= node.get("maxLength", length)
+                and ("pattern" not in node or bool(self.patterns[node["pattern"]].search(value)))
+                and (node.get("format") != "uuid" or _uuid(value))
+                and (node.get("format") != "date-time" or _timestamp(value))
+            )
+        if type(value) is int or type(value) is float:
+            return (
+                ("minimum" not in node or value >= node["minimum"])
+                and ("maximum" not in node or value <= node["maximum"])
+                and ("exclusiveMinimum" not in node or value > node["exclusiveMinimum"])
+            )
+        return True
+
+    @staticmethod
+    def _equal(value: Any, choice: Any) -> bool:
+        return (
+            type(value) is type(choice)
+            and value == choice
+            or (type(value) in (int, float) and type(choice) in (int, float) and value == choice)
+        )
+
+    @staticmethod
+    def _type(value: Any, kind: str) -> bool:
+        if kind == "number" or kind == "integer":
+            return type(value) in (int, float) and (kind == "number" or value == math.floor(value))
+        return type(value) is {"null": type(None), "boolean": bool, "string": str, "array": list, "object": dict}[kind]
+
+
+@lru_cache(maxsize=1)
+def _engine() -> CanonicalEventSchema:
+    return CanonicalEventSchema(json.loads(Path(__file__).with_name("event-envelope.schema.json").read_text()))
+
+
+def valid_owned_event(value: dict[str, Any]) -> bool:
+    try:
+        return _engine().accepts(value)
+    except ValidationBudgetExceeded:
+        raise
+    except Exception:
+        return False

debugbundle/config.py

@@ -22,6 +22,7 @@ class CapturePolicy:
     capture_probe_events: str
     immediate_client_error_statuses: tuple[int, ...]
     immediate_client_error_path_rules: tuple[ImmediateClientErrorPathRule, ...] = ()
+    capture_diagnostic_context: bool = True
 
 
 @dataclass(frozen=True)
@@ -61,6 +62,7 @@ MINIMAL_CAPTURE_POLICY = CapturePolicy(
     capture_probe_events="buffer_only",
     immediate_client_error_statuses=(),
     immediate_client_error_path_rules=(),
+    capture_diagnostic_context=False,
 )
 
 
@@ -147,6 +149,9 @@ def _parse_capture_policy(payload: object) -> CapturePolicy | None:
         return None
     if immediate_client_error_statuses is None or immediate_client_error_path_rules is None:
         return None
+    diagnostic = payload.get("capture_diagnostic_context", True)
+    if type(diagnostic) is not bool:
+        return None
 
     return CapturePolicy(
         preset=preset,
@@ -156,6 +161,7 @@ def _parse_capture_policy(payload: object) -> CapturePolicy | None:
         capture_probe_events=capture_probe_events,
         immediate_client_error_statuses=immediate_client_error_statuses,
         immediate_client_error_path_rules=immediate_client_error_path_rules,
+        capture_diagnostic_context=preset != "minimal" and diagnostic,
     )