Contactformulier-module, banners, thema's, taalbestanden en CI-herstructurering #15

Merged
Sluijsens merged 84 commits from feature/contact-forms-module into master 2026-11-16 11:51:12 +01:00
28 changed files with 1273 additions and 107 deletions
Showing only changes of commit bc7936034c - Show all commits
@@ -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
@@ -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.
---
@@ -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.
+13
View File
@@ -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"
},
@@ -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($"<h1 class=\"mail-accent\" style=\"margin:0 0 16px 0;font-size:22px;color:{colour};\">{E(heading)}</h1>");
if (greeting is not null) sb.Append($"<p style=\"margin:0 0 12px 0;\">{E(greeting)}</p>");
sb.Append($"<p style=\"margin:0 0 24px 0;\">{E(intro)}</p>");
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)
/// <summary>
/// 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 &lt;br&gt;.
/// </summary>
private static void AppendDetails(StringBuilder sb, IReadOnlyList<MailDetail>? details)
{
if (details is null || details.Count == 0) return;
sb.Append("<table role=\"presentation\" width=\"100%\" cellpadding=\"0\" cellspacing=\"0\" style=\"margin:0 0 24px 0;\">");
foreach (var detail in details)
{
var value = E(detail.Value.Replace("\r\n", "\n").Replace('\r', '\n')).Replace("\n", "<br>");
sb.Append("<tr><td class=\"mail-rule\" style=\"padding:10px 0;border-top:1px solid #e5e7eb;\">");
sb.Append($"<div class=\"mail-muted\" style=\"font-size:12px;color:#6b7280;margin:0 0 2px 0;\">{E(detail.Label)}</div>");
sb.Append($"<div style=\"font-size:15px;line-height:1.5;word-break:break-word;\">{value}</div>");
sb.Append("</td></tr>");
}
sb.Append("</table>");
}
private static string BuildText(
string? greeting, string heading, string intro, string? url, string? note, string footer,
IReadOnlyList<MailDetail>? 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);
+11 -3
View File
@@ -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,
/// <summary>A visitor's message from the contact form, mailed to the site owner (details + Reply-To).</summary>
ContactMessage
}
/// <summary>One labelled value in the details block of a mail (for example the visitor's name). Always encoded in HTML.</summary>
public sealed record MailDetail(string Label, string Value);
/// <summary>Values the template needs. <see cref="Detail"/> carries the role key for <see cref="MailKind.RoleChanged"/>.</summary>
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<MailDetail>? Details = null);
public sealed record RenderedMail(string Subject, string Html, string Text);
@@ -40,6 +40,14 @@ public sealed class SmtpEmailSender(IOptions<EmailOptions> options, ILogger<Smtp
var message = new MimeMessage();
message.From.Add(new MailboxAddress(fromName, fromAddress));
message.To.Add(MailboxAddress.Parse(mail.ToAddress));
// Optional Reply-To (the contact form: the visitor). Same allowlist rule as every other address; a value that
// does not pass is left out rather than failing the mail, and a display name with control characters is dropped.
if (EmailAddressRules.IsValidAddress(mail.ReplyToAddress))
{
var replyName = mail.ReplyToName is { } n && EmailAddressRules.IsValidDisplayName(n) ? n.Trim() : null;
message.ReplyTo.Add(new MailboxAddress(replyName, mail.ReplyToAddress));
}
message.Subject = mail.Subject;
message.Body = new BodyBuilder { HtmlBody = mail.HtmlBody, TextBody = mail.TextBody }.ToMessageBody();
@@ -0,0 +1,422 @@
using FluentAssertions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Time.Testing;
using NSubstitute;
using NSubstitute.ExceptionExtensions;
using SlpModularCms.Core.Email;
using SlpModularCms.Core.SiteSettings;
using SlpModularCms.Modules.Contact.Config;
using SlpModularCms.Modules.Contact.Data;
using SlpModularCms.Modules.Contact.Data.Entities;
using SlpModularCms.Modules.Contact.Repositories;
using SlpModularCms.Modules.Contact.Services;
namespace SlpModularCms.Modules.Contact.Tests;
public class ContactMailOptionsTests
{
[Theory]
[InlineData(1, 5)]
[InlineData(2, 15)]
[InlineData(3, 60)]
[InlineData(4, 360)]
[InlineData(5, 1440)]
[InlineData(9, 1440)]
public void TheBackoff_IsFiveMinutesFifteenMinutesOneHourSixHoursTwentyFourHours(int attempts, int minutes)
=> 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<IEmailSender>();
public IMailAvailability Availability { get; } = Substitute.For<IMailAvailability>();
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<OutgoingMail>(), Arg.Any<CancellationToken>()).Returns(call =>
{
Sent = call.Arg<OutgoingMail>();
return MailSendResult.Ok;
});
}
public ContactMailSender Build(string language = "nl")
{
var languages = Substitute.For<ILanguageResolver>();
languages.Resolve(Arg.Any<string?>()).Returns(language);
var settings = Substitute.For<ISiteSettingsService>();
settings.GetEffectiveSenderAsync(Arg.Any<CancellationToken>()).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<ContactMailSender>());
}
}
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: "<script>alert(1)</script>\nregel2"), CancellationToken.None);
rig.Sent!.HtmlBody.Should().NotContain("<script>").And.Contain("&lt;script&gt;").And.Contain("<br");
rig.Sent.TextBody.Should().Contain("regel2").And.Contain("Naam:");
}
[Fact]
public async Task English_UsesEnglishLabelsAndSubject()
{
var rig = new Rig();
await rig.Build("en").SendAsync(Message(), CancellationToken.None);
rig.Sent!.Subject.Should().Be("New message via De Site");
rig.Sent.TextBody.Should().Contain("Name:").And.Contain("Message:");
}
[Fact]
public async Task AControlCharacterInTheVisitorName_NeverReachesAHeader()
{
var rig = new Rig();
await rig.Build().SendAsync(Message(name: "Jan\r\nBcc: evil@example.com"), CancellationToken.None);
rig.Sent!.ReplyToName.Should().BeNull("an invalid display name is not used; the address alone is");
rig.Sent.ReplyToAddress.Should().Be(Visitor);
}
[Fact]
public async Task AFailure_IsReturnedAsItsShortCode_AndLogsNoPersonalData()
{
var rig = new Rig();
rig.Email.SendAsync(Arg.Any<OutgoingMail>(), Arg.Any<CancellationToken>()).Returns(MailSendResult.Fail(MailSendResult.AuthFailed));
var result = await rig.Build().SendAsync(Message(name: "ZXQ-Name", body: "ZXQ-Body"), CancellationToken.None);
result.Should().Be(new ContactMailResult(ContactMailOutcome.Failed, "auth_failed"));
rig.Logs.Messages.Should().NotContain(m => m.Contains("ZXQ") || m.Contains(Visitor) || m.Contains("owner@example.org"));
}
[Fact]
public async Task AnExceptionFromTheSender_BecomesUnknown_LoggedByTypeOnly()
{
var rig = new Rig();
rig.Email.SendAsync(Arg.Any<OutgoingMail>(), Arg.Any<CancellationToken>())
.ThrowsAsync(new InvalidOperationException($"cannot deliver to {Visitor}"));
var result = await rig.Build().SendAsync(Message(), CancellationToken.None);
result.Should().Be(new ContactMailResult(ContactMailOutcome.Failed, "unknown"));
rig.Logs.Messages.Should().NotContain(m => m.Contains(Visitor));
rig.Logs.Messages.Should().Contain(m => m.Contains(nameof(InvalidOperationException)));
}
[Fact]
public async Task WhenMailIsOff_NothingIsSent_AndTheReasonIsDisabled()
{
var rig = new Rig();
rig.Availability.IsEnabled.Returns(false);
var sut = rig.Build();
var result = await sut.SendAsync(Message(), CancellationToken.None);
result.Should().Be(new ContactMailResult(ContactMailOutcome.Skipped, "disabled"));
sut.NotReadyReason().Should().Be("disabled");
await rig.Email.DidNotReceive().SendAsync(Arg.Any<OutgoingMail>(), Arg.Any<CancellationToken>());
}
[Theory]
[InlineData(null)]
[InlineData("")]
[InlineData("not-an-address")]
public async Task WithoutAValidRecipient_NothingIsSent(string? recipient)
{
var rig = new Rig();
rig.Contact.RecipientEmail = recipient;
var sut = rig.Build();
var result = await sut.SendAsync(Message(), CancellationToken.None);
result.Should().Be(new ContactMailResult(ContactMailOutcome.Skipped, "recipient_not_configured"));
await rig.Email.DidNotReceive().SendAsync(Arg.Any<OutgoingMail>(), Arg.Any<CancellationToken>());
}
}
public class ContactMailServiceTests : IDisposable
{
private static readonly DateTimeOffset Now = new(2026, 11, 9, 12, 0, 0, TimeSpan.Zero);
private readonly string _dbName = Guid.NewGuid().ToString();
private readonly FakeTimeProvider _time = new(Now);
private readonly ContactOptions _options = new() { Enabled = true, SiteId = "site-a" };
private readonly IContactMailSender _sender = Substitute.For<IContactMailSender>();
private readonly CapturingLoggerProvider _logs = new();
private readonly ServiceProvider _provider;
public ContactMailServiceTests()
{
_sender.NotReadyReason().Returns((string?)null);
_sender.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>()).Returns(ContactMailOutcome.Sent);
var services = new ServiceCollection();
services.AddDbContext<ContactDbContext>(o => o.UseInMemoryDatabase(_dbName));
services.AddScoped<IContactRepository, ContactRepository>();
services.AddScoped(_ => _sender);
_provider = services.BuildServiceProvider();
}
public void Dispose() => _provider.Dispose();
private ContactMailService Sut() => new(
_provider.GetRequiredService<IServiceScopeFactory>(), new ContactMailSignal(), Options.Create(_options), _time,
LoggerFactory.Create(b => b.AddProvider(_logs)).CreateLogger<ContactMailService>());
private Guid Add(
ContactMessageStatus status = ContactMessageStatus.New, ContactMailStatus mail = ContactMailStatus.Pending,
int attempts = 0, DateTimeOffset? next = null, int minutesAgo = 0)
{
using var scope = _provider.CreateScope();
var db = scope.ServiceProvider.GetRequiredService<ContactDbContext>();
var message = new ContactMessage
{
Id = Guid.NewGuid(), SiteId = "site-a", ReceivedAt = Now.AddMinutes(-minutesAgo), Name = "Jan", Email = "jan@example.nl",
Subject = "s", Message = "m", Status = status, MailStatus = mail, MailAttempts = attempts,
NextMailAttemptAt = next ?? Now, RetentionUntil = Now.AddMonths(12),
};
db.ContactMessages.Add(message);
db.SaveChanges();
return message.Id;
}
private ContactMessage Get(Guid id)
{
using var scope = _provider.CreateScope();
return scope.ServiceProvider.GetRequiredService<ContactDbContext>().ContactMessages.AsNoTracking().Single(m => m.Id == id);
}
[Fact]
public async Task ADueMessage_IsSent_AndRecorded()
{
var id = Add();
(await Sut().SweepAsync(CancellationToken.None)).Should().Be(1);
var m = Get(id);
m.MailStatus.Should().Be(ContactMailStatus.Sent);
m.MailAttempts.Should().Be(1);
m.NextMailAttemptAt.Should().BeNull();
m.MailError.Should().BeNull();
}
[Fact]
public async Task SpamReadArchivedAndAlreadySentMessages_AreNeverAutoMailed()
{
Add(ContactMessageStatus.Spam, ContactMailStatus.NotApplicable);
Add(ContactMessageStatus.Read);
Add(ContactMessageStatus.Archived);
Add(mail: ContactMailStatus.Sent);
(await Sut().SweepAsync(CancellationToken.None)).Should().Be(0);
await _sender.DidNotReceive().SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>());
}
[Fact]
public async Task AFailure_IsRetriedWithTheBackoffSchedule_UntilTheMaximum_ThenNoMore()
{
_sender.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>())
.Returns(new ContactMailResult(ContactMailOutcome.Failed, "rejected"));
var id = Add();
var sut = Sut();
var expected = new[] { 5, 15, 60, 360, 1440 };
for (var attempt = 1; attempt <= 5; attempt++)
{
(await sut.SweepAsync(CancellationToken.None)).Should().Be(1);
var m = Get(id);
m.MailAttempts.Should().Be(attempt);
m.MailStatus.Should().Be(ContactMailStatus.Failed);
m.MailError.Should().Be("rejected");
m.NextMailAttemptAt.Should().Be(_time.GetUtcNow() + TimeSpan.FromMinutes(expected[attempt - 1]));
// Before the backoff has passed nothing is attempted.
(await sut.SweepAsync(CancellationToken.None)).Should().Be(0);
_time.Advance(TimeSpan.FromMinutes(expected[attempt - 1]));
}
(await sut.SweepAsync(CancellationToken.None)).Should().Be(1); // sixth and last
var last = Get(id);
last.MailAttempts.Should().Be(6);
last.NextMailAttemptAt.Should().BeNull();
_time.Advance(TimeSpan.FromDays(30));
(await sut.SweepAsync(CancellationToken.None)).Should().Be(0);
}
[Fact]
public async Task ARecoveryAfterAFailure_EndsAsSent()
{
_sender.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>())
.Returns(new ContactMailResult(ContactMailOutcome.Failed, "timeout"), new ContactMailResult(ContactMailOutcome.Sent));
var id = Add();
var sut = Sut();
await sut.SweepAsync(CancellationToken.None);
_time.Advance(TimeSpan.FromMinutes(5));
await sut.SweepAsync(CancellationToken.None);
var m = Get(id);
m.MailStatus.Should().Be(ContactMailStatus.Sent);
m.MailAttempts.Should().Be(2);
m.MailError.Should().BeNull();
}
[Fact]
public async Task WhenMailCannotBeSent_NothingIsAttemptedOrCounted_AndTheReasonIsShown()
{
_sender.NotReadyReason().Returns("disabled");
var id = Add();
(await Sut().SweepAsync(CancellationToken.None)).Should().Be(0);
var m = Get(id);
m.MailAttempts.Should().Be(0);
m.MailStatus.Should().Be(ContactMailStatus.Pending);
m.MailError.Should().Be("disabled");
await _sender.DidNotReceive().SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>());
// Once mail works again the same message goes out without any lost attempts.
_sender.NotReadyReason().Returns((string?)null);
(await Sut().SweepAsync(CancellationToken.None)).Should().Be(1);
Get(id).MailAttempts.Should().Be(1);
}
[Fact]
public async Task ASkippedSend_CountsNothing()
{
_sender.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>())
.Returns(new ContactMailResult(ContactMailOutcome.Skipped, "disabled"));
var id = Add();
await Sut().SweepAsync(CancellationToken.None);
var m = Get(id);
m.MailAttempts.Should().Be(0);
m.MailStatus.Should().Be(ContactMailStatus.Pending);
}
[Fact]
public async Task WhenTheModuleIsDisabled_NothingIsDone()
{
_options.Enabled = false;
Add();
(await Sut().SweepAsync(CancellationToken.None)).Should().Be(0);
await _sender.DidNotReceive().SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>());
}
[Fact]
public async Task TheOldestMessagesGoFirst_AndTheBatchIsLimited()
{
_options.Mail.BatchSize = 2;
var oldest = Add(minutesAgo: 30);
var middle = Add(minutesAgo: 20);
var newest = Add(minutesAgo: 10);
(await Sut().SweepAsync(CancellationToken.None)).Should().Be(2);
Get(oldest).MailStatus.Should().Be(ContactMailStatus.Sent);
Get(middle).MailStatus.Should().Be(ContactMailStatus.Sent);
Get(newest).MailStatus.Should().Be(ContactMailStatus.Pending);
}
[Fact]
public async Task AMessageClaimedByAnotherInstance_IsSkipped()
{
var id = Add();
// The other instance claims the message between our read and our claim.
_sender.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>()).Returns(ContactMailOutcome.Sent);
using var scope = _provider.CreateScope();
var real = scope.ServiceProvider.GetRequiredService<IContactRepository>();
var due = await real.GetDueForMailAsync("site-a", Now, 6, 20, CancellationToken.None);
due.Should().HaveCount(1);
using (var other = _provider.CreateScope())
{
var db = other.ServiceProvider.GetRequiredService<ContactDbContext>();
var row = db.ContactMessages.Single(m => m.Id == id);
row.NextMailAttemptAt = Now.AddMinutes(5);
db.SaveChanges();
}
due[0].NextMailAttemptAt = Now.AddMinutes(5);
var act = async () => await real.SaveChangesAsync(CancellationToken.None);
await act.Should().ThrowAsync<DbUpdateConcurrencyException>();
}
[Fact]
public async Task TheLogs_CarryNoPersonalData()
{
_sender.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>())
.ThrowsAsync(new InvalidOperationException("cannot deliver to jan@example.nl"));
Add();
await Sut().SweepAsync(CancellationToken.None);
_logs.Messages.Should().NotContain(m => m.Contains("jan@example.nl"));
_logs.Messages.Should().Contain(m => m.Contains(nameof(InvalidOperationException)));
}
[Fact]
public async Task TheSignal_WakesTheWait_AndTheTimeoutAlsoReturns()
{
var signal = new ContactMailSignal();
signal.Notify();
await signal.WaitAsync(TimeSpan.FromSeconds(30), CancellationToken.None);
await signal.WaitAsync(TimeSpan.FromMilliseconds(50), CancellationToken.None);
}
}
@@ -54,19 +54,6 @@ public class ContactNoPersonalDataInLogsTests
AssertClean(h, key, token, "ZXQ-Honeypot");
}
[Fact]
public async Task AMailFailureWithPersonalDataInItsMessage_IsLoggedByTypeOnly()
{
using var h = new SubmissionHarness();
h.Mail.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>())
.ThrowsAsync(new InvalidOperationException($"cannot deliver to {MarkerEmail}: {MarkerMessage}"));
await h.Submit(Marked(h.MatureToken()));
AssertClean(h);
h.Logs.Messages.Should().Contain(m => m.Contains(nameof(InvalidOperationException)));
}
[Fact]
public async Task ADatabaseFailureWithPersonalDataInItsMessage_DoesNotLeakThroughTheServiceLogs()
{
@@ -45,47 +45,29 @@ public class ContactSubmissionServiceTests
}
[Fact]
public async Task TheMailSender_IsCalledAfterTheMessageIsStored_AndOnlyForGenuineMessages()
public async Task AGenuineMessage_IsStoredPendingAndDueAtOnce_AndTheMailSenderIsSignalled_NeverCalledInline()
{
using var h = new SubmissionHarness();
var storedWhenMailWasCalled = false;
h.Mail.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>()).Returns(call =>
{
storedWhenMailWasCalled = h.Db.ContactMessages.AsNoTracking().Any(m => m.Id == call.Arg<ContactMessage>().Id);
return ContactMailOutcome.Skipped;
});
await h.Submit(SubmissionHarness.Request(h.MatureToken()));
await h.Submit(SubmissionHarness.Request(h.MatureToken(), hp: "bot"));
storedWhenMailWasCalled.Should().BeTrue();
await h.Mail.Received(1).SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>());
var genuine = (await Messages(h)).Single(m => m.Status == ContactMessageStatus.New);
genuine.MailStatus.Should().Be(ContactMailStatus.Pending);
genuine.MailAttempts.Should().Be(0);
genuine.NextMailAttemptAt.Should().Be(genuine.ReceivedAt);
h.Signal.Received(1).Notify();
}
[Fact]
public async Task ASentMail_IsRecorded_WithOneAttempt()
public async Task ASpamMessage_IsNeverDueForMail()
{
using var h = new SubmissionHarness();
h.Mail.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>()).Returns(ContactMailOutcome.Sent);
await h.Submit(SubmissionHarness.Request(h.MatureToken()));
await h.Submit(SubmissionHarness.Request(h.MatureToken(), hp: "bot"));
var stored = (await Messages(h)).Single();
stored.MailStatus.Should().Be(ContactMailStatus.Sent);
stored.MailAttempts.Should().Be(1);
}
[Fact]
public async Task AMailFailure_NeverFailsTheRequest_AndLeavesTheMessageStored()
{
using var h = new SubmissionHarness();
h.Mail.SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>())
.ThrowsAsync(new InvalidOperationException("smtp said no to jan@example.nl"));
var result = await h.Submit(SubmissionHarness.Request(h.MatureToken()));
result.Should().BeOfType<SubmissionResult.Received>();
(await Messages(h)).Single().MailStatus.Should().Be(ContactMailStatus.Pending);
(await Messages(h)).Single().NextMailAttemptAt.Should().BeNull();
h.Signal.DidNotReceive().Notify();
}
[Fact]
@@ -100,7 +82,7 @@ public class ContactSubmissionServiceTests
var stored = (await Messages(h)).Single(m => m.Status == ContactMessageStatus.Spam);
stored.MailStatus.Should().Be(ContactMailStatus.NotApplicable);
stored.RetentionUntil.Should().Be(stored.ReceivedAt.AddDays(30));
await h.Mail.Received(1).SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>());
h.Signal.Received(1).Notify();
}
[Fact]
@@ -178,7 +160,7 @@ public class ContactSubmissionServiceTests
second.Should().Be(first);
(await Messages(h)).Should().HaveCount(1);
await h.Mail.Received(1).SendAsync(Arg.Any<ContactMessage>(), Arg.Any<CancellationToken>());
h.Signal.Received(1).Notify();
}
[Fact]
@@ -247,11 +247,11 @@ public class ContactAdminPipelineTests(ClosedCmsSwitchContactHostFactory factory
(await patch.Content.ReadAsStringAsync()).Should().Contain("\"status\":\"read\"");
(await admin.PatchAsync($"{Messages}/{first}", Jwt.Json("""{"status":"spam"}"""))).StatusCode.Should().Be(HttpStatusCode.BadRequest);
// Resend: spam is refused, a regular message answers (no mail sender yet: mailed=false).
// Resend: spam is refused, a regular message answers (mail not configured on this host: mailed=false, reason shown).
(await admin.PostAsync($"{Messages}/{spam}/resend", null)).StatusCode.Should().Be(HttpStatusCode.Conflict);
var resend = await admin.PostAsync($"{Messages}/{second}/resend", null);
resend.StatusCode.Should().Be(HttpStatusCode.OK);
(await resend.Content.ReadAsStringAsync()).Should().Be("""{"mailStatus":"pending","mailAttempts":0,"mailed":false}""");
(await resend.Content.ReadAsStringAsync()).Should().Be("""{"mailStatus":"pending","mailAttempts":0,"mailed":false,"mailError":"disabled"}""");
// Not spam after all: now in the default list.
(await admin.PatchAsync($"{Messages}/{spam}", Jwt.Json("""{"status":"archived"}"""))).StatusCode.Should().Be(HttpStatusCode.OK);
@@ -0,0 +1,142 @@
using System.Collections.Concurrent;
using System.Net;
using FluentAssertions;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.TestHost;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using NSubstitute;
using SlpModularCms.Core.Email;
using SlpModularCms.Modules.Contact.Data.Entities;
namespace SlpModularCms.Modules.Contact.Tests.Pipeline;
/// <summary>An IEmailSender that records every mail and can be told to fail.</summary>
public sealed class CapturingEmailSender : IEmailSender
{
public ConcurrentQueue<OutgoingMail> Sent { get; } = new();
public volatile string? FailWith;
public Task<MailSendResult> SendAsync(OutgoingMail mail, CancellationToken cancellationToken = default)
{
if (FailWith is { } code)
{
return Task.FromResult(MailSendResult.Fail(code));
}
Sent.Enqueue(mail);
return Task.FromResult(MailSendResult.Ok);
}
}
/// <summary>The real host with the contact form open, mail "on" and a capturing sender instead of SMTP.</summary>
public sealed class MailContactHostFactory() : ContactHostFactory(new()
{
["Contact:Enabled"] = "true",
["Contact:SiteId"] = "pipeline-site",
["Contact:MinSeconds"] = "0",
["Contact:RecipientEmail"] = "owner@example.org",
["Contact:Mail:SweepSeconds"] = "5",
["RateLimiting:ContactForm:PermitLimit"] = "1000",
["RateLimiting:ContactToken:PermitLimit"] = "1000",
})
{
public CapturingEmailSender Mailer { get; } = new();
public IMailAvailability Availability { get; } = Substitute.For<IMailAvailability>();
protected override bool OpenCmsSwitch => true;
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
base.ConfigureWebHost(builder);
Availability.IsEnabled.Returns(true);
builder.ConfigureTestServices(services =>
{
services.AddSingleton<IEmailSender>(Mailer);
services.AddSingleton(Availability);
});
}
}
public class ContactMailPipelineTests(MailContactHostFactory factory) : IClassFixture<MailContactHostFactory>
{
private async Task<Guid> SubmitAsync(string name)
{
var client = factory.CreateClient();
var token = await Http.GetTokenAsync(client);
(await Http.PostAsync(client, Http.Body(token, name: name))).StatusCode.Should().Be(HttpStatusCode.Accepted);
return (await factory.WithDb(db => db.ContactMessages.AsNoTracking().SingleAsync(m => m.Name == name))).Id;
}
private async Task<ContactMessage> WaitForAsync(Guid id, Func<ContactMessage, bool> done)
{
var deadline = DateTime.UtcNow.AddSeconds(30);
ContactMessage row;
do
{
row = await factory.WithDb(db => db.ContactMessages.AsNoTracking().SingleAsync(m => m.Id == id));
if (done(row))
{
return row;
}
await Task.Delay(200);
}
while (DateTime.UtcNow < deadline);
return row;
}
[Fact]
public async Task ASubmission_IsMailedInTheBackground_WithinSeconds_AndRecordedAsSent()
{
var id = await SubmitAsync("Mail Genuine");
var row = await WaitForAsync(id, m => m.MailStatus == ContactMailStatus.Sent);
row.MailStatus.Should().Be(ContactMailStatus.Sent, "error={0} next={1} attempts={2}", row.MailError, row.NextMailAttemptAt, row.MailAttempts);
row.MailAttempts.Should().Be(1);
var mail = factory.Mailer.Sent.Single(m => m.HtmlBody.Contains("Mail Genuine"));
mail.ToAddress.Should().Be("owner@example.org");
mail.ReplyToAddress.Should().Be("jan@example.nl");
}
[Fact]
public async Task ASpamSubmission_IsNeverMailed()
{
var client = factory.CreateClient();
var token = await Http.GetTokenAsync(client);
await Http.PostAsync(client, Http.Body(token, name: "Mail Spam", hp: "http://spam"));
await Task.Delay(TimeSpan.FromSeconds(2));
factory.Mailer.Sent.Should().NotContain(m => m.HtmlBody.Contains("Mail Spam"));
}
[Fact]
public async Task AResend_OfAFailedMessage_Works_AndIgnoresTheBackoff()
{
var id = Guid.NewGuid();
await factory.WithDb(async db =>
{
db.ContactMessages.Add(new ContactMessage
{
Id = id, SiteId = "pipeline-site", ReceivedAt = DateTimeOffset.UtcNow, Name = "Mail Resend",
Email = "x@example.nl", Subject = "s", Message = "m", Status = ContactMessageStatus.Read,
MailStatus = ContactMailStatus.Failed, MailAttempts = 6, MailError = "rejected",
RetentionUntil = DateTimeOffset.UtcNow.AddMonths(11),
});
await db.SaveChangesAsync();
return 0;
});
var admin = await Jwt.ClientWithRoleAsync(factory, "Administrator");
var response = await admin.PostAsync($"/api/v1/contact-messages/{id}/resend", null);
response.StatusCode.Should().Be(HttpStatusCode.OK);
(await response.Content.ReadAsStringAsync()).Should().Contain("\"mailed\":true");
var row = await factory.WithDb(db => db.ContactMessages.AsNoTracking().SingleAsync(m => m.Id == id));
row.MailStatus.Should().Be(ContactMailStatus.Sent, "error={0} next={1} attempts={2}", row.MailError, row.NextMailAttemptAt, row.MailAttempts);
row.MailError.Should().BeNull();
}
}
@@ -53,7 +53,7 @@ public sealed class SubmissionHarness : IDisposable
public IContactRepository Repository { get; }
public IContactTokenService Tokens { get; }
public ICaptchaVerifier Captcha { get; } = Substitute.For<ICaptchaVerifier>();
public IContactMailSender Mail { get; } = Substitute.For<IContactMailSender>();
public IContactMailSignal Signal { get; } = Substitute.For<IContactMailSignal>();
public CapturingLoggerProvider Logs { get; } = new();
public ContactSubmissionService Sut { get; }
@@ -71,12 +71,10 @@ public sealed class SubmissionHarness : IDisposable
Tokens = new ContactTokenService(DataProtectionProvider.Create("submission-tests"), wrapped, Time);
Captcha.VerifyAsync(Arg.Any<string?>(), Arg.Any<CancellationToken>()).Returns(true);
Mail.SendAsync(Arg.Any<Data.Entities.ContactMessage>(), Arg.Any<CancellationToken>())
.Returns(ContactMailOutcome.Skipped);
var loggerFactory = LoggerFactory.Create(b => b.AddProvider(Logs));
Sut = new ContactSubmissionService(
Repository, Tokens, Captcha, Mail, wrapped, Time, loggerFactory.CreateLogger<ContactSubmissionService>());
Repository, Tokens, Captcha, Signal, wrapped, Time, loggerFactory.CreateLogger<ContactSubmissionService>());
}
/// <summary>A token that is old enough to pass the minimum-time check.</summary>
@@ -38,9 +38,41 @@ public class ContactOptions
public ContactCaptchaOptions Captcha { get; set; } = new();
/// <summary>
/// Where the notification mail for a genuine message goes. Supply it through the environment
/// (<c>Contact__RecipientEmail</c>); it is never part of committed configuration and never exposed to a client.
/// </summary>
public string? RecipientEmail { get; set; }
public ContactMailOptions Mail { get; set; } = new();
public string EffectiveSiteId => string.IsNullOrWhiteSpace(SiteId) ? "default" : SiteId.Trim();
}
/// <summary>How the background sender works (section <c>Contact:Mail</c>).</summary>
public class ContactMailOptions
{
/// <summary>How often the sender looks for mail that is due, besides being woken by a new message.</summary>
public int SweepSeconds { get; set; } = 120;
/// <summary>Automatic attempts per message; after that it stays failed until an administrator resends.</summary>
public int MaxAttempts { get; set; } = 6;
/// <summary>Wait before attempt n+1 after attempt n failed (the last value repeats). Default 5 min, 15 min, 1 h, 6 h, 24 h.</summary>
public int[] BackoffMinutes { get; set; } = [5, 15, 60, 360, 1440];
/// <summary>A claimed message is not claimed again by another instance for this long.</summary>
public int ClaimMinutes { get; set; } = 5;
public int BatchSize { get; set; } = 20;
public TimeSpan BackoffAfter(int attempts)
{
var steps = BackoffMinutes is { Length: > 0 } ? BackoffMinutes : [5];
return TimeSpan.FromMinutes(Math.Max(1, steps[Math.Clamp(attempts - 1, 0, steps.Length - 1)]));
}
}
public class ContactCaptchaOptions
{
public bool Enabled { get; set; }
@@ -44,7 +44,10 @@ public class ContactModule : IModule
services.AddScoped<IContactSubmissionService, ContactSubmissionService>();
services.AddSingleton<IContactTokenService, ContactTokenService>();
services.AddSingleton<ICaptchaVerifier, NullCaptchaVerifier>();
services.AddScoped<IContactMailSender, NoOpContactMailSender>();
// Mail: the request only stores and signals; the background service sends (and retries) with the host's mail pieces.
services.AddScoped<IContactMailSender, ContactMailSender>();
services.AddSingleton<IContactMailSignal, ContactMailSignal>();
services.AddHostedService<ContactMailService>();
// Gate: the form is open only if the host switch AND the CMS switch are on. The host switch
// is asked first, so with it off the database is never touched.
services.AddSingleton<ContactSettingsCache>();
@@ -28,6 +28,10 @@ public class ContactDbContext(DbContextOptions<ContactDbContext> options) : DbCo
entity.Property(e => e.MailError).HasMaxLength(100);
entity.Property(e => e.RetentionUntil).IsRequired();
// The claim of the background sender: two instances that try to claim the same message at once
// cannot both succeed (the second update finds a different value and affects no row).
entity.Property(e => e.NextMailAttemptAt).IsConcurrencyToken();
entity.HasIndex(e => new { e.SiteId, e.Status, e.ReceivedAt });
entity.HasIndex(e => e.RetentionUntil);
});
@@ -0,0 +1,135 @@
// <auto-generated />
using System;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Infrastructure;
using Microsoft.EntityFrameworkCore.Migrations;
using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
using SlpModularCms.Modules.Contact.Data;
#nullable disable
namespace SlpModularCms.Modules.Contact.Migrations
{
[DbContext(typeof(ContactDbContext))]
[Migration("20261110141855_ContactMailClaim")]
partial class ContactMailClaim
{
/// <inheritdoc />
protected override void BuildTargetModel(ModelBuilder modelBuilder)
{
#pragma warning disable 612, 618
modelBuilder
.HasAnnotation("ProductVersion", "10.0.9")
.HasAnnotation("Relational:MaxIdentifierLength", 64);
modelBuilder.Entity("SlpModularCms.Modules.Contact.Data.Entities.ContactMessage", b =>
{
b.Property<Guid>("Id")
.ValueGeneratedOnAdd()
.HasColumnType("char(36)");
b.Property<string>("Email")
.IsRequired()
.HasMaxLength(254)
.HasColumnType("varchar(254)");
b.Property<int>("MailAttempts")
.HasColumnType("int");
b.Property<string>("MailError")
.HasMaxLength(100)
.HasColumnType("varchar(100)");
b.Property<string>("MailStatus")
.IsRequired()
.HasMaxLength(20)
.HasColumnType("varchar(20)");
b.Property<string>("Message")
.IsRequired()
.HasMaxLength(2000)
.HasColumnType("varchar(2000)");
b.Property<string>("Name")
.IsRequired()
.HasMaxLength(100)
.HasColumnType("varchar(100)");
b.Property<DateTimeOffset?>("NextMailAttemptAt")
.IsConcurrencyToken()
.HasColumnType("datetime");
b.Property<DateTimeOffset>("ReceivedAt")
.HasColumnType("datetime");
b.Property<DateTimeOffset>("RetentionUntil")
.HasColumnType("datetime");
b.Property<string>("SiteId")
.IsRequired()
.HasMaxLength(100)
.HasColumnType("varchar(100)");
b.Property<string>("Status")
.IsRequired()
.HasMaxLength(20)
.HasColumnType("varchar(20)");
b.Property<string>("Subject")
.IsRequired()
.HasMaxLength(100)
.HasColumnType("varchar(100)");
b.HasKey("Id");
b.HasIndex("RetentionUntil");
b.HasIndex("SiteId", "Status", "ReceivedAt");
b.ToTable("ContactMessages", (string)null);
});
modelBuilder.Entity("SlpModularCms.Modules.Contact.Data.Entities.ContactSettings", b =>
{
b.Property<int>("Id")
.HasColumnType("int");
b.Property<bool>("Enabled")
.HasColumnType("tinyint(1)");
b.Property<DateTimeOffset>("UpdatedAt")
.HasColumnType("datetime");
b.Property<Guid>("UpdatedByUserId")
.HasColumnType("char(36)");
b.HasKey("Id");
b.ToTable("ContactSettings", (string)null);
});
modelBuilder.Entity("SlpModularCms.Modules.Contact.Data.Entities.IdempotencyRecord", b =>
{
b.Property<string>("SiteId")
.HasMaxLength(100)
.HasColumnType("varchar(100)");
b.Property<Guid>("Key")
.HasColumnType("char(36)");
b.Property<DateTimeOffset>("CreatedAt")
.HasColumnType("datetime");
b.Property<int>("StatusCode")
.HasColumnType("int");
b.HasKey("SiteId", "Key");
b.HasIndex("CreatedAt");
b.ToTable("ContactIdempotency", (string)null);
});
#pragma warning restore 612, 618
}
}
}
@@ -0,0 +1,22 @@
using Microsoft.EntityFrameworkCore.Migrations;
#nullable disable
namespace SlpModularCms.Modules.Contact.Migrations
{
/// <inheritdoc />
public partial class ContactMailClaim : Migration
{
/// <inheritdoc />
protected override void Up(MigrationBuilder migrationBuilder)
{
}
/// <inheritdoc />
protected override void Down(MigrationBuilder migrationBuilder)
{
}
}
}
@@ -53,6 +53,7 @@ namespace SlpModularCms.Modules.Contact.Migrations
.HasColumnType("varchar(100)");
b.Property<DateTimeOffset?>("NextMailAttemptAt")
.IsConcurrencyToken()
.HasColumnType("datetime");
b.Property<DateTimeOffset>("ReceivedAt")
@@ -37,13 +37,14 @@ public record ContactMessageDetail(
string MailStatus,
int MailAttempts,
string? MailError,
DateTimeOffset RetentionUntil);
DateTimeOffset RetentionUntil,
DateTimeOffset? NextMailAttemptAt = null);
/// <summary>Body of PATCH /contact-messages/{id}. Nullable so a missing field is reported in our own shape.</summary>
public record UpdateContactMessageStatusRequest(string? Status);
[ExcludeFromCodeCoverage]
public record ContactResendResult(string MailStatus, int MailAttempts, bool Mailed);
public record ContactResendResult(string MailStatus, int MailAttempts, bool Mailed, string? MailError = null);
[ExcludeFromCodeCoverage]
public record ContactSettingsDto(bool Enabled, bool HostEnabled);
@@ -28,6 +28,16 @@ public interface IContactRepository
Task<ContactSettings?> GetSettingsAsync(CancellationToken cancellationToken);
void Add(ContactSettings settings);
// ---- background mail ----
/// <summary>
/// Unread (<c>New</c>) messages whose mail is due: pending or failed, fewer than <paramref name="maxAttempts"/>
/// attempts, and no next-attempt time in the future. Oldest first. Read, archived and spam messages are never mailed
/// automatically.
/// </summary>
Task<IReadOnlyList<ContactMessage>> GetDueForMailAsync(
string siteId, DateTimeOffset now, int maxAttempts, int take, CancellationToken cancellationToken);
}
public class ContactRepository(ContactDbContext context) : IContactRepository
@@ -94,6 +104,18 @@ public class ContactRepository(ContactDbContext context) : IContactRepository
public void Add(ContactSettings settings) => context.ContactSettings.Add(settings);
public async Task<IReadOnlyList<ContactMessage>> GetDueForMailAsync(
string siteId, DateTimeOffset now, int maxAttempts, int take, CancellationToken cancellationToken)
=> await context.ContactMessages
.Where(m => m.SiteId == siteId
&& m.Status == ContactMessageStatus.New
&& (m.MailStatus == ContactMailStatus.Pending || m.MailStatus == ContactMailStatus.Failed)
&& m.MailAttempts < maxAttempts
&& (m.NextMailAttemptAt == null || m.NextMailAttemptAt <= now))
.OrderBy(m => m.ReceivedAt)
.Take(take)
.ToListAsync(cancellationToken);
public async Task<int> DeleteExpiredMessagesAsync(DateTimeOffset now, CancellationToken cancellationToken)
{
var total = 0;
@@ -131,21 +131,44 @@ public sealed class ContactAdminService(
throw new ContactResendNotAllowedException();
}
var outcome = await mailSender.SendAsync(message, cancellationToken);
if (outcome != ContactMailOutcome.Skipped)
// A manual resend ignores the backoff and the maximum of the automatic attempts.
var result = await mailSender.SendAsync(message, cancellationToken);
switch (result.Outcome)
{
message.MailAttempts++;
message.MailStatus = outcome == ContactMailOutcome.Sent ? ContactMailStatus.Sent : ContactMailStatus.Failed;
await repository.SaveChangesAsync(cancellationToken);
case ContactMailOutcome.Sent:
message.MailAttempts++;
message.MailStatus = ContactMailStatus.Sent;
message.MailError = null;
message.NextMailAttemptAt = null;
await repository.SaveChangesAsync(cancellationToken);
break;
case ContactMailOutcome.Failed:
message.MailAttempts++;
message.MailStatus = ContactMailStatus.Failed;
message.MailError = result.ErrorCode;
await repository.SaveChangesAsync(cancellationToken);
break;
default:
// Nothing could be attempted (mail off / no recipient): show why, count nothing.
if (result.ErrorCode is not null && message.MailError != result.ErrorCode)
{
message.MailError = result.ErrorCode;
await repository.SaveChangesAsync(cancellationToken);
}
break;
}
logger.LogInformation("Contact message {MessageId} resent: {Outcome}", id, outcome);
logger.LogInformation("Contact message {MessageId} resent: {Outcome}", id, result.Outcome);
return new ContactResendResult(
ContactStatusNames.Of(message.MailStatus), message.MailAttempts, outcome == ContactMailOutcome.Sent);
ContactStatusNames.Of(message.MailStatus), message.MailAttempts, result.Outcome == ContactMailOutcome.Sent,
result.Outcome == ContactMailOutcome.Sent ? null : message.MailError);
}
private static ContactMessageDetail ToDetail(ContactMessage m) => new(
m.Id.ToString(), m.ReceivedAt, m.Name, m.Email, m.Subject, m.Message,
ContactStatusNames.Of(m.Status), ContactStatusNames.Of(m.MailStatus),
m.MailAttempts, m.MailError, m.RetentionUntil);
m.MailAttempts, m.MailError, m.RetentionUntil, m.NextMailAttemptAt);
}
@@ -0,0 +1,97 @@
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using SlpModularCms.Core.Email;
using SlpModularCms.Core.SiteSettings;
using SlpModularCms.Modules.Contact.Config;
using SlpModularCms.Modules.Contact.Data.Entities;
namespace SlpModularCms.Modules.Contact.Services;
/// <summary>
/// Mails the notification of a stored message to the site owner, using the host's own mail
/// pieces (sender, renderer, effective site sender). The owner can simply reply: the visitor is
/// the Reply-To. Nothing the visitor typed ends up in the subject or in any header except
/// Reply-To, and no address, name or text is ever logged: only the message id and a short code.
/// </summary>
public sealed class ContactMailSender(
IEmailSender sender,
IMailTemplateRenderer renderer,
ILanguageResolver languages,
ISiteSettingsService siteSettings,
IMailAvailability availability,
IOptions<EmailOptions> email,
IOptions<AppMailOptions> app,
IOptions<ContactOptions> contact,
ILogger<ContactMailSender> logger) : IContactMailSender
{
public string? NotReadyReason()
{
if (!availability.IsEnabled)
{
return ContactMailResult.Disabled;
}
return EmailAddressRules.IsValidAddress(contact.Value.RecipientEmail) ? null : ContactMailResult.RecipientNotConfigured;
}
public async Task<ContactMailResult> SendAsync(ContactMessage message, CancellationToken cancellationToken)
{
var notReady = NotReadyReason();
if (notReady is not null)
{
return new ContactMailResult(ContactMailOutcome.Skipped, notReady);
}
try
{
var (fromAddress, fromName) = await siteSettings.GetEffectiveSenderAsync(cancellationToken);
var baseUrl = app.Value.PublicBaseUrl.TrimEnd('/');
var language = languages.Resolve(null);
var dutch = language == MailLanguages.Dutch;
var model = new MailModel(
SiteName: fromName,
LogoUrl: ResolveLogo(baseUrl, email.Value.LogoUrl),
BrandColor: string.IsNullOrWhiteSpace(email.Value.BrandColor) ? null : email.Value.BrandColor,
LogoDarkUrl: ResolveLogo(baseUrl, email.Value.LogoDarkUrl),
Details:
[
new MailDetail(dutch ? "Naam" : "Name", message.Name),
new MailDetail(dutch ? "E-mailadres" : "E-mail address", message.Email),
new MailDetail(dutch ? "Onderwerp" : "Subject", message.Subject),
new MailDetail(dutch ? "Bericht" : "Message", message.Message),
]);
var rendered = renderer.Render(MailKind.ContactMessage, language, model);
var result = await sender.SendAsync(
new OutgoingMail(
contact.Value.RecipientEmail!.Trim(), rendered.Subject, rendered.Html, rendered.Text,
fromAddress, fromName,
ReplyToAddress: message.Email,
ReplyToName: EmailAddressRules.IsValidDisplayName(message.Name) ? message.Name : null),
cancellationToken);
if (result.Sent)
{
logger.LogInformation("contact_mail_sent message={MessageId}", message.Id);
return ContactMailOutcome.Sent;
}
logger.LogWarning("contact_mail_failed message={MessageId} code={Code}", message.Id, result.ErrorCode);
return new ContactMailResult(ContactMailOutcome.Failed, result.ErrorCode ?? MailSendResult.Unknown);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// Type only: the exception text could quote addresses or content.
logger.LogWarning("contact_mail_failed message={MessageId} code={Code} exception={ExceptionType}",
message.Id, MailSendResult.Unknown, ex.GetType().Name);
return new ContactMailResult(ContactMailOutcome.Failed, MailSendResult.Unknown);
}
}
private static string? ResolveLogo(string baseUrl, string? logoUrl)
{
if (string.IsNullOrWhiteSpace(logoUrl)) return null;
return logoUrl.StartsWith('/') ? baseUrl + logoUrl : logoUrl;
}
}
@@ -0,0 +1,159 @@
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using SlpModularCms.Modules.Contact.Config;
using SlpModularCms.Modules.Contact.Data.Entities;
using SlpModularCms.Modules.Contact.Repositories;
namespace SlpModularCms.Modules.Contact.Services;
/// <summary>
/// Sends the notification mails in the background, so a visitor never waits for SMTP. It wakes when a message was
/// stored and on a fixed sweep, picks the unread messages whose mail is due, claims each one (so two instances never
/// mail the same message), sends it and records the outcome. A failure is retried with a growing wait up to a maximum;
/// after that the message stays failed until an administrator resends it. While mail cannot be sent at all (mail off,
/// no valid recipient) nothing is attempted and nothing is counted: the reason is shown on the message instead.
/// While the module is disabled it does nothing and never touches the database.
/// </summary>
public class ContactMailService(
IServiceScopeFactory scopeFactory,
IContactMailSignal signal,
IOptions<ContactOptions> options,
TimeProvider time,
ILogger<ContactMailService> logger) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
await SweepAsync(stoppingToken);
try
{
await signal.WaitAsync(TimeSpan.FromSeconds(Math.Max(5, options.Value.Mail.SweepSeconds)), stoppingToken);
}
catch (OperationCanceledException)
{
return;
}
}
}
/// <summary>One pass. Returns the number of messages that were attempted.</summary>
internal async Task<int> SweepAsync(CancellationToken cancellationToken)
{
var settings = options.Value;
if (!settings.Enabled)
{
return 0;
}
try
{
await using var scope = scopeFactory.CreateAsyncScope();
var repository = scope.ServiceProvider.GetRequiredService<IContactRepository>();
var sender = scope.ServiceProvider.GetRequiredService<IContactMailSender>();
var mail = settings.Mail;
var siteId = settings.EffectiveSiteId;
var now = time.GetUtcNow();
var due = await repository.GetDueForMailAsync(siteId, now, mail.MaxAttempts, mail.BatchSize, cancellationToken);
if (due.Count == 0)
{
return 0;
}
// Mail cannot be sent at all: say why on the messages, count nothing, retry nothing in a loop.
var notReady = sender.NotReadyReason();
if (!string.IsNullOrEmpty(notReady))
{
foreach (var message in due.Where(m => m.MailError != notReady))
{
message.MailError = notReady;
}
await TrySaveAsync(repository, cancellationToken);
return 0;
}
var attempted = 0;
foreach (var message in due)
{
// Claim first. The next-attempt time is a concurrency token: a second instance holding the old
// value fails to save here and skips the message.
// Whole seconds: the column keeps no fractions, and the value must read back exactly as written
// because it is the concurrency token of the save that records the outcome.
var claimUntil = now + TimeSpan.FromMinutes(Math.Max(1, mail.ClaimMinutes));
message.NextMailAttemptAt = new DateTimeOffset(claimUntil.Ticks - claimUntil.Ticks % TimeSpan.TicksPerSecond, claimUntil.Offset);
try
{
await repository.SaveChangesAsync(cancellationToken);
}
catch (DbUpdateConcurrencyException)
{
continue;
}
var result = await sender.SendAsync(message, cancellationToken);
attempted++;
Record(message, result, mail, time.GetUtcNow());
await repository.SaveChangesAsync(cancellationToken);
}
if (attempted > 0)
{
logger.LogInformation("Contact mail: {Count} message(s) attempted", attempted);
}
return attempted;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// Type only: the message could quote addresses.
logger.LogError("Contact mail sweep failed ({ExceptionType})", ex.GetType().Name);
return 0;
}
}
/// <summary>Applies the outcome of one automatic attempt to the message.</summary>
internal static void Record(ContactMessage message, ContactMailResult result, ContactMailOptions mail, DateTimeOffset now)
{
switch (result.Outcome)
{
case ContactMailOutcome.Sent:
message.MailStatus = ContactMailStatus.Sent;
message.MailError = null;
message.MailAttempts++;
message.NextMailAttemptAt = null;
break;
case ContactMailOutcome.Failed:
message.MailStatus = ContactMailStatus.Failed;
message.MailError = result.ErrorCode;
message.MailAttempts++;
// After the last allowed attempt there is no next one; an administrator can still resend.
message.NextMailAttemptAt = message.MailAttempts >= mail.MaxAttempts ? null : now + mail.BackoffAfter(message.MailAttempts);
break;
default:
// Skipped: nothing was attempted, so nothing is counted; try again at the next sweep.
message.MailError = result.ErrorCode;
message.NextMailAttemptAt = null;
break;
}
}
private static async Task TrySaveAsync(IContactRepository repository, CancellationToken cancellationToken)
{
try
{
await repository.SaveChangesAsync(cancellationToken);
}
catch (DbUpdateConcurrencyException)
{
// Another instance changed the same rows; the next sweep sorts it out.
}
}
}
@@ -22,25 +22,67 @@ public sealed class NullCaptchaVerifier : ICaptchaVerifier
public enum ContactMailOutcome
{
/// <summary>No mail was attempted (no sender available yet); the message stays pending.</summary>
/// <summary>No mail was attempted (mail is off or no recipient is configured); nothing is counted.</summary>
Skipped,
Sent,
Failed,
}
/// <summary>
/// Sends the notification mail for a genuine message. Called after the message is stored; a
/// failure must never fail the request. The real implementation arrives with the mail unit.
/// What one send came to. <see cref="ErrorCode"/> is a short code only (for example
/// <c>auth_failed</c>, <c>disabled</c>, <c>recipient_not_configured</c>), never an address or text.
/// </summary>
public readonly record struct ContactMailResult(ContactMailOutcome Outcome, string? ErrorCode = null)
{
public const string Disabled = "disabled";
public const string RecipientNotConfigured = "recipient_not_configured";
public static implicit operator ContactMailResult(ContactMailOutcome outcome) => new(outcome);
}
/// <summary>
/// Mails the notification for a stored message. Used by the background sender and by the administrator's
/// resend; it never throws into its caller.
/// </summary>
public interface IContactMailSender
{
Task<ContactMailOutcome> SendAsync(ContactMessage message, CancellationToken cancellationToken);
/// <summary>Null (or empty) when mail can be sent now, otherwise the short reason code.</summary>
string? NotReadyReason();
Task<ContactMailResult> SendAsync(ContactMessage message, CancellationToken cancellationToken);
}
public sealed class NoOpContactMailSender : IContactMailSender
/// <summary>Wakes the background mail sender after a message was stored, so the mail goes out within seconds.</summary>
public interface IContactMailSignal
{
public Task<ContactMailOutcome> SendAsync(ContactMessage message, CancellationToken cancellationToken)
=> Task.FromResult(ContactMailOutcome.Skipped);
void Notify();
Task WaitAsync(TimeSpan timeout, CancellationToken cancellationToken);
}
public sealed class ContactMailSignal : IContactMailSignal
{
private readonly System.Threading.Channels.Channel<bool> _channel =
System.Threading.Channels.Channel.CreateBounded<bool>(new System.Threading.Channels.BoundedChannelOptions(1)
{
FullMode = System.Threading.Channels.BoundedChannelFullMode.DropWrite,
});
public void Notify() => _channel.Writer.TryWrite(true);
/// <summary>Returns when notified or when the timeout passes, whichever is first.</summary>
public async Task WaitAsync(TimeSpan timeout, CancellationToken cancellationToken)
{
using var source = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
source.CancelAfter(timeout);
try
{
await _channel.Reader.ReadAsync(source.Token);
}
catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
{
// timeout: the periodic sweep
}
}
}
/// <summary>
@@ -22,7 +22,7 @@ public sealed class ContactSubmissionService(
IContactRepository repository,
IContactTokenService tokens,
ICaptchaVerifier captcha,
IContactMailSender mailSender,
IContactMailSignal mailSignal,
IOptions<ContactOptions> options,
TimeProvider time,
ILogger<ContactSubmissionService> logger) : IContactSubmissionService
@@ -115,6 +115,7 @@ public sealed class ContactSubmissionService(
{
message = NewMessage(request, siteId, now, ContactMessageStatus.New, ContactMailStatus.Pending,
now.AddMonths(o.RetentionMonths));
message.NextMailAttemptAt = now; // due at once; the background sender picks it up
}
if (message is not null)
@@ -150,11 +151,11 @@ public sealed class ContactSubmissionService(
return new SubmissionResult.Received();
}
// 6. Mail, only for genuine messages and only after the message is safely stored. A mail
// problem never fails the request.
if (outcome == Outcome.Genuine && message is not null)
// 6. Mail: the visitor never waits for SMTP. A genuine message is stored as pending and due now; the
// background sender is woken and mails it within seconds (and retries on failure).
if (outcome == Outcome.Genuine)
{
await TryMailAsync(message, cancellationToken);
mailSignal.Notify();
}
Log(outcome, siteId);
@@ -163,27 +164,6 @@ public sealed class ContactSubmissionService(
private const int StatusCodes202 = 202;
private async Task TryMailAsync(ContactMessage message, CancellationToken cancellationToken)
{
try
{
var result = await mailSender.SendAsync(message, cancellationToken);
if (result == ContactMailOutcome.Skipped)
{
return;
}
message.MailAttempts++;
message.MailStatus = result == ContactMailOutcome.Sent ? ContactMailStatus.Sent : ContactMailStatus.Failed;
await repository.SaveChangesAsync(cancellationToken);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
// Type only: the exception message could carry addresses or content.
logger.LogError("Notification mail for a contact message failed ({ExceptionType})", ex.GetType().Name);
}
}
private static ContactMessage NewMessage(
ContactMessageRequest request, string siteId, DateTimeOffset now,
ContactMessageStatus status, ContactMailStatus mailStatus, DateTimeOffset retentionUntil) => new()