simple-module-mail 0.0.38__py3-none-any.whl

mail/__init__.py

@@ -0,0 +1 @@
+"""Mail module."""

mail/constants.py

@@ -0,0 +1,24 @@
+"""Every literal the mail module depends on."""
+
+from __future__ import annotations
+
+MODULE_NAME = "Mail"
+MODULE_PACKAGE = "mail"
+
+# Dependency names must match the other modules' ``ModuleMeta.name``.
+MODULE_SETTINGS = "Settings"
+
+BACKEND_CONSOLE = "console"
+BACKEND_SMTP = "smtp"
+
+# On-demand health check; also drives the settings page's "Test connection".
+CHECK_MAILER = "mail.mailer"
+
+DEFAULT_FROM = "no-reply@localhost"
+DEFAULT_SMTP_PORT = 587
+MIN_PORT = 1
+MAX_PORT = 65535
+
+#: Seconds per SMTP operation (aiosmtplib defaults to 60). A send can run in a
+#: request's after-commit hook, so a hung server must not hold it for a minute.
+SMTP_TIMEOUT_SECONDS = 15.0

mail/module.py

@@ -0,0 +1,75 @@
+"""Mail module — the app's outgoing-mail transport, configured from the DB."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from simple_module_core.health import HealthCheck, HealthRegistry
+from simple_module_core.mail import install_mail_resolver, install_mail_sender
+from simple_module_core.module import ModuleBase, ModuleMeta
+
+from mail import constants as c
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from simple_module_core.events import EventBus
+
+
+class MailModule(ModuleBase):
+    meta = ModuleMeta(
+        name=c.MODULE_NAME,
+        # ``Settings``: the runtime re-reads overrides through its SettingsStore.
+        depends_on=[c.MODULE_SETTINGS],
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from simple_module_core.module_settings import register_module_settings
+
+        from mail.settings import MailSettings
+        from mail.state import MailState
+
+        register_module_settings(
+            app, c.MODULE_PACKAGE, MailSettings, lambda s: MailState(settings=s)
+        )
+
+    def register_health_checks(self, registry: HealthRegistry) -> None:
+        from mail.runtime import check_smtp
+
+        registry.add(
+            HealthCheck(
+                name=c.CHECK_MAILER,
+                check=check_smtp,
+                # On demand only: this authenticates against the mail provider,
+                # which must not happen on a readiness-probe timer.
+                probe=False,
+            )
+        )
+
+    def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) -> None:
+        # Before the ``app is None`` return: the outbox worker builds modules
+        # without an app and still has to send durable mail.
+        from mail.runtime import resolve_sender_from_db
+
+        install_mail_resolver(resolve_sender_from_db)
+        if app is None:
+            return
+
+        from settings.contracts.events import SettingsReloaded
+
+        from mail.runtime import install_app_sender
+
+        async def _reinstall(event: SettingsReloaded) -> None:
+            if event.package != c.MODULE_PACKAGE:
+                return
+            install_app_sender(app)
+
+        bus.subscribe(SettingsReloaded, _reinstall)
+
+    async def on_startup(self, app: FastAPI) -> None:
+        from mail.runtime import install_app_sender
+
+        install_app_sender(app)
+
+    async def on_shutdown(self, app: FastAPI) -> None:
+        install_mail_sender(None)
+        install_mail_resolver(None)

mail/runtime.py

@@ -0,0 +1,63 @@
+"""Resolver and health check: the parts that work without an app."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from settings.service import SettingService
+from settings.store import SettingsStore
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+from simple_module_core.health import HealthCheckResult, HealthStatus
+from simple_module_core.mail import MailSender, current_mail_sender, install_mail_sender
+from simple_module_core.settings_hydrate import hydrate_settings
+
+from mail import constants as c
+from mail.sender import build_sender
+from mail.settings import MailSettings
+
+
+async def resolve_sender_from_db(db: Any) -> MailSender:
+    """Build a sender from the stored settings; used where none is installed.
+
+    The outbox worker builds modules without an app, so it has only a session.
+    """
+    store = SettingsStore(SettingService(db))
+    settings = await hydrate_settings(MailSettings, store, c.MODULE_PACKAGE, lenient=True)
+    return build_sender(settings, log_bodies=_worker_is_non_prod())
+
+
+def _worker_is_non_prod() -> bool:
+    # No app (and so no host settings) in the worker: read the process's
+    # environment the way background_tasks' own checks do.
+    return os.environ.get("SM_ENVIRONMENT", "development") in NON_PROD_ENVIRONMENTS
+
+
+def install_app_sender(app: Any) -> None:
+    """Install a sender built from *app*'s current mail settings.
+
+    Bodies are logged only in development or testing (host ``environment``).
+    """
+    log_bodies = app.state.sm.settings.environment in NON_PROD_ENVIRONMENTS
+    install_mail_sender(build_sender(app.state.mail.settings, log_bodies=log_bodies))
+
+
+async def check_smtp() -> HealthCheckResult:
+    """Verify the installed sender, re-read on every run.
+
+    Settings can change after boot, so a check pinned to the boot-time sender
+    would keep testing credentials the admin has replaced.
+    """
+    sender = current_mail_sender()
+    verify = getattr(sender, "verify_connection", None)
+    if verify is None:
+        return HealthCheckResult(
+            status=HealthStatus.HEALTHY,
+            detail=f"{type(sender).__name__} needs no connection",
+        )
+    try:
+        await verify()
+    except Exception as exc:
+        # The reason matters more than the traceback.
+        return HealthCheckResult(status=HealthStatus.UNHEALTHY, detail=str(exc))
+    return HealthCheckResult(status=HealthStatus.HEALTHY, detail="SMTP reachable")

mail/sender.py

@@ -0,0 +1,94 @@
+"""Mail senders and the settings -> sender mapping."""
+
+from __future__ import annotations
+
+import contextlib
+from email.message import EmailMessage
+
+import aiosmtplib
+from simple_module_core.mail import ConsoleMailSender, MailMessage, MailSender
+
+from mail import constants as c
+from mail.settings import MailSettings
+
+
+class SmtpMailSender:
+    """Delivers through an SMTP server with aiosmtplib."""
+
+    delivers_email = True
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        username: str,
+        password: str,
+        from_address: str,
+        use_tls: bool,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._username = username
+        self._password = password
+        self._from = from_address
+        self._use_tls = use_tls
+
+    async def send(self, message: MailMessage) -> None:
+        email = EmailMessage()
+        email["From"] = self._from
+        email["To"] = message.to
+        email["Subject"] = message.subject
+        email.set_content(message.text)
+        if message.html:
+            email.add_alternative(message.html, subtype="html")
+
+        await aiosmtplib.send(
+            email,
+            hostname=self._host,
+            port=self._port,
+            username=self._username or None,
+            password=self._password or None,
+            use_tls=self._use_tls,
+            timeout=c.SMTP_TIMEOUT_SECONDS,
+        )
+
+    async def verify_connection(self) -> None:
+        """Open an SMTP session and authenticate, then hang up.
+
+        Deliberately stops short of sending anything: an admin checking their
+        config should not put a stray message in someone's inbox. Raises
+        whatever aiosmtplib raises so the caller can show the real reason.
+        """
+        client = aiosmtplib.SMTP(
+            hostname=self._host,
+            port=self._port,
+            use_tls=self._use_tls,
+            timeout=c.SMTP_TIMEOUT_SECONDS,
+        )
+        await client.connect()
+        try:
+            if self._username:
+                await client.login(self._username, self._password or "")
+        finally:
+            # A failure hanging up must not mask the login error being unwound.
+            with contextlib.suppress(Exception):
+                await client.quit()
+
+
+def build_sender(settings: MailSettings, *, log_bodies: bool = True) -> MailSender:
+    """``smtp`` -> :class:`SmtpMailSender`; ``console`` -> a logging sender.
+
+    *log_bodies* is false outside development and testing: a console backend
+    left in place in production must not write reset and invite tokens to the
+    log, so there it logs only recipient and subject.
+    """
+    if settings.backend == c.BACKEND_SMTP:
+        return SmtpMailSender(
+            host=settings.smtp_host,
+            port=settings.smtp_port,
+            username=settings.smtp_username,
+            password=settings.smtp_password,
+            from_address=settings.smtp_from,
+            use_tls=settings.smtp_tls,
+        )
+    return ConsoleMailSender(include_body=log_bodies)

mail/settings.py

@@ -0,0 +1,30 @@
+"""Mail module settings — DB-backed via ``register_module_settings``.
+
+``smtp_password`` is masked by the settings UI because its name matches the
+secret-field pattern (``simple_module_core.secret_fields.is_secret_field``).
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+from simple_module_core.settings_base import DbBackedSettings
+
+from mail import constants as c
+
+
+class MailSettings(DbBackedSettings):
+    """Which transport sends mail, and the SMTP account it uses."""
+
+    # ``DbBackedSettings`` so the DB is the only source (GH #283).
+    model_config = SettingsConfigDict(extra="ignore")
+
+    backend: Literal["console", "smtp"] = c.BACKEND_CONSOLE
+    smtp_host: str = ""
+    smtp_port: int = Field(default=c.DEFAULT_SMTP_PORT, ge=c.MIN_PORT, le=c.MAX_PORT)
+    smtp_username: str = ""
+    smtp_password: str = ""
+    smtp_from: str = c.DEFAULT_FROM
+    smtp_tls: bool = True

mail/state.py

@@ -0,0 +1,14 @@
+"""Module-owned state attached to ``app.state.mail``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mail.settings import MailSettings
+
+
+@dataclass
+class MailState:
+    """``settings`` is reassigned in place on a hot reload, so stay mutable."""
+
+    settings: MailSettings

simple_module_mail-0.0.38.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: simple_module_mail
+Version: 0.0.38
+Summary: Outgoing mail (SMTP or console) for simple_module apps, configured from the DB-backed settings
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,mail,simple-module,smtp
+Requires-Python: >=3.12
+Requires-Dist: aiosmtplib>=3.0
+Requires-Dist: simple-module-core==0.0.38
+Requires-Dist: simple-module-settings==0.0.38
+Description-Content-Type: text/markdown
+
+# simple_module_mail
+
+Outgoing mail for `simple_module` apps. The module owns the transport (SMTP via
+`aiosmtplib`, or a console backend that logs each message) and its settings, and
+installs a process-level sender that any module can use through
+`simple_module_core.mail` without knowing whether mail is configured.
+
+The default backend is `console`: messages are logged, nothing is delivered.
+Switch to `smtp` and fill in the server details to deliver real email.
+
+## Install
+
+Add the package to your host and re-sync. Discovery picks it up from the
+`simple_module` entry point, no host code changes:
+
+```toml
+# host/pyproject.toml
+dependencies = ["simple_module_mail"]
+```
+
+```bash
+uv sync --all-packages
+```
+
+## Usage
+
+1. Sign in as an admin and open **Settings -> Modules -> Mail**.
+2. Set `backend` to `smtp` and fill `smtp_host`, `smtp_port`, `smtp_username`,
+   `smtp_password` (masked in the UI), `smtp_from` and `smtp_tls`. Saving
+   rebuilds the sender live, no restart needed.
+3. Use **Test connection** to run the `mail.mailer` health check. It logs in to
+   the server and hangs up without sending anything.
+
+From code, send through the core interface:
+
+```python
+from simple_module_core.mail import MailMessage, current_mail_sender
+
+await current_mail_sender().send(
+    MailMessage(to="a@example.com", subject="Hello", text="Plain body")
+)
+```
+
+Code that may run in the outbox worker (no `app`) calls
+`await resolve_mail_sender(db)` instead; the module installs a resolver that
+builds the sender from the stored settings. `sender.delivers_email` is `False`
+for the console backend, so screens can fall back to showing a link.
+
+Settings stored by earlier versions as `users.mailer` / `users.smtp_*` are moved
+to `mail.backend` / `mail.smtp_*` by a data migration.

simple_module_mail-0.0.38.dist-info/RECORD

@@ -0,0 +1,13 @@
+mail/__init__.py,sha256=Y-bRGfB1ShpdMEa3VnYILwicDfKX2FRg0U_s3-vA_CA,19
+mail/constants.py,sha256=YSGPqHmbq_QdXUjVFWGp_yFkh4zTFkFKJWJlE-ZsEag,667
+mail/module.py,sha256=syTNxf_AFrgIejUDZQbiOcMRVEyG7PI9NH13TeFZbrY,2485
+mail/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mail/runtime.py,sha256=rhsqUxAl4Avd_4TO18997PkZ-1wO85ghBPlH-UFKfjs,2461
+mail/sender.py,sha256=uMSfJU82PF9GYabKMNU9VqjO-PQ3KTML8uYN2zhBFio,3050
+mail/settings.py,sha256=EGEc5uxwr0kDIewA-EQFP-nL0TVHrB1n-ECF-_iN4Bw,985
+mail/state.py,sha256=WIhsa4dsO9nk8HvL812m4D1AJgVJ9WnRsQpn19-ZLtE,306
+simple_module_mail-0.0.38.dist-info/METADATA,sha256=_PMaL8ZIrgeA8Ae5AMMTA9iWjgQOzYQlW5gHD_4u5Bc,2591
+simple_module_mail-0.0.38.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+simple_module_mail-0.0.38.dist-info/entry_points.txt,sha256=O3Bwcev1zoGXKR9CuwpTquAbn53euXpw6suXARrpyic,46
+simple_module_mail-0.0.38.dist-info/licenses/LICENSE,sha256=UIp30ue1HZit7tMmSK0SS3swJBqOcLLnLJn5LY5YdNE,1036
+simple_module_mail-0.0.38.dist-info/RECORD,,

simple_module_mail-0.0.38.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_mail-0.0.38.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+mail = mail.module:MailModule

simple_module_mail-0.0.38.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.