foxray 0.1.2__py3-none-any.whl

foxray/__init__.py

@@ -0,0 +1,3 @@
+"""Foxray: a light error tracker that speaks the Sentry SDK protocol."""
+
+__version__ = "0.1.2"

foxray/__main__.py

@@ -0,0 +1,3 @@
+from foxray.standalone.cli import main
+
+raise SystemExit(main())

foxray/core/__init__.py

@@ -0,0 +1,2 @@
+"""Foxray core: protocol parsing, normalising, grouping, scrubbing, rules and
+the SQL store. Pure standard library; never imports Django."""

foxray/core/alerts.py

@@ -0,0 +1,225 @@
+"""Alerts: decided inside the ingest transaction, written to the
+``foxray_alert`` outbox, and sent after commit by a short background
+thread. A send that fails is retried with backoff; nothing is lost if the
+mail server is down for a while.
+
+Issue alerts fire on a new issue and on a regression (a resolved issue seen
+again, or an ignored one past its "until"). Repeats never alert, and a
+regression within the cooldown of the issue's last alert stays quiet.
+Per project: new and/or regression, a minimum level, and environments."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Callable
+
+from .models import Alert, Issue, Monitor, Project, level_rank
+from .settings import Settings
+from .util import utcnow
+
+log = logging.getLogger("foxray.alerts")
+
+KIND_LABELS = {
+    "new_issue": "New issue",
+    "regression": "Regression",
+    "unignored": "Back after ignore",
+    "monitor_error": "Monitor failed",
+    "monitor_missed": "Monitor missed a check-in",
+    "monitor_timeout": "Monitor timed out",
+    "store_full": "Storage full",
+}
+
+
+class Links:
+    """Where things live in the UI, for the links in alerts."""
+
+    def __init__(self, base_url: str = ""):
+        self.base_url = (base_url or "").rstrip("/")
+
+    def issue(self, issue_id: int) -> str:
+        return f"{self.base_url}/issues/{issue_id}"
+
+    def monitor(self, monitor_id: int) -> str:
+        return f"{self.base_url}/monitors/{monitor_id}"
+
+    def storage(self) -> str:
+        return f"{self.base_url}/storage"
+
+
+@dataclass
+class AlertDraft:
+    kind: str
+    subject: str
+    body: str
+    payload: dict = field(default_factory=dict)
+    issue_id: int | None = None
+    monitor_id: int | None = None
+
+
+def _split(value: str) -> list[str]:
+    return [p.strip() for p in (value or "").split(",") if p.strip()]
+
+
+def should_alert_issue(project: Project, settings: Settings, issue: Issue, kind: str,
+                       environment: str, now: datetime) -> bool:
+    if kind == "new_issue" and not project.alert_new:
+        return False
+    if kind in ("regression", "unignored") and not project.alert_regression:
+        return False
+    if project.alert_min_level and level_rank(issue.level) < level_rank(project.alert_min_level):
+        return False
+    envs = _split(project.alert_environments)
+    if envs and environment not in envs:
+        return False
+    if kind != "new_issue" and issue.last_alerted_at is not None:
+        if now - issue.last_alerted_at < timedelta(seconds=settings.alert_cooldown_seconds):
+            return False
+    return True
+
+
+def issue_draft(project: Project, issue: Issue, kind: str, ev: dict, links: Links) -> AlertDraft:
+    label = KIND_LABELS.get(kind, kind)
+    url = links.issue(issue.id)
+    env = ev.get("environment") or ""
+    lines = [
+        f"{label} in {project.name}: {issue.title}",
+        "",
+        f"Where:       {issue.culprit or '-'}",
+        f"Level:       {issue.level}",
+        f"Environment: {env or '-'}",
+        f"Release:     {ev.get('release') or '-'}",
+        f"Seen:        {issue.times_seen} time(s), first {issue.first_seen:%Y-%m-%d %H:%M} UTC",
+        "",
+        url,
+    ]
+    payload = {
+        "kind": kind, "project": project.name, "project_id": project.id, "issue_id": issue.id,
+        "title": issue.title, "culprit": issue.culprit, "level": issue.level, "environment": env,
+        "release": ev.get("release") or "", "times_seen": issue.times_seen,
+        "first_seen": issue.first_seen.isoformat(), "last_seen": issue.last_seen.isoformat(),
+        "event_id": ev.get("event_id"), "url": url,
+    }
+    return AlertDraft(kind, f"[Foxray] {label}: {issue.title}"[:300], "\n".join(lines), payload, issue_id=issue.id)
+
+
+def monitor_draft(project: Project, monitor: Monitor, kind: str, links: Links, detail: str = "") -> AlertDraft:
+    label = KIND_LABELS.get(kind, kind)
+    url = links.monitor(monitor.id)
+    schedule = f"{monitor.schedule_type} {monitor.schedule_value} {monitor.schedule_unit}".strip()
+    body = "\n".join([f"{label} in {project.name}: {monitor.slug}", "", f"Schedule: {schedule or '-'}",
+                      detail, "", url])
+    payload = {"kind": kind, "project": project.name, "project_id": project.id, "monitor_id": monitor.id,
+               "monitor": monitor.slug, "schedule": schedule, "detail": detail, "url": url}
+    return AlertDraft(kind, f"[Foxray] {label}: {monitor.slug}", body, payload, monitor_id=monitor.id)
+
+
+def store_full_draft(size: int, cap: int, links: Links) -> AlertDraft:
+    mb = lambda n: f"{n / 1048576:.1f} MB"  # noqa: E731
+    body = (f"Foxray's store is at {mb(size)}, over its cap of {mb(cap)}, even after removing old event "
+            f"bodies.\n\nIt is now counting only: issues are still grouped, counted and alerted, but new event "
+            f"bodies are not stored until there is room again.\n\n{links.storage()}")
+    return AlertDraft("store_full", "[Foxray] Storage full: counting only", body,
+                      {"kind": "store_full", "size": size, "cap": cap, "url": links.storage()})
+
+
+def queue_alert(store, project: Project | None, draft: AlertDraft, channels: list[str], now: datetime) -> None:
+    for channel in channels or ["log"]:
+        store.add_alert(project_id=project.id if project else None, kind=draft.kind, channel=channel,
+                        subject=draft.subject, body=draft.body, payload=draft.payload, now=now,
+                        issue_id=draft.issue_id, monitor_id=draft.monitor_id)
+
+
+def post_webhook(url: str, alert: Alert, timeout: float = 10) -> str:
+    try:
+        payload = json.loads(alert.payload)
+    except ValueError:
+        payload = {}
+    payload.setdefault("subject", alert.subject)
+    payload.setdefault("text", alert.body)
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(url, data=data, method="POST",
+                                 headers={"Content-Type": "application/json", "User-Agent": "foxray"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 - admin-configured URL
+        if resp.status >= 300:
+            raise RuntimeError(f"webhook answered {resp.status}")
+        return f"webhook {resp.status}"
+
+
+def webhook_sender(default_url: str):
+    def send(alert: Alert, project: Project | None) -> str:
+        url = (project.alert_webhook if project else "") or default_url
+        if not url:
+            return "no webhook URL"
+        return post_webhook(url, alert)
+    return send
+
+
+Sender = Callable[[Alert, "Project | None"], "str | None"]
+
+
+class Outbox:
+    """Sends pending alerts. Safe to run in several processes at once: each
+    alert is claimed with a conditional UPDATE before it is sent."""
+
+    def __init__(self, store, settings: Settings, senders: dict[str, Sender], clock=utcnow):
+        self.store = store
+        self.settings = settings
+        self.senders = senders
+        self.clock = clock
+        self._running = threading.Lock()
+
+    @staticmethod
+    def backoff(attempts: int) -> timedelta:
+        return timedelta(seconds=min(3600, 60 * (2 ** min(attempts, 6))))
+
+    def flush(self, now: datetime | None = None, limit: int = 50) -> dict:
+        now = now or self.clock()
+        sent = failed = 0
+        give_up = timedelta(days=self.settings.failed_alert_retention_days)
+        projects: dict = {}
+        for alert in self.store.due_alerts(now, limit):
+            if now - alert.created_at > give_up:
+                self.store.mark_alert_error(alert.id, alert.last_error or "gave up", failed=True)
+                failed += 1
+                continue
+            if not self.store.claim_alert(alert.id, now, now + self.backoff(alert.attempts)):
+                continue
+            if alert.project_id is not None and alert.project_id not in projects:
+                projects[alert.project_id] = self.store.get_project(alert.project_id)
+            project = projects.get(alert.project_id)
+            sender = self.senders.get(alert.channel)
+            try:
+                if sender is None:
+                    log.warning("alert (no channel configured): %s", alert.subject)
+                    note = "logged only: no email or webhook configured"
+                else:
+                    note = sender(alert, project) or ""
+                self.store.mark_alert_sent(alert.id, self.clock(), note)
+                sent += 1
+            except Exception as exc:  # noqa: BLE001 - any failure means retry later
+                log.warning("alert %s via %s failed: %s", alert.id, alert.channel, exc)
+                self.store.mark_alert_error(alert.id, f"{type(exc).__name__}: {exc}")
+                failed += 1
+        return {"sent": sent, "failed": failed}
+
+    def kick(self, on_thread_exit: Callable | None = None) -> None:
+        """Send due alerts on a short background thread (one per process)."""
+        if not self._running.acquire(blocking=False):
+            return
+
+        def run():
+            try:
+                self.flush()
+            except Exception:  # noqa: BLE001
+                log.exception("sending alerts failed")
+            finally:
+                self._running.release()
+                if on_thread_exit:
+                    on_thread_exit()
+
+        threading.Thread(target=run, name="foxray-alerts", daemon=True).start()

foxray/core/auth.py

@@ -0,0 +1,54 @@
+"""Finding the public key an SDK sent: the ``X-Sentry-Auth`` header, an
+``Authorization: Sentry ...`` header, ``sentry_key`` in the query string, or
+the ``dsn`` in an envelope header (used by browser tunnels)."""
+
+from __future__ import annotations
+
+import hmac
+from typing import Mapping
+
+from .dsn import DsnError, parse_dsn
+
+
+def parse_auth_header(value: str) -> dict[str, str]:
+    """``Sentry sentry_key=abc, sentry_version=7, sentry_client=x/1.0``."""
+    if not value:
+        return {}
+    s = value.strip()
+    if s[:7].lower() == "sentry ":
+        s = s[7:]
+    out: dict[str, str] = {}
+    for part in s.split(","):
+        key, sep, val = part.strip().partition("=")
+        if sep and key.strip():
+            out[key.strip()] = val.strip().strip('"')
+    return out
+
+
+def extract_public_key(headers: Mapping[str, str], query: Mapping[str, str],
+                       envelope_header: dict | None = None) -> str | None:
+    """``headers`` must have lower-case names."""
+    raw = headers.get("x-sentry-auth")
+    if not raw:
+        authz = headers.get("authorization", "")
+        if authz[:7].lower() == "sentry ":
+            raw = authz
+    if raw:
+        key = parse_auth_header(raw).get("sentry_key")
+        if key:
+            return key
+    key = query.get("sentry_key") if query else None
+    if key:
+        return key
+    if envelope_header and isinstance(envelope_header.get("dsn"), str):
+        try:
+            return parse_dsn(envelope_header["dsn"]).public_key
+        except DsnError:
+            return None
+    return None
+
+
+def key_matches(given: str | None, expected: str) -> bool:
+    if not given or not expected:
+        return False
+    return hmac.compare_digest(given.encode(), expected.encode())

foxray/core/cron.py

@@ -0,0 +1,176 @@
+"""Monitor schedules, as the SDKs send them in ``monitor_config``:
+``{"type": "crontab", "value": "0 * * * *"}`` or
+``{"type": "interval", "value": 2, "unit": "hour"}``, with an optional
+IANA ``timezone``."""
+
+from __future__ import annotations
+
+import calendar
+from datetime import datetime, timedelta
+from functools import lru_cache
+
+try:
+    from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+except ImportError:  # pragma: no cover
+    ZoneInfo = None  # type: ignore
+    ZoneInfoNotFoundError = Exception  # type: ignore
+
+from .util import UTC
+
+
+class ScheduleError(ValueError):
+    pass
+
+
+MACROS = {
+    "@yearly": "0 0 1 1 *", "@annually": "0 0 1 1 *", "@monthly": "0 0 1 * *",
+    "@weekly": "0 0 * * 0", "@daily": "0 0 * * *", "@midnight": "0 0 * * *", "@hourly": "0 * * * *",
+}
+_MONTHS = {m.lower(): i for i, m in enumerate(calendar.month_abbr) if m}
+_DAYS = {"sun": 0, "mon": 1, "tue": 2, "wed": 3, "thu": 4, "fri": 5, "sat": 6}
+UNITS = ("minute", "hour", "day", "week", "month", "year")
+
+
+def _value(token: str, names: dict, lo: int, hi: int) -> int:
+    t = token.strip().lower()
+    if t in names:
+        return names[t]
+    if not t.isdigit():
+        raise ScheduleError(f"bad crontab value: {token!r}")
+    v = int(t)
+    if not lo <= v <= hi:
+        raise ScheduleError(f"crontab value {v} out of range {lo}-{hi}")
+    return v
+
+
+def _field(spec: str, lo: int, hi: int, names: dict | None = None) -> tuple[frozenset, bool]:
+    names = names or {}
+    out: set[int] = set()
+    star = spec.strip() == "*"
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            raise ScheduleError("empty crontab field")
+        rng, _, step_s = part.partition("/")
+        step = 1
+        if step_s:
+            if not step_s.isdigit() or int(step_s) == 0:
+                raise ScheduleError(f"bad crontab step: {part!r}")
+            step = int(step_s)
+        if rng == "*":
+            start, end = lo, hi
+        elif "-" in rng:
+            a, b = rng.split("-", 1)
+            start, end = _value(a, names, lo, hi), _value(b, names, lo, hi)
+            if end < start:
+                raise ScheduleError(f"bad crontab range: {part!r}")
+        else:
+            start = _value(rng, names, lo, hi)
+            end = hi if step_s else start
+        out.update(range(start, end + 1, step))
+    return frozenset(out), star
+
+
+class Crontab:
+    def __init__(self, expr: str):
+        expr = (expr or "").strip()
+        expr = MACROS.get(expr.lower(), expr)
+        parts = expr.split()
+        if len(parts) != 5:
+            raise ScheduleError("a crontab needs 5 fields")
+        self.minutes, _ = _field(parts[0], 0, 59)
+        self.hours, _ = _field(parts[1], 0, 23)
+        self.doms, self.dom_star = _field(parts[2], 1, 31)
+        self.months, _ = _field(parts[3], 1, 12, _MONTHS)
+        dows, self.dow_star = _field(parts[4], 0, 7, _DAYS)
+        self.dows = frozenset(0 if d == 7 else d for d in dows)
+
+    def _day_ok(self, d: datetime) -> bool:
+        dom_ok = d.day in self.doms
+        dow_ok = (d.isoweekday() % 7) in self.dows
+        if self.dom_star or self.dow_star:
+            return dom_ok and dow_ok
+        return dom_ok or dow_ok  # cron: either restricted day field may match
+
+    def next_after(self, after: datetime, tz=UTC) -> datetime:
+        """The first scheduled minute strictly after ``after``."""
+        local = after.astimezone(tz).replace(tzinfo=None, second=0, microsecond=0) + timedelta(minutes=1)
+        limit = local + timedelta(days=366 * 5)
+        while local < limit:
+            if local.month not in self.months:
+                y, m = (local.year + 1, 1) if local.month == 12 else (local.year, local.month + 1)
+                local = local.replace(year=y, month=m, day=1, hour=0, minute=0)
+                continue
+            if not self._day_ok(local):
+                local = (local + timedelta(days=1)).replace(hour=0, minute=0)
+                continue
+            if local.hour not in self.hours:
+                local = (local + timedelta(hours=1)).replace(minute=0)
+                continue
+            if local.minute not in self.minutes:
+                local += timedelta(minutes=1)
+                continue
+            return local.replace(tzinfo=tz).astimezone(UTC)
+        raise ScheduleError("crontab never fires")
+
+
+@lru_cache(maxsize=256)
+def crontab(expr: str) -> Crontab:
+    return Crontab(expr)
+
+
+def zone(name: str | None):
+    if not name or ZoneInfo is None:
+        return UTC
+    try:
+        return ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError, OSError):
+        return UTC
+
+
+def add_interval(dt: datetime, value: int, unit: str) -> datetime:
+    if unit == "minute":
+        return dt + timedelta(minutes=value)
+    if unit == "hour":
+        return dt + timedelta(hours=value)
+    if unit == "day":
+        return dt + timedelta(days=value)
+    if unit == "week":
+        return dt + timedelta(weeks=value)
+    if unit in ("month", "year"):
+        months = value * (12 if unit == "year" else 1)
+        y, m = divmod(dt.month - 1 + months, 12)
+        year, month = dt.year + y, m + 1
+        day = min(dt.day, calendar.monthrange(year, month)[1])
+        return dt.replace(year=year, month=month, day=day)
+    raise ScheduleError(f"bad interval unit: {unit!r}")
+
+
+def parse_schedule(config: dict) -> tuple[str, str, str]:
+    """Validate an SDK ``monitor_config['schedule']``; returns (type, value, unit)."""
+    if not isinstance(config, dict):
+        raise ScheduleError("schedule must be an object")
+    kind = config.get("type")
+    if kind == "crontab":
+        value = str(config.get("value") or "").strip()
+        crontab(value)
+        return "crontab", value, ""
+    if kind == "interval":
+        try:
+            value = int(config.get("value"))
+        except (TypeError, ValueError):
+            raise ScheduleError("interval value must be a number") from None
+        unit = str(config.get("unit") or "").lower().rstrip("s")
+        if value <= 0 or unit not in UNITS:
+            raise ScheduleError("interval needs a positive value and a unit")
+        return "interval", str(value), unit
+    raise ScheduleError("schedule type must be crontab or interval")
+
+
+def next_expected(schedule_type: str, value: str, unit: str, tz_name: str, after: datetime) -> datetime | None:
+    """When the next run should start, given the last check-in at ``after``."""
+    if schedule_type == "crontab" and value:
+        return crontab(value).next_after(after, zone(tz_name))
+    if schedule_type == "interval" and value:
+        return add_interval(after, int(value), unit)
+    return None

foxray/core/dsn.py

@@ -0,0 +1,63 @@
+"""DSNs: ``scheme://public_key[:secret]@host[:port]/[path/]project_id``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+
+class DsnError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Dsn:
+    scheme: str
+    public_key: str
+    secret_key: str
+    host: str
+    port: int | None
+    path: str          # prefix before the project id, without trailing slash ("" or "/foxray")
+    project_id: str
+
+    @property
+    def netloc(self) -> str:
+        return self.host if self.port is None else f"{self.host}:{self.port}"
+
+    def endpoint(self, kind: str = "envelope") -> str:
+        return f"{self.scheme}://{self.netloc}{self.path}/api/{self.project_id}/{kind}/"
+
+    def __str__(self) -> str:
+        secret = f":{self.secret_key}" if self.secret_key else ""
+        return f"{self.scheme}://{self.public_key}{secret}@{self.netloc}{self.path}/{self.project_id}"
+
+
+def parse_dsn(value: str) -> Dsn:
+    if not value or not isinstance(value, str):
+        raise DsnError("empty DSN")
+    parts = urlsplit(value.strip())
+    if parts.scheme not in ("http", "https"):
+        raise DsnError("DSN scheme must be http or https")
+    if not parts.username:
+        raise DsnError("DSN has no public key")
+    if not parts.hostname:
+        raise DsnError("DSN has no host")
+    path = parts.path.rstrip("/")
+    prefix, _, project_id = path.rpartition("/")
+    if not project_id:
+        raise DsnError("DSN has no project id")
+    try:
+        port = parts.port
+    except ValueError as exc:
+        raise DsnError(str(exc)) from None
+    return Dsn(parts.scheme, parts.username, parts.password or "", parts.hostname, port, prefix, project_id)
+
+
+def make_dsn(base_url: str, public_key: str, project_id) -> str:
+    """``base_url`` is where ingest is mounted, e.g. ``https://host`` for the
+    standalone server or ``https://host/foxray`` for the Django app."""
+    parts = urlsplit((base_url or "http://localhost").strip())
+    scheme = parts.scheme or "http"
+    netloc = parts.netloc or parts.path
+    path = parts.path.rstrip("/") if parts.netloc else ""
+    return f"{scheme}://{public_key}@{netloc}{path}/{project_id}"