From bc7936034ce81397fbe1df16e70eb7b2d9ffd4a1 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Tue, 10 Nov 2026 15:28:24 +0100 Subject: [PATCH] Contact: mail via achtergrondservice met claim, backoff en maximum (CMS-U5) Co-Authored-By: Claude Sonnet 5.5 --- .../contact-forms-module/aidlc-state.md | 2 +- .../features/contact-forms-module/audit.md | 12 + .../cms-u5-contact-mail/code/summary.md | 23 + .../construction/phase-1-handoff.md | 5 + ...ms-u5-contact-mail-code-generation-plan.md | 16 +- openapi/slpsoftware.v1.json | 13 + .../Email/MailTemplateRenderer.cs | 49 +- src/SlpModularCms.Core/Email/MailTypes.cs | 14 +- .../Email/SmtpEmailSender.cs | 8 + .../ContactMailTests.cs | 422 ++++++++++++++++++ .../ContactNoPersonalDataInLogsTests.cs | 13 - .../ContactSubmissionServiceTests.cs | 42 +- .../Pipeline/ContactAdminPipelineTests.cs | 4 +- .../Pipeline/ContactMailPipelineTests.cs | 142 ++++++ .../SubmissionHarness.cs | 6 +- .../Config/ContactOptions.cs | 32 ++ .../ContactModule.cs | 5 +- .../Data/ContactDbContext.cs | 4 + ...0261110141855_ContactMailClaim.Designer.cs | 135 ++++++ .../20261110141855_ContactMailClaim.cs | 22 + .../ContactDbContextModelSnapshot.cs | 1 + .../Models/ContactAdminModels.cs | 5 +- .../Repositories/ContactRepository.cs | 22 + .../Services/ContactAdminService.cs | 39 +- .../Services/ContactMailSender.cs | 97 ++++ .../Services/ContactMailService.cs | 159 +++++++ .../Services/ContactSeams.cs | 56 ++- .../Services/ContactSubmissionService.cs | 32 +- 28 files changed, 1273 insertions(+), 107 deletions(-) create mode 100644 aidlc-docs/features/contact-forms-module/construction/cms-u5-contact-mail/code/summary.md create mode 100644 src/SlpModularCms.Modules.Contact.Tests/ContactMailTests.cs create mode 100644 src/SlpModularCms.Modules.Contact.Tests/Pipeline/ContactMailPipelineTests.cs create mode 100644 src/SlpModularCms.Modules.Contact/Migrations/20261110141855_ContactMailClaim.Designer.cs create mode 100644 src/SlpModularCms.Modules.Contact/Migrations/20261110141855_ContactMailClaim.cs create mode 100644 src/SlpModularCms.Modules.Contact/Services/ContactMailSender.cs create mode 100644 src/SlpModularCms.Modules.Contact/Services/ContactMailService.cs diff --git a/aidlc-docs/features/contact-forms-module/aidlc-state.md b/aidlc-docs/features/contact-forms-module/aidlc-state.md index de74d2f..3e0cabc 100644 --- a/aidlc-docs/features/contact-forms-module/aidlc-state.md +++ b/aidlc-docs/features/contact-forms-module/aidlc-state.md @@ -5,7 +5,7 @@ - **Feature Slug**: contact-forms-module - **Project Type**: Brownfield - **Start Date**: 2026-11-09 -- **Current Stage**: PHASE 2 - CMS-U7 built and committed; next CMS-U5, then CMS-U6 +- **Current Stage**: PHASE 2 - CMS-U7 and CMS-U5 built and committed; next CMS-U6, then plan CMS-U8 - **Branch**: feature/contact-forms-module (worktree ..SlpModularCms-contact-forms, from master d9cc539; main checkout stays on feature/identity-email-notifications — never switch it) ## Workspace State diff --git a/aidlc-docs/features/contact-forms-module/audit.md b/aidlc-docs/features/contact-forms-module/audit.md index dd29407..fa43bb4 100644 --- a/aidlc-docs/features/contact-forms-module/audit.md +++ b/aidlc-docs/features/contact-forms-module/audit.md @@ -143,3 +143,15 @@ **Context**: Phase 2 planning. --- + +## CMS-U5 contact mail built + +**Timestamp**: 2026-11-10 + +**User Input**: Approval of plan CMS-U5 incl. the three additive shared mail changes (via Redesign - SLS). + +**AI Response**: Store + signal + background sender with claim, backoff and maximum; real sender; admin resend and detail; tests (unit and pipeline with a capturing sender); OpenAPI regenerated; all test projects green. + +**Context**: Phase 2, one commit. + +--- diff --git a/aidlc-docs/features/contact-forms-module/construction/cms-u5-contact-mail/code/summary.md b/aidlc-docs/features/contact-forms-module/construction/cms-u5-contact-mail/code/summary.md new file mode 100644 index 0000000..d80dfdc --- /dev/null +++ b/aidlc-docs/features/contact-forms-module/construction/cms-u5-contact-mail/code/summary.md @@ -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. diff --git a/aidlc-docs/features/contact-forms-module/construction/phase-1-handoff.md b/aidlc-docs/features/contact-forms-module/construction/phase-1-handoff.md index 1cd8103..4921fca 100644 --- a/aidlc-docs/features/contact-forms-module/construction/phase-1-handoff.md +++ b/aidlc-docs/features/contact-forms-module/construction/phase-1-handoff.md @@ -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`. diff --git a/aidlc-docs/features/contact-forms-module/construction/plans/cms-u5-contact-mail-code-generation-plan.md b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u5-contact-mail-code-generation-plan.md index af1121c..0e89893 100644 --- a/aidlc-docs/features/contact-forms-module/construction/plans/cms-u5-contact-mail-code-generation-plan.md +++ b/aidlc-docs/features/contact-forms-module/construction/plans/cms-u5-contact-mail-code-generation-plan.md @@ -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. diff --git a/openapi/slpsoftware.v1.json b/openapi/slpsoftware.v1.json index e9ae40b..f4dbeb3 100644 --- a/openapi/slpsoftware.v1.json +++ b/openapi/slpsoftware.v1.json @@ -138,6 +138,13 @@ "name": { "type": "string" }, + "nextMailAttemptAt": { + "format": "date-time", + "type": [ + "null", + "string" + ] + }, "receivedAt": { "format": "date-time", "type": "string" @@ -306,6 +313,12 @@ "string" ] }, + "mailError": { + "type": [ + "null", + "string" + ] + }, "mailStatus": { "type": "string" }, diff --git a/src/SlpModularCms.Core/Email/MailTemplateRenderer.cs b/src/SlpModularCms.Core/Email/MailTemplateRenderer.cs index cbeab6f..cd602a0 100644 --- a/src/SlpModularCms.Core/Email/MailTemplateRenderer.cs +++ b/src/SlpModularCms.Core/Email/MailTemplateRenderer.cs @@ -101,6 +101,19 @@ public sealed class MailTemplateRenderer : IMailTemplateRenderer "An administrator has changed your role at {0} to: {1}.", null, "Think this is a mistake? Please contact the administrator.", "This message was sent automatically by {0}.") + }, + // The details (name, e-mail address, subject, message) come from MailModel.Details; nothing the visitor + // typed is part of the subject, which stays fixed text. + [MailKind.ContactMessage] = new() + { + ["nl"] = new("Nieuw bericht via {0}", "Nieuw bericht via het contactformulier", + "Er is een bericht verstuurd via het contactformulier van {0}.", + null, "Je kunt direct op deze mail antwoorden: het antwoord gaat naar het e-mailadres van de afzender.", + "Deze mail is automatisch verstuurd door {0}."), + ["en"] = new("New message via {0}", "New message from the contact form", + "A message was sent through the contact form of {0}.", + null, "You can reply to this message directly: the reply goes to the sender's e-mail address.", + "This message was sent automatically by {0}.") } }; @@ -135,7 +148,7 @@ public sealed class MailTemplateRenderer : IMailTemplateRenderer var hasAction = t.Button is not null && !string.IsNullOrEmpty(model.ActionUrl); return new RenderedMail(subject, BuildHtml(model, site, colour, greeting, heading, intro, hasAction ? t.Button : null, note, footer), - BuildText(greeting, heading, intro, hasAction ? model.ActionUrl : null, note, footer)); + BuildText(greeting, heading, intro, hasAction ? model.ActionUrl : null, note, footer, model.Details)); } private static string RoleName(string lang, string? key) => @@ -224,6 +237,7 @@ public sealed class MailTemplateRenderer : IMailTemplateRenderer sb.Append($"

{E(heading)}

"); if (greeting is not null) sb.Append($"

{E(greeting)}

"); sb.Append($"

{E(intro)}

"); + AppendDetails(sb, model.Details); if (button is not null && !string.IsNullOrEmpty(model.ActionUrl)) { // 'Bulletproof' button: a table cell with bgcolor + style, a visible border, and the link filling the cell. @@ -240,12 +254,43 @@ public sealed class MailTemplateRenderer : IMailTemplateRenderer return sb.ToString(); } - private static string BuildText(string? greeting, string heading, string intro, string? url, string? note, string footer) + /// + /// Labelled values (label on its own line in the muted colour, value below it). Only classes the dark block already + /// overrides carry an inline colour (.mail-muted, .mail-rule); the values inherit the card's text colour, so they + /// read in light and dark. Every value is HTML-encoded; line breaks in a value become <br>. + /// + private static void AppendDetails(StringBuilder sb, IReadOnlyList? details) + { + if (details is null || details.Count == 0) return; + + sb.Append(""); + foreach (var detail in details) + { + var value = E(detail.Value.Replace("\r\n", "\n").Replace('\r', '\n')).Replace("\n", "
"); + sb.Append(""); + } + sb.Append("
"); + sb.Append($"
{E(detail.Label)}
"); + sb.Append($"
{value}
"); + sb.Append("
"); + } + + private static string BuildText( + string? greeting, string heading, string intro, string? url, string? note, string footer, + IReadOnlyList? details = null) { var sb = new StringBuilder(); sb.AppendLine(heading).AppendLine(); if (greeting is not null) sb.AppendLine(greeting).AppendLine(); sb.AppendLine(intro).AppendLine(); + if (details is { Count: > 0 }) + { + foreach (var detail in details) + { + // Plain text: a label line, then the value as written (the message keeps its own line breaks). + sb.Append(detail.Label).AppendLine(":").AppendLine(detail.Value.Replace("\r\n", "\n").Replace('\r', '\n')).AppendLine(); + } + } if (url is not null) sb.AppendLine(url).AppendLine(); if (note is not null) sb.AppendLine(note).AppendLine(); sb.AppendLine("--").AppendLine(footer); diff --git a/src/SlpModularCms.Core/Email/MailTypes.cs b/src/SlpModularCms.Core/Email/MailTypes.cs index 7ad0759..f9a899e 100644 --- a/src/SlpModularCms.Core/Email/MailTypes.cs +++ b/src/SlpModularCms.Core/Email/MailTypes.cs @@ -33,7 +33,9 @@ public sealed record OutgoingMail( string HtmlBody, string? TextBody = null, string? FromAddress = null, - string? FromName = null); + string? FromName = null, + string? ReplyToAddress = null, + string? ReplyToName = null); public enum MailKind { @@ -42,9 +44,14 @@ public enum MailKind PasswordReset, AccountDeactivated, AccountReactivated, - RoleChanged + RoleChanged, + /// A visitor's message from the contact form, mailed to the site owner (details + Reply-To). + ContactMessage } +/// One labelled value in the details block of a mail (for example the visitor's name). Always encoded in HTML. +public sealed record MailDetail(string Label, string Value); + /// Values the template needs. carries the role key for . public sealed record MailModel( string SiteName, @@ -54,7 +61,8 @@ public sealed record MailModel( string? Detail = null, string? LogoUrl = null, string? BrandColor = null, - string? LogoDarkUrl = null); + string? LogoDarkUrl = null, + IReadOnlyList? Details = null); public sealed record RenderedMail(string Subject, string Html, string Text); diff --git a/src/SlpModularCms.Core/Email/SmtpEmailSender.cs b/src/SlpModularCms.Core/Email/SmtpEmailSender.cs index f24012e..56b06b2 100644 --- a/src/SlpModularCms.Core/Email/SmtpEmailSender.cs +++ b/src/SlpModularCms.Core/Email/SmtpEmailSender.cs @@ -40,6 +40,14 @@ public sealed class SmtpEmailSender(IOptions options, ILogger new ContactMailOptions().BackoffAfter(attempts).Should().Be(TimeSpan.FromMinutes(minutes)); + + [Fact] + public void TheDefaults_AreSixAttempts() + => new ContactMailOptions().MaxAttempts.Should().Be(6); +} + +public class ContactMailSenderTests +{ + private const string Visitor = "jan@example.nl"; + + private sealed class Rig + { + public IEmailSender Email { get; } = Substitute.For(); + public IMailAvailability Availability { get; } = Substitute.For(); + public ContactOptions Contact { get; } = new() { Enabled = true, RecipientEmail = "owner@example.org" }; + public CapturingLoggerProvider Logs { get; } = new(); + public OutgoingMail? Sent; + + public Rig() + { + Availability.IsEnabled.Returns(true); + Email.SendAsync(Arg.Any(), Arg.Any()).Returns(call => + { + Sent = call.Arg(); + return MailSendResult.Ok; + }); + } + + public ContactMailSender Build(string language = "nl") + { + var languages = Substitute.For(); + languages.Resolve(Arg.Any()).Returns(language); + var settings = Substitute.For(); + settings.GetEffectiveSenderAsync(Arg.Any()).Returns(("noreply@example.org", "De Site")); + return new ContactMailSender( + Email, new MailTemplateRenderer(), languages, settings, Availability, + Options.Create(new EmailOptions()), Options.Create(new AppMailOptions { PublicBaseUrl = "https://example.org" }), + Options.Create(Contact), LoggerFactory.Create(b => b.AddProvider(Logs)).CreateLogger()); + } + } + + private static ContactMessage Message(string name = "Jan Jansen", string subject = "website", string body = "Hallo\nwereld") + => new() { Id = Guid.NewGuid(), SiteId = "s", Name = name, Email = Visitor, Subject = subject, Message = body }; + + [Fact] + public async Task ASend_GoesToTheRecipient_FromTheSiteSender_WithTheVisitorAsReplyTo() + { + var rig = new Rig(); + + var result = await rig.Build().SendAsync(Message(), CancellationToken.None); + + result.Outcome.Should().Be(ContactMailOutcome.Sent); + rig.Sent!.ToAddress.Should().Be("owner@example.org"); + rig.Sent.FromAddress.Should().Be("noreply@example.org"); + rig.Sent.ReplyToAddress.Should().Be(Visitor); + rig.Sent.ReplyToName.Should().Be("Jan Jansen"); + } + + [Fact] + public async Task TheSubject_NeverContainsAnythingTheVisitorTyped() + { + var rig = new Rig(); + + await rig.Build().SendAsync(Message(name: "ZXQ-Name", subject: "ZXQ-Subject\r\nBcc: x@y.z", body: "ZXQ-Body"), CancellationToken.None); + + rig.Sent!.Subject.Should().NotContain("ZXQ").And.NotContain("\r").And.NotContain("\n"); + rig.Sent.Subject.Should().Be("Nieuw bericht via De Site"); + } + + [Fact] + public async Task TheBody_EncodesHtml_AndKeepsLineBreaks_AndHasATextPart() + { + var rig = new Rig(); + + await rig.Build().SendAsync(Message(body: "\nregel2"), CancellationToken.None); + + rig.Sent!.HtmlBody.Should().NotContain("