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.
This commit is contained in:
Jakub Zych
2026-11-13 10:38:14 +01:00
parent 7e5d2c74af
commit 5df1ec27cf
17 changed files with 1273 additions and 71 deletions

View File

@@ -8,7 +8,7 @@ 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. 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.
postcard is the mail layer of SummerCMS. Plugins that implement `pact.HasMailTemplates` ship WinterCMS-shaped mail files under `views/mail/`, and plugins that implement `pact.HasMailPartials` ship reusable blocks for them; at boot, `postcard.Activate` publishes one app-scoped `postcard.Mailer` built from the compass `mail.*` config, and `postcard.BootPlugin` registers each plugin's templates, layouts and partials 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, layout or partial has a customized row, the mailer uses 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
@@ -24,11 +24,12 @@ Use cases:
- 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.
- 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). Three layouts are built in and usable from any plugin's templates: `default`, `system` and `minimal`.
- Partials: reusable blocks named `<plugin>::mail.partials.<name>`, loaded from `views/mail/partials/<name>.htm` and declared through `pact.HasMailPartials`. Bodies and layouts call them with `{{ partial "<name>" "key" value }}`. The partials `button`, `panel`, `table` and `subcopy` are 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.
- Database overrides: a customized row of `system_mail_templates` replaces a template's subject, body and layout, a customized row of `system_mail_layouts` or `system_mail_partials` replaces a layout or a partial, and `system_mail_layouts` also holds layouts that exist only in the database. The mailer reads them 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
@@ -99,6 +100,83 @@ func TestWelcomeMail(t *testing.T) {
}
```
### Partials
A partial is a block of mail that several templates and layouts share, such as a button. Its file has the layout format: a header with a `name`, a `==` line, the text section, a `==` line, then the HTML section. A plugin ships `views/mail/partials/note.htm`:
```text
name = "Note"
==
NOTE: {{ .text }}
==
<div class="note">{{ .text }}</div>
```
and declares it next to its templates:
```go
package blog
import (
"embed"
"io/fs"
"git.golem15.com/golem15/summercms/modules/pact"
)
//go:embed views/mail
var mailFS embed.FS
type Plugin struct{}
var _ pact.HasMailPartials = Plugin{}
func (Plugin) ID() string { return "acme.blog" }
func (Plugin) MailPartialsFS() fs.FS { return mailFS }
func (Plugin) MailPartials() []string {
return []string{"acme.blog::mail.partials.note"}
}
```
A name must be in the plugin's own namespace and under `mail.partials.`; a name outside either, a missing file or a duplicate fails `postcard.BootPlugin` with the dotted name. A plugin may implement `pact.HasMailPartials` without `pact.HasMailTemplates`, and any plugin's templates may call its partials.
A template body or a layout calls a partial with its name followed by pairs of a key and a value, which become the partial's variables:
```text
subject = "Your order {{ .code }}"
==
Thanks for your order.
{{ partial "button" "url" .link "body" "Track the order" "type" "positive" }}
{{ partial "acme.blog::mail.partials.note" "text" .note }}
```
A bare name such as `button` is one of postcard's built-in partials; a plugin's partial is called by its full name. The HTML section goes into the HTML part and the text section into the plain-text part. An unknown name, an odd number of key and value arguments or a key that is not a string fails the render with the partial's name.
Inside a partial's HTML section, `{{ markdown .body }}` renders a value as Markdown, tables included; in the text section it returns the value unchanged. A partial cannot call `partial`.
Markdown drops raw HTML, so a call in a body does not insert the partial's HTML directly. It leaves a token of letters and digits, `MAILPARTIAL` followed by a random value drawn for that one render, and postcard swaps the token for the rendered partial after the body has been converted. A variable's value cannot contain that token, so text that only looks like one stays text. Put a call on its own line, with blank lines around it, to get the partial as a block of its own. Markdown rendering of bodies is unchanged: raw HTML in a body is still dropped.
### Built-in layouts and partials
| Layout alias | Full name | Renders |
|--------------|-----------|---------|
| `default` | `postcard::mail.layouts.default` | The message in a `content-body` block. Used when a template names no layout. |
| `system` | `postcard::mail.layouts.system` | WinterCMS's system layout: the message in a centred table, followed by a note that the message is automatic. |
| `minimal` | `postcard::mail.layouts.minimal` | The message directly in the page body. |
A template selects one with `layout = "system"`. A plugin's own alias of the same name wins, except `default`, which plugins cannot redefine. Every built-in layout has the `{{ .brandCss }}{{ .css }}` style block.
| Partial | Arguments | Renders |
|---------|-----------|---------|
| `button` | `url`, `body`, `type` (`primary` by default, `positive` or `negative`) | A link styled as a button (`button button-<type>`); in text, the label and the address. |
| `panel` | `body` (Markdown) | A highlighted block (`panel`). |
| `table` | `body` (a Markdown table) | A table in a `table` block. |
| `subcopy` | `body` (Markdown) | Small print under a rule (`subcopy`). |
### 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.
@@ -111,11 +189,13 @@ The subject is taken from the first of these that is set:
2. the override's subject;
3. the file's subject.
Layouts and partials are overridden the same way. A row of `system_mail_layouts` with `is_custom` set and a full layout name in `code` replaces that layout's HTML and text wrappers; a row with another `code` is a layout that exists only in the database, which a template override can select. A layout row's `content_css` is placed before `mail.css` in the layout's `{{ .css }}` slot. A row of `system_mail_partials` with `is_custom` set replaces the HTML and text sections of the partial named in its `code`.
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 an override (of the template, its layout or a partial it calls) 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 message is sent from the files alone.
- 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:
@@ -152,14 +232,15 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
| 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.BootPlugin` | Registers a booting plugin's declared partials (`pact.HasMailPartials`) and its templates and layouts (`pact.HasMailTemplates`) 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` | Registered templates, layouts and partials, including the built-in ones. |
| `postcard.NewCatalog` | Returns a catalog holding the built-in layouts and partials and no template. |
| `postcard.Catalog.Register` | Loads a plugin's templates and layout aliases from an `fs.FS`. |
| `postcard.Catalog.RegisterPartials` | Loads a plugin's partials 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. |
@@ -170,8 +251,8 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
| `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.LayoutOverride` | A layout's name, HTML wrapper, text wrapper and CSS from the database. In `postcard.Overrides.Layouts` under a file layout's full name it replaces that layout; under another code it is a database-only layout. |
| `postcard.PartialOverride` | A partial's HTML and text sections from the database, in `postcard.Overrides.Partials` under the partial's full name. |
| `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. |
@@ -208,8 +289,8 @@ 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), `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`.
- Third-party: `github.com/wneessen/go-mail` (SMTP), `github.com/yuin/goldmark` (Markdown, and its table extension inside partials), `gorm.io/gorm` (reading overrides), `github.com/go-gormigrate/gormigrate/v2` (the mail tables' migrations).
- Standard library: `bytes`, `context`, `crypto/rand`, `database/sql`, `embed`, `encoding/hex`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `strconv`, `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

View File

@@ -0,0 +1,14 @@
name = "Minimal"
==
{{ .Content }}
==
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style type="text/css">{{ .brandCss }}{{ .css }}</style>
</head>
<body>
{{ .Content }}
</body>
</html>

View File

@@ -0,0 +1,17 @@
name = "Button"
==
{{ .body }}{{ with .url }} <{{ . }}>{{ end }}
==
<table class="action" align="center" width="100%" cellpadding="0" cellspacing="0">
<tr>
<td align="center">
<table border="0" cellpadding="0" cellspacing="0">
<tr>
<td>
<a href="{{ .url }}" class="button button-{{ if .type }}{{ .type }}{{ else }}primary{{ end }}" target="_blank">{{ .body }}</a>
</td>
</tr>
</table>
</td>
</tr>
</table>

View File

@@ -0,0 +1,17 @@
name = "Panel"
==
{{ .body }}
==
<table class="panel break-all" width="100%" cellpadding="0" cellspacing="0">
<tr>
<td class="panel-content">
<table width="100%" cellpadding="0" cellspacing="0">
<tr>
<td class="panel-item">
{{ markdown .body }}
</td>
</tr>
</table>
</td>
</tr>
</table>

View File

@@ -0,0 +1,12 @@
name = "Subcopy"
==
-----
{{ .body }}
==
<table class="subcopy" width="100%" cellpadding="0" cellspacing="0">
<tr>
<td>
{{ markdown .body }}
</td>
</tr>
</table>

View File

@@ -0,0 +1,7 @@
name = "Table"
==
{{ .body }}
==
<div class="table">
{{ markdown .body }}
</div>

View File

@@ -0,0 +1,38 @@
name = "System layout"
==
{{ .Content }}
---
This is an automatic message. Please do not reply to it.
==
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style type="text/css">{{ .brandCss }}{{ .css }}</style>
</head>
<body>
<table class="wrapper layout-system" width="100%" cellpadding="0" cellspacing="0">
<tr>
<td align="center">
<table class="content" width="100%" cellpadding="0" cellspacing="0">
<tr>
<td class="body" width="100%" cellpadding="0" cellspacing="0">
<table class="inner-body" align="center" width="570" cellpadding="0" cellspacing="0">
<tr>
<td class="content-cell">
{{ .Content }}
{{ partial "subcopy" "body" "**This is an automatic message. Please do not reply to it.**" }}
</td>
</tr>
</table>
</td>
</tr>
</table>
</td>
</tr>
</table>
</body>
</html>

View File

@@ -271,11 +271,14 @@ func loggerFromApp(app *backpack.App) *slog.Logger {
return moduleLog
}
// BootPlugin registers a plugin's declared mail templates and layouts.
// Missing files and unknown layout aliases fail with the dotted name.
// BootPlugin registers a plugin's declared mail partials (pact.HasMailPartials)
// and its templates and layouts (pact.HasMailTemplates). Either capability is
// optional. Missing files, duplicates, names outside the plugin's namespace
// and unknown layout aliases fail with the dotted name.
func BootPlugin[P interface{ ID() string }](app *backpack.App, p P) error {
hm, ok := any(p).(pact.HasMailTemplates)
if !ok {
hm, hasTemplates := any(p).(pact.HasMailTemplates)
hp, hasPartials := any(p).(pact.HasMailPartials)
if !hasTemplates && !hasPartials {
return nil
}
got, ok := app.Lookup[Mailer]()
@@ -286,5 +289,13 @@ func BootPlugin[P interface{ ID() string }](app *backpack.App, p P) error {
if !ok || m == nil || m.catalog == nil {
return fmt.Errorf("postcard: mailer not published")
}
return m.catalog.Register(p.ID(), hm.MailTemplatesFS(), hm.MailTemplates(), hm.MailLayouts())
if hasPartials {
if err := m.catalog.RegisterPartials(p.ID(), hp.MailPartialsFS(), hp.MailPartials()); err != nil {
return err
}
}
if hasTemplates {
return m.catalog.Register(p.ID(), hm.MailTemplatesFS(), hm.MailTemplates(), hm.MailLayouts())
}
return nil
}

View File

@@ -165,6 +165,16 @@ func bootMailApp(t *testing.T, gdb *gorm.DB) (*mailer, *MemoryDriver, *bytes.Buf
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) {
@@ -173,7 +183,7 @@ func customizeWelcome(t *testing.T, gdb *gorm.DB, subject, body, layoutCode stri
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 {
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
@@ -297,6 +307,62 @@ func TestMailOverrideSmoke(t *testing.T) {
}
})
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)

View File

@@ -0,0 +1,226 @@
package postcard
import (
"bytes"
"crypto/rand"
"encoding/hex"
"fmt"
"html/template"
"strconv"
"strings"
texttemplate "text/template"
"github.com/yuin/goldmark"
"github.com/yuin/goldmark/extension"
)
const (
partialSegment = "mail.partials."
// builtinPartialPrefix is what a bare partial name such as "button"
// resolves under.
builtinPartialPrefix = "postcard::" + partialSegment
// partialTokenPrefix starts the placeholder a partial call leaves in a
// Markdown body until the body has been converted to HTML.
partialTokenPrefix = "MAILPARTIAL"
)
// partialMarkdown renders the argument of the markdown func inside
// partials: goldmark with tables, raw HTML still dropped.
var partialMarkdown = goldmark.New(goldmark.WithExtensions(extension.Table))
// partialError is a failed partial call. name is the partial's full name.
type partialError struct {
name string
msg string
}
func (e *partialError) Error() string {
return "postcard: " + e.msg + " " + e.name
}
// partialRun renders the partial calls of one message. Partials come from
// the catalog, with the run's overrides replacing their sections.
//
// goldmark drops raw HTML, so a call in a Markdown body cannot return its
// HTML directly. It returns a token instead, made of letters and digits
// only so that neither html/template nor goldmark changes it, and carrying
// a nonce drawn for this run so that no variable value can contain it.
// swapHTML and swapText put the rendered partial in its place afterwards.
type partialRun struct {
cat *Catalog
overrides map[string]PartialOverride
nonce string
calls []partialCall
}
// partialCall is one rendered call from a body.
type partialCall struct {
token string
html string
text string
}
func newPartialRun(cat *Catalog, overrides map[string]PartialOverride) *partialRun {
return &partialRun{cat: cat, overrides: overrides}
}
// partialName returns the full name a call refers to: a bare name is one of
// postcard's built-in partials.
func partialName(name string) string {
if strings.Contains(name, "::") {
return name
}
return builtinPartialPrefix + name
}
// sections returns the text and HTML sections of a partial, from its
// override when the run has one.
func (r *partialRun) sections(full string) (text, html string, err error) {
p, ok := r.cat.lookupPartial(full)
if !ok {
return "", "", &partialError{name: full, msg: "unknown partial"}
}
if ov, ok := r.overrides[full]; ok {
return ov.Text, ov.HTML, nil
}
return p.textWrap, p.htmlWrap, nil
}
// partialArgs turns the key/value arguments of a call into the partial's
// data.
func partialArgs(full string, kv []any) (map[string]any, error) {
if len(kv)%2 != 0 {
return nil, &partialError{name: full, msg: "arguments must be pairs of a key and a value in a call of partial"}
}
data := make(map[string]any, len(kv)/2)
for i := 0; i < len(kv); i += 2 {
key, ok := kv[i].(string)
if !ok {
return nil, &partialError{name: full, msg: "argument " + strconv.Itoa(i+1) + " is not a string key in a call of partial"}
}
data[key] = kv[i+1]
}
return data, nil
}
func (r *partialRun) renderHTML(name string, kv []any) (string, error) {
full := partialName(name)
_, src, err := r.sections(full)
if err != nil {
return "", err
}
data, err := partialArgs(full, kv)
if err != nil {
return "", err
}
out, err := execHTMLFuncs(full+".html", src, data, template.FuncMap{"markdown": partialMarkdownHTML})
if err != nil {
return "", err
}
if err := validateHTML(out); err != nil {
return "", err
}
return out, nil
}
func (r *partialRun) renderText(name string, kv []any) (string, error) {
full := partialName(name)
src, _, err := r.sections(full)
if err != nil {
return "", err
}
data, err := partialArgs(full, kv)
if err != nil {
return "", err
}
return execTextFuncs(full+".text", src, data, texttemplate.FuncMap{"markdown": partialMarkdownText})
}
// bodyCall is the partial func of a Markdown body: it renders both sections
// now and returns the token that stands for them.
func (r *partialRun) bodyCall(name string, kv ...any) (string, error) {
html, err := r.renderHTML(name, kv)
if err != nil {
return "", err
}
text, err := r.renderText(name, kv)
if err != nil {
return "", err
}
if r.nonce == "" {
var raw [16]byte
if _, err := rand.Read(raw[:]); err != nil {
return "", fmt.Errorf("postcard: partial token: %w", err)
}
r.nonce = strings.ToUpper(hex.EncodeToString(raw[:]))
}
// X is not a hexadecimal digit: it ends the nonce and the counter, so
// one token is never the prefix of another.
token := partialTokenPrefix + r.nonce + "X" + strconv.Itoa(len(r.calls)+1) + "X"
r.calls = append(r.calls, partialCall{token: token, html: html, text: text})
return token, nil
}
// htmlCall is the partial func of a layout's HTML wrapper.
func (r *partialRun) htmlCall(name string, kv ...any) (template.HTML, error) {
out, err := r.renderHTML(name, kv)
return template.HTML(out), err
}
// textCall is the partial func of a layout's text wrapper.
func (r *partialRun) textCall(name string, kv ...any) (string, error) {
return r.renderText(name, kv)
}
// swapHTML replaces the tokens in a converted body with the partials' HTML.
// A token alone in a paragraph takes the paragraph with it.
func (r *partialRun) swapHTML(html string) string {
if len(r.calls) == 0 {
return html
}
pairs := make([]string, 0, len(r.calls)*4)
for _, c := range r.calls {
pairs = append(pairs, "<p>"+c.token+"</p>", c.html)
}
for _, c := range r.calls {
pairs = append(pairs, c.token, c.html)
}
// One pass: text a partial rendered is never scanned again.
return strings.NewReplacer(pairs...).Replace(html)
}
// swapText replaces the tokens in a body with the partials' text.
func (r *partialRun) swapText(text string) string {
if len(r.calls) == 0 {
return text
}
pairs := make([]string, 0, len(r.calls)*2)
for _, c := range r.calls {
pairs = append(pairs, c.token, c.text)
}
return strings.NewReplacer(pairs...).Replace(text)
}
// partialMarkdownHTML is the markdown func of a partial's HTML section.
func partialMarkdownHTML(v any) (template.HTML, error) {
if v == nil {
return "", nil
}
var buf bytes.Buffer
if err := partialMarkdown.Convert([]byte(fmt.Sprint(v)), &buf); err != nil {
return "", fmt.Errorf("postcard: markdown: %w", err)
}
if err := validateHTML(buf.String()); err != nil {
return "", err
}
return template.HTML(buf.String()), nil
}
// partialMarkdownText is the markdown func of a partial's text section: the
// Markdown source is the text.
func partialMarkdownText(v any) string {
if v == nil {
return ""
}
return fmt.Sprint(v)
}

View File

@@ -0,0 +1,448 @@
package postcard
import (
"context"
"io/fs"
"strings"
"testing"
"testing/fstest"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/pact"
)
// partialsPlugin is a fixture plugin that ships only mail partials.
type partialsPlugin struct {
id string
fsys fs.FS
partials []string
}
func (p partialsPlugin) ID() string { return p.id }
func (p partialsPlugin) MailPartialsFS() fs.FS { return p.fsys }
func (p partialsPlugin) MailPartials() []string { return p.partials }
// mailPlugin is a fixture plugin that ships templates and, optionally,
// partials.
type mailPlugin struct {
partialsPlugin
templates []string
layouts map[string]string
}
func (p mailPlugin) MailTemplatesFS() fs.FS { return p.fsys }
func (p mailPlugin) MailTemplates() []string { return p.templates }
func (p mailPlugin) MailLayouts() map[string]string { return p.layouts }
// templatesOnly hides the partial capability of a mailPlugin.
type templatesOnly struct{ p mailPlugin }
func (t templatesOnly) ID() string { return t.p.id }
func (t templatesOnly) MailTemplatesFS() fs.FS { return t.p.fsys }
func (t templatesOnly) MailTemplates() []string { return t.p.templates }
func (t templatesOnly) MailLayouts() map[string]string { return t.p.layouts }
var (
_ pact.HasMailPartials = partialsPlugin{}
_ pact.HasMailPartials = mailPlugin{}
_ pact.HasMailTemplates = mailPlugin{}
_ pact.HasMailTemplates = templatesOnly{}
)
// fakeOverrides is an OverrideSource with a fixed answer.
type fakeOverrides struct{ ov Overrides }
func (f fakeOverrides) MailOverrides(context.Context, string) (Overrides, error) { return f.ov, nil }
const noteHTM = `name = "Note"
==
NOTE: {{ .text }}
==
<div class="note">{{ .text }}</div>
`
func partialsFS() fstest.MapFS {
return fstest.MapFS{
"views/mail/welcome.htm": {Data: []byte("subject = \"Welcome\"\n==\nHi {{ .Name }}\n\n{{ partial \"button\" \"url\" .Link \"body\" \"Go\" }}\n\nBye\n")},
"views/mail/note.htm": {Data: []byte("subject = \"Note\"\nlayout = \"blog\"\n==\n{{ partial \"acme.blog::mail.partials.note\" \"text\" .Text }}\n")},
"views/mail/auto.htm": {Data: []byte("subject = \"Auto\"\nlayout = \"system\"\n==\nDone.\n")},
"views/mail/bare.htm": {Data: []byte("subject = \"Bare\"\nlayout = \"minimal\"\n==\nDone.\n")},
"views/mail/layouts/blog.htm": {Data: []byte(`name = "Blog"
==
{{ .Content }}
{{ partial "acme.blog::mail.partials.note" "text" "footer" }}
==
<div class="blog-mail">{{ .Content }}{{ partial "acme.blog::mail.partials.note" "text" "footer" }}</div>
<style>{{ .brandCss }}{{ .css }}</style>
`)},
"views/mail/partials/note.htm": {Data: []byte(noteHTM)},
}
}
func blogPlugin() mailPlugin {
return mailPlugin{
partialsPlugin: partialsPlugin{id: "acme.blog", fsys: partialsFS(), partials: []string{"acme.blog::mail.partials.note"}},
templates: []string{"acme.blog::mail.welcome", "acme.blog::mail.note", "acme.blog::mail.auto", "acme.blog::mail.bare"},
layouts: map[string]string{"blog": "acme.blog::mail.layouts.blog"},
}
}
// partialsMailer registers the blog fixture in a fresh catalog and returns a
// mailer over it with the given overrides.
func partialsMailer(t *testing.T, opts Options, ov *Overrides) (Mailer, *MemoryDriver) {
t.Helper()
p := blogPlugin()
cat := NewCatalog()
if err := cat.RegisterPartials(p.id, p.fsys, p.partials); err != nil {
t.Fatalf("RegisterPartials: %v", err)
}
if err := cat.Register(p.id, p.fsys, p.templates, p.layouts); err != nil {
t.Fatalf("Register: %v", err)
}
if ov != nil {
opts.Overrides = fakeOverrides{ov: *ov}
}
drv := NewMemoryDriver()
return NewMailer(cat, drv, opts), drv
}
func sendTemplate(t *testing.T, m Mailer, drv *MemoryDriver, name string, vars map[string]any) RenderedMessage {
t.Helper()
if err := m.Send(context.Background(), Message{Template: name, To: []string{"ada@example.com"}, Vars: vars}); err != nil {
t.Fatalf("Send %s: %v", name, err)
}
return lastMessage(t, drv)
}
func bootPartials[P interface{ ID() string }](t *testing.T, plugins ...P) (*backpack.App, error) {
t.Helper()
app := backpack.New(nil)
if err := Activate(app, plugins); err != nil {
t.Fatalf("Activate: %v", err)
}
for _, p := range plugins {
if err := BootPlugin(app, p); err != nil {
return app, err
}
}
return app, nil
}
// TestMailPartialsSmoke covers mail partials end to end without a database:
// the pact capability and its boot errors, partial calls in Markdown bodies
// and in layouts, the built-in layouts, and layout and partial overrides
// from an OverrideSource.
func TestMailPartialsSmoke(t *testing.T) {
t.Parallel()
t.Run("capability", func(t *testing.T) {
if _, err := bootPartials(t, blogPlugin()); err != nil {
t.Fatalf("a plugin with templates and a partial does not boot: %v", err)
}
fsys := partialsFS()
cases := []struct {
name string
partials []string
want []string
}{
{"foreign namespace", []string{"acme.other::mail.partials.note"}, []string{"not owned", "acme.other::mail.partials.note"}},
{"outside mail.partials", []string{"acme.blog::mail.note"}, []string{"acme.blog::mail.note", "mail.partials."}},
{"missing file", []string{"acme.blog::mail.partials.gone"}, []string{"missing partial acme.blog::mail.partials.gone"}},
{"duplicate", []string{"acme.blog::mail.partials.note", "acme.blog::mail.partials.note"}, []string{"duplicate partial acme.blog::mail.partials.note"}},
{"path escape", []string{"acme.blog::mail.partials.a/../b"}, []string{"invalid mail name"}},
}
for _, tc := range cases {
_, err := bootPartials(t, partialsPlugin{id: "acme.blog", fsys: fsys, partials: tc.partials})
if err == nil {
t.Errorf("%s: BootPlugin succeeded", tc.name)
continue
}
for _, want := range tc.want {
if !strings.Contains(err.Error(), want) {
t.Errorf("%s: error %q lacks %q", tc.name, err, want)
}
}
}
// The built-in names cannot be taken by a plugin.
if err := NewCatalog().RegisterPartials("postcard", fsys, []string{"postcard::mail.partials.button"}); err == nil || !strings.Contains(err.Error(), "duplicate partial") {
t.Errorf("re-registering a built-in partial = %v", err)
}
})
t.Run("partials_only_plugin", func(t *testing.T) {
// acme.kit ships only a partial; acme.blog's template calls it.
kit := partialsPlugin{id: "acme.kit", partials: []string{"acme.kit::mail.partials.badge"}, fsys: fstest.MapFS{
"views/mail/partials/badge.htm": {Data: []byte("name = \"Badge\"\n==\n[{{ .label }}]\n==\n<span class=\"badge\">{{ .label }}</span>\n")},
}}
blog := mailPlugin{
partialsPlugin: partialsPlugin{id: "acme.blog", fsys: fstest.MapFS{
"views/mail/hello.htm": {Data: []byte("subject = \"Hello\"\n==\nNew: {{ partial \"acme.kit::mail.partials.badge\" \"label\" \"beta\" }}\n")},
}},
templates: []string{"acme.blog::mail.hello"},
}
app := backpack.New(nil)
if err := Activate(app, []partialsPlugin{kit}); err != nil {
t.Fatal(err)
}
if err := BootPlugin(app, kit); err != nil {
t.Fatalf("a plugin with only partials does not boot: %v", err)
}
// blog implements both capabilities but declares no partial.
if err := BootPlugin(app, blog); err != nil {
t.Fatalf("BootPlugin blog: %v", err)
}
// A plugin with only templates still boots.
if _, err := bootPartials(t, templatesOnly{p: blog}); err != nil {
t.Fatalf("a plugin with only templates does not boot: %v", err)
}
got, _ := app.Lookup[Mailer]()
m := got.(*mailer)
msg := sendTemplate(t, m, m.driver.(*MemoryDriver), "acme.blog::mail.hello", nil)
if !strings.Contains(msg.HTML, `<p>New: <span class="badge">beta</span></p>`) {
t.Errorf("HTML = %q, want the other plugin's partial inline", msg.HTML)
}
if !strings.Contains(msg.Text, "New: [beta]") {
t.Errorf("text = %q", msg.Text)
}
})
t.Run("body", func(t *testing.T) {
m, drv := partialsMailer(t, Options{}, nil)
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", map[string]any{"Name": "Ada", "Link": "https://example.com/go?a=1&b=2"})
if strings.Contains(msg.HTML, "raw HTML omitted") {
t.Errorf("the partial was dropped by Markdown:\n%s", msg.HTML)
}
for _, want := range []string{
"<p>Hi Ada</p>\n<table class=\"action\"",
`<a href="https://example.com/go?a=1&amp;b=2" class="button button-primary" target="_blank">Go</a>`,
"</table>\n<p>Bye</p>",
} {
if !strings.Contains(msg.HTML, want) {
t.Errorf("HTML lacks %q:\n%s", want, msg.HTML)
}
}
if strings.Contains(msg.HTML, "MAILPARTIAL") || strings.Contains(msg.Text, "MAILPARTIAL") {
t.Errorf("a token was left in the message:\n%s\n%s", msg.HTML, msg.Text)
}
if msg.Text != "Hi Ada\n\nGo <https://example.com/go?a=1&b=2>\n\nBye" {
t.Errorf("text = %q", msg.Text)
}
// The type argument picks the button class.
cat := NewCatalog()
fsys := fstest.MapFS{"views/mail/b.htm": {Data: []byte("subject = \"B\"\n==\n{{ partial \"button\" \"url\" \"https://example.com\" \"body\" \"Pay\" \"type\" \"positive\" }}\n\n{{ partial \"panel\" \"body\" \"Keep **this**.\" }}\n\n{{ partial \"table\" \"body\" .Table }}\n\n{{ partial \"subcopy\" \"body\" \"Small print.\" }}\n")}}
if err := cat.Register("acme.blog", fsys, []string{"acme.blog::mail.b"}, nil); err != nil {
t.Fatal(err)
}
drv2 := NewMemoryDriver()
msg = sendTemplate(t, NewMailer(cat, drv2, Options{}), drv2, "acme.blog::mail.b", map[string]any{"Table": "| Item | Qty |\n|---|---|\n| Pen | 2 |"})
for _, want := range []string{
`class="button button-positive"`,
`<table class="panel`, "<p>Keep <strong>this</strong>.</p>",
`<div class="table">`, "<th>Item</th>", "<td>Pen</td>",
`<table class="subcopy"`, "<p>Small print.</p>",
} {
if !strings.Contains(msg.HTML, want) {
t.Errorf("built-in partials: HTML lacks %q:\n%s", want, msg.HTML)
}
}
for _, want := range []string{"Pay <https://example.com>", "Keep **this**.", "| Pen | 2 |", "-----\nSmall print."} {
if !strings.Contains(msg.Text, want) {
t.Errorf("built-in partials: text lacks %q:\n%s", want, msg.Text)
}
}
})
t.Run("forged_token", func(t *testing.T) {
m, drv := partialsMailer(t, Options{}, nil)
forged := "MAILPARTIAL1 MAILPARTIAL" + strings.Repeat("0", 32) + "X1X"
msg := sendTemplate(t, m, drv, "acme.blog::mail.welcome", map[string]any{"Name": forged, "Link": "https://example.com"})
if !strings.Contains(msg.HTML, "<p>Hi "+forged+"</p>") {
t.Errorf("a forged token in a variable was not left as text:\n%s", msg.HTML)
}
if n := strings.Count(msg.HTML, `class="button`); n != 1 {
t.Errorf("%d buttons rendered, want 1:\n%s", n, msg.HTML)
}
if !strings.Contains(msg.Text, "Hi "+forged) {
t.Errorf("text = %q", msg.Text)
}
// Tokens carry a fresh random nonce per render.
a, b := newPartialRun(NewCatalog(), nil), newPartialRun(NewCatalog(), nil)
ta, err := a.bodyCall("button", "url", "https://example.com", "body", "Go")
if err != nil {
t.Fatal(err)
}
tb, err := b.bodyCall("button", "url", "https://example.com", "body", "Go")
if err != nil {
t.Fatal(err)
}
if ta == tb {
t.Errorf("two renders produced the same token %q", ta)
}
for _, tok := range []string{ta, tb} {
if !strings.HasPrefix(tok, "MAILPARTIAL") || len(tok) < len("MAILPARTIAL")+32 || strings.Trim(tok, "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789") != "" {
t.Errorf("token %q is not MAILPARTIAL plus an alphanumeric nonce", tok)
}
}
})
t.Run("errors", func(t *testing.T) {
cases := map[string]struct {
body string
want []string
}{
"unknown": {`{{ partial "nope" "a" "b" }}`, []string{"unknown partial", "postcard::mail.partials.nope"}},
"unknown_ns": {`{{ partial "acme.blog::mail.partials.nope" }}`, []string{"unknown partial", "acme.blog::mail.partials.nope"}},
"odd": {`{{ partial "button" "url" }}`, []string{"postcard::mail.partials.button", "key and a value"}},
"key_type": {`{{ partial "button" 1 "x" }}`, []string{"postcard::mail.partials.button", "not a string"}},
"unsafe_html": {`{{ partial "panel" "body" "Type javascript: here" }}`, []string{"dangerous"}},
}
for name, tc := range cases {
cat := NewCatalog()
fsys := fstest.MapFS{"views/mail/x.htm": {Data: []byte("subject = \"X\"\n==\n" + tc.body + "\n")}}
if err := cat.Register("acme.blog", fsys, []string{"acme.blog::mail.x"}, nil); err != nil {
t.Fatalf("%s: Register: %v", name, err)
}
drv := NewMemoryDriver()
err := NewMailer(cat, drv, Options{}).Send(context.Background(), Message{Template: "acme.blog::mail.x", To: []string{"ada@example.com"}})
if err == nil {
t.Errorf("%s: Send succeeded", name)
continue
}
for _, want := range tc.want {
if !strings.Contains(err.Error(), want) {
t.Errorf("%s: error %q lacks %q", name, err, want)
}
}
if len(drv.Messages()) != 0 {
t.Errorf("%s: a message was sent", name)
}
}
// partial is not available inside a partial.
nested := fstest.MapFS{"views/mail/partials/outer.htm": {Data: []byte("name = \"Outer\"\n==\nx\n==\n{{ partial \"button\" }}\n")}}
cat := NewCatalog()
if err := cat.RegisterPartials("acme.blog", nested, []string{"acme.blog::mail.partials.outer"}); err != nil {
t.Fatal(err)
}
if _, err := newPartialRun(cat, nil).htmlCall("acme.blog::mail.partials.outer"); err == nil || !strings.Contains(err.Error(), `function "partial" not defined`) {
t.Errorf("a partial calling partial = %v", err)
}
})
t.Run("built_in_layouts", func(t *testing.T) {
m, drv := partialsMailer(t, Options{CSS: "p{color:red}", BrandCSS: ".brand{color:blue}"}, nil)
msg := sendTemplate(t, m, drv, "acme.blog::mail.auto", nil)
for _, want := range []string{
`class="wrapper layout-system"`, "<p>Done.</p>",
`<table class="subcopy"`, "<strong>This is an automatic message. Please do not reply to it.</strong>",
".brand{color:blue}", "p{color:red}",
} {
if !strings.Contains(msg.HTML, want) {
t.Errorf("system layout: HTML lacks %q:\n%s", want, msg.HTML)
}
}
if msg.Text != "Done.\n\n\n---\nThis is an automatic message. Please do not reply to it." {
t.Errorf("system layout: text = %q", msg.Text)
}
msg = sendTemplate(t, m, drv, "acme.blog::mail.bare", nil)
if !strings.Contains(msg.HTML, "<body>\n<p>Done.</p>\n\n</body>") || strings.Contains(msg.HTML, "content-body") || strings.Contains(msg.HTML, "layout-system") {
t.Errorf("minimal layout: HTML = %q", msg.HTML)
}
if !strings.Contains(msg.HTML, "<style type=\"text/css\">.brand{color:blue}p{color:red}</style>") {
t.Errorf("minimal layout: style block = %q", msg.HTML)
}
if msg.Text != "Done." {
t.Errorf("minimal layout: text = %q", msg.Text)
}
// A plugin's own alias named system wins over the built-in one.
fsys := fstest.MapFS{
"views/mail/auto.htm": {Data: []byte("subject = \"Auto\"\nlayout = \"system\"\n==\nDone.\n")},
"views/mail/layouts/system.htm": {Data: []byte("name = \"Mine\"\n==\n{{ .Content }}\n==\n<div class=\"mine\">{{ .Content }}</div>\n")},
}
cat := NewCatalog()
if err := cat.Register("acme.shop", fsys, []string{"acme.shop::mail.auto"}, map[string]string{"system": "acme.shop::mail.layouts.system"}); err != nil {
t.Fatal(err)
}
drv2 := NewMemoryDriver()
msg = sendTemplate(t, NewMailer(cat, drv2, Options{}), drv2, "acme.shop::mail.auto", nil)
if !strings.Contains(msg.HTML, `<div class="mine">`) || strings.Contains(msg.HTML, "layout-system") {
t.Errorf("a plugin alias named system did not win: %q", msg.HTML)
}
// An alias that is neither the plugin's nor built in still fails at boot.
bad := fstest.MapFS{"views/mail/x.htm": {Data: []byte("subject = \"X\"\nlayout = \"fancy\"\n==\nx\n")}}
if err := NewCatalog().Register("acme.shop", bad, []string{"acme.shop::mail.x"}, nil); err == nil || !strings.Contains(err.Error(), "unknown layout fancy") {
t.Errorf("unknown alias = %v", err)
}
})
t.Run("layout_partials", func(t *testing.T) {
m, drv := partialsMailer(t, Options{}, nil)
msg := sendTemplate(t, m, drv, "acme.blog::mail.note", map[string]any{"Text": "<b>hi</b>"})
want := `<div class="blog-mail"><div class="note">&lt;b&gt;hi&lt;/b&gt;</div>` + "\n" + `<div class="note">footer</div></div>`
if !strings.Contains(msg.HTML, want) {
t.Errorf("HTML = %q, want the body partial and the layout partial", msg.HTML)
}
if msg.Text != "NOTE: <b>hi</b>\nNOTE: footer" {
t.Errorf("text = %q", msg.Text)
}
})
t.Run("overrides", func(t *testing.T) {
ov := Overrides{
// A customized file layout, by its full name.
Layouts: map[string]LayoutOverride{
"acme.blog::mail.layouts.blog": {Name: "Blog", HTML: `<div class="custom-blog">{{ .Content }}</div><style>{{ .brandCss }}{{ .css }}</style>`, Text: "[custom] {{ .Content }}", CSS: ".custom{margin:0}"},
// A database-only layout, by its code.
"promo": {Name: "Promo", HTML: `<div class="promo">{{ .Content }}{{ partial "acme.blog::mail.partials.note" "text" "promo" }}</div><style>{{ .css }}</style>`, Text: "PROMO {{ .Content }}", CSS: ".promo{margin:0}"},
},
Partials: map[string]PartialOverride{
"acme.blog::mail.partials.note": {HTML: `<aside>{{ .text }}</aside>`, Text: "* {{ .text }}"},
// An override of a partial that no plugin ships is ignored.
"acme.blog::mail.partials.gone": {HTML: "x", Text: "x"},
},
}
m, drv := partialsMailer(t, Options{CSS: "p{color:red}", BrandCSS: ".brand{color:blue}"}, &ov)
msg := sendTemplate(t, m, drv, "acme.blog::mail.note", map[string]any{"Text": "hi"})
if !strings.Contains(msg.HTML, `<div class="custom-blog"><aside>hi</aside>`) {
t.Errorf("HTML = %q, want the customized layout and partial", msg.HTML)
}
if !strings.Contains(msg.HTML, "<style>.brand{color:blue}.custom{margin:0}\np{color:red}</style>") {
t.Errorf("style block = %q, want the layout CSS before mail.css", msg.HTML)
}
if msg.Text != "[custom] * hi" {
t.Errorf("text = %q", msg.Text)
}
// A template override moves the template to the database-only layout.
ov.Template = &TemplateOverride{Subject: "Promo", Body: "Sale.", Layout: "promo"}
m, drv = partialsMailer(t, Options{CSS: "p{color:red}"}, &ov)
msg = sendTemplate(t, m, drv, "acme.blog::mail.welcome", nil)
if msg.Subject != "Promo" || !strings.Contains(msg.HTML, `<div class="promo"><p>Sale.</p>`+"\n"+`<aside>promo</aside></div><style>.promo{margin:0}`+"\np{color:red}</style>") {
t.Errorf("database-only layout: %q / %q", msg.Subject, msg.HTML)
}
if msg.Text != "PROMO Sale." {
t.Errorf("database-only layout: text = %q", msg.Text)
}
// A customized default layout applies to templates on the default layout.
ov = Overrides{Layouts: map[string]LayoutOverride{defaultLayoutName: {HTML: `<main>{{ .Content }}</main>`, Text: "{{ .Content }} (sent by acme)"}}}
m, drv = partialsMailer(t, Options{}, &ov)
msg = sendTemplate(t, m, drv, "acme.blog::mail.welcome", map[string]any{"Name": "Ada", "Link": "https://example.com"})
if !strings.HasPrefix(msg.HTML, "<main><p>Hi Ada</p>") || !strings.HasSuffix(msg.Text, "Bye (sent by acme)") {
t.Errorf("customized default layout: %q / %q", msg.HTML, msg.Text)
}
// A partial override that does not render falls back to the files.
ov = Overrides{Partials: map[string]PartialOverride{"acme.blog::mail.partials.note": {HTML: `{{ .text.missing.field }}`, Text: "x"}}}
m, drv = partialsMailer(t, Options{}, &ov)
msg = sendTemplate(t, m, drv, "acme.blog::mail.note", map[string]any{"Text": "hi"})
if !strings.Contains(msg.HTML, `<div class="note">hi</div>`) {
t.Errorf("a failing partial override did not fall back to the file: %q", msg.HTML)
}
})
}

View File

@@ -2,6 +2,7 @@ package postcard
import (
"context"
"database/sql"
"fmt"
"git.golem15.com/golem15/summercms/modules/backpack"
@@ -140,9 +141,11 @@ 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 holds layout content by layout code: the full name of a
// customized file layout, or the code of a database-only layout. The
// layout a render uses is taken from here when its code is present.
Layouts map[string]LayoutOverride
// Partials holds partial content by partial name.
// Partials holds the customized sections of partials by full name.
Partials map[string]PartialOverride
}
@@ -160,7 +163,8 @@ type TemplateOverride struct {
Layout string
}
// LayoutOverride replaces a layout's wrappers and adds its CSS.
// LayoutOverride is a layout's content from the database: the HTML and text
// wrappers, and CSS that is placed before mail.css in the layout's css slot.
type LayoutOverride struct {
Name string
HTML string
@@ -178,6 +182,10 @@ type PartialOverride struct {
// 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.
//
// One call reads, in one read-only transaction, the customized row of the
// template, every customized file layout and every database-only layout, and
// every customized partial.
func NewDBSource(app *backpack.App) OverrideSource {
return &dbSource{app: app}
}
@@ -199,23 +207,60 @@ func (s *dbSource) MailOverrides(ctx context.Context, name string) (Overrides, e
// 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
err := db.Transaction(func(tx *gorm.DB) error {
if name != "" {
var rows []struct {
Subject string
Body string
Layout string
}
err := tx.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 err
}
if len(rows) > 0 {
out.Template = &TemplateOverride{Subject: rows[0].Subject, Body: rows[0].Body, Layout: rows[0].Layout}
}
}
// is_custom is set on a customized file layout and on every
// database-only layout.
var layouts []struct {
Code string
Name string
ContentHTML string `gorm:"column:content_html"`
ContentText string `gorm:"column:content_text"`
ContentCSS string `gorm:"column:content_css"`
}
if err := tx.Raw(`SELECT code, name, content_html, content_text, content_css FROM ` + LayoutsTable + ` WHERE is_custom`).Scan(&layouts).Error; err != nil {
return err
}
for _, l := range layouts {
if out.Layouts == nil {
out.Layouts = make(map[string]LayoutOverride, len(layouts))
}
out.Layouts[l.Code] = LayoutOverride{Name: l.Name, HTML: l.ContentHTML, Text: l.ContentText, CSS: l.ContentCSS}
}
var partials []struct {
Code string
ContentHTML string `gorm:"column:content_html"`
ContentText string `gorm:"column:content_text"`
}
if err := tx.Raw(`SELECT code, content_html, content_text FROM ` + PartialsTable + ` WHERE is_custom`).Scan(&partials).Error; err != nil {
return err
}
for _, p := range partials {
if out.Partials == nil {
out.Partials = make(map[string]PartialOverride, len(partials))
}
out.Partials[p.Code] = PartialOverride{HTML: p.ContentHTML, Text: p.ContentText}
}
return nil
}, &sql.TxOptions{ReadOnly: true, Isolation: sql.LevelRepeatableRead})
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
}

View File

@@ -2,7 +2,7 @@ package postcard
import (
"bytes"
_ "embed"
"embed"
"fmt"
"html/template"
"io/fs"
@@ -15,12 +15,27 @@ import (
)
const (
builtinPluginID = "postcard"
defaultLayoutAlias = "default"
defaultLayoutName = "postcard::mail.layouts.default"
systemLayoutName = "postcard::mail.layouts.system"
minimalLayoutName = "postcard::mail.layouts.minimal"
mailPrefix = "mail."
assetRoot = "views/mail/"
)
// builtinLayoutAliases are the layout aliases every plugin's templates can
// use. A plugin's own alias of the same name wins, except default, which is
// reserved.
var builtinLayoutAliases = map[string]string{
defaultLayoutAlias: defaultLayoutName,
"system": systemLayoutName,
"minimal": minimalLayoutName,
}
// builtinPartials are the partials postcard ships, callable by bare name.
var builtinPartials = []string{"button", "panel", "subcopy", "table"}
var (
dangerousScheme = regexp.MustCompile(`(?i)(?:javascript|vbscript|data):`)
eventHandler = regexp.MustCompile(`(?i)\son[a-z]+\s*=`)
@@ -32,11 +47,17 @@ var (
//go:embed assets/default.htm
var defaultLayoutSource string
// Catalog holds registered mail templates and layouts.
// builtinAssets holds postcard's own layouts and partials.
//
//go:embed assets
var builtinAssets embed.FS
// Catalog holds registered mail templates, layouts and partials.
type Catalog struct {
mu sync.RWMutex
templates map[string]*parsedTemplate
layouts map[string]*parsedLayout
partials map[string]*parsedPartial
aliases map[string]map[string]string // pluginID -> short name -> full name
}
@@ -57,19 +78,53 @@ type parsedLayout struct {
htmlWrap string
}
// NewCatalog returns an empty catalog that already contains postcard's
// neutral default layout.
// parsedPartial is a partial file: the layout file format, a header, a text
// section and an HTML section.
type parsedPartial struct {
name string
pluginID string
headerName string
textWrap string
htmlWrap string
}
// NewCatalog returns a catalog that already contains postcard's built-in
// layouts (default, system and minimal) and partials (button, panel, table
// and subcopy). It holds no template.
func NewCatalog() *Catalog {
c := &Catalog{
templates: make(map[string]*parsedTemplate),
layouts: make(map[string]*parsedLayout),
partials: make(map[string]*parsedPartial),
aliases: make(map[string]map[string]string),
}
layout, err := parseLayout(defaultLayoutName, "postcard", defaultLayoutSource)
layout, err := parseLayout(defaultLayoutName, builtinPluginID, defaultLayoutSource)
if err != nil {
panic("postcard: default layout: " + err.Error())
}
c.layouts[defaultLayoutName] = layout
for file, name := range map[string]string{"system": systemLayoutName, "minimal": minimalLayoutName} {
raw, err := builtinAssets.ReadFile("assets/" + file + ".htm")
if err != nil {
panic("postcard: " + file + " layout: " + err.Error())
}
layout, err := parseLayout(name, builtinPluginID, string(raw))
if err != nil {
panic("postcard: " + file + " layout: " + err.Error())
}
c.layouts[name] = layout
}
for _, short := range builtinPartials {
raw, err := builtinAssets.ReadFile("assets/partials/" + short + ".htm")
if err != nil {
panic("postcard: " + short + " partial: " + err.Error())
}
partial, err := parsePartial(builtinPartialPrefix+short, builtinPluginID, string(raw))
if err != nil {
panic("postcard: " + short + " partial: " + err.Error())
}
c.partials[partial.name] = partial
}
return c
}
@@ -160,6 +215,10 @@ func (c *Catalog) resolveLayoutLocked(t *parsedTemplate) error {
return nil
}
full, ok := c.aliases[t.pluginID][short]
if !ok {
// Not one of the plugin's own aliases: a built-in layout.
full, ok = builtinLayoutAliases[short]
}
if !ok {
return fmt.Errorf("postcard: unknown layout %s", short)
}
@@ -180,17 +239,50 @@ func (c *Catalog) lookupTemplate(name string) (*parsedTemplate, error) {
return t, nil
}
func (c *Catalog) lookupLayout(name string) (*parsedLayout, error) {
// RegisterPartials loads declared partial names from fsys. Each name must
// be owned by pluginID, have the form <plugin>::mail.partials.<name> and map
// to views/mail/partials/<name>.htm.
func (c *Catalog) RegisterPartials(pluginID string, fsys fs.FS, partials []string) error {
if c == nil {
return fmt.Errorf("postcard: catalog is nil")
}
if pluginID == "" {
return fmt.Errorf("postcard: plugin id is empty")
}
c.mu.Lock()
defer c.mu.Unlock()
for _, name := range partials {
if err := assertOwner(pluginID, name); err != nil {
return err
}
if _, rest, _ := strings.Cut(name, "::"); !strings.HasPrefix(rest, partialSegment) || rest == partialSegment {
return fmt.Errorf("postcard: invalid partial name %s (want %s::%s<name>)", name, pluginID, partialSegment)
}
if _, exists := c.partials[name]; exists {
return fmt.Errorf("postcard: duplicate partial %s", name)
}
path, err := assetPath(name)
if err != nil {
return err
}
raw, err := fs.ReadFile(fsys, path)
if err != nil {
return fmt.Errorf("postcard: missing partial %s", name)
}
parsed, err := parsePartial(name, pluginID, string(raw))
if err != nil {
return err
}
c.partials[name] = parsed
}
return nil
}
func (c *Catalog) lookupPartial(name string) (*parsedPartial, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
if name == "" || name == defaultLayoutAlias {
name = defaultLayoutName
}
l, ok := c.layouts[name]
if !ok {
return nil, fmt.Errorf("postcard: missing layout %s", name)
}
return l, nil
p, ok := c.partials[name]
return p, ok
}
func assertOwner(pluginID, fullName string) error {
@@ -253,6 +345,14 @@ func parseLayout(name, pluginID, src string) (*parsedLayout, error) {
}, nil
}
func parsePartial(name, pluginID, src string) (*parsedPartial, error) {
l, err := parseLayout(name, pluginID, src)
if err != nil {
return nil, err
}
return &parsedPartial{name: l.name, pluginID: l.pluginID, headerName: l.headerName, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, nil
}
func splitTwo(src string) (header, body string, err error) {
parts, err := splitEQ(src, 2)
if err != nil {
@@ -373,7 +473,10 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
if strings.ContainsAny(subject, "\r\n") {
return out, fmt.Errorf("postcard: subject contains CR/LF")
}
markdownBody, err := execHTML(src.name+".body", src.body, vars)
// Partial calls in the body leave tokens that are swapped for the
// rendered partials once Markdown has run; see partialRun.
partials := newPartialRun(c, opts.overrides.Partials)
markdownBody, err := execHTMLFuncs(src.name+".body", src.body, vars, template.FuncMap{"partial": partials.bodyCall})
if err != nil {
return out, err
}
@@ -381,6 +484,8 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
if err != nil {
return out, err
}
htmlBody = partials.swapHTML(htmlBody)
textBody := partials.swapText(markdownBody)
if err := validateHTML(htmlBody); err != nil {
return out, err
}
@@ -388,21 +493,29 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
if err != nil {
return out, err
}
text, err := execText(layout.name+".text", layout.textWrap, map[string]any{
"Content": markdownBody,
// A layout's own CSS goes before mail.css in the css slot.
css := opts.css
if layout.css != "" {
css = layout.css
if opts.css != "" {
css += "\n" + opts.css
}
}
text, err := execTextFuncs(layout.name+".text", layout.textWrap, map[string]any{
"Content": textBody,
"Subject": subject,
"css": opts.css,
"css": css,
"brandCss": opts.brandCSS,
})
}, texttemplate.FuncMap{"partial": partials.textCall})
if err != nil {
return out, err
}
html, err := execHTML(layout.name+".html", layout.htmlWrap, map[string]any{
html, err := execHTMLFuncs(layout.name+".html", layout.htmlWrap, map[string]any{
"Content": template.HTML(htmlBody),
"Subject": subject,
"css": template.CSS(opts.css),
"css": template.CSS(css),
"brandCss": template.CSS(opts.brandCSS),
})
}, template.FuncMap{"partial": partials.htmlCall})
if err != nil {
return out, err
}
@@ -421,20 +534,54 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
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 {
// renderLayout is the layout one render uses: a file layout, a file layout
// with its override applied, or a database-only layout.
type renderLayout struct {
name string // layout code, used in parse and execute errors
textWrap string
htmlWrap string
css string
}
// layoutFor returns the layout src renders in. An override of that layout,
// or a database-only layout of that code, wins over the file. A layout code
// from a template override that names no layout is reported through
// opts.warn and replaced by the default layout.
func (c *Catalog) layoutFor(src renderSource, opts renderOptions) (renderLayout, error) {
code := src.layout
if code == "" || code == defaultLayoutAlias {
code = defaultLayoutName
}
layout, ok, err := c.layoutByCode(code, opts.overrides.Layouts)
if err != nil || ok {
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)
if !src.layoutFromOverride {
return renderLayout{}, fmt.Errorf("postcard: missing layout %s", code)
}
return c.lookupLayout(defaultLayoutAlias)
if opts.warn != nil {
opts.warn("layout:"+src.name+":"+code,
"postcard: override names an unknown layout, using the default layout",
"template", src.name, "layout", code)
}
layout, ok, err = c.layoutByCode(defaultLayoutName, opts.overrides.Layouts)
if err == nil && !ok {
err = fmt.Errorf("postcard: missing layout %s", defaultLayoutName)
}
return layout, err
}
func (c *Catalog) layoutByCode(code string, overrides map[string]LayoutOverride) (renderLayout, bool, error) {
if ov, ok := overrides[code]; ok {
return renderLayout{name: code, textWrap: ov.Text, htmlWrap: ov.HTML, css: ov.CSS}, true, nil
}
c.mu.RLock()
l, ok := c.layouts[code]
c.mu.RUnlock()
if !ok {
return renderLayout{}, false, nil
}
return renderLayout{name: l.name, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, true, nil
}
func markdownHTML(src string) (string, error) {
@@ -459,7 +606,17 @@ func validateHTML(html string) error {
}
func execHTML(name, src string, data any) (string, error) {
tmpl, err := template.New(name).Option("missingkey=zero").Parse(src)
return execHTMLFuncs(name, src, data, nil)
}
func execText(name, src string, data any) (string, error) {
return execTextFuncs(name, src, data, nil)
}
// execHTMLFuncs is execHTML with template funcs; they must be set before
// the source is parsed.
func execHTMLFuncs(name, src string, data any, funcs template.FuncMap) (string, error) {
tmpl, err := template.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src)
if err != nil {
return "", fmt.Errorf("postcard: parse %s: %w", name, err)
}
@@ -470,8 +627,8 @@ func execHTML(name, src string, data any) (string, error) {
return buf.String(), nil
}
func execText(name, src string, data any) (string, error) {
tmpl, err := texttemplate.New(name).Option("missingkey=zero").Parse(src)
func execTextFuncs(name, src string, data any, funcs texttemplate.FuncMap) (string, error) {
tmpl, err := texttemplate.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src)
if err != nil {
return "", fmt.Errorf("postcard: parse %s: %w", name, err)
}