Contact: mail via achtergrondservice met claim, backoff en maximum (CMS-U5)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 15:28:24 +01:00
co-authored by Claude Sonnet 5.5
parent 728fc08db8
commit bc7936034c
28 changed files with 1273 additions and 107 deletions
@@ -0,0 +1,23 @@
# CMS-U5 — Contact mail + retry (summary)
## Behaviour
- A submission only stores the message (status `new`, mail `pending`, `NextMailAttemptAt = now`) and signals the background sender. The visitor never waits for SMTP.
- `ContactMailService` (BackgroundService) wakes on the signal and every `Contact:Mail:SweepSeconds`; it picks unread (`new`) messages with mail `pending`/`failed`, fewer than `MaxAttempts` attempts and a due `NextMailAttemptAt`, oldest first, `BatchSize` at a time.
- Claim: `NextMailAttemptAt` is a concurrency token; the sender first sets it to now + `ClaimMinutes` (whole seconds, the column is `datetime`), a second instance fails to save and skips the message.
- Failure: `failed` + short error code, attempts + 1, next attempt after 5 min / 15 min / 1 h / 6 h / 24 h; after `MaxAttempts` (6) no automatic attempt; an administrator can still resend (ignores backoff and maximum).
- Mail off or no valid recipient: nothing attempted or counted; the reason (`disabled` / `recipient_not_configured`) is shown as `mailError`.
- Spam, read, archived messages are never auto-mailed. Module disabled: the service does nothing and never touches the database.
- Mail: To = `Contact:RecipientEmail`, From = site sender, Reply-To = visitor (address validated, name only if valid), fixed subject "Nieuw bericht via {site}" / "New message via {site}"; details (name, e-mail, subject, message) HTML-encoded, line breaks kept, text part included. Logs: message id and short codes only.
## Configuration (env-only for the address)
- `Contact__RecipientEmail` (environment variable; no address in repo config).
- `Contact:Mail:SweepSeconds` 120, `MaxAttempts` 6, `BackoffMinutes` [5,15,60,360,1440], `ClaimMinutes` 5, `BatchSize` 20.
## API
- Detail has `nextMailAttemptAt`; resend result has `mailError`. Migration `ContactMailClaim` (schema unchanged, concurrency token only). OpenAPI regenerated.
## Shared files changed (additive only)
`Core/Email/MailTypes.cs`, `MailTemplateRenderer.cs`, `SmtpEmailSender.cs` (+66/-5). Existing Core tests untouched: 625 green.
## Found by the real-database pipeline test
`datetime` drops fractions, which made the claim's concurrency check fail on the outcome save; claim time is now truncated to whole seconds.
@@ -107,3 +107,8 @@ CMS switch (not configuration): table `ContactSettings`, `PUT /contact-settings`
## 6. Rebase result (2026-11-10)
Rebased onto `origin/master` `e671078` (merge of PR #11: identity-email-notifications + andreaslop-site-hosting). Conflicts: `aidlc-docs/active-features.md` (kept master's table, appended our row), `AvailabilityMiddleware` (kept their `CheckAdmin` / expired-token 401 behaviour, our marker block before it), `AddCmsRateLimiting.OnRejected` (kept their Retry-After logic for sliding windows, added the `60 s` fallback for policies without a wait and the problem+json body), `SlpModularCms.sln` (took master's, re-added the two Contact projects). No EF snapshot conflict (own contexts). Checklist steps 1 and 2 are DONE: `ContactRateLimitPartition.KeyFor` now returns `ClientPartitionKey.For(context)` and its test asserts different buckets per address. Still open: step 3 (`ForwardedHeaders:KnownProxies` per host), step 5 (`Contact:Enabled=true`), step 6 (CMS switch). `GET /System/capabilities` now carries `[PublicSiteEndpoint]` (never 503; separate commit). The pipeline tests for the management routes log in with a real user (the host validates every access token against its user and security stamp).
## 7. CMS-U5 additions (contact mail)
- Env var `Contact__RecipientEmail` (SLP: environment only, like ASF). Optional `Contact__Mail__SweepSeconds|MaxAttempts|ClaimMinutes|BatchSize`, `Contact__Mail__BackoffMinutes__0..n`.
- Mail itself needs the host's normal `Email:*` configuration; without it messages stay `pending` with `mailError: "disabled"`.
- Detail: `nextMailAttemptAt`; resend: `mailError`. New migration `ContactMailClaim`.
@@ -18,14 +18,14 @@ Phase 2, on the rebased branch (base `origin/master` `e671078`). Inputs: contrac
8. The Andrea host gets the Contact module reference only when SLS/Bryan decide the ASF website uses the form (out of scope here); the module works there unchanged.
## Steps
- [ ] **Step 1 — Shared mail code, additive**: `MailKind.ContactMessage`, catalog texts (nl/en), `MailModel.Details`, `OutgoingMail.ReplyTo*`, `SmtpEmailSender` reply-to; renderer tests (see below). Show the diff of the three shared files to SLS before moving on.
- [ ] **Step 2 — Contact mail sender**: `ContactMailSender : IContactMailSender` (replaces the no-op; renders, builds the Reply-To, calls `IEmailSender`, maps the `MailSendResult` to `Sent/Failed` + code; returns `Skipped` for "disabled"/"no recipient").
- [ ] **Step 3 — Pipeline change**: `ContactSubmissionService` stops sending inline, sets `NextMailAttemptAt`, signals `IContactMailSignal`.
- [ ] **Step 4 — Retry/background service** `ContactMailService` (claim, backoff, max attempts, signal, disabled handling) and options `Contact:Mail:*` (`SweepSeconds`, `MaxAttempts`, `BackoffMinutes`), `Contact:RecipientEmail`.
- [ ] **Step 5 — Admin**: detail gets `nextMailAttemptAt`; resend uses the real sender; OpenAPI regenerated.
- [ ] **Step 6 — Tests**: renderer (every visitor value HTML-encoded, newline handling, subject contains no visitor text, nl/en, dark-mode classes present, text part); sender with a fake `IEmailSender` (To/From/Reply-To/subject, control characters in the display name never reach a header, result codes mapped, disabled and missing recipient give `Skipped`); retry service (only due rows, spam never, backoff schedule exactly as configured, max attempts, claim prevents a second sender, signal wakes it, disabled mail leaves rows untouched and uncounted, resend ignores backoff); submission service no longer calls the sender and signals; no personal data in any log (extends the existing log-capture tests); **pipeline** on the real host with a capturing `IEmailSender` registered in the test host: submit -> mail captured within seconds and row `sent`; failing sender -> `failed` + code + next attempt; resend `mailed:true`; mail disabled -> rows pending.
- [ ] **Step 7 — Verification (automatic)**: build; all test projects incl. pipeline tests on a temporary MariaDB (removed afterwards). Optionally one manual end-to-end against smtp4dev if it is available locally (not a gate).
- [ ] **Step 8 — Docs/commit**: summary (config keys, behaviour table, shared-file diff), update `phase-1-handoff.md` routes/keys; one commit; no push.
- [x] **Step 1 — Shared mail code, additive**: `MailKind.ContactMessage`, catalog texts (nl/en), `MailModel.Details`, `OutgoingMail.ReplyTo*`, `SmtpEmailSender` reply-to; renderer tests (see below). Show the diff of the three shared files to SLS before moving on.
- [x] **Step 2 — Contact mail sender**: `ContactMailSender : IContactMailSender` (replaces the no-op; renders, builds the Reply-To, calls `IEmailSender`, maps the `MailSendResult` to `Sent/Failed` + code; returns `Skipped` for "disabled"/"no recipient").
- [x] **Step 3 — Pipeline change**: `ContactSubmissionService` stops sending inline, sets `NextMailAttemptAt`, signals `IContactMailSignal`.
- [x] **Step 4 — Retry/background service** `ContactMailService` (claim, backoff, max attempts, signal, disabled handling) and options `Contact:Mail:*` (`SweepSeconds`, `MaxAttempts`, `BackoffMinutes`), `Contact:RecipientEmail`.
- [x] **Step 5 — Admin**: detail gets `nextMailAttemptAt`; resend uses the real sender; OpenAPI regenerated.
- [x] **Step 6 — Tests**: renderer (every visitor value HTML-encoded, newline handling, subject contains no visitor text, nl/en, dark-mode classes present, text part); sender with a fake `IEmailSender` (To/From/Reply-To/subject, control characters in the display name never reach a header, result codes mapped, disabled and missing recipient give `Skipped`); retry service (only due rows, spam never, backoff schedule exactly as configured, max attempts, claim prevents a second sender, signal wakes it, disabled mail leaves rows untouched and uncounted, resend ignores backoff); submission service no longer calls the sender and signals; no personal data in any log (extends the existing log-capture tests); **pipeline** on the real host with a capturing `IEmailSender` registered in the test host: submit -> mail captured within seconds and row `sent`; failing sender -> `failed` + code + next attempt; resend `mailed:true`; mail disabled -> rows pending.
- [x] **Step 7 — Verification (automatic)**: build; all test projects incl. pipeline tests on a temporary MariaDB (removed afterwards). Optionally one manual end-to-end against smtp4dev if it is available locally (not a gate).
- [x] **Step 8 — Docs/commit**: summary (config keys, behaviour table, shared-file diff), update `phase-1-handoff.md` routes/keys; one commit; no push.
## Explicitly NOT touched
Existing mail kinds and their texts/behaviour, identity mail flow, `IMailAvailability`, site settings, SMTP credentials handling, the public routes' contract (still `202` immediately), the availability gate.