Files
summercms/modules/postcard/README.md
Jakub Zych 7e5d2c74af feat(postcard): database overrides for mail templates with file fallback
- postcard owns the system_mail_* tables (postcard.Migrations), run by lagoon
  as the framework set summercms.postcard after system_files
- Send asks an OverrideSource once per message; NewDBSource reads the
  customized template row through the *gorm.DB published on the app
- a failed lookup, missing tables or an override that does not render or
  fails the safety checks sends the file version and is logged
- the caller's Message.Subject still wins; Mailer, Message, NewMailer,
  Catalog.Register and BootPlugin keep their signatures

Plan 35-01, task 2 (tracer).
2026-11-13 10:26:10 +01:00

222 lines
13 KiB
Markdown

# postcard
Transactional mail from plugin-owned Markdown templates and layouts, delivered through a memory, log or SMTP driver.
`import "git.golem15.com/golem15/summercms/modules/postcard"`
**Name:** What you send home in summer; it delivers the application's mail.
## Overview
postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates and layouts as the plugin boots. Callers then send a template by its dotted name with a map of variables. postcard also owns the mail tables that hold administrators' edits: when a template has a customized row, the mailer sends that override, and the plugin's file otherwise. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts.
## Role in the framework
A service module on `backpack`, `compass` and `pact`; `party` registers the templates plugins contribute, and `lagoon` runs `postcard.Migrations` with the framework's other migrations. postcard does not import `lagoon`: it finds the database through `backpack`. It is separate so mail rendering and delivery can be tested and swapped (memory, log, SMTP) without touching the code that sends.
Use cases:
- Send account mail (welcome, password reset) from Markdown templates owned by the plugin.
- Share one branded layout across all of an application's mail.
- Capture sent mail in memory in tests, or log it in development instead of delivering it.
## Features
- Templates named `<plugin>::mail.<name>` and loaded from `views/mail/<name>.htm` (dots become directories). A plugin may only register names in its own namespace; missing files, duplicates and unknown layout aliases fail at boot.
- WinterCMS file format: an INI header (`subject`, `layout`, `description`), a `==` separator, then a Markdown body rendered with Go `html/template` variables such as `{{ .name }}`.
- Layouts with a header, a text wrapper and an HTML wrapper, referenced from templates by a short alias (`pact.HasMailTemplates` maps aliases to full names). A neutral default layout is built in.
- Every message gets an HTML part (Markdown converted with goldmark) and a plain-text part. `mail.css` and `mail.brandCss` are inlined into the layout's style block.
- Safety checks: rendered HTML with script, iframe, object or embed tags, inline event handlers or `javascript:`/`vbscript:`/`data:` URLs is rejected; CR/LF in the subject or address headers is rejected; addresses are parsed with `net/mail`.
- Drivers behind the `postcard.Driver` interface: `postcard.MemoryDriver` (keeps messages for tests), `postcard.LogDriver` (logs headers and the text part through `log/slog`, never the HTML or credentials), `postcard.SMTPDriver` (go-mail with an explicit TLS policy) and `postcard.FailDriver` (a deterministic failure for tests).
- Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout. The mailer reads it on every send, with no cache, in every process that publishes a `*gorm.DB`. A missing database, tables that are not migrated yet, or an override that does not render or fails the safety checks sends the file version.
- No locale selection: callers pass the full template name, including any locale suffix.
## Usage
A plugin ships `views/mail/welcome.htm`:
```text
subject = "Welcome, {{ .name }}"
description = "Sent after registration"
==
Hi **{{ .name }}**, thanks for joining the blog.
```
and sends it through the mailer the runtime published:
```go
package blog
import (
"context"
"errors"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/postcard"
)
func SendWelcome(ctx context.Context, app *backpack.App, email, name string) error {
mailer, ok := app.Lookup[postcard.Mailer]()
if !ok {
return errors.New("mailer not published")
}
return mailer.Send(ctx, postcard.Message{
Template: "acme.blog::mail.welcome",
To: []string{email},
Vars: map[string]any{"name": name},
})
}
```
In tests, build the catalog and mailer directly and inspect what was sent:
```go
package blog
import (
"context"
"testing"
"testing/fstest"
"git.golem15.com/golem15/summercms/modules/postcard"
)
func TestWelcomeMail(t *testing.T) {
mailFS := fstest.MapFS{"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome, {{ .name }}\"\n==\nHi **{{ .name }}**.\n")}}
cat := postcard.NewCatalog()
if err := cat.Register("acme.blog", mailFS, []string{"acme.blog::mail.welcome"}, nil); err != nil {
t.Fatal(err)
}
driver := postcard.NewMemoryDriver()
mailer := postcard.NewMailer(cat, driver, postcard.Options{From: "blog@example.com"})
msg := postcard.Message{Template: "acme.blog::mail.welcome", To: []string{"ada@example.com"}, Vars: map[string]any{"name": "Ada"}}
if err := mailer.Send(context.Background(), msg); err != nil {
t.Fatal(err)
}
if got := driver.Messages()[0].Subject; got != "Welcome, Ada" {
t.Fatalf("subject = %q", got)
}
}
```
### Overrides from the admin
postcard owns the tables `system_mail_templates`, `system_mail_layouts`, `system_mail_partials`, `system_mail_brand_settings` and `system_mail_image_library` (`postcard.Migrations`). A row of `system_mail_templates` with `is_custom` set is an override of the template named in its `code`: its `subject` and `body` replace the file's, and the row its `layout_id` points at names the layout. The body has the same format as in the file, Markdown with Go template variables.
`postcard.Activate` gives the mailer the source `postcard.NewDBSource` returns. On every `Send` the mailer asks it once for the template being sent; nothing is cached, so an edit applies to the next message in every process that shares the database, including a worker that never loads the admin.
The subject is taken from the first of these that is set:
1. `postcard.Message.Subject`, the caller's subject;
2. the override's subject;
3. the file's subject.
An override never stops mail:
- With no `*gorm.DB` published, the file version is sent.
- When the lookup fails (no connection, or the tables are not migrated yet), the file version is sent and a warning is logged, at most once a minute per distinct error.
- When the override does not parse, fails while rendering (for example it uses a field of a variable the caller does not pass) or fails the safety checks, the error is logged as `postcard: override failed, sending the file version` with the template name, and the file version is sent.
- When the override's layout no longer exists, the message is rendered in the default layout and a warning is logged.
`postcard.NewMailer` takes a source through `postcard.Options.Overrides`; any `postcard.OverrideSource` works, which is how a test supplies overrides without a database:
```go
package blog
import (
"context"
"git.golem15.com/golem15/summercms/modules/postcard"
)
// fixedOverrides overrides one template with a fixed subject and body.
type fixedOverrides struct{}
func (fixedOverrides) MailOverrides(_ context.Context, template string) (postcard.Overrides, error) {
if template != "acme.blog::mail.welcome" {
return postcard.Overrides{}, nil
}
return postcard.Overrides{Template: &postcard.TemplateOverride{
Subject: "Hello, {{ .name }}",
Body: "Good to see you, **{{ .name }}**.",
}}, nil
}
func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Mailer {
return postcard.NewMailer(cat, driver, postcard.Options{Overrides: fixedOverrides{}})
}
```
## API reference
| Identifier | Description |
|------------|-------------|
| `postcard.Activate` | Builds the driver from config and publishes the app-scoped `postcard.Mailer` before plugins boot. The mailer reads overrides through `postcard.NewDBSource`. |
| `postcard.BootPlugin` | Registers a booting plugin's declared templates and layouts with the published mailer. |
| `postcard.Mailer` | Sends a registered template through the configured driver. |
| `postcard.NewMailer` | Builds a mailer from a catalog, a driver and `postcard.Options`. |
| `postcard.Message` | What callers send: template name, recipients, reply-to, variables and an optional subject override. |
| `postcard.Options` | Mailer settings: sender address, CSS, brand CSS and, in `postcard.Options.Overrides`, the source of database overrides (nil sends the file versions). |
| `postcard.Catalog` | Registered templates and layouts, including the built-in default layout. |
| `postcard.NewCatalog` | Returns a catalog holding only the default layout. |
| `postcard.Catalog.Register` | Loads a plugin's templates and layout aliases from an `fs.FS`. |
| `postcard.Driver` | Delivers a `postcard.RenderedMessage`. |
| `postcard.RenderedMessage` | The validated payload a driver transmits: headers, HTML part and text part. |
| `postcard.NewMemoryDriver` | In-memory driver; `postcard.MemoryDriver.Messages` returns what was sent. |
| `postcard.NewLogDriver` | Driver that logs through a `*slog.Logger` (the postcard component logger when nil). |
| `postcard.NewSMTPDriver` | SMTP driver built from a `postcard.SMTPConfig`. |
| `postcard.SMTPConfig` | Host, port, credentials, TLS policy and timeout for the SMTP driver. |
| `postcard.FailDriver` | Driver whose `postcard.FailDriver.Send` always returns `postcard.FailDriver.Err`. |
| `postcard.OverrideSource` | Supplies the database overrides of one render. `postcard.OverrideSource.MailOverrides` takes the template name; an empty name asks for everything except a template override. |
| `postcard.Overrides` | What a source returns: the template override in `postcard.Overrides.Template` (nil when there is none), layout content by code in `postcard.Overrides.Layouts` and partial content by name in `postcard.Overrides.Partials`. |
| `postcard.TemplateOverride` | A template's customized subject, body and layout code. An empty `postcard.TemplateOverride.Layout` keeps the file's layout. |
| `postcard.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS as stored in the database. |
| `postcard.PartialOverride` | A partial's HTML and text sections as stored in the database. |
| `postcard.NewDBSource` | The source over postcard's tables. It looks the `*gorm.DB` up on the app at every call and returns no overrides when none is published. |
| `postcard.Migrations` | The gormigrate set that creates the mail tables; lagoon runs it under the `summercms.postcard` history. |
| `postcard.TemplatesTable`, `postcard.LayoutsTable`, `postcard.PartialsTable`, `postcard.BrandTable`, `postcard.ImageLibraryTable` | The names of the mail tables, for code that defines models over them. |
## Configuration
`postcard.Activate` reads these keys from the app's [compass](../compass/README.md) config:
| Key | Default | Controls |
|-----|---------|----------|
| `mail.driver` | `memory` | Delivery driver: `memory`, `log` or `smtp`. Any other value fails at boot. |
| `mail.from` | empty | Sender address. Required by the SMTP driver. |
| `mail.css` | empty | CSS inlined into the layout. |
| `mail.brandCss` | empty | Brand CSS inlined before `mail.css`. |
| `mail.smtp.host` | none | SMTP host. Required when `mail.driver` is `smtp`. |
| `mail.smtp.port` | `587` | SMTP port. |
| `mail.smtp.username` | empty | SMTP user. When set, PLAIN authentication is used. |
| `mail.smtp.password` | empty | SMTP password. |
| `mail.smtp.tls` | `mandatory` | TLS policy: `mandatory` (or `tls`), `starttls` (or `opportunistic`), `none` (or `notls`, `off`). Plain connections are never inferred. |
| `mail.smtp.timeout` | `10s` | Connection timeout, as a Go duration or a number of seconds. |
```yaml
mail:
driver: smtp
from: blog@example.com
smtp:
host: smtp.example.com
port: 587
username: blog
password: <secret>
tls: mandatory
```
## Dependencies
- SummerCMS modules: [backpack](../backpack/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component logger `postcard` when the app publishes no logger), [pact](../pact/README.md).
- Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations).
- Standard library: `bytes`, `context`, `embed`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `strings`, `sync`, `text/template`, `time`.
- Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`.
## Testing
```sh
go test ./modules/postcard/...
```
The SMTP integration test starts a Mailpit container and the override smoke test a Postgres container, both through testcontainers-go, so they need Docker. Run `go test -short ./modules/postcard/...` to skip them; the remaining tests use the memory and fail drivers and need no external services.