✨ Testsuite updates and some tests

.github/workflows/release.yml

@@ -4,9 +4,21 @@ on:
   release:
     types: [created]
   workflow_dispatch:
+    inputs:
+      pypi:
+        description: "Publish to PyPI"
+        required: false
+        default: true
+        type: boolean
+      docker:
+        description: "Publish to GHCR"
+        required: false
+        default: true
+        type: boolean
 
 jobs:
-  publish:
+  pypi:
+    if: ${{ github.event_name == 'release' || inputs.pypi }}
     runs-on: ubuntu-latest
     environment: release
     permissions:
@@ -32,3 +44,46 @@ jobs:
       - if: ${{ github.event_name != 'workflow_dispatch' }}
         name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  docker:
+    if: ${{ github.event_name == 'release' || inputs.docker }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ghcr.io/${{ github.repository }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=ref,event=pr
+            type=pep440,pattern={{version}}
+            type=pep440,pattern={{major}}.{{minor}}
+            type=pep440,pattern={{major}}
+            type=sha,prefix=sha-
+            type=raw,value=latest,enable={{is_default_branch}}
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and publish Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/test.yml

@@ -3,7 +3,7 @@ name: test
 on:
   push:
     branches: main
-  pull_request_target:
+  pull_request:
 
 concurrency:
   group: test-${{ github.head_ref }}
@@ -21,7 +21,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
-        django-version: ['3.2', '4.0', '4.1', '4.2', 'main']
+        django-version: ['3.2', '4.1', '4.2', 'main']
     steps:
     - uses: actions/checkout@v4
 
@@ -37,7 +37,7 @@ jobs:
 
     - name: Run tests
       run: |
-          nox --session "tests-${{ matrix.python-version }}(django='${{ matrix.django-version }}')"
+        python -m nox --session "tests-${{ matrix.python-version }}(django='${{ matrix.django-version }}')"
 
   tests:
     runs-on: ubuntu-latest
@@ -88,7 +88,7 @@ jobs:
     # https://hynek.me/articles/ditch-codecov-python/
     - name: Run tests
       run: |
-        coverage run -m pytest
+        python -m pytest
         python -m coverage html --skip-covered --skip-empty
         python -m coverage report | sed 's/^/    /' >> $GITHUB_STEP_SUMMARY
-        python -m coverage report --fail-under=100
+        python -m coverage report --fail-under=50

.pre-commit-config.yaml

@@ -11,13 +11,13 @@ repos:
       - id: check-yaml
 
   - repo: https://github.com/adamchainz/django-upgrade
-    rev: 1.14.1
+    rev: 1.15.0
     hooks:
       - id: django-upgrade
         args: [--target-version, "4.2"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.290
+    rev: v0.0.291
     hooks:
       - id: ruff
         alias: autoformat

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project attempts to adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- An email backend that stores emails in a database ala a Message model rather than sending them via SMTP or other means
+- A database backend that routes writes to the Message model to a separate database
+- A Message model that stores the contents of an email
+- A relay service intended to be run separately, either as a standalone Docker image or as a management command within a Django project
+- Initial documentation (README.md)
+- Initial tests
+- Initial CI/CD (GitHub Actions)
+
+[unreleased]: https://github.com/westerveltco/django-email-relay/compare/HEAD...HEAD

Justfile

@@ -48,9 +48,7 @@ test:
     python -m nox --reuse-existing-virtualenvs
 
 coverage:
-    rm -rf htmlcov
-    python -m coverage run -m pytest
-    python -m coverage html --skip-covered --skip-empty
+    python -m nox --reuse-existing-virtualenvs --session "coverage"
 
 types:
     python -m mypy .
@@ -235,4 +233,7 @@ envsync:
 ##################
 
 lint:
-    pre-commit run --all-files
+    python -m nox --reuse-existing-virtualenvs --session "lint"
+
+mypy:
+    python -m nox --reuse-existing-virtualenvs --session "mypy"

README.md

@@ -2,15 +2,25 @@
 
 [![PyPI](https://img.shields.io/pypi/v/django-email-relay)](https://pypi.org/project/django-email-relay/)
 ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-email-relay)
-![Django Version](https://img.shields.io/badge/django-3.2%20%7C%204.0%20%7C%204.1%20%7C%204.2-%2344B78B?labelColor=%23092E20)
+![Django Version](https://img.shields.io/badge/django-3.2%20%7C%204.1%20%7C%204.2-%2344B78B?labelColor=%23092E20)
 <!-- https://shields.io/badges -->
-<!-- django-3.2 | 4.0 | 4.1 | 4.2-#44B78B-->
+<!-- django-3.2 | 4.1 | 4.2-#44B78B -->
 <!-- labelColor=%23092E20 -->
 
+`django-email-relay` enables Django projects without direct access to a preferred SMTP server to use that server for email dispatch.
+
+It consists of two parts: a Django app with a custom email backend that stores emails in a central database queue, and a relay service that reads from this queue to orchestrate email sending, available as either a standalone Docker image or a management command to be used within a Django project that does have access to the preferred SMTP server.
+
+Why opt for this setup?
+
+- The potential for emails sent through an external Email Service Provider (ESP) to be marked as spam or filtered, a common issue when routing transactional emails from internal applications to internal users via an ESP.
+- It eliminates the necessity to open firewall ports or the need to utilize services like Tailscale for SMTP server access.
+- It decouples the emailing process from the main web application, much in the same way as using a task queue like Celery or Django-Q2 would.
+
 ## Requirements
 
 - Python 3.8, 3.9, 3.10, 3.11, or 3.12
-- Django 3.2, 4.0, 4.1, or 4.2
+- Django 3.2, 4.1, or 4.2
 - PostgreSQL (for provided Docker image)
 
 ## Installation
@@ -35,7 +45,7 @@ INSTALLED_APPS = [
 ]
 ```
 
-3. Add the `EmailRelayBackend` to your `EMAIL_BACKEND` setting:
+3. Add the `RelayDatabaseEmailBackend` to your `EMAIL_BACKEND` setting:
 
 ```python
 EMAIL_BACKEND = 'email_relay.backend.RelayDatabaseEmailBackend'
@@ -81,12 +91,12 @@ DJANGO_EMAIL_RELAY = {
 }
 ```
 
-4. Add the `EmailRelayDatabaseRouter` to your `DATABASE_ROUTERS` setting:
+4. Add the `EmailDatabaseRouter` to your `DATABASE_ROUTERS` setting:
 
 ```python
 DATABASE_ROUTERS = [
     ...
-    'email_relay.db.EmailRelayDatabaseRouter',
+    'email_relay.db.EmailDatabaseRouter',
     ...
 ]
 ```

noxfile.py

@@ -11,12 +11,11 @@
 PY_DEFAULT = PY38
 
 DJ32 = "3.2"
-DJ40 = "4.0"
 DJ41 = "4.1"
 DJ42 = "4.2"
 DJMAIN = "main"
 DJMAIN_MIN_PY = PY310
-DJ_VERSIONS = [DJ32, DJ40, DJ41, DJ42, DJMAIN]
+DJ_VERSIONS = [DJ32, DJ41, DJ42, DJMAIN]
 DJ_DEFAULT = DJ32
 
 
@@ -50,4 +49,24 @@ def tests(session, django):
     else:
         session.install(f"django=={django}")
 
-    session.run("pytest", "-n", "auto", "--dist", "loadfile")
+    session.run("python", "-m", "pytest", "-n", "auto", "--dist", "loadfile")
+
+
+@nox.session
+def coverage(session):
+    session.install(".[dev]")
+    session.run("python", "-m", "pytest")
+    session.run("python", "-m", "coverage", "html", "--skip-covered", "--skip-empty")
+    session.run("python", "-m", "coverage", "report", "--fail-under=50")
+
+
+@nox.session
+def lint(session):
+    session.install(".[lint]")
+    session.run("pre-commit", "run", "--all-files")
+
+
+@nox.session
+def mypy(session):
+    session.install(".[dev]")
+    session.run("mypy")

pyproject.toml

@@ -41,20 +41,21 @@ requires-python = ">=3.8"
 
 [project.optional-dependencies]
 dev = [
-  "black",
   "coverage[toml]",
   "django-stubs",
   "django-stubs-ext",
   "hatch",
+  "model_bakery",
   "mypy",
   "nox",
   "pytest",
+  "pytest-cov",
   "pytest-django",
   "pytest-randomly",
   "pytest-reverse",
   "pytest-xdist",
-  "ruff",
 ]
+lint = ["pre-commit"]
 psycopg = ["psycopg[binary]"]
 psycopg2 = ["psycopg2-binary"]
 
@@ -112,21 +113,25 @@ version_pattern = "YYYY.INC1"
 
 [tool.coverage.run]
 omit = [
-  "src/email_relay/*/migrations/*",
-  "tests/*",
   "manage.py",
-  "service.py"
+  "service.py",
+  "src/email_relay/migrations/*",
+  "tests/*",
 ]
-source = ["src/email_relay"]
+source = ["email_relay"]
+
+[tool.coverage.paths]
+source = ["src"]
+
 
 [tool.django-stubs]
 django_settings_module = "tests.settings"
+strict_settings = false
 
 [tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
 check_untyped_defs = true
-files = [
-  "src.email_relay",
-]
 no_implicit_optional = true
 plugins = [
   "mypy_django_plugin.main",
@@ -137,24 +142,19 @@ warn_unused_ignores = true
 
 [[tool.mypy.overrides]]
 ignore_errors = true
-module = [
-  "src.email_relay.*.migrations.*",
-]
-
-[[tool.mypy.overrides]]
 ignore_missing_imports = true
-module = []
+module = "tests.*"
 
 [tool.mypy_django_plugin]
 ignore_missing_model_attributes = true
 
 [tool.pytest.ini_options]
-DJANGO_SETTINGS_MODULE = "tests.settings"
 django_find_project = false
 pythonpath = ". src"
-addopts = "--create-db -n auto --dist loadfile"
+addopts = "--create-db --cov=email_relay -n auto --dist loadfile"
 norecursedirs = ".* bin build dist *.egg htmlcov logs node_modules templates venv"
 python_files = "tests.py test_*.py *_tests.py"
+testpaths = ["tests"]
 
 [tool.ruff]
 ignore = ["E501", "E741"] # temporary