feat: add scheduler and mail outbox

SMTP adapter with TLS and a fake, outbox with retries, backoff, rate limit and restart safety, scheduler tick with job-run records started by gunicorn, and a send_test_mail command.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01N3t4WL7bd9bdHHNjEsxzqC

portal/adapters/mail/__init__.py

@@ -0,0 +1,15 @@
+"""Mail adapter: the only code that talks SMTP (AD-1)."""
+
+from .base import Mailer, MailError, MailMessage, MailRejected, MailUnavailable
+from .fake import FakeMailer
+from .smtp import SmtpMailer
+
+__all__ = [
+    "FakeMailer",
+    "MailError",
+    "MailMessage",
+    "MailRejected",
+    "MailUnavailable",
+    "Mailer",
+    "SmtpMailer",
+]

portal/adapters/mail/base.py

@@ -0,0 +1,32 @@
+"""The mail interface the outbox uses (AD-1, AD-11)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class MailError(Exception):
+    """Base class. Messages never contain the recipient or the text of the e-mail."""
+
+
+class MailUnavailable(MailError):
+    """The server could not take the message right now; trying again later may work."""
+
+
+class MailRejected(MailError):
+    """The server refused the message for good (for example an unknown recipient)."""
+
+
+@dataclass(frozen=True)
+class MailMessage:
+    sender: str
+    recipient: str
+    subject: str
+    body_text: str
+
+
+class Mailer(Protocol):
+    def send(self, message: MailMessage) -> None:
+        """Hand the message to the mail server, or raise MailUnavailable or MailRejected."""
+        ...

portal/adapters/mail/fake.py

@@ -0,0 +1,24 @@
+"""In-memory mail server for tests (AD-1)."""
+
+from __future__ import annotations
+
+from .base import MailMessage, MailRejected, MailUnavailable
+
+
+class FakeMailer:
+    """Records what was sent. `unavailable` makes every send fail temporarily; recipients in
+    `rejected` are refused for good."""
+
+    def __init__(self) -> None:
+        self.sent: list[MailMessage] = []
+        self.unavailable = False
+        self.rejected: set[str] = set()
+        self.attempts = 0
+
+    def send(self, message: MailMessage) -> None:
+        self.attempts += 1
+        if self.unavailable:
+            raise MailUnavailable("The mail server is not available")
+        if message.recipient in self.rejected:
+            raise MailRejected("The mail server refused the message (550)")
+        self.sent.append(message)

portal/adapters/mail/smtp.py

@@ -0,0 +1,89 @@
+"""Sends e-mail through an SMTP server over TLS. The only module that talks SMTP (AD-1)."""
+
+from __future__ import annotations
+
+import logging
+import smtplib
+import ssl
+from email.message import EmailMessage
+from email.utils import formatdate, make_msgid
+
+from portal.config.env import SmtpConfig
+
+from .base import MailMessage, MailRejected, MailUnavailable
+
+logger = logging.getLogger(__name__)
+
+TIMEOUT_SECONDS = 20
+
+
+class SmtpMailer:
+    def __init__(self, config: SmtpConfig, smtp_module=smtplib) -> None:
+        self._config = config
+        self._smtp = smtp_module
+
+    def _build(self, message: MailMessage) -> EmailMessage:
+        email = EmailMessage()
+        # Setting a header that holds a line break raises ValueError, so no header injection.
+        email["From"] = message.sender
+        email["To"] = message.recipient
+        email["Subject"] = message.subject
+        email["Date"] = formatdate(localtime=False)
+        email["Message-ID"] = make_msgid(domain=self._config.host)
+        email.set_content(message.body_text, charset="utf-8")
+        return email
+
+    def _connect(self):
+        config = self._config
+        context = ssl.create_default_context()  # verifies the certificate and the host name
+        if config.security == "ssl":
+            connection = self._smtp.SMTP_SSL(
+                config.host, config.port, timeout=TIMEOUT_SECONDS, context=context
+            )
+        else:
+            connection = self._smtp.SMTP(config.host, config.port, timeout=TIMEOUT_SECONDS)
+        try:
+            connection.ehlo()
+            if config.security == "starttls":
+                connection.starttls(context=context)
+                connection.ehlo()
+            connection.login(config.username, config.password)
+        except BaseException:
+            connection.close()
+            raise
+        return connection
+
+    def send(self, message: MailMessage) -> None:
+        try:
+            email = self._build(message)
+        except ValueError as exc:
+            raise MailRejected("The message could not be built") from exc
+        try:
+            connection = self._connect()
+            try:
+                connection.send_message(email)
+            finally:
+                try:
+                    connection.quit()
+                except (self._smtp.SMTPException, OSError):
+                    connection.close()
+        except self._smtp.SMTPAuthenticationError as exc:
+            # A configuration problem: the Admin fixes it and the retry works.
+            logger.error("SMTP login refused (code %s)", exc.smtp_code)
+            raise MailUnavailable(f"The mail server refused the login ({exc.smtp_code})") from exc
+        except self._smtp.SMTPRecipientsRefused as exc:
+            codes = [code for code, _ in exc.recipients.values()]
+            raise _by_code(max(codes, default=0)) from exc
+        except self._smtp.SMTPResponseException as exc:
+            raise _by_code(exc.smtp_code) from exc
+        except (self._smtp.SMTPException, OSError, ssl.SSLError) as exc:
+            logger.warning("SMTP request failed: %s", type(exc).__name__)
+            name = type(exc).__name__
+            raise MailUnavailable(f"The mail server is not available ({name})") from exc
+
+
+def _by_code(code: int):
+    """Codes 5xx are permanent; everything else may work later."""
+    if 500 <= code < 600:
+        return MailRejected(f"The mail server refused the message ({code})")
+    return MailUnavailable(f"The mail server could not take the message ({code})")