commitguardian 0.1.0__py3-none-any.whl

commitguard/notifications/outbox.py

@@ -0,0 +1,106 @@
+"""The notification outbox.
+
+::
+
+    domain transaction (scan result / policy version / installation state)
+      ├── state change
+      ├── audit event
+      └── notification event  ── emit(db, event)      <- same transaction
+                                     │
+    dispatcher (background)          ▼
+      notification_events WHERE dispatched_at IS NULL
+      -> in-app notifications, e-mail and webhook deliveries (one transaction)
+
+Because the event is written with the state change, a crash can never leave a
+policy change or a blocked commit without its notification, and a failed
+transaction never produces a notification for a change that did not happen.
+Delivery is a separate, later step: a provider outage cannot undo or delay the
+security decision.
+"""
+
+import json
+import sqlite3
+from datetime import datetime
+
+from commitguard.notifications.deduplication import storage_key
+from commitguard.notifications.models import NotificationEvent
+from commitguard.observability.logging import current_correlation, get_logger
+
+log = get_logger(__name__)
+
+
+def emit(db: sqlite3.Connection, event: NotificationEvent, now: datetime) -> str:
+    """Write ``event`` inside the caller's transaction. Returns the stored event ID.
+
+    A repeat of an event with the same storage key (see
+    :mod:`commitguard.notifications.deduplication`) updates the stored event and
+    marks its in-app notifications unread again; it does not fan out again.
+    """
+    key = storage_key(event.type, event.dedup_key, now)
+    correlation = current_correlation()
+
+    def _corr(name: str) -> str | None:
+        value = correlation.get(name)
+        return None if value is None else str(value)[:128]
+
+    cursor = db.execute(
+        "INSERT INTO notification_events (event_id, account_id, type, severity, installation_id, "
+        "repository_id, resource_type, resource_id, dedup_key, title, body, metadata, "
+        "occurrences, created_at, last_occurred_at, request_id, delivery_id, job_id) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?) "
+        "ON CONFLICT (account_id, dedup_key) DO NOTHING",
+        (
+            event.event_id,
+            event.account_id,
+            event.type.value,
+            event.severity.value,
+            event.installation_id,
+            event.repository_id,
+            event.resource_type,
+            event.resource_id,
+            key,
+            event.title,
+            event.body,
+            json.dumps(event.metadata, sort_keys=True),
+            now.timestamp(),
+            now.timestamp(),
+            _corr("request_id"),
+            _corr("delivery_id"),
+            _corr("job_id"),
+        ),
+    )
+    if cursor.rowcount == 1:
+        log.info("notification_event_emitted", type=event.type.value, event_id=event.event_id)
+        return event.event_id
+    row = db.execute(
+        "SELECT event_id FROM notification_events WHERE account_id = ? AND dedup_key = ?",
+        (event.account_id, key),
+    ).fetchone()
+    existing = str(row["event_id"])
+    db.execute(
+        "UPDATE notification_events SET occurrences = occurrences + 1, last_occurred_at = ?, "
+        "title = ?, body = ?, metadata = ?, resource_id = ? WHERE event_id = ?",
+        (
+            now.timestamp(),
+            event.title,
+            event.body,
+            json.dumps(event.metadata, sort_keys=True),
+            event.resource_id,
+            existing,
+        ),
+    )
+    db.execute(
+        "UPDATE notifications SET state = CASE WHEN state = 'read' THEN 'unread' ELSE state END, "
+        "read_at = CASE WHEN state = 'read' THEN NULL ELSE read_at END, "
+        "updated_at = ?, sort_at = ? WHERE event_id = ? AND state != 'archived'",
+        (now.timestamp(), now.timestamp(), existing),
+    )
+    log.info("notification_event_coalesced", type=event.type.value, event_id=existing)
+    return existing
+
+
+def account_for_installation(db: sqlite3.Connection, installation_id: int) -> int | None:
+    row = db.execute(
+        "SELECT account_id FROM installations WHERE installation_id = ?", (int(installation_id),)
+    ).fetchone()
+    return int(row["account_id"]) if row is not None else None

commitguard/notifications/preferences.py

@@ -0,0 +1,224 @@
+"""Notification preferences: organization defaults, personal choices, effective result.
+
+::
+
+    built-in defaults (per type)
+      + organization settings   administrators (notifications:manage), versioned
+      + personal preferences    each member, in-app only, for their own inbox
+      = effective preferences
+
+Ownership rules:
+
+* **Organization settings** decide which types reach the organization's e-mail
+  recipients and webhooks, and whether a non-mandatory type appears in members'
+  inboxes at all. Only ``notifications:manage`` may change them; turning a
+  delivery *off* needs explicit confirmation.
+* **Personal preferences** only mute non-mandatory types in the member's own
+  inbox. They cannot touch e-mail, webhooks or anyone else's inbox, so a viewer
+  can never silence security notifications for the organization.
+* **Mandatory** in-app types (see :mod:`commitguard.notifications.models`) are
+  delivered to every eligible member regardless of either setting.
+"""
+
+import json
+import re
+import sqlite3
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from commitguard.controlplane.errors import InputValidationError
+from commitguard.notifications.models import (
+    DEFINITIONS,
+    NotificationChannel,
+    NotificationType,
+    TypeDefinition,
+)
+
+MAX_EMAIL_RECIPIENTS = 20
+MAX_EMAIL_CHARS = 254
+# Deliberately strict: a plain mailbox address, no display name, comments or quoting.
+_EMAIL_RE = re.compile(
+    r"\A[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]{1,64}@[A-Za-z0-9-]{1,63}(\.[A-Za-z0-9-]{1,63})+\Z"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelSetting:
+    in_app: bool
+    email: bool
+    webhook: bool
+
+
+@dataclass(frozen=True, slots=True)
+class OrganizationSettings:
+    account_id: int
+    version: int  # 0: built-in defaults, never saved
+    types: Mapping[NotificationType, ChannelSetting]
+    email_recipients: tuple[str, ...]
+    updated_at: datetime | None = None
+    updated_by: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class UserPreferences:
+    user_id: int
+    account_id: int
+    muted: frozenset[NotificationType] = field(default_factory=frozenset)
+
+
+def default_setting(definition: TypeDefinition) -> ChannelSetting:
+    return ChannelSetting(
+        in_app=definition.default_in_app or definition.mandatory_in_app,
+        email=definition.default_email,
+        webhook=definition.default_webhook,
+    )
+
+
+def _normalize(document: Mapping[str, object]) -> dict[NotificationType, ChannelSetting]:
+    types: dict[NotificationType, ChannelSetting] = {}
+    for notification_type, definition in DEFINITIONS.items():
+        default = default_setting(definition)
+        raw = document.get(notification_type.value)
+        entry = raw if isinstance(raw, Mapping) else {}
+        in_app = entry.get("in_app", default.in_app)
+        email = entry.get("email", default.email)
+        webhook = entry.get("webhook", default.webhook)
+        types[notification_type] = ChannelSetting(
+            in_app=True if definition.mandatory_in_app else bool(in_app),
+            email=bool(email),
+            webhook=bool(webhook),
+        )
+    return types
+
+
+def load_organization_settings(db: sqlite3.Connection, account_id: int) -> OrganizationSettings:
+    row = db.execute(
+        "SELECT * FROM notification_settings WHERE account_id = ?", (int(account_id),)
+    ).fetchone()
+    if row is None:
+        return OrganizationSettings(account_id, 0, _normalize({}), ())
+    return OrganizationSettings(
+        account_id=int(account_id),
+        version=int(row["version"]),
+        types=_normalize(json.loads(row["document"])),
+        email_recipients=tuple(json.loads(row["email_recipients"])),
+        updated_at=datetime.fromtimestamp(float(row["updated_at"]), UTC),
+        updated_by=row["updated_by_login"],
+    )
+
+
+def load_user_preferences(db: sqlite3.Connection, user_id: int, account_id: int) -> UserPreferences:
+    rows = db.execute(
+        "SELECT type, in_app FROM notification_user_preferences WHERE user_id = ? "
+        "AND account_id = ?",
+        (int(user_id), int(account_id)),
+    ).fetchall()
+    muted = frozenset(
+        NotificationType(r["type"]) for r in rows if not r["in_app"] and r["type"] in DEFINITIONS
+    )
+    return UserPreferences(int(user_id), int(account_id), muted)
+
+
+def in_app_enabled(
+    definition: TypeDefinition,
+    organization: OrganizationSettings,
+    user: UserPreferences | None,
+) -> bool:
+    if definition.mandatory_in_app:
+        return True
+    if not organization.types[definition.type].in_app:
+        return False
+    return user is None or definition.type not in user.muted
+
+
+# --------------------------------------------------------------------------- #
+# Validation of API input
+# --------------------------------------------------------------------------- #
+def parse_type(value: object, field_name: str) -> NotificationType:
+    if not isinstance(value, str) or value not in {t.value for t in NotificationType}:
+        raise InputValidationError("unknown notification type", field=field_name)
+    return NotificationType(value)
+
+
+def validate_organization_document(raw: object) -> dict[NotificationType, ChannelSetting]:
+    """``{"type": {"in_app": bool, "email": bool, "webhook": bool}}`` - partial updates allowed."""
+    if not isinstance(raw, Mapping):
+        raise InputValidationError("types must be an object of notification types", field="types")
+    document: dict[str, dict[str, bool]] = {}
+    for key, entry in raw.items():
+        notification_type = parse_type(key, "types")
+        if not isinstance(entry, Mapping):
+            raise InputValidationError("each type must be an object", field=f"types.{key}")
+        clean: dict[str, bool] = {}
+        for channel, value in entry.items():
+            if channel not in {c.value for c in NotificationChannel}:
+                raise InputValidationError("unknown channel", field=f"types.{key}")
+            if not isinstance(value, bool):
+                raise InputValidationError(
+                    "channel settings must be true or false", field=f"types.{key}.{channel}"
+                )
+            if (
+                channel == NotificationChannel.IN_APP.value
+                and not value
+                and DEFINITIONS[notification_type].mandatory_in_app
+            ):
+                raise InputValidationError(
+                    "in-app delivery of this notification type cannot be turned off",
+                    field=f"types.{key}.in_app",
+                )
+            clean[channel] = value
+        document[notification_type.value] = clean
+    return _normalize(document)
+
+
+def validate_email_recipients(raw: object) -> tuple[str, ...]:
+    if not isinstance(raw, Sequence) or isinstance(raw, str):
+        raise InputValidationError("email_recipients must be a list", field="email_recipients")
+    if len(raw) > MAX_EMAIL_RECIPIENTS:
+        raise InputValidationError(
+            f"at most {MAX_EMAIL_RECIPIENTS} e-mail recipients", field="email_recipients"
+        )
+    recipients: list[str] = []
+    for item in raw:
+        if (
+            not isinstance(item, str)
+            or len(item) > MAX_EMAIL_CHARS
+            or not _EMAIL_RE.match(item.strip())
+        ):
+            raise InputValidationError(
+                "each recipient must be a plain e-mail address", field="email_recipients"
+            )
+        address = item.strip().lower()
+        if address not in recipients:
+            recipients.append(address)
+    return tuple(recipients)
+
+
+def serialize(types: Mapping[NotificationType, ChannelSetting]) -> str:
+    return json.dumps(
+        {
+            t.value: {"in_app": s.in_app, "email": s.email, "webhook": s.webhook}
+            for t, s in sorted(types.items())
+        },
+        sort_keys=True,
+    )
+
+
+def disabled_deliveries(
+    before: OrganizationSettings,
+    types: Mapping[NotificationType, ChannelSetting],
+    recipients: Sequence[str],
+) -> list[str]:
+    """Human-readable list of deliveries a settings change turns off (needs confirmation)."""
+    removed: list[str] = []
+    for notification_type, setting in types.items():
+        old = before.types[notification_type]
+        label = DEFINITIONS[notification_type].label
+        for channel in ("in_app", "email", "webhook"):
+            if getattr(old, channel) and not getattr(setting, channel):
+                removed.append(f"{label}: {channel.replace('_', '-')}")
+    dropped = sorted(set(before.email_recipients) - set(recipients))
+    if dropped:
+        removed.append(f"e-mail recipients removed: {len(dropped)}")
+    return removed

commitguard/notifications/retry.py

@@ -0,0 +1,282 @@
+"""Delivery worker: bounded retries for e-mail and webhook deliveries.
+
+::
+
+    pending ──claim (lease)──> attempt ──success──> sent
+                                  │
+                                  ├─ retryable failure, attempts < 5 ──> pending
+                                  │     next_retry_at = now + 1m, 5m, 30m, 2h
+                                  └─ permanent failure, or 5th attempt ──> failed
+
+* **Bounded.** At most :data:`MAX_ATTEMPTS` attempts; there is no infinite loop.
+* **One sender at a time.** A delivery is claimed with a lease
+  (:data:`LEASE_SECONDS`) through a conditional update; another worker or
+  process skips it until the lease expires.
+* **Idempotent.** The idempotency key travels with every attempt. If a process
+  dies after the provider accepted a message but before ``sent`` was stored,
+  the lease expires and the message is sent again with the *same* key, which
+  receivers use to discard the duplicate (at-least-once delivery).
+* **Secondary to security.** Failures change only the delivery record. The
+  scan result, the violation, the policy version and the in-app notification
+  are already stored.
+"""
+
+import sqlite3
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+
+from commitguard.audit.models import AuditEventType
+from commitguard.github.storage import SqliteStateStore
+from commitguard.notifications.channels.base import DeliveryError, DeliveryReceipt
+from commitguard.notifications.channels.email import EmailProvider
+from commitguard.notifications.channels.webhook import WebhookProvider
+from commitguard.notifications.dispatcher import stored_event
+from commitguard.notifications.models import (
+    DeliveryStatus,
+    NotificationChannel,
+    StoredNotificationEvent,
+)
+from commitguard.notifications.templates import render_email, render_webhook
+from commitguard.observability.logging import correlation, get_logger
+from commitguard.observability.metrics import (
+    NOTIFICATION_RETRIES,
+    NOTIFICATIONS_FAILED,
+    NOTIFICATIONS_SENT,
+    Metrics,
+)
+from commitguard.services.audit import AuditService
+
+log = get_logger(__name__)
+
+MAX_ATTEMPTS = 5
+BACKOFF_SECONDS = (60, 300, 1800, 7200)
+LEASE_SECONDS = 120
+DELIVERY_BATCH = 50
+
+
+def retry_delay(attempts_made: int) -> timedelta | None:
+    """Delay before the next attempt, or None when no attempt is left."""
+    if attempts_made >= MAX_ATTEMPTS:
+        return None
+    return timedelta(seconds=BACKOFF_SECONDS[min(attempts_made, len(BACKOFF_SECONDS)) - 1])
+
+
+def mask_destination(channel: str, destination: str) -> str:
+    """How a destination appears in audit events (no full e-mail addresses)."""
+    if channel != NotificationChannel.EMAIL.value or "@" not in destination:
+        return destination
+    local, _, domain = destination.partition("@")
+    return f"{local[:1]}***@{domain}"
+
+
+class DeliveryWorker:
+    def __init__(
+        self,
+        store: SqliteStateStore,
+        audit: AuditService,
+        metrics: Metrics,
+        *,
+        email: EmailProvider | None,
+        webhook: WebhookProvider | None,
+        dashboard_origin: str | None,
+        now: Callable[[], datetime] = lambda: datetime.now(UTC),
+    ) -> None:
+        self._store = store
+        self._audit = audit
+        self._metrics = metrics
+        self._email = email
+        self._webhook = webhook
+        self._origin = dashboard_origin
+        self._now = now
+
+    # ------------------------------------------------------------------ #
+    def deliver_due(self, limit: int = DELIVERY_BATCH) -> int:
+        now = self._now().timestamp()
+        rows = self._store.query(
+            "SELECT delivery_id FROM notification_deliveries WHERE status = 'pending' "
+            "AND (next_retry_at IS NULL OR next_retry_at <= ?) "
+            "AND (lease_expires_at IS NULL OR lease_expires_at < ?) ORDER BY created_at LIMIT ?",
+            (now, now, int(limit)),
+        )
+        attempted = 0
+        for row in rows:
+            if self._claim(str(row["delivery_id"])):
+                self._attempt(str(row["delivery_id"]))
+                attempted += 1
+        return attempted
+
+    def _claim(self, delivery_id: str) -> bool:
+        now = self._now().timestamp()
+        with self._store.transaction() as db:
+            return (
+                db.execute(
+                    "UPDATE notification_deliveries SET lease_expires_at = ?, updated_at = ? "
+                    "WHERE delivery_id = ? AND status = 'pending' AND (next_retry_at IS NULL OR "
+                    "next_retry_at <= ?) AND (lease_expires_at IS NULL OR lease_expires_at < ?)",
+                    (now + LEASE_SECONDS, now, delivery_id, now, now),
+                ).rowcount
+                == 1
+            )
+
+    def _attempt(self, delivery_id: str) -> None:
+        rows = self._store.query(
+            "SELECT d.*, e.event_id AS e_event_id, i.account_login, "
+            "(SELECT owner || '/' || name FROM known_repositories k WHERE "
+            "k.installation_id = e.installation_id AND k.repository_id = e.repository_id) "
+            "AS repository_name, w.url AS webhook_url, w.removed_at AS webhook_removed_at "
+            "FROM notification_deliveries d JOIN notification_events e ON e.event_id = d.event_id "
+            "LEFT JOIN (SELECT account_id, MIN(account_login) AS account_login FROM installations "
+            "GROUP BY account_id) i ON i.account_id = d.account_id "
+            "LEFT JOIN notification_webhooks w ON w.endpoint_id = d.destination "
+            "AND w.account_id = d.account_id WHERE d.delivery_id = ?",
+            (delivery_id,),
+        )
+        if not rows:
+            return
+        row = rows[0]
+        event_rows = self._store.query(
+            "SELECT * FROM notification_events WHERE event_id = ?", (row["event_id"],)
+        )
+        stored = stored_event(event_rows[0])
+        organization = row["account_login"] or f"account {row['account_id']}"
+        channel = str(row["channel"])
+        with correlation(notification_event_id=stored.event.event_id):
+            try:
+                receipt = self._send(row, stored, organization, channel)
+            except DeliveryError as exc:
+                self._failed(row, exc)
+            except Exception as exc:  # noqa: BLE001 - a delivery bug must not stop the worker
+                log.error("notification_delivery_crashed", error_type=type(exc).__name__)
+                self._failed(row, DeliveryError("internal_error"))
+            else:
+                self._sent(row, receipt)
+
+    def _send(
+        self,
+        row: sqlite3.Row,
+        stored: StoredNotificationEvent,
+        organization: str,
+        channel: str,
+    ) -> DeliveryReceipt:
+        if channel == NotificationChannel.EMAIL.value:
+            if self._email is None:
+                raise _Cancelled("email_channel_unavailable")
+            return self._email.send(
+                render_email(
+                    stored,
+                    to=str(row["destination"]),
+                    organization=organization,
+                    dashboard_origin=self._origin,
+                ),
+                idempotency_key=str(row["idempotency_key"]),
+            )
+        if self._webhook is None:
+            raise _Cancelled("webhook_channel_unavailable")
+        if row["webhook_url"] is None or row["webhook_removed_at"] is not None:
+            raise _Cancelled("webhook_endpoint_removed")
+        now = self._now()
+        return self._webhook.send(
+            url=str(row["webhook_url"]),
+            endpoint_id=str(row["destination"]),
+            event_type=stored.event.type.value,
+            body=render_webhook(
+                stored,
+                organization=organization,
+                repository=row["repository_name"],
+                dashboard_origin=self._origin,
+                now=now,
+            ),
+            idempotency_key=str(row["idempotency_key"]),
+            timestamp=int(now.timestamp()),
+        )
+
+    # ------------------------------------------------------------------ #
+    def _sent(self, row: sqlite3.Row, receipt: DeliveryReceipt) -> None:
+        now = self._now().timestamp()
+        with self._store.transaction() as db:
+            db.execute(
+                "UPDATE notification_deliveries SET status = 'sent', attempt_count = "
+                "attempt_count + 1, provider = ?, provider_message_id = ?, failure_code = NULL, "
+                "last_attempt_at = ?, next_retry_at = NULL, lease_expires_at = NULL, "
+                "updated_at = ? WHERE delivery_id = ?",
+                (
+                    receipt.provider,
+                    (receipt.provider_message_id or "")[:200] or None,
+                    now,
+                    now,
+                    row["delivery_id"],
+                ),
+            )
+            event = self._store.insert_audit_event(
+                db,
+                self._audit.build(
+                    AuditEventType.NOTIFICATION_DELIVERED,
+                    account_id=int(row["account_id"]),
+                    channel=str(row["channel"]),
+                    destination=mask_destination(str(row["channel"]), str(row["destination"])),
+                    notification_delivery=str(row["delivery_id"]),
+                    notification_event=str(row["event_id"]),
+                    attempts=int(row["attempt_count"]) + 1,
+                ),
+            )
+        self._audit.log_stored(event)
+        self._metrics.increment(NOTIFICATIONS_SENT, channel=str(row["channel"]))
+
+    def _failed(self, row: sqlite3.Row, error: DeliveryError) -> None:
+        now = self._now()
+        attempts = int(row["attempt_count"]) + 1
+        cancelled = isinstance(error, _Cancelled)
+        delay = None if (error.permanent or cancelled) else retry_delay(attempts)
+        if cancelled:
+            status = DeliveryStatus.CANCELLED
+        elif delay is None:
+            status = DeliveryStatus.FAILED
+        else:
+            status = DeliveryStatus.PENDING
+        with self._store.transaction() as db:
+            db.execute(
+                "UPDATE notification_deliveries SET status = ?, attempt_count = ?, "
+                "failure_code = ?, last_attempt_at = ?, next_retry_at = ?, "
+                "lease_expires_at = NULL, updated_at = ? WHERE delivery_id = ?",
+                (
+                    status.value,
+                    attempts,
+                    error.code,
+                    now.timestamp(),
+                    (now + delay).timestamp() if delay is not None else None,
+                    now.timestamp(),
+                    row["delivery_id"],
+                ),
+            )
+            event = self._store.insert_audit_event(
+                db,
+                self._audit.build(
+                    AuditEventType.NOTIFICATION_DELIVERY_FAILED,
+                    account_id=int(row["account_id"]),
+                    channel=str(row["channel"]),
+                    destination=mask_destination(str(row["channel"]), str(row["destination"])),
+                    notification_delivery=str(row["delivery_id"]),
+                    notification_event=str(row["event_id"]),
+                    attempts=attempts,
+                    failure_code=error.code,
+                    status=status.value,
+                    retry_scheduled=delay is not None,
+                ),
+            )
+        self._audit.log_stored(event)
+        if status is DeliveryStatus.PENDING:
+            self._metrics.increment(NOTIFICATION_RETRIES, channel=str(row["channel"]))
+        else:
+            self._metrics.increment(NOTIFICATIONS_FAILED, channel=str(row["channel"]))
+        log.warning(
+            "notification_delivery_failed",
+            channel=str(row["channel"]),
+            failure_code=error.code,
+            attempts=attempts,
+            status=status.value,
+        )
+
+
+class _Cancelled(DeliveryError):
+    def __init__(self, code: str) -> None:
+        super().__init__(code, permanent=True)