schemawatch-core 0.1.0__py3-none-any.whl

schemawatch/__init__.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from schemawatch.diff import Change, DriftEvent, diff
+from schemawatch.infer import SchemaNode, infer_schema, merge
+from schemawatch.redact import DYNAMIC_KEY_WILDCARD, DynamicKeyWildcard, redact
+from schemawatch.severity import (
+    KIND_BECAME_NULLABLE,
+    KIND_ENUM_CHANGED,
+    KIND_FIELD_ADDED,
+    KIND_FIELD_MISSING,
+    KIND_TYPE_CHANGED,
+    SEVERITY_BREAKING,
+    SEVERITY_INFO,
+    SEVERITY_WARNING,
+    calculate_severity,
+)
+from schemawatch.store import MemoryStore, RedisStore, Store
+from schemawatch.watchdog import Watchdog
+
+if TYPE_CHECKING:
+    from schemawatch.alerts import SlackAlert, WebhookAlert, fan_out
+    from schemawatch.integrations.httpx_hook import SchemawatchHTTPXHook, create_httpx_hook
+
+__all__ = [
+    "Change",
+    "DYNAMIC_KEY_WILDCARD",
+    "DriftEvent",
+    "DynamicKeyWildcard",
+    "KIND_BECAME_NULLABLE",
+    "KIND_ENUM_CHANGED",
+    "KIND_FIELD_ADDED",
+    "KIND_FIELD_MISSING",
+    "KIND_TYPE_CHANGED",
+    "MemoryStore",
+    "RedisStore",
+    "SEVERITY_BREAKING",
+    "SEVERITY_INFO",
+    "SEVERITY_WARNING",
+    "SchemaNode",
+    "SchemawatchHTTPXHook",
+    "SlackAlert",
+    "Store",
+    "Watchdog",
+    "WebhookAlert",
+    "calculate_severity",
+    "create_httpx_hook",
+    "diff",
+    "fan_out",
+    "infer_schema",
+    "merge",
+    "redact",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy module exports so 'import schemawatch' works without httpx installed."""
+    if name in ("SlackAlert", "WebhookAlert", "fan_out"):
+        import schemawatch.alerts as alerts
+
+        return getattr(alerts, name)
+    if name in ("SchemawatchHTTPXHook", "create_httpx_hook"):
+        import schemawatch.integrations.httpx_hook as httpx_hook
+
+        return getattr(httpx_hook, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

schemawatch/alerts/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from schemawatch.alerts.slack import SlackAlert
+from schemawatch.alerts.webhook import WebhookAlert
+from schemawatch.diff import Change, DriftEvent
+
+logger = logging.getLogger(__name__)
+
+
+def fan_out(
+    *dispatchers: Callable[[DriftEvent], None],
+) -> Callable[[DriftEvent | Change], None]:
+    """Combine multiple alert dispatchers into a single fail-open callback.
+
+    Dispatches sequentially to each handler. If one handler raises an exception,
+    the exception is logged and swallowed so subsequent handlers still execute.
+    """
+
+    def _composite(event: DriftEvent | Change) -> None:
+        drift_event = (
+            event
+            if isinstance(event, DriftEvent)
+            else DriftEvent(vendor="unknown", endpoint="unknown", changes=(event,))
+        )
+        for dispatcher in dispatchers:
+            try:
+                dispatcher(drift_event)
+            except Exception as exc:
+                logger.exception("schemawatch fan_out: dispatcher failed: %s", exc)
+
+    return _composite
+
+
+__all__ = [
+    "SlackAlert",
+    "WebhookAlert",
+    "fan_out",
+]

schemawatch/alerts/retry.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import logging
+import urllib.error
+from typing import Final
+
+logger = logging.getLogger(__name__)
+
+RETRYABLE_STATUS_CODES: Final[frozenset[int]] = frozenset({408, 425, 429})
+MAX_RETRY_AFTER_SECONDS: Final[float] = 30.0
+
+
+def should_retry_error(exc: Exception) -> tuple[bool, float | None]:
+    """Determine whether an HTTP/network exception should be retried.
+
+    Rules:
+    - Network errors (URLError, OSError, TimeoutError) are retried.
+    - HTTP status codes 408, 425, 429, and 5xx are retried.
+    - Other 4xx status codes (400, 401, 403, 404, etc.) are NOT retried.
+    - If a Retry-After header is present on a retryable HTTP response, its value
+      is honoured as seconds and capped at 30 seconds.
+
+    Returns:
+        (should_retry, retry_after_delay_in_seconds)
+    """
+    if isinstance(exc, urllib.error.HTTPError):
+        code = exc.code
+        if code in RETRYABLE_STATUS_CODES or code >= 500:
+            retry_after: float | None = None
+            if exc.headers:
+                raw_ra = exc.headers.get("Retry-After")
+                if raw_ra:
+                    try:
+                        retry_after = min(max(0.0, float(raw_ra)), MAX_RETRY_AFTER_SECONDS)
+                    except ValueError:
+                        retry_after = None
+            return True, retry_after
+        # Other 4xx are client errors and should NOT be retried
+        if 400 <= code < 500:
+            return False, None
+        return False, None
+
+    if isinstance(exc, (urllib.error.URLError, OSError, TimeoutError)):
+        return True, None
+
+    return False, None

schemawatch/alerts/slack.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+from schemawatch.alerts.retry import should_retry_error
+from schemawatch.diff import Change, DriftEvent
+from schemawatch.severity import SEVERITY_BREAKING, SEVERITY_INFO, SEVERITY_WARNING
+
+logger = logging.getLogger(__name__)
+
+SLACK_COLOR_MAP: dict[str, str] = {
+    SEVERITY_BREAKING: "#E01E5A",  # Red / Danger
+    SEVERITY_WARNING: "#ECB22E",  # Yellow / Warning
+    SEVERITY_INFO: "#2F80ED",  # Blue / Info
+}
+SLACK_COLOR_DEFAULT = "#2F80ED"  # Blue / Info
+
+
+class SlackAlert:
+    """Fail-open Slack incoming webhook dispatcher with rich formatting.
+
+    Maps schema drift changes to colored Slack attachments.
+    Never raises exceptions into host application and never logs raw webhook URLs.
+    """
+
+    def __init__(
+        self,
+        webhook_url: str,
+        *,
+        channel: str | None = None,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+        backoff_seconds: float = 0.5,
+        sleep_fn: Callable[[float], None] = time.sleep,
+    ) -> None:
+        parsed = urllib.parse.urlparse(webhook_url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(
+                f"Invalid alert webhook URL scheme: {parsed.scheme!r}. Must be http or https."
+            )
+        self._url = webhook_url
+        self._channel = channel
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._backoff = backoff_seconds
+        self._sleep_fn = sleep_fn
+        self.last_status_code: int | None = None
+        self.last_response_body: str | None = None
+        self.last_attempts: int = 0
+
+    def __repr__(self) -> str:
+        return f"SlackAlert(webhook_url='***redacted***', channel={self._channel!r})"
+
+    def __call__(self, event: DriftEvent | Change) -> None:
+        """Dispatch drift event alert to Slack."""
+        self.send(event)
+
+    def _build_payload(self, event: DriftEvent) -> dict[str, Any]:
+        header_text = f":warning: API Contract Drift Detected: *{event.vendor}* `{event.endpoint}`"
+
+        # Group changes by severity in priority order
+        severity_order = [SEVERITY_BREAKING, SEVERITY_WARNING, SEVERITY_INFO]
+        changes_by_sev: dict[str, list[Change]] = {sev: [] for sev in severity_order}
+
+        for ch in event.changes:
+            if ch.severity in changes_by_sev:
+                changes_by_sev[ch.severity].append(ch)
+            else:
+                changes_by_sev[SEVERITY_INFO].append(ch)
+
+        attachments: list[dict[str, Any]] = []
+        for sev in severity_order:
+            sev_changes = changes_by_sev[sev]
+            if not sev_changes:
+                continue
+
+            color = SLACK_COLOR_MAP.get(sev, SLACK_COLOR_DEFAULT)
+            fields: list[dict[str, Any]] = []
+            for ch in sev_changes:
+                desc = ch.detail or (f"`{ch.was}` -> `{ch.now}`" if ch.was or ch.now else ch.kind)
+                fields.append(
+                    {
+                        "title": f"`{ch.field}`",
+                        "value": f"*{ch.kind}*: {desc}",
+                        "short": len(ch.field) <= 24,
+                    }
+                )
+
+            count_str = f" ({len(sev_changes)})" if len(sev_changes) > 1 else ""
+            attachments.append(
+                {
+                    "color": color,
+                    "title": f"[{sev.upper()}]{count_str}",
+                    "fields": fields,
+                    "ts": int(event.detected_at),
+                }
+            )
+
+        payload: dict[str, Any] = {
+            "text": header_text,
+            "attachments": attachments,
+        }
+        if self._channel:
+            payload["channel"] = self._channel
+        return payload
+
+    def send(self, event: DriftEvent | Change) -> bool:
+        """Send formatted Slack message with retries.
+
+        Returns True if successful, False otherwise. Never raises exceptions.
+        """
+        # Normalize Change to DriftEvent if passed directly
+        if isinstance(event, Change):
+            drift_event = DriftEvent(
+                vendor="unknown",
+                endpoint="unknown",
+                changes=(event,),
+            )
+        else:
+            drift_event = event
+
+        payload = self._build_payload(drift_event)
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "schemawatch-slack-alert/0.1.0",
+        }
+
+        self.last_status_code = None
+        self.last_response_body = None
+        self.last_attempts = 0
+
+        for attempt in range(1, self._max_retries + 2):
+            self.last_attempts = attempt
+            try:
+                req = urllib.request.Request(
+                    self._url,
+                    data=data,
+                    headers=headers,
+                    method="POST",
+                )
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # nosec B310
+                    self.last_status_code = resp.status
+                    self.last_response_body = resp.read().decode("utf-8", errors="replace")
+                    if 200 <= resp.status < 300:
+                        return True
+            except urllib.error.HTTPError as http_exc:
+                self.last_status_code = http_exc.code
+                try:
+                    self.last_response_body = http_exc.read().decode("utf-8", errors="replace")
+                except Exception:
+                    self.last_response_body = None
+                should_retry, retry_after = should_retry_error(http_exc)
+                logger.warning(
+                    "schemawatch: slack alert delivery failed (attempt %d/%d): HTTP %d",
+                    attempt,
+                    self._max_retries + 1,
+                    http_exc.code,
+                )
+                if not should_retry:
+                    return False
+
+                if attempt <= self._max_retries:
+                    delay = (
+                        retry_after
+                        if retry_after is not None
+                        else self._backoff * (2 ** (attempt - 1))
+                    )
+                    self._sleep_fn(delay)
+            except Exception as exc:
+                should_retry, retry_after = should_retry_error(exc)
+                # Privacy rule: NEVER log the webhook URL
+                logger.warning(
+                    "schemawatch: slack alert delivery failed (attempt %d/%d): %s",
+                    attempt,
+                    self._max_retries + 1,
+                    type(exc).__name__,
+                )
+                if not should_retry:
+                    return False
+
+                if attempt <= self._max_retries:
+                    delay = (
+                        retry_after
+                        if retry_after is not None
+                        else self._backoff * (2 ** (attempt - 1))
+                    )
+                    self._sleep_fn(delay)
+
+        logger.error(
+            "schemawatch: slack alert delivery exhausted all retries for %s %s",
+            drift_event.vendor,
+            drift_event.endpoint,
+        )
+        return False

schemawatch/alerts/webhook.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import logging
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+from schemawatch.alerts.retry import should_retry_error
+from schemawatch.diff import Change, DriftEvent
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookAlert:
+    """Fail-open generic webhook alert dispatcher with retries.
+
+    Dispatches JSON alert payloads to a configured HTTP webhook endpoint.
+    Guaranteed never to raise exceptions into the host application and never
+    to log raw webhook URLs (preventing token/credential leaks).
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        secret: str | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float = 5.0,
+        max_retries: int = 2,
+        backoff_seconds: float = 0.5,
+        sleep_fn: Callable[[float], None] = time.sleep,
+    ) -> None:
+        parsed = urllib.parse.urlparse(url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(
+                f"Invalid alert webhook URL scheme: {parsed.scheme!r}. Must be http or https."
+            )
+        self._url = url
+        self._secret = secret
+        self._headers = headers or {}
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._backoff = backoff_seconds
+        self._sleep_fn = sleep_fn
+        self.last_status_code: int | None = None
+        self.last_response_body: str | None = None
+        self.last_attempts: int = 0
+
+    def __repr__(self) -> str:
+        return f"WebhookAlert(url='***redacted***', timeout={self._timeout})"
+
+    def __call__(self, event: DriftEvent | Change) -> None:
+        """Dispatch drift event alert to the webhook."""
+        self.send(event)
+
+    def send(self, event: DriftEvent | Change) -> bool:
+        """Send drift event alert with retries.
+
+        Returns True if successful, False otherwise. Never raises exceptions.
+        """
+        # Normalize single Change to DriftEvent if passed directly
+        if isinstance(event, Change):
+            drift_event = DriftEvent(
+                vendor="unknown",
+                endpoint="unknown",
+                changes=(event,),
+            )
+        else:
+            drift_event = event
+
+        payload: dict[str, Any] = {
+            "event": "schema_drift",
+            "vendor": drift_event.vendor,
+            "endpoint": drift_event.endpoint,
+            "highest_severity": drift_event.highest_severity,
+            "detected_at": drift_event.detected_at,
+            "changes": [c.to_dict() for c in drift_event.changes],
+        }
+
+        data = json.dumps(payload).encode("utf-8")
+        req_headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "schemawatch-alert/0.1.0",
+            **self._headers,
+        }
+        if self._secret:
+            sig = hmac.new(self._secret.encode("utf-8"), data, hashlib.sha256).hexdigest()
+            req_headers["X-Schemawatch-Signature"] = f"sha256={sig}"
+
+        self.last_status_code = None
+        self.last_response_body = None
+        self.last_attempts = 0
+
+        for attempt in range(1, self._max_retries + 2):
+            self.last_attempts = attempt
+            try:
+                req = urllib.request.Request(
+                    self._url,
+                    data=data,
+                    headers=req_headers,
+                    method="POST",
+                )
+                with urllib.request.urlopen(req, timeout=self._timeout) as resp:  # nosec B310
+                    self.last_status_code = resp.status
+                    self.last_response_body = resp.read().decode("utf-8", errors="replace")
+                    if 200 <= resp.status < 300:
+                        return True
+            except urllib.error.HTTPError as http_exc:
+                self.last_status_code = http_exc.code
+                try:
+                    self.last_response_body = http_exc.read().decode("utf-8", errors="replace")
+                except Exception:
+                    self.last_response_body = None
+                should_retry, retry_after = should_retry_error(http_exc)
+                logger.warning(
+                    "schemawatch: webhook delivery failed (attempt %d/%d): HTTP %d",
+                    attempt,
+                    self._max_retries + 1,
+                    http_exc.code,
+                )
+                if not should_retry:
+                    return False
+
+                if attempt <= self._max_retries:
+                    delay = (
+                        retry_after
+                        if retry_after is not None
+                        else self._backoff * (2 ** (attempt - 1))
+                    )
+                    self._sleep_fn(delay)
+            except Exception as exc:
+                should_retry, retry_after = should_retry_error(exc)
+                # Privacy rule: NEVER log the webhook URL
+                logger.warning(
+                    "schemawatch: webhook delivery failed (attempt %d/%d): %s",
+                    attempt,
+                    self._max_retries + 1,
+                    type(exc).__name__,
+                )
+                if not should_retry:
+                    return False
+
+                if attempt <= self._max_retries:
+                    delay = (
+                        retry_after
+                        if retry_after is not None
+                        else self._backoff * (2 ** (attempt - 1))
+                    )
+                    self._sleep_fn(delay)
+
+        logger.error(
+            "schemawatch: webhook alert delivery exhausted all retries for %s %s",
+            drift_event.vendor,
+            drift_event.endpoint,
+        )
+        return False