swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/mail/message.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+import email.utils
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Self
+
+from swiftpy.mail.attachments import Attachment
+from swiftpy.mail.exceptions import (
+    HeaderInjectionError,
+    InvalidAddressError,
+    MailValidationError,
+)
+
+_CRLF_PATTERN = re.compile(r"[\r\n\0]")
+_BASIC_EMAIL_REGEX = re.compile(
+    r"^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$"
+)
+
+
+def _validate_no_crlf(value: str, field_name: str) -> None:
+    if _CRLF_PATTERN.search(value):
+        raise HeaderInjectionError(
+            f"Detected CRLF or null byte injection in {field_name}: {value!r}"
+        )
+
+
+def parse_mail_address(
+    raw_address: str, field_name: str = "recipient"
+) -> tuple[str, str]:
+    """Parse and validate an email address or 'Display Name <addr>' into (name, email)."""
+    _validate_no_crlf(raw_address, field_name)
+    cleaned = raw_address.strip()
+    if not cleaned:
+        raise InvalidAddressError(f"{field_name} address cannot be empty")
+
+    name, addr = email.utils.parseaddr(cleaned)
+    if not addr and cleaned.endswith(">") and "<" in cleaned:
+        prefix, _, candidate = cleaned[:-1].rpartition("<")
+        candidate_stripped = candidate.strip()
+        if (
+            candidate_stripped
+            and "<" not in candidate_stripped
+            and ">" not in candidate_stripped
+            and "," not in candidate_stripped
+        ):
+            addr = candidate_stripped
+            name = prefix.strip().strip('"')
+
+    target = addr if addr else cleaned
+    if not _BASIC_EMAIL_REGEX.match(target):
+        raise InvalidAddressError(f"Invalid email address '{cleaned}' in {field_name}")
+    return name.strip(), target
+
+
+def format_mail_address(
+    raw_or_address: str,
+    name: str | None = None,
+    *,
+    field_name: str = "recipient",
+) -> str:
+    """Validate and RFC-format an address, quoting display names containing commas."""
+    parsed_name, addr = parse_mail_address(raw_or_address, field_name=field_name)
+    display_name = name.strip() if name is not None and name.strip() else parsed_name
+    if display_name:
+        _validate_no_crlf(display_name, f"{field_name}_name")
+        return email.utils.formataddr((display_name, addr))
+    return addr
+
+
+def _validate_address(raw_address: str, field_name: str = "recipient") -> str:
+    """Validate and normalize an email address or formatted name <addr> string."""
+    parse_mail_address(raw_address, field_name=field_name)
+    return raw_address.strip()
+
+
+def _normalize_recipients(
+    recipients: list[str] | tuple[str, ...] | str | None,
+    field_name: str,
+) -> list[str]:
+    if recipients is None:
+        return []
+    if isinstance(recipients, str):
+        recipients = [recipients]
+    normalized: list[str] = []
+    for r in recipients:
+        validated = _validate_address(str(r), field_name)
+        normalized.append(validated)
+    return normalized
+
+
+@dataclass(slots=True)
+class MailMessage:
+    """Represents a validated, delivery-ready email message."""
+
+    subject: str
+    to: list[str] = field(default_factory=list)
+    cc: list[str] = field(default_factory=list)
+    bcc: list[str] = field(default_factory=list)
+    from_address: str | None = None
+    from_name: str | None = None
+    reply_to: str | None = None
+    text_body: str | None = None
+    html_body: str | None = None
+    template: str | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+    attachments: list[Attachment] = field(default_factory=list)
+    headers: dict[str, str] = field(default_factory=dict)
+    tags: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._validate()
+
+    def _validate(self) -> None:
+        # Validate subject
+        if self.subject is None:
+            raise MailValidationError("Email subject cannot be None")
+        _validate_no_crlf(self.subject, "subject")
+
+        # Normalize & validate recipient lists
+        self.to = _normalize_recipients(self.to, "to")
+        self.cc = _normalize_recipients(self.cc, "cc")
+        self.bcc = _normalize_recipients(self.bcc, "bcc")
+
+        # Validate from_address and from_name
+        if self.from_address:
+            self.from_address = _validate_address(self.from_address, "from_address")
+        if self.from_name:
+            _validate_no_crlf(self.from_name, "from_name")
+
+        # Validate reply_to
+        if self.reply_to:
+            self.reply_to = _validate_address(self.reply_to, "reply_to")
+
+        # Validate headers
+        normalized_headers: dict[str, str] = {}
+        for k, v in self.headers.items():
+            _validate_no_crlf(k, f"header key '{k}'")
+            _validate_no_crlf(v, f"header value for '{k}'")
+            normalized_headers[k.strip()] = v.strip()
+        self.headers = normalized_headers
+
+    def attach(self, attachment: Attachment) -> Self:
+        """Add an attachment to the message."""
+        self.attachments.append(attachment)
+        return self
+
+    def attach_from_path(
+        self,
+        path: str | Path,
+        filename: str | None = None,
+        content_type: str | None = None,
+    ) -> Self:
+        """Add a file attachment from a disk path."""
+        self.attachments.append(
+            Attachment.from_path(path, filename=filename, content_type=content_type)
+        )
+        return self
+
+    def attach_from_bytes(
+        self,
+        content: bytes,
+        filename: str,
+        content_type: str | None = None,
+    ) -> Self:
+        """Add an in-memory byte attachment."""
+        self.attachments.append(
+            Attachment.from_bytes(content, filename=filename, content_type=content_type)
+        )
+        return self
+
+    def add_header(self, key: str, value: str) -> Self:
+        """Add a custom email header with CRLF injection validation."""
+        _validate_no_crlf(key, f"header key '{key}'")
+        _validate_no_crlf(value, f"header value for '{key}'")
+        self.headers[key.strip()] = value.strip()
+        return self
+
+    def all_recipient_addresses(self) -> list[str]:
+        """Extract just the pure email addresses from to, cc, and bcc."""
+        return [parse_mail_address(r, field_name="recipient")[1] for r in self.to + self.cc + self.bcc]
+
+
+__all__ = ["MailMessage", "format_mail_address", "parse_mail_address"]

swiftpy/mail/models.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class MailSendResult:
+    """Normalized delivery outcome returned by all mail transports."""
+
+    success: bool
+    message_id: str | None = None
+    provider: str | None = None
+    accepted: list[str] = field(default_factory=list)
+    rejected: list[str] = field(default_factory=list)
+    raw_response: Any = None
+
+
+__all__ = ["MailSendResult"]

swiftpy/mail/queue/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from swiftpy.mail.queue.job import SendQueuedMailableJob
+
+__all__ = ["SendQueuedMailableJob"]

swiftpy/mail/queue/job.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import ast
+import importlib
+import inspect
+import logging
+import textwrap
+import types
+from collections.abc import Sequence
+from typing import Any, ClassVar
+
+from swiftpy.mail.exceptions import (
+    MailAuthenticationError,
+    MailConfigurationError,
+    MailConnectionError,
+    MailRateLimitError,
+    MailTimeoutError,
+    MailTransportError,
+    MailValidationError,
+)
+from swiftpy.mail.mailable import Mailable
+from swiftpy.mail.manager import MailManager
+from swiftpy.queue.job import Job, is_trusted_class_path, parse_class_path
+
+logger = logging.getLogger("swiftpy.mail.queue")
+
+_MISSING = object()
+
+
+def _collect_self_attr_targets(node: ast.AST, targets: set[str]) -> None:
+    """Recursively collect ``self.<attr>`` names from AST assignment targets."""
+    if isinstance(node, ast.Attribute):
+        if (
+            isinstance(node.value, ast.Name)
+            and node.value.id == "self"
+            and not node.attr.startswith("_")
+        ):
+            targets.add(node.attr)
+    elif isinstance(node, (ast.Tuple, ast.List)):
+        for elt in node.elts:
+            _collect_self_attr_targets(elt, targets)
+
+
+def _allowed_state_fields(target_cls: type[Mailable]) -> set[str]:
+    """Return declared public instance/class attributes permitted in ``mailable_state``."""
+    allowed: set[str] = set()
+    for cls_in_mro in target_cls.__mro__:
+        if cls_in_mro is object:
+            continue
+
+        for name in inspect.get_annotations(cls_in_mro):
+            if isinstance(name, str) and not name.startswith("_"):
+                allowed.add(name)
+
+        for attr_name, attr_val in cls_in_mro.__dict__.items():
+            if attr_name.startswith("_"):
+                continue
+            if not callable(attr_val) and (
+                isinstance(attr_val, types.MemberDescriptorType)
+                or (
+                    not hasattr(attr_val, "__get__")
+                    and not hasattr(attr_val, "__set__")
+                )
+            ):
+                allowed.add(attr_name)
+
+        init_fn = cls_in_mro.__dict__.get("__init__")
+        if callable(init_fn):
+            try:
+                sig = inspect.signature(init_fn)
+            except (ValueError, TypeError):
+                sig = None
+            if sig is not None:
+                for param_name, param in sig.parameters.items():
+                    if (
+                        param_name != "self"
+                        and not param_name.startswith("_")
+                        and param.kind
+                        not in (
+                            inspect.Parameter.VAR_POSITIONAL,
+                            inspect.Parameter.VAR_KEYWORD,
+                        )
+                    ):
+                        allowed.add(param_name)
+
+        for member in cls_in_mro.__dict__.values():
+            if not inspect.isfunction(member):
+                continue
+            try:
+                source = textwrap.dedent(inspect.getsource(member))
+                tree = ast.parse(source)
+            except (OSError, TypeError, SyntaxError):
+                continue
+            for ast_node in ast.walk(tree):
+                if isinstance(ast_node, ast.Assign):
+                    for target in ast_node.targets:
+                        _collect_self_attr_targets(target, allowed)
+                elif isinstance(ast_node, (ast.AnnAssign, ast.AugAssign)):
+                    _collect_self_attr_targets(ast_node.target, allowed)
+
+    return allowed
+
+
+class SendQueuedMailableJob(Job):
+    """
+    Asynchronous background job for delivering a Mailable.
+    Handles serialization, execution, and retry semantics.
+    """
+
+    queue = "emails"
+    tries = 3
+    backoff: int | float | Sequence[int | float] = (5, 15, 60)
+    _trusted_mailable_classes: ClassVar[set[str]] = set()
+
+    @classmethod
+    def allow_mailable_class(cls, mailable_cls_or_path: type[Mailable] | str) -> str:
+        """Explicitly allow deserialization of a Mailable class or module path."""
+        if isinstance(mailable_cls_or_path, str):
+            mod_name, cls_name = parse_class_path(
+                mailable_cls_or_path, exc_cls=MailValidationError
+            )
+            class_path = f"{mod_name}:{cls_name}"
+        elif isinstance(mailable_cls_or_path, type) and issubclass(
+            mailable_cls_or_path, Mailable
+        ):
+            class_path = (
+                f"{mailable_cls_or_path.__module__}:{mailable_cls_or_path.__qualname__}"
+            )
+        else:
+            raise MailValidationError(
+                "allow_mailable_class requires a Mailable subclass or valid class path"
+            )
+        cls._trusted_mailable_classes.add(class_path)
+        return class_path
+
+    def __init__(self, mailable: Mailable | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.mailable = mailable
+
+        if mailable is not None:
+            self.queue = getattr(mailable, "queue", self.queue)
+            self.tries = getattr(mailable, "tries", self.tries)
+            self.backoff = getattr(mailable, "backoff", self.backoff)
+            self.timeout = getattr(mailable, "timeout", self.timeout)
+
+            # Store mailable class and state in data
+            self.data["mailable_class"] = (
+                f"{mailable.__class__.__module__}:{mailable.__class__.__qualname__}"
+            )
+            state: dict[str, Any] = {}
+            if hasattr(mailable, "__dict__"):
+                for k, v in vars(mailable).items():
+                    if not k.startswith("_"):
+                        state[k] = v
+            self.data["mailable_state"] = state
+            self.data["mailer_name"] = mailable.mailer_name
+
+    def _resolve_mailable(self) -> Mailable:
+        if self.mailable is not None:
+            return self.mailable
+
+        mailable_class_str = self.data.get("mailable_class")
+        if not mailable_class_str or not isinstance(mailable_class_str, str):
+            raise MailValidationError(
+                "SendQueuedMailableJob missing 'mailable_class' in payload"
+            )
+
+        mod_name, cls_name = parse_class_path(
+            mailable_class_str, exc_cls=MailValidationError
+        )
+        if not is_trusted_class_path(
+            mailable_class_str,
+            mod_name,
+            trusted_namespaces=Job.get_trusted_namespaces(),
+            trusted_classes=self._trusted_mailable_classes,
+            class_name=cls_name,
+        ):
+            raise MailValidationError(
+                f"Mailable class '{mailable_class_str}' from module '{mod_name}' is not in trusted namespaces"
+            )
+
+        module = importlib.import_module(mod_name)
+        target_cls = getattr(module, cls_name, None)
+
+        if (
+            target_cls is None
+            or not isinstance(target_cls, type)
+            or not issubclass(target_cls, Mailable)
+        ):
+            raise MailValidationError(
+                f"Class '{mailable_class_str}' is not a valid subclass of Mailable"
+            )
+
+        instance = target_cls.__new__(target_cls)
+        state = self.data.get("mailable_state", {})
+        if state is not None:
+            if not isinstance(state, dict):
+                raise MailValidationError(
+                    "SendQueuedMailableJob 'mailable_state' must be a dictionary"
+                )
+            allowed_fields = _allowed_state_fields(target_cls)
+            for key, value in state.items():
+                if not isinstance(key, str) or key.startswith("_"):
+                    raise MailValidationError(
+                        f"Disallowed attribute '{key}' in mailable_state"
+                    )
+                existing = inspect.getattr_static(target_cls, key, _MISSING)
+                if existing is not _MISSING and (
+                    callable(existing)
+                    or (
+                        (hasattr(existing, "__get__") or hasattr(existing, "__set__"))
+                        and not isinstance(existing, types.MemberDescriptorType)
+                    )
+                ):
+                    raise MailValidationError(
+                        f"Disallowed descriptor or callable attribute '{key}' in mailable_state"
+                    )
+                if key not in allowed_fields:
+                    raise MailValidationError(
+                        f"Undeclared attribute '{key}' in mailable_state for {target_cls.__name__}"
+                    )
+                setattr(instance, key, value)
+
+        mailer_name = self.data.get("mailer_name")
+        if mailer_name is not None:
+            instance.mailer_name = str(mailer_name)
+
+        self.mailable = instance
+        return instance
+
+    async def handle(self) -> None:
+        mailable_label = (
+            self.mailable.__class__.__name__
+            if self.mailable is not None
+            else str(self.data.get("mailable_class", "unknown"))
+        )
+
+        try:
+            mailable = self._resolve_mailable()
+            mailable_label = mailable.__class__.__name__
+            message = await mailable.build_message()
+            manager = MailManager.get_instance()
+            result = await manager.send(message, mailer=mailable.mailer_name)
+            if not result.success:
+                raise MailTransportError(
+                    f"Email delivery via {result.provider} was not successful: rejected={result.rejected}"
+                )
+        except (MailConnectionError, MailRateLimitError, MailTimeoutError) as exc:
+            # Transient error: re-raise to trigger queue retry
+            logger.warning(
+                "Transient delivery failure for mailable %s: %s (attempt %d/%d)",
+                mailable_label,
+                exc,
+                self.attempts,
+                self.tries,
+            )
+            raise
+        except (
+            MailValidationError,
+            MailAuthenticationError,
+            MailConfigurationError,
+        ):
+            # Permanent error: exhaust retries so QueueWorker sends the job to DLQ instead of looping
+            logger.exception(
+                "Permanent delivery failure for mailable %s",
+                mailable_label,
+            )
+            self.attempts = max(self.attempts, self.tries)
+            raise
+
+    async def failed(self, exception: BaseException) -> None:
+        logger.error(
+            "Permanent failure delivering mailable %s: %s",
+            self.mailable.__class__.__name__ if self.mailable else "unknown",
+            exception,
+        )
+
+
+__all__ = ["SendQueuedMailableJob"]

swiftpy/mail/service_provider.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from swiftpy.core.providers.base import ServiceProvider
+from swiftpy.mail.manager import MailManager
+
+
+class MailServiceProvider(ServiceProvider):
+    """
+    Registers the MailManager singleton into the application DI container.
+    """
+
+    def register(self) -> None:
+        self.container.singleton(MailManager)
+
+    def boot(self) -> None:
+        pass
+
+
+__all__ = ["MailServiceProvider"]

swiftpy/mail/templates/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from swiftpy.mail.templates.renderer import MailTemplateRenderer, RenderedEmail
+
+__all__ = ["MailTemplateRenderer", "RenderedEmail"]

swiftpy/mail/templates/renderer.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import asyncio
+import html
+import logging
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from swiftpy.mail.exceptions import MailValidationError
+
+
+class _Jinja2Module(Protocol):
+    FileSystemLoader: Any
+    select_autoescape: Any
+
+
+_jinja_sandbox_env_cls: Callable[..., Any] | None
+jinja2: _Jinja2Module | None
+try:
+    import jinja2 as _jinja2
+    from jinja2.sandbox import SandboxedEnvironment as _SandboxedEnvironment
+
+    jinja2 = _jinja2
+    _jinja_sandbox_env_cls = _SandboxedEnvironment
+except ImportError:
+    jinja2 = None
+    _jinja_sandbox_env_cls = None
+
+logger = logging.getLogger("swiftpy.mail.templates")
+
+
+@dataclass(frozen=True, slots=True)
+class RenderedEmail:
+    """Represents the rendered output of an email template."""
+
+    html: str | None = None
+    text: str | None = None
+
+
+_VAR_PATTERN = re.compile(r"\{\{\s*([a-zA-Z0-9_\.]+)\s*\}\}")
+
+
+class MailTemplateRenderer:
+    """
+    Renders dual HTML and plain-text email templates with automatic escaping.
+    Uses Jinja2 if available; otherwise falls back to a safe built-in formatter.
+    Protects against path traversal, handles nested variables, and escapes quotes.
+    """
+
+    _instance: MailTemplateRenderer | None = None
+
+    def __init__(self, template_dir: str | Path = "views") -> None:
+        self.template_dir = Path(template_dir)
+        self._jinja_env: Any = None
+        if jinja2 is not None and _jinja_sandbox_env_cls is not None:
+            self._jinja_env = _jinja_sandbox_env_cls(
+                loader=jinja2.FileSystemLoader(str(self.template_dir)),
+                autoescape=jinja2.select_autoescape(["html", "xml"]),
+                enable_async=True,
+            )
+
+    @classmethod
+    def get_instance(cls) -> MailTemplateRenderer:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def _resolve_template_path(self, base_name: str, ext: str) -> Path:
+        """Resolve template file path and prevent directory traversal attacks."""
+        candidate = self.template_dir / f"{base_name}.{ext}"
+        try:
+            resolved_candidate = candidate.resolve()
+            resolved_dir = self.template_dir.resolve()
+            if not resolved_candidate.is_relative_to(resolved_dir):
+                raise MailValidationError(
+                    f"Template path '{base_name}' traverses outside template directory"
+                )
+            return resolved_candidate
+        except (ValueError, RuntimeError) as exc:
+            raise MailValidationError(
+                f"Invalid template path '{base_name}': {exc}"
+            ) from exc
+
+    async def render(
+        self,
+        template_name: str,
+        context: dict[str, Any],
+    ) -> RenderedEmail:
+        """Render both HTML and plain-text templates if present."""
+        base_name = template_name
+        if base_name.endswith((".html", ".txt")):
+            base_name = base_name.rsplit(".", 1)[0]
+
+        # Verify traversal safety
+        html_path = self._resolve_template_path(base_name, "html")
+        text_path = self._resolve_template_path(base_name, "txt")
+
+        html_content: str | None = None
+        text_content: str | None = None
+
+        if self._jinja_env is not None:
+            html_template_file = f"{base_name}.html"
+            text_template_file = f"{base_name}.txt"
+
+            if await asyncio.to_thread(html_path.is_file):
+                template = await asyncio.to_thread(
+                    self._jinja_env.get_template, html_template_file
+                )
+                html_content = await template.render_async(context)
+
+            if await asyncio.to_thread(text_path.is_file):
+                template = await asyncio.to_thread(
+                    self._jinja_env.get_template, text_template_file
+                )
+                text_content = await template.render_async(context)
+        else:
+            if await asyncio.to_thread(html_path.is_file):
+                raw = await asyncio.to_thread(html_path.read_text, encoding="utf-8")
+                html_content = self._render_string(raw, context, escape_html=True)
+
+            if await asyncio.to_thread(text_path.is_file):
+                raw = await asyncio.to_thread(text_path.read_text, encoding="utf-8")
+                text_content = self._render_string(raw, context, escape_html=False)
+
+        return RenderedEmail(html=html_content, text=text_content)
+
+    def render_string(
+        self,
+        template_str: str,
+        context: dict[str, Any],
+        escape_html: bool = True,
+    ) -> str:
+        """Render a raw template string with context values."""
+        return self._render_string(template_str, context, escape_html=escape_html)
+
+    def _render_string(
+        self,
+        template_str: str,
+        context: dict[str, Any],
+        escape_html: bool,
+    ) -> str:
+        def _resolve_nested(path: str) -> Any:
+            parts = path.split(".")
+            curr: Any = context
+            for part in parts:
+                if part.startswith("_"):
+                    raise MailValidationError(
+                        f"Access to private or dunder template attribute '{part}' is forbidden"
+                    )
+                if isinstance(curr, dict) and part in curr:
+                    curr = curr[part]
+                elif hasattr(curr, part):
+                    curr = getattr(curr, part)
+                else:
+                    return None
+            return curr
+
+        def _replace(match: re.Match[str]) -> str:
+            var_path = match.group(1)
+            val = _resolve_nested(var_path)
+            if val is not None:
+                val_str = str(val)
+                return html.escape(val_str, quote=True) if escape_html else val_str
+            # Missing variable renders as empty string to avoid leaking placeholders
+            return ""
+
+        return _VAR_PATTERN.sub(_replace, template_str)
+
+
+__all__ = ["MailTemplateRenderer", "RenderedEmail"]