halfabyte-synapse 0.2.0__py3-none-any.whl

synapse/alerts.py

@@ -0,0 +1,227 @@
+"""Tell the owner when something needs them: WhatsApp, Slack, and email through EmailJS.
+
+Ported from Black Box `blackbox/guardian/channels.py`, cut down to these channels. A channel is
+used only when its settings exist in `.env`, and otherwise says what is missing. The outbox always
+keeps a copy. One channel failing never stops the others, and never changes the result of the
+command that raised the alert.
+
+Alerts go out only when asked (`--notify`) or from `synapse alerts test`. The dashboard runs the
+firewall whenever a page scrolls into view, so it must never page anyone.
+
+    Slack     SLACK_WEBHOOK_URL
+    EmailJS   EMAILJS_SERVICE_ID, EMAILJS_TEMPLATE_ID, EMAILJS_PUBLIC_KEY, EMAILJS_PRIVATE_KEY, ALERT_EMAIL_TO
+    WhatsApp  TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_WHATSAPP_FROM, ALERT_WHATSAPP_TO
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from html import escape
+from pathlib import Path
+
+USER_AGENT = "Synapse-Alerts/0.1"  # Cloudflare refuses Python's default User-Agent
+
+
+class ChannelError(RuntimeError):
+    """A delivery the service refused, with the service's own explanation."""
+
+
+@dataclass
+class Alert:
+    title: str
+    lines: list[str] = field(default_factory=list)
+    severity: str = "warning"  # info | warning | critical
+    source: str = "synapse"
+    actions: list[tuple[str, str]] = field(default_factory=list)  # (button label, chat command)
+
+    @property
+    def subject(self) -> str:
+        return f"[Synapse {self.severity}] {self.title}"
+
+    @property
+    def text(self) -> str:
+        return "\n".join([self.subject, "", *self.lines])
+
+    @property
+    def html(self) -> str:
+        items = "".join(f"<li>{escape(line)}</li>" for line in self.lines)
+        return f"<h2>{escape(self.title)}</h2><p>From {escape(self.source)}</p><ul>{items}</ul>"
+
+
+def _post(url: str, data: bytes, headers: dict) -> tuple[int, bytes]:
+    request = urllib.request.Request(url, data=data, headers={"User-Agent": USER_AGENT, **headers})
+    try:
+        with urllib.request.urlopen(request, timeout=20) as reply:
+            return reply.status, reply.read()
+    except urllib.error.HTTPError as exc:
+        raise ChannelError(f"HTTP {exc.code}: {exc.read().decode(errors='replace').strip()[:300]}") from None
+
+
+def _post_json(url: str, payload: dict) -> tuple[int, bytes]:
+    return _post(url, json.dumps(payload).encode(), {"Content-Type": "application/json"})
+
+
+def _twilio(resource: str, fields: dict) -> str:
+    sid = os.environ["TWILIO_ACCOUNT_SID"]
+    auth = base64.b64encode(f"{sid}:{os.environ['TWILIO_AUTH_TOKEN']}".encode()).decode()
+    _, reply = _post(f"https://api.twilio.com/2010-04-01/Accounts/{sid}/{resource}.json",
+                     urllib.parse.urlencode(fields).encode(), {"Authorization": f"Basic {auth}"})
+    return str(json.loads(reply).get("sid"))
+
+
+def _twilio_message(sid: str) -> dict:
+    account = os.environ["TWILIO_ACCOUNT_SID"]
+    auth = base64.b64encode(f"{account}:{os.environ['TWILIO_AUTH_TOKEN']}".encode()).decode()
+    request = urllib.request.Request(f"https://api.twilio.com/2010-04-01/Accounts/{account}/Messages/{sid}.json",
+                                     headers={"User-Agent": USER_AGENT, "Authorization": f"Basic {auth}"})
+    with urllib.request.urlopen(request, timeout=20) as reply:
+        return json.load(reply)
+
+
+class Channel:
+    name = "channel"
+    required: tuple[str, ...] = ()
+
+    def missing(self) -> list[str]:
+        return [n for n in self.required if not os.environ.get(n)]
+
+    def wants(self, alert: Alert) -> bool:  # noqa: ARG002 - subclasses decide by the alert
+        return True
+
+    def send(self, alert: Alert) -> str:
+        raise NotImplementedError
+
+
+class Slack(Channel):
+    name = "slack"
+    required = ("SLACK_WEBHOOK_URL",)
+
+    def send(self, alert: Alert) -> str:
+        payload: dict = {"text": alert.text}
+        if alert.actions:
+            payload["blocks"] = [
+                {"type": "section", "text": {"type": "mrkdwn", "text": alert.text[:2900]}},
+                {"type": "actions", "elements": [
+                    {"type": "button", "text": {"type": "plain_text", "text": label}, "value": command,
+                     "action_id": f"synapse_{i}"}
+                    for i, (label, command) in enumerate(alert.actions)]},
+            ]
+        status, _ = _post_json(os.environ["SLACK_WEBHOOK_URL"], payload)
+        return f"posted ({status})"
+
+
+class EmailJS(Channel):
+    """The template must use {{subject}}, {{to_email}} and {{{html_message}}}."""
+
+    name = "email-emailjs"
+    required = ("EMAILJS_SERVICE_ID", "EMAILJS_TEMPLATE_ID", "EMAILJS_PUBLIC_KEY", "EMAILJS_PRIVATE_KEY",
+                "ALERT_EMAIL_TO")
+
+    def send(self, alert: Alert) -> str:
+        status, _ = _post_json("https://api.emailjs.com/api/v1.0/email/send", {
+            "service_id": os.environ["EMAILJS_SERVICE_ID"],
+            "template_id": os.environ["EMAILJS_TEMPLATE_ID"],
+            "user_id": os.environ["EMAILJS_PUBLIC_KEY"],
+            "accessToken": os.environ["EMAILJS_PRIVATE_KEY"],
+            "template_params": {"to_email": os.environ["ALERT_EMAIL_TO"], "subject": alert.subject,
+                                "html_message": alert.html, "text_message": alert.text,
+                                "severity": alert.severity},
+        })
+        return f"sent ({status})"
+
+
+class WhatsApp(Channel):
+    """Twilio accepting a message is not delivery, so this waits for the real outcome."""
+
+    name = "whatsapp-twilio"
+    required = ("TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN", "TWILIO_WHATSAPP_FROM", "ALERT_WHATSAPP_TO")
+    WAIT_S = 15.0
+
+    def send(self, alert: Alert) -> str:
+        sid = _twilio("Messages", {"From": os.environ["TWILIO_WHATSAPP_FROM"], "To": os.environ["ALERT_WHATSAPP_TO"],
+                                   "Body": alert.text[:1500]})
+        deadline = time.monotonic() + self.WAIT_S
+        state: dict = {}
+        while time.monotonic() < deadline:
+            state = _twilio_message(sid)
+            if state.get("status") in ("delivered", "read"):
+                return str(state["status"])
+            if state.get("status") in ("failed", "undelivered"):
+                code = state.get("error_code")
+                raise ChannelError(f"{state['status']}, Twilio error {code}. {WHY.get(code, '')}".strip())
+            time.sleep(1.0)
+        return f"not confirmed after {self.WAIT_S:.0f} s, status {state.get('status')}"
+
+
+#: What the owner has to do about Twilio's WhatsApp errors.
+WHY = {
+    63015: "This number has not joined the sandbox: send the join code to the sandbox number on WhatsApp.",
+    63016: "Outside the 24-hour window: send any message to the sandbox number on WhatsApp, then try again.",
+}
+
+
+CHANNELS: tuple[Channel, ...] = (WhatsApp(), Slack(), EmailJS())
+
+
+def _outbox(alert: Alert) -> Path:
+    root = Path(os.environ.get("SYNAPSE_DATA", "data")) / "outbox"
+    root.mkdir(parents=True, exist_ok=True)
+    path = root / f"{time.strftime('%Y%m%d-%H%M%S')}-{alert.severity}.txt"
+    path.write_text(alert.text, encoding="utf-8")
+    return path
+
+
+def status() -> list[tuple[str, str]]:
+    """Every channel and whether it is ready. Names settings, never their values."""
+    return [(c.name, f"needs {', '.join(c.missing())}" if c.missing() else "ready") for c in CHANNELS]
+
+
+def send(alert: Alert, channels: tuple[Channel, ...] = CHANNELS) -> list[tuple[str, str, str]]:
+    """Deliver everywhere it can. Returns (channel, sent | skipped | failed, detail)."""
+    results = [("outbox", "sent", str(_outbox(alert)))]
+    for channel in channels:
+        if channel.missing():
+            results.append((channel.name, "skipped", f"needs {', '.join(channel.missing())}"))
+        elif not channel.wants(alert):
+            results.append((channel.name, "skipped", "not for this alert"))
+        else:
+            try:
+                results.append((channel.name, "sent", channel.send(alert)))
+            except (ChannelError, OSError) as exc:
+                results.append((channel.name, "failed", str(exc)))
+    return results
+
+
+def from_verdict(workflow: str, verdict: dict, graph_id: str | None = None) -> Alert:
+    decision = verdict["decision"]
+    return Alert(
+        title=f"{workflow}: firewall said {decision}",
+        severity="warning" if decision == "BLOCK" else "info",
+        source=graph_id or workflow,
+        lines=[
+            str(verdict.get("reason", "")),
+            f"{verdict.get('broken', 0)} broke, {verdict.get('fixed', 0)} fixed, "
+            f"{verdict.get('unchanged', 0)} unchanged, on {verdict.get('split', 'an unnamed split')}",
+            f"Reply: why {workflow}, receipt {workflow}, or hold {workflow}",
+        ],
+        actions=[("Why", f"why {workflow}"), ("Receipt", f"receipt {workflow}"), ("Savings", f"savings {workflow}"),
+                 ("Hold", f"hold {workflow}"), *([("Ship", f"ship {workflow}")] if decision == "APPROVE" else [])],
+    )
+
+
+def from_regression(workflow: str, problems: list[str]) -> Alert:
+    return Alert(title=f"{workflow} regressed", severity="critical", source="synapse ci", lines=list(problems))
+
+
+def from_audit(model: str, result: dict) -> Alert:
+    return Alert(title=f"{model}: answers are not stable", severity="warning", source="synapse audit",
+                 lines=[f"Varied one at a time: {result['varied_one_at_a_time']} of {result['prompts']}",
+                        f"Varied under concurrency: {result['varied_under_concurrency']} of {result['prompts']}",
+                        result["advice"]])