Files
summercms/modules/postcard/override_smoke_test.go
Jakub Zych 5df1ec27cf feat(postcard): mail partials, built-in layouts and layout and partial overrides
- pact.HasMailPartials: plugins declare <plugin>::mail.partials.<name>,
  loaded from views/mail/partials/<name>.htm; HasMailTemplates is unchanged
- bodies and layouts call {{ partial "name" "key" value ... }}; a call in a
  Markdown body leaves a per-render random token swapped after goldmark, so
  raw HTML stays disabled for bodies
- built-in partials button, panel, table and subcopy, built-in layouts
  system and minimal next to the unchanged default, reachable by alias
  after a plugin's own aliases
- NewDBSource also reads customized and database-only layouts and
  customized partials; a layout's CSS goes before mail.css

Plan 35-01, task 3.
2026-11-13 10:38:14 +01:00

517 lines
18 KiB
Go

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
}
// appWith returns an app that publishes gdb.
func appWith(t *testing.T, gdb *gorm.DB) *backpack.App {
t.Helper()
app := backpack.New(nil)
if err := app.Publish(gdb); err != nil {
t.Fatal(err)
}
return app
}
// 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 code = EXCLUDED.code 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("layouts_and_partials", func(t *testing.T) {
gdb := mailPostgres(t)
m, drv, logs := bootMailApp(t, gdb)
stmts := []string{
// A customized file layout, a database-only layout and an index
// row that is not customized.
`INSERT INTO ` + LayoutsTable + ` (code, source, name, content_html, content_text, content_css, is_custom) VALUES
('acme.blog::mail.layouts.blog', 'acme.blog', 'Blog', '<div class="custom-blog">{{ .Content }}</div><style>{{ .css }}</style>', '[custom] {{ .Content }}', '.custom{margin:0}', TRUE),
('promo', NULL, 'Promo', '<div class="promo">{{ .Content }}{{ partial "button" "url" "https://example.com" "body" "Shop" }}</div>', 'PROMO {{ .Content }}', '', TRUE),
('` + defaultLayoutName + `', 'postcard', 'Default', '<div class="mirror">{{ .Content }}</div>', 'MIRROR {{ .Content }}', '', FALSE)`,
// A customized built-in partial.
`INSERT INTO ` + PartialsTable + ` (code, source, name, content_html, content_text, is_custom) VALUES
('postcard::mail.partials.button', 'postcard', 'Button', '<a class="btn" href="{{ .url }}">{{ .body }}</a>', '{{ .body }}: {{ .url }}', TRUE),
('postcard::mail.partials.panel', 'postcard', 'Panel', 'mirror', 'mirror', FALSE)`,
}
for _, stmt := range stmts {
if err := gdb.Exec(stmt).Error; err != nil {
t.Fatal(err)
}
}
// With no template row the file template is sent in its customized layout.
sendWelcome(t, m, "")
got := lastMessage(t, drv)
if got.Subject != file.Subject || !strings.Contains(got.HTML, `<div class="custom-blog"><p>Hi <strong>Ada</strong>`) ||
!strings.Contains(got.HTML, "<style>.custom{margin:0}</style>") || !strings.HasPrefix(got.Text, "[custom] Hi **Ada**") {
t.Errorf("customized file layout: %+v", got)
}
// A template override on the database-only layout, which calls the
// customized partial.
customizeWelcome(t, gdb, "Sale", "Now.", "promo")
sendWelcome(t, m, "")
got = lastMessage(t, drv)
if got.Subject != "Sale" || !strings.Contains(got.HTML, `<div class="promo"><p>Now.</p>`+"\n"+`<a class="btn" href="https://example.com">Shop</a></div>`) {
t.Errorf("database-only layout: %+v", got)
}
if got.Text != "PROMO Now." {
t.Errorf("database-only layout: text = %q", got.Text)
}
// An empty template name asks for everything except a template override.
all, err := NewDBSource(appWith(t, gdb)).MailOverrides(context.Background(), "")
if err != nil {
t.Fatal(err)
}
if all.Template != nil || len(all.Layouts) != 2 || len(all.Partials) != 1 {
t.Errorf("overrides without a template name = %+v", all)
}
if l := all.Layouts["promo"]; l.Name != "Promo" || !strings.HasPrefix(l.Text, "PROMO") {
t.Errorf("promo layout = %+v", l)
}
if logs.Len() != 0 {
t.Errorf("unexpected log output:\n%s", 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)
}
})
}