goatnotify-core 0.1.0__py3-none-any.whl

goatnotify/core/__init__.py

@@ -0,0 +1,86 @@
+from goatnotify.core import events
+from goatnotify.core._json import JsonValue
+from goatnotify.core.channel import Channel
+from goatnotify.core.channels.database import (
+    DatabaseChannel,
+    DatabaseMessage,
+    NotificationStore,
+    StoredNotification,
+)
+from goatnotify.core.channels.email import EmailChannel
+from goatnotify.core.channels.webhook import WebhookChannel, WebhookMessage
+from goatnotify.core.errors import (
+    ConfigurationError,
+    DeliveryError,
+    DeliveryFailed,
+    InvalidMessageError,
+    NotificationError,
+    PermanentError,
+    RetryableError,
+    SkipDelivery,
+)
+from goatnotify.core.events import Event, Hook
+from goatnotify.core.http import HttpRequest, HttpResponse, HttpTransport, UrllibTransport
+from goatnotify.core.mail.mailable import Mailable
+from goatnotify.core.mail.mailer import Mailer
+from goatnotify.core.mail.message import Address, Attachment, EmailMessage
+from goatnotify.core.mail.mime import to_mime
+from goatnotify.core.mail.smtp import SmtpTransport
+from goatnotify.core.mail.transport import EmailTransport
+from goatnotify.core.notification import Message, Notifiable, Notification
+from goatnotify.core.notifier import Notifier
+from goatnotify.core.queue import AsyncioQueue, DrainableQueue, NotificationJob, Queue
+from goatnotify.core.results import DeliveryResult, DeliveryStatus, NotificationResult
+from goatnotify.core.retry import NO_RETRY, Backoff, ExponentialBackoff, RetryPolicy
+from goatnotify.core.templates import TemplateRenderer
+
+__all__ = [
+    "NO_RETRY",
+    "Address",
+    "AsyncioQueue",
+    "Attachment",
+    "Backoff",
+    "Channel",
+    "ConfigurationError",
+    "DatabaseChannel",
+    "DatabaseMessage",
+    "DeliveryError",
+    "DeliveryFailed",
+    "DeliveryResult",
+    "DeliveryStatus",
+    "DrainableQueue",
+    "EmailChannel",
+    "EmailMessage",
+    "EmailTransport",
+    "Event",
+    "ExponentialBackoff",
+    "Hook",
+    "HttpRequest",
+    "HttpResponse",
+    "HttpTransport",
+    "InvalidMessageError",
+    "JsonValue",
+    "Mailable",
+    "Mailer",
+    "Message",
+    "Notifiable",
+    "Notification",
+    "NotificationError",
+    "NotificationJob",
+    "NotificationResult",
+    "NotificationStore",
+    "Notifier",
+    "PermanentError",
+    "Queue",
+    "RetryPolicy",
+    "RetryableError",
+    "SkipDelivery",
+    "SmtpTransport",
+    "StoredNotification",
+    "TemplateRenderer",
+    "UrllibTransport",
+    "WebhookChannel",
+    "WebhookMessage",
+    "events",
+    "to_mime",
+]

goatnotify/core/_json.py

@@ -0,0 +1 @@
+type JsonValue = str | int | float | bool | list[JsonValue] | dict[str, JsonValue] | None

goatnotify/core/channel.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+from goatnotify.core.notification import Message, Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+
+class Channel[M: Message](ABC):
+    name: str
+    message_type: type[M]
+    retry: RetryPolicy | None = None
+
+    @abstractmethod
+    async def send(self, notifiable: Notifiable, message: M) -> str | None: ...

goatnotify/core/channels/database.py

@@ -0,0 +1,55 @@
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Protocol
+from uuid import UUID, uuid4
+
+from goatnotify.core._json import JsonValue
+from goatnotify.core.channel import Channel
+from goatnotify.core.notification import Message, Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+
+@dataclass(frozen=True, slots=True)
+class DatabaseMessage(Message):
+    kind: str
+    data: Mapping[str, JsonValue]
+
+
+@dataclass(frozen=True, slots=True)
+class StoredNotification:
+    id: UUID
+    kind: str
+    data: Mapping[str, JsonValue]
+    created_at: datetime
+
+
+class NotificationStore(Protocol):
+    async def store(self, notifiable: Notifiable, record: StoredNotification) -> None: ...
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class DatabaseChannel(Channel[DatabaseMessage]):
+    name = "database"
+    message_type = DatabaseMessage
+
+    def __init__(
+        self,
+        store: NotificationStore,
+        *,
+        retry: RetryPolicy | None = None,
+        clock: Callable[[], datetime] = utc_now,
+    ) -> None:
+        self._store = store
+        self._clock = clock
+        self.retry = retry
+
+    async def send(self, notifiable: Notifiable, message: DatabaseMessage) -> str | None:
+        record = StoredNotification(
+            id=uuid4(), kind=message.kind, data=message.data, created_at=self._clock()
+        )
+        await self._store.store(notifiable, record)
+        return str(record.id)

goatnotify/core/channels/email.py

@@ -0,0 +1,23 @@
+from goatnotify.core.channel import Channel
+from goatnotify.core.errors import SkipDelivery
+from goatnotify.core.mail.mailable import Mailable
+from goatnotify.core.mail.mailer import Mailer
+from goatnotify.core.notification import Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+
+class EmailChannel(Channel[Mailable]):
+    name = "email"
+    message_type = Mailable
+
+    def __init__(self, mailer: Mailer, *, retry: RetryPolicy | None = None) -> None:
+        self._mailer = mailer
+        self.retry = retry
+
+    async def send(self, notifiable: Notifiable, message: Mailable) -> str | None:
+        if message.to:
+            return await self._mailer.send(message)
+        route = notifiable.route_notification(self.name)
+        if route is None:
+            raise SkipDelivery(f"{type(notifiable).__qualname__} has no email route")
+        return await self._mailer.send(message, to=[route])

goatnotify/core/channels/webhook.py

@@ -0,0 +1,104 @@
+import hashlib
+import hmac
+import json
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Final, Literal
+from urllib.parse import urlsplit
+
+from goatnotify.core._json import JsonValue
+from goatnotify.core.channel import Channel
+from goatnotify.core.errors import DeliveryError, PermanentError, RetryableError, SkipDelivery
+from goatnotify.core.http import (
+    HttpRequest,
+    HttpResponse,
+    HttpTransport,
+    UrllibTransport,
+    require_http_url,
+)
+from goatnotify.core.notification import Message, Notifiable
+from goatnotify.core.retry import RetryPolicy
+
+SIGNATURE_HEADER: Final = "X-GoatNotify-Signature"
+TIMESTAMP_HEADER: Final = "X-GoatNotify-Timestamp"
+MAX_RETRY_AFTER: Final = 300.0
+RETRYABLE_STATUSES: Final = frozenset({408, 429})
+ERROR_BODY_LIMIT: Final = 200
+
+
+@dataclass(frozen=True, slots=True)
+class WebhookMessage(Message):
+    payload: JsonValue
+    url: str | None = None
+    headers: Mapping[str, str] = field(default_factory=dict[str, str])
+    method: Literal["POST", "PUT"] = "POST"
+
+
+class WebhookChannel(Channel[WebhookMessage]):
+    name = "webhook"
+    message_type = WebhookMessage
+
+    def __init__(
+        self,
+        transport: HttpTransport | None = None,
+        *,
+        secret: str | None = None,
+        timeout: float = 10.0,
+        retry: RetryPolicy | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        self._transport = transport or UrllibTransport()
+        self._secret = secret
+        self._timeout = timeout
+        self._clock = clock
+        self.retry = retry
+
+    async def send(self, notifiable: Notifiable, message: WebhookMessage) -> str | None:
+        url = message.url or notifiable.route_notification(self.name)
+        if url is None:
+            raise SkipDelivery(f"{type(notifiable).__qualname__} has no webhook route")
+        require_http_url(url)
+        body = json.dumps(message.payload, separators=(",", ":"), ensure_ascii=False).encode()
+        headers = {"Content-Type": "application/json", **message.headers, **self._sign(body)}
+        host = urlsplit(url).netloc
+        try:
+            response = await self._transport.send(
+                HttpRequest(message.method, url, headers, body, self._timeout)
+            )
+        except DeliveryError:
+            raise
+        # "from None": transport errors often quote the full URL, which may embed a token.
+        except OSError as error:
+            detail = f"Webhook request to {host} failed: {type(error).__name__}"
+            raise RetryableError(detail) from None
+        except Exception as error:
+            detail = f"Webhook request to {host} failed: {type(error).__name__}"
+            raise PermanentError(detail) from None
+        _raise_for_status(response, host)
+        return None
+
+    def _sign(self, body: bytes) -> dict[str, str]:
+        if self._secret is None:
+            return {}
+        timestamp = str(int(self._clock()))
+        digest = hmac.new(
+            self._secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256
+        ).hexdigest()
+        return {TIMESTAMP_HEADER: timestamp, SIGNATURE_HEADER: f"sha256={digest}"}
+
+
+def _raise_for_status(response: HttpResponse, host: str) -> None:
+    if 200 <= response.status < 300:
+        return
+    detail = f"Webhook {host} answered {response.status}: {response.body[:ERROR_BODY_LIMIT]!r}"
+    if response.status in RETRYABLE_STATUSES or response.status >= 500:
+        raise RetryableError(detail, retry_after=_retry_after(response))
+    raise PermanentError(detail)
+
+
+def _retry_after(response: HttpResponse) -> float | None:
+    value = (response.header("Retry-After") or "").strip()
+    if not (value.isascii() and value.isdecimal()):
+        return None
+    return min(float(value), MAX_RETRY_AFTER)

goatnotify/core/errors.py

@@ -0,0 +1,47 @@
+from typing import TYPE_CHECKING, Self
+
+if TYPE_CHECKING:
+    from goatnotify.core.results import NotificationResult
+
+
+class NotificationError(Exception):
+    pass
+
+
+class ConfigurationError(NotificationError):
+    pass
+
+
+class DeliveryError(NotificationError):
+    pass
+
+
+class RetryableError(DeliveryError):
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class PermanentError(DeliveryError):
+    pass
+
+
+class InvalidMessageError(PermanentError):
+    pass
+
+
+class SkipDelivery(DeliveryError):  # noqa: N818 (a control-flow signal, not an error)
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+class DeliveryFailed(ExceptionGroup[Exception]):
+    result: NotificationResult
+
+    @classmethod
+    def from_result(cls, result: NotificationResult) -> Self:
+        errors = [delivery.error for delivery in result.deliveries if delivery.error is not None]
+        group = cls(f"{len(errors)} of {len(result.deliveries)} deliveries failed", errors)
+        group.result = result
+        return group

goatnotify/core/events.py

@@ -0,0 +1,51 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, ClassVar, Literal
+from uuid import UUID
+
+from goatnotify.core.errors import RetryableError
+from goatnotify.core.notification import Message, Notifiable, Notification
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _DeliveryEvent:
+    notification_id: UUID
+    notification: Notification[Any]
+    notifiable: Notifiable
+    channel: str
+    message: Message
+    attempt: int
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Sending(_DeliveryEvent):
+    name: ClassVar[Literal["notification.sending"]] = "notification.sending"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Retrying(_DeliveryEvent):
+    name: ClassVar[Literal["notification.retrying"]] = "notification.retrying"
+    delay: float
+    error: RetryableError
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Sent(_DeliveryEvent):
+    name: ClassVar[Literal["notification.sent"]] = "notification.sent"
+    provider_id: str | None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Failed(_DeliveryEvent):
+    name: ClassVar[Literal["notification.failed"]] = "notification.failed"
+    error: Exception
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Skipped(_DeliveryEvent):
+    name: ClassVar[Literal["notification.skipped"]] = "notification.skipped"
+    reason: str
+
+
+type Event = Sending | Retrying | Sent | Failed | Skipped
+type Hook = Callable[[Event], Awaitable[None] | None]

goatnotify/core/http.py

@@ -0,0 +1,102 @@
+import asyncio
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from dataclasses import dataclass
+from email.message import Message
+from importlib.metadata import PackageNotFoundError, version
+from typing import IO, Protocol, override
+from urllib.parse import urlsplit
+
+from goatnotify.core.errors import InvalidMessageError
+
+
+def _distribution_version() -> str:
+    try:
+        return version("goatnotify-core")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+USER_AGENT = f"goatnotify/{_distribution_version()}"
+ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+def require_http_url(url: str) -> None:
+    parts = urlsplit(url)
+    if parts.scheme not in ALLOWED_SCHEMES or not parts.netloc:
+        raise InvalidMessageError("Only absolute http and https URLs are allowed")
+    if not url.isascii() or not url.isprintable() or " " in url:
+        raise InvalidMessageError("URLs must be percent-encoded ASCII without spaces")
+
+
+@dataclass(frozen=True, slots=True)
+class HttpRequest:
+    method: str
+    url: str
+    headers: Mapping[str, str]
+    body: bytes
+    timeout: float
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+    def header(self, name: str) -> str | None:
+        wanted = name.lower()
+        return next((v for k, v in self.headers.items() if k.lower() == wanted), None)
+
+
+class HttpTransport(Protocol):
+    async def send(self, request: HttpRequest) -> HttpResponse: ...
+
+
+def _with_user_agent(headers: Mapping[str, str]) -> dict[str, str]:
+    # urllib's default "Python-urllib" agent is rejected by some bot-protected endpoints.
+    if any(name.lower() == "user-agent" for name in headers):
+        return dict(headers)
+    return {**headers, "User-Agent": USER_AGENT}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # urllib would replay a POST as a bodiless GET and forward signature headers to any host.
+    @override
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: IO[bytes],
+        code: int,
+        msg: str,
+        headers: Message,
+        newurl: str,
+    ) -> None:
+        return None
+
+
+class UrllibTransport:
+    def __init__(self) -> None:
+        self._opener = urllib.request.build_opener(_NoRedirect)
+
+    async def send(self, request: HttpRequest) -> HttpResponse:
+        require_http_url(request.url)
+        return await asyncio.to_thread(self._send, request)
+
+    def _send(self, request: HttpRequest) -> HttpResponse:
+        prepared = urllib.request.Request(  # noqa: S310 (scheme checked by require_http_url)
+            request.url,
+            data=request.body,
+            headers=_with_user_agent(request.headers),
+            method=request.method,
+        )
+        try:
+            # Safe: send() has already restricted the URL to http and https.
+            with self._opener.open(prepared, timeout=request.timeout) as response:  # nosemgrep
+                return HttpResponse(
+                    response.status, dict(response.headers.items()), response.read()
+                )
+        except urllib.error.HTTPError as error:
+            with error:
+                return HttpResponse(error.code, dict(error.headers.items()), error.read())

goatnotify/core/mail/mailable.py

@@ -0,0 +1,36 @@
+from collections.abc import Mapping, Sequence
+from types import MappingProxyType
+
+from goatnotify.core.mail.message import AddressLike, Attachment
+from goatnotify.core.notification import Message
+
+_EMPTY: MappingProxyType[str, str] = MappingProxyType({})
+
+
+class Mailable(Message):
+    subject: str = ""
+    sender: AddressLike | None = None
+    to: Sequence[AddressLike] = ()
+    cc: Sequence[AddressLike] = ()
+    bcc: Sequence[AddressLike] = ()
+    reply_to: Sequence[AddressLike] = ()
+    headers: Mapping[str, str] = _EMPTY
+    metadata: Mapping[str, str] = _EMPTY
+
+    def attachments(self) -> Sequence[Attachment]:
+        return ()
+
+    def html(self) -> str | None:
+        return None
+
+    def text(self) -> str | None:
+        return None
+
+    def template(self) -> str | None:
+        return None
+
+    def text_template(self) -> str | None:
+        return None
+
+    def context(self) -> Mapping[str, object]:
+        return _EMPTY

goatnotify/core/mail/mailer.py

@@ -0,0 +1,60 @@
+from collections.abc import Iterable, Mapping, Sequence
+
+from goatnotify.core.errors import ConfigurationError, InvalidMessageError
+from goatnotify.core.mail.mailable import Mailable
+from goatnotify.core.mail.message import Address, AddressLike, EmailMessage
+from goatnotify.core.mail.transport import EmailTransport
+from goatnotify.core.templates import TemplateRenderer
+
+
+class Mailer:
+    def __init__(
+        self,
+        transport: EmailTransport,
+        *,
+        sender: AddressLike,
+        renderer: TemplateRenderer | None = None,
+    ) -> None:
+        self._transport = transport
+        self._sender = Address.parse(sender)
+        self._renderer = renderer
+
+    async def render(self, mailable: Mailable, *, to: Sequence[AddressLike] = ()) -> EmailMessage:
+        if not mailable.subject:
+            raise InvalidMessageError(f"{type(mailable).__qualname__} has no subject")
+        context = mailable.context()
+        html = mailable.html()
+        if html is None:
+            html = await self._render(mailable.template(), context)
+        text = mailable.text()
+        if text is None:
+            text = await self._render(mailable.text_template(), context)
+        return EmailMessage(
+            subject=mailable.subject,
+            sender=self._sender if mailable.sender is None else Address.parse(mailable.sender),
+            to=_addresses(to or mailable.to),
+            cc=_addresses(mailable.cc),
+            bcc=_addresses(mailable.bcc),
+            reply_to=_addresses(mailable.reply_to),
+            html=html,
+            text=text,
+            attachments=tuple(mailable.attachments()),
+            headers=dict(mailable.headers),
+            metadata=dict(mailable.metadata),
+        )
+
+    async def send(self, mailable: Mailable, *, to: Sequence[AddressLike] = ()) -> str | None:
+        return await self._transport.send(await self.render(mailable, to=to))
+
+    async def _render(self, template: str | None, context: Mapping[str, object]) -> str | None:
+        if template is None:
+            return None
+        if self._renderer is None:
+            raise ConfigurationError(
+                f"Template {template!r} needs a TemplateRenderer: pass renderer= to Mailer"
+            )
+        return await self._renderer.render(template, context)
+
+
+def _addresses(values: Iterable[AddressLike]) -> tuple[Address, ...]:
+    return tuple(Address.parse(value) for value in values)