neuronos-capabilities-lib 0.0.2__py3-none-any.whl
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.
- neuronos_capabilities/AuthManager/__init__.py +42 -0
- neuronos_capabilities/AuthManager/adapters/__init__.py +3 -0
- neuronos_capabilities/AuthManager/adapters/clerk_adapter.py +87 -0
- neuronos_capabilities/AuthManager/auth_manager.py +237 -0
- neuronos_capabilities/AuthManager/config/__init__.py +3 -0
- neuronos_capabilities/AuthManager/config/auth_config.py +106 -0
- neuronos_capabilities/AuthManager/examples/usage.py +56 -0
- neuronos_capabilities/AuthManager/exceptions/__init__.py +13 -0
- neuronos_capabilities/AuthManager/exceptions/auth_exceptions.py +23 -0
- neuronos_capabilities/AuthManager/ports/__init__.py +3 -0
- neuronos_capabilities/AuthManager/ports/auth_port.py +92 -0
- neuronos_capabilities/AuthManager/tests/__init__.py +1 -0
- neuronos_capabilities/AuthManager/tests/test_clock_skew.py +178 -0
- neuronos_capabilities/NotificationsManager/README.md +75 -0
- neuronos_capabilities/NotificationsManager/__init__.py +37 -0
- neuronos_capabilities/NotificationsManager/adapters/__init__.py +7 -0
- neuronos_capabilities/NotificationsManager/adapters/aws.py +146 -0
- neuronos_capabilities/NotificationsManager/adapters/console.py +30 -0
- neuronos_capabilities/NotificationsManager/adapters/memory.py +143 -0
- neuronos_capabilities/NotificationsManager/adapters/postgres.py +214 -0
- neuronos_capabilities/NotificationsManager/adapters/templates.py +73 -0
- neuronos_capabilities/NotificationsManager/artifact.yaml +64 -0
- neuronos_capabilities/NotificationsManager/config/__init__.py +3 -0
- neuronos_capabilities/NotificationsManager/config/notifications_config.py +123 -0
- neuronos_capabilities/NotificationsManager/entrypoints/__init__.py +1 -0
- neuronos_capabilities/NotificationsManager/entrypoints/events.py +36 -0
- neuronos_capabilities/NotificationsManager/entrypoints/sender.py +22 -0
- neuronos_capabilities/NotificationsManager/exceptions/__init__.py +19 -0
- neuronos_capabilities/NotificationsManager/exceptions/notifications_exceptions.py +41 -0
- neuronos_capabilities/NotificationsManager/models.py +88 -0
- neuronos_capabilities/NotificationsManager/notifications_manager.py +605 -0
- neuronos_capabilities/NotificationsManager/ports/__init__.py +110 -0
- neuronos_capabilities/NotificationsManager/tests/__init__.py +0 -0
- neuronos_capabilities/NotificationsManager/tests/test_aws_adapters.py +93 -0
- neuronos_capabilities/NotificationsManager/tests/test_notifications_manager.py +198 -0
- neuronos_capabilities/S3Manager/__init__.py +55 -0
- neuronos_capabilities/S3Manager/adapters/__init__.py +3 -0
- neuronos_capabilities/S3Manager/adapters/aws_adapter.py +400 -0
- neuronos_capabilities/S3Manager/artifact.yaml +52 -0
- neuronos_capabilities/S3Manager/config/__init__.py +3 -0
- neuronos_capabilities/S3Manager/config/s3_config.py +91 -0
- neuronos_capabilities/S3Manager/examples/usage.py +86 -0
- neuronos_capabilities/S3Manager/exceptions/__init__.py +21 -0
- neuronos_capabilities/S3Manager/exceptions/s3_exceptions.py +43 -0
- neuronos_capabilities/S3Manager/ports/__init__.py +3 -0
- neuronos_capabilities/S3Manager/ports/s3_port.py +499 -0
- neuronos_capabilities/S3Manager/s3_manager.py +332 -0
- neuronos_capabilities/S3Manager/tests/__init__.py +1 -0
- neuronos_capabilities/SQLManager/__init__.py +53 -0
- neuronos_capabilities/SQLManager/adapters/__init__.py +0 -0
- neuronos_capabilities/SQLManager/adapters/postgres_adapter.py +893 -0
- neuronos_capabilities/SQLManager/artifact.yaml +52 -0
- neuronos_capabilities/SQLManager/config/__init__.py +0 -0
- neuronos_capabilities/SQLManager/config/sql_config.py +175 -0
- neuronos_capabilities/SQLManager/examples/testing_library_execution.py +167 -0
- neuronos_capabilities/SQLManager/exceptions/__init__.py +0 -0
- neuronos_capabilities/SQLManager/exceptions/sql_exceptions.py +117 -0
- neuronos_capabilities/SQLManager/migrations/__init__.py +0 -0
- neuronos_capabilities/SQLManager/migrations/alembic_manager.py +617 -0
- neuronos_capabilities/SQLManager/models/__init__.py +9 -0
- neuronos_capabilities/SQLManager/models/base.py +118 -0
- neuronos_capabilities/SQLManager/ports/__init__.py +0 -0
- neuronos_capabilities/SQLManager/ports/sql_port.py +940 -0
- neuronos_capabilities/SQLManager/sql_manager.py +495 -0
- neuronos_capabilities/SQLManager/tests/__init__.py +0 -0
- neuronos_capabilities/SQLManager/utils/__init__.py +0 -0
- neuronos_capabilities/SQLManager/utils/query_builder.py +238 -0
- neuronos_capabilities/SQLManager/utils/singleton.py +120 -0
- neuronos_capabilities/__init__.py +58 -0
- neuronos_capabilities/__version__.py +2 -0
- neuronos_capabilities_lib-0.0.2.dist-info/LICENSE +21 -0
- neuronos_capabilities_lib-0.0.2.dist-info/METADATA +152 -0
- neuronos_capabilities_lib-0.0.2.dist-info/RECORD +75 -0
- neuronos_capabilities_lib-0.0.2.dist-info/WHEEL +5 -0
- neuronos_capabilities_lib-0.0.2.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
"""Clock-skew tolerance on JWT verification (ClerkAdapter + AuthConfig).
|
|
2
|
+
|
|
3
|
+
The bug these pin: `_decode_token` called `jwt.decode` with no `leeway`, so PyJWT
|
|
4
|
+
rejected any token whose `iat` was even one second ahead of the host clock —
|
|
5
|
+
|
|
6
|
+
ImmatureSignatureError: The token is not yet valid (iat)
|
|
7
|
+
(PyJWT api_jwt.py: `if iat > (now + leeway)`)
|
|
8
|
+
|
|
9
|
+
The provider stamps `iat` with its own clock, so a host running slightly behind
|
|
10
|
+
failed EVERY request, and a client could not compensate: re-minting a token
|
|
11
|
+
produces a later `iat` still.
|
|
12
|
+
|
|
13
|
+
The leeway must not become a way around verification, so these tests also assert
|
|
14
|
+
that a foreign signature, a genuinely expired token and a wrong issuer are all
|
|
15
|
+
still rejected.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
import time
|
|
19
|
+
|
|
20
|
+
import jwt
|
|
21
|
+
import pytest
|
|
22
|
+
from cryptography.hazmat.primitives.asymmetric import rsa
|
|
23
|
+
|
|
24
|
+
from neuronos_capabilities.AuthManager.adapters.clerk_adapter import ClerkAdapter
|
|
25
|
+
from neuronos_capabilities.AuthManager.config.auth_config import AuthConfig
|
|
26
|
+
from neuronos_capabilities.AuthManager.exceptions.auth_exceptions import (
|
|
27
|
+
ConfigurationError,
|
|
28
|
+
TokenError,
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
JWKS_URL = "https://example.clerk.accounts.dev/.well-known/jwks.json"
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _rsa_key():
|
|
35
|
+
return rsa.generate_private_key(public_exponent=65537, key_size=2048)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _token(private_key, **overrides):
|
|
39
|
+
now = int(time.time())
|
|
40
|
+
claims = {"sub": "user_123", "org_id": "org_123", "iat": now, "exp": now + 60}
|
|
41
|
+
claims.update(overrides)
|
|
42
|
+
return jwt.encode(claims, private_key, algorithm="RS256")
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _adapter(private_key, **config_kwargs):
|
|
46
|
+
"""A ClerkAdapter whose JWKS resolves to `private_key`'s public key."""
|
|
47
|
+
adapter = ClerkAdapter(AuthConfig(jwks_url=JWKS_URL, **config_kwargs))
|
|
48
|
+
public_key = private_key.public_key()
|
|
49
|
+
|
|
50
|
+
class _FakeJWKSClient:
|
|
51
|
+
def get_signing_key_from_jwt(self, token):
|
|
52
|
+
class _SigningKey:
|
|
53
|
+
key = public_key
|
|
54
|
+
|
|
55
|
+
return _SigningKey()
|
|
56
|
+
|
|
57
|
+
adapter._jwks_client = _FakeJWKSClient()
|
|
58
|
+
return adapter
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
# ─── config ─────────────────────────────────────────────────────────────────
|
|
62
|
+
|
|
63
|
+
def test_default_leeway_is_thirty_seconds():
|
|
64
|
+
assert AuthConfig(jwks_url=JWKS_URL).leeway_seconds == 30
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def test_leeway_reads_env_var(monkeypatch):
|
|
68
|
+
monkeypatch.setenv("NEURONOS_AUTH_LEEWAY_SECONDS", "90")
|
|
69
|
+
assert AuthConfig(jwks_url=JWKS_URL).leeway_seconds == 90
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def test_explicit_zero_wins_over_env(monkeypatch):
|
|
73
|
+
"""Asking for strict clocks must not be silently overridden by the env."""
|
|
74
|
+
monkeypatch.setenv("NEURONOS_AUTH_LEEWAY_SECONDS", "90")
|
|
75
|
+
assert AuthConfig(jwks_url=JWKS_URL, leeway_seconds=0).leeway_seconds == 0
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def test_non_integer_env_var_is_a_configuration_error(monkeypatch):
|
|
79
|
+
monkeypatch.setenv("NEURONOS_AUTH_LEEWAY_SECONDS", "a-while")
|
|
80
|
+
with pytest.raises(ConfigurationError):
|
|
81
|
+
AuthConfig(jwks_url=JWKS_URL)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def test_negative_leeway_is_a_configuration_error():
|
|
85
|
+
with pytest.raises(ConfigurationError):
|
|
86
|
+
AuthConfig(jwks_url=JWKS_URL, leeway_seconds=-1)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def test_leeway_is_serialized():
|
|
90
|
+
assert AuthConfig(jwks_url=JWKS_URL, leeway_seconds=15).to_dict()[
|
|
91
|
+
"leeway_seconds"
|
|
92
|
+
] == 15
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
# ─── the bug ────────────────────────────────────────────────────────────────
|
|
96
|
+
|
|
97
|
+
def test_token_issued_one_second_in_the_future_is_accepted():
|
|
98
|
+
"""The exact production failure: host clock 1s behind the issuer."""
|
|
99
|
+
key = _rsa_key()
|
|
100
|
+
adapter = _adapter(key)
|
|
101
|
+
token = _token(key, iat=int(time.time()) + 1)
|
|
102
|
+
|
|
103
|
+
assert adapter.verify_token(token)["sub"] == "user_123"
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def test_future_iat_within_leeway_is_accepted():
|
|
107
|
+
key = _rsa_key()
|
|
108
|
+
adapter = _adapter(key, leeway_seconds=30)
|
|
109
|
+
token = _token(key, iat=int(time.time()) + 25)
|
|
110
|
+
|
|
111
|
+
assert adapter.verify_token(token)["sub"] == "user_123"
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def test_token_a_second_past_expiry_is_accepted():
|
|
115
|
+
key = _rsa_key()
|
|
116
|
+
adapter = _adapter(key)
|
|
117
|
+
now = int(time.time())
|
|
118
|
+
token = _token(key, iat=now - 61, exp=now - 1)
|
|
119
|
+
|
|
120
|
+
assert adapter.verify_token(token)["sub"] == "user_123"
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
@pytest.mark.asyncio
|
|
124
|
+
async def test_async_path_shares_the_tolerance():
|
|
125
|
+
key = _rsa_key()
|
|
126
|
+
adapter = _adapter(key)
|
|
127
|
+
token = _token(key, iat=int(time.time()) + 1)
|
|
128
|
+
|
|
129
|
+
payload = await adapter.verify_token_async(token)
|
|
130
|
+
assert payload["sub"] == "user_123"
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
# ─── the tolerance is bounded, and never bypasses verification ──────────────
|
|
134
|
+
|
|
135
|
+
def test_future_iat_beyond_leeway_is_rejected():
|
|
136
|
+
key = _rsa_key()
|
|
137
|
+
adapter = _adapter(key, leeway_seconds=30)
|
|
138
|
+
token = _token(key, iat=int(time.time()) + 3600)
|
|
139
|
+
|
|
140
|
+
with pytest.raises(TokenError):
|
|
141
|
+
adapter.verify_token(token)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def test_genuinely_expired_token_is_rejected():
|
|
145
|
+
key = _rsa_key()
|
|
146
|
+
adapter = _adapter(key, leeway_seconds=30)
|
|
147
|
+
now = int(time.time())
|
|
148
|
+
token = _token(key, iat=now - 7200, exp=now - 3600)
|
|
149
|
+
|
|
150
|
+
with pytest.raises(TokenError):
|
|
151
|
+
adapter.verify_token(token)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def test_zero_leeway_still_rejects_a_future_iat():
|
|
155
|
+
key = _rsa_key()
|
|
156
|
+
adapter = _adapter(key, leeway_seconds=0)
|
|
157
|
+
token = _token(key, iat=int(time.time()) + 5)
|
|
158
|
+
|
|
159
|
+
with pytest.raises(TokenError):
|
|
160
|
+
adapter.verify_token(token)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def test_foreign_signature_is_rejected_regardless_of_leeway():
|
|
164
|
+
"""Leeway forgives the clock, never the signature."""
|
|
165
|
+
adapter = _adapter(_rsa_key(), leeway_seconds=300)
|
|
166
|
+
token = _token(_rsa_key(), iat=int(time.time()) + 1) # signed by another key
|
|
167
|
+
|
|
168
|
+
with pytest.raises(TokenError):
|
|
169
|
+
adapter.verify_token(token)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def test_wrong_issuer_is_rejected():
|
|
173
|
+
key = _rsa_key()
|
|
174
|
+
adapter = _adapter(key, issuer="https://expected.example.com")
|
|
175
|
+
token = _token(key, iss="https://attacker.example.com")
|
|
176
|
+
|
|
177
|
+
with pytest.raises(TokenError):
|
|
178
|
+
adapter.verify_token(token)
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# NotificationsManager
|
|
2
|
+
|
|
3
|
+
In-app notices and email for any NeuronOS project. **One send path** for everything, from an
|
|
4
|
+
invitation to a campaign of 50,000:
|
|
5
|
+
|
|
6
|
+
```
|
|
7
|
+
API (NotificationsManager.publish) → Postgres (message + bell) → SQS lane (realtime | bulk, FIFO)
|
|
8
|
+
→ Lambda sender (outside the VPC) → SES
|
|
9
|
+
SES events → SNS → SQS events → Lambda events (inside the VPC) → Postgres (status, history, suppression)
|
|
10
|
+
Future sends: EventBridge Scheduler drops the built message in the lane at that minute.
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- **The API decides and records; it never sends.** Queuing takes ~20 ms; the email arrives in 1–3 s.
|
|
14
|
+
- **The sender is dumb:** it takes a built message and calls SES. No database, no business.
|
|
15
|
+
- **Retries and deduplication are SQS's.** FIFO dedup by message id; a temporary error comes back
|
|
16
|
+
after a backoff (30 s, 2 min, 10 min, 30 min); the 5th failure is recorded as `failed` and moves
|
|
17
|
+
to the DLQ. A permanent error is recorded and not retried.
|
|
18
|
+
- **Two lanes:** `realtime` (invitations, alerts) and `bulk` (newsletters, onboarding), with their
|
|
19
|
+
own queue and concurrency, so a campaign never delays an invitation.
|
|
20
|
+
|
|
21
|
+
## Use (API)
|
|
22
|
+
```python
|
|
23
|
+
from neuronos_capabilities.NotificationsManager import Catalog, EventSpec, NotificationsManager, Recipient
|
|
24
|
+
|
|
25
|
+
catalog = Catalog([
|
|
26
|
+
EventSpec("member_invited", "transactional"), # can't be turned off
|
|
27
|
+
EventSpec("usage_alert", "alerts"),
|
|
28
|
+
EventSpec("newsletter", "marketing", channels=("email",), lane="bulk"),
|
|
29
|
+
])
|
|
30
|
+
nm = NotificationsManager.from_env(catalog, db=sql_manager) # Postgres store on your SQLManager
|
|
31
|
+
nm.create_tables() # schema NOTIF_SCHEMA ("notifications")
|
|
32
|
+
|
|
33
|
+
nm.publish("member_invited", [Recipient("u1", "ana@acme.co", "Ana", "es")],
|
|
34
|
+
{"org": "Acme", "inviter": "Eva", "message": "Welcome!"}, link="https://app/accept")
|
|
35
|
+
nm.schedule("trial_ending", recipients, data, send_at=datetime(2026, 11, 1, 14, tzinfo=timezone.utc))
|
|
36
|
+
nm.cancel(message_id)
|
|
37
|
+
|
|
38
|
+
nm.inbox("u1"); nm.unread_count("u1"); nm.mark_read("u1") # the bell
|
|
39
|
+
nm.preferences("u1"); nm.set_preference("u1", "alerts", "email", False)
|
|
40
|
+
nm.unsubscribe(token) # your public one-click endpoint
|
|
41
|
+
nm.history(message_id) # the message and all its events
|
|
42
|
+
nm.resend(message_id)
|
|
43
|
+
```
|
|
44
|
+
Every method has an `_async` twin.
|
|
45
|
+
|
|
46
|
+
**Categories** (what a person can turn off): `transactional` (never), `alerts`, `activity`,
|
|
47
|
+
`product`, `marketing`. `product` and `marketing` go with the marketing SES configuration set and
|
|
48
|
+
carry `List-Unsubscribe` one-click.
|
|
49
|
+
|
|
50
|
+
## Templates
|
|
51
|
+
One Jinja file per event and locale in `NOTIF_TEMPLATE_DIR`: `<event>.<locale>.j2` with blocks
|
|
52
|
+
`title` and `inapp` (the bell), `subject`, `html` and `text` (optional: derived from the HTML). An
|
|
53
|
+
optional `_layout.<locale>.j2` wraps the HTML (`{{ content }}`). A missing locale falls back to
|
|
54
|
+
the default one. Every template gets the data plus `recipient`, `link`, `unsubscribe_url`, and
|
|
55
|
+
`count` (folded notices).
|
|
56
|
+
|
|
57
|
+
## Message status
|
|
58
|
+
`scheduled → queued → retrying → sent → delivered`, or `failed`, `bounced`, `complained`. Never
|
|
59
|
+
sent: `skipped` (turned off, no address, disabled), `suppressed`, `cancelled`. Late or repeated
|
|
60
|
+
events never move a message back. Each event is kept in `message_events`.
|
|
61
|
+
|
|
62
|
+
## Lambdas
|
|
63
|
+
Build both zips (Python 3.12, `x86_64` or `arm64`): `neuronos_capabilities/NotificationsManager/build_lambdas.sh`
|
|
64
|
+
|
|
65
|
+
| Lambda | Handler | Where | Needs |
|
|
66
|
+
|---|---|---|---|
|
|
67
|
+
| `notification-sender` | `…entrypoints.sender.handler` | Outside the VPC | SQS triggers on both lanes (partial batch response), `ses:SendEmail`, `sqs:SendMessage` to events, `sqs:ChangeMessageVisibility` on the lanes |
|
|
68
|
+
| `notification-events` | `…entrypoints.events.handler` | Inside the VPC (reaches Postgres) | SQS trigger on events; `PG_*` env vars |
|
|
69
|
+
|
|
70
|
+
## Local
|
|
71
|
+
With no queue URLs the manager uses an in-memory queue and the console channel: `publish` runs
|
|
72
|
+
the whole path right away and writes each email as an `.html` file in `NOTIF_CONSOLE_DIR`.
|
|
73
|
+
|
|
74
|
+
## Configuration
|
|
75
|
+
See `config/notifications_config.py` (`NotificationsConfig.from_env`) for every variable.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""
|
|
2
|
+
NotificationsManager — notifications capability for NeuronOS projects.
|
|
3
|
+
|
|
4
|
+
In-app notices and email (SES) through one send path: API → SQS lane (realtime | bulk) →
|
|
5
|
+
sender Lambda → SES → events (SNS → SQS) → events Lambda → Postgres. Scheduled sends with
|
|
6
|
+
EventBridge Scheduler. Per-person preferences by category, suppression of bounced and
|
|
7
|
+
complaining addresses, one-click unsubscribe.
|
|
8
|
+
|
|
9
|
+
Example:
|
|
10
|
+
from neuronos_capabilities.NotificationsManager import (
|
|
11
|
+
Catalog, EventSpec, NotificationsManager, Recipient)
|
|
12
|
+
|
|
13
|
+
catalog = Catalog([EventSpec("member_invited"), EventSpec("usage_alert", "alerts")])
|
|
14
|
+
nm = NotificationsManager.from_env(catalog, db=sql_manager)
|
|
15
|
+
nm.publish("member_invited", [Recipient("u1", "ana@acme.co", "Ana", "es")], {"org": "Acme"})
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from .config import CATEGORIES, CHANNELS, LANES, NotificationsConfig
|
|
19
|
+
from .exceptions import (
|
|
20
|
+
ChannelError,
|
|
21
|
+
ConfigurationError,
|
|
22
|
+
NotificationsError,
|
|
23
|
+
PermanentChannelError,
|
|
24
|
+
RetryableChannelError,
|
|
25
|
+
TemplateError,
|
|
26
|
+
UnknownEventError,
|
|
27
|
+
)
|
|
28
|
+
from .models import Catalog, EventSpec, Recipient, Rendered
|
|
29
|
+
from .notifications_manager import NotificationsManager
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"CATEGORIES", "CHANNELS", "LANES", "Catalog", "ChannelError", "ConfigurationError", "EventSpec",
|
|
33
|
+
"NotificationsConfig", "NotificationsError", "NotificationsManager", "PermanentChannelError", "Recipient",
|
|
34
|
+
"Rendered", "RetryableChannelError", "TemplateError", "UnknownEventError",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
__version__ = "1.0.0"
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"""Adapters. The memory and console ones load with no extra dependency; AWS (``aws``),
|
|
2
|
+
Postgres (``postgres``) and Jinja (``templates``) are imported from their modules when used."""
|
|
3
|
+
|
|
4
|
+
from .console import ConsoleChannel
|
|
5
|
+
from .memory import MemoryQueue, MemoryScheduler, MemoryStore
|
|
6
|
+
|
|
7
|
+
__all__ = ["ConsoleChannel", "MemoryQueue", "MemoryScheduler", "MemoryStore"]
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""AWS adapters: SES (email), SQS (lanes and events) and EventBridge Scheduler (future sends).
|
|
2
|
+
boto3 clients can be injected (tests, custom sessions)."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import hashlib
|
|
7
|
+
import json
|
|
8
|
+
from typing import Any, Dict, Optional
|
|
9
|
+
|
|
10
|
+
from ..config import NotificationsConfig
|
|
11
|
+
from ..exceptions import ConfigurationError, PermanentChannelError, RetryableChannelError
|
|
12
|
+
from ..ports import ChannelPort, QueuePort, SchedulerPort
|
|
13
|
+
|
|
14
|
+
#: SES errors where trying again later can work. Anything else from SES is permanent.
|
|
15
|
+
RETRYABLE_SES = {"Throttling", "ThrottlingException", "TooManyRequestsException", "LimitExceededException",
|
|
16
|
+
"SendingPausedException", "ServiceUnavailable", "InternalFailure", "InternalServiceError",
|
|
17
|
+
"RequestTimeout", "AccountSuspendedException"}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _client(service: str, config: NotificationsConfig, client=None):
|
|
21
|
+
if client is not None:
|
|
22
|
+
return client
|
|
23
|
+
import boto3
|
|
24
|
+
|
|
25
|
+
return boto3.client(service, region_name=config.region) if config.region else boto3.client(service)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _tag(v: Optional[str]) -> str:
|
|
29
|
+
# SES tag values: letters, digits, _ - and . only
|
|
30
|
+
return "".join(ch if ch.isalnum() or ch in "_-." else "_" for ch in str(v or "none"))[:256] or "none"
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def queue_arn(url: str) -> str:
|
|
34
|
+
"""https://sqs.us-east-1.amazonaws.com/123456789012/name → arn:aws:sqs:us-east-1:123456789012:name"""
|
|
35
|
+
try:
|
|
36
|
+
host, account, name = url.split("://", 1)[1].split("/")[:3]
|
|
37
|
+
region = host.split(".")[1]
|
|
38
|
+
except (IndexError, ValueError):
|
|
39
|
+
raise ConfigurationError(f"Not an SQS queue URL: {url}") from None
|
|
40
|
+
return f"arn:aws:sqs:{region}:{account}:{name}"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def group_of(key: str, groups: int = 64) -> str:
|
|
44
|
+
"""FIFO message group: one person's messages keep their order, different people go in parallel."""
|
|
45
|
+
return f"g{int(hashlib.sha1(key.encode()).hexdigest(), 16) % groups}"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class SESChannel(ChannelPort):
|
|
49
|
+
def __init__(self, config: NotificationsConfig, client=None):
|
|
50
|
+
self.config = config
|
|
51
|
+
self.client = _client("sesv2", config, client)
|
|
52
|
+
|
|
53
|
+
def send(self, message: Dict[str, Any]) -> Dict[str, Any]:
|
|
54
|
+
from botocore.exceptions import BotoCoreError, ClientError
|
|
55
|
+
|
|
56
|
+
simple: Dict[str, Any] = {
|
|
57
|
+
"Subject": {"Data": message.get("subject") or "", "Charset": "UTF-8"},
|
|
58
|
+
"Body": {"Html": {"Data": message.get("html") or "", "Charset": "UTF-8"},
|
|
59
|
+
"Text": {"Data": message.get("text") or "", "Charset": "UTF-8"}},
|
|
60
|
+
}
|
|
61
|
+
headers = [{"Name": k, "Value": v} for k, v in (message.get("headers") or {}).items()]
|
|
62
|
+
if headers:
|
|
63
|
+
simple["Headers"] = headers
|
|
64
|
+
req: Dict[str, Any] = {
|
|
65
|
+
"FromEmailAddress": message.get("from") or self.config.email_from,
|
|
66
|
+
"Destination": {"ToAddresses": [message["to"]]},
|
|
67
|
+
"Content": {"Simple": simple},
|
|
68
|
+
# the tag is how SES's events find our row again (events Lambda)
|
|
69
|
+
"EmailTags": [{"Name": "message_id", "Value": _tag(message.get("id"))},
|
|
70
|
+
{"Name": "event", "Value": _tag(message.get("event"))},
|
|
71
|
+
{"Name": "category", "Value": _tag(message.get("category"))}],
|
|
72
|
+
}
|
|
73
|
+
if message.get("reply_to") or self.config.email_reply_to:
|
|
74
|
+
req["ReplyToAddresses"] = [message.get("reply_to") or self.config.email_reply_to]
|
|
75
|
+
if message.get("configuration_set"):
|
|
76
|
+
req["ConfigurationSetName"] = message["configuration_set"]
|
|
77
|
+
try:
|
|
78
|
+
out = self.client.send_email(**req)
|
|
79
|
+
except ClientError as exc:
|
|
80
|
+
err = exc.response.get("Error", {})
|
|
81
|
+
code, msg = err.get("Code", ""), err.get("Message", str(exc))
|
|
82
|
+
if code in RETRYABLE_SES or exc.response.get("ResponseMetadata", {}).get("HTTPStatusCode", 0) >= 500:
|
|
83
|
+
raise RetryableChannelError(msg, code=code) from exc
|
|
84
|
+
raise PermanentChannelError(msg, code=code) from exc
|
|
85
|
+
except BotoCoreError as exc: # network, endpoint, credentials
|
|
86
|
+
raise RetryableChannelError(str(exc), code=type(exc).__name__) from exc
|
|
87
|
+
return {"provider_id": out.get("MessageId")}
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class SQSQueue(QueuePort):
|
|
91
|
+
def __init__(self, config: NotificationsConfig, client=None):
|
|
92
|
+
self.config = config
|
|
93
|
+
self.client = _client("sqs", config, client)
|
|
94
|
+
|
|
95
|
+
def url(self, queue: str) -> str:
|
|
96
|
+
url = self.config.queue_urls.get(queue)
|
|
97
|
+
if not url:
|
|
98
|
+
raise ConfigurationError(f"No queue URL for {queue}")
|
|
99
|
+
return url
|
|
100
|
+
|
|
101
|
+
def send(self, queue, body, *, group_id=None, dedup_id=None):
|
|
102
|
+
url = self.url(queue)
|
|
103
|
+
req: Dict[str, Any] = {"QueueUrl": url, "MessageBody": json.dumps(body, default=str)}
|
|
104
|
+
if url.endswith(".fifo"):
|
|
105
|
+
req["MessageGroupId"] = group_id or "default"
|
|
106
|
+
if dedup_id:
|
|
107
|
+
req["MessageDeduplicationId"] = dedup_id[:128]
|
|
108
|
+
self.client.send_message(**req)
|
|
109
|
+
|
|
110
|
+
def retry_later(self, source_arn, receipt, delay_s):
|
|
111
|
+
# arn:aws:sqs:region:account:name → its URL
|
|
112
|
+
_, _, _, region, account, name = source_arn.split(":", 5)
|
|
113
|
+
url = next((u for u in self.config.queue_urls.values() if u.rstrip("/").endswith(f"/{account}/{name}")),
|
|
114
|
+
f"https://sqs.{region}.amazonaws.com/{account}/{name}")
|
|
115
|
+
self.client.change_message_visibility(QueueUrl=url, ReceiptHandle=receipt,
|
|
116
|
+
VisibilityTimeout=max(0, min(43200, int(delay_s))))
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
class EventBridgeScheduler(SchedulerPort):
|
|
120
|
+
def __init__(self, config: NotificationsConfig, client=None):
|
|
121
|
+
if not config.scheduler_group or not config.scheduler_role_arn:
|
|
122
|
+
raise ConfigurationError("scheduler_group and scheduler_role_arn are required for eventbridge")
|
|
123
|
+
self.config = config
|
|
124
|
+
self.client = _client("scheduler", config, client)
|
|
125
|
+
|
|
126
|
+
def create(self, name, at, queue, body, *, group_id):
|
|
127
|
+
url = self.config.queue_urls.get(queue)
|
|
128
|
+
if not url:
|
|
129
|
+
raise ConfigurationError(f"No queue URL for {queue}")
|
|
130
|
+
target: Dict[str, Any] = {"Arn": queue_arn(url), "RoleArn": self.config.scheduler_role_arn,
|
|
131
|
+
"Input": json.dumps(body, default=str)}
|
|
132
|
+
if url.endswith(".fifo"):
|
|
133
|
+
target["SqsParameters"] = {"MessageGroupId": group_id} # dedup: content-based on the queue
|
|
134
|
+
self.client.create_schedule(Name=name[:64], GroupName=self.config.scheduler_group,
|
|
135
|
+
ScheduleExpression=f"at({at.strftime('%Y-%m-%dT%H:%M:%S')})",
|
|
136
|
+
ScheduleExpressionTimezone="UTC", FlexibleTimeWindow={"Mode": "OFF"},
|
|
137
|
+
Target=target, ActionAfterCompletion="DELETE")
|
|
138
|
+
|
|
139
|
+
def delete(self, name):
|
|
140
|
+
try:
|
|
141
|
+
self.client.delete_schedule(Name=name[:64], GroupName=self.config.scheduler_group)
|
|
142
|
+
return True
|
|
143
|
+
except Exception as exc: # already fired or gone
|
|
144
|
+
if "ResourceNotFound" in type(exc).__name__ or "ResourceNotFound" in str(exc):
|
|
145
|
+
return False
|
|
146
|
+
raise
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Local email channel: writes each message as an .html file you can open, and logs it."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
import re
|
|
9
|
+
import time
|
|
10
|
+
import uuid
|
|
11
|
+
|
|
12
|
+
from ..ports import ChannelPort
|
|
13
|
+
|
|
14
|
+
logger = logging.getLogger("notifications")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class ConsoleChannel(ChannelPort):
|
|
18
|
+
def __init__(self, folder: str):
|
|
19
|
+
self.folder = folder
|
|
20
|
+
|
|
21
|
+
def send(self, message):
|
|
22
|
+
os.makedirs(self.folder, exist_ok=True)
|
|
23
|
+
pid = f"console-{uuid.uuid4().hex[:12]}"
|
|
24
|
+
safe = re.sub(r"[^A-Za-z0-9_.-]+", "_", f"{message.get('event')}-{message.get('to')}")[:120]
|
|
25
|
+
path = os.path.join(self.folder, f"{time.strftime('%Y%m%d-%H%M%S')}-{safe}.html")
|
|
26
|
+
meta = {k: message.get(k) for k in ("id", "to", "from", "subject", "event", "category", "headers")}
|
|
27
|
+
with open(path, "w", encoding="utf-8") as f:
|
|
28
|
+
f.write(f"<!-- {json.dumps(meta, default=str)} -->\n{message.get('html') or message.get('text') or ''}")
|
|
29
|
+
logger.info("notification %s → %s: %s", message.get("event"), message.get("to"), path)
|
|
30
|
+
return {"provider_id": pid, "path": path, "local": True}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
"""In-memory queue, scheduler and store: tests and local runs without AWS or a database."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import copy
|
|
6
|
+
import threading
|
|
7
|
+
import uuid
|
|
8
|
+
from datetime import datetime
|
|
9
|
+
from typing import Any, Dict, List, Optional
|
|
10
|
+
|
|
11
|
+
from ..ports import QueuePort, SchedulerPort, StorePort
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class MemoryQueue(QueuePort):
|
|
15
|
+
def __init__(self):
|
|
16
|
+
self.messages: Dict[str, List[Dict[str, Any]]] = {}
|
|
17
|
+
self.retries: List[tuple] = []
|
|
18
|
+
self._dedup: set = set()
|
|
19
|
+
self._lock = threading.Lock()
|
|
20
|
+
|
|
21
|
+
def send(self, queue, body, *, group_id=None, dedup_id=None):
|
|
22
|
+
with self._lock:
|
|
23
|
+
if dedup_id and (queue, dedup_id) in self._dedup: # like an SQS FIFO queue
|
|
24
|
+
return
|
|
25
|
+
if dedup_id:
|
|
26
|
+
self._dedup.add((queue, dedup_id))
|
|
27
|
+
self.messages.setdefault(queue, []).append({"body": copy.deepcopy(body), "group_id": group_id,
|
|
28
|
+
"dedup_id": dedup_id})
|
|
29
|
+
|
|
30
|
+
def retry_later(self, source_arn, receipt, delay_s):
|
|
31
|
+
self.retries.append((source_arn, receipt, delay_s))
|
|
32
|
+
|
|
33
|
+
def take(self, queue: str) -> List[Dict[str, Any]]:
|
|
34
|
+
"""Test helper: the bodies waiting in a queue (removed)."""
|
|
35
|
+
with self._lock:
|
|
36
|
+
out = [m["body"] for m in self.messages.get(queue, [])]
|
|
37
|
+
self.messages[queue] = []
|
|
38
|
+
return out
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class MemoryScheduler(SchedulerPort):
|
|
42
|
+
def __init__(self):
|
|
43
|
+
self.schedules: Dict[str, Dict[str, Any]] = {}
|
|
44
|
+
|
|
45
|
+
def create(self, name, at, queue, body, *, group_id):
|
|
46
|
+
self.schedules[name] = {"at": at, "queue": queue, "body": copy.deepcopy(body), "group_id": group_id}
|
|
47
|
+
|
|
48
|
+
def delete(self, name):
|
|
49
|
+
return self.schedules.pop(name, None) is not None
|
|
50
|
+
|
|
51
|
+
def fire_due(self, now: datetime, queue: QueuePort) -> int:
|
|
52
|
+
"""Local/test helper: what EventBridge does at the right minute."""
|
|
53
|
+
due = [n for n, s in self.schedules.items() if s["at"] <= now]
|
|
54
|
+
for n in due:
|
|
55
|
+
s = self.schedules.pop(n)
|
|
56
|
+
queue.send(s["queue"], s["body"], group_id=s["group_id"], dedup_id=s["body"].get("id"))
|
|
57
|
+
return len(due)
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class MemoryStore(StorePort):
|
|
61
|
+
def __init__(self):
|
|
62
|
+
self.messages: Dict[str, Dict[str, Any]] = {}
|
|
63
|
+
self.events: Dict[str, Dict[str, Any]] = {}
|
|
64
|
+
self.inbox_items: Dict[str, Dict[str, Any]] = {}
|
|
65
|
+
self.prefs: Dict[tuple, bool] = {}
|
|
66
|
+
self.suppressed: Dict[str, Dict[str, Any]] = {}
|
|
67
|
+
self._lock = threading.RLock()
|
|
68
|
+
|
|
69
|
+
# ── messages ──
|
|
70
|
+
def create_message(self, row):
|
|
71
|
+
with self._lock:
|
|
72
|
+
row = {"id": row.get("id") or str(uuid.uuid4()), "attempts": 0, "provider_id": None, "error": None, **row}
|
|
73
|
+
self.messages[row["id"]] = row
|
|
74
|
+
return dict(row)
|
|
75
|
+
|
|
76
|
+
def get_message(self, message_id):
|
|
77
|
+
r = self.messages.get(message_id)
|
|
78
|
+
return dict(r) if r else None
|
|
79
|
+
|
|
80
|
+
def update_message(self, message_id, **fields):
|
|
81
|
+
with self._lock:
|
|
82
|
+
if message_id in self.messages:
|
|
83
|
+
self.messages[message_id].update(fields)
|
|
84
|
+
|
|
85
|
+
def add_event(self, event):
|
|
86
|
+
with self._lock:
|
|
87
|
+
if event["key"] in self.events:
|
|
88
|
+
return False
|
|
89
|
+
self.events[event["key"]] = dict(event)
|
|
90
|
+
return True
|
|
91
|
+
|
|
92
|
+
def events_of(self, message_id):
|
|
93
|
+
return sorted((dict(e) for e in self.events.values() if e["message_id"] == message_id), key=lambda e: e["at"])
|
|
94
|
+
|
|
95
|
+
def messages_of(self, recipient_id, limit=50):
|
|
96
|
+
rows = [dict(m) for m in self.messages.values() if m["recipient_id"] == recipient_id]
|
|
97
|
+
return sorted(rows, key=lambda m: m["created_at"], reverse=True)[:limit]
|
|
98
|
+
|
|
99
|
+
# ── inbox ──
|
|
100
|
+
def create_inbox(self, item):
|
|
101
|
+
with self._lock:
|
|
102
|
+
item = {"id": str(uuid.uuid4()), "agg_count": 1, "read_at": None, **item}
|
|
103
|
+
self.inbox_items[item["id"]] = item
|
|
104
|
+
return dict(item)
|
|
105
|
+
|
|
106
|
+
def open_inbox_aggregate(self, recipient_id, aggregation_key, since):
|
|
107
|
+
return next((dict(i) for i in self.inbox_items.values()
|
|
108
|
+
if i["recipient_id"] == recipient_id and i.get("aggregation_key") == aggregation_key
|
|
109
|
+
and i["read_at"] is None and i["created_at"] >= since), None)
|
|
110
|
+
|
|
111
|
+
def update_inbox(self, item_id, **fields):
|
|
112
|
+
with self._lock:
|
|
113
|
+
self.inbox_items[item_id].update(fields)
|
|
114
|
+
|
|
115
|
+
def inbox(self, recipient_id, limit=20, before: Optional[datetime] = None):
|
|
116
|
+
items = [i for i in self.inbox_items.values()
|
|
117
|
+
if i["recipient_id"] == recipient_id and (before is None or i["created_at"] < before)]
|
|
118
|
+
return [dict(i) for i in sorted(items, key=lambda i: i["created_at"], reverse=True)[:limit]]
|
|
119
|
+
|
|
120
|
+
def unread_count(self, recipient_id):
|
|
121
|
+
return sum(1 for i in self.inbox_items.values() if i["recipient_id"] == recipient_id and i["read_at"] is None)
|
|
122
|
+
|
|
123
|
+
def mark_read(self, recipient_id, ids, at):
|
|
124
|
+
n = 0
|
|
125
|
+
for i in self.inbox_items.values():
|
|
126
|
+
if i["recipient_id"] == recipient_id and i["read_at"] is None and (ids is None or i["id"] in ids):
|
|
127
|
+
i["read_at"] = at
|
|
128
|
+
n += 1
|
|
129
|
+
return n
|
|
130
|
+
|
|
131
|
+
# ── preferences and suppression ──
|
|
132
|
+
def preferences(self, recipient_id):
|
|
133
|
+
return {key: v for (rid, key), v in self.prefs.items() if rid == recipient_id}
|
|
134
|
+
|
|
135
|
+
def set_preference(self, recipient_id, category, channel, enabled):
|
|
136
|
+
self.prefs[(recipient_id, f"{category}:{channel}")] = bool(enabled)
|
|
137
|
+
|
|
138
|
+
def is_suppressed(self, address):
|
|
139
|
+
return bool(address) and address.lower() in self.suppressed
|
|
140
|
+
|
|
141
|
+
def suppress(self, address, channel, reason):
|
|
142
|
+
if address:
|
|
143
|
+
self.suppressed.setdefault(address.lower(), {"channel": channel, "reason": reason})
|