swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/mail/transports/api/sendgrid.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import httpx
+
+from swiftpy.mail.exceptions import MailConfigurationError, MailValidationError
+from swiftpy.mail.message import MailMessage, parse_mail_address
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.transports.api.base import ApiMailTransport
+
+
+class SendGridTransport(ApiMailTransport):
+    """
+    Email delivery transport using SendGrid v3 Mail Send API (https://sendgrid.com).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        timeout: float = 30.0,
+        endpoint: str = "https://api.sendgrid.com/v3/mail/send",
+        client: httpx.AsyncClient | None = None,
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> None:
+        super().__init__(
+            timeout=timeout,
+            client=client,
+            default_from=default_from,
+            max_attachment_size_bytes=max_attachment_size_bytes,
+            max_message_size_bytes=max_message_size_bytes,
+        )
+        self.api_key = api_key
+        self.endpoint = endpoint
+
+    @classmethod
+    def from_config(
+        cls,
+        config: dict[str, Any],
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> SendGridTransport:
+        api_key = str(config.get("api_key", ""))
+        timeout = float(config.get("timeout", 30.0))
+        endpoint = str(config.get("endpoint", "https://api.sendgrid.com/v3/mail/send"))
+        return cls(
+            api_key=api_key,
+            timeout=timeout,
+            endpoint=endpoint,
+            default_from=default_from,
+            max_attachment_size_bytes=cls._resolve_size_limit(
+                max_attachment_size_bytes, config, "max_attachment_size_bytes"
+            ),
+            max_message_size_bytes=cls._resolve_size_limit(
+                max_message_size_bytes, config, "max_message_size_bytes"
+            ),
+        )
+
+    def _parse_recipient(self, formatted: str) -> dict[str, str]:
+        name, addr = parse_mail_address(formatted, field_name="recipient")
+        rec = {"email": addr}
+        if name:
+            rec["name"] = name
+        return rec
+
+    async def send(self, message: MailMessage) -> MailSendResult:
+        if not self.api_key:
+            raise MailConfigurationError("SendGrid API key is not configured")
+
+        if not message.to and not message.cc and not message.bcc:
+            raise MailValidationError(
+                "Email message must specify at least one recipient"
+            )
+
+        from_addr, from_name = self._resolve_from(
+            message.from_address, message.from_name
+        )
+        parsed_from_name, clean_from_addr = parse_mail_address(
+            from_addr, field_name="from"
+        )
+        from_payload: dict[str, str] = {"email": clean_from_addr}
+        resolved_from_name = (
+            from_name.strip()
+            if from_name is not None and from_name.strip()
+            else parsed_from_name
+        )
+        if resolved_from_name:
+            from_payload["name"] = resolved_from_name
+
+        personalization: dict[str, Any] = {
+            "to": [self._parse_recipient(r) for r in message.to]
+        }
+        if message.cc:
+            personalization["cc"] = [self._parse_recipient(r) for r in message.cc]
+        if message.bcc:
+            personalization["bcc"] = [self._parse_recipient(r) for r in message.bcc]
+
+        content_list: list[dict[str, str]] = []
+        if message.text_body:
+            content_list.append({"type": "text/plain", "value": message.text_body})
+        if message.html_body:
+            content_list.append({"type": "text/html", "value": message.html_body})
+        if not content_list:
+            content_list.append({"type": "text/plain", "value": ""})
+
+        payload: dict[str, Any] = {
+            "personalizations": [personalization],
+            "from": from_payload,
+            "subject": message.subject,
+            "content": content_list,
+        }
+
+        if message.reply_to:
+            payload["reply_to"] = self._parse_recipient(message.reply_to)
+
+        if message.headers:
+            payload["headers"] = {str(k): str(v) for k, v in message.headers.items()}
+        if message.tags:
+            payload["categories"] = [str(tag) for tag in message.tags]
+        if message.metadata:
+            payload["custom_args"] = {
+                str(k): str(v) for k, v in message.metadata.items()
+            }
+
+        loaded_attachments = await self._read_attachments_with_limits(message)
+        if loaded_attachments:
+            att_payload: list[dict[str, str]] = []
+            for att, data in loaded_attachments:
+                encoded = base64.b64encode(data).decode("ascii")
+                item = {
+                    "content": encoded,
+                    "filename": att.filename,
+                    "type": att.content_type,
+                    "disposition": att.disposition,
+                }
+                if att.cid:
+                    item["content_id"] = att.cid
+                att_payload.append(item)
+            payload["attachments"] = att_payload
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "SwiftPY-Mail/1.0",
+        }
+
+        client = await self._get_client()
+
+        try:
+            response = await client.post(self.endpoint, json=payload, headers=headers)
+            response.raise_for_status()
+            msg_id = response.headers.get("X-Message-Id") or response.headers.get(
+                "x-message-id"
+            )
+            return MailSendResult(
+                success=True,
+                message_id=msg_id,
+                provider="sendgrid",
+                accepted=message.all_recipient_addresses(),
+                rejected=[],
+                raw_response={"status_code": response.status_code},
+            )
+        except Exception as exc:
+            self._handle_http_error(exc, "SendGrid")
+            raise  # pragma: no cover
+
+
+__all__ = ["SendGridTransport"]

swiftpy/mail/transports/base.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from swiftpy.mail.message import MailMessage
+from swiftpy.mail.models import MailSendResult
+
+
+class MailTransport(ABC):
+    """Abstract contract for SwiftPY email delivery backends."""
+
+    @abstractmethod
+    async def send(self, message: MailMessage) -> MailSendResult:
+        """
+        Deliver the given MailMessage.
+
+        Raises MailTransportError or specialized subclasses on network/auth failure.
+        """
+
+    async def close(self) -> None:
+        """Release underlying connections, pools, or open handles."""
+
+
+__all__ = ["MailTransport"]

swiftpy/mail/transports/console.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+from swiftpy.mail.exceptions import AttachmentTooLargeError
+from swiftpy.mail.message import MailMessage
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.transports.base import MailTransport
+
+
+class ConsoleTransport(MailTransport):
+    """
+    Development and logging transport.
+    Outputs email metadata to the logger and retains sent messages in memory for inspection.
+    """
+
+    def __init__(
+        self,
+        channel: str = "mail",
+        *,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> None:
+        self.channel = channel
+        self.logger = logging.getLogger(f"swiftpy.mail.{channel}")
+        self.sent_messages: list[MailMessage] = []
+        self.max_attachment_size_bytes = max_attachment_size_bytes
+        self.max_message_size_bytes = max_message_size_bytes
+
+    @classmethod
+    def from_config(
+        cls,
+        config: dict[str, Any],
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> ConsoleTransport:
+        channel = str(config.get("channel", "mail"))
+        raw_att = config.get("max_attachment_size_bytes", max_attachment_size_bytes)
+        raw_msg = config.get("max_message_size_bytes", max_message_size_bytes)
+        return cls(
+            channel=channel,
+            max_attachment_size_bytes=int(raw_att) if raw_att is not None else None,
+            max_message_size_bytes=int(raw_msg) if raw_msg is not None else None,
+        )
+
+    async def send(self, message: MailMessage) -> MailSendResult:
+        if (
+            self.max_attachment_size_bytes is not None
+            or self.max_message_size_bytes is not None
+        ):
+            total_bytes = len((message.text_body or "").encode("utf-8")) + len(
+                (message.html_body or "").encode("utf-8")
+            )
+            for att in message.attachments:
+                att_data = await att.read_bytes(
+                    max_size=self.max_attachment_size_bytes
+                )
+                total_bytes += len(att_data)
+            if (
+                self.max_message_size_bytes is not None
+                and total_bytes > self.max_message_size_bytes
+            ):
+                raise AttachmentTooLargeError(
+                    f"Total email size ({total_bytes} bytes) exceeds configured limit ({self.max_message_size_bytes} bytes)"
+                )
+
+        self.sent_messages.append(message)
+        msg_id = f"console-{uuid.uuid4().hex[:16]}"
+
+        self.logger.info(
+            "Email dispatched via ConsoleTransport: To=%s Subject='%s' Message-ID=%s",
+            message.to,
+            message.subject,
+            msg_id,
+        )
+
+        return MailSendResult(
+            success=True,
+            message_id=msg_id,
+            provider="console",
+            accepted=message.all_recipient_addresses(),
+            rejected=[],
+        )
+
+    async def close(self) -> None:
+        self.sent_messages.clear()
+
+
+__all__ = ["ConsoleTransport"]

swiftpy/mail/transports/sendmail.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+from swiftpy.mail.envelope import Envelope
+from swiftpy.mail.exceptions import (
+    MailConfigurationError,
+    MailTimeoutError,
+    MailTransportError,
+)
+from swiftpy.mail.message import MailMessage, parse_mail_address
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.transports.base import MailTransport
+
+logger = logging.getLogger("swiftpy.mail.sendmail")
+
+
+class SendmailTransport(MailTransport):
+    """
+    Local sendmail binary transport.
+    Invokes sendmail non-blockingly via asyncio.create_subprocess_exec.
+    Enforces process timeouts and cancellation cleanup.
+    """
+
+    def __init__(
+        self,
+        path: str = "/usr/sbin/sendmail",
+        timeout: float = 30.0,
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> None:
+        self.path = path
+        self.timeout = timeout
+        self.default_from = default_from
+        self.max_attachment_size_bytes = max_attachment_size_bytes
+        self.max_message_size_bytes = max_message_size_bytes
+
+    @classmethod
+    def from_config(
+        cls,
+        config: dict[str, Any],
+        default_from: tuple[str, str | None] | None = None,
+        max_attachment_size_bytes: int | None = None,
+        max_message_size_bytes: int | None = None,
+    ) -> SendmailTransport:
+        path = str(config.get("path", "/usr/sbin/sendmail"))
+        timeout = float(config.get("timeout", 30.0))
+        raw_att = config.get("max_attachment_size_bytes", max_attachment_size_bytes)
+        raw_msg = config.get("max_message_size_bytes", max_message_size_bytes)
+        return cls(
+            path=path,
+            timeout=timeout,
+            default_from=default_from,
+            max_attachment_size_bytes=int(raw_att) if raw_att is not None else None,
+            max_message_size_bytes=int(raw_msg) if raw_msg is not None else None,
+        )
+
+    async def send(self, message: MailMessage) -> MailSendResult:
+        if not Path(self.path).exists():
+            raise MailConfigurationError(f"Sendmail binary not found at '{self.path}'")
+
+        email_msg = await Envelope.build(
+            message,
+            default_from=self.default_from,
+            max_message_size_bytes=self.max_message_size_bytes,
+            max_attachment_size_bytes=self.max_attachment_size_bytes,
+        )
+        raw_bytes = email_msg.as_bytes()
+
+        _, sender_addr = parse_mail_address(
+            str(email_msg["From"]), field_name="from_address"
+        )
+        all_recipients = [
+            parse_mail_address(r, field_name="recipient")[1]
+            for r in message.to + message.cc + message.bcc
+        ]
+        cmd = [self.path, "-i", "-f", sender_addr, "--", *all_recipients]
+
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(input=raw_bytes),
+                timeout=self.timeout,
+            )
+        except TimeoutError as exc:
+            try:
+                proc.kill()
+                await proc.wait()
+            except Exception:
+                logger.debug("Failed to kill timed-out sendmail process", exc_info=True)
+            raise MailTimeoutError(
+                f"Sendmail process timed out after {self.timeout}s"
+            ) from exc
+        except asyncio.CancelledError:
+            try:
+                proc.kill()
+                await proc.wait()
+            except Exception:
+                logger.debug("Failed to kill cancelled sendmail process", exc_info=True)
+            raise
+
+        if proc.returncode != 0:
+            err_text = stderr.decode("utf-8", errors="replace").strip()
+            raise MailTransportError(
+                f"Sendmail process exited with code {proc.returncode}: {err_text}"
+            )
+
+        return MailSendResult(
+            success=True,
+            message_id=str(email_msg.get("Message-ID", "")),
+            provider="sendmail",
+            accepted=all_recipients,
+            rejected=[],
+            raw_response=stdout.decode("utf-8", errors="replace"),
+        )
+
+
+__all__ = ["SendmailTransport"]