stapel-mailtrap 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- stapel_mailtrap-0.1.1/LICENSE +21 -0
- stapel_mailtrap-0.1.1/PKG-INFO +172 -0
- stapel_mailtrap-0.1.1/README.md +144 -0
- stapel_mailtrap-0.1.1/__init__.py +53 -0
- stapel_mailtrap-0.1.1/admin.py +34 -0
- stapel_mailtrap-0.1.1/apps.py +16 -0
- stapel_mailtrap-0.1.1/checks.py +50 -0
- stapel_mailtrap-0.1.1/conf.py +37 -0
- stapel_mailtrap-0.1.1/conftest.py +61 -0
- stapel_mailtrap-0.1.1/dto.py +55 -0
- stapel_mailtrap-0.1.1/errors.py +20 -0
- stapel_mailtrap-0.1.1/management/__init__.py +0 -0
- stapel_mailtrap-0.1.1/management/commands/__init__.py +0 -0
- stapel_mailtrap-0.1.1/management/commands/purge_trapped_emails.py +56 -0
- stapel_mailtrap-0.1.1/migrations/0001_initial.py +34 -0
- stapel_mailtrap-0.1.1/migrations/__init__.py +0 -0
- stapel_mailtrap-0.1.1/models.py +49 -0
- stapel_mailtrap-0.1.1/provider.py +63 -0
- stapel_mailtrap-0.1.1/py.typed +0 -0
- stapel_mailtrap-0.1.1/pyproject.toml +68 -0
- stapel_mailtrap-0.1.1/schemas/emits/mailtrap.email.trapped.json +17 -0
- stapel_mailtrap-0.1.1/scope.py +36 -0
- stapel_mailtrap-0.1.1/serializers.py +19 -0
- stapel_mailtrap-0.1.1/services.py +110 -0
- stapel_mailtrap-0.1.1/setup.cfg +4 -0
- stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/PKG-INFO +172 -0
- stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/SOURCES.txt +59 -0
- stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/dependency_links.txt +1 -0
- stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/requires.txt +3 -0
- stapel_mailtrap-0.1.1/stapel_mailtrap.egg-info/top_level.txt +1 -0
- stapel_mailtrap-0.1.1/tasks.py +51 -0
- stapel_mailtrap-0.1.1/tests/test_api.py +74 -0
- stapel_mailtrap-0.1.1/tests/test_command_and_task.py +56 -0
- stapel_mailtrap-0.1.1/tests/test_provider.py +44 -0
- stapel_mailtrap-0.1.1/tests/test_seams.py +77 -0
- stapel_mailtrap-0.1.1/tests/test_services.py +93 -0
- stapel_mailtrap-0.1.1/urls.py +17 -0
- stapel_mailtrap-0.1.1/views.py +125 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Stapel contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: stapel-mailtrap
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Email trap (mail catcher) for the Stapel framework — capture outbound email in dev/staging
|
|
5
|
+
License: MIT
|
|
6
|
+
Project-URL: Homepage, https://github.com/usestapel/stapel-mailtrap
|
|
7
|
+
Project-URL: Repository, https://github.com/usestapel/stapel-mailtrap
|
|
8
|
+
Project-URL: Documentation, https://github.com/usestapel/stapel-mailtrap#readme
|
|
9
|
+
Project-URL: Changelog, https://github.com/usestapel/stapel-mailtrap/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Issues, https://github.com/usestapel/stapel-mailtrap/issues
|
|
11
|
+
Keywords: django,stapel,email,mailtrap,mailcatcher
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Framework :: Django
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: stapel-core<0.9,>=0.8
|
|
26
|
+
Provides-Extra: all
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# stapel-mailtrap
|
|
30
|
+
|
|
31
|
+
[](https://github.com/usestapel/stapel-mailtrap/actions/workflows/ci.yml)
|
|
32
|
+
[](https://codecov.io/gh/usestapel/stapel-mailtrap)
|
|
33
|
+
|
|
34
|
+
> An email trap (mail catcher) for dev/staging: outbound mail is captured into
|
|
35
|
+
> a `TrappedEmail` journal instead of being sent, and browsed through a
|
|
36
|
+
> read-only "Mail" API. Plugs into stapel-notifications' email-provider seam by
|
|
37
|
+
> dotted path — no module-to-module import.
|
|
38
|
+
|
|
39
|
+
Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps
|
|
40
|
+
that deploy as a monolith or as microservices without changing module code.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pip install stapel-mailtrap
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
# settings.py
|
|
50
|
+
INSTALLED_APPS = [
|
|
51
|
+
# ...
|
|
52
|
+
"stapel_mailtrap",
|
|
53
|
+
]
|
|
54
|
+
|
|
55
|
+
# urls.py
|
|
56
|
+
path("mailtrap/", include("stapel_mailtrap.urls"))
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
python manage.py migrate
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Trapping notifications email
|
|
64
|
+
|
|
65
|
+
Point stapel-notifications' email provider at the trap — one setting, no code:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
STAPEL_NOTIFICATIONS = {
|
|
69
|
+
"EMAIL_PROVIDER": "stapel_mailtrap.provider.MailtrapEmailProvider",
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Every email stapel-notifications would send is now persisted and inspectable
|
|
74
|
+
instead. The provider matches the notifications email duck type
|
|
75
|
+
(`send(recipient, subject, html_body, headers)`) — see MODULE.md §3.
|
|
76
|
+
|
|
77
|
+
## Trapping any backend
|
|
78
|
+
|
|
79
|
+
For a host whose own mail path should trap, call the service directly:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from stapel_mailtrap import trap_email
|
|
83
|
+
|
|
84
|
+
trap_email(
|
|
85
|
+
to_email="alice@example.com",
|
|
86
|
+
from_email="bot@example.com",
|
|
87
|
+
subject="Your code",
|
|
88
|
+
body_html="<b>123456</b>",
|
|
89
|
+
body_text="123456",
|
|
90
|
+
attachments=[{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 8123}],
|
|
91
|
+
scope_key="workspace-42", # opaque host scope
|
|
92
|
+
)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
It persists the row and emits `mailtrap.email.trapped` transactionally.
|
|
96
|
+
Attachments are **metadata only** — raw bytes are never stored.
|
|
97
|
+
|
|
98
|
+
## HTTP API ("Письма" / Mail)
|
|
99
|
+
|
|
100
|
+
Read-only (the trap is filled by the provider / `trap_email`, never via the API):
|
|
101
|
+
|
|
102
|
+
| Route | Meaning |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `GET mailtrap/emails/` | Trapped emails, newest first, paginated (anchor); `?scope_key=` filters |
|
|
105
|
+
| `GET mailtrap/emails/<uuid>/` | One trapped email — full HTML/text bodies + attachment metadata |
|
|
106
|
+
|
|
107
|
+
Default permission is staff/service only (trapped mail can contain OTPs and
|
|
108
|
+
magic links). Override `permission_classes` and set a `SCOPE_PROVIDER` for
|
|
109
|
+
per-tenant visibility — see MODULE.md.
|
|
110
|
+
|
|
111
|
+
## Retention
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
STAPEL_MAILTRAP = {
|
|
115
|
+
"MAX_EMAILS": 1000, # hard cap on stored rows (0 disables)
|
|
116
|
+
"TTL_DAYS": 30, # delete rows older than N days (0 disables)
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Run the sweep from any scheduler:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
python manage.py purge_trapped_emails # --dry-run supported
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Or schedule the Celery task (celery is an optional host dependency):
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
CELERY_BEAT_SCHEDULE = {
|
|
130
|
+
"purge-trapped-emails": {
|
|
131
|
+
"task": "stapel_mailtrap.tasks.purge_trapped_emails",
|
|
132
|
+
"schedule": crontab(hour=3, minute=0), # nightly
|
|
133
|
+
},
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Settings
|
|
138
|
+
|
|
139
|
+
All configuration lives in the `STAPEL_MAILTRAP` namespace (dict setting, flat
|
|
140
|
+
setting, or env var — resolved lazily):
|
|
141
|
+
|
|
142
|
+
| Key | Default | Meaning |
|
|
143
|
+
|---|---|---|
|
|
144
|
+
| `SCOPE_PROVIDER` | `"stapel_mailtrap.scope.DefaultScopeProvider"` | Dotted path to a `ScopeProvider` subclass — the multi-tenant seam. |
|
|
145
|
+
| `MAX_EMAILS` | `1000` | Retention count cap (0 disables). |
|
|
146
|
+
| `TTL_DAYS` | `30` | Retention age cap in days (0 disables). |
|
|
147
|
+
| `STORE_BODY` | `True` | `False` stores the envelope only (bodies empty). |
|
|
148
|
+
|
|
149
|
+
## comm surface
|
|
150
|
+
|
|
151
|
+
| Kind | Name | Contract |
|
|
152
|
+
|---|---|---|
|
|
153
|
+
| Event | `mailtrap.email.trapped` | `{email_id, to, from?, subject, scope_key, attachment_count, trapped_at}` — [schema](schemas/emits/mailtrap.email.trapped.json) |
|
|
154
|
+
|
|
155
|
+
## Extension points
|
|
156
|
+
|
|
157
|
+
See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
|
|
158
|
+
(settings, the `ScopeProvider` seam, the notifications email-provider adapter
|
|
159
|
+
with its duck-typed contract, serializer seams, permissions, comm surface,
|
|
160
|
+
system checks).
|
|
161
|
+
|
|
162
|
+
## Development
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
pip install -e . && pip install pytest pytest-django pytest-cov ruff jsonschema
|
|
166
|
+
./setup-hooks.sh
|
|
167
|
+
pytest tests/
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## License
|
|
171
|
+
|
|
172
|
+
MIT
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# stapel-mailtrap
|
|
2
|
+
|
|
3
|
+
[](https://github.com/usestapel/stapel-mailtrap/actions/workflows/ci.yml)
|
|
4
|
+
[](https://codecov.io/gh/usestapel/stapel-mailtrap)
|
|
5
|
+
|
|
6
|
+
> An email trap (mail catcher) for dev/staging: outbound mail is captured into
|
|
7
|
+
> a `TrappedEmail` journal instead of being sent, and browsed through a
|
|
8
|
+
> read-only "Mail" API. Plugs into stapel-notifications' email-provider seam by
|
|
9
|
+
> dotted path — no module-to-module import.
|
|
10
|
+
|
|
11
|
+
Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps
|
|
12
|
+
that deploy as a monolith or as microservices without changing module code.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pip install stapel-mailtrap
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
# settings.py
|
|
22
|
+
INSTALLED_APPS = [
|
|
23
|
+
# ...
|
|
24
|
+
"stapel_mailtrap",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
# urls.py
|
|
28
|
+
path("mailtrap/", include("stapel_mailtrap.urls"))
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
python manage.py migrate
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Trapping notifications email
|
|
36
|
+
|
|
37
|
+
Point stapel-notifications' email provider at the trap — one setting, no code:
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
STAPEL_NOTIFICATIONS = {
|
|
41
|
+
"EMAIL_PROVIDER": "stapel_mailtrap.provider.MailtrapEmailProvider",
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Every email stapel-notifications would send is now persisted and inspectable
|
|
46
|
+
instead. The provider matches the notifications email duck type
|
|
47
|
+
(`send(recipient, subject, html_body, headers)`) — see MODULE.md §3.
|
|
48
|
+
|
|
49
|
+
## Trapping any backend
|
|
50
|
+
|
|
51
|
+
For a host whose own mail path should trap, call the service directly:
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
from stapel_mailtrap import trap_email
|
|
55
|
+
|
|
56
|
+
trap_email(
|
|
57
|
+
to_email="alice@example.com",
|
|
58
|
+
from_email="bot@example.com",
|
|
59
|
+
subject="Your code",
|
|
60
|
+
body_html="<b>123456</b>",
|
|
61
|
+
body_text="123456",
|
|
62
|
+
attachments=[{"filename": "invoice.pdf", "content_type": "application/pdf", "size": 8123}],
|
|
63
|
+
scope_key="workspace-42", # opaque host scope
|
|
64
|
+
)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
It persists the row and emits `mailtrap.email.trapped` transactionally.
|
|
68
|
+
Attachments are **metadata only** — raw bytes are never stored.
|
|
69
|
+
|
|
70
|
+
## HTTP API ("Письма" / Mail)
|
|
71
|
+
|
|
72
|
+
Read-only (the trap is filled by the provider / `trap_email`, never via the API):
|
|
73
|
+
|
|
74
|
+
| Route | Meaning |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `GET mailtrap/emails/` | Trapped emails, newest first, paginated (anchor); `?scope_key=` filters |
|
|
77
|
+
| `GET mailtrap/emails/<uuid>/` | One trapped email — full HTML/text bodies + attachment metadata |
|
|
78
|
+
|
|
79
|
+
Default permission is staff/service only (trapped mail can contain OTPs and
|
|
80
|
+
magic links). Override `permission_classes` and set a `SCOPE_PROVIDER` for
|
|
81
|
+
per-tenant visibility — see MODULE.md.
|
|
82
|
+
|
|
83
|
+
## Retention
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
STAPEL_MAILTRAP = {
|
|
87
|
+
"MAX_EMAILS": 1000, # hard cap on stored rows (0 disables)
|
|
88
|
+
"TTL_DAYS": 30, # delete rows older than N days (0 disables)
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Run the sweep from any scheduler:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
python manage.py purge_trapped_emails # --dry-run supported
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Or schedule the Celery task (celery is an optional host dependency):
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
CELERY_BEAT_SCHEDULE = {
|
|
102
|
+
"purge-trapped-emails": {
|
|
103
|
+
"task": "stapel_mailtrap.tasks.purge_trapped_emails",
|
|
104
|
+
"schedule": crontab(hour=3, minute=0), # nightly
|
|
105
|
+
},
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Settings
|
|
110
|
+
|
|
111
|
+
All configuration lives in the `STAPEL_MAILTRAP` namespace (dict setting, flat
|
|
112
|
+
setting, or env var — resolved lazily):
|
|
113
|
+
|
|
114
|
+
| Key | Default | Meaning |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| `SCOPE_PROVIDER` | `"stapel_mailtrap.scope.DefaultScopeProvider"` | Dotted path to a `ScopeProvider` subclass — the multi-tenant seam. |
|
|
117
|
+
| `MAX_EMAILS` | `1000` | Retention count cap (0 disables). |
|
|
118
|
+
| `TTL_DAYS` | `30` | Retention age cap in days (0 disables). |
|
|
119
|
+
| `STORE_BODY` | `True` | `False` stores the envelope only (bodies empty). |
|
|
120
|
+
|
|
121
|
+
## comm surface
|
|
122
|
+
|
|
123
|
+
| Kind | Name | Contract |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| Event | `mailtrap.email.trapped` | `{email_id, to, from?, subject, scope_key, attachment_count, trapped_at}` — [schema](schemas/emits/mailtrap.email.trapped.json) |
|
|
126
|
+
|
|
127
|
+
## Extension points
|
|
128
|
+
|
|
129
|
+
See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
|
|
130
|
+
(settings, the `ScopeProvider` seam, the notifications email-provider adapter
|
|
131
|
+
with its duck-typed contract, serializer seams, permissions, comm surface,
|
|
132
|
+
system checks).
|
|
133
|
+
|
|
134
|
+
## Development
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
pip install -e . && pip install pytest pytest-django pytest-cov ruff jsonschema
|
|
138
|
+
./setup-hooks.sh
|
|
139
|
+
pytest tests/
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
MIT
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""stapel-mailtrap — an email trap (mail catcher) for the Stapel framework.
|
|
2
|
+
|
|
3
|
+
In dev/staging, outbound mail must not leave the box (system-design S4: SMTP
|
|
4
|
+
is closed). This module is the sink: an email "provider" that, instead of
|
|
5
|
+
sending, persists every message as a ``TrappedEmail`` row and emits
|
|
6
|
+
``mailtrap.email.trapped``. A read-only DRF API ("Письма" / Mail) lists and
|
|
7
|
+
inspects captured mail. It plugs into stapel-notifications' email-provider
|
|
8
|
+
seam **by dotted path** — no module imports another (invariant I2).
|
|
9
|
+
|
|
10
|
+
Public API (lazily exported, PEP 562 — importing this package never pulls in
|
|
11
|
+
Django or requires configured settings):
|
|
12
|
+
|
|
13
|
+
- ``mailtrap_settings`` — resolved app settings (``stapel_mailtrap.conf``).
|
|
14
|
+
- ``MailtrapEmailProvider`` — the notifications email-provider adapter
|
|
15
|
+
(dotted path for ``STAPEL_NOTIFICATIONS["EMAIL_PROVIDER"]``).
|
|
16
|
+
- ``ScopeProvider`` / ``DefaultScopeProvider`` — the multi-tenant scope seam.
|
|
17
|
+
- ``trap_email`` — persist one message + emit ``mailtrap.email.trapped``.
|
|
18
|
+
- ``purge_expired`` — retention sweep (TTL + MAX_EMAILS cap).
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"DefaultScopeProvider",
|
|
23
|
+
"MailtrapEmailProvider",
|
|
24
|
+
"ScopeProvider",
|
|
25
|
+
"mailtrap_settings",
|
|
26
|
+
"purge_expired",
|
|
27
|
+
"trap_email",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
# name -> submodule that defines it. Resolution is deferred until first
|
|
31
|
+
# attribute access so that `import stapel_mailtrap` stays Django-free.
|
|
32
|
+
_LAZY_EXPORTS = {
|
|
33
|
+
"mailtrap_settings": ".conf",
|
|
34
|
+
"MailtrapEmailProvider": ".provider",
|
|
35
|
+
"ScopeProvider": ".scope",
|
|
36
|
+
"DefaultScopeProvider": ".scope",
|
|
37
|
+
"trap_email": ".services",
|
|
38
|
+
"purge_expired": ".services",
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def __getattr__(name):
|
|
43
|
+
if name in _LAZY_EXPORTS:
|
|
44
|
+
from importlib import import_module
|
|
45
|
+
|
|
46
|
+
value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
|
|
47
|
+
globals()[name] = value # cache for subsequent lookups
|
|
48
|
+
return value
|
|
49
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def __dir__():
|
|
53
|
+
return sorted(set(globals()) | set(__all__))
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""Read-only admin for the trapped-email journal (docs/library-standard.md §2).
|
|
2
|
+
|
|
3
|
+
The trap is filled by the notifications provider / ``trap_email`` — never by
|
|
4
|
+
hand — so the admin is inspect-only; deletion is allowed for manual cleanup.
|
|
5
|
+
"""
|
|
6
|
+
from django.contrib import admin
|
|
7
|
+
|
|
8
|
+
from .models import TrappedEmail
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@admin.register(TrappedEmail)
|
|
12
|
+
class TrappedEmailAdmin(admin.ModelAdmin):
|
|
13
|
+
list_display = ["id", "subject", "to_email", "from_email", "scope_key", "created_at"]
|
|
14
|
+
list_filter = ["scope_key", "created_at"]
|
|
15
|
+
search_fields = ["to_email", "from_email", "subject", "scope_key"]
|
|
16
|
+
readonly_fields = [
|
|
17
|
+
"id",
|
|
18
|
+
"to_email",
|
|
19
|
+
"from_email",
|
|
20
|
+
"subject",
|
|
21
|
+
"body_html",
|
|
22
|
+
"body_text",
|
|
23
|
+
"attachments",
|
|
24
|
+
"headers",
|
|
25
|
+
"scope_key",
|
|
26
|
+
"created_at",
|
|
27
|
+
]
|
|
28
|
+
ordering = ["-created_at"]
|
|
29
|
+
|
|
30
|
+
def has_add_permission(self, request):
|
|
31
|
+
return False
|
|
32
|
+
|
|
33
|
+
def has_change_permission(self, request, obj=None):
|
|
34
|
+
return False
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
from django.apps import AppConfig
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
class MailtrapConfig(AppConfig):
|
|
5
|
+
name = "stapel_mailtrap"
|
|
6
|
+
label = "mailtrap"
|
|
7
|
+
verbose_name = "Mail trap"
|
|
8
|
+
default_auto_field = "django.db.models.BigAutoField"
|
|
9
|
+
|
|
10
|
+
def ready(self):
|
|
11
|
+
# Import-time side effects: system checks + error-key registration.
|
|
12
|
+
# Keep each in its own module. The email-provider adapter is resolved
|
|
13
|
+
# lazily by stapel-notifications (dotted path), so nothing to register
|
|
14
|
+
# here for it.
|
|
15
|
+
from . import checks # noqa: F401
|
|
16
|
+
from . import errors # noqa: F401
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Django system checks for stapel-mailtrap configuration.
|
|
2
|
+
|
|
3
|
+
Policy (docs/library-standard.md §3.7): E-level for configuration the service
|
|
4
|
+
cannot run with; W-level for entries that degrade lazily. The scope provider is
|
|
5
|
+
W-level on purpose: a broken ``SCOPE_PROVIDER`` degrades the API (it may raise
|
|
6
|
+
per request), it must not block deploys — the trap keeps capturing mail either
|
|
7
|
+
way. IDs:
|
|
8
|
+
|
|
9
|
+
- ``stapel_mailtrap.W001`` — ``SCOPE_PROVIDER`` dotted path fails to import.
|
|
10
|
+
- ``stapel_mailtrap.W002`` — ``SCOPE_PROVIDER`` resolves to something that is
|
|
11
|
+
not a ``ScopeProvider`` subclass.
|
|
12
|
+
"""
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import inspect
|
|
16
|
+
|
|
17
|
+
from django.core import checks
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@checks.register("stapel_mailtrap")
|
|
21
|
+
def check_scope_provider(app_configs, **kwargs):
|
|
22
|
+
from .conf import mailtrap_settings
|
|
23
|
+
from .scope import ScopeProvider
|
|
24
|
+
|
|
25
|
+
try:
|
|
26
|
+
provider = mailtrap_settings.SCOPE_PROVIDER
|
|
27
|
+
except ImportError as exc:
|
|
28
|
+
return [
|
|
29
|
+
checks.Warning(
|
|
30
|
+
f"STAPEL_MAILTRAP['SCOPE_PROVIDER'] cannot be imported: {exc}",
|
|
31
|
+
hint=(
|
|
32
|
+
"Fix the dotted path or install the missing dependency; "
|
|
33
|
+
"the Mail API will fail to scope until it resolves."
|
|
34
|
+
),
|
|
35
|
+
id="stapel_mailtrap.W001",
|
|
36
|
+
)
|
|
37
|
+
]
|
|
38
|
+
if not (inspect.isclass(provider) and issubclass(provider, ScopeProvider)):
|
|
39
|
+
return [
|
|
40
|
+
checks.Warning(
|
|
41
|
+
f"STAPEL_MAILTRAP['SCOPE_PROVIDER'] resolves to {provider!r}, "
|
|
42
|
+
"which is not a stapel_mailtrap.scope.ScopeProvider subclass.",
|
|
43
|
+
hint="Implement the ScopeProvider seam (see MODULE.md).",
|
|
44
|
+
id="stapel_mailtrap.W002",
|
|
45
|
+
)
|
|
46
|
+
]
|
|
47
|
+
return []
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
__all__ = ["check_scope_provider"]
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Settings namespace for stapel-mailtrap.
|
|
2
|
+
|
|
3
|
+
All configuration is read through ``mailtrap_settings`` (lazily, at call
|
|
4
|
+
time) — never via module-level ``os.getenv`` (values would freeze at import,
|
|
5
|
+
docs/library-standard.md §3.1). Resolution order per key:
|
|
6
|
+
``settings.STAPEL_MAILTRAP`` dict -> flat Django setting of the same name ->
|
|
7
|
+
environment variable -> default below.
|
|
8
|
+
|
|
9
|
+
Dotted-path keys listed in ``import_strings`` are resolved with
|
|
10
|
+
``import_string`` — the fork-free escape hatch for swappable behavior.
|
|
11
|
+
"""
|
|
12
|
+
from stapel_core.conf import AppSettings
|
|
13
|
+
|
|
14
|
+
mailtrap_settings = AppSettings(
|
|
15
|
+
"STAPEL_MAILTRAP",
|
|
16
|
+
defaults={
|
|
17
|
+
# Dotted path to a stapel_mailtrap.scope.ScopeProvider subclass —
|
|
18
|
+
# the multi-tenant seam (single strategy, REPLACE semantics). The
|
|
19
|
+
# default is a single global scope (every mail gets scope_key="").
|
|
20
|
+
"SCOPE_PROVIDER": "stapel_mailtrap.scope.DefaultScopeProvider",
|
|
21
|
+
# Retention: hard cap on stored messages. The retention sweep
|
|
22
|
+
# (services.purge_expired / the purge_trapped_emails command / the
|
|
23
|
+
# Celery task) deletes the oldest rows beyond this many. 0 disables
|
|
24
|
+
# the count cap.
|
|
25
|
+
"MAX_EMAILS": 1000,
|
|
26
|
+
# Retention: delete messages older than this many days. 0 disables
|
|
27
|
+
# the age cap.
|
|
28
|
+
"TTL_DAYS": 30,
|
|
29
|
+
# Store rendered HTML/text bodies on the row. A host that only needs
|
|
30
|
+
# the envelope (to/from/subject) for a lighter footprint can set this
|
|
31
|
+
# False; bodies are then stored empty.
|
|
32
|
+
"STORE_BODY": True,
|
|
33
|
+
},
|
|
34
|
+
import_strings=("SCOPE_PROVIDER",),
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
__all__ = ["mailtrap_settings"]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
def pytest_configure(config):
|
|
2
|
+
from django.conf import settings
|
|
3
|
+
|
|
4
|
+
if not settings.configured:
|
|
5
|
+
settings.configure(
|
|
6
|
+
SECRET_KEY="test-secret-key-not-for-production",
|
|
7
|
+
INSTALLED_APPS=[
|
|
8
|
+
"django.contrib.contenttypes",
|
|
9
|
+
"django.contrib.auth",
|
|
10
|
+
"django.contrib.sessions",
|
|
11
|
+
"django.contrib.admin",
|
|
12
|
+
"django.contrib.messages",
|
|
13
|
+
"stapel_core.django.users",
|
|
14
|
+
"rest_framework",
|
|
15
|
+
"stapel_mailtrap",
|
|
16
|
+
],
|
|
17
|
+
AUTH_USER_MODEL="users.User",
|
|
18
|
+
DATABASES={
|
|
19
|
+
"default": {
|
|
20
|
+
"ENGINE": "django.db.backends.sqlite3",
|
|
21
|
+
"NAME": ":memory:",
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
|
|
25
|
+
DEFAULT_FROM_EMAIL="noreply@example.com",
|
|
26
|
+
USE_TZ=True,
|
|
27
|
+
ROOT_URLCONF="stapel_mailtrap.tests.urls",
|
|
28
|
+
CACHES={
|
|
29
|
+
"default": {
|
|
30
|
+
"BACKEND": "django.core.cache.backends.locmem.LocMemCache",
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
# Synchronous in-process comm with schema validation ON, so the
|
|
34
|
+
# committed contract in schemas/emits/ is enforced by the tests.
|
|
35
|
+
STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
|
|
36
|
+
STAPEL_COMM={
|
|
37
|
+
"OUTBOX_ENABLED": False,
|
|
38
|
+
"ACTION_TRANSPORT": "inprocess",
|
|
39
|
+
"VALIDATE_SCHEMAS": True,
|
|
40
|
+
},
|
|
41
|
+
MIGRATION_MODULES={
|
|
42
|
+
"users": None,
|
|
43
|
+
},
|
|
44
|
+
)
|
|
45
|
+
import django
|
|
46
|
+
|
|
47
|
+
django.setup()
|
|
48
|
+
|
|
49
|
+
from stapel_core.comm.schemas import autoload_schemas
|
|
50
|
+
|
|
51
|
+
autoload_schemas()
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
import pytest # noqa: E402
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@pytest.fixture
|
|
58
|
+
def api_client():
|
|
59
|
+
from rest_framework.test import APIClient
|
|
60
|
+
|
|
61
|
+
return APIClient()
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""Dataclass DTOs — the API models of stapel-mailtrap (never ORM instances)."""
|
|
2
|
+
from dataclasses import dataclass, field
|
|
3
|
+
from typing import List
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
@dataclass
|
|
7
|
+
class TrappedEmailListItem:
|
|
8
|
+
"""A trapped email in the list view (envelope, no bodies).
|
|
9
|
+
|
|
10
|
+
Attributes:
|
|
11
|
+
id: Message id (UUID).
|
|
12
|
+
to_email: Recipient address.
|
|
13
|
+
from_email: Sender address.
|
|
14
|
+
subject: Subject line.
|
|
15
|
+
scope_key: Opaque host scope (workspace/org/project/tenant).
|
|
16
|
+
attachment_count: Number of attachments (metadata only).
|
|
17
|
+
created_at: Capture time (tz-aware ISO 8601).
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
id: str
|
|
21
|
+
to_email: str
|
|
22
|
+
from_email: str
|
|
23
|
+
subject: str
|
|
24
|
+
scope_key: str
|
|
25
|
+
attachment_count: int
|
|
26
|
+
created_at: str
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass
|
|
30
|
+
class TrappedEmailDetail:
|
|
31
|
+
"""A trapped email in the detail view (full bodies + attachment metadata).
|
|
32
|
+
|
|
33
|
+
Attributes:
|
|
34
|
+
id: Message id (UUID).
|
|
35
|
+
to_email: Recipient address.
|
|
36
|
+
from_email: Sender address.
|
|
37
|
+
subject: Subject line.
|
|
38
|
+
body_html: Rendered HTML body (empty when STORE_BODY is off).
|
|
39
|
+
body_text: Plain-text body (empty when STORE_BODY is off).
|
|
40
|
+
attachments: Attachment metadata dicts (filename/content_type/size).
|
|
41
|
+
headers: Header snapshot.
|
|
42
|
+
scope_key: Opaque host scope.
|
|
43
|
+
created_at: Capture time (tz-aware ISO 8601).
|
|
44
|
+
"""
|
|
45
|
+
|
|
46
|
+
id: str
|
|
47
|
+
to_email: str
|
|
48
|
+
from_email: str
|
|
49
|
+
subject: str
|
|
50
|
+
body_html: str
|
|
51
|
+
body_text: str
|
|
52
|
+
attachments: List[dict] = field(default_factory=list)
|
|
53
|
+
headers: dict = field(default_factory=dict)
|
|
54
|
+
scope_key: str = ""
|
|
55
|
+
created_at: str = ""
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""i18n error keys of stapel-mailtrap.
|
|
2
|
+
|
|
3
|
+
Only ``error.<status>.<slug>`` keys leave this package — human-readable
|
|
4
|
+
strings are translations, never literals in responses
|
|
5
|
+
(docs/library-standard.md §3.6).
|
|
6
|
+
"""
|
|
7
|
+
from stapel_core.django.api.errors import register_service_errors
|
|
8
|
+
|
|
9
|
+
ERR_404_EMAIL_NOT_FOUND = "error.404.mailtrap_email_not_found"
|
|
10
|
+
|
|
11
|
+
STAPEL_MAILTRAP_ERRORS = {
|
|
12
|
+
ERR_404_EMAIL_NOT_FOUND: "Trapped email not found",
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
register_service_errors(STAPEL_MAILTRAP_ERRORS)
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"ERR_404_EMAIL_NOT_FOUND",
|
|
19
|
+
"STAPEL_MAILTRAP_ERRORS",
|
|
20
|
+
]
|
|
File without changes
|
|
File without changes
|