pynotifyhub 0.1.0__py3-none-any.whl

notify_hub/__init__.py

@@ -0,0 +1,75 @@
+"""notify-hub: unified multi-channel notification library.
+
+Quickstart::
+
+    from notify_hub import Hub
+
+    hub = Hub.from_config("notify-hub.toml")
+    hub.notify("db down", level="CRITICAL")   # returns immediately
+"""
+
+from .capabilities import Capability, DegradeMode, DegradePolicy
+from .channels.base import Channel
+from .exceptions import (
+    ChannelSendError,
+    ConfigError,
+    HubClosedError,
+    NotifyHubError,
+    UnknownChannelError,
+    UnknownLevelError,
+)
+from .guard import Deduplicator, TokenBucket
+from .hub import Hub
+from .levels import CRITICAL, DEBUG, ERROR, INFO, WARNING, Level, LevelRegistry
+from .logging import (
+    FileNotificationLogger,
+    MultiLogger,
+    NotificationLogger,
+    NullLogger,
+    SendRecord,
+    StdlibNotificationLogger,
+)
+from .message import Attachment, AttachmentKind, Message
+from .registry import register_channel
+from .results import ChannelResult, NotificationHandle, NotificationResult
+from .router import Router, RoutingRule
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CRITICAL",
+    "DEBUG",
+    "ERROR",
+    "INFO",
+    "WARNING",
+    "Attachment",
+    "AttachmentKind",
+    "Capability",
+    "Channel",
+    "ChannelResult",
+    "ChannelSendError",
+    "ConfigError",
+    "Deduplicator",
+    "DegradeMode",
+    "DegradePolicy",
+    "FileNotificationLogger",
+    "Hub",
+    "HubClosedError",
+    "Level",
+    "LevelRegistry",
+    "Message",
+    "MultiLogger",
+    "NotificationHandle",
+    "NotificationLogger",
+    "NotificationResult",
+    "NotifyHubError",
+    "NullLogger",
+    "Router",
+    "RoutingRule",
+    "SendRecord",
+    "StdlibNotificationLogger",
+    "TokenBucket",
+    "UnknownChannelError",
+    "UnknownLevelError",
+    "register_channel",
+]

notify_hub/_util.py

@@ -0,0 +1,79 @@
+"""Small internal helpers: fingerprinting, truncation, backoff, TTS cleanup."""
+
+from __future__ import annotations
+
+import hashlib
+import random
+import re
+
+_MD_PATTERNS = (
+    re.compile(r"```.*?```", re.DOTALL),  # code blocks
+    re.compile(r"`([^`]*)`"),  # inline code -> keep content
+    re.compile(r"!\[[^\]]*\]\([^)]*\)"),  # images
+    re.compile(r"\[([^\]]*)\]\([^)]*\)"),  # links -> keep label
+    re.compile(r"https?://\S+"),  # bare URLs
+    re.compile(r"[*_~#>|]+"),  # emphasis / heading / table markers
+)
+
+
+def fingerprint(level_name: str, title: str | None, body: str) -> str:
+    """Stable 16-hex-char digest used for dedup and log correlation."""
+    payload = "\x00".join((level_name, title or "", body))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]
+
+
+def truncate(text: str, limit: int, *, suffix: str = "…") -> str:
+    """Truncate by character count, appending a suffix when cut."""
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[: max(limit - len(suffix), 0)] + suffix
+
+
+def truncate_utf8_bytes(text: str, limit: int, *, suffix: str = "…") -> str:
+    """Truncate so the UTF-8 encoding fits in ``limit`` bytes (WeCom limits)."""
+    raw = text.encode("utf-8")
+    if len(raw) <= limit:
+        return text
+    suffix_len = len(suffix.encode("utf-8"))
+    cut = raw[: max(limit - suffix_len, 0)]
+    return cut.decode("utf-8", errors="ignore") + suffix
+
+
+def backoff_delay(attempt: int, *, base: float = 1.0, cap: float = 30.0) -> float:
+    """Exponential backoff with full jitter: attempt 1 -> ~1s, 2 -> ~2s, 3 -> ~4s."""
+    return random.uniform(0, min(cap, base * (2 ** (attempt - 1))))
+
+
+_SECRET_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    # query-string credentials (wecom key=, dingtalk access_token=, signatures)
+    (re.compile(r"(?i)\b(key|access_token|sign|secret|token)=[^&\s'\"]+"), r"\1=***"),
+    # telegram bot token in the URL path
+    (re.compile(r"/bot\d+:[\w-]+"), "/bot***"),
+    # slack incoming-webhook path
+    (re.compile(r"(hooks\.slack\.com/services/)[\w/]+"), r"\1***"),
+    # discord webhook id/token path
+    (re.compile(r"(discord(?:app)?\.com/api/webhooks/\d+/)[\w-]+"), r"\1***"),
+    # lark/feishu webhook token path
+    (re.compile(r"(/open-apis/bot/v2/hook/)[\w-]+"), r"\1***"),
+)
+
+
+def redact_secrets(text: str) -> str:
+    """Mask credentials that may appear in error messages (e.g. httpx errors
+    quote the full request URL, which embeds tokens for several channels).
+    Applied to every error string before it reaches results and the log."""
+    for pattern, replacement in _SECRET_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def strip_for_tts(text: str) -> str:
+    """Strip markdown noise and URLs so the text reads naturally over TTS."""
+    out = text
+    out = _MD_PATTERNS[0].sub(" ", out)
+    out = _MD_PATTERNS[1].sub(r"\1", out)
+    out = _MD_PATTERNS[2].sub(" ", out)
+    out = _MD_PATTERNS[3].sub(r"\1", out)
+    out = _MD_PATTERNS[4].sub(" ", out)
+    out = _MD_PATTERNS[5].sub(" ", out)
+    return re.sub(r"\s+", " ", out).strip()

notify_hub/capabilities.py

@@ -0,0 +1,32 @@
+"""Channel capability flags and the attachment degrade policy."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+class Capability(enum.Flag):
+    TEXT = enum.auto()
+    MARKDOWN = enum.auto()
+    IMAGE = enum.auto()
+    FILE = enum.auto()
+    RICH_CARD = enum.auto()
+
+
+class DegradeMode(enum.Enum):
+    """What to do when a message part is unsupported by a channel.
+
+    DROP: silently drop the unsupported part (recorded in the result).
+    LINK: if the attachment source is a URL, append the URL to the text.
+    FAIL: mark that channel's send as failed (never raises into the host).
+    """
+
+    DROP = "drop"
+    LINK = "link"
+    FAIL = "fail"
+
+
+@dataclass(frozen=True, slots=True)
+class DegradePolicy:
+    on_unsupported_attachment: DegradeMode = DegradeMode.DROP

notify_hub/channels/__init__.py

@@ -0,0 +1,19 @@
+"""Built-in channel adapters.
+
+Importing this package registers all built-in channel types.
+Adapter modules are added incrementally; each must import cleanly with only
+the library's hard dependencies installed.
+"""
+
+from . import (  # noqa: F401  (self-register on import)
+    dingtalk,
+    discord,
+    lark,
+    phone,
+    slack,
+    telegram,
+    wecom,
+)
+from .base import Channel
+
+__all__ = ["Channel"]

notify_hub/channels/base.py

@@ -0,0 +1,93 @@
+"""Channel adapter base class.
+
+Adapters are async-only and written once; sync-host support lives entirely
+in the runtime layer. Adapters raise ``ChannelSendError`` on failure and the
+hub pipeline handles retry, isolation and logging.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+import httpx
+
+from ..capabilities import Capability, DegradeMode, DegradePolicy
+from ..exceptions import ChannelSendError
+from ..message import Attachment, AttachmentKind, Message
+
+
+def ensure_http_ok(resp: httpx.Response, context: str) -> None:
+    """Raise ChannelSendError for HTTP errors; 429/5xx are marked retryable."""
+    if resp.status_code == 429 or resp.status_code >= 500:
+        raise ChannelSendError(f"{context}: HTTP {resp.status_code}", retryable=True)
+    if resp.status_code >= 400:
+        raise ChannelSendError(f"{context}: HTTP {resp.status_code} {resp.text[:200]}")
+
+
+def render_text(message: Message, *, bold: str = "**") -> str:
+    """Default rendering: bolded title line followed by the body."""
+    if message.title:
+        return f"{bold}{message.title}{bold}\n{message.body}"
+    return message.body
+
+
+class Channel(ABC):
+    name: ClassVar[str]
+    # Class-level default; adapters whose support depends on instance config
+    # (e.g. Slack file upload requiring a bot token) override supports().
+    capabilities: Capability
+
+    def __init__(
+        self,
+        *,
+        channel_id: str,
+        client: httpx.AsyncClient,
+        degrade: DegradePolicy | None = None,
+        **config: Any,
+    ) -> None:
+        self.channel_id = channel_id
+        self.client = client
+        self.degrade_policy = degrade or DegradePolicy()
+        self.config = config
+
+    @abstractmethod
+    async def send(self, message: Message) -> None:
+        """Deliver the message. Raise ChannelSendError on failure."""
+
+    def supports(self, attachment: Attachment) -> bool:
+        needed = Capability.IMAGE if attachment.kind is AttachmentKind.IMAGE else Capability.FILE
+        return bool(self.capabilities & needed)
+
+    def degrade(self, message: Message) -> tuple[Message, list[str]]:
+        """Strip unsupported attachments per policy.
+
+        Returns the (possibly modified) message and human-readable
+        descriptions of the parts that were dropped or linked. With
+        ``DegradeMode.FAIL`` the caller is expected to fail the channel send
+        when descriptions are non-empty (see Hub pipeline).
+        """
+        if not message.attachments:
+            return message, []
+        keep: list[Attachment] = []
+        dropped: list[str] = []
+        extra_links: list[str] = []
+        mode = self.degrade_policy.on_unsupported_attachment
+        for att in message.attachments:
+            if self.supports(att):
+                keep.append(att)
+                continue
+            if mode is DegradeMode.LINK and att.is_url:
+                extra_links.append(str(att.source))
+                dropped.append(f"linked {att.describe()}")
+            else:
+                dropped.append(f"dropped {att.describe()}")
+        if not dropped:
+            return message, []
+        body = message.body
+        if extra_links:
+            body = body + "\n" + "\n".join(extra_links)
+        return message.replace_attachments(tuple(keep), body), dropped
+
+    async def aclose(self) -> None:  # noqa: B027 - optional hook, not abstract
+        """Release adapter-owned resources (the shared client is hub-owned)."""

notify_hub/channels/dingtalk.py

@@ -0,0 +1,82 @@
+"""DingTalk (钉钉) group robot adapter.
+
+Signing (when ``secret`` is configured): millisecond timestamp,
+``f"{ts}\\n{secret}"`` is the HMAC-SHA256 *message* with the secret as key;
+the base64 digest is percent-encoded and appended to the query string.
+Robots configured with keyword filtering instead can set
+``keyword_prefix``, which is prepended to every message.
+
+The robot webhook only supports text/markdown — attachments always
+degrade. Markdown messages require a ``title`` (shown in the notification
+banner); we use the message title or the level name.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+import urllib.parse
+from typing import Any
+
+from ..capabilities import Capability
+from ..exceptions import ChannelSendError, ConfigError
+from ..message import Message
+from ..registry import register_channel
+from .base import Channel, ensure_http_ok, render_text
+
+API_URL = "https://oapi.dingtalk.com/robot/send"
+
+
+@register_channel
+class DingTalkChannel(Channel):
+    name = "dingtalk"
+    capabilities = Capability.TEXT | Capability.MARKDOWN
+
+    def __init__(self, **kw: Any) -> None:
+        super().__init__(**kw)
+        access_token = self.config.get("access_token")
+        if not access_token:
+            raise ConfigError("dingtalk channel requires `access_token`")
+        self.access_token: str = access_token
+        self.secret: str | None = self.config.get("secret")
+        self.keyword_prefix: str = self.config.get("keyword_prefix", "")
+
+    def _signed_url(self, now_ms: int | None = None) -> str:
+        url = f"{API_URL}?access_token={self.access_token}"
+        if not self.secret:
+            return url
+        ts = str(now_ms if now_ms is not None else round(time.time() * 1000))
+        string_to_sign = f"{ts}\n{self.secret}"
+        digest = hmac.new(
+            self.secret.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256
+        ).digest()
+        sign = urllib.parse.quote_plus(base64.b64encode(digest))
+        return f"{url}&timestamp={ts}&sign={sign}"
+
+    async def send(self, message: Message) -> None:
+        text = render_text(message)
+        if self.keyword_prefix:
+            text = f"{self.keyword_prefix} {text}"
+        payload = {
+            "msgtype": "markdown",
+            "markdown": {
+                "title": message.title or message.level.name,
+                "text": text,
+            },
+        }
+        resp = await self.client.post(self._signed_url(), json=payload)
+        ensure_http_ok(resp, "dingtalk send")
+        try:
+            result = resp.json()
+        except json.JSONDecodeError:
+            raise ChannelSendError("dingtalk send: non-JSON response") from None
+        errcode = result.get("errcode")
+        if errcode != 0:
+            # 130101: send too fast (rate limited by DingTalk)
+            raise ChannelSendError(
+                f"dingtalk send: errcode={errcode} {result.get('errmsg', '')}",
+                retryable=errcode == 130101,
+            )

notify_hub/channels/discord.py

@@ -0,0 +1,51 @@
+"""Discord webhook adapter.
+
+Plain text goes as JSON ``{"content": ...}``; attachments use
+``multipart/form-data`` with a ``payload_json`` part plus ``files[N]`` parts
+(max 10 files, content limit 2000 chars). ``?wait=true`` makes the API
+return the created message so we get a real success signal.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .._util import truncate
+from ..capabilities import Capability
+from ..exceptions import ConfigError
+from ..message import Message
+from ..registry import register_channel
+from .base import Channel, ensure_http_ok, render_text
+
+CONTENT_LIMIT = 2000
+MAX_FILES = 10
+
+
+@register_channel
+class DiscordChannel(Channel):
+    name = "discord"
+    capabilities = Capability.TEXT | Capability.MARKDOWN | Capability.IMAGE | Capability.FILE
+
+    def __init__(self, **kw: Any) -> None:
+        super().__init__(**kw)
+        webhook_url = self.config.get("webhook_url")
+        if not webhook_url:
+            raise ConfigError("discord channel requires `webhook_url`")
+        separator = "&" if "?" in webhook_url else "?"
+        self.webhook_url = f"{webhook_url}{separator}wait=true"
+
+    async def send(self, message: Message) -> None:
+        content = truncate(render_text(message), CONTENT_LIMIT)
+        if not message.attachments:
+            resp = await self.client.post(self.webhook_url, json={"content": content})
+            ensure_http_ok(resp, "discord webhook")
+            return
+        files: dict[str, tuple[str | None, bytes | str, str]] = {
+            "payload_json": (None, json.dumps({"content": content}), "application/json"),
+        }
+        for i, att in enumerate(message.attachments[:MAX_FILES]):
+            data = await att.read_bytes(self.client)
+            files[f"files[{i}]"] = (att.resolved_filename(), data, att.resolved_mime_type())
+        resp = await self.client.post(self.webhook_url, files=files)
+        ensure_http_ok(resp, "discord webhook")

notify_hub/channels/lark.py

@@ -0,0 +1,166 @@
+"""Lark / Feishu (飞书) group bot webhook adapter.
+
+The webhook URL is given in full, so both ``open.feishu.cn`` and
+``open.larksuite.com`` domains just work.
+
+Signing differs from DingTalk: SECOND-precision timestamp,
+``f"{ts}\\n{secret}"`` is the HMAC-SHA256 *key* with an EMPTY message, and
+``sign``/``timestamp`` go in the JSON body, not the query string.
+
+Titled messages use ``msg_type: post`` (rich text); plain ones use
+``msg_type: text``. Success is ``{"code": 0}`` (newer) or
+``{"StatusCode": 0}`` (legacy); we accept either.
+
+Images: the webhook only accepts an ``image_key``, which can only be
+obtained through the authenticated upload API — so image support requires
+optional ``app_id``/``app_secret`` (a custom app). When configured, the
+adapter fetches a tenant_access_token (cached until near expiry), uploads
+each image to ``/open-apis/im/v1/images`` and sends an image message.
+Without app credentials, images degrade as before.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+from urllib.parse import urlsplit
+
+from ..capabilities import Capability
+from ..exceptions import ChannelSendError, ConfigError
+from ..message import Attachment, AttachmentKind, Message
+from ..registry import register_channel
+from .base import Channel, ensure_http_ok
+
+TOKEN_REFRESH_MARGIN = 300  # refresh the tenant token 5 min before expiry
+
+
+@register_channel
+class LarkChannel(Channel):
+    name = "lark"
+    capabilities = Capability.TEXT | Capability.MARKDOWN | Capability.RICH_CARD | Capability.IMAGE
+
+    def __init__(self, **kw: Any) -> None:
+        super().__init__(**kw)
+        webhook_url = self.config.get("webhook_url")
+        if not webhook_url:
+            raise ConfigError("lark channel requires `webhook_url`")
+        self.webhook_url: str = webhook_url
+        self.secret: str | None = self.config.get("secret")
+        self.lang: str = self.config.get("lang", "zh_cn")
+        self.app_id: str | None = self.config.get("app_id")
+        self.app_secret: str | None = self.config.get("app_secret")
+        if bool(self.app_id) != bool(self.app_secret):
+            raise ConfigError("lark `app_id` and `app_secret` must be set together")
+        # Reuse the webhook's domain (feishu.cn vs larksuite.com) for app APIs.
+        split = urlsplit(webhook_url)
+        self.api_base = f"{split.scheme}://{split.netloc}"
+        self._token: str | None = None
+        self._token_deadline = 0.0
+
+    def supports(self, attachment: Attachment) -> bool:
+        if attachment.kind is AttachmentKind.IMAGE:
+            return bool(self.app_id)  # image upload needs app credentials
+        return False  # files unsupported via group bot
+
+    # ------------------------------------------------------------------ #
+    # Webhook message
+    # ------------------------------------------------------------------ #
+
+    def _signature(self, ts: int) -> str:
+        assert self.secret is not None
+        key = f"{ts}\n{self.secret}".encode()
+        digest = hmac.new(key, b"", hashlib.sha256).digest()
+        return base64.b64encode(digest).decode("ascii")
+
+    def _signed(self, payload: dict[str, Any], now_s: int | None = None) -> dict[str, Any]:
+        if self.secret:
+            ts = now_s if now_s is not None else int(time.time())
+            payload["timestamp"] = str(ts)
+            payload["sign"] = self._signature(ts)
+        return payload
+
+    def _payload(self, message: Message, now_s: int | None = None) -> dict[str, Any]:
+        payload: dict[str, Any]
+        if message.title:
+            payload = {
+                "msg_type": "post",
+                "content": {
+                    "post": {
+                        self.lang: {
+                            "title": message.title,
+                            "content": [[{"tag": "text", "text": message.body}]],
+                        }
+                    }
+                },
+            }
+        else:
+            payload = {"msg_type": "text", "content": {"text": message.body}}
+        return self._signed(payload, now_s)
+
+    async def _post_webhook(self, payload: dict[str, Any], context: str) -> None:
+        resp = await self.client.post(self.webhook_url, json=payload)
+        ensure_http_ok(resp, context)
+        try:
+            result = resp.json()
+        except json.JSONDecodeError:
+            raise ChannelSendError(f"{context}: non-JSON response") from None
+        code = result.get("code", result.get("StatusCode"))
+        if code != 0:
+            raise ChannelSendError(
+                f"{context}: code={code} {result.get('msg', result.get('StatusMessage', ''))}"
+            )
+
+    # ------------------------------------------------------------------ #
+    # App API (tenant token + image upload), only with app credentials
+    # ------------------------------------------------------------------ #
+
+    async def _tenant_token(self) -> str:
+        if self._token is not None and time.monotonic() < self._token_deadline:
+            return self._token
+        resp = await self.client.post(
+            f"{self.api_base}/open-apis/auth/v3/tenant_access_token/internal",
+            json={"app_id": self.app_id, "app_secret": self.app_secret},
+        )
+        ensure_http_ok(resp, "lark tenant_access_token")
+        result = resp.json()
+        if result.get("code") != 0:
+            raise ChannelSendError(
+                f"lark tenant_access_token: code={result.get('code')} {result.get('msg', '')}"
+            )
+        token: str = result["tenant_access_token"]
+        expire = float(result.get("expire", 3600))
+        self._token = token
+        self._token_deadline = time.monotonic() + max(expire - TOKEN_REFRESH_MARGIN, 60)
+        return token
+
+    async def _upload_image(self, att: Attachment) -> str:
+        data = await att.read_bytes(self.client)
+        token = await self._tenant_token()
+        resp = await self.client.post(
+            f"{self.api_base}/open-apis/im/v1/images",
+            headers={"Authorization": f"Bearer {token}"},
+            data={"image_type": "message"},
+            files={"image": (att.resolved_filename(), data, att.resolved_mime_type())},
+        )
+        ensure_http_ok(resp, "lark image upload")
+        result = resp.json()
+        if result.get("code") != 0:
+            raise ChannelSendError(
+                f"lark image upload: code={result.get('code')} {result.get('msg', '')}"
+            )
+        key: str = result["data"]["image_key"]
+        return key
+
+    # ------------------------------------------------------------------ #
+
+    async def send(self, message: Message) -> None:
+        await self._post_webhook(self._payload(message), "lark send")
+        for att in message.attachments:
+            if att.kind is AttachmentKind.IMAGE:
+                image_key = await self._upload_image(att)
+                payload = self._signed({"msg_type": "image", "content": {"image_key": image_key}})
+                await self._post_webhook(payload, "lark image send")

notify_hub/channels/phone/__init__.py

@@ -0,0 +1,7 @@
+"""Phone voice-call channel package."""
+
+from . import twilio  # noqa: F401  (registers the provider)
+from .base import PROVIDERS, VoiceProvider, register_provider
+from .channel import PhoneChannel
+
+__all__ = ["PROVIDERS", "PhoneChannel", "VoiceProvider", "register_provider"]

notify_hub/channels/phone/base.py

@@ -0,0 +1,34 @@
+"""Voice call provider abstraction.
+
+``PhoneChannel`` dispatches to a ``VoiceProvider``; Twilio ships in v1 and
+new providers (e.g. Vonage) only need to subclass ``VoiceProvider`` and
+register themselves in ``PROVIDERS``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import httpx
+
+
+class VoiceProvider(ABC):
+    name: str
+
+    def __init__(self, client: httpx.AsyncClient) -> None:
+        self.client = client
+
+    @abstractmethod
+    async def call(self, to: str, text: str) -> None:
+        """Place a call to ``to`` reading ``text`` aloud.
+
+        Raise ChannelSendError on failure.
+        """
+
+
+PROVIDERS: dict[str, type[VoiceProvider]] = {}
+
+
+def register_provider(cls: type[VoiceProvider]) -> type[VoiceProvider]:
+    PROVIDERS[cls.name] = cls
+    return cls