insider-python 0.1.0__py3-none-any.whl

insider/contrib/django/middleware.py

@@ -0,0 +1,164 @@
+"""
+InsiderMiddleware: attach request context to the SDK scope, and
+auto-capture any unhandled exception that escapes a view.
+
+The middleware is a no-op when the SDK is in disabled mode.
+
+What we attach to the scope:
+
+  - method, path, route (URL name if available), query_string
+  - headers (post-scrubbing — note that scrubbing happens at envelope
+    build time, not here, so headers go on as-is and get masked just
+    before transport)
+  - body and user.id ONLY when `send_default_pii=True` in init()
+
+What we never touch:
+
+  - request.session
+  - file uploads
+  - anything from request.META not on the allowlist
+
+`process_exception` is Django's hook for "an exception escaped a view
+without being handled". We call `capture_exception` and then return
+None so Django continues its normal 500 handling.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from ... import capture_exception
+from ...client import _client
+from ...safety import debug, safe
+
+
+# Request headers that are safe to forward to the dashboard. We keep an
+# allow-list rather than a deny-list because there are too many possible
+# custom headers to enumerate scary ones. Scrubbing further masks names
+# matching the default deny-list (Authorization, Cookie, etc.) at envelope
+# build time.
+_SAFE_HEADERS = {
+    "accept",
+    "accept-encoding",
+    "accept-language",
+    "content-type",
+    "content-length",
+    "host",
+    "referer",
+    "user-agent",
+    "x-forwarded-for",
+    "x-real-ip",
+    "x-request-id",
+}
+
+
+class InsiderMiddleware:
+    """
+    Django middleware. Installs request context on the SDK scope, then
+    captures any unhandled exception with that context attached.
+    """
+
+    def __init__(self, get_response: Callable[[Any], Any]) -> None:
+        self.get_response = get_response
+
+    @safe
+    def __call__(self, request: Any) -> Any:
+        client = _client()
+        if client is None:
+            return self.get_response(request)
+
+        ctx = self._build_request_ctx(request, client.send_default_pii)
+        client.scope.set_request(ctx)
+        try:
+            return self.get_response(request)
+        finally:
+            client.scope.clear_request()
+
+    @safe
+    def process_exception(self, request: Any, exception: BaseException) -> None:
+        # Scope's already set in __call__; capture inherits the request ctx.
+        capture_exception(exception)
+        return None  # let Django render the 500
+
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _build_request_ctx(request: Any, send_default_pii: bool) -> Dict[str, Any]:
+        try:
+            method = getattr(request, "method", None)
+            path = getattr(request, "path", None)
+            query = getattr(request, "META", {}).get("QUERY_STRING") or None
+            route = None
+            try:
+                # ResolverMatch is set after urls resolve; in middleware
+                # __call__ before view, it's usually None. We still try.
+                match = getattr(request, "resolver_match", None)
+                if match is not None:
+                    route = match.view_name
+            except Exception:
+                pass
+
+            headers = _extract_headers(getattr(request, "META", {}))
+
+            ctx: Dict[str, Any] = {
+                "method": method,
+                "path": path,
+                "query_string": query,
+                "route": route,
+                "headers": headers,
+            }
+
+            if send_default_pii:
+                ctx["body"] = _read_body(request)
+                user = getattr(request, "user", None)
+                user_id = getattr(user, "id", None) if user is not None else None
+                if user_id is not None:
+                    ctx["user"] = {"id": user_id}
+
+            return ctx
+        except Exception as exc:
+            debug(f"request ctx build failed: {exc}")
+            return {}
+
+
+def _extract_headers(meta: Dict[str, Any]) -> Dict[str, str]:
+    """Convert Django's META dict into a real headers dict, allow-listed."""
+    headers: Dict[str, str] = {}
+    for key, value in meta.items():
+        if not key.startswith("HTTP_") and key not in (
+            "CONTENT_TYPE",
+            "CONTENT_LENGTH",
+        ):
+            continue
+        name = key
+        if key.startswith("HTTP_"):
+            name = key[len("HTTP_") :]
+        name = name.replace("_", "-").lower()
+        if name not in _SAFE_HEADERS:
+            # We still include unknown headers; the scrubber will mask any
+            # whose name is in the deny-list. But we cap obviously huge or
+            # weird ones here.
+            if len(str(value)) > 4096:
+                continue
+        try:
+            headers[name] = str(value)
+        except Exception:
+            pass
+    return headers
+
+
+def _read_body(request: Any) -> Optional[str]:
+    """
+    Return a string version of the request body, or None.
+    We don't consume `request.body` if it hasn't been read yet, to avoid
+    breaking downstream views; if it's accessible, we take it.
+    """
+    try:
+        raw = getattr(request, "body", None)
+        if raw is None:
+            return None
+        if isinstance(raw, bytes):
+            return raw.decode("utf-8", errors="replace")
+        return str(raw)
+    except Exception:
+        return None

insider/dsn.py

@@ -0,0 +1,92 @@
+"""
+DSN string parsing and validation.
+
+A DSN is the single string the customer pastes into their config. It
+encodes everything the SDK needs to know about which server to beam
+beacons at and which credential to use:
+
+    {scheme}://{beacon_token}@{host}/{project_public_id}
+
+Example:
+
+    https://abc...xyz@insider.example.com/3c29b8cb-1fe9-4b42-94a0-28d016cb20f9
+
+The endpoint path (`/api/v1/beam/<uuid>/`) is *not* in the DSN. We hard-
+code it on the SDK side so we can change the server's URL layout later
+without breaking SDKs already in the wild.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlparse
+from uuid import UUID
+
+
+class InvalidDSNError(ValueError):
+    """Raised when a DSN string can't be parsed into a usable shape."""
+
+
+@dataclass(frozen=True)
+class DSN:
+    """A parsed DSN. Immutable; safe to share across threads."""
+
+    scheme: str
+    host: str
+    token: str
+    project_id: str
+
+    @classmethod
+    def parse(cls, raw: str) -> "DSN":
+        if not raw or not isinstance(raw, str):
+            raise InvalidDSNError("DSN must be a non-empty string.")
+
+        parsed = urlparse(raw.strip())
+
+        if parsed.scheme not in ("http", "https"):
+            raise InvalidDSNError(
+                f"DSN scheme must be http or https, got {parsed.scheme!r}."
+            )
+        if not parsed.username:
+            raise InvalidDSNError("DSN is missing the beacon token (the userinfo part).")
+        if parsed.password:
+            raise InvalidDSNError(
+                "DSN must not contain a password; only the beacon token belongs there."
+            )
+        if not parsed.hostname:
+            raise InvalidDSNError("DSN is missing the host.")
+
+        # The path is "/<project_public_id>" — strip the leading slash and any
+        # trailing slash. We deliberately reject extra path components so we
+        # catch typos like "/api/v1/beam/<uuid>" pasted by mistake.
+        path = parsed.path.strip("/")
+        if not path:
+            raise InvalidDSNError("DSN is missing the project id in the path.")
+        if "/" in path:
+            raise InvalidDSNError(
+                "DSN path must be just the project id, with no extra segments."
+            )
+        try:
+            UUID(path)
+        except ValueError as exc:
+            raise InvalidDSNError(f"Project id {path!r} is not a valid UUID.") from exc
+
+        host = parsed.hostname
+        if parsed.port:
+            host = f"{host}:{parsed.port}"
+
+        return cls(
+            scheme=parsed.scheme,
+            host=host,
+            token=parsed.username,
+            project_id=path,
+        )
+
+    @property
+    def beam_url(self) -> str:
+        """The URL the SDK POSTs beacons to."""
+        return f"{self.scheme}://{self.host}/api/v1/beam/{self.project_id}/"
+
+    def redacted(self) -> str:
+        """A safe-to-log version of the DSN with the token masked."""
+        return f"{self.scheme}://[redacted]@{self.host}/{self.project_id}"

insider/safety.py

@@ -0,0 +1,61 @@
+"""
+The never-crash machinery.
+
+Every public entrypoint of the SDK is wrapped with `@safe`, which catches
+any `Exception` raised by the wrapped function and routes it through the
+SDK's debug logger. The host application sees `None` instead of an
+exception. That is the contract: the SDK cannot crash the customer's app.
+
+Why `print` to stderr instead of the `logging` module?
+    The SDK may be initialized *before* the customer's logging config is
+    in place. Using the stdlib `logging` module risks recursing into a
+    customer LoggingHandler that itself uses Insider (phase 4 of the
+    plan). Writing directly to stderr is dependency-free and recursion-free.
+"""
+
+from __future__ import annotations
+
+import functools
+import sys
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_debug_enabled: bool = False
+
+
+def set_debug(enabled: bool) -> None:
+    """Toggle SDK-internal debug logging. Called from `Client.__init__`."""
+    global _debug_enabled
+    _debug_enabled = bool(enabled)
+
+
+def debug(message: str) -> None:
+    """Write a single line to stderr if debug mode is on. Never raises."""
+    if not _debug_enabled:
+        return
+    try:
+        sys.stderr.write(f"[insider] {message}\n")
+    except Exception:
+        pass
+
+
+def safe(fn: F) -> F:
+    """
+    Decorator: swallow every exception raised by `fn`, return `None`
+    instead, and emit a debug line. The original return value is passed
+    through on success.
+
+    Use on every public entrypoint. Internal helpers can raise normally;
+    the boundary functions catch them.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:
+            debug(f"swallowed {type(exc).__name__} in {fn.__qualname__}: {exc}")
+            return None
+
+    return wrapper  # type: ignore[return-value]

insider/scope.py

@@ -0,0 +1,54 @@
+"""
+Global + per-thread scope.
+
+The scope holds the context that every Beacon should be enriched with:
+
+  - Static, set once at `init()`: environment, release, in_app_include.
+  - Dynamic, per-thread: the current HTTP request (when running inside a
+    framework integration), other transient enrichments.
+
+We use a threading.local for the dynamic part because Django still runs
+one request per thread under wsgi. When we add asgi / asyncio support in
+a later phase we'll swap this for `contextvars.ContextVar` — the public
+API doesn't change.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class StaticScope:
+    """Process-global, set by `Client.__init__` and read-only thereafter."""
+
+    environment: str = "production"
+    release: Optional[str] = None
+    in_app_include: Optional[List[str]] = None
+
+
+class _ThreadLocal(threading.local):
+    """Per-thread state. Each thread gets its own `request` slot."""
+
+    request: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Scope:
+    static: StaticScope = field(default_factory=StaticScope)
+    _local: _ThreadLocal = field(default_factory=_ThreadLocal)
+
+    # -- request context ---------------------------------------------------
+
+    def set_request(self, request: Dict[str, Any]) -> None:
+        """Attach a request-context dict to the current thread."""
+        self._local.request = request
+
+    def clear_request(self) -> None:
+        """Drop the current thread's request context."""
+        self._local.request = None
+
+    def current_request(self) -> Optional[Dict[str, Any]]:
+        return getattr(self._local, "request", None)

insider/scrubbing.py

@@ -0,0 +1,91 @@
+"""
+Default and custom data scrubbing.
+
+This is the SDK-side defence against accidental PII / secret leakage.
+We assume the customer's code routinely has dicts named `headers`,
+`form`, `cookies`, etc. that contain sensitive values, and that we are
+about to serialize and ship those dicts off-host. So before we do, we
+walk the structure and mask any key name that looks dangerous.
+
+Match is case-insensitive on the *key name only*. We never inspect
+values for sensitive content (regex-on-everything is expensive and
+unreliable). If a customer wants extra keys filtered they pass
+`scrub_keys=[...]` into `init`, and the deny-list grows.
+
+A future phase can add value-level patterns (credit-card regex, etc.)
+but the v1 contract is "we mask anything whose key looks scary."
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional, Set
+
+# Lowercase. Match is `key.lower() in DEFAULT_DENY_KEYS`.
+DEFAULT_DENY_KEYS: frozenset[str] = frozenset(
+    {
+        "password",
+        "passwd",
+        "pwd",
+        "secret",
+        "token",
+        "access_token",
+        "refresh_token",
+        "api_key",
+        "apikey",
+        "authorization",
+        "auth",
+        "x-api-key",
+        "cookie",
+        "set-cookie",
+        "session",
+        "sessionid",
+        "csrf",
+        "csrftoken",
+        "x-csrf-token",
+        "credit_card",
+        "card_number",
+        "cc_number",
+        "cvv",
+        "ssn",
+    }
+)
+
+FILTERED = "[Filtered]"
+
+# Walk depth cap. Pathological customer payloads (deeply nested dicts) shouldn't
+# burn the SDK's stack or budget. Anything deeper than this is replaced with a
+# marker — the customer's data was already going to be lossily truncated by
+# the size budget anyway.
+_MAX_DEPTH = 16
+
+
+def build_deny_set(extra_keys: Optional[Iterable[str]] = None) -> Set[str]:
+    """Combine the default deny-list with caller-supplied keys."""
+    deny = set(DEFAULT_DENY_KEYS)
+    if extra_keys:
+        deny.update(k.lower() for k in extra_keys if isinstance(k, str))
+    return deny
+
+
+def scrub(data: Any, *, extra_keys: Optional[Iterable[str]] = None) -> Any:
+    """
+    Return a new structure with sensitive values replaced by `[Filtered]`.
+    The input is not mutated.
+    """
+    deny = build_deny_set(extra_keys)
+    return _scrub(data, deny, depth=0)
+
+
+def _scrub(value: Any, deny: Set[str], depth: int) -> Any:
+    if depth > _MAX_DEPTH:
+        return "[TooDeep]"
+    if isinstance(value, dict):
+        return {
+            k: (FILTERED if isinstance(k, str) and k.lower() in deny
+                else _scrub(v, deny, depth + 1))
+            for k, v in value.items()
+        }
+    if isinstance(value, (list, tuple)):
+        scrubbed = [_scrub(item, deny, depth + 1) for item in value]
+        return scrubbed if isinstance(value, list) else tuple(scrubbed)
+    return value

insider/stacktrace.py

@@ -0,0 +1,153 @@
+"""
+Stack frame extraction.
+
+Given an exception (and therefore a traceback), produce a serializable
+list of frames the dashboard can render. We deliberately *don't* read
+source files in v1 — that's I/O on the error path and a chunk of
+deferred work (see docs/python-sdk-plan -> Non-goals). We also don't
+capture frame-local variables (security risk, opt-in feature later).
+
+`in_app` is a hint to the dashboard about which frames are "the
+customer's code" vs library / stdlib code. Default heuristic:
+
+    in_app == filename does not live under site-packages / dist-packages
+              and is not under the stdlib path
+
+The customer can override with `in_app_include=["/srv/myapp", ...]`,
+which switches to an explicit allow-list.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from types import TracebackType
+from typing import Any, Dict, Iterable, List, Optional
+
+from .safety import debug
+
+# Computed once at import time. Falls back to "" if `os.__file__` isn't a
+# usable path (e.g. frozen Python build).
+_STDLIB_PATH = os.path.dirname(getattr(os, "__file__", "") or "")
+
+
+def is_in_app(
+    filename: Optional[str],
+    in_app_include: Optional[Iterable[str]] = None,
+) -> bool:
+    """Return True if `filename` should be flagged as customer code."""
+    if not filename or filename.startswith("<"):
+        return False
+    if in_app_include:
+        return any(filename.startswith(prefix) for prefix in in_app_include)
+    if "site-packages" in filename or "dist-packages" in filename:
+        return False
+    if _STDLIB_PATH and filename.startswith(_STDLIB_PATH):
+        return False
+    return True
+
+
+def extract_frames(
+    tb: Optional[TracebackType],
+    *,
+    in_app_include: Optional[Iterable[str]] = None,
+    max_frames: int = 200,
+) -> List[Dict[str, Any]]:
+    """
+    Walk a traceback into a list of frame dicts.
+
+    Order: innermost (where the exception was raised) is last, matching
+    Python's own `traceback` module. The dashboard renders top-down.
+    `max_frames` is a guardrail against pathological recursion.
+    """
+    frames: List[Dict[str, Any]] = []
+    walked = 0
+    while tb is not None and walked < max_frames:
+        try:
+            frame = tb.tb_frame
+            code = frame.f_code
+            filename = code.co_filename
+            frames.append(
+                {
+                    "filename": filename,
+                    "function": code.co_name,
+                    "module": frame.f_globals.get("__name__", ""),
+                    "lineno": tb.tb_lineno,
+                    "in_app": is_in_app(filename, in_app_include),
+                }
+            )
+        except Exception as exc:
+            debug(f"frame extraction skipped one frame: {exc}")
+        tb = tb.tb_next
+        walked += 1
+    return frames
+
+
+def exception_payload(
+    exc: BaseException,
+    *,
+    in_app_include: Optional[Iterable[str]] = None,
+) -> Dict[str, Any]:
+    """
+    Build the `payload.exception` block.
+
+    Walks `__cause__` / `__context__` and stops at a small chain depth so
+    we don't accidentally serialize a circular chain forever.
+    """
+    chain: List[Dict[str, Any]] = []
+    seen: set[int] = set()
+    current: Optional[BaseException] = exc
+    while current is not None and len(chain) < 10 and id(current) not in seen:
+        seen.add(id(current))
+        chain.append(
+            {
+                "type": type(current).__name__,
+                "module": type(current).__module__,
+                "value": str(current),
+                "frames": extract_frames(
+                    current.__traceback__,
+                    in_app_include=in_app_include,
+                ),
+            }
+        )
+        current = current.__cause__ or current.__context__
+
+    head = chain[0]
+    if len(chain) > 1:
+        head["chain"] = chain[1:]
+    return head
+
+
+def runtime_payload(sdk_version: str) -> Dict[str, Any]:
+    """Static runtime info to attach to every error envelope."""
+    return {
+        "sdk": "insider-python",
+        "sdk_version": sdk_version,
+        "python_version": (
+            f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+        ),
+        "platform": sys.platform,
+    }
+
+
+def caller_source(skip: int = 1) -> Optional[str]:
+    """
+    Return `<module>.<function>` of the first non-SDK caller above this
+    function. `skip` is the minimum number of frames to skip before we
+    start looking for a non-internal frame.
+
+    We walk frames because the `@safe` decorator and the module-level
+    facade each add a stack frame on top of `Client.capture_message`;
+    a fixed `skip` would be brittle.
+    """
+    try:
+        frame = sys._getframe(skip)
+        while frame is not None:
+            module = frame.f_globals.get("__name__", "") or ""
+            if not module.startswith("insider"):
+                function = frame.f_code.co_name
+                return f"{module}.{function}" if module else function
+            frame = frame.f_back
+        return None
+    except Exception:
+        return None