Files

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 a MailSendResult(Sent, ErrorCode); never throws. IMailAvailability.IsEnabled is the single answer to "can this host send mail" (SMTP host set and configuration valid). ISiteSettingsService.GetEffectiveSenderAsync gives the effective From address/name (already checked against Email:AllowedFromAddresses). ILanguageResolver + IMailTemplateRenderer render subject/HTML/text from a static catalog per MailKind (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. OutgoingMail has no reply-to member and MailModel has no list of details.
  • SmtpEmailSender already classifies failures into short codes (auth_failed, rejected_recipient, timeout_*, ...); those codes are what ContactMessage.MailError stores.

Decisions

  1. Additive changes in the shared mail code (needs ASF/SLS consent, nothing existing changes behaviour): MailKind.ContactMessage (+ nl/en catalog entry); MailModel gets an optional IReadOnlyList<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); OutgoingMail gets optional ReplyToAddress/ReplyToName, applied by SmtpEmailSender (control characters stripped, address validated with EmailAddressRules). No other change to those files.
  2. 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=Pending and NextMailAttemptAt=now and wakes the sender in-process (a Channel signal); the mail goes out within seconds in the background. Resend (admin request) still sends inline, as U4 does.
  3. Retry job ContactMailService : BackgroundService — wakes on the signal and every Contact:Mail:SweepSeconds (default 120). Selects rows with Status != Spam, MailStatus in (Pending, Failed), MailAttempts < MaxAttempts and NextMailAttemptAt <= 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); after Contact:Mail:MaxAttempts (default 6) it stays Failed until an administrator resends (resend ignores backoff and the maximum).
  4. When mail cannot be sent at all (IMailAvailability.IsEnabled false or no valid Contact:RecipientEmail): rows stay Pending, 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.
  5. Addresses: recipient Contact:RecipientEmail is 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.
  6. 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.Describe output stays out of the contact logs (it may quote reply text).
  7. Admin API additive field: the message detail gets nextMailAttemptAt (nullable) so the UI can show "next attempt at ...".
  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.

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

  1. 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.
  2. Contact:RecipientEmail for the SLP host: committed in its appsettings or environment only?
  3. Backoff 5 min / 15 min / 1 h / 6 h / 24 h and 6 attempts: acceptable?