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).
This commit is contained in:
@@ -29,7 +29,7 @@ Use cases:
|
||||
- One shared pool: `lagoon.Open`, `lagoon.Use` and `lagoon.OpenFromApp` return a `*sql.DB` and a `*gorm.DB` built on that same pool; `lagoon.Publish` makes both available on the `backpack.App`.
|
||||
- Database-ready hooks: `lagoon.OnDatabase` runs a callback with the pool and GORM handle as soon as the database is published, immediately when it already is, otherwise when `lagoon.Publish` runs. Plugins register GORM callbacks through it from Boot, which runs before the `serve` command publishes the database.
|
||||
- After-commit work: `lagoon.Transaction` runs a function in a transaction and then the callbacks registered with `lagoon.AfterCommit`, in order, only after the commit succeeds; a nested `lagoon.Transaction` is a savepoint whose callbacks are dropped with it when it fails. A nested `lagoon.Transaction` must be given the outer transaction's handle: given a root handle it returns an error without running its function, rather than open an independent transaction whose callbacks would wait on the outer one. A single-statement write for which GORM opens its own implicit transaction runs its callbacks from `lagoon:after_commit` once GORM commits, and never when the write fails. A GORM callback that runs after `lagoon:after_commit` on the same write registers its work too late: the work never runs, and `lagoon.AfterCommit` logs a warning. A callback registered inside a foreign plain GORM transaction is unsafe because Lagoon cannot observe its commit, so `lagoon.AfterCommit` warns and skips it. Outside a transaction, callbacks run immediately. The handle a supported callback receives always has an empty statement on the connection its work belongs to. A panicking callback is logged and never turns a committed write into an error.
|
||||
- Per-plugin migrations: `lagoon.Migrate` runs the framework's `system_files` set (`attach.Migrations`), backend admin identity set (`lagoon.BackendAdminMigrations`), `deferred_bindings` set (`lagoon.DeferredBindingMigrations`, under the `lagoon.DeferredHistoryID` history) and job-queue set (`lagoon.QueueMigrations`: River's schema pinned at `lagoon.RiverSchemaVersion`, then the `lagoon.JobsTable` record table, under the `lagoon.QueueHistoryID` history), then every `pact.HasMigrations` set in plugin activation order, each in its own `summer_migrations_<plugin_id>` history table (`lagoon.HistoryTableName`). `lagoon.RollbackLast` and `lagoon.Status` cover rollback and history.
|
||||
- Per-plugin migrations: `lagoon.Migrate` runs the framework's `system_files` set (`attach.Migrations`), mail set (`postcard.Migrations`, under the `summercms.postcard` history), backend admin identity set (`lagoon.BackendAdminMigrations`), `deferred_bindings` set (`lagoon.DeferredBindingMigrations`, under the `lagoon.DeferredHistoryID` history) and job-queue set (`lagoon.QueueMigrations`: River's schema pinned at `lagoon.RiverSchemaVersion`, then the `lagoon.JobsTable` record table, under the `lagoon.QueueHistoryID` history), then every `pact.HasMigrations` set in plugin activation order, each in its own `summer_migrations_<plugin_id>` history table (`lagoon.HistoryTableName`). `lagoon.RollbackLast` and `lagoon.Status` cover rollback and history.
|
||||
- Mass assignment: `lagoon.Fill` copies only allow-listed keys onto a model by GORM column name and silently drops the rest, logging each dropped key once outside production. A `json.Number` (from a decoder using `UseNumber`) fills integer, unsigned and float fields. A value that does not fit its column (a fraction, an exponent or an overflow for an integer field, or a value of the wrong type) is a `lagoon.FillTypeError` naming the key, so a caller can answer it as a validation failure on that field. `lagoon.HasFillable` and `lagoon.HasHidden` are the Go forms of `$fillable` and `$hidden`.
|
||||
- Validation: `lagoon.Validate` (where `required` fails on a zero date or time) accepts Laravel-style rule strings (`required`, `nullable`, `integer`, `numeric`, `between`, `min`, `max`, `in`, `unique`, `boolean`, `email`, `string`, `url`, `confirmed`, `different`, `mimes`) and returns a field-to-messages map, translated through phrasebook when a translator is given. Unknown rule tokens are an error. `string` requires a string value (a pointer to one included) and `url` a URL matching Laravel's pattern, the one `lagoon.ValidateRequest` uses; both skip an empty or blank value, which is left to `required`. On a field without `integer` or `numeric`, `min` and `max` compare the length in characters of a string or of a number's decimal form (the `lagoon::validation` messages `max.string`, `min.string`) and the element count of a slice or map (`max.array`, `min.array`); an empty or blank value, a boolean and a date are not measured, and a bound that is not a whole number is an error. A failed numeric range reports the bound that failed: the `min` message below the lower bound, the `max` message above the upper one, and the numeric `between` message when the bound came from `between`.
|
||||
- Request validation: `lagoon.ValidateRequest` reproduces Laravel 9 request validation for ported API endpoints, so a 422 body matches the PHP one message for message. It takes the decoded input and an ordered `lagoon.RequestRule` table (attribute names may hold `*` wildcards, expanded against the input to `posts.0.title`), runs the rules of each attribute in order and stops an attribute after a failed implicit rule (`required`, `present`, `filled`, `accepted`) or, under `bail`, after any failure. A non-implicit rule is skipped for an absent attribute, a blank string, a null value under `nullable` and an absent key under `sometimes`. Supported rules: `required`, `present`, `filled`, `accepted`, `nullable`, `sometimes`, `bail`, `array`, `string`, `integer`, `numeric`, `boolean`, `email` (PHP `FILTER_VALIDATE_EMAIL`, WinterCMS's default), `url`, `date`, `after`, `after_or_equal`, `before`, `before_or_equal` (a date, a relative word such as `tomorrow`, or another field), `exists:table,column`, `regex`, `not_regex`, `in`, `not_in`, `file`, `image`, `mimes`, `min`, `max`, `size`, `between` and `prohibited` (fails for any value `required` would accept, `0` and `false` included; not implicit, so an absent key, `null`, a blank string and an empty array pass, and with no catalog line its message is the key `validation.prohibited`), plus closure rules built with `lagoon.CustomRule`. The size rules compare the number under `numeric` or `integer` (exactly, as decimals), the element count of an array, kilobytes of a `lagoon.UploadedFile`, and otherwise the length in characters, and pick the matching message. Messages come from the `lagoon::validation` catalog in the request locale; `lagoon.ErrorKeys` gives the attribute order of PHP's message bag.
|
||||
@@ -265,7 +265,7 @@ storage:
|
||||
|
||||
| Command | Flags | Description |
|
||||
|---------|-------|-------------|
|
||||
| `migrate` | `--pretend`, `--force` | Runs the framework migrations (`system_files`, the backend admin tables, `deferred_bindings` and the job queue), then each plugin's migrations in dependency order; prints `<set>: N applied` per set and `Applied N migrations`, or `Nothing to migrate`. The applied lines count what was actually applied: when a migration fails, `migrate` prints the lines for the sets applied before it, then the error, and no `Applied` line. If the history cannot be re-read after a successful run, `migrate` warns and counts every pending migration as applied (exit 0). `--pretend` prints each pending migration as `<plugin>: <id>` and `N migrations would run`, and applies nothing. In production on an interactive terminal it asks first (`--force` skips the question); off a terminal it never asks. |
|
||||
| `migrate` | `--pretend`, `--force` | Runs the framework migrations (`system_files`, the mail tables, the backend admin tables, `deferred_bindings` and the job queue), then each plugin's migrations in dependency order; prints `<set>: N applied` per set and `Applied N migrations`, or `Nothing to migrate`. The applied lines count what was actually applied: when a migration fails, `migrate` prints the lines for the sets applied before it, then the error, and no `Applied` line. If the history cannot be re-read after a successful run, `migrate` warns and counts every pending migration as applied (exit 0). `--pretend` prints each pending migration as `<plugin>: <id>` and `N migrations would run`, and applies nothing. In production on an interactive terminal it asks first (`--force` skips the question); off a terminal it never asks. |
|
||||
| `migrate:rollback` | `--plugin <id>`, `--pretend`, `--force` | Rolls back the last applied migration of the given plugin; without the flag, of the last activated plugin that has migrations. Prints `Rolled back <id> of <plugin>`; `--pretend` names the migration and changes nothing. Production confirmation as for `migrate`. |
|
||||
| `migrate:status` | `--json` | Prints a table of the framework's own migration sets and every plugin with migrations, with history table and applied migration IDs. `--json` prints a JSON array of every declared migration of those sets: `plugin`, `table`, `id`, `applied`. |
|
||||
| `deferred:purge` | `--days <n>`, `--pretend`, `--force` | Deletes deferred bindings older than `n` days (default `database.deferred_bindings.purge_days`, else 5), with the unattached uploads they hold (blobs after the commit) and the records created under deferral, and prints the counts. Records that were only linked are kept. Model types come from every plugin's `pact.HasModels`; the uploads bucket from the published one or `storage.uploads.bucket_url`. `--pretend` counts the bindings past the cut-off and deletes nothing; production confirmation as for `migrate`. |
|
||||
@@ -275,7 +275,7 @@ An empty `database.dsn` and an unreachable database fail with a `bonfire.WithHin
|
||||
|
||||
## Dependencies
|
||||
|
||||
- SummerCMS modules: [backpack](../backpack/README.md), [bonfire](../bonfire/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component loggers, GORM's logger), [pact](../pact/README.md), [party](../party/README.md), [phrasebook](../phrasebook/README.md) (validation messages).
|
||||
- SummerCMS modules: [backpack](../backpack/README.md), [bonfire](../bonfire/README.md), [compass](../compass/README.md), [diary](../diary/README.md) (component loggers, GORM's logger), [pact](../pact/README.md), [party](../party/README.md), [phrasebook](../phrasebook/README.md) (validation messages), [postcard](../postcard/README.md) (the mail tables' migrations).
|
||||
- Third-party: `gorm.io/gorm`, `gorm.io/driver/postgres`, `github.com/jackc/pgx/v5` (stdlib driver; `pgconn` for `lagoon.DatabaseLabel`), `github.com/go-gormigrate/gormigrate/v2`, `github.com/go-playground/validator/v10`, `github.com/riverqueue/river` (its `rivermigrate` and `riverdriver/riverdatabasesql` packages, for the River schema in `lagoon.QueueMigrations`).
|
||||
- Third-party, `attach` only: `gocloud.dev/blob` (file and memory drivers; the S3 driver `gocloud.dev/blob/s3blob` and the AWS SDK v2 only under the `summercms_s3` build tag), `github.com/disintegration/imaging` (thumbnails), `golang.org/x/image/webp` (WebP decoding).
|
||||
- Third-party, `attach/webp` only: `github.com/gen2brain/webp` (WebP encoding; through it `github.com/ebitengine/purego`), decided in `.planning/notes/2026-10-28-webp-gen2brain.md`.
|
||||
|
||||
@@ -9,6 +9,7 @@ import (
|
||||
"git.golem15.com/golem15/summercms/modules/lagoon/attach"
|
||||
"git.golem15.com/golem15/summercms/modules/pact"
|
||||
"git.golem15.com/golem15/summercms/modules/party"
|
||||
"git.golem15.com/golem15/summercms/modules/postcard"
|
||||
"github.com/go-gormigrate/gormigrate/v2"
|
||||
"gorm.io/gorm"
|
||||
)
|
||||
@@ -208,15 +209,15 @@ type MigrationRef struct {
|
||||
// migrationSet is one history table's declared migrations.
|
||||
type migrationSet struct {
|
||||
id string
|
||||
// label names the set in Migrate's errors: "system_files", "backend
|
||||
// admin", "deferred bindings", "queue" or the plugin ID.
|
||||
// label names the set in Migrate's errors: "system_files", "mail",
|
||||
// "backend admin", "deferred bindings", "queue" or the plugin ID.
|
||||
label string
|
||||
migrations []*gormigrate.Migration
|
||||
}
|
||||
|
||||
// migrationSets lists the sets Migrate applies, in its order: the framework
|
||||
// sets (system files, backend admin, deferred bindings, job queue), then each
|
||||
// plugin's HasMigrations set in plugin order.
|
||||
// sets (system files, mail, backend admin, deferred bindings, job queue),
|
||||
// then each plugin's HasMigrations set in plugin order.
|
||||
func migrationSets(gdb *gorm.DB, plugins []party.Plugin) ([]migrationSet, error) {
|
||||
sqlDB, err := gdb.DB()
|
||||
if err != nil {
|
||||
@@ -224,6 +225,7 @@ func migrationSets(gdb *gorm.DB, plugins []party.Plugin) ([]migrationSet, error)
|
||||
}
|
||||
sets := []migrationSet{
|
||||
{"summercms.attach", "system_files", attach.Migrations},
|
||||
{"summercms.postcard", "mail", postcard.Migrations},
|
||||
{"summercms.cabana", "backend admin", BackendAdminMigrations},
|
||||
{DeferredHistoryID, "deferred bindings", DeferredBindingMigrations},
|
||||
{QueueHistoryID, "queue", QueueMigrations(sqlDB)},
|
||||
|
||||
@@ -346,7 +346,7 @@ func TestMigrateStatusJSON(t *testing.T) {
|
||||
for _, line := range strings.Split(strings.TrimSpace(out), "\n")[1:] {
|
||||
sets = append(sets, strings.Fields(line)[0])
|
||||
}
|
||||
wantSets := []string{"summercms.attach", "summercms.cabana", DeferredHistoryID, QueueHistoryID, "demo.alpha", "demo.beta"}
|
||||
wantSets := []string{"summercms.attach", "summercms.postcard", "summercms.cabana", DeferredHistoryID, QueueHistoryID, "demo.alpha", "demo.beta"}
|
||||
if !slices.Equal(sets, wantSets) {
|
||||
t.Errorf("migrate:status sets = %q, want %q:\n%s", sets, wantSets, out)
|
||||
}
|
||||
|
||||
@@ -8,11 +8,11 @@ Transactional mail from plugin-owned Markdown templates and layouts, delivered t
|
||||
|
||||
## 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. It is the counterpart of WinterCMS's `Mail::send` with `views/mail/*.htm` templates and mail layouts.
|
||||
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. It is separate so mail rendering and delivery can be tested and swapped (memory, log, SMTP) without touching the code that sends.
|
||||
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:
|
||||
|
||||
@@ -28,6 +28,7 @@ Use cases:
|
||||
- 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
|
||||
@@ -98,16 +99,64 @@ func TestWelcomeMail(t *testing.T) {
|
||||
}
|
||||
```
|
||||
|
||||
### 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. |
|
||||
| `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 and brand CSS. |
|
||||
| `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`. |
|
||||
@@ -118,6 +167,14 @@ func TestWelcomeMail(t *testing.T) {
|
||||
| `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
|
||||
|
||||
@@ -151,9 +208,9 @@ mail:
|
||||
## 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).
|
||||
- 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 container).
|
||||
- Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`.
|
||||
|
||||
## Testing
|
||||
|
||||
@@ -161,4 +218,4 @@ mail:
|
||||
go test ./modules/postcard/...
|
||||
```
|
||||
|
||||
The SMTP integration test starts a Mailpit container through testcontainers-go and needs Docker. Run `go test -short ./modules/postcard/...` to skip it; the remaining tests use the memory and fail drivers and need no external services.
|
||||
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.
|
||||
|
||||
@@ -5,6 +5,7 @@ import (
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
@@ -38,24 +39,36 @@ type Options struct {
|
||||
From string
|
||||
CSS string
|
||||
BrandCSS string
|
||||
// Overrides, when set, is asked once per Send for the database
|
||||
// overrides of the template being sent. Nil sends the file versions.
|
||||
Overrides OverrideSource
|
||||
}
|
||||
|
||||
type mailer struct {
|
||||
catalog *Catalog
|
||||
driver Driver
|
||||
opts Options
|
||||
// source supplies database overrides; nil means files only.
|
||||
source OverrideSource
|
||||
// log receives override warnings and failures; nil means moduleLog.
|
||||
log *slog.Logger
|
||||
warned warnGate
|
||||
}
|
||||
|
||||
// NewMailer returns a mailer that renders from cat and delivers through driver.
|
||||
// NewMailer returns a mailer that renders from cat and delivers through
|
||||
// driver. opts.Overrides, when set, supplies database overrides per send.
|
||||
func NewMailer(cat *Catalog, driver Driver, opts Options) Mailer {
|
||||
if cat == nil {
|
||||
cat = NewCatalog()
|
||||
}
|
||||
return &mailer{catalog: cat, driver: driver, opts: opts}
|
||||
return &mailer{catalog: cat, driver: driver, opts: opts, source: opts.Overrides}
|
||||
}
|
||||
|
||||
// Send renders msg.Template and delivers it. It performs no locale selection;
|
||||
// the caller must pass the full dotted name, including any -en suffix.
|
||||
// the caller must pass the full dotted name, including any -en suffix. A
|
||||
// database override of the template is applied when the mailer has an
|
||||
// OverrideSource; an override that cannot be read or does not render is
|
||||
// logged and the file version is sent instead.
|
||||
func (m *mailer) Send(ctx context.Context, msg Message) error {
|
||||
if m == nil {
|
||||
return fmt.Errorf("postcard: mailer is nil")
|
||||
@@ -69,10 +82,7 @@ func (m *mailer) Send(ctx context.Context, msg Message) error {
|
||||
if len(msg.To) == 0 && len(msg.Cc) == 0 && len(msg.Bcc) == 0 {
|
||||
return fmt.Errorf("postcard: no recipients")
|
||||
}
|
||||
rendered, err := m.catalog.render(msg, renderOptions{
|
||||
css: m.opts.CSS,
|
||||
brandCSS: m.opts.BrandCSS,
|
||||
})
|
||||
rendered, err := m.render(ctx, msg)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
@@ -87,8 +97,101 @@ func (m *mailer) Send(ctx context.Context, msg Message) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// render renders msg with its database overrides applied. With no source, no
|
||||
// overrides, or overrides that fail to render or to pass the safety checks,
|
||||
// it renders the file version.
|
||||
func (m *mailer) render(ctx context.Context, msg Message) (RenderedMessage, error) {
|
||||
file := renderOptions{css: m.opts.CSS, brandCSS: m.opts.BrandCSS}
|
||||
if _, err := m.catalog.lookupTemplate(msg.Template); err != nil {
|
||||
return RenderedMessage{}, err
|
||||
}
|
||||
ov := m.overrides(ctx, msg.Template)
|
||||
if ov.empty() {
|
||||
return m.catalog.render(msg, file)
|
||||
}
|
||||
with := file
|
||||
with.overrides = ov
|
||||
with.warn = m.warn
|
||||
rendered, err := m.catalog.render(msg, with)
|
||||
if err == nil {
|
||||
return rendered, nil
|
||||
}
|
||||
// The override is at fault only when the file version renders; a
|
||||
// failure of both is the caller's (a bad subject, a missing variable)
|
||||
// and is returned as before.
|
||||
rendered, fileErr := m.catalog.render(msg, file)
|
||||
if fileErr != nil {
|
||||
return RenderedMessage{}, fileErr
|
||||
}
|
||||
m.logger().Error("postcard: override failed, sending the file version",
|
||||
slog.String("template", msg.Template),
|
||||
slog.String("error", err.Error()),
|
||||
)
|
||||
return rendered, nil
|
||||
}
|
||||
|
||||
// overrides asks the source once. A failed lookup (no connection, tables not
|
||||
// migrated yet) is a warning, not a send failure: the file version is sent.
|
||||
func (m *mailer) overrides(ctx context.Context, template string) Overrides {
|
||||
if m.source == nil {
|
||||
return Overrides{}
|
||||
}
|
||||
ov, err := m.source.MailOverrides(ctx, template)
|
||||
if err != nil {
|
||||
m.warn(err.Error(), "postcard: mail overrides unavailable, sending the file version",
|
||||
slog.String("template", template),
|
||||
slog.String("error", err.Error()),
|
||||
)
|
||||
return Overrides{}
|
||||
}
|
||||
return ov
|
||||
}
|
||||
|
||||
func (m *mailer) logger() *slog.Logger {
|
||||
if m.log != nil {
|
||||
return m.log
|
||||
}
|
||||
return moduleLog
|
||||
}
|
||||
|
||||
// warn logs at warning level, at most once per warnInterval per key.
|
||||
func (m *mailer) warn(key, msg string, args ...any) {
|
||||
if !m.warned.allow(key, time.Now()) {
|
||||
return
|
||||
}
|
||||
m.logger().Warn(msg, args...)
|
||||
}
|
||||
|
||||
const (
|
||||
// warnInterval is how often the same override warning is repeated.
|
||||
warnInterval = time.Minute
|
||||
// warnGateSize bounds the keys a warnGate remembers.
|
||||
warnGateSize = 64
|
||||
)
|
||||
|
||||
// warnGate rate-limits warnings by key. The zero value is ready to use.
|
||||
type warnGate struct {
|
||||
mu sync.Mutex
|
||||
last map[string]time.Time
|
||||
}
|
||||
|
||||
func (g *warnGate) allow(key string, now time.Time) bool {
|
||||
g.mu.Lock()
|
||||
defer g.mu.Unlock()
|
||||
if last, ok := g.last[key]; ok && now.Sub(last) < warnInterval {
|
||||
return false
|
||||
}
|
||||
if g.last == nil || len(g.last) >= warnGateSize {
|
||||
g.last = make(map[string]time.Time)
|
||||
}
|
||||
g.last[key] = now
|
||||
return true
|
||||
}
|
||||
|
||||
// Activate publishes an app-scoped Mailer before plugin Boot. Catalog files
|
||||
// are validated later at each plugin's Boot transition.
|
||||
// are validated later at each plugin's Boot transition. The mailer reads
|
||||
// database overrides through NewDBSource, so they apply in every process
|
||||
// that publishes a *gorm.DB on app.
|
||||
func Activate[P interface{ ID() string }](app *backpack.App, _ []P) error {
|
||||
if app == nil {
|
||||
return fmt.Errorf("postcard: app is nil")
|
||||
@@ -97,10 +200,12 @@ func Activate[P interface{ ID() string }](app *backpack.App, _ []P) error {
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
opts.Overrides = NewDBSource(app)
|
||||
m := &mailer{
|
||||
catalog: NewCatalog(),
|
||||
driver: driver,
|
||||
opts: opts,
|
||||
source: opts.Overrides,
|
||||
}
|
||||
if err := app.Publish[Mailer](m); err != nil {
|
||||
return fmt.Errorf("postcard: %w", err)
|
||||
|
||||
450
modules/postcard/override_smoke_test.go
Normal file
450
modules/postcard/override_smoke_test.go
Normal file
@@ -0,0 +1,450 @@
|
||||
package postcard
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"database/sql"
|
||||
"fmt"
|
||||
"io/fs"
|
||||
"log/slog"
|
||||
"net/url"
|
||||
"strings"
|
||||
"sync"
|
||||
"sync/atomic"
|
||||
"testing"
|
||||
"testing/fstest"
|
||||
"time"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
"github.com/go-gormigrate/gormigrate/v2"
|
||||
_ "github.com/jackc/pgx/v5/stdlib"
|
||||
tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres"
|
||||
gormpostgres "gorm.io/driver/postgres"
|
||||
"gorm.io/gorm"
|
||||
"gorm.io/gorm/logger"
|
||||
)
|
||||
|
||||
var (
|
||||
mailPGOnce sync.Once
|
||||
mailPGAdmin *sql.DB
|
||||
mailPGDSN string
|
||||
mailPGErr error
|
||||
mailPGSeq atomic.Int64
|
||||
)
|
||||
|
||||
// mailPostgres returns a GORM handle on a fresh database with
|
||||
// postcard.Migrations applied. Every call gets its own database on one
|
||||
// shared postgres:16-alpine container, so tests cannot see each other's
|
||||
// rows. It skips under -short. postcard must not import lagoon, so this
|
||||
// opens Postgres directly.
|
||||
func mailPostgres(t *testing.T) *gorm.DB {
|
||||
t.Helper()
|
||||
if testing.Short() {
|
||||
t.Skip("requires testcontainers postgres")
|
||||
}
|
||||
mailPGOnce.Do(func() {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
|
||||
defer cancel()
|
||||
ctr, err := tcpostgres.Run(ctx, "postgres:16-alpine",
|
||||
tcpostgres.WithDatabase("postcard"),
|
||||
tcpostgres.WithUsername("postcard"),
|
||||
tcpostgres.WithPassword("postcard"),
|
||||
tcpostgres.BasicWaitStrategies(),
|
||||
)
|
||||
if err != nil {
|
||||
mailPGErr = err
|
||||
return
|
||||
}
|
||||
dsn, err := ctr.ConnectionString(ctx, "sslmode=disable")
|
||||
if err != nil {
|
||||
mailPGErr = err
|
||||
return
|
||||
}
|
||||
db, err := sql.Open("pgx", dsn)
|
||||
if err != nil {
|
||||
mailPGErr = err
|
||||
return
|
||||
}
|
||||
if err := db.PingContext(ctx); err != nil {
|
||||
mailPGErr = err
|
||||
return
|
||||
}
|
||||
mailPGAdmin, mailPGDSN = db, dsn
|
||||
})
|
||||
if mailPGErr != nil {
|
||||
t.Fatalf("postgres: %v", mailPGErr)
|
||||
}
|
||||
name := fmt.Sprintf("mail_%d", mailPGSeq.Add(1))
|
||||
if _, err := mailPGAdmin.Exec("CREATE DATABASE " + name); err != nil {
|
||||
t.Fatalf("create database: %v", err)
|
||||
}
|
||||
u, err := url.Parse(mailPGDSN)
|
||||
if err != nil {
|
||||
t.Fatalf("postgres dsn: %v", err)
|
||||
}
|
||||
u.Path = "/" + name
|
||||
sqlDB, err := sql.Open("pgx", u.String())
|
||||
if err != nil {
|
||||
t.Fatalf("open %s: %v", name, err)
|
||||
}
|
||||
t.Cleanup(func() { _ = sqlDB.Close() })
|
||||
gdb, err := gorm.Open(gormpostgres.New(gormpostgres.Config{Conn: sqlDB}), &gorm.Config{Logger: logger.Discard})
|
||||
if err != nil {
|
||||
t.Fatalf("gorm open: %v", err)
|
||||
}
|
||||
if err := gormigrate.New(gdb, gormigrate.DefaultOptions, Migrations).Migrate(); err != nil {
|
||||
t.Fatalf("migrate: %v", err)
|
||||
}
|
||||
return gdb
|
||||
}
|
||||
|
||||
// acmeBlog is a fixture plugin that ships one template and one layout.
|
||||
type acmeBlog struct{}
|
||||
|
||||
func (acmeBlog) ID() string { return "acme.blog" }
|
||||
|
||||
func (acmeBlog) MailTemplatesFS() fs.FS {
|
||||
return fstest.MapFS{
|
||||
"views/mail/welcome.htm": {Data: []byte(`subject = "Welcome, {{ .name }}"
|
||||
description = "Sent after registration"
|
||||
layout = "blog"
|
||||
==
|
||||
Hi **{{ .name }}**, thanks for joining.
|
||||
`)},
|
||||
"views/mail/layouts/blog.htm": {Data: []byte(`name = "Blog"
|
||||
==
|
||||
{{ .Content }}
|
||||
|
||||
-- The Acme blog
|
||||
==
|
||||
<div class="blog-mail">{{ .Content }}</div>
|
||||
`)},
|
||||
}
|
||||
}
|
||||
|
||||
func (acmeBlog) MailTemplates() []string { return []string{"acme.blog::mail.welcome"} }
|
||||
|
||||
func (acmeBlog) MailLayouts() map[string]string {
|
||||
return map[string]string{"blog": "acme.blog::mail.layouts.blog"}
|
||||
}
|
||||
|
||||
const acmeWelcome = "acme.blog::mail.welcome"
|
||||
|
||||
// bootMailApp activates postcard on a fresh app the way party does, boots
|
||||
// the fixture plugin and returns the published mailer with its log captured.
|
||||
// gdb may be nil: the app then has no database.
|
||||
func bootMailApp(t *testing.T, gdb *gorm.DB) (*mailer, *MemoryDriver, *bytes.Buffer) {
|
||||
t.Helper()
|
||||
app := backpack.New(nil)
|
||||
if gdb != nil {
|
||||
if err := app.Publish(gdb); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
plugin := acmeBlog{}
|
||||
if err := Activate(app, []acmeBlog{plugin}); err != nil {
|
||||
t.Fatalf("Activate: %v", err)
|
||||
}
|
||||
if err := BootPlugin(app, plugin); err != nil {
|
||||
t.Fatalf("BootPlugin: %v", err)
|
||||
}
|
||||
got, ok := app.Lookup[Mailer]()
|
||||
if !ok {
|
||||
t.Fatal("mailer not published")
|
||||
}
|
||||
m, ok := got.(*mailer)
|
||||
if !ok {
|
||||
t.Fatalf("published mailer is %T", got)
|
||||
}
|
||||
drv, ok := m.driver.(*MemoryDriver)
|
||||
if !ok {
|
||||
t.Fatalf("driver is %T, want the memory driver", m.driver)
|
||||
}
|
||||
var logs bytes.Buffer
|
||||
m.log = slog.New(slog.NewTextHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug}))
|
||||
return m, drv, &logs
|
||||
}
|
||||
|
||||
// customizeWelcome turns the welcome template's index row into an override.
|
||||
// layoutCode names the layout row to point at; empty leaves layout_id NULL.
|
||||
func customizeWelcome(t *testing.T, gdb *gorm.DB, subject, body, layoutCode string) {
|
||||
t.Helper()
|
||||
var layoutID any
|
||||
if layoutCode != "" {
|
||||
var id int64
|
||||
if err := gdb.Raw(`INSERT INTO `+LayoutsTable+` (code, source, name) VALUES (?, 'acme.blog', 'Blog')
|
||||
ON CONFLICT (code) DO UPDATE SET name = EXCLUDED.name RETURNING id`, layoutCode).Scan(&id).Error; err != nil {
|
||||
t.Fatalf("layout row: %v", err)
|
||||
}
|
||||
layoutID = id
|
||||
}
|
||||
err := gdb.Exec(`INSERT INTO `+TemplatesTable+` (code, source, subject, body, layout_id, is_custom, customized_at)
|
||||
VALUES (?, 'acme.blog', ?, ?, ?, TRUE, NOW())
|
||||
ON CONFLICT (code) DO UPDATE SET subject = EXCLUDED.subject, body = EXCLUDED.body,
|
||||
layout_id = EXCLUDED.layout_id, is_custom = TRUE`, acmeWelcome, subject, body, layoutID).Error
|
||||
if err != nil {
|
||||
t.Fatalf("template row: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func sendWelcome(t *testing.T, m Mailer, subject string) {
|
||||
t.Helper()
|
||||
err := m.Send(context.Background(), Message{
|
||||
Template: acmeWelcome,
|
||||
To: []string{"ada@example.com"},
|
||||
Vars: map[string]any{"name": "Ada"},
|
||||
Subject: subject,
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("Send: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func lastMessage(t *testing.T, drv *MemoryDriver) RenderedMessage {
|
||||
t.Helper()
|
||||
msgs := drv.Messages()
|
||||
if len(msgs) == 0 {
|
||||
t.Fatal("no message was sent")
|
||||
}
|
||||
return msgs[len(msgs)-1]
|
||||
}
|
||||
|
||||
// fileWelcome is what a mailer with no override source sends for the
|
||||
// fixture: the reference every fallback is compared with.
|
||||
func fileWelcome(t *testing.T) RenderedMessage {
|
||||
t.Helper()
|
||||
plugin := acmeBlog{}
|
||||
cat := NewCatalog()
|
||||
if err := cat.Register(plugin.ID(), plugin.MailTemplatesFS(), plugin.MailTemplates(), plugin.MailLayouts()); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
drv := NewMemoryDriver()
|
||||
sendWelcome(t, NewMailer(cat, drv, Options{}), "")
|
||||
return lastMessage(t, drv)
|
||||
}
|
||||
|
||||
// TestMailOverrideSmoke is the tracer of the database override layer: a
|
||||
// process that only ran postcard.Activate (no admin module) and published a
|
||||
// *gorm.DB sends a customized row instead of the plugin's file, and anything
|
||||
// wrong with that row or with the database degrades to the file version.
|
||||
func TestMailOverrideSmoke(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("requires testcontainers postgres")
|
||||
}
|
||||
file := fileWelcome(t)
|
||||
if file.Subject != "Welcome, Ada" || !strings.Contains(file.HTML, `<div class="blog-mail"><p>Hi <strong>Ada</strong>`) {
|
||||
t.Fatalf("file version = %+v", file)
|
||||
}
|
||||
|
||||
t.Run("override", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
customizeWelcome(t, gdb, "Hello {{ .name }}", "Good to see you, *{{ .name }}*.", "acme.blog::mail.layouts.blog")
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != "Hello Ada" {
|
||||
t.Errorf("subject = %q, want the override's", got.Subject)
|
||||
}
|
||||
if !strings.Contains(got.HTML, `<div class="blog-mail"><p>Good to see you, <em>Ada</em>.</p>`) {
|
||||
t.Errorf("HTML = %q, want the override body in the blog layout", got.HTML)
|
||||
}
|
||||
if got.Text != "Good to see you, *Ada*.\n\n-- The Acme blog" {
|
||||
t.Errorf("text = %q", got.Text)
|
||||
}
|
||||
if logs.Len() != 0 {
|
||||
t.Errorf("unexpected log output:\n%s", logs)
|
||||
}
|
||||
|
||||
// No cache: an edit and a reset are both effective on the next send.
|
||||
customizeWelcome(t, gdb, "Second {{ .name }}", "Edited.", "acme.blog::mail.layouts.blog")
|
||||
sendWelcome(t, m, "")
|
||||
if got := lastMessage(t, drv); got.Subject != "Second Ada" {
|
||||
t.Errorf("subject after an edit = %q", got.Subject)
|
||||
}
|
||||
if err := gdb.Exec(`UPDATE `+TemplatesTable+` SET is_custom = FALSE WHERE code = ?`, acmeWelcome).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
sendWelcome(t, m, "")
|
||||
if got := lastMessage(t, drv); got.Subject != file.Subject || got.HTML != file.HTML || got.Text != file.Text {
|
||||
t.Errorf("after is_custom was cleared the row still applies: %+v", got)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("override_layout", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
// The override moves the template to postcard's default layout.
|
||||
customizeWelcome(t, gdb, "Hello", "Plain.", defaultLayoutName)
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if !strings.Contains(got.HTML, `<div class="content-body"><p>Plain.</p>`) || strings.Contains(got.HTML, "blog-mail") {
|
||||
t.Errorf("HTML = %q, want the default layout", got.HTML)
|
||||
}
|
||||
if logs.Len() != 0 {
|
||||
t.Errorf("unexpected log output:\n%s", logs)
|
||||
}
|
||||
|
||||
// A layout code that names nothing renders with the default layout
|
||||
// and says so.
|
||||
customizeWelcome(t, gdb, "Hello", "Plain.", "gone")
|
||||
sendWelcome(t, m, "")
|
||||
got = lastMessage(t, drv)
|
||||
if !strings.Contains(got.HTML, `<div class="content-body"><p>Plain.</p>`) {
|
||||
t.Errorf("HTML = %q, want the default layout for an unknown layout code", got.HTML)
|
||||
}
|
||||
if !strings.Contains(logs.String(), "level=WARN") || !strings.Contains(logs.String(), "unknown layout") || !strings.Contains(logs.String(), "layout=gone") {
|
||||
t.Errorf("log = %q, want a warning naming the layout", logs)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("file", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != file.Subject || got.HTML != file.HTML || got.Text != file.Text {
|
||||
t.Errorf("without a row the mail differs from the file version:\n got %+v\nwant %+v", got, file)
|
||||
}
|
||||
|
||||
// A row that is not customized (an index row) changes nothing.
|
||||
if err := gdb.Exec(`INSERT INTO `+TemplatesTable+` (code, source, subject, body) VALUES (?, 'acme.blog', 'Mirror', 'Mirror')`, acmeWelcome).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
sendWelcome(t, m, "")
|
||||
got = lastMessage(t, drv)
|
||||
if got.Subject != file.Subject || got.HTML != file.HTML || got.Text != file.Text {
|
||||
t.Errorf("a row with is_custom false changed the mail: %+v", got)
|
||||
}
|
||||
if logs.Len() != 0 {
|
||||
t.Errorf("unexpected log output:\n%s", logs)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("fallback", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
cases := map[string]string{
|
||||
// A field of a variable the caller does not pass fails at execution.
|
||||
"runtime": "Order {{ .order.code }}",
|
||||
// A body that does not parse.
|
||||
"parse": "Hi {{ .name",
|
||||
// A body that renders but fails the safety checks on the result.
|
||||
"unsafe": "Type javascript: in the address bar.",
|
||||
}
|
||||
for name, body := range cases {
|
||||
logs.Reset()
|
||||
customizeWelcome(t, gdb, "Hello {{ .name }}", body, "acme.blog::mail.layouts.blog")
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != file.Subject || got.HTML != file.HTML || got.Text != file.Text {
|
||||
t.Errorf("%s: a failing override did not fall back to the file version: %+v", name, got)
|
||||
}
|
||||
out := logs.String()
|
||||
if !strings.Contains(out, "level=ERROR") || !strings.Contains(out, "postcard: override failed, sending the file version") ||
|
||||
!strings.Contains(out, "template="+acmeWelcome) || !strings.Contains(out, "error=") {
|
||||
t.Errorf("%s: log = %q, want the override failure with template and error", name, out)
|
||||
}
|
||||
}
|
||||
|
||||
// A subject override with a line break is refused the same way.
|
||||
logs.Reset()
|
||||
customizeWelcome(t, gdb, "Hello\nBcc: all@example.com", "Fine.", "acme.blog::mail.layouts.blog")
|
||||
sendWelcome(t, m, "")
|
||||
if got := lastMessage(t, drv); got.Subject != file.Subject || got.HTML != file.HTML {
|
||||
t.Errorf("a subject override with a line break was sent: %+v", got)
|
||||
}
|
||||
if !strings.Contains(logs.String(), "CR/LF") {
|
||||
t.Errorf("log = %q, want the CR/LF refusal", logs)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("caller_subject", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, _ := bootMailApp(t, gdb)
|
||||
customizeWelcome(t, gdb, "Hello {{ .name }}", "Override body.", "acme.blog::mail.layouts.blog")
|
||||
sendWelcome(t, m, "From the caller, {{ .name }}")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != "From the caller, Ada" {
|
||||
t.Errorf("subject = %q, want the caller's", got.Subject)
|
||||
}
|
||||
if !strings.Contains(got.HTML, "Override body.") {
|
||||
t.Errorf("HTML = %q, want the override body next to the caller's subject", got.HTML)
|
||||
}
|
||||
|
||||
// A caller subject that is refused fails the send as before, and is
|
||||
// not blamed on the override.
|
||||
before := len(drv.Messages())
|
||||
err := m.Send(context.Background(), Message{
|
||||
Template: acmeWelcome,
|
||||
To: []string{"ada@example.com"},
|
||||
Subject: "Hi\r\nBcc: all@example.com",
|
||||
})
|
||||
if err == nil || !strings.Contains(err.Error(), "CR/LF") {
|
||||
t.Errorf("Send with a CR/LF caller subject = %v", err)
|
||||
}
|
||||
if len(drv.Messages()) != before {
|
||||
t.Error("a refused message was sent")
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("missing_table", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
m, drv, logs := bootMailApp(t, gdb)
|
||||
customizeWelcome(t, gdb, "Hello", "Override.", "")
|
||||
if err := gdb.Exec(`DROP TABLE ` + TemplatesTable).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for range 3 {
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != file.Subject || got.HTML != file.HTML || got.Text != file.Text {
|
||||
t.Fatalf("with the table missing the mail differs from the file version: %+v", got)
|
||||
}
|
||||
}
|
||||
out := logs.String()
|
||||
if n := strings.Count(out, "postcard: mail overrides unavailable, sending the file version"); n != 1 {
|
||||
t.Errorf("warning logged %d times for 3 sends, want 1 (rate-limited):\n%s", n, out)
|
||||
}
|
||||
if !strings.Contains(out, "level=WARN") || !strings.Contains(out, TemplatesTable) {
|
||||
t.Errorf("log = %q, want a warning naming the table", out)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("no_db", func(t *testing.T) {
|
||||
m, drv, logs := bootMailApp(t, nil)
|
||||
sendWelcome(t, m, "")
|
||||
got := lastMessage(t, drv)
|
||||
if got.Subject != file.Subject || got.HTML != file.HTML || got.Text != file.Text {
|
||||
t.Errorf("without a database the mail differs from the file version: %+v", got)
|
||||
}
|
||||
if logs.Len() != 0 {
|
||||
t.Errorf("unexpected log output:\n%s", logs)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("unknown_template", func(t *testing.T) {
|
||||
m, _, _ := bootMailApp(t, mailPostgres(t))
|
||||
err := m.Send(context.Background(), Message{Template: "acme.blog::mail.missing", To: []string{"ada@example.com"}})
|
||||
if err == nil || !strings.Contains(err.Error(), "unknown template acme.blog::mail.missing") {
|
||||
t.Errorf("Send of an unknown template = %v", err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("migrations_roll_back", func(t *testing.T) {
|
||||
gdb := mailPostgres(t)
|
||||
mig := gormigrate.New(gdb, gormigrate.DefaultOptions, Migrations)
|
||||
if err := mig.RollbackLast(); err != nil {
|
||||
t.Fatalf("rollback: %v", err)
|
||||
}
|
||||
var n int64
|
||||
if err := gdb.Raw(`SELECT COUNT(*) FROM information_schema.tables WHERE table_name LIKE 'system_mail_%'`).Scan(&n).Error; err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if n != 0 {
|
||||
t.Errorf("%d mail tables left after the rollback", n)
|
||||
}
|
||||
if err := mig.Migrate(); err != nil {
|
||||
t.Fatalf("migrate again: %v", err)
|
||||
}
|
||||
})
|
||||
}
|
||||
221
modules/postcard/store.go
Normal file
221
modules/postcard/store.go
Normal file
@@ -0,0 +1,221 @@
|
||||
package postcard
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"git.golem15.com/golem15/summercms/modules/backpack"
|
||||
"github.com/go-gormigrate/gormigrate/v2"
|
||||
"gorm.io/gorm"
|
||||
"gorm.io/gorm/logger"
|
||||
)
|
||||
|
||||
// The mail tables postcard owns. Admin code builds its models over these
|
||||
// names; postcard itself reads them with plain SQL.
|
||||
const (
|
||||
// TemplatesTable holds one row per mail template.
|
||||
TemplatesTable = "system_mail_templates"
|
||||
// LayoutsTable holds one row per mail layout, file-backed or database-only.
|
||||
LayoutsTable = "system_mail_layouts"
|
||||
// PartialsTable holds one row per mail partial.
|
||||
PartialsTable = "system_mail_partials"
|
||||
// BrandTable holds the mail branding settings (a single row, id 1).
|
||||
BrandTable = "system_mail_brand_settings"
|
||||
// ImageLibraryTable holds the one row the mail image library attaches
|
||||
// its files to.
|
||||
ImageLibraryTable = "system_mail_image_library"
|
||||
)
|
||||
|
||||
// Migrations creates the mail tables. lagoon runs it as a framework set
|
||||
// under the summercms.postcard history, after the system_files set.
|
||||
//
|
||||
// A row is an override only while is_custom is true. file_hash is the hash
|
||||
// of the current file and base_hash the hash of the file the override was
|
||||
// written against, so a customized row is outdated when the two differ.
|
||||
var Migrations = []*gormigrate.Migration{
|
||||
{
|
||||
ID: "202611060001_create_system_mail_tables",
|
||||
Migrate: func(tx *gorm.DB) error {
|
||||
stmts := []string{
|
||||
`CREATE TABLE ` + LayoutsTable + ` (
|
||||
id SERIAL PRIMARY KEY,
|
||||
code TEXT NOT NULL UNIQUE,
|
||||
source TEXT,
|
||||
name TEXT NOT NULL,
|
||||
content_html TEXT NOT NULL DEFAULT '',
|
||||
content_text TEXT NOT NULL DEFAULT '',
|
||||
content_css TEXT NOT NULL DEFAULT '',
|
||||
is_custom BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
file_hash TEXT,
|
||||
base_hash TEXT,
|
||||
customized_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)`,
|
||||
`CREATE TABLE ` + TemplatesTable + ` (
|
||||
id SERIAL PRIMARY KEY,
|
||||
code TEXT NOT NULL UNIQUE,
|
||||
source TEXT NOT NULL,
|
||||
locale TEXT,
|
||||
description TEXT NOT NULL DEFAULT '',
|
||||
subject TEXT NOT NULL DEFAULT '',
|
||||
body TEXT NOT NULL DEFAULT '',
|
||||
layout_id INTEGER REFERENCES ` + LayoutsTable + `(id) ON DELETE RESTRICT,
|
||||
is_custom BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
file_hash TEXT,
|
||||
base_hash TEXT,
|
||||
customized_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)`,
|
||||
`CREATE INDEX ` + TemplatesTable + `_layout_id_index ON ` + TemplatesTable + ` (layout_id)`,
|
||||
`CREATE TABLE ` + PartialsTable + ` (
|
||||
id SERIAL PRIMARY KEY,
|
||||
code TEXT NOT NULL UNIQUE,
|
||||
source TEXT NOT NULL,
|
||||
name TEXT NOT NULL DEFAULT '',
|
||||
content_html TEXT NOT NULL DEFAULT '',
|
||||
content_text TEXT NOT NULL DEFAULT '',
|
||||
is_custom BOOLEAN NOT NULL DEFAULT FALSE,
|
||||
file_hash TEXT,
|
||||
base_hash TEXT,
|
||||
customized_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)`,
|
||||
`CREATE TABLE ` + BrandTable + ` (
|
||||
id INTEGER PRIMARY KEY,
|
||||
logo_file_id INTEGER,
|
||||
body_bg TEXT NOT NULL DEFAULT '',
|
||||
content_bg TEXT NOT NULL DEFAULT '',
|
||||
header_color TEXT NOT NULL DEFAULT '',
|
||||
footer_color TEXT NOT NULL DEFAULT '',
|
||||
heading_color TEXT NOT NULL DEFAULT '',
|
||||
text_color TEXT NOT NULL DEFAULT '',
|
||||
link_color TEXT NOT NULL DEFAULT '',
|
||||
button_text_color TEXT NOT NULL DEFAULT '',
|
||||
button_primary_bg TEXT NOT NULL DEFAULT '',
|
||||
button_positive_bg TEXT NOT NULL DEFAULT '',
|
||||
button_negative_bg TEXT NOT NULL DEFAULT '',
|
||||
panel_bg TEXT NOT NULL DEFAULT '',
|
||||
table_border_color TEXT NOT NULL DEFAULT '',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)`,
|
||||
`CREATE TABLE ` + ImageLibraryTable + ` (
|
||||
id SERIAL PRIMARY KEY,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)`,
|
||||
}
|
||||
for _, stmt := range stmts {
|
||||
if err := tx.Exec(stmt).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
},
|
||||
Rollback: func(tx *gorm.DB) error {
|
||||
// Templates first: they reference layouts.
|
||||
for _, table := range []string{ImageLibraryTable, BrandTable, PartialsTable, TemplatesTable, LayoutsTable} {
|
||||
if err := tx.Exec("DROP TABLE IF EXISTS " + table).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
// OverrideSource supplies the database overrides one render needs.
|
||||
type OverrideSource interface {
|
||||
// MailOverrides returns the overrides for one send of template. An
|
||||
// empty template asks for everything except a template override. A nil
|
||||
// or empty field means the file version is used.
|
||||
MailOverrides(ctx context.Context, template string) (Overrides, error)
|
||||
}
|
||||
|
||||
// Overrides is what an OverrideSource returns for one render.
|
||||
type Overrides struct {
|
||||
// Template is the customized subject, body and layout of the template
|
||||
// being sent, or nil.
|
||||
Template *TemplateOverride
|
||||
// Layouts holds layout content by layout code.
|
||||
Layouts map[string]LayoutOverride
|
||||
// Partials holds partial content by partial name.
|
||||
Partials map[string]PartialOverride
|
||||
}
|
||||
|
||||
// empty reports whether o changes nothing about a render.
|
||||
func (o Overrides) empty() bool {
|
||||
return o.Template == nil && len(o.Layouts) == 0 && len(o.Partials) == 0
|
||||
}
|
||||
|
||||
// TemplateOverride replaces a template's subject, body and layout.
|
||||
type TemplateOverride struct {
|
||||
Subject string
|
||||
Body string
|
||||
// Layout is a layout code: the full name of a file layout or the code
|
||||
// of a database-only one. Empty keeps the file's layout.
|
||||
Layout string
|
||||
}
|
||||
|
||||
// LayoutOverride replaces a layout's wrappers and adds its CSS.
|
||||
type LayoutOverride struct {
|
||||
Name string
|
||||
HTML string
|
||||
Text string
|
||||
CSS string
|
||||
}
|
||||
|
||||
// PartialOverride replaces a partial's HTML and text sections.
|
||||
type PartialOverride struct {
|
||||
HTML string
|
||||
Text string
|
||||
}
|
||||
|
||||
// NewDBSource returns the OverrideSource that reads postcard's tables. It
|
||||
// looks the *gorm.DB up on app at every call and never caches a row, so an
|
||||
// edit is effective on the next send in every process that shares the
|
||||
// database. With no database published it returns no overrides and no error.
|
||||
func NewDBSource(app *backpack.App) OverrideSource {
|
||||
return &dbSource{app: app}
|
||||
}
|
||||
|
||||
type dbSource struct {
|
||||
app *backpack.App
|
||||
}
|
||||
|
||||
// MailOverrides implements OverrideSource. name is the template's full name.
|
||||
func (s *dbSource) MailOverrides(ctx context.Context, name string) (Overrides, error) {
|
||||
var out Overrides
|
||||
if s == nil || s.app == nil {
|
||||
return out, nil
|
||||
}
|
||||
gdb, ok := s.app.Lookup[*gorm.DB]()
|
||||
if !ok || gdb == nil {
|
||||
return out, nil
|
||||
}
|
||||
// The mailer reports a failed lookup itself, rate-limited; GORM's own
|
||||
// error line per send would repeat it for every message.
|
||||
db := gdb.Session(&gorm.Session{Logger: gdb.Logger.LogMode(logger.Silent)}).WithContext(ctx)
|
||||
if name == "" {
|
||||
return out, nil
|
||||
}
|
||||
var rows []struct {
|
||||
Subject string
|
||||
Body string
|
||||
Layout string
|
||||
}
|
||||
err := db.Raw(`SELECT t.subject, t.body, COALESCE(l.code, '') AS layout
|
||||
FROM `+TemplatesTable+` t
|
||||
LEFT JOIN `+LayoutsTable+` l ON l.id = t.layout_id
|
||||
WHERE t.code = ? AND t.is_custom`, name).Scan(&rows).Error
|
||||
if err != nil {
|
||||
return Overrides{}, fmt.Errorf("postcard: mail overrides: %w", err)
|
||||
}
|
||||
if len(rows) > 0 {
|
||||
out.Template = &TemplateOverride{Subject: rows[0].Subject, Body: rows[0].Body, Layout: rows[0].Layout}
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
@@ -317,30 +317,63 @@ func parseINI(header string) (map[string]string, error) {
|
||||
type renderOptions struct {
|
||||
css string
|
||||
brandCSS string
|
||||
// overrides are the database overrides to apply; the zero value renders
|
||||
// the file version.
|
||||
overrides Overrides
|
||||
// warn reports a problem with an override that the render recovered
|
||||
// from. key identifies the problem for rate limiting. Nil drops it.
|
||||
warn func(key, msg string, args ...any)
|
||||
}
|
||||
|
||||
// renderSource is what one render works from: a file template, or a file
|
||||
// template with its override applied.
|
||||
type renderSource struct {
|
||||
name string // template name, used in parse and execute errors
|
||||
subject string
|
||||
body string
|
||||
layout string // full layout name, the default alias, or an override's layout code
|
||||
// layoutFromOverride marks a layout an override chose: one that resolves
|
||||
// to nothing renders with the default layout instead of failing.
|
||||
layoutFromOverride bool
|
||||
}
|
||||
|
||||
// render renders msg.Template: the file version, or the file version with
|
||||
// opts.overrides applied. Both go through renderFrom.
|
||||
func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, error) {
|
||||
var out RenderedMessage
|
||||
t, err := c.lookupTemplate(msg.Template)
|
||||
if err != nil {
|
||||
return out, err
|
||||
return RenderedMessage{}, err
|
||||
}
|
||||
src := renderSource{name: t.name, subject: t.subject, body: t.body, layout: t.layout}
|
||||
if ov := opts.overrides.Template; ov != nil {
|
||||
src.subject, src.body = ov.Subject, ov.Body
|
||||
if ov.Layout != "" {
|
||||
src.layout, src.layoutFromOverride = ov.Layout, true
|
||||
}
|
||||
}
|
||||
return c.renderFrom(msg, src, opts)
|
||||
}
|
||||
|
||||
// renderFrom renders src for msg. The caller's non-empty msg.Subject wins
|
||||
// over src.subject.
|
||||
func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions) (RenderedMessage, error) {
|
||||
var out RenderedMessage
|
||||
vars := msg.Vars
|
||||
if vars == nil {
|
||||
vars = map[string]any{}
|
||||
}
|
||||
subjectSrc := t.subject
|
||||
subjectSrc := src.subject
|
||||
if strings.TrimSpace(msg.Subject) != "" {
|
||||
subjectSrc = msg.Subject
|
||||
}
|
||||
subject, err := execHTML(t.name+".subject", subjectSrc, vars)
|
||||
subject, err := execHTML(src.name+".subject", subjectSrc, vars)
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
if strings.ContainsAny(subject, "\r\n") {
|
||||
return out, fmt.Errorf("postcard: subject contains CR/LF")
|
||||
}
|
||||
markdownBody, err := execHTML(t.name+".body", t.body, vars)
|
||||
markdownBody, err := execHTML(src.name+".body", src.body, vars)
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
@@ -351,7 +384,7 @@ func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, erro
|
||||
if err := validateHTML(htmlBody); err != nil {
|
||||
return out, err
|
||||
}
|
||||
layout, err := c.lookupLayout(t.layout)
|
||||
layout, err := c.layoutFor(src, opts)
|
||||
if err != nil {
|
||||
return out, err
|
||||
}
|
||||
@@ -388,6 +421,22 @@ func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, erro
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// layoutFor returns the layout src renders in. A layout code from an
|
||||
// override that names no layout is reported through opts.warn and replaced
|
||||
// by the default layout.
|
||||
func (c *Catalog) layoutFor(src renderSource, opts renderOptions) (*parsedLayout, error) {
|
||||
layout, err := c.lookupLayout(src.layout)
|
||||
if err == nil || !src.layoutFromOverride {
|
||||
return layout, err
|
||||
}
|
||||
if opts.warn != nil {
|
||||
opts.warn("layout:"+src.name+":"+src.layout,
|
||||
"postcard: override names an unknown layout, using the default layout",
|
||||
"template", src.name, "layout", src.layout)
|
||||
}
|
||||
return c.lookupLayout(defaultLayoutAlias)
|
||||
}
|
||||
|
||||
func markdownHTML(src string) (string, error) {
|
||||
var buf bytes.Buffer
|
||||
if err := markdown.Convert([]byte(src), &buf); err != nil {
|
||||
|
||||
Reference in New Issue
Block a user