devbench 0.1.0__py3-none-any.whl

devbench/django/apps.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any, Optional
+
+from django.apps import AppConfig
+
+MIDDLEWARE_PATH = "devbench.django.middleware.DevbenchMiddleware"
+
+
+class DevbenchConfig(AppConfig):
+    name = "devbench.django"
+    label = "devbench"
+    verbose_name = "Dev Bench"
+    default = True
+
+    def ready(self) -> None:
+        # A diagnostics package that can fail a boot is worse than none.
+        try:
+            from .. import _core, _integration
+
+            if not _core.enabled():
+                return
+            from django.conf import settings
+
+            _integration.setup(service=_project_name(settings), root=_base_dir(settings))
+            insert_middleware(settings)
+
+            from django.core.signals import got_request_exception
+
+            from .middleware import on_request_exception
+
+            got_request_exception.connect(on_request_exception, dispatch_uid="devbench.request_exception")
+
+            # The standard Celery layout imports the Celery app from the
+            # project package, so it is loaded by now, in the web process and
+            # the worker alike.
+            if "celery" in sys.modules:
+                from .. import celery as devbench_celery
+
+                devbench_celery.install()
+        except Exception:
+            pass
+
+
+def insert_middleware(settings: Any) -> bool:
+    """Puts DevbenchMiddleware first, as sentry-sdk instruments the handler,
+    so ``"devbench.django"`` in INSTALLED_APPS is the whole install. Not when
+    the app already lists it. Runs in ready(), before Django's handler reads
+    MIDDLEWARE. Returns True when it was added."""
+    current = list(getattr(settings, "MIDDLEWARE", None) or [])
+    if MIDDLEWARE_PATH in current:
+        return False
+    settings.MIDDLEWARE = [MIDDLEWARE_PATH] + current
+    return True
+
+
+def _project_name(settings: Any) -> Optional[str]:
+    # DJANGO_SETTINGS_MODULE "acme_shop.settings" -> "acme_shop".
+    module = getattr(settings, "SETTINGS_MODULE", None) or os.environ.get("DJANGO_SETTINGS_MODULE") or ""
+    head = module.split(".")[0]
+    return head if "." in module else None
+
+
+def _base_dir(settings: Any) -> Optional[str]:
+    base = getattr(settings, "BASE_DIR", None)
+    return str(base) if base else None

devbench/django/management/commands/devbench_test.py

@@ -0,0 +1,18 @@
+"""``python manage.py devbench_test``: ``python -m devbench test`` with the
+project's settings loaded, so the service name is the project's."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError
+
+
+class Command(BaseCommand):
+    help = "Check DEVBENCH_DSN against Dev Bench and print the HTTP result"
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        from devbench import _core
+
+        if not _core.self_test(self.stdout):
+            raise CommandError("Dev Bench test failed (see above)")

devbench/django/middleware.py

@@ -0,0 +1,87 @@
+"""DevbenchMiddleware for Django (sync and async). Added first in MIDDLEWARE
+by the app config.
+
+Django turns every exception inside the stack into a response before it
+reaches this middleware, so failures are reported from
+``got_request_exception``, which Django sends for exactly the exceptions it
+answers with a 500 (an Http404, PermissionDenied, BadRequest or
+SuspiciousOperation is a response, not a failure, and never reaches it). The
+signal runs inside this middleware's scope, so the report carries the
+request's trace and user.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any, Callable, Optional
+
+from asgiref.sync import iscoroutinefunction, markcoroutinefunction
+
+from .. import _core, _integration, context
+from ..trace import WSGI_HEADER, Trace
+
+
+class DevbenchMiddleware:
+    sync_capable = True
+    async_capable = True
+
+    def __init__(self, get_response: Callable[..., Any]) -> None:
+        self.get_response = get_response
+        self._async = iscoroutinefunction(get_response)
+        if self._async:
+            markcoroutinefunction(self)
+
+    def __call__(self, request: Any) -> Any:
+        if self._async:
+            return self.__acall__(request)
+        if not _core.enabled():
+            return self.get_response(request)
+        with context.scoped(_parse(request)):
+            response = self.get_response(request)
+            _mark_handled(response)
+            return response
+
+    async def __acall__(self, request: Any) -> Any:
+        if not _core.enabled():
+            return await self.get_response(request)
+        with context.scoped(_parse(request)):
+            response = await self.get_response(request)
+            _mark_handled(response)
+            return response
+
+
+def on_request_exception(sender: Any = None, request: Any = None, **_: Any) -> None:
+    """got_request_exception: the exception being handled is sys.exc_info()."""
+    try:
+        _integration.report_request_error(sys.exc_info()[1], _symbol(request))
+    except Exception:
+        pass
+
+
+def _parse(request: Any) -> Optional[Trace]:
+    try:
+        return Trace.parse(request.META.get(WSGI_HEADER))
+    except Exception:
+        return None
+
+
+def _symbol(request: Any) -> Optional[str]:
+    # "shop.views.checkout": the resolved view, when routing got that far.
+    try:
+        match = getattr(request, "resolver_match", None)
+        if match is None:
+            return None
+        return getattr(match, "_func_path", None) or _integration.callable_path(match.func)
+    except Exception:
+        return None
+
+
+def _mark_handled(response: Any) -> None:
+    try:
+        count = _integration.handled_count()
+        if count <= 0 or response is None:
+            return
+        response[_integration.HANDLED_HEADER] = str(count)
+        response[_integration.EXPOSE_HEADER] = _integration.exposed(response.get(_integration.EXPOSE_HEADER))
+    except Exception:
+        pass

devbench/egress_policy.py

@@ -0,0 +1,101 @@
+"""Learned redaction rules, as ingest sends them on a flush response
+(``redaction``), compiled and applied exactly as the sidecar does
+(internal/sidecar/rules.go and Sidecar.redactBody)::
+
+    {"fp": <shape fp>, "egress": "masked"|"none"|"full"}   shape rule
+    {"kind": "field", "target": "license"}                 mask that field's value
+    {"kind": "term",  "target": "Whitfield"}               mask that literal
+
+Immutable once built; the transport swaps a whole new one in when a response
+carries a rule set, and keeps the current one when a response carries none
+(absent is not empty: ingest omits the field when it could not look the
+rules up).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+from .fingerprint import GO_WS as WS
+
+FIELD = "field"
+TERM = "term"
+
+# store.NormalizeRule's field-name shape; anything else is ignored, so a
+# malformed rule never becomes an odd pattern here.
+FIELD_NAME = re.compile(r"[a-z0-9_.\-]{1,64}\Z")
+# A shorter term would mask fragments of ordinary words everywhere.
+MIN_TERM_BYTES = 3
+
+
+class EgressPolicy:
+    __slots__ = ("_shapes", "_terms", "_fields")
+
+    def __init__(self, shapes: Dict[str, str], fields: List[str], terms: List[str]) -> None:
+        self._shapes = dict(shapes)
+        self._terms = tuple(terms)
+        self._fields = _field_pattern(fields) if fields else None
+
+    @classmethod
+    def compile(cls, rules: Any) -> "EgressPolicy":
+        """rules: the parsed JSON array. Entries that are not objects, or not
+        understood, are skipped (a newer ingest may send kinds this SDK cannot
+        enforce; the local passes still run)."""
+        shapes: Dict[str, str] = {}
+        fields: List[str] = []
+        terms: List[str] = []
+        for rule in rules if isinstance(rules, list) else []:
+            if not isinstance(rule, dict):
+                continue
+            kind = rule.get("kind")
+            kind = kind if isinstance(kind, str) else ""
+            target = rule.get("target")
+            target = target if isinstance(target, str) else ""
+            if kind == "":
+                fp = rule.get("fp")
+                if isinstance(fp, str) and fp:
+                    egress = rule.get("egress")
+                    shapes[fp] = egress if isinstance(egress, str) else ""
+            elif kind == FIELD:
+                name = target.strip().lower()
+                if FIELD_NAME.match(name) and name not in fields:
+                    fields.append(name)
+            elif kind == TERM:
+                if len(target.encode("utf-8", "replace")) >= MIN_TERM_BYTES and target not in terms:
+                    terms.append(target)
+        return cls(shapes, fields, terms)
+
+    def rule_for(self, fp: Optional[str]) -> Optional[str]:
+        """The shape rule for a fingerprint, or None."""
+        return self._shapes.get(fp) if fp else None
+
+    def has_shapes(self) -> bool:
+        return bool(self._shapes)
+
+    @property
+    def terms(self) -> tuple:
+        return self._terms
+
+    def mask(self, value: str) -> str:
+        """Field and term rules. Additive only: it removes text, never
+        restores any."""
+        if self._fields is not None:
+            value = self._fields.sub(r"\g<1>\g<2>\g<3>\g<4><redacted:field>", value)
+        for term in self._terms:
+            value = value.replace(term, "<redacted:term>")
+        return value
+
+
+def _field_pattern(fields: List[str]) -> "re.Pattern[str]":
+    """The field name, exactly ("license" must not catch "licensed" or
+    "driver_license"), optionally quoted or a Ruby symbol, then a separator,
+    then one value: a quoted string or a bare token. Go's pattern, with Go's
+    \\s and with \\A for Go's unanchored-mode ^."""
+    names = "|".join(re.escape(f) for f in fields)
+    return re.compile(
+        r"(\A|[^a-z0-9_.\-])([\"':]?)(" + names + ")"
+        r"([\"']?" + WS + "*(?:=>|=|:)" + WS + "*)"
+        r"(\"(?:[^\"\\]|\\.)*\"|'(?:[^'\\]|\\.)*'|[^\t\n\f\r ,;&)}\]]+)",
+        re.IGNORECASE,
+    )

devbench/fastapi.py

@@ -0,0 +1,14 @@
+"""FastAPI (and Starlette)::
+
+    from fastapi import FastAPI
+    from devbench.fastapi import DevbenchMiddleware
+
+    app = FastAPI()
+    app.add_middleware(DevbenchMiddleware)
+
+The same middleware as devbench.asgi.
+"""
+
+from .asgi import DevbenchMiddleware
+
+__all__ = ["DevbenchMiddleware"]

devbench/fingerprint.py

@@ -0,0 +1,199 @@
+"""A port of internal/fingerprint (Go): the same signal gives the same
+fingerprint, byte for byte, as the sidecar, the browser, Ruby and Go compute.
+
+If two implementations disagree, the same problem is counted as two: triage
+cost doubles and one issue is split in half. testdata/fingerprint_vectors.json
+holds all of them to one answer (tests/test_vectors.py).
+
+Go's regexp and Python's differ in ways that matter here, so the patterns are
+spelled out rather than copied:
+
+* Go's ``\\b`` is an ASCII word boundary; Python's (str patterns) treats "é"
+  as a word character. ``GO_B`` rebuilds Go's.
+* Go's ``\\d`` is ASCII; Python's matches every Unicode digit. Spelled
+  ``[0-9]``.
+* Go's ``\\s`` is ``[\\t\\n\\f\\r ]``; Python's adds ``\\v`` and Unicode
+  spaces. ``GO_WS`` is Go's.
+* Go's strings.TrimSpace trims Unicode spaces (unicode.IsSpace), a set that
+  differs from str.strip()'s. ``GO_SPACE`` is Go's.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Any, Iterable, Mapping
+
+GO_W = "[0-9A-Za-z_]"
+GO_B = "(?:(?<=%s)(?!%s)|(?<!%s)(?=%s))" % (GO_W, GO_W, GO_W, GO_W)
+GO_WS = r"[\t\n\f\r ]"
+GO_NOT_WS = r"[^\t\n\f\r ]"
+# unicode.IsSpace, which strings.TrimSpace and strings.Fields use.
+GO_SPACE = "\t\n\v\f\r \u0085  " + "".join(chr(c) for c in range(0x2000, 0x200B)) + "

  　"
+GO_SPACE_CLASS = "\t\n\v\f\r \u0085   - 

  　"
+
+
+def go_re(source: str, flags: int = 0) -> "re.Pattern[str]":
+    """Compiles a Go pattern: ``\\d`` (outside character classes) as ASCII
+    digits and ``\\b`` as Go's ASCII word boundary."""
+    return re.compile(source.replace(r"\d", "[0-9]").replace(r"\b", GO_B), flags)
+
+
+# Ordered as in Go: more specific patterns first, or a UUID becomes a string
+# of <num> fragments.
+TEMPLATE_RULES = [
+    (go_re(r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b", re.IGNORECASE), "<uuid>"),
+    (go_re(r"\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?"), "<ts>"),
+    (go_re(r"\b\d{4}-\d{2}-\d{2}\b"), "<date>"),
+    (go_re(r"\b[^\t\n\f\r <>@]+@[^\t\n\f\r <>@]+\.[A-Za-z]{2,}\b"), "<email>"),
+    (go_re(r"\b[a-z][a-z0-9+.-]*://" + GO_NOT_WS + "+"), "<url>"),
+    (go_re(r"\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b"), "<ip>"),
+    (go_re(r"\b(?:0x)?[0-9a-fA-F]{8,}\b"), "<hex>"),
+    (re.compile(r'"[^"]*"'), "<str>"),
+    (re.compile(r"'[^']*'"), "<str>"),
+    (go_re(r"\b\d+(?:\.\d+)?" + GO_WS + r"?(?:ms|s|us|ns|µs)\b"), "<dur>"),
+    (go_re(r"\b\d+(?:\.\d+)?\b"), "<num>"),
+]
+
+WHITESPACE = re.compile(GO_WS + "+")
+MAX_FRAMES = 5
+KEEP_SEGMENTS = 3
+
+DEPENDENCY_FRAGMENTS = (
+    "/node_modules/", "/vendor/", "/gems/", "/ruby/gems/", "/usr/local/go/src/",
+    "/go/pkg/mod/", "/.bundle/", "<anonymous>",
+)
+
+ASSET_DIGEST = re.compile(r"(.+)[-.]([A-Za-z0-9_]{8,})((?:\.chunk|\.bundle)?\.(?:js|mjs|cjs|css)(?:\.map)?)\Z")
+_SURROGATE = re.compile("[\ud800-\udfff]")
+_LOWER_HEX = re.compile(r"[0-9a-f]*\Z")
+_DIGIT = re.compile("[0-9]")
+_UPPER = re.compile("[A-Z]")
+_QUERY = re.compile(r"[?#]")
+
+
+def utf8(text: Any) -> str:
+    """Go treats invalid UTF-8 as U+FFFD. A Python str cannot hold invalid
+    UTF-8, but it can hold lone surrogates (surrogateescape'd bytes from a
+    path or an environment variable), which cannot be encoded: each becomes
+    U+FFFD, as Go would have read the byte."""
+    if isinstance(text, bytes):
+        return text.decode("utf-8", "replace")
+    if not isinstance(text, str):
+        text = "" if text is None else str(text)
+    if _SURROGATE.search(text):
+        return _SURROGATE.sub("�", text)
+    return text
+
+
+def trim(text: str) -> str:
+    return text.strip(GO_SPACE)
+
+
+def compute(kind: str, source: str, service: str = "", type: str = "", message: str = "",
+            frames: Iterable[Mapping[str, Any]] | None = None) -> str | None:
+    """The fingerprint (64 hex chars) of a signal, or None when the signal has
+    no kind/source, or no type, message or frames (Go returns an error)."""
+    frames = list(frames or [])
+    if not kind or not source:
+        return None
+    if not type and not message and not frames:
+        return None
+    norm = normalize(kind, source, service, type, message, frames)
+    return hashlib.sha256(canonical(norm).encode("utf-8")).hexdigest()
+
+
+def normalize(kind: str, source: str, service: str, type: str, message: str,
+              frames: Iterable[Mapping[str, Any]] | None) -> dict:
+    """The canonical form, field by field, as Go's Normalized."""
+    return {
+        "kind": utf8(kind),
+        "source": utf8(source),
+        "service": utf8(service),
+        "type": trim(utf8(type)),
+        "template": template(message),
+        "frames": _normalize_frames(frames or []),
+    }
+
+
+def template(message: Any) -> str:
+    """Reduces a message to its shape, replacing values that vary between
+    occurrences with holes."""
+    out = trim(utf8(message))
+    if not out:
+        return ""
+    for pattern, hole in TEMPLATE_RULES:
+        out = pattern.sub(hole, out)
+    return trim(WHITESPACE.sub(" ", out))
+
+
+def normalize_path(path: Any) -> str:
+    p = trim(utf8(path))
+    if not p:
+        return ""
+    i = p.find("://")
+    if i >= 0:
+        rest = p[i + 3:]
+        j = rest.find("/")
+        p = rest[j:] if j >= 0 else rest
+    m = _QUERY.search(p)
+    if m:
+        p = p[: m.start()]
+    p = p.replace("\\", "/")
+    segments = p.strip("/").split("/")
+    segments = segments[-KEEP_SEGMENTS:]
+    segments[-1] = _strip_asset_digest(segments[-1])
+    return "/".join(segments)
+
+
+def canonical(norm: Mapping[str, Any]) -> str:
+    return "\x1e".join([
+        "v1", norm["kind"], norm["source"], norm["service"], norm["type"], norm["template"],
+        "\x1f".join(norm["frames"]),
+    ])
+
+
+def _normalize_frames(frames: Iterable[Mapping[str, Any]]) -> list:
+    out = []
+    for f in frames:
+        function = _field(f, "function")
+        file = _field(f, "file")
+        if _dependency(file, function):
+            continue
+        fn = trim(function)
+        path = normalize_path(file)
+        if not fn and not path:
+            continue
+        # Deliberately no line number.
+        out.append(fn + "@" + path)
+        if len(out) == MAX_FRAMES:
+            break
+    return out
+
+
+def _field(frame: Any, name: str) -> str:
+    if not isinstance(frame, Mapping):
+        return ""
+    value = frame.get(name)
+    return "" if value is None else utf8(value)
+
+
+def _dependency(file: str, function: str) -> bool:
+    hay = file + " " + function
+    return any(frag in hay for frag in DEPENDENCY_FRAGMENTS)
+
+
+def _strip_asset_digest(name: str) -> str:
+    m = ASSET_DIGEST.match(name)
+    if m is None or not _digest(m.group(2)):
+        return name
+    return m.group(1) + m.group(3)
+
+
+def _digest(token: str) -> bool:
+    digit = _DIGIT.search(token) is not None
+    upper = _UPPER.search(token) is not None
+    hex_only = _LOWER_HEX.match(token) is not None
+    if hex_only and digit and len(token) >= 8:
+        return True
+    return len(token) == 8 and digit and upper

devbench/flask.py

@@ -0,0 +1,54 @@
+"""Flask::
+
+    from flask import Flask
+    from devbench.flask import Devbench
+
+    app = Flask(__name__)
+    Devbench(app)          # or devbench_ext = Devbench(); devbench_ext.init_app(app)
+
+Wraps ``app.wsgi_app`` in the WSGI middleware (trace, identity scope,
+``x-adt-handled``) and subscribes to ``got_request_exception``, which Flask
+sends for an unhandled exception before it answers 500 (an ``abort(404)`` or
+any other HTTPException is a response, not a failure, and never reaches it).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from flask import got_request_exception, request
+
+from . import _integration
+from .wsgi import DevbenchMiddleware
+
+
+class Devbench:
+    def __init__(self, app: Any = None) -> None:
+        if app is not None:
+            self.init_app(app)
+
+    def init_app(self, app: Any) -> None:
+        extensions = getattr(app, "extensions", None)
+        if isinstance(extensions, dict):
+            if "devbench" in extensions:
+                return
+            extensions["devbench"] = self
+        _integration.setup(service=getattr(app, "import_name", None))
+        app.wsgi_app = DevbenchMiddleware(app.wsgi_app)
+        got_request_exception.connect(_on_exception, app, weak=False)
+
+
+def _on_exception(sender: Any, exception: Optional[BaseException] = None, **_: Any) -> None:
+    try:
+        _integration.report_request_error(exception, _symbol(sender))
+    except Exception:
+        pass
+
+
+def _symbol(app: Any) -> Optional[str]:
+    try:
+        endpoint = request.endpoint
+        view = app.view_functions.get(endpoint) if endpoint else None
+        return _integration.callable_path(view) if view is not None else endpoint
+    except Exception:
+        return None

devbench/identity.py

@@ -0,0 +1,50 @@
+"""Who was affected (docs/SERVER_SDK_SPEC.md, Capability 5).
+
+Identity travels in its own field and nowhere else: never in a message, a
+symbol or a log line, so it can never move a fingerprint.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from . import context
+from .fingerprint import utf8
+
+MAX = 255
+
+
+def normalize(email: Any, account: Any) -> Optional[dict]:
+    """``{"email", "account"}`` with empty fields dropped (email trimmed and
+    lowercased, each at most 255 characters), or None when neither is
+    present."""
+    user = {}
+    e = _text(email).strip().lower()
+    if e:
+        user["email"] = e[:MAX]
+    a = _text(account).strip()
+    if a:
+        user["account"] = a[:MAX]
+    return user or None
+
+
+def set_user(email: Any = None, account: Any = None) -> None:
+    """Records who the current request (or job) is for. Call once per
+    request, e.g. from middleware after authentication; the Dev Bench
+    middleware ends it with the request. Each field is optional; calling
+    again replaces the whole identity, and calling with neither clears it.
+    Never raises."""
+    try:
+        context.ensure().user = normalize(email, account)
+    except Exception:
+        pass
+
+
+def _text(value: Any) -> str:
+    # An identity that cannot be read is dropped rather than raised.
+    if value is None:
+        return ""
+    try:
+        return utf8(value)
+    except Exception:
+        return ""