7.6 KiB
7.6 KiB
Code Generation Plan — CMS-U5 contact-mail (mail + retry)
Phase 2, on the rebased branch (base origin/master e671078). Inputs: contract § 4 (store first, mail after commit, no personal data in logs, From = fixed site sender, Reply-To = visitor), requirements FR-D, SLS decision "new MailKind, do not change existing mail code", CMS-U3/U4 seams (IContactMailSender, ContactMessage.MailStatus/MailAttempts/MailError/NextMailAttemptAt, resend endpoint). Nothing is deployed; Contact:Enabled stays off.
Findings on the merged master (Core/Email)
IEmailSender.SendAsync(OutgoingMail)returns aMailSendResult(Sent, ErrorCode); never throws.IMailAvailability.IsEnabledis the single answer to "can this host send mail" (SMTP host set and configuration valid).ISiteSettingsService.GetEffectiveSenderAsyncgives the effective From address/name (already checked againstEmail:AllowedFromAddresses).ILanguageResolver+IMailTemplateRendererrender subject/HTML/text from a static catalog perMailKind(nl/en), with dark-mode classes (DarkPage/DarkCard).- The renderer's layout has a heading, a greeting, one intro paragraph, an optional button and a note. A contact mail also needs a block with the visitor's name, e-mail address, subject and message, and the mail needs a
Reply-To.OutgoingMailhas no reply-to member andMailModelhas no list of details. SmtpEmailSenderalready classifies failures into short codes (auth_failed,rejected_recipient,timeout_*, ...); those codes are whatContactMessage.MailErrorstores.
Decisions
- Additive changes in the shared mail code (needs ASF/SLS consent, nothing existing changes behaviour):
MailKind.ContactMessage(+ nl/en catalog entry);MailModelgets an optionalIReadOnlyList<MailDetail>? Details(label/value pairs; values HTML-encoded, line breaks kept as<br>in HTML and plain lines in text, rendered inside the existing card with the existing muted/dark classes so the dark-mode contrast is kept);OutgoingMailgets optionalReplyToAddress/ReplyToName, applied bySmtpEmailSender(control characters stripped, address validated withEmailAddressRules). No other change to those files. - The visitor never waits for SMTP. The submit request no longer sends mail inline (U3 did a no-op call there). It stores the message with
MailStatus=PendingandNextMailAttemptAt=nowand wakes the sender in-process (aChannelsignal); the mail goes out within seconds in the background. Resend (admin request) still sends inline, as U4 does. - Retry job
ContactMailService : BackgroundService— wakes on the signal and everyContact:Mail:SweepSeconds(default 120). Selects rows withStatus != Spam,MailStatus in (Pending, Failed),MailAttempts < MaxAttemptsandNextMailAttemptAt <= now(or null), oldest first, batches of 20. Each row is claimed first (NextMailAttemptAt = now + 5 min, saved) so two instances never mail the same message; then sent. Success:Sent, error cleared. Failure:Failed,MailError= the short code,MailAttempts++,NextMailAttemptAt = now + backoff[attempts]with backoff 5 min, 15 min, 1 h, 6 h, 24 h (configurable list); afterContact:Mail:MaxAttempts(default 6) it staysFaileduntil an administrator resends (resend ignores backoff and the maximum). - When mail cannot be sent at all (
IMailAvailability.IsEnabledfalse or no validContact:RecipientEmail): rows stayPending, no attempt is counted, nothing is retried in a loop; the admin detail shows why (mailError=disabled/recipient_not_configured). They are picked up automatically once mail is configured. - Addresses: recipient
Contact:RecipientEmailis environment only for the Andrea site (no address in committed config); the SLP host may keep it in its own appsettings (SLS to confirm). From =ISiteSettingsService.GetEffectiveSenderAsync(allow-listed); Reply-To = visitor address and display name. Mail subject is fixed text from the catalog ("Nieuw bericht via {site}"); no visitor-supplied text goes into the subject or any header except Reply-To. - Privacy: no address, name or message in any log line, exception or Sentry event; only message id, attempt number and the short error code.
SmtpFailure.Describeoutput stays out of the contact logs (it may quote reply text). - Admin API additive field: the message detail gets
nextMailAttemptAt(nullable) so the UI can show "next attempt at ...". - 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*,SmtpEmailSenderreply-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, callsIEmailSender, maps theMailSendResulttoSent/Failed+ code; returnsSkippedfor "disabled"/"no recipient"). - Step 3 — Pipeline change:
ContactSubmissionServicestops sending inline, setsNextMailAttemptAt, signalsIContactMailSignal. - Step 4 — Retry/background service
ContactMailService(claim, backoff, max attempts, signal, disabled handling) and optionsContact: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 giveSkipped); 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 capturingIEmailSenderregistered in the test host: submit -> mail captured within seconds and rowsent; failing sender ->failed+ code + next attempt; resendmailed: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.mdroutes/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.
Risks / questions for approval
- OK to make the three additive changes in shared mail code (
MailTypes.cs,MailTemplateRenderer.cs,SmtpEmailSender.cs)? Alternative without touching them: a plain-text-only contact mail built in the Contact module with no Reply-To header (worse: no one can reply by pressing Reply). I recommend the additive change. Contact:RecipientEmailfor the SLP host: committed in its appsettings or environment only?- Backoff 5 min / 15 min / 1 h / 6 h / 24 h and 6 attempts: acceptable?