nthlayer-workers 1.0.0__py3-none-any.whl

nthlayer_workers/respond/notification_backends/ntfy_backend.py

@@ -0,0 +1,158 @@
+"""ntfy notification backend — DND-override push notifications."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+import structlog
+
+from nthlayer_workers.respond.notification_backends.protocol import (
+    NotificationPayload,
+    NotificationResult,
+)
+from nthlayer_workers.respond.oncall.schedule import RosterMember
+
+logger = structlog.get_logger(__name__)
+
+# Map incident severity to ntfy priority.
+# P1 = max (overrides DND), P2 = urgent, P3 = high, P4 = default.
+# Unknown severities default to "high" / "warning" (conservative).
+PRIORITY_MAP = {1: "max", 2: "urgent", 3: "high", 4: "default"}
+_DEFAULT_PRIORITY = "high"
+
+# ntfy tags (emoji) by severity
+TAGS_MAP = {
+    1: "rotating_light,fire",
+    2: "rotating_light,warning",
+    3: "warning",
+    4: "information_source",
+}
+_DEFAULT_TAGS = "warning"
+
+
+class NtfyNotificationBackend:
+    """ntfy push notification delivery.
+
+    Sends high-priority notifications that override Do Not Disturb.
+    Each roster member has a personal ntfy topic. The ntfy server
+    can be self-hosted or use ntfy.sh.
+    """
+
+    def __init__(
+        self,
+        server_url: str | None = None,
+        client: Any | None = None,
+        webhook_base_url: str | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self.server_url = (
+            server_url or os.environ.get("NTFY_SERVER_URL", "https://ntfy.sh")
+        )
+        self._webhook_base_url = webhook_base_url or os.environ.get(
+            "NTHLAYER_WEBHOOK_URL", "http://localhost:8090"
+        )
+        if client is not None:
+            self._client = client
+            self._owns_client = False
+        else:
+            import httpx
+
+            headers = {}
+            auth_token = os.environ.get("NTFY_AUTH_TOKEN")
+            if auth_token:
+                headers["Authorization"] = f"Bearer {auth_token}"
+            self._client = httpx.AsyncClient(headers=headers, timeout=timeout)
+            self._owns_client = True
+
+    async def close(self) -> None:
+        """Release the httpx client if we own it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def send(
+        self, recipient: RosterMember, payload: NotificationPayload
+    ) -> NotificationResult:
+        if not recipient.ntfy_topic:  # None or empty string
+            return NotificationResult(
+                delivered=False,
+                channel="ntfy",
+                recipient=recipient.name,
+                timestamp=datetime.now(timezone.utc),
+                message_id=None,
+                error="No ntfy_topic configured for this user",
+            )
+
+        priority = PRIORITY_MAP.get(payload.severity, _DEFAULT_PRIORITY)
+        title = f"{payload.incident_id}: {payload.title}"
+        body = payload.summary
+        if payload.root_cause:
+            body += f"\nRoot cause: {payload.root_cause}"
+
+        headers: dict[str, str] = {
+            "Title": title,
+            "Priority": priority,
+            "Tags": TAGS_MAP.get(payload.severity, _DEFAULT_TAGS),
+        }
+
+        if payload.actions_url:
+            headers["Click"] = payload.actions_url
+
+        if payload.requires_ack:
+            ack_url = (
+                f"{self._webhook_base_url}/api/v1/incidents/"
+                f"{payload.incident_id}/ack"
+            )
+            headers["Actions"] = (
+                f"http, Acknowledge, {ack_url}, method=POST, clear=true"
+            )
+
+        try:
+            response = await self._client.post(
+                f"{self.server_url}/{recipient.ntfy_topic}",
+                content=body,
+                headers=headers,
+            )
+            response.raise_for_status()
+            try:
+                data = response.json()
+            except Exception:
+                data = {}
+
+            logger.debug(
+                "ntfy_sent",
+                recipient=recipient.name,
+                topic=recipient.ntfy_topic,
+                priority=priority,
+            )
+            return NotificationResult(
+                delivered=True,
+                channel="ntfy",
+                recipient=recipient.name,
+                timestamp=datetime.now(timezone.utc),
+                message_id=data.get("id"),
+                error=None,
+            )
+        except Exception as exc:
+            logger.warning(
+                "ntfy_send_failed",
+                recipient=recipient.name,
+                error=str(exc),
+            )
+            return NotificationResult(
+                delivered=False,
+                channel="ntfy",
+                recipient=recipient.name,
+                timestamp=datetime.now(timezone.utc),
+                message_id=None,
+                error=str(exc),
+            )
+
+    async def health_check(self) -> bool:
+        """Check if the ntfy server is reachable."""
+        try:
+            response = await self._client.get(f"{self.server_url}/v1/health")
+            return response.status_code == 200
+        except Exception:
+            return False

nthlayer_workers/respond/notification_backends/protocol.py

@@ -0,0 +1,59 @@
+"""Notification backend protocol and shared dataclasses.
+
+Every notification channel (Slack, ntfy, Twilio, PagerDuty, stdout)
+implements the ``NotificationBackend`` protocol. The escalation engine
+dispatches to backends without knowing delivery details.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from nthlayer_workers.respond.oncall.schedule import RosterMember
+
+
+@dataclass
+class NotificationPayload:
+    """What to tell the human."""
+
+    incident_id: str
+    severity: int  # 1 = P1 (critical), 2 = P2 (major), 3 = P3 (minor), 4 = P4 (info)
+    title: str
+    summary: str
+    root_cause: str | None
+    blast_radius: list[str]
+    actions_url: str | None
+    escalation_step: int
+    requires_ack: bool
+
+
+@dataclass
+class NotificationResult:
+    """What happened when we tried to notify."""
+
+    delivered: bool
+    channel: str  # "slack_dm" | "ntfy" | "phone" | "pagerduty" | "stdout"
+    recipient: str
+    timestamp: datetime
+    message_id: str | None
+    error: str | None
+
+
+@runtime_checkable
+class NotificationBackend(Protocol):
+    """Protocol for all notification delivery mechanisms.
+
+    Each backend handles one delivery channel. Adding a new channel
+    is one file implementing this protocol.
+    """
+
+    async def send(
+        self,
+        recipient: RosterMember,
+        payload: NotificationPayload,
+    ) -> NotificationResult: ...
+
+    async def health_check(self) -> bool: ...

nthlayer_workers/respond/notification_backends/slack_backend.py

@@ -0,0 +1,203 @@
+"""Slack notification backend — DM and channel notifications with Block Kit."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+import structlog
+
+from nthlayer_workers.respond.notification_backends.protocol import (
+    NotificationPayload,
+    NotificationResult,
+)
+from nthlayer_workers.respond.oncall.schedule import RosterMember
+
+logger = structlog.get_logger(__name__)
+
+# red_circle, orange_circle, yellow_circle, blue_circle
+SEVERITY_EMOJI = {1: "\U0001f534", 2: "\U0001f7e0", 3: "\U0001f7e1", 4: "\U0001f535"}
+
+
+class SlackNotificationBackend:
+    """Slack notification delivery via Web API.
+
+    Two modes:
+    - ``send()``: DM to a specific user via their ``slack_id``
+    - ``send_to_channel()``: post to a Slack channel with @here
+
+    Messages include interactive Acknowledge/Escalate buttons via
+    Slack Block Kit when ``payload.requires_ack`` is True.
+    """
+
+    def __init__(self, client: Any) -> None:  # Any = SlackWebClient or compatible
+        self._client = client
+
+    async def send(
+        self, recipient: RosterMember, payload: NotificationPayload
+    ) -> NotificationResult:
+        """Send a DM to the recipient."""
+        blocks = _build_incident_blocks(payload)
+        fallback = f"{SEVERITY_EMOJI.get(payload.severity, '')} {payload.title}"
+
+        try:
+            message_ts = await self._client.post_message(
+                channel=recipient.slack_id,
+                blocks=blocks,
+                text=fallback,
+            )
+            logger.debug(
+                "slack_dm_sent",
+                recipient=recipient.name,
+                incident_id=payload.incident_id,
+            )
+            return NotificationResult(
+                delivered=True,
+                channel="slack_dm",
+                recipient=recipient.name,
+                timestamp=datetime.now(timezone.utc),
+                message_id=message_ts,
+                error=None,
+            )
+        except Exception as exc:
+            logger.warning(
+                "slack_dm_failed",
+                recipient=recipient.name,
+                error=str(exc),
+            )
+            return NotificationResult(
+                delivered=False,
+                channel="slack_dm",
+                recipient=recipient.name,
+                timestamp=datetime.now(timezone.utc),
+                message_id=None,
+                error=str(exc),
+            )
+
+    async def send_to_channel(
+        self, channel: str, payload: NotificationPayload
+    ) -> NotificationResult:
+        """Post to a Slack channel with @here."""
+        blocks = _build_incident_blocks(payload, include_at_here=True)
+        fallback = f"<!here> {SEVERITY_EMOJI.get(payload.severity, '')} {payload.title}"
+
+        try:
+            message_ts = await self._client.post_message(
+                channel=channel,
+                blocks=blocks,
+                text=fallback,
+            )
+            logger.debug(
+                "slack_channel_sent",
+                channel=channel,
+                incident_id=payload.incident_id,
+            )
+            return NotificationResult(
+                delivered=True,
+                channel="slack_channel",
+                recipient=channel,
+                timestamp=datetime.now(timezone.utc),
+                message_id=message_ts,
+                error=None,
+            )
+        except Exception as exc:
+            logger.warning(
+                "slack_channel_failed",
+                channel=channel,
+                error=str(exc),
+            )
+            return NotificationResult(
+                delivered=False,
+                channel="slack_channel",
+                recipient=channel,
+                timestamp=datetime.now(timezone.utc),
+                message_id=None,
+                error=str(exc),
+            )
+
+    async def health_check(self) -> bool:
+        """Check if the Slack client is usable."""
+        return self._client is not None and bool(
+            getattr(self._client, "bot_token", True)
+        )
+
+
+def _build_incident_blocks(
+    payload: NotificationPayload, *, include_at_here: bool = False
+) -> list[dict[str, Any]]:
+    """Build Slack Block Kit blocks for incident notification."""
+    emoji = SEVERITY_EMOJI.get(payload.severity, "")
+
+    header_text = f"{emoji} {payload.incident_id}: {payload.title}"[:150]
+
+    blocks: list[dict[str, Any]] = [
+        {
+            "type": "header",
+            "text": {
+                "type": "plain_text",
+                "text": header_text,
+            },
+        },
+    ]
+
+    if include_at_here:
+        blocks.append(
+            {
+                "type": "section",
+                "text": {"type": "mrkdwn", "text": "<!here>"},
+            }
+        )
+
+    blocks.append(
+        {
+            "type": "section",
+            "text": {
+                "type": "mrkdwn",
+                "text": payload.summary,
+            },
+        }
+    )
+
+    if payload.root_cause:
+        blocks.append(
+            {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"*Root cause:* {payload.root_cause}",
+                },
+            }
+        )
+
+    if payload.blast_radius:
+        services = ", ".join(f"`{s}`" for s in payload.blast_radius)
+        blocks.append(
+            {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"*Blast radius:* {services}",
+                },
+            }
+        )
+
+    if payload.requires_ack:
+        buttons: list[dict[str, Any]] = [
+            {
+                "type": "button",
+                "text": {"type": "plain_text", "text": "Acknowledge"},
+                "style": "primary",
+                "action_id": "incident_ack",
+                "value": payload.incident_id,
+            },
+            {
+                "type": "button",
+                "text": {"type": "plain_text", "text": "Escalate"},
+                "style": "danger",
+                "action_id": "incident_escalate",
+                "value": payload.incident_id,
+            },
+        ]
+        blocks.append({"type": "actions", "elements": buttons})
+
+    return blocks

nthlayer_workers/respond/notification_backends/stdout_backend.py

@@ -0,0 +1,56 @@
+"""Stdout notification backend — for testing and local development."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import structlog
+
+from nthlayer_workers.respond.notification_backends.protocol import (
+    NotificationPayload,
+    NotificationResult,
+)
+from nthlayer_workers.respond.oncall.schedule import RosterMember
+
+logger = structlog.get_logger(__name__)
+
+SEVERITY_LABEL = {1: "P1 CRITICAL", 2: "P2 MAJOR", 3: "P3 MINOR", 4: "P4 INFO"}
+
+
+class StdoutNotificationBackend:
+    """Print notifications to stdout. For testing and local development."""
+
+    async def send(
+        self, recipient: RosterMember, payload: NotificationPayload
+    ) -> NotificationResult:
+        label = SEVERITY_LABEL.get(payload.severity, f"P{payload.severity}")
+        lines = [
+            f"{'=' * 60}",
+            f"NOTIFICATION -> {recipient.name}",
+            f"  Incident: {payload.incident_id}",
+            f"  Severity: {label}",
+            f"  Title: {payload.title}",
+            f"  Summary: {payload.summary}",
+        ]
+        if payload.root_cause:
+            lines.append(f"  Root cause: {payload.root_cause}")
+        if payload.blast_radius:
+            lines.append(f"  Blast radius: {', '.join(payload.blast_radius)}")
+        lines.append(f"  Escalation step: {payload.escalation_step}")
+        if payload.requires_ack:
+            lines.append("  Requires acknowledgment: yes")
+        lines.append(f"{'=' * 60}")
+
+        print("\n".join(lines))  # noqa: T201 — CLI entrypoint output
+
+        return NotificationResult(
+            delivered=True,
+            channel="stdout",
+            recipient=recipient.name,
+            timestamp=datetime.now(timezone.utc),
+            message_id=None,
+            error=None,
+        )
+
+    async def health_check(self) -> bool:
+        return True