insider-python 0.1.0__py3-none-any.whl

insider/__init__.py

@@ -0,0 +1,37 @@
+"""
+Insider — Python SDK.
+
+Public API:
+
+    insider.init(dsn=..., environment=..., release=..., ...)
+    insider.capture_exception(exc, level="error", tags=..., extra=...)
+    insider.capture_message("text", level="info", tags=..., extra=...)
+    insider.flush(timeout=2.0)
+    insider.close(timeout=2.0)
+
+Nothing else is part of the public contract. Anything imported below
+`_` is internal and may change without notice.
+"""
+
+from ._version import __version__
+from .client import (
+    Client,
+    capture_exception,
+    capture_message,
+    close,
+    flush,
+    init,
+)
+from .dsn import DSN, InvalidDSNError
+
+__all__ = [
+    "Client",
+    "DSN",
+    "InvalidDSNError",
+    "__version__",
+    "capture_exception",
+    "capture_message",
+    "close",
+    "flush",
+    "init",
+]

insider/_envelope.py

@@ -0,0 +1,189 @@
+"""
+Beacon envelope construction + size-budget enforcement.
+
+`build_envelope` is called from the capture functions in `client.py`. It
+takes the raw bits (kind, level, message, exception payload, scope,
+tags, extra) and produces the top-level dict the transport will ship.
+
+`enforce_size_budget` is the second-to-last step before submit. It
+truncates progressively until the JSON-encoded envelope fits under the
+server's 256 KB cap. The truncation order is intentional and matches
+docs/python-sdk-plan -> "Payload size budget":
+
+    1. message capped to 8 KB
+    2. frame `vars` capped to 2 KB each   (v1 has no vars, future-proof)
+    3. request.body capped to 32 KB
+    4. request.headers capped to 4 KB (after deny-listed keys are masked
+       by scrub.py upstream)
+    5. drop frames from the outermost end of the stack until envelope fits,
+       keeping the innermost frames (closest to the error)
+    6. drop payload.request entirely
+    7. ship minimal envelope with payload.truncated = True
+
+Step 7's existence is the property: we ship *something* truthful rather
+than nothing.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterable, List, Optional
+
+from .safety import debug
+
+MAX_ENVELOPE_BYTES = 256 * 1024
+MAX_MESSAGE_BYTES = 8 * 1024
+MAX_REQUEST_BODY_BYTES = 32 * 1024
+MAX_REQUEST_HEADERS_BYTES = 4 * 1024
+
+
+def _now_iso() -> str:
+    """ISO-8601 UTC timestamp with microseconds, used as `occurred_at`."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def build_envelope(
+    *,
+    kind: str,
+    level: str,
+    message: Optional[str],
+    source: Optional[str],
+    environment: str,
+    release: Optional[str],
+    trace_id: Optional[str],
+    payload: Optional[Dict[str, Any]] = None,
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    occurred_at: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Assemble the Beacon envelope. Pure: no I/O, no globals."""
+    body: Dict[str, Any] = dict(payload or {})
+    if tags:
+        body["tags"] = tags
+    if extra:
+        body["extra"] = extra
+    return {
+        "kind": kind,
+        "level": level,
+        "environment": environment,
+        "release": release,
+        "source": source,
+        "message": message,
+        "occurred_at": occurred_at or _now_iso(),
+        "trace_id": trace_id,
+        "payload": body,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Size budget
+# ---------------------------------------------------------------------------
+
+
+def _byte_len(obj: Any) -> int:
+    """Best-effort serialized size. Encode errors → infinity to force trim."""
+    try:
+        return len(json.dumps(obj, default=str, ensure_ascii=False).encode("utf-8"))
+    except Exception:
+        return 10**9
+
+
+def _truncate_str_to_bytes(value: str, limit: int) -> str:
+    encoded = value.encode("utf-8")
+    if len(encoded) <= limit:
+        return value
+    return encoded[:limit].decode("utf-8", errors="ignore")
+
+
+def enforce_size_budget(envelope: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Apply the truncation rules in order. Returns the same envelope dict,
+    mutated. The caller is expected to discard the original reference
+    after this call.
+    """
+    # 1. message
+    msg = envelope.get("message")
+    if isinstance(msg, str):
+        envelope["message"] = _truncate_str_to_bytes(msg, MAX_MESSAGE_BYTES)
+
+    payload = envelope.get("payload") or {}
+
+    # 3. request.body
+    request_ctx = payload.get("request")
+    if isinstance(request_ctx, dict):
+        body = request_ctx.get("body")
+        if isinstance(body, str):
+            request_ctx["body"] = _truncate_str_to_bytes(body, MAX_REQUEST_BODY_BYTES)
+        elif body is not None:
+            # Non-string body: dump to string and cap.
+            try:
+                as_str = json.dumps(body, default=str)
+            except Exception:
+                as_str = str(body)
+            request_ctx["body"] = _truncate_str_to_bytes(as_str, MAX_REQUEST_BODY_BYTES)
+
+        # 4. request.headers
+        headers = request_ctx.get("headers")
+        if isinstance(headers, dict):
+            if _byte_len(headers) > MAX_REQUEST_HEADERS_BYTES:
+                # Drop the largest-value headers until under budget. We drop
+                # whole entries rather than truncating individual values to
+                # avoid producing partial / misleading header strings.
+                items = sorted(
+                    headers.items(),
+                    key=lambda kv: _byte_len(kv[1]),
+                    reverse=True,
+                )
+                trimmed = dict(items)
+                while items and _byte_len(trimmed) > MAX_REQUEST_HEADERS_BYTES:
+                    k, _ = items.pop(0)
+                    trimmed.pop(k, None)
+                request_ctx["headers"] = trimmed
+
+    # 5. drop frames from the outside until envelope fits
+    exception = payload.get("exception")
+    if isinstance(exception, dict) and isinstance(exception.get("frames"), list):
+        while _byte_len(envelope) > MAX_ENVELOPE_BYTES and exception["frames"]:
+            # Keep the *innermost* frames (the end of the list).
+            exception["frames"].pop(0)
+
+    # 6. drop payload.request entirely if still too big
+    if _byte_len(envelope) > MAX_ENVELOPE_BYTES and "request" in payload:
+        payload.pop("request", None)
+        debug("size budget: dropped payload.request")
+
+    # 7. minimal envelope of last resort
+    if _byte_len(envelope) > MAX_ENVELOPE_BYTES:
+        minimal_exception: Optional[Dict[str, Any]] = None
+        if isinstance(exception, dict):
+            minimal_exception = {
+                "type": exception.get("type"),
+                "value": _truncate_str_to_bytes(
+                    str(exception.get("value", "")), 1024
+                ),
+            }
+        minimal_payload: Dict[str, Any] = {"truncated": True}
+        if minimal_exception is not None:
+            minimal_payload["exception"] = minimal_exception
+        envelope["payload"] = minimal_payload
+        debug("size budget: emitting minimal envelope")
+
+    return envelope
+
+
+def safe_frame_subset(
+    frames: List[Dict[str, Any]],
+    in_app_only: bool = False,
+) -> List[Dict[str, Any]]:
+    """Optional filter for dashboards; unused in v1 but kept for callers."""
+    if not in_app_only:
+        return frames
+    return [f for f in frames if f.get("in_app")]
+
+
+__all__: Iterable[str] = (
+    "MAX_ENVELOPE_BYTES",
+    "build_envelope",
+    "enforce_size_budget",
+)

insider/_version.py

@@ -0,0 +1,8 @@
+"""Single source of truth for the SDK version.
+
+Kept separate from `pyproject.toml` at runtime to avoid an `importlib.metadata`
+lookup on every beacon. Bump this and `[project].version` together when
+cutting a release.
+"""
+
+__version__ = "0.1.0"

insider/client.py

@@ -0,0 +1,344 @@
+"""
+The Client and the module-level facade.
+
+There are two ways to talk to the SDK:
+
+  1. Module-level helpers (`insider.init`, `insider.capture_exception`,
+     etc.). These operate on a single process-global `Client`.
+  2. Explicit `Client` instance returned by `init()`. Useful for tests,
+     advanced users, and the eventual multi-DSN case.
+
+Both paths route to the same code. The module-level functions are thin
+@safe wrappers around `_active_client()`.
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import threading
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+from ._envelope import build_envelope, enforce_size_budget
+from ._version import __version__
+from .dsn import DSN, InvalidDSNError
+from .safety import debug, safe, set_debug
+from .scope import Scope, StaticScope
+from .scrubbing import scrub
+from .stacktrace import caller_source, exception_payload, runtime_payload
+from .transport import BackgroundTransport
+
+
+VALID_KINDS = {"error", "perf", "log", "custom"}
+VALID_LEVELS = {"debug", "info", "warning", "error", "fatal"}
+
+
+# ---------------------------------------------------------------------------
+# DSN resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_dsn_string(explicit: Optional[str]) -> Optional[str]:
+    """Find a DSN string from `init()` arg → env var → None."""
+    if explicit:
+        return explicit
+    env = os.environ.get("INSIDER_DSN")
+    if env:
+        return env
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+
+class Client:
+    """
+    A configured SDK instance. Owns a `Scope`, a `BackgroundTransport`,
+    and the customer-supplied hooks.
+
+    Customers usually don't construct this directly — they call
+    `insider.init(...)` which returns a `Client` and also stashes it as
+    the process-global active client.
+    """
+
+    def __init__(
+        self,
+        dsn: DSN,
+        *,
+        environment: str = "production",
+        release: Optional[str] = None,
+        send_default_pii: bool = False,
+        before_send: Optional[Callable[[Dict[str, Any]], Optional[Dict[str, Any]]]] = None,
+        scrub_keys: Optional[Iterable[str]] = None,
+        in_app_include: Optional[Iterable[str]] = None,
+        transport_queue_size: int = 1000,
+        transport_flush_timeout: float = 2.0,
+        debug: bool = False,
+        transport: Optional[BackgroundTransport] = None,
+    ) -> None:
+        set_debug(debug)
+        self.dsn = dsn
+        self.send_default_pii = bool(send_default_pii)
+        self.before_send = before_send
+        self.scrub_keys: List[str] = list(scrub_keys or [])
+        self.scope = Scope(
+            static=StaticScope(
+                environment=environment,
+                release=release,
+                in_app_include=list(in_app_include) if in_app_include else None,
+            )
+        )
+        self.transport: BackgroundTransport = transport or BackgroundTransport(
+            dsn,
+            queue_size=transport_queue_size,
+            flush_timeout=transport_flush_timeout,
+        )
+
+    # ------------------------------------------------------------------
+    # Capture
+    # ------------------------------------------------------------------
+
+    def capture_exception(
+        self,
+        exc: BaseException,
+        *,
+        level: str = "error",
+        tags: Optional[Dict[str, Any]] = None,
+        extra: Optional[Dict[str, Any]] = None,
+        trace_id: Optional[str] = None,
+    ) -> Optional[str]:
+        if not isinstance(exc, BaseException):
+            debug(f"capture_exception got non-exception: {type(exc).__name__}")
+            return None
+        level = level if level in VALID_LEVELS else "error"
+
+        exception_block = exception_payload(
+            exc, in_app_include=self.scope.static.in_app_include
+        )
+        payload: Dict[str, Any] = {
+            "exception": exception_block,
+            "runtime": runtime_payload(__version__),
+        }
+        request_ctx = self.scope.current_request()
+        if request_ctx is not None:
+            payload["request"] = request_ctx
+
+        envelope = build_envelope(
+            kind="error",
+            level=level,
+            message=str(exc) or type(exc).__name__,
+            source=self._source_from_exception(exception_block),
+            environment=self.scope.static.environment,
+            release=self.scope.static.release,
+            trace_id=trace_id,
+            payload=payload,
+            tags=tags,
+            extra=extra,
+        )
+        return self._dispatch(envelope)
+
+    def capture_message(
+        self,
+        message: str,
+        *,
+        level: str = "info",
+        tags: Optional[Dict[str, Any]] = None,
+        extra: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        kind: str = "log",
+    ) -> Optional[str]:
+        if not isinstance(message, str):
+            debug(f"capture_message expects str, got {type(message).__name__}")
+            return None
+        level = level if level in VALID_LEVELS else "info"
+        kind = kind if kind in VALID_KINDS else "log"
+
+        payload: Dict[str, Any] = {"runtime": runtime_payload(__version__)}
+        request_ctx = self.scope.current_request()
+        if request_ctx is not None:
+            payload["request"] = request_ctx
+
+        envelope = build_envelope(
+            kind=kind,
+            level=level,
+            message=message,
+            source=source or caller_source(skip=2),
+            environment=self.scope.static.environment,
+            release=self.scope.static.release,
+            trace_id=trace_id,
+            payload=payload,
+            tags=tags,
+            extra=extra,
+        )
+        return self._dispatch(envelope)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        return self.transport.flush(timeout)
+
+    def close(self, timeout: Optional[float] = None) -> None:
+        self.transport.close(timeout)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _dispatch(self, envelope: Dict[str, Any]) -> Optional[str]:
+        """Scrub → before_send → size budget → transport submit."""
+        envelope["payload"] = scrub(envelope.get("payload"), extra_keys=self.scrub_keys)
+        if self.before_send is not None:
+            try:
+                envelope = self.before_send(envelope)  # type: ignore[assignment]
+            except Exception as exc:
+                debug(f"before_send raised {type(exc).__name__}: {exc}; dropping beacon")
+                return None
+            if envelope is None:
+                return None
+
+        envelope = enforce_size_budget(envelope)
+        accepted = self.transport.submit(envelope)
+        return envelope.get("occurred_at") if accepted else None
+
+    @staticmethod
+    def _source_from_exception(exception_block: Dict[str, Any]) -> Optional[str]:
+        """Pick the innermost in_app frame's module as the beacon `source`."""
+        frames = exception_block.get("frames") or []
+        for frame in reversed(frames):
+            if frame.get("in_app"):
+                return frame.get("module") or frame.get("function")
+        if frames:
+            tail = frames[-1]
+            return tail.get("module") or tail.get("function")
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Module-level facade
+# ---------------------------------------------------------------------------
+
+
+_active_client: Optional[Client] = None
+_init_lock = threading.Lock()
+
+
+def _client() -> Optional[Client]:
+    return _active_client
+
+
+def _set_active(client: Optional[Client]) -> None:
+    global _active_client
+    _active_client = client
+
+
+@safe
+def init(
+    dsn: Optional[str] = None,
+    **kwargs: Any,
+) -> Optional[Client]:
+    """
+    Initialize the SDK. Returns the new `Client` on success, or `None`
+    when no DSN is configured (disabled mode).
+
+    Calling `init` a second time is allowed but logs a warning and
+    closes the previous client first. The new client becomes the
+    process-global one.
+    """
+    global _active_client
+    raw = _resolve_dsn_string(dsn)
+    if not raw:
+        debug("no DSN configured; entering disabled mode")
+        return None
+    try:
+        parsed = DSN.parse(raw)
+    except InvalidDSNError as exc:
+        debug(f"invalid DSN: {exc}; entering disabled mode")
+        return None
+
+    with _init_lock:
+        if _active_client is not None:
+            debug("re-initializing; closing previous client")
+            try:
+                _active_client.close()
+            except Exception as exc:
+                debug(f"previous client close failed: {exc}")
+        client = Client(parsed, **kwargs)
+        _set_active(client)
+
+    atexit.register(_atexit_close)
+    return client
+
+
+def _atexit_close() -> None:
+    """Hook registered with `atexit` to drain on process exit."""
+    client = _active_client
+    if client is None:
+        return
+    try:
+        client.close()
+    except Exception as exc:
+        debug(f"atexit close failed: {exc}")
+
+
+@safe
+def capture_exception(
+    exc: BaseException,
+    *,
+    level: str = "error",
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    trace_id: Optional[str] = None,
+) -> Optional[str]:
+    client = _client()
+    if client is None:
+        return None
+    return client.capture_exception(
+        exc, level=level, tags=tags, extra=extra, trace_id=trace_id
+    )
+
+
+@safe
+def capture_message(
+    message: str,
+    *,
+    level: str = "info",
+    tags: Optional[Dict[str, Any]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    source: Optional[str] = None,
+    trace_id: Optional[str] = None,
+    kind: str = "log",
+) -> Optional[str]:
+    client = _client()
+    if client is None:
+        return None
+    return client.capture_message(
+        message,
+        level=level,
+        tags=tags,
+        extra=extra,
+        source=source,
+        trace_id=trace_id,
+        kind=kind,
+    )
+
+
+@safe
+def flush(timeout: Optional[float] = None) -> bool:
+    client = _client()
+    if client is None:
+        return True
+    return client.flush(timeout)
+
+
+@safe
+def close(timeout: Optional[float] = None) -> None:
+    client = _client()
+    if client is None:
+        return
+    client.close(timeout)
+    _set_active(None)

insider/contrib/django/__init__.py

@@ -0,0 +1,27 @@
+"""
+Django integration for insider-python.
+
+How to enable:
+
+    # settings.py
+    INSTALLED_APPS = [
+        ...
+        "insider.contrib.django",
+    ]
+
+    MIDDLEWARE = [
+        ...
+        "insider.contrib.django.middleware.InsiderMiddleware",
+    ]
+
+    INSIDER_DSN = "https://<token>@insider.example.com/<project_uuid>"
+    INSIDER_ENVIRONMENT = "production"
+    INSIDER_RELEASE = "1.2.3"
+
+The `AppConfig.ready()` hook reads `INSIDER_*` from settings and calls
+`insider.init(...)`. If no DSN is configured (`INSIDER_DSN` absent or
+empty), the SDK enters disabled mode and the middleware becomes a
+no-op.
+"""
+
+default_app_config = "insider.contrib.django.apps.InsiderConfig"

insider/contrib/django/apps.py

@@ -0,0 +1,60 @@
+"""
+AppConfig that auto-initializes the SDK from Django settings.
+
+We avoid importing `django.conf.settings` at module import time — Django
+calls `ready()` once the settings are fully resolved, which is the safe
+place to do it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from django.apps import AppConfig
+
+from ... import init
+from ...safety import debug
+
+
+def _settings_kwargs() -> Dict[str, Any]:
+    """Collect `INSIDER_*` keys from Django settings into init kwargs."""
+    from django.conf import settings
+
+    kwargs: Dict[str, Any] = {}
+    for setting, key in (
+        ("INSIDER_DSN", "dsn"),
+        ("INSIDER_ENVIRONMENT", "environment"),
+        ("INSIDER_RELEASE", "release"),
+        ("INSIDER_SEND_DEFAULT_PII", "send_default_pii"),
+        ("INSIDER_BEFORE_SEND", "before_send"),
+        ("INSIDER_SCRUB_KEYS", "scrub_keys"),
+        ("INSIDER_IN_APP_INCLUDE", "in_app_include"),
+        ("INSIDER_TRANSPORT_QUEUE_SIZE", "transport_queue_size"),
+        ("INSIDER_TRANSPORT_FLUSH_TIMEOUT", "transport_flush_timeout"),
+        ("INSIDER_DEBUG", "debug"),
+    ):
+        value = getattr(settings, setting, None)
+        if value is not None:
+            kwargs[key] = value
+    return kwargs
+
+
+class InsiderConfig(AppConfig):
+    """Side-effect-only Django app: initialize the SDK when ready."""
+
+    name = "insider.contrib.django"
+    label = "insider_django"
+    verbose_name = "Insider (telemetry)"
+
+    def ready(self) -> None:
+        try:
+            kwargs = _settings_kwargs()
+        except Exception as exc:
+            debug(f"settings read failed: {exc}")
+            return
+        # No DSN means disabled mode — `init` itself debug-logs that and
+        # returns None.  We pass kwargs.pop("dsn", None) explicitly so the
+        # env-var fallback in `init` still applies if Django's settings
+        # didn't define it.
+        dsn = kwargs.pop("dsn", None)
+        init(dsn, **kwargs)