feat(postcard): sample values, file hashes, index sync and the draft editor

- sample.<path> header keys and a parse-tree walker that fills every other
  variable with a visible [path] placeholder, nested fields and range
  targets included
- every file entry carries the sha256 of its CRLF-normalized text; the
  catalog lists its files (Templates, Layouts, Partials) for admin code
- SyncIndex upserts one index row per file and never touches the override
  columns of a customized row; ResetOverride returns a row to its file
- Editor validates, previews and test-sends a template, layout or partial
  draft through the render path of Send and reports field and rule
- pact.RowStateCustomized and pact.RowStateOutdated

Plan 35-01, task 4.
This commit is contained in:
Jakub Zych
2026-11-13 10:57:05 +01:00
parent 5df1ec27cf
commit 495319ee21
11 changed files with 2128 additions and 42 deletions

View File

@@ -33,7 +33,7 @@ Use cases:
- Admin controller contracts: `pact.AdminController`, `pact.HasAdminControllers`, `pact.AdminAssets` (embedded Winter-shaped admin YAML), `pact.AdminPermissioned` and `pact.AdminRecordSource`.
- Admin extension contracts, so a plugin extends the compiled admin SPA without a Node build: `pact.AdminClientAssets` (per-controller JS and CSS from the plugin's embedded `assets/` tree, Winter's `addJs`/`addCss`), `pact.HasAdminActions` with `pact.AdminAction`, `pact.AdminActionInput` and `pact.AdminActionResult` (named toolbar and widget actions whose routes, CSRF check, permissions and record scoping the framework owns), `pact.HasAdminBulkActions` with `pact.AdminBulkAction`, `pact.AdminBulkActionInput` and `pact.AdminBulkActionResult` (named actions on the rows selected in a list, which receive records the framework loaded through the list scope, never ids; a `Detached` action runs outside the framework transaction), `pact.HasAdminRecordActions` with `pact.AdminRecordAction`, `pact.AdminRecordActionInput` and `pact.AdminRecordActionResult` (named actions on one record, each with an `Applies` rule for the record's state), `pact.HasAdminActionExtensions` with `pact.AdminActionExtension` (a plugin adds record actions to any admin controller by controller ID, one it does not own included; they are offered on that controller's preview screen after the owner's) and `pact.AdminFormExtension` (a plugin places fields and tabs in another controller's form, before or after the owner's, and loads and saves their values itself inside the record's save transaction), and `pact.AdminPartialData` (the curated view model a partial template renders).
- Plugin field types: `pact.HasFormFieldTypes` returns `pact.FormFieldType` entries, admin form field types any controller's `fields.yaml` uses by a short alias (`type: notes`). A type names its custom element, its scripts and styles, its own option keys and its Go funcs: `Decode` turns a submitted `pact.FormFieldValue` into a `pact.FormFieldDecoded` (the value to store plus optional `pact.FormFieldNotice` messages for the administrator, such as what a sanitizer removed) or refuses it with a `pact.FormFieldError`; `Load` serves the stored value to the element, `ListValue` formats a list column, `Upload` stores a file from a `pact.FormFieldUpload` and answers a `pact.FormFieldUploadResult`, and `RequestOptions` adds options that change per request (a site setting the element follows) to the served form schema. The admin framework owns the routes, permissions, record scope, locale storage of a translatable type and the localization of notices.
- Optional admin hooks a controller or model can implement: list and form query scoping (`pact.ListExtendQuery`, `pact.FormExtendQuery`), list row states (`pact.ListRowStates` with the fixed `pact.RowState` set `pact.RowStateDeleted`, `pact.RowStateNegative` and `pact.RowStateDisabled`), values of unstored list columns filled once per page (`pact.ListExtendRecords`), the record title of the form and preview screens (`pact.FormRecordTitle`), create, update and delete hooks (`pact.FormBeforeCreate`, `pact.FormAfterUpdate`, `pact.FormBeforeDelete` and their siblings), a hook after a reorder save (`pact.ReorderAfterSave`), form-only fields that reach those hooks without being model columns (`pact.FormVirtualFields`), validation rules per operation for admin saves (`pact.FormRules`), relation hooks (`pact.RelationExtendManageQuery`, `pact.RelationExtendOptionsQuery`, `pact.RelationBeforeLink`), relation child hooks around creating, updating and deleting a related record (`pact.RelationBeforeCreate`, `pact.RelationAfterCreate`, `pact.RelationBeforeUpdate`, `pact.RelationAfterUpdate`, `pact.RelationBeforeDelete`, `pact.RelationAfterDelete`), filter scopes (`pact.FilterScope`, `pact.FilterOptions`) and dropdown options (`pact.DropdownOptionsProvider`).
- Optional admin hooks a controller or model can implement: list and form query scoping (`pact.ListExtendQuery`, `pact.FormExtendQuery`), list row states (`pact.ListRowStates` with the fixed `pact.RowState` set `pact.RowStateDeleted`, `pact.RowStateNegative`, `pact.RowStateDisabled`, `pact.RowStateCustomized` and `pact.RowStateOutdated`), values of unstored list columns filled once per page (`pact.ListExtendRecords`), the record title of the form and preview screens (`pact.FormRecordTitle`), create, update and delete hooks (`pact.FormBeforeCreate`, `pact.FormAfterUpdate`, `pact.FormBeforeDelete` and their siblings), a hook after a reorder save (`pact.ReorderAfterSave`), form-only fields that reach those hooks without being model columns (`pact.FormVirtualFields`), validation rules per operation for admin saves (`pact.FormRules`), relation hooks (`pact.RelationExtendManageQuery`, `pact.RelationExtendOptionsQuery`, `pact.RelationBeforeLink`), relation child hooks around creating, updating and deleting a related record (`pact.RelationBeforeCreate`, `pact.RelationAfterCreate`, `pact.RelationBeforeUpdate`, `pact.RelationAfterUpdate`, `pact.RelationBeforeDelete`, `pact.RelationAfterDelete`), filter scopes (`pact.FilterScope`, `pact.FilterOptions`) and dropdown options (`pact.DropdownOptionsProvider`).
- Dependent dropdown options: `pact.DependentOptionsProvider` answers a `pact.DependentOptionSet` (whether the sibling's value takes a choice at all, and the choices) for a dropdown with `dependsOn`, from the submitted values of its siblings and with a context, so the choices can come from the database; the admin framework calls it for the options route and again on every save. `pact.Option.Depth` indents a choice taken from a tree.
- Menu item types: `pact.HasMenuItemTypes` returns `pact.MenuItemType` values (key, label, default URL pattern, `PatternFrom` for a list type, the `References` an item can point at as a `pact.MenuItemReference` tree, and `Resolve`), the typed successor of WinterCMS's `pages.menuitem.*` events. `Resolve` receives a `pact.MenuItemResolve` with the pattern already layered and answers a `pact.ResolvedMenuItem` with its alternates as an ordered `[]pact.MenuItemAlternate`. [signpost](../signpost/README.md) collects them at boot. A record type may set `Content` to a `pact.ContentDescriptor`, which describes its records for consumers that work on every content type at once (sitemaps, search indexers, metadata editors): the admin controller that edits them, their morph type, `Describe` (a `pact.ContentRecord` with per-locale `pact.ContentLocale` URL, title, description, image and word count), and the optional `Records` (paged through `pact.ContentList` and `pact.ContentPage`) and `Match` (a public path to a `pact.ContentMatchResult`).
- Content facts: a descriptor may also say what kind of record the type holds (`pact.ContentDescriptor.Kind`) and which MCP tools change its records, by operation (`pact.ContentDescriptor.Tools`); `Describe` and `Records` may report a record's first publication, ordered parents, authors and top heading level, and per locale its images, videos and heading outline. All of them are optional.
@@ -193,7 +193,7 @@ func (p *Plugin) Schedule() []pact.ScheduledCommand {
| `pact.ListRowStates` | Optional controller hook called once per list page; returns the states of the page's records, index-aligned. |
| `pact.ListExtendRecords` | Optional controller hook called once per list page, before the columns are read; fills unstored fields of the page's records. |
| `pact.FormRecordTitle` | Optional controller hook naming a record on its form and preview screens; sent as the record envelope's `meta.title`. |
| `pact.RowState` | One state of a list row: `pact.RowStateDeleted`, `pact.RowStateNegative` or `pact.RowStateDisabled`. |
| `pact.RowState` | One state of a list row: `pact.RowStateDeleted`, `pact.RowStateNegative`, `pact.RowStateDisabled`, `pact.RowStateCustomized` (shipped content replaced by an administrator, such as a mail template with an override) or `pact.RowStateOutdated` (customized, and the shipped content has changed since). |
| `pact.FormVirtualFields` | Optional controller list of form fields that are not model columns for the form (a password and its confirmation, for example): never bound, filled or returned; their submitted values reach the Form hooks through the admin framework's context accessor. |
| `pact.FormRules` | Optional controller hook returning the validation rules of an admin save for `create` or `update`; the set replaces the model's `Rules()` for those saves and may name virtual fields. |
| `pact.FilterScope` | Model scopes a list filter may call, limited to an exact allow list. |

View File

@@ -1059,6 +1059,12 @@ const (
RowStateNegative RowState = "negative"
// RowStateDisabled marks an inactive record.
RowStateDisabled RowState = "disabled"
// RowStateCustomized marks a record whose shipped content an
// administrator has replaced, such as a mail template with an override.
RowStateCustomized RowState = "customized"
// RowStateOutdated marks a customized record whose shipped content has
// changed since it was customized.
RowStateOutdated RowState = "outdated"
)
// ListRowStates optionally marks the rows of an admin list with states. The
@@ -1066,7 +1072,7 @@ const (
// order, and the list's database handle: a list does not run in a
// transaction, so cabana.TxFromContext reports none here. The result is
// index-aligned with records; a row may carry several states and a nil entry
// means none. Values outside the three RowState constants are dropped.
// means none. Values outside the five RowState constants are dropped.
type ListRowStates interface {
ListRowStates(ctx context.Context, db *gorm.DB, records []any) ([][]RowState, error)
}

View File

@@ -30,6 +30,8 @@ Use cases:
- 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, 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.
- Sample values: a template's header may give its variables sample values with `sample.<path>` keys. Previews and save checks use them, and show every other variable as a visible `[path]` placeholder.
- An editor API for admin code (`postcard.Editor`): validate, preview and test-send an unsaved draft of a template, layout or partial through the same render path as a real send; one index row per file (`postcard.SyncIndex`) with a hash of the file for detecting that it changed under an override, and reset to the file version (`postcard.ResetOverride`).
- No locale selection: callers pass the full template name, including any locale suffix.
## Usage
@@ -227,6 +229,93 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
}
```
### Sample values
A preview has no caller to supply variables, so a template can carry sample values in its header. A key is `sample.` followed by the variable's path, and the path keeps its case, because template variables are case-sensitive:
```text
subject = "Your order {{ .order.code }}"
description = "Sent when an order is paid"
sample.name = "Ada"
sample.order.code = "ZAM-1"
==
Hi {{ .name }}, we received the payment for **{{ .order.code }}**.
{{ range .order.items }}- {{ .description }}
{{ end }}
```
Sample values are strings and are used only by `postcard.Editor`; `Send` never reads them, and a file without them works as before. For a preview postcard walks the draft's subject and body and gives every variable they read a value: its sample, or the placeholder `[path]`, as in `[order.items.description]`. A field of a variable becomes a nested value and the target of a `range` a list of one element, so a body that reads `.order.code` or ranges over `.order.items` renders without the caller's data.
### Editing drafts
`postcard.EditorFrom` returns the `postcard.Editor` of the mailer `postcard.Activate` published. Admin code describes unsaved content as a `postcard.Draft` and asks the editor to check, render or send it:
```go
package blog
import (
"context"
"errors"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/postcard"
)
// previewWelcome renders an edited welcome mail without saving it.
func previewWelcome(ctx context.Context, app *backpack.App, subject, body string) (postcard.Preview, error) {
editor, ok := postcard.EditorFrom(app)
if !ok {
return postcard.Preview{}, errors.New("mailer not published")
}
draft := postcard.Draft{
Kind: postcard.KindTemplate,
Name: "acme.blog::mail.welcome",
Subject: subject,
Body: body,
}
if problem := editor.Validate(ctx, draft); problem != nil {
// problem.Field and problem.Rule say what to show next to which field.
return postcard.Preview{}, problem
}
return editor.Preview(ctx, draft)
}
```
A draft is rendered by the code that renders a send, with the mailer's CSS and the layouts and partials its override source returns, so a preview is what the saved content would send:
| `postcard.Draft.Kind` | `postcard.Draft.Name` | Content fields | Rendered as |
|-----------------------|-----------------------|----------------|-------------|
| `postcard.KindTemplate` | The template's full name | `Subject`, `Body`, `Layout` (a layout code; empty keeps the file's layout) | The template with its sample values and placeholders. |
| `postcard.KindLayout` | The layout's code | `HTML`, `Text`, `CSS` | The layout around postcard's sample message. |
| `postcard.KindPartial` | The partial's full name | `HTML`, `Text` | A message that is one call of the partial, with a placeholder for every argument it reads. |
`postcard.Editor.Validate` returns nil or a `postcard.DraftError`. `postcard.DraftError.Field` is the form field at fault: `subject`, `layout` or `body` for a template, `content_html`, `content_text` or `content_css` for a layout or a partial. `postcard.DraftError.Rule` is one of:
| Rule | Meaning |
|------|---------|
| `parse` | The content is not a valid template. |
| `render` | It does not render with the sample values and placeholders. |
| `unsafe` | It contains, or renders to, a script, iframe, object or embed tag, an inline event handler or a `javascript:`, `vbscript:` or `data:` address; a layout's CSS that would close the style block is refused the same way. `postcard.DraftError.Message` holds the text that matched. |
| `subject_line` | The subject renders to more than one line. |
| `layout` | The template's layout code names no layout. |
| `partial` | A call names a partial that does not exist; `postcard.DraftError.Name` holds the name. |
| `no_content` | A layout wrapper does not use `{{ .Content }}`. |
`postcard.DraftError.Message` carries the template parser's, the renderer's or the safety check's own text and nothing else. The safety checks are the ones a send runs, so text such as `metadata:` is refused at save as it would be at send, and the message shows where. A template body is also refused when its source contains one of the unsafe tags, which Markdown would otherwise drop without notice.
`postcard.Editor.Preview` and `postcard.Editor.SendDraft` return a draft problem as a `postcard.DraftError` too (use `errors.As`). `postcard.Editor.SendDraft` delivers the rendered draft to the one address it is given, through the mailer's driver and from `mail.from`.
### Index rows, drift and reset
`postcard.Catalog.Templates`, `postcard.Catalog.Layouts` and `postcard.Catalog.Partials` list the files as `postcard.TemplateFile`, `postcard.LayoutFile` and `postcard.PartialFile` values; each carries its `Source` and a `Hash`, the SHA-256 of the file's text with CRLF line endings normalized, so the same file hashes the same on every platform.
`postcard.SyncIndex` gives every file a row in its table, keyed by `code`. A row that is not customized mirrors the file, so lists and forms show the file version. A customized row keeps its content; only `source`, `description`, `locale`, `name` and `file_hash` follow the file. An override stores the hash of the file it was written against in `base_hash`, so it is outdated when `base_hash` and `file_hash` differ. `postcard.SyncIndex` never deletes a row, leaves database-only layouts alone, writes nothing when a row already matches, and may run in several processes at once. It needs the tables: when they are not migrated yet it returns the error.
`postcard.ResetOverride` returns one row to its file version and clears `is_custom`, `base_hash` and `customized_at`. A database-only layout has no file version and is refused.
`postcard.FormatTemplate`, `postcard.FormatLayout` and `postcard.FormatPartial` write content in the file format, so a file version and an override can be compared line by line. `postcard.TemplateLocale` reads the locale from a name such as `acme.blog::mail.welcome-en`, given the application's locales.
## API reference
| Identifier | Description |
@@ -256,6 +345,22 @@ func newTestMailer(cat *postcard.Catalog, driver postcard.Driver) postcard.Maile
| `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. |
| `postcard.SyncIndex` | Upserts one index row per file template, layout and partial of a catalog; mirrors the file into rows that are not customized and refreshes `file_hash` on all. |
| `postcard.ResetOverride` | Returns one file-backed row to its file version. Takes the row's `postcard.Kind` and code. |
| `postcard.Kind` | What a draft or a row is: `postcard.KindTemplate`, `postcard.KindLayout`, `postcard.KindPartial` or `postcard.KindBrand` (reserved for the branding settings; the editor does not render it yet). |
| `postcard.Editor` | Validates, previews and test-sends drafts with the mailer's catalog, configuration, override source and driver. |
| `postcard.EditorFrom` | Returns the editor of the mailer published on an app. |
| `postcard.Editor.Catalog` | The mailer's catalog. |
| `postcard.Editor.Validate` | Checks a draft; returns nil or a `postcard.DraftError`. |
| `postcard.Editor.Preview` | Renders a draft to a `postcard.Preview` (subject, HTML part, text part). |
| `postcard.Editor.SendDraft` | Renders a draft and delivers it to one address. |
| `postcard.Draft` | Unsaved content of one kind. |
| `postcard.DraftError` | Why a draft cannot be saved: field, rule, message and, for an unknown partial, its name. |
| `postcard.TemplateFile`, `postcard.LayoutFile`, `postcard.PartialFile` | A registered file with its parts, its normalized `Source` and its `Hash`. `postcard.TemplateFile.Samples` holds the sample values and `postcard.TemplateFile.Layout` the full name of the file's layout. |
| `postcard.Catalog.Templates`, `postcard.Catalog.Layouts`, `postcard.Catalog.Partials` | The registered files, sorted by name. |
| `postcard.Catalog.Template`, `postcard.Catalog.Layout`, `postcard.Catalog.Partial` | One registered file by full name. |
| `postcard.FormatTemplate`, `postcard.FormatLayout`, `postcard.FormatPartial` | Content written in the file format, for display and comparison. |
| `postcard.TemplateLocale` | The locale suffix of a template name, when it is one of the given locales. |
## Configuration
@@ -290,7 +395,7 @@ mail:
- 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, 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`.
- Standard library: `bytes`, `context`, `crypto/rand`, `crypto/sha256`, `database/sql`, `embed`, `encoding/hex`, `errors`, `fmt`, `html/template`, `io/fs`, `log/slog`, `net/mail`, `regexp`, `sort`, `strconv`, `strings`, `sync`, `text/template` (and `text/template/parse`), `time`.
- Tests additionally use `github.com/testcontainers/testcontainers-go` (Mailpit and Postgres containers), `gorm.io/driver/postgres` and `github.com/jackc/pgx/v5`.
## Testing
@@ -299,4 +404,4 @@ mail:
go test ./modules/postcard/...
```
The SMTP integration test starts a Mailpit container and the override smoke test a Postgres container, both through testcontainers-go, so they need Docker. Run `go test -short ./modules/postcard/...` to skip them; the remaining tests use the memory and fail drivers and need no external services.
The SMTP integration test starts a Mailpit container, and the override, index and reset tests a Postgres container, all 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.

View File

@@ -0,0 +1,12 @@
subject = "A sample message"
description = "The message a mail layout is previewed around"
==
# A sample heading
This is how a message looks in this layout: a paragraph with **bold text** and [a link](https://example.com).
{{ partial "button" "url" "https://example.com" "body" "A button" }}
{{ partial "panel" "body" "A panel holds a note that should stand out." }}
Thanks for reading.

473
modules/postcard/editor.go Normal file
View File

@@ -0,0 +1,473 @@
package postcard
import (
"context"
"errors"
"fmt"
"regexp"
"sort"
"strconv"
"strings"
"sync"
"text/template/parse"
"git.golem15.com/golem15/summercms/modules/backpack"
)
// Kind names what a Draft or an index row is.
type Kind string
// The kinds of mail content an administrator edits.
const (
KindTemplate Kind = "template"
KindLayout Kind = "layout"
KindPartial Kind = "partial"
KindBrand Kind = "brand"
)
// Draft is edited mail content that has not been saved: what Validate
// checks and Preview and SendDraft render.
type Draft struct {
Kind Kind
// Name is the template's full name, the layout's code or the partial's
// full name.
Name string
// Subject, Body and Layout are a template draft. Layout is a layout
// code; empty keeps the file's layout.
Subject string
Body string
Layout string
// HTML and Text are a layout's wrappers or a partial's sections; CSS is
// a layout's own CSS.
HTML string
Text string
CSS string
}
// The rules a DraftError reports.
const (
ruleParse = "parse"
ruleRender = "render"
ruleUnsafe = "unsafe"
ruleSubjectLine = "subject_line"
ruleLayout = "layout"
rulePartial = "partial"
ruleNoContent = "no_content"
)
// The fields a DraftError names: the columns an admin form binds.
const (
fieldSubject = "subject"
fieldLayout = "layout"
fieldBody = "body"
fieldContentHTML = "content_html"
fieldContentText = "content_text"
fieldContentCSS = "content_css"
)
// DraftError is a draft that cannot be saved as it is.
type DraftError struct {
// Field is the form field at fault: subject, layout or body for a
// template, content_html, content_text or content_css for a layout or a
// partial.
Field string
// Rule is what failed: parse, render, unsafe, subject_line, layout,
// partial or no_content.
Rule string
// Message is the parser's, renderer's or safety check's own text, and
// for the unsafe rule the text that matched. It carries nothing else.
Message string
// Name is the partial an unknown-partial failure refers to.
Name string
}
func (e *DraftError) Error() string {
out := "postcard: draft " + e.Field + ": " + e.Rule
if e.Name != "" {
out += " " + e.Name
}
if e.Message != "" {
out += ": " + e.Message
}
return out
}
// Preview is a rendered draft.
type Preview struct {
Subject string
HTML string
Text string
}
// Editor validates, previews and test-sends drafts with the mailer's own
// catalog, configuration, override source and driver, so a draft renders as
// the saved content would be sent.
type Editor struct {
m *mailer
}
// EditorFrom returns the editor of the mailer postcard.Activate published
// on app.
func EditorFrom(app *backpack.App) (*Editor, bool) {
if app == nil {
return nil, false
}
got, ok := app.Lookup[Mailer]()
if !ok {
return nil, false
}
m, ok := got.(*mailer)
if !ok || m == nil || m.catalog == nil {
return nil, false
}
return &Editor{m: m}, true
}
// Catalog returns the mailer's catalog of file templates, layouts and
// partials.
func (e *Editor) Catalog() *Catalog {
return e.m.catalog
}
// Validate checks a draft the way a send would treat it: it parses it,
// renders it with sample values and placeholders and runs the safety checks.
// It returns nil for a draft that can be saved.
func (e *Editor) Validate(ctx context.Context, d Draft) *DraftError {
_, err := e.render(ctx, d)
if err == nil {
return nil
}
return draftErrorFor(d, err)
}
// Preview renders a draft: a template with its sample values and visible
// [name] placeholders, a layout around postcard's sample message, a partial
// called with placeholder arguments. Layouts, partials and other pieces the
// draft does not carry come from the mailer's override source, as in a send.
// A problem with the draft is returned as a *DraftError.
func (e *Editor) Preview(ctx context.Context, d Draft) (Preview, error) {
msg, err := e.render(ctx, d)
if err != nil {
return Preview{}, draftErrorFor(d, err)
}
return Preview{Subject: msg.Subject, HTML: msg.HTML, Text: msg.Text}, nil
}
// SendDraft renders a draft as Preview does and delivers it to the one
// address to, through the mailer's driver and from its sender address. A
// problem with the draft is returned as a *DraftError.
func (e *Editor) SendDraft(ctx context.Context, d Draft, to string) error {
m := e.m
if m.driver == nil {
return fmt.Errorf("postcard: driver is nil")
}
msg, err := e.render(ctx, d)
if err != nil {
return draftErrorFor(d, err)
}
msg.To, msg.Cc, msg.Bcc, msg.ReplyTo = []string{to}, nil, nil, ""
msg.From = m.opts.From
_, smtp := m.driver.(*SMTPDriver)
if err := validateRendered(msg, smtp); err != nil {
return err
}
if err := m.driver.Send(ctx, msg); err != nil {
return fmt.Errorf("postcard: %w", err)
}
return nil
}
// render renders a draft through the catalog's render path, with the other
// overrides of the mailer's source applied.
func (e *Editor) render(ctx context.Context, d Draft) (RenderedMessage, error) {
m := e.m
// An empty template name: everything except a template override. The
// stored override of a template being edited is replaced by the draft.
ov := m.overrides(ctx, "")
ov.Template = nil
opts := renderOptions{css: m.opts.CSS, brandCSS: m.opts.BrandCSS}
switch d.Kind {
case KindTemplate:
return e.renderTemplate(d, ov, opts)
case KindLayout:
return e.renderLayout(d, ov, opts)
case KindPartial:
return e.renderPartial(d, ov, opts)
}
return RenderedMessage{}, fmt.Errorf("postcard: unsupported draft kind %q", d.Kind)
}
func (e *Editor) renderTemplate(d Draft, ov Overrides, opts renderOptions) (RenderedMessage, error) {
cat := e.m.catalog
t, err := cat.lookupTemplate(d.Name)
if err != nil {
return RenderedMessage{}, err
}
// Markdown drops raw HTML from a body, so such a tag would vanish from
// the mail without a word; say so when the draft is saved.
if loc := rawUnsafeTag.FindStringIndex(d.Body); loc != nil {
return RenderedMessage{}, &DraftError{Field: fieldBody, Rule: ruleUnsafe, Message: snippetAt(d.Body, loc)}
}
if d.Layout != "" {
if _, ok, _ := cat.layoutByCode(d.Layout, ov.Layouts); !ok {
return RenderedMessage{}, &DraftError{Field: fieldLayout, Rule: ruleLayout}
}
}
ov.Template = &TemplateOverride{Subject: d.Subject, Body: d.Body, Layout: d.Layout}
opts.overrides = ov
return cat.render(Message{
Template: d.Name,
Vars: placeholderVars(t.samples, d.Subject, d.Body),
}, opts)
}
// closingStyle matches what would end the style block a layout's CSS is
// placed in.
var closingStyle = regexp.MustCompile(`(?i)</\s*style`)
// draftLayoutCode is the code a layout draft without one is rendered under.
const draftLayoutCode = "draft"
func (e *Editor) renderLayout(d Draft, ov Overrides, opts renderOptions) (RenderedMessage, error) {
if loc := closingStyle.FindStringIndex(d.CSS); loc != nil {
return RenderedMessage{}, &DraftError{Field: fieldContentCSS, Rule: ruleUnsafe, Message: snippetAt(d.CSS, loc)}
}
var unsafe *unsafeError
if err := validateHTML(d.CSS); errors.As(err, &unsafe) {
return RenderedMessage{}, &DraftError{Field: fieldContentCSS, Rule: ruleUnsafe, Message: unsafe.snippet}
}
// A wrapper that does not parse is reported by the render below.
if uses, parsed := usesContent(d.HTML); parsed && !uses {
return RenderedMessage{}, &DraftError{Field: fieldContentHTML, Rule: ruleNoContent}
}
if uses, parsed := usesContent(d.Text); parsed && !uses {
return RenderedMessage{}, &DraftError{Field: fieldContentText, Rule: ruleNoContent}
}
code := d.Name
if code == "" {
code = draftLayoutCode
}
layouts := make(map[string]LayoutOverride, len(ov.Layouts)+1)
for k, v := range ov.Layouts {
layouts[k] = v
}
layouts[code] = LayoutOverride{Name: code, HTML: d.HTML, Text: d.Text, CSS: d.CSS}
ov.Layouts = layouts
opts.overrides = ov
sample := sampleMessage()
return e.m.catalog.renderFrom(Message{
Vars: placeholderVars(sample.samples, sample.subject, sample.body),
}, renderSource{name: sample.name, subject: sample.subject, body: sample.body, layout: code, layoutFromOverride: true}, opts)
}
func (e *Editor) renderPartial(d Draft, ov Overrides, opts renderOptions) (RenderedMessage, error) {
cat := e.m.catalog
p, ok := cat.lookupPartial(d.Name)
if !ok {
return RenderedMessage{}, &partialError{name: d.Name, msg: "unknown partial", unknown: true}
}
partials := make(map[string]PartialOverride, len(ov.Partials)+1)
for k, v := range ov.Partials {
partials[k] = v
}
partials[d.Name] = PartialOverride{HTML: d.HTML, Text: d.Text}
ov.Partials = partials
opts.overrides = ov
// A message that is one call of the partial, with a placeholder for
// every argument its sections read.
args := placeholderVars(nil, d.HTML, d.Text)
keys := make([]string, 0, len(args))
for key := range args {
keys = append(keys, key)
}
sort.Strings(keys)
var body strings.Builder
body.WriteString("{{ partial " + strconv.Quote(d.Name))
for _, key := range keys {
body.WriteString(" " + strconv.Quote(key) + " (index . " + strconv.Quote(key) + ")")
}
body.WriteString(" }}")
msg, err := cat.renderFrom(Message{Vars: args}, renderSource{name: d.Name + ".preview", body: body.String()}, opts)
if err != nil {
return RenderedMessage{}, err
}
msg.Subject = p.headerName
if msg.Subject == "" {
msg.Subject = p.name
}
return msg, nil
}
// usesContent reports whether a layout wrapper reads .Content, and whether
// the wrapper parsed at all.
func usesContent(src string) (uses, parsed bool) {
tree := parse.New("content")
tree.Mode = parse.SkipFuncCheck
if _, err := tree.Parse(src, "", "", map[string]*parse.Tree{}); err != nil || tree.Root == nil {
return false, false
}
return nodeUsesContent(tree.Root), true
}
func nodeUsesContent(node parse.Node) bool {
switch n := node.(type) {
case *parse.ListNode:
if n == nil {
return false
}
for _, child := range n.Nodes {
if nodeUsesContent(child) {
return true
}
}
case *parse.ActionNode:
return nodeUsesContent(n.Pipe)
case *parse.PipeNode:
if n == nil {
return false
}
for _, cmd := range n.Cmds {
if nodeUsesContent(cmd) {
return true
}
}
case *parse.CommandNode:
for _, arg := range n.Args {
if nodeUsesContent(arg) {
return true
}
}
case *parse.FieldNode:
return len(n.Ident) > 0 && n.Ident[0] == "Content"
case *parse.VariableNode:
return len(n.Ident) > 1 && n.Ident[0] == "$" && n.Ident[1] == "Content"
case *parse.ChainNode:
return nodeUsesContent(n.Node)
case *parse.IfNode:
return nodeUsesContent(n.Pipe) || nodeUsesContent(n.List) || nodeUsesContent(n.ElseList)
case *parse.WithNode:
return nodeUsesContent(n.Pipe) || nodeUsesContent(n.List) || nodeUsesContent(n.ElseList)
case *parse.RangeNode:
return nodeUsesContent(n.Pipe) || nodeUsesContent(n.List) || nodeUsesContent(n.ElseList)
case *parse.TemplateNode:
return nodeUsesContent(n.Pipe)
}
return false
}
// draftErrorFor turns a failed render of d into the field and the rule an
// admin form shows. The message keeps only what the template parser, the
// renderer or the safety check said.
func draftErrorFor(d Draft, err error) *DraftError {
var de *DraftError
if errors.As(err, &de) {
return de
}
part := ""
var re *renderError
if errors.As(err, &re) {
part = re.part
}
// The innermost template error names the template that failed: a
// partial's section inside a body, for example.
var inner *tmplError
for cur := err; cur != nil; cur = errors.Unwrap(cur) {
if te, ok := cur.(*tmplError); ok {
inner = te
}
}
out := &DraftError{Field: draftField(d, part, inner)}
var pe *partialError
var ue *unsafeError
switch {
case errors.Is(err, errSubjectLine):
out.Field, out.Rule = fieldSubject, ruleSubjectLine
case errors.As(err, &pe) && pe.unknown:
out.Rule, out.Name = rulePartial, pe.name
case errors.As(err, &ue):
out.Rule, out.Message = ruleUnsafe, ue.snippet
case inner != nil:
out.Rule = ruleRender
if inner.parse {
out.Rule = ruleParse
}
out.Message = templateMessage(inner)
default:
out.Rule, out.Message = ruleRender, scrubMessage(err.Error())
}
return out
}
// draftField returns the form field a failure in part of the message
// belongs to for a draft of d's kind.
func draftField(d Draft, part string, inner *tmplError) string {
switch d.Kind {
case KindTemplate:
switch part {
case partSubject:
return fieldSubject
case partLayout, partLayoutText, partLayoutHTML:
return fieldLayout
}
return fieldBody
case KindLayout:
if part == partLayoutText {
return fieldContentText
}
return fieldContentHTML
case KindPartial:
if inner != nil && inner.name == d.Name+".text" {
return fieldContentText
}
return fieldContentHTML
}
return ""
}
// templateMessage is a template error without the template's name: the
// line, then what the template package reported.
func templateMessage(te *tmplError) string {
msg := te.err.Error()
for _, prefix := range []string{"template: ", "html/template:"} {
msg = strings.TrimPrefix(msg, prefix)
}
if rest, ok := strings.CutPrefix(msg, te.name+":"); ok {
msg = strings.TrimSpace(rest)
if msg != "" && msg[0] >= '0' && msg[0] <= '9' {
msg = "line " + msg
}
}
msg = strings.Replace(msg, `executing "`+te.name+`" `, "", 1)
return scrubMessage(msg)
}
// scrubMessage drops the package prefixes from an error text.
func scrubMessage(msg string) string {
msg = strings.ReplaceAll(msg, "postcard: ", "")
msg = strings.ReplaceAll(msg, "html/template:", "")
return strings.TrimSpace(strings.ReplaceAll(msg, "template: ", ""))
}
var (
sampleOnce sync.Once
sampleParsed *parsedTemplate
)
// sampleMessage is the message a layout draft is previewed around. It is
// not a registered template: nothing can send it.
func sampleMessage() *parsedTemplate {
sampleOnce.Do(func() {
raw, err := builtinAssets.ReadFile("assets/sample.htm")
if err != nil {
panic("postcard: sample message: " + err.Error())
}
sampleParsed, err = parseTemplateFile("postcard::mail.sample", builtinPluginID, string(raw))
if err != nil {
panic("postcard: sample message: " + err.Error())
}
})
return sampleParsed
}

View File

@@ -0,0 +1,763 @@
package postcard
import (
"context"
"errors"
"reflect"
"regexp"
"strconv"
"strings"
"sync"
"testing"
"testing/fstest"
"git.golem15.com/golem15/summercms/modules/backpack"
)
const editorWelcomeHTM = `subject = "Welcome, {{ .Name }}"
description = "Sent after registration"
layout = "blog"
sample.Name = "Ada"
sample.order.code = "ZAM-1"
==
Hi **{{ .Name }}**, order {{ .order.code }} for {{ .company }}.
{{ range .order.items }}- {{ .description }}
{{ end }}
`
func editorFS(welcome string) fstest.MapFS {
return fstest.MapFS{
"views/mail/welcome.htm": {Data: []byte(welcome)},
"views/mail/welcome-en.htm": {Data: []byte("subject = \"Welcome\"\ndescription = \"English welcome\"\n==\nHello.\n")},
"views/mail/layouts/blog.htm": {Data: []byte(`name = "Blog"
==
{{ .Content }}
-- The Acme blog
==
<div class="blog-mail">{{ .Content }}</div>
`)},
"views/mail/partials/note.htm": {Data: []byte(noteHTM)},
}
}
const (
editorWelcome = "acme.blog::mail.welcome"
editorBlogLayout = "acme.blog::mail.layouts.blog"
editorNote = "acme.blog::mail.partials.note"
)
func editorPlugin(welcome string) mailPlugin {
return mailPlugin{
partialsPlugin: partialsPlugin{id: "acme.blog", fsys: editorFS(welcome), partials: []string{editorNote}},
templates: []string{editorWelcome, "acme.blog::mail.welcome-en"},
layouts: map[string]string{"blog": editorBlogLayout},
}
}
func editorCatalog(t *testing.T, welcome string) *Catalog {
t.Helper()
p := editorPlugin(welcome)
cat := NewCatalog()
if err := cat.RegisterPartials(p.id, p.fsys, p.partials); err != nil {
t.Fatal(err)
}
if err := cat.Register(p.id, p.fsys, p.templates, p.layouts); err != nil {
t.Fatal(err)
}
return cat
}
// newEditor boots the fixture the way party does and returns the editor of
// the published mailer. ov, when set, replaces the mailer's override source.
func newEditor(t *testing.T, ov *Overrides) (*Editor, *MemoryDriver) {
t.Helper()
app := backpack.New(nil)
plugin := editorPlugin(editorWelcomeHTM)
if err := Activate(app, []mailPlugin{plugin}); err != nil {
t.Fatal(err)
}
if err := BootPlugin(app, plugin); err != nil {
t.Fatal(err)
}
ed, ok := EditorFrom(app)
if !ok {
t.Fatal("EditorFrom found no mailer")
}
ed.m.opts.From = "blog@example.com"
if ov != nil {
ed.m.source = fakeOverrides{ov: *ov}
}
return ed, ed.m.driver.(*MemoryDriver)
}
var hex64 = regexp.MustCompile(`^[0-9a-f]{64}$`)
// TestMailEditorSmoke covers what the admin layer builds on: sample values
// and placeholders, file hashes, the catalog read API, draft validation,
// preview and test send, and the index rows with reset.
func TestMailEditorSmoke(t *testing.T) {
ctx := context.Background()
t.Run("samples", func(t *testing.T) {
parsed, err := parseTemplateFile(editorWelcome, "acme.blog", editorWelcomeHTM)
if err != nil {
t.Fatal(err)
}
if want := map[string]string{"Name": "Ada", "order.code": "ZAM-1"}; !reflect.DeepEqual(parsed.samples, want) {
t.Errorf("samples = %v, want %v", parsed.samples, want)
}
if parsed.subject != "Welcome, {{ .Name }}" || parsed.description != "Sent after registration" || parsed.layout != "blog" {
t.Errorf("header = %q / %q / %q", parsed.subject, parsed.description, parsed.layout)
}
// A file without sample keys parses exactly as before.
plain, err := parseTemplateFile("acme.blog::mail.plain", "acme.blog", "Subject = \"Hi\"\nLAYOUT = 'blog'\n==\nBody.\n")
if err != nil {
t.Fatal(err)
}
if plain.subject != "Hi" || plain.layout != "blog" || plain.body != "Body." || len(plain.samples) != 0 {
t.Errorf("plain file = %+v", plain)
}
// The prefix is matched in any case; the path keeps its case.
mixed, err := parseTemplateFile("acme.blog::mail.mixed", "acme.blog", "SAMPLE.bankDetailsLines = 'x'\nsample. = \"ignored\"\n==\nBody.\n")
if err != nil {
t.Fatal(err)
}
if want := map[string]string{"bankDetailsLines": "x"}; !reflect.DeepEqual(mixed.samples, want) {
t.Errorf("samples = %v, want %v", mixed.samples, want)
}
file, ok := editorCatalog(t, editorWelcomeHTM).Template(editorWelcome)
if !ok || file.Samples["order.code"] != "ZAM-1" {
t.Errorf("TemplateFile.Samples = %v", file.Samples)
}
})
t.Run("walker", func(t *testing.T) {
render := func(src string, samples map[string]string) string {
t.Helper()
out, err := execHTMLFuncs("t", src, placeholderVars(samples, src), map[string]any{
"partial": func(name string, kv ...any) string { return "" },
})
if err != nil {
t.Fatalf("render %q: %v", src, err)
}
return out
}
samples := map[string]string{"Name": "Ada", "order.code": "ZAM-1"}
src := `{{ .Name }} {{ .order.code }} {{ if .employee.first_name }}x{{ end }} {{ range .order.items }}{{ .description }}{{ end }} {{ range .lines }}{{ . }}{{ end }} {{ with .user }}{{ .email }}{{ end }}`
if got, want := render(src, samples), "Ada ZAM-1 x [order.items.description] [lines] [user.email]"; got != want {
t.Errorf("placeholders = %q, want %q", got, want)
}
cases := map[string]struct {
src, want string
samples map[string]string
}{
"if else": {`{{ if .user }}Hi {{ .user.first_name }},{{ else }}Hi,{{ end }}`, "Hi [user.first_name],", nil},
"range fields": {"{{ range .order.items }}- {{ .description }} x {{ .count }}\n{{ end }}", "- [order.items.description] x [order.items.count]\n", nil},
"range variables": {`{{ range $i, $item := .rows }}{{ $item.name }}{{ end }}`, "[rows.name]", nil},
"range one var": {`{{ range $row := .rows }}{{ $row }}{{ end }}`, "[rows]", nil},
"range else": {`{{ range .rows }}{{ .a }}{{ else }}{{ .none }}{{ end }}`, "[rows.a]", nil},
"nested range": {`{{ range .groups }}{{ .title }}:{{ range .items }}{{ .name }}{{ end }}{{ end }}`, "[groups.title]:[groups.items.name]", nil},
"with else": {`{{ with .a.b }}{{ .c }}{{ else }}no{{ end }}`, "[a.b.c]", nil},
"with dot": {`{{ with .note }}{{ . }}{{ end }}`, "[note]", nil},
"root variable": {`{{ range .rows }}{{ $.shop }}{{ end }}`, "[shop]", nil},
"declared var": {`{{ $u := .user }}{{ $u.email }} {{ $u.name }}`, "[user.email] [user.name]", nil},
"chain": {`{{ (.user).email }}`, "[user.email]", nil},
"pipeline": {`{{ .title | printf "%s!" }}`, "[title]!", nil},
"function args": {`{{ printf "%s/%s" .a .b.c }}`, "[a]/[b.c]", nil},
"partial args": {`{{ partial "button" "url" .Link "body" .label.text }}{{ .Link }} {{ .label.text }}`, "[Link] [label.text]", nil},
"range sample": {`{{ range .lines }}{{ . }}{{ end }}`, "One", map[string]string{"lines": "One"}},
"element sample": {`{{ range .items }}{{ .name }}{{ end }}`, "Pen", map[string]string{"items.name": "Pen"}},
"unused sample": {`{{ .a }}`, "[a]", map[string]string{"b.c": "x"}},
"no variables": {`Plain.`, "Plain.", nil},
}
for name, tc := range cases {
if got := render(tc.src, tc.samples); got != tc.want {
t.Errorf("%s: %q, want %q", name, got, tc.want)
}
}
// A sample is available even when the walked sources do not use it.
vars := placeholderVars(map[string]string{"b.c": "x"}, `{{ .a }}`)
if b, ok := vars["b"].(map[string]any); !ok || b["c"] != "x" {
t.Errorf("an unused sample is missing: %v", vars)
}
// A source that does not parse contributes nothing and is not an error here.
if vars := placeholderVars(nil, `{{ .a`, `{{ .b }}`); vars["b"] != "[b]" {
t.Errorf("vars = %v", vars)
}
})
t.Run("validate", func(t *testing.T) {
ed, _ := newEditor(t, nil)
ok := Draft{Kind: KindTemplate, Name: editorWelcome, Subject: "Hi {{ .Name }}", Body: "Order {{ .order.code }} for {{ .customer.address.city }}.\n\n{{ partial \"button\" \"url\" .link \"body\" \"Go\" }}", Layout: editorBlogLayout}
if err := ed.Validate(ctx, ok); err != nil {
t.Fatalf("a valid template draft was refused: %+v", err)
}
layout := Draft{Kind: KindLayout, Name: "promo", HTML: `<div class="promo">{{ .Content }}</div>`, Text: "{{ .Content }}", CSS: ".promo{margin:0}"}
partial := Draft{Kind: KindPartial, Name: editorNote, HTML: `<b>{{ .text }}</b>`, Text: "{{ .text }}"}
for name, d := range map[string]Draft{"layout": layout, "file layout": with(layout, func(d *Draft) { d.Name = editorBlogLayout }), "partial": partial, "empty template layout": with(ok, func(d *Draft) { d.Layout = "" })} {
if err := ed.Validate(ctx, d); err != nil {
t.Errorf("a valid %s draft was refused: %+v", name, err)
}
}
cases := []struct {
name string
draft Draft
field, rule string
message string // substring of Message
partial string // Name
}{
{"body parse", with(ok, func(d *Draft) { d.Body = "Hi {{ .Name" }), "body", "parse", "line 1", ""},
{"subject parse", with(ok, func(d *Draft) { d.Subject = "{{ .Name" }), "subject", "parse", "", ""},
{"body render", with(ok, func(d *Draft) { d.Body = "{{ len 5 }}" }), "body", "render", "len of type int", ""},
{"body script", with(ok, func(d *Draft) { d.Body = "Hi\n\n<script>alert(1)</script>" }), "body", "unsafe", "<script>alert(1)", ""},
{"body scheme", with(ok, func(d *Draft) { d.Body = "See the metadata: field." }), "body", "unsafe", "metadata: field", ""},
{"subject line", with(ok, func(d *Draft) { d.Subject = "Hi\nthere" }), "subject", "subject_line", "", ""},
{"unknown layout", with(ok, func(d *Draft) { d.Layout = "nope" }), "layout", "layout", "", ""},
{"unknown partial", with(ok, func(d *Draft) { d.Body = `{{ partial "nope" "a" "b" }}` }), "body", "partial", "", "postcard::mail.partials.nope"},
{"layout html no content", with(layout, func(d *Draft) { d.HTML = "<div>static</div>" }), "content_html", "no_content", "", ""},
{"layout text no content", with(layout, func(d *Draft) { d.Text = "static" }), "content_text", "no_content", "", ""},
{"layout css", with(layout, func(d *Draft) { d.CSS = "a{}</style><p>x" }), "content_css", "unsafe", "</style>", ""},
{"layout script", with(layout, func(d *Draft) { d.HTML += `<iframe src="https://example.com"></iframe>` }), "content_html", "unsafe", "<iframe", ""},
{"layout html parse", with(layout, func(d *Draft) { d.HTML = "{{ .Content" }), "content_html", "parse", "", ""},
{"layout text parse", with(layout, func(d *Draft) { d.Text = "{{ .Content }}{{ end }}" }), "content_text", "parse", "", ""},
{"layout unknown partial", with(layout, func(d *Draft) { d.HTML += `{{ partial "nope" }}` }), "content_html", "partial", "", "postcard::mail.partials.nope"},
{"partial html parse", with(partial, func(d *Draft) { d.HTML = "{{ .text" }), "content_html", "parse", "", ""},
{"partial text render", with(partial, func(d *Draft) { d.Text = "{{ len 5 }}" }), "content_text", "render", "", ""},
{"partial nested call", with(partial, func(d *Draft) { d.HTML = `{{ partial "button" }}` }), "content_html", "parse", `"partial" not defined`, ""},
{"partial unsafe", with(partial, func(d *Draft) { d.HTML = `<a onclick = "x">{{ .text }}</a>` }), "content_html", "unsafe", "onclick", ""},
{"unknown template", with(ok, func(d *Draft) { d.Name = "acme.blog::mail.gone" }), "body", "render", "acme.blog::mail.gone", ""},
{"unknown partial draft", with(partial, func(d *Draft) { d.Name = "acme.blog::mail.partials.gone" }), "content_html", "partial", "", "acme.blog::mail.partials.gone"},
}
for _, tc := range cases {
got := ed.Validate(ctx, tc.draft)
if got == nil {
t.Errorf("%s: the draft was accepted", tc.name)
continue
}
if got.Field != tc.field || got.Rule != tc.rule || got.Name != tc.partial {
t.Errorf("%s: %+v, want field %q rule %q name %q", tc.name, *got, tc.field, tc.rule, tc.partial)
}
if !strings.Contains(got.Message, tc.message) {
t.Errorf("%s: message %q lacks %q", tc.name, got.Message, tc.message)
}
if strings.Contains(got.Message, "postcard:") || strings.Contains(got.Message, "template: ") {
t.Errorf("%s: message %q carries internal prefixes", tc.name, got.Message)
}
if got.Error() == "" {
t.Errorf("%s: empty Error()", tc.name)
}
}
// A template draft is checked against the layout it selects, with
// the other overrides of the source applied.
ed, _ = newEditor(t, &Overrides{Layouts: map[string]LayoutOverride{"promo": {HTML: `<div class="promo">{{ .Content }}</div>`, Text: "{{ .Content }}"}}})
if err := ed.Validate(ctx, with(ok, func(d *Draft) { d.Layout = "promo" })); err != nil {
t.Errorf("a draft on a database-only layout was refused: %+v", err)
}
})
t.Run("preview", func(t *testing.T) {
ed, drv := newEditor(t, nil)
file, _ := ed.Catalog().Template(editorWelcome)
draft := Draft{Kind: KindTemplate, Name: editorWelcome, Subject: file.Subject, Body: file.Body, Layout: file.Layout}
got, err := ed.Preview(ctx, draft)
if err != nil {
t.Fatalf("Preview: %v", err)
}
if got.Subject != "Welcome, Ada" {
t.Errorf("subject = %q, want the sample value", got.Subject)
}
for _, want := range []string{`<div class="blog-mail"><p>Hi <strong>Ada</strong>, order ZAM-1 for [company].</p>`, "<li>[order.items.description]</li>"} {
if !strings.Contains(got.HTML, want) {
t.Errorf("HTML lacks %q:\n%s", want, got.HTML)
}
}
if !strings.HasPrefix(got.Text, "Hi **Ada**, order ZAM-1 for [company].") || !strings.HasSuffix(got.Text, "-- The Acme blog") {
t.Errorf("text = %q", got.Text)
}
// The preview is what Send produces for the same content and variables.
vars := placeholderVars(file.Samples, file.Subject, file.Body)
if err := ed.m.Send(ctx, Message{Template: editorWelcome, To: []string{"ada@example.com"}, Vars: vars}); err != nil {
t.Fatal(err)
}
sent := lastMessage(t, drv)
if sent.Subject != got.Subject || sent.HTML != got.HTML || sent.Text != got.Text {
t.Errorf("preview differs from the sent mail:\n preview %+v\n sent %+v", got, sent)
}
// A draft that moves the template to another layout.
draft.Layout = systemLayoutName
draft.Subject = "Changed"
got, err = ed.Preview(ctx, draft)
if err != nil {
t.Fatal(err)
}
if got.Subject != "Changed" || !strings.Contains(got.HTML, "layout-system") {
t.Errorf("draft layout not applied: %q / %q", got.Subject, got.HTML)
}
// A layout draft wraps the sample message.
got, err = ed.Preview(ctx, Draft{Kind: KindLayout, Name: "promo", HTML: `<div class="promo">{{ .Content }}</div><style>{{ .css }}</style>`, Text: "PROMO\n{{ .Content }}", CSS: ".promo{margin:0}"})
if err != nil {
t.Fatalf("layout preview: %v", err)
}
for _, want := range []string{`<div class="promo"><h1>`, `class="button button-primary"`, `<table class="panel`, "<style>.promo{margin:0}</style>"} {
if !strings.Contains(got.HTML, want) {
t.Errorf("layout preview lacks %q:\n%s", want, got.HTML)
}
}
if got.Subject == "" || !strings.HasPrefix(got.Text, "PROMO\n") {
t.Errorf("layout preview: %q / %q", got.Subject, got.Text)
}
// A partial draft is called with placeholder arguments.
got, err = ed.Preview(ctx, Draft{Kind: KindPartial, Name: editorNote, HTML: `<div class="note2">{{ .text }} {{ .author.name }}</div>`, Text: "N: {{ .text }}"})
if err != nil {
t.Fatalf("partial preview: %v", err)
}
if !strings.Contains(got.HTML, `<div class="note2">[text] [author.name]</div>`) || !strings.Contains(got.Text, "N: [text]") {
t.Errorf("partial preview: %q / %q", got.HTML, got.Text)
}
// The other pieces come from the override source: a customized
// partial and a customized default layout show in a template preview.
ed, _ = newEditor(t, &Overrides{
Partials: map[string]PartialOverride{editorNote: {HTML: `<aside>{{ .text }}</aside>`, Text: "* {{ .text }}"}},
Layouts: map[string]LayoutOverride{defaultLayoutName: {HTML: `<main>{{ .Content }}</main>`, Text: "{{ .Content }}"}},
// The stored override of the template itself is not the draft.
Template: &TemplateOverride{Subject: "Stored", Body: "Stored."},
})
got, err = ed.Preview(ctx, Draft{Kind: KindTemplate, Name: editorWelcome, Subject: "Draft", Body: `{{ partial "` + editorNote + `" "text" "hi" }}`, Layout: defaultLayoutName})
if err != nil {
t.Fatal(err)
}
if got.Subject != "Draft" || got.HTML != "<main><aside>hi</aside>\n</main>" || got.Text != "* hi" {
t.Errorf("preview with overrides = %+v", got)
}
// A draft problem is a *DraftError.
_, err = ed.Preview(ctx, Draft{Kind: KindTemplate, Name: editorWelcome, Subject: "x", Body: "{{ .a", Layout: defaultLayoutName})
var de *DraftError
if !errors.As(err, &de) || de.Field != "body" || de.Rule != "parse" {
t.Errorf("Preview of a broken draft = %v", err)
}
})
t.Run("send_draft", func(t *testing.T) {
ed, drv := newEditor(t, nil)
draft := Draft{Kind: KindTemplate, Name: editorWelcome, Subject: "Test {{ .Name }}", Body: "Body for {{ .company }}.", Layout: editorBlogLayout}
if err := ed.SendDraft(ctx, draft, "admin@example.com"); err != nil {
t.Fatalf("SendDraft: %v", err)
}
msgs := drv.Messages()
if len(msgs) != 1 {
t.Fatalf("%d messages sent, want 1", len(msgs))
}
msg := msgs[0]
if len(msg.To) != 1 || msg.To[0] != "admin@example.com" || len(msg.Cc) != 0 || len(msg.Bcc) != 0 {
t.Errorf("recipients = %v / %v / %v, want only the given address", msg.To, msg.Cc, msg.Bcc)
}
if msg.From != "blog@example.com" || msg.Subject != "Test Ada" || !strings.Contains(msg.HTML, "<p>Body for [company].</p>") {
t.Errorf("message = %+v", msg)
}
// Layout and partial drafts are sent as their previews.
if err := ed.SendDraft(ctx, Draft{Kind: KindLayout, Name: "promo", HTML: `<div class="promo">{{ .Content }}</div>`, Text: "{{ .Content }}"}, "admin@example.com"); err != nil {
t.Fatalf("SendDraft layout: %v", err)
}
if msg := lastMessage(t, drv); !strings.Contains(msg.HTML, `<div class="promo">`) {
t.Errorf("layout draft mail = %q", msg.HTML)
}
before := len(drv.Messages())
var de *DraftError
if err := ed.SendDraft(ctx, with(draft, func(d *Draft) { d.Body = "{{ .a" }), "admin@example.com"); !errors.As(err, &de) {
t.Errorf("SendDraft of a broken draft = %v", err)
}
for _, to := range []string{"", "not-an-address", "a@example.com\r\nBcc: b@example.com"} {
if err := ed.SendDraft(ctx, draft, to); err == nil {
t.Errorf("SendDraft to %q succeeded", to)
}
}
if len(drv.Messages()) != before {
t.Error("a refused draft was sent")
}
})
t.Run("hash", func(t *testing.T) {
lf := editorCatalog(t, editorWelcomeHTM)
// The same files with CRLF line endings.
crlfFS := fstest.MapFS{}
for path, file := range editorFS(editorWelcomeHTM) {
crlfFS[path] = &fstest.MapFile{Data: []byte(strings.ReplaceAll(string(file.Data), "\n", "\r\n"))}
}
p := editorPlugin(editorWelcomeHTM)
crlf := NewCatalog()
if err := crlf.RegisterPartials(p.id, crlfFS, p.partials); err != nil {
t.Fatal(err)
}
if err := crlf.Register(p.id, crlfFS, p.templates, p.layouts); err != nil {
t.Fatal(err)
}
templates, layouts, partials := lf.Templates(), lf.Layouts(), lf.Partials()
if len(templates) != 2 || len(layouts) != 4 || len(partials) != 5 {
t.Fatalf("catalog holds %d templates, %d layouts, %d partials", len(templates), len(layouts), len(partials))
}
if templates[0].Name != editorWelcome || templates[1].Name != "acme.blog::mail.welcome-en" || layouts[0].Name != editorBlogLayout || partials[0].Name != editorNote {
t.Errorf("lists are not sorted by name: %q %q %q %q", templates[0].Name, templates[1].Name, layouts[0].Name, partials[0].Name)
}
for _, f := range templates {
other, ok := crlf.Template(f.Name)
if !ok || !hex64.MatchString(f.Hash) || other.Hash != f.Hash || other.Source != f.Source || strings.Contains(other.Source, "\r") {
t.Errorf("template %s: hash %q vs CRLF %q", f.Name, f.Hash, other.Hash)
}
}
for _, f := range layouts {
other, ok := crlf.Layout(f.Name)
if !ok || !hex64.MatchString(f.Hash) || other.Hash != f.Hash || other.Source != f.Source {
t.Errorf("layout %s: hash %q vs CRLF %q", f.Name, f.Hash, other.Hash)
}
}
for _, f := range partials {
other, ok := crlf.Partial(f.Name)
if !ok || !hex64.MatchString(f.Hash) || other.Hash != f.Hash || other.Source != f.Source {
t.Errorf("partial %s: hash %q vs CRLF %q", f.Name, f.Hash, other.Hash)
}
}
// A different file has a different hash.
changed, _ := editorCatalog(t, strings.Replace(editorWelcomeHTM, "Hi **", "Hello **", 1)).Template(editorWelcome)
if changed.Hash == templates[0].Hash {
t.Error("a changed file kept its hash")
}
w := templates[0]
if w.PluginID != "acme.blog" || w.Subject != "Welcome, {{ .Name }}" || w.Description != "Sent after registration" || w.Layout != editorBlogLayout ||
!strings.HasPrefix(w.Body, "Hi **{{ .Name }}**") || w.Source != editorWelcomeHTM {
t.Errorf("TemplateFile = %+v", w)
}
if en := templates[1]; en.Layout != defaultLayoutName {
t.Errorf("a template without a layout resolves to %q, want the default layout's full name", en.Layout)
}
blog, _ := lf.Layout(editorBlogLayout)
if blog.Title != "Blog" || blog.PluginID != "acme.blog" || blog.Text != "{{ .Content }}\n\n-- The Acme blog" || blog.HTML != `<div class="blog-mail">{{ .Content }}</div>` {
t.Errorf("LayoutFile = %+v", blog)
}
note, _ := lf.Partial(editorNote)
if note.Title != "Note" || note.Text != "NOTE: {{ .text }}" || note.HTML != `<div class="note">{{ .text }}</div>` {
t.Errorf("PartialFile = %+v", note)
}
if _, ok := lf.Template("acme.blog::mail.gone"); ok {
t.Error("Template found a name that is not registered")
}
if _, ok := lf.Layout("promo"); ok {
t.Error("Layout found a name that is not registered")
}
if _, ok := lf.Partial("button"); ok {
t.Error("Partial resolves bare names; it takes full names")
}
// The serializers give both sides of a comparison the same shape.
if got, want := FormatTemplate("Hi", editorBlogLayout, "Body."), "subject = \"Hi\"\nlayout = \""+editorBlogLayout+"\"\n==\nBody.\n"; got != want {
t.Errorf("FormatTemplate = %q, want %q", got, want)
}
if got, want := FormatLayout("Blog", "T", "<b>H</b>", ""), "name = \"Blog\"\n==\nT\n==\n<b>H</b>\n"; got != want {
t.Errorf("FormatLayout = %q, want %q", got, want)
}
if got, want := FormatLayout("Blog", "T", "<b>H</b>", "a{}"), "name = \"Blog\"\n==\nT\n==\n<b>H</b>\n==\na{}\n"; got != want {
t.Errorf("FormatLayout with CSS = %q, want %q", got, want)
}
if got, want := FormatPartial("Note", "T", "<b>H</b>"), "name = \"Note\"\n==\nT\n==\n<b>H</b>\n"; got != want {
t.Errorf("FormatPartial = %q, want %q", got, want)
}
if got := FormatLayout(blog.Title, blog.Text, blog.HTML, ""); got != blog.Source {
t.Errorf("FormatLayout of a file's parts = %q, want its source %q", got, blog.Source)
}
})
t.Run("locale", func(t *testing.T) {
locales := []string{"en", "pl", "pt-BR"}
cases := map[string]string{
"acme.blog::mail.welcome-en": "en",
"acme.blog::mail.cancel-notice": "",
"acme.blog::mail.welcome": "",
"acme.blog::mail.two_factor_code-en": "en",
"acme.blog::mail.order.paid-pl": "pl",
"acme.blog::mail.order-en.paid": "",
"acme.blog::mail.welcome-EN": "en",
"acme.blog::mail.welcome-pt-BR": "pt-BR",
"acme.blog::mail.-en": "",
"acme-en": "",
}
for name, want := range cases {
if got := TemplateLocale(name, locales); got != want {
t.Errorf("TemplateLocale(%q) = %q, want %q", name, got, want)
}
}
if got := TemplateLocale("acme.blog::mail.welcome-en", nil); got != "" {
t.Errorf("TemplateLocale without locales = %q", got)
}
})
t.Run("sync", func(t *testing.T) {
gdb := mailPostgres(t)
cat := editorCatalog(t, editorWelcomeHTM)
locales := []string{"en", "pl"}
if err := SyncIndex(ctx, gdb, cat, locales); err != nil {
t.Fatalf("SyncIndex: %v", err)
}
type row struct {
ID int64
Code string
Source *string
Locale *string
Description string
Subject string
Body string
LayoutID *int64
Name string
ContentHTML string `gorm:"column:content_html"`
ContentText string `gorm:"column:content_text"`
IsCustom bool
FileHash *string
BaseHash *string
UpdatedText string
}
rows := func(table string) map[string]row {
t.Helper()
var list []row
if err := gdb.Raw(`SELECT *, updated_at::text AS updated_text FROM ` + table + ` ORDER BY code`).Scan(&list).Error; err != nil {
t.Fatal(err)
}
out := make(map[string]row, len(list))
for _, r := range list {
out[r.Code] = r
}
return out
}
templates, layouts, partials := rows(TemplatesTable), rows(LayoutsTable), rows(PartialsTable)
if len(templates) != 2 || len(layouts) != 4 || len(partials) != 5 {
t.Fatalf("index holds %d templates, %d layouts, %d partials", len(templates), len(layouts), len(partials))
}
file, _ := cat.Template(editorWelcome)
w := templates[editorWelcome]
if w.Source == nil || *w.Source != "acme.blog" || w.Locale != nil || w.Description != file.Description || w.Subject != file.Subject || w.Body != file.Body ||
w.IsCustom || w.FileHash == nil || *w.FileHash != file.Hash || w.BaseHash != nil {
t.Errorf("welcome row = %+v", w)
}
if w.LayoutID == nil || *w.LayoutID != layouts[editorBlogLayout].ID {
t.Errorf("welcome row layout_id = %v, want the blog layout row %d", w.LayoutID, layouts[editorBlogLayout].ID)
}
if en := templates["acme.blog::mail.welcome-en"]; en.Locale == nil || *en.Locale != "en" || en.LayoutID == nil || *en.LayoutID != layouts[defaultLayoutName].ID {
t.Errorf("welcome-en row = %+v", en)
}
blog, _ := cat.Layout(editorBlogLayout)
if l := layouts[editorBlogLayout]; l.Name != "Blog" || l.ContentHTML != blog.HTML || l.ContentText != blog.Text || l.IsCustom || *l.FileHash != blog.Hash || *l.Source != "acme.blog" {
t.Errorf("blog layout row = %+v", l)
}
if l := layouts[systemLayoutName]; l.Name != "System layout" || *l.Source != "postcard" {
t.Errorf("system layout row = %+v", l)
}
note, _ := cat.Partial(editorNote)
if p := partials[editorNote]; p.Name != "Note" || p.ContentHTML != note.HTML || p.ContentText != note.Text || *p.FileHash != note.Hash {
t.Errorf("note partial row = %+v", p)
}
// A second run changes nothing, IDs and timestamps included.
if err := SyncIndex(ctx, gdb, cat, locales); err != nil {
t.Fatal(err)
}
if again := rows(TemplatesTable); !reflect.DeepEqual(again, templates) {
t.Errorf("a second sync changed the template rows:\n%+v\n%+v", templates, again)
}
if again := rows(LayoutsTable); !reflect.DeepEqual(again, layouts) {
t.Error("a second sync changed the layout rows")
}
if again := rows(PartialsTable); !reflect.DeepEqual(again, partials) {
t.Error("a second sync changed the partial rows")
}
// An override, a database-only layout and a row of a template this
// catalog does not hold.
defaultID := layouts[defaultLayoutName].ID
stmts := []string{
`UPDATE ` + TemplatesTable + ` SET subject = 'Mine', body = 'My body.', layout_id = ` + itoa(defaultID) + `, is_custom = TRUE, base_hash = 'based-on', customized_at = NOW() WHERE code = '` + editorWelcome + `'`,
`UPDATE ` + PartialsTable + ` SET content_html = '<i>mine</i>', is_custom = TRUE, base_hash = 'based-on' WHERE code = '` + editorNote + `'`,
`UPDATE ` + LayoutsTable + ` SET content_html = '<p>mine {{ .Content }}</p>', is_custom = TRUE, base_hash = 'based-on' WHERE code = '` + editorBlogLayout + `'`,
`INSERT INTO ` + LayoutsTable + ` (code, source, name, content_html, content_text, is_custom) VALUES ('promo', NULL, 'Promo', '<p>{{ .Content }}</p>', '{{ .Content }}', TRUE)`,
`INSERT INTO ` + TemplatesTable + ` (code, source, subject, body) VALUES ('acme.old::mail.gone', 'acme.old', 'Old', 'Old.')`,
}
for _, stmt := range stmts {
if err := gdb.Exec(stmt).Error; err != nil {
t.Fatal(err)
}
}
promo := rows(LayoutsTable)["promo"]
// The plugin ships changed files: the override columns stay, the
// file columns follow the files.
changedSrc := strings.Replace(strings.Replace(editorWelcomeHTM, "Sent after registration", "Sent on sign-up", 1), "Hi **", "Hello **", 1)
changed := editorCatalog(t, changedSrc)
if err := SyncIndex(ctx, gdb, changed, locales); err != nil {
t.Fatal(err)
}
newFile, _ := changed.Template(editorWelcome)
after := rows(TemplatesTable)
w2 := after[editorWelcome]
if w2.ID != w.ID || w2.Subject != "Mine" || w2.Body != "My body." || *w2.LayoutID != defaultID || !w2.IsCustom || *w2.BaseHash != "based-on" {
t.Errorf("sync touched the override columns of a customized row: %+v", w2)
}
if *w2.FileHash != newFile.Hash || w2.Description != "Sent on sign-up" || *w2.FileHash == *w.FileHash {
t.Errorf("sync did not refresh the file columns of a customized row: %+v", w2)
}
if len(after) != 3 || after["acme.old::mail.gone"].Subject != "Old" {
t.Errorf("sync deleted or changed a row outside the catalog: %+v", after)
}
afterLayouts := rows(LayoutsTable)
if got := afterLayouts["promo"]; !reflect.DeepEqual(got, promo) {
t.Errorf("sync touched a database-only layout: %+v", got)
}
if l := afterLayouts[editorBlogLayout]; l.ContentHTML != "<p>mine {{ .Content }}</p>" || !l.IsCustom {
t.Errorf("sync touched a customized layout: %+v", l)
}
if p := rows(PartialsTable)[editorNote]; p.ContentHTML != "<i>mine</i>" || !p.IsCustom {
t.Errorf("sync touched a customized partial: %+v", p)
}
// A row that is not customized follows the file.
if err := gdb.Exec(`UPDATE ` + TemplatesTable + ` SET is_custom = FALSE WHERE code = '` + editorWelcome + `'`).Error; err != nil {
t.Fatal(err)
}
if err := SyncIndex(ctx, gdb, changed, locales); err != nil {
t.Fatal(err)
}
if w3 := rows(TemplatesTable)[editorWelcome]; w3.Subject != newFile.Subject || w3.Body != newFile.Body || *w3.LayoutID != layouts[editorBlogLayout].ID {
t.Errorf("a row that is not customized was not mirrored from the file: %+v", w3)
}
// Concurrent runs both succeed.
var wg sync.WaitGroup
errs := make([]error, 4)
for i := range errs {
wg.Add(1)
go func() {
defer wg.Done()
errs[i] = SyncIndex(ctx, gdb, cat, locales)
}()
}
wg.Wait()
for i, err := range errs {
if err != nil {
t.Errorf("concurrent SyncIndex %d: %v", i, err)
}
}
if got := rows(TemplatesTable); len(got) != 3 || got[editorWelcome].ID != w.ID {
t.Errorf("concurrent syncs changed the rows: %+v", got)
}
// Tables that are not migrated yet are an error for the caller to report.
empty := mailPostgres(t)
if err := empty.Exec(`DROP TABLE ` + TemplatesTable).Error; err != nil {
t.Fatal(err)
}
if err := SyncIndex(ctx, empty, cat, locales); err == nil {
t.Error("SyncIndex without the tables succeeded")
}
if err := SyncIndex(ctx, nil, cat, locales); err == nil {
t.Error("SyncIndex with a nil database succeeded")
}
})
t.Run("reset", func(t *testing.T) {
gdb := mailPostgres(t)
cat := editorCatalog(t, editorWelcomeHTM)
if err := SyncIndex(ctx, gdb, cat, nil); err != nil {
t.Fatal(err)
}
stmts := []string{
`UPDATE ` + TemplatesTable + ` SET subject = 'Mine', body = 'My body.', layout_id = (SELECT id FROM ` + LayoutsTable + ` WHERE code = '` + defaultLayoutName + `'), is_custom = TRUE, base_hash = 'based-on', customized_at = NOW() WHERE code = '` + editorWelcome + `'`,
`UPDATE ` + LayoutsTable + ` SET content_html = 'mine', content_text = 'mine', content_css = 'a{}', is_custom = TRUE, base_hash = 'based-on', customized_at = NOW() WHERE code = '` + editorBlogLayout + `'`,
`UPDATE ` + PartialsTable + ` SET content_html = 'mine', content_text = 'mine', is_custom = TRUE, base_hash = 'based-on', customized_at = NOW() WHERE code = '` + editorNote + `'`,
`INSERT INTO ` + LayoutsTable + ` (code, source, name, content_html, content_text, is_custom) VALUES ('promo', NULL, 'Promo', '<p>{{ .Content }}</p>', '{{ .Content }}', TRUE)`,
}
for _, stmt := range stmts {
if err := gdb.Exec(stmt).Error; err != nil {
t.Fatal(err)
}
}
type state struct {
Subject string
Body string
Layout string
ContentHTML string `gorm:"column:content_html"`
ContentText string `gorm:"column:content_text"`
ContentCSS string `gorm:"column:content_css"`
IsCustom bool
BaseHash *string
CustomizedAt *string
FileHash *string
}
read := func(query, code string) state {
t.Helper()
var s state
if err := gdb.Raw(query, code).Scan(&s).Error; err != nil {
t.Fatal(err)
}
return s
}
if err := ResetOverride(ctx, gdb, cat, KindTemplate, editorWelcome); err != nil {
t.Fatalf("ResetOverride template: %v", err)
}
file, _ := cat.Template(editorWelcome)
got := read(`SELECT t.subject, t.body, l.code AS layout, t.is_custom, t.base_hash, t.customized_at::text AS customized_at, t.file_hash
FROM `+TemplatesTable+` t LEFT JOIN `+LayoutsTable+` l ON l.id = t.layout_id WHERE t.code = ?`, editorWelcome)
if got.Subject != file.Subject || got.Body != file.Body || got.Layout != editorBlogLayout || got.IsCustom || got.BaseHash != nil || got.CustomizedAt != nil || *got.FileHash != file.Hash {
t.Errorf("template after reset = %+v", got)
}
if err := ResetOverride(ctx, gdb, cat, KindLayout, editorBlogLayout); err != nil {
t.Fatalf("ResetOverride layout: %v", err)
}
blog, _ := cat.Layout(editorBlogLayout)
got = read(`SELECT content_html, content_text, content_css, is_custom, base_hash, customized_at::text AS customized_at, file_hash FROM `+LayoutsTable+` WHERE code = ?`, editorBlogLayout)
if got.ContentHTML != blog.HTML || got.ContentText != blog.Text || got.ContentCSS != "" || got.IsCustom || got.BaseHash != nil || got.CustomizedAt != nil {
t.Errorf("layout after reset = %+v", got)
}
if err := ResetOverride(ctx, gdb, cat, KindPartial, editorNote); err != nil {
t.Fatalf("ResetOverride partial: %v", err)
}
note, _ := cat.Partial(editorNote)
got = read(`SELECT content_html, content_text, is_custom, base_hash, customized_at::text AS customized_at, file_hash FROM `+PartialsTable+` WHERE code = ?`, editorNote)
if got.ContentHTML != note.HTML || got.ContentText != note.Text || got.IsCustom || got.BaseHash != nil || got.CustomizedAt != nil {
t.Errorf("partial after reset = %+v", got)
}
// A database-only layout has no file version: it is deleted, never reset.
if err := ResetOverride(ctx, gdb, cat, KindLayout, "promo"); err == nil {
t.Error("ResetOverride of a database-only layout succeeded")
}
if got := read(`SELECT content_html, is_custom FROM `+LayoutsTable+` WHERE code = ?`, "promo"); got.ContentHTML != "<p>{{ .Content }}</p>" || !got.IsCustom {
t.Errorf("a refused reset changed the row: %+v", got)
}
for name, err := range map[string]error{
"unknown code": ResetOverride(ctx, gdb, cat, KindTemplate, "acme.blog::mail.gone"),
"brand": ResetOverride(ctx, gdb, cat, KindBrand, "1"),
"nil db": ResetOverride(ctx, nil, cat, KindTemplate, editorWelcome),
} {
if err == nil {
t.Errorf("ResetOverride (%s) succeeded", name)
}
}
})
}
func with(d Draft, edit func(*Draft)) Draft { edit(&d); return d }
func itoa(n int64) string { return strconv.FormatInt(n, 10) }

View File

@@ -28,10 +28,12 @@ const (
// 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.
// partialError is a failed partial call. name is the partial's full name;
// unknown is set when no such partial is registered.
type partialError struct {
name string
msg string
name string
msg string
unknown bool
}
func (e *partialError) Error() string {
@@ -78,7 +80,7 @@ func partialName(name string) string {
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"}
return "", "", &partialError{name: full, msg: "unknown partial", unknown: true}
}
if ov, ok := r.overrides[full]; ok {
return ov.Text, ov.HTML, nil

253
modules/postcard/samples.go Normal file
View File

@@ -0,0 +1,253 @@
package postcard
import (
"strings"
"text/template/parse"
)
// samplePrefix starts the header keys that give a template's variables
// sample values, as in sample.order.code = "ZAM-1".
const samplePrefix = "sample."
// placeholderVars builds the variables a draft is validated and previewed
// with. It walks the parse trees of sources and gives every variable they
// read a value: its sample from samples (keyed by dotted path), or the
// visible placeholder "[path]". A field of a variable becomes a nested map
// and the target of a range a slice of one element, so that templates that
// read .order.code or range over .order.items render instead of failing on a
// missing value. A source that does not parse contributes nothing; the
// render that follows reports it.
func placeholderVars(samples map[string]string, sources ...string) map[string]any {
root := &phNode{}
for _, src := range sources {
tree := parse.New("placeholders")
// Function names are not checked: partial and markdown exist only
// in the real render.
tree.Mode = parse.SkipFuncCheck
if _, err := tree.Parse(src, "", "", map[string]*parse.Tree{}); err != nil || tree.Root == nil {
continue
}
w := phWalker{root: root}
w.list(tree.Root, phScope{dot: root})
}
// Samples the sources do not read are still variables of the template.
for path := range samples {
node := root
for _, name := range strings.Split(path, ".") {
if name == "" {
node = nil
break
}
node = node.field(name)
}
}
vars, _ := root.value("", samples).(map[string]any)
if vars == nil {
vars = map[string]any{}
}
return vars
}
// phNode is one variable, or one field of one, that the sources read.
type phNode struct {
fields map[string]*phNode
// elem is set when the sources range over the node: the node of one
// element.
elem *phNode
}
// field returns the node of a field of n. A field of a ranged node is a
// field of its elements.
func (n *phNode) field(name string) *phNode {
if n == nil {
return nil
}
if n.elem != nil {
n = n.elem
}
if n.fields == nil {
n.fields = make(map[string]*phNode)
}
child, ok := n.fields[name]
if !ok {
child = &phNode{}
n.fields[name] = child
}
return child
}
func (n *phNode) path(names []string) *phNode {
for _, name := range names {
n = n.field(name)
}
return n
}
// value turns the node into template data. path is its dotted path; the
// elements of a ranged node keep the path of the node.
func (n *phNode) value(path string, samples map[string]string) any {
if n.elem != nil {
return []any{n.elem.value(path, samples)}
}
if len(n.fields) > 0 {
out := make(map[string]any, len(n.fields))
for name, child := range n.fields {
childPath := name
if path != "" {
childPath = path + "." + name
}
out[name] = child.value(childPath, samples)
}
return out
}
if sample, ok := samples[path]; ok {
return sample
}
return "[" + path + "]"
}
// phScope is what a template action sees: the node of the dot (nil when it
// is not a variable the walker follows) and the nodes of declared variables.
type phScope struct {
dot *phNode
vars map[string]*phNode
}
func (s phScope) with(dot *phNode) phScope {
return phScope{dot: dot, vars: s.vars}
}
// bind returns the scope with a variable declared. Scopes share nothing, so
// a declaration inside a block does not leak out of it.
func (s phScope) bind(name string, node *phNode) phScope {
vars := make(map[string]*phNode, len(s.vars)+1)
for k, v := range s.vars {
vars[k] = v
}
vars[name] = node
return phScope{dot: s.dot, vars: vars}
}
type phWalker struct {
root *phNode
}
func (w *phWalker) list(list *parse.ListNode, scope phScope) {
if list == nil {
return
}
for _, node := range list.Nodes {
scope = w.node(node, scope)
}
}
// node walks one node and returns the scope for the nodes after it, which
// differs when the node declares a variable.
func (w *phWalker) node(node parse.Node, scope phScope) phScope {
switch n := node.(type) {
case *parse.ActionNode:
_, scope = w.pipe(n.Pipe, scope)
case *parse.IfNode:
_, inner := w.pipe(n.Pipe, scope)
w.list(n.List, inner)
w.list(n.ElseList, inner)
case *parse.WithNode:
target, inner := w.pipe(n.Pipe, scope)
w.list(n.List, inner.with(target))
w.list(n.ElseList, inner)
case *parse.RangeNode:
w.rangeNode(n, scope)
case *parse.TemplateNode:
w.pipe(n.Pipe, scope)
case *parse.ListNode:
w.list(n, scope)
}
return scope
}
func (w *phWalker) rangeNode(n *parse.RangeNode, scope phScope) {
if n.Pipe == nil {
return
}
// The declarations of a range name the index and the element, not the
// pipeline's value: walk the commands only.
var target *phNode
for _, cmd := range n.Pipe.Cmds {
target = w.command(cmd, scope)
}
if len(n.Pipe.Cmds) != 1 {
target = nil
}
var elem *phNode
if target != nil {
if target.elem == nil {
// Fields read before the range belong to the elements too.
target.elem = &phNode{fields: target.fields}
target.fields = nil
}
elem = target.elem
}
body := scope.with(elem)
if decl := n.Pipe.Decl; len(decl) > 0 {
for _, v := range decl[:len(decl)-1] {
body = body.bind(v.Ident[0], nil)
}
body = body.bind(decl[len(decl)-1].Ident[0], elem)
}
w.list(n.List, body)
w.list(n.ElseList, scope)
}
// pipe walks a pipeline. It returns the node the pipeline evaluates to when
// that is a variable the walker follows, and the scope with the pipeline's
// declarations.
func (w *phWalker) pipe(pipe *parse.PipeNode, scope phScope) (*phNode, phScope) {
if pipe == nil {
return nil, scope
}
var target *phNode
for _, cmd := range pipe.Cmds {
target = w.command(cmd, scope)
}
if len(pipe.Cmds) != 1 {
target = nil
}
for _, v := range pipe.Decl {
scope = scope.bind(v.Ident[0], target)
}
return target, scope
}
// command walks one command of a pipeline and returns its node when the
// command is a single variable reference.
func (w *phWalker) command(cmd *parse.CommandNode, scope phScope) *phNode {
var target *phNode
for _, arg := range cmd.Args {
target = w.arg(arg, scope)
}
if len(cmd.Args) != 1 {
return nil
}
return target
}
func (w *phWalker) arg(arg parse.Node, scope phScope) *phNode {
switch a := arg.(type) {
case *parse.FieldNode:
return scope.dot.path(a.Ident)
case *parse.DotNode:
return scope.dot
case *parse.VariableNode:
base := scope.vars[a.Ident[0]]
if a.Ident[0] == "$" {
base = w.root
}
return base.path(a.Ident[1:])
case *parse.ChainNode:
return w.arg(a.Node, scope).path(a.Field)
case *parse.PipeNode:
target, _ := w.pipe(a, scope)
return target
}
return nil
}

View File

@@ -264,3 +264,162 @@ WHERE t.code = ? AND t.is_custom`, name).Scan(&rows).Error
}
return out, nil
}
// syncLockKey names the advisory lock that serializes SyncIndex runs.
const syncLockKey = "summercms.postcard.sync"
// SyncIndex gives every template, layout and partial of cat its index row,
// keyed by code, so that admin lists, forms and relations can work on rows.
// It runs layouts first, then templates (whose layout_id points at the
// layout row of the file's layout), then partials.
//
// For a row that is not customized the content columns mirror the file. For
// a customized row they are left alone: only source, description, locale,
// name and file_hash follow the file, which is what makes a changed file
// show as a difference between base_hash and file_hash. No row is deleted,
// database-only layouts are not touched, and a row that already matches is
// not written. locales are the application's locales, for TemplateLocale.
//
// It is safe to call from several processes at once. It fails when the
// tables are not migrated yet; the caller decides when to try again.
func SyncIndex(ctx context.Context, db *gorm.DB, cat *Catalog, locales []string) error {
if db == nil {
return fmt.Errorf("postcard: sync index: database is nil")
}
if cat == nil {
return fmt.Errorf("postcard: sync index: catalog is nil")
}
layouts, templates, partials := cat.Layouts(), cat.Templates(), cat.Partials()
err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := tx.Exec(`SELECT pg_advisory_xact_lock(hashtext(?))`, syncLockKey).Error; err != nil {
return err
}
for _, l := range layouts {
if err := tx.Exec(`INSERT INTO `+LayoutsTable+` AS t (code, source, name, content_html, content_text, content_css, file_hash)
VALUES (?, ?, ?, ?, ?, '', ?)
ON CONFLICT (code) DO UPDATE SET
source = EXCLUDED.source,
name = EXCLUDED.name,
file_hash = EXCLUDED.file_hash,
content_html = CASE WHEN t.is_custom THEN t.content_html ELSE EXCLUDED.content_html END,
content_text = CASE WHEN t.is_custom THEN t.content_text ELSE EXCLUDED.content_text END,
content_css = CASE WHEN t.is_custom THEN t.content_css ELSE EXCLUDED.content_css END,
updated_at = NOW()
WHERE t.source IS DISTINCT FROM EXCLUDED.source
OR t.name IS DISTINCT FROM EXCLUDED.name
OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
OR (NOT t.is_custom AND (t.content_html, t.content_text, t.content_css)
IS DISTINCT FROM (EXCLUDED.content_html, EXCLUDED.content_text, EXCLUDED.content_css))`,
l.Name, l.PluginID, rowName(l.Title, l.Name), l.HTML, l.Text, l.Hash).Error; err != nil {
return err
}
}
for _, f := range templates {
if err := tx.Exec(`INSERT INTO `+TemplatesTable+` AS t (code, source, locale, description, subject, body, layout_id, file_hash)
VALUES (?, ?, NULLIF(?, ''), ?, ?, ?, (SELECT id FROM `+LayoutsTable+` WHERE code = ?), ?)
ON CONFLICT (code) DO UPDATE SET
source = EXCLUDED.source,
locale = EXCLUDED.locale,
description = EXCLUDED.description,
file_hash = EXCLUDED.file_hash,
subject = CASE WHEN t.is_custom THEN t.subject ELSE EXCLUDED.subject END,
body = CASE WHEN t.is_custom THEN t.body ELSE EXCLUDED.body END,
layout_id = CASE WHEN t.is_custom THEN t.layout_id ELSE EXCLUDED.layout_id END,
updated_at = NOW()
WHERE t.source IS DISTINCT FROM EXCLUDED.source
OR t.locale IS DISTINCT FROM EXCLUDED.locale
OR t.description IS DISTINCT FROM EXCLUDED.description
OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
OR (NOT t.is_custom AND (t.subject, t.body, t.layout_id)
IS DISTINCT FROM (EXCLUDED.subject, EXCLUDED.body, EXCLUDED.layout_id))`,
f.Name, f.PluginID, TemplateLocale(f.Name, locales), f.Description, f.Subject, f.Body, f.Layout, f.Hash).Error; err != nil {
return err
}
}
for _, p := range partials {
if err := tx.Exec(`INSERT INTO `+PartialsTable+` AS t (code, source, name, content_html, content_text, file_hash)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT (code) DO UPDATE SET
source = EXCLUDED.source,
name = EXCLUDED.name,
file_hash = EXCLUDED.file_hash,
content_html = CASE WHEN t.is_custom THEN t.content_html ELSE EXCLUDED.content_html END,
content_text = CASE WHEN t.is_custom THEN t.content_text ELSE EXCLUDED.content_text END,
updated_at = NOW()
WHERE t.source IS DISTINCT FROM EXCLUDED.source
OR t.name IS DISTINCT FROM EXCLUDED.name
OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
OR (NOT t.is_custom AND (t.content_html, t.content_text)
IS DISTINCT FROM (EXCLUDED.content_html, EXCLUDED.content_text))`,
p.Name, p.PluginID, rowName(p.Title, p.Name), p.HTML, p.Text, p.Hash).Error; err != nil {
return err
}
}
return nil
})
if err != nil {
return fmt.Errorf("postcard: sync index: %w", err)
}
return nil
}
// rowName is the name column of a layout or partial row: the name in the
// file's header, or the full name when the header has none.
func rowName(title, full string) string {
if title != "" {
return title
}
return full
}
// ResetOverride returns one file-backed row to its file version: the content
// columns mirror the file again and is_custom, base_hash and customized_at
// are cleared. kind is KindTemplate, KindLayout or KindPartial and code the
// row's code. A database-only layout has no file version: it is refused, and
// so is a code cat does not hold.
func ResetOverride(ctx context.Context, db *gorm.DB, cat *Catalog, kind Kind, code string) error {
if db == nil {
return fmt.Errorf("postcard: reset %s: database is nil", code)
}
if cat == nil {
return fmt.Errorf("postcard: reset %s: catalog is nil", code)
}
db = db.WithContext(ctx)
var res *gorm.DB
switch kind {
case KindTemplate:
f, ok := cat.Template(code)
if !ok {
return fmt.Errorf("postcard: reset %s: no file version", code)
}
res = db.Exec(`UPDATE `+TemplatesTable+` SET subject = ?, body = ?,
layout_id = (SELECT id FROM `+LayoutsTable+` WHERE code = ?),
file_hash = ?, is_custom = FALSE, base_hash = NULL, customized_at = NULL, updated_at = NOW()
WHERE code = ? AND source IS NOT NULL`, f.Subject, f.Body, f.Layout, f.Hash, code)
case KindLayout:
f, ok := cat.Layout(code)
if !ok {
return fmt.Errorf("postcard: reset %s: no file version", code)
}
res = db.Exec(`UPDATE `+LayoutsTable+` SET name = ?, content_html = ?, content_text = ?, content_css = '',
file_hash = ?, is_custom = FALSE, base_hash = NULL, customized_at = NULL, updated_at = NOW()
WHERE code = ? AND source IS NOT NULL`, rowName(f.Title, f.Name), f.HTML, f.Text, f.Hash, code)
case KindPartial:
f, ok := cat.Partial(code)
if !ok {
return fmt.Errorf("postcard: reset %s: no file version", code)
}
res = db.Exec(`UPDATE `+PartialsTable+` SET name = ?, content_html = ?, content_text = ?,
file_hash = ?, is_custom = FALSE, base_hash = NULL, customized_at = NULL, updated_at = NOW()
WHERE code = ? AND source IS NOT NULL`, rowName(f.Title, f.Name), f.HTML, f.Text, f.Hash, code)
default:
return fmt.Errorf("postcard: reset %s: kind %q has no file version", code, kind)
}
if res.Error != nil {
return fmt.Errorf("postcard: reset %s: %w", code, res.Error)
}
if res.RowsAffected == 0 {
return fmt.Errorf("postcard: reset %s: no index row", code)
}
return nil
}

View File

@@ -2,11 +2,15 @@ package postcard
import (
"bytes"
"crypto/sha256"
"embed"
"encoding/hex"
"errors"
"fmt"
"html/template"
"io/fs"
"regexp"
"sort"
"strings"
"sync"
texttemplate "text/template"
@@ -68,6 +72,9 @@ type parsedTemplate struct {
description string
layout string // short name from header; empty means default
body string
samples map[string]string // sample.<path> header keys by path
source string // the file's text, CRLF normalized to LF
hash string // sha256 of source, hex
}
type parsedLayout struct {
@@ -76,6 +83,8 @@ type parsedLayout struct {
headerName string
textWrap string
htmlWrap string
source string
hash string
}
// parsedPartial is a partial file: the layout file format, a header, a text
@@ -86,6 +95,8 @@ type parsedPartial struct {
headerName string
textWrap string
htmlWrap string
source string
hash string
}
// NewCatalog returns a catalog that already contains postcard's built-in
@@ -309,11 +320,12 @@ func assetPath(fullName string) (string, error) {
}
func parseTemplateFile(name, pluginID, src string) (*parsedTemplate, error) {
src = normalizeNewlines(src)
header, body, err := splitTwo(src)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
}
fields, err := parseINI(header)
fields, samples, err := parseHeader(header)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
}
@@ -324,10 +336,14 @@ func parseTemplateFile(name, pluginID, src string) (*parsedTemplate, error) {
description: fields["description"],
layout: fields["layout"],
body: strings.TrimSuffix(body, "\n"),
samples: samples,
source: src,
hash: fileHash(src),
}, nil
}
func parseLayout(name, pluginID, src string) (*parsedLayout, error) {
src = normalizeNewlines(src)
header, textWrap, htmlWrap, err := splitThree(src)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
@@ -342,15 +358,28 @@ func parseLayout(name, pluginID, src string) (*parsedLayout, error) {
headerName: fields["name"],
textWrap: strings.TrimSuffix(textWrap, "\n"),
htmlWrap: strings.TrimSuffix(htmlWrap, "\n"),
source: src,
hash: fileHash(src),
}, nil
}
func normalizeNewlines(src string) string {
return strings.ReplaceAll(src, "\r\n", "\n")
}
// fileHash is the hash an override's base_hash is compared with: sha256 of
// the file's text with CRLF normalized to LF, in hex.
func fileHash(normalized string) string {
sum := sha256.Sum256([]byte(normalized))
return hex.EncodeToString(sum[:])
}
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
return &parsedPartial{name: l.name, pluginID: l.pluginID, headerName: l.headerName, textWrap: l.textWrap, htmlWrap: l.htmlWrap, source: l.source, hash: l.hash}, nil
}
func splitTwo(src string) (header, body string, err error) {
@@ -370,7 +399,7 @@ func splitThree(src string) (header, textWrap, htmlWrap string, err error) {
}
func splitEQ(src string, n int) ([]string, error) {
src = strings.ReplaceAll(src, "\r\n", "\n")
src = normalizeNewlines(src)
lines := strings.Split(src, "\n")
parts := make([]string, 0, n)
start := 0
@@ -388,18 +417,28 @@ func splitEQ(src string, n int) ([]string, error) {
return nil, fmt.Errorf("missing == separator")
}
// parseINI reads a header's key = value lines. Keys are lower-cased.
func parseINI(header string) (map[string]string, error) {
fields, _, err := parseHeader(header)
return fields, err
}
// parseHeader reads a header's key = value lines into fields, with
// lower-cased keys, and its sample.<path> keys into samples by path. The
// path keeps its case, because template variables are case-sensitive.
func parseHeader(header string) (fields, samples map[string]string, err error) {
out := make(map[string]string)
for _, line := range strings.Split(header, "\n") {
line = strings.TrimSpace(line)
if line == "" || strings.HasPrefix(line, ";") || strings.HasPrefix(line, "#") {
continue
}
key, val, ok := strings.Cut(line, "=")
rawKey, val, ok := strings.Cut(line, "=")
if !ok {
return nil, fmt.Errorf("invalid header line %q", line)
return nil, nil, fmt.Errorf("invalid header line %q", line)
}
key = strings.ToLower(strings.TrimSpace(key))
rawKey = strings.TrimSpace(rawKey)
key := strings.ToLower(rawKey)
val = strings.TrimSpace(val)
if len(val) >= 2 {
if q := val[0]; (q == '"' || q == '\'') && val[len(val)-1] == q {
@@ -407,11 +446,20 @@ func parseINI(header string) (map[string]string, error) {
}
}
if key == "" {
return nil, fmt.Errorf("invalid header line %q", line)
return nil, nil, fmt.Errorf("invalid header line %q", line)
}
if strings.HasPrefix(key, samplePrefix) {
if path := rawKey[len(samplePrefix):]; path != "" {
if samples == nil {
samples = make(map[string]string)
}
samples[path] = val
}
continue
}
out[key] = val
}
return out, nil
return out, samples, nil
}
type renderOptions struct {
@@ -454,10 +502,71 @@ func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, erro
return c.renderFrom(msg, src, opts)
}
// The parts of a message a render can fail in.
const (
partSubject = "subject"
partBody = "body"
partLayout = "layout"
partLayoutText = "layout.text"
partLayoutHTML = "layout.html"
)
// renderError places a render failure in a part of the message. Its text is
// the failure's own.
type renderError struct {
part string
err error
}
func (e *renderError) Error() string { return e.err.Error() }
func (e *renderError) Unwrap() error { return e.err }
func inPart(part string, err error) error {
return &renderError{part: part, err: err}
}
// tmplError is a template that did not parse or did not execute. name is the
// template's name: a mail name plus .subject, .body, .text or .html.
type tmplError struct {
name string
parse bool
err error
}
func (e *tmplError) Error() string {
verb := "execute"
if e.parse {
verb = "parse"
}
return "postcard: " + verb + " " + e.name + ": " + e.err.Error()
}
func (e *tmplError) Unwrap() error { return e.err }
// unsafeError is rendered HTML that failed a safety check. snippet is the
// text that matched, with some of what surrounds it.
type unsafeError struct {
msg string
snippet string
}
func (e *unsafeError) Error() string { return "postcard: " + e.msg }
var errSubjectLine = errors.New("postcard: subject contains CR/LF")
// 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
out, part, err := c.renderParts(msg, src, opts)
if err != nil {
return RenderedMessage{}, inPart(part, err)
}
return out, nil
}
// renderParts is renderFrom's work; with an error it returns the part of
// the message that failed.
func (c *Catalog) renderParts(msg Message, src renderSource, opts renderOptions) (out RenderedMessage, part string, err error) {
vars := msg.Vars
if vars == nil {
vars = map[string]any{}
@@ -468,30 +577,30 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
}
subject, err := execHTML(src.name+".subject", subjectSrc, vars)
if err != nil {
return out, err
return out, partSubject, err
}
if strings.ContainsAny(subject, "\r\n") {
return out, fmt.Errorf("postcard: subject contains CR/LF")
return out, partSubject, errSubjectLine
}
// 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
return out, partBody, err
}
htmlBody, err := markdownHTML(markdownBody)
if err != nil {
return out, err
return out, partBody, err
}
htmlBody = partials.swapHTML(htmlBody)
textBody := partials.swapText(markdownBody)
if err := validateHTML(htmlBody); err != nil {
return out, err
return out, partBody, err
}
layout, err := c.layoutFor(src, opts)
if err != nil {
return out, err
return out, partLayout, err
}
// A layout's own CSS goes before mail.css in the css slot.
css := opts.css
@@ -508,7 +617,7 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
"brandCss": opts.brandCSS,
}, texttemplate.FuncMap{"partial": partials.textCall})
if err != nil {
return out, err
return out, partLayoutText, err
}
html, err := execHTMLFuncs(layout.name+".html", layout.htmlWrap, map[string]any{
"Content": template.HTML(htmlBody),
@@ -517,10 +626,10 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
"brandCss": template.CSS(opts.brandCSS),
}, template.FuncMap{"partial": partials.htmlCall})
if err != nil {
return out, err
return out, partLayoutHTML, err
}
if err := validateHTML(html); err != nil {
return out, err
return out, partLayoutHTML, err
}
out = RenderedMessage{
To: append([]string(nil), msg.To...),
@@ -531,7 +640,7 @@ func (c *Catalog) renderFrom(msg Message, src renderSource, opts renderOptions)
HTML: html,
Text: text,
}
return out, nil
return out, "", nil
}
// renderLayout is the layout one render uses: a file layout, a file layout
@@ -593,24 +702,28 @@ func markdownHTML(src string) (string, error) {
}
func validateHTML(html string) error {
if rawUnsafeTag.MatchString(html) {
return fmt.Errorf("postcard: rendered HTML contains raw unsafe tags")
if loc := rawUnsafeTag.FindStringIndex(html); loc != nil {
return &unsafeError{msg: "rendered HTML contains raw unsafe tags", snippet: snippetAt(html, loc)}
}
if eventHandler.MatchString(html) {
return fmt.Errorf("postcard: rendered HTML contains event handlers")
if loc := eventHandler.FindStringIndex(html); loc != nil {
return &unsafeError{msg: "rendered HTML contains event handlers", snippet: snippetAt(html, loc)}
}
if dangerousScheme.MatchString(html) {
return fmt.Errorf("postcard: rendered HTML contains a dangerous URL scheme")
if loc := dangerousScheme.FindStringIndex(html); loc != nil {
return &unsafeError{msg: "rendered HTML contains a dangerous URL scheme", snippet: snippetAt(html, loc)}
}
return nil
}
func execHTML(name, src string, data any) (string, error) {
return execHTMLFuncs(name, src, data, nil)
// snippetAt returns the match at loc with up to snippetContext bytes on
// either side, on one line.
func snippetAt(s string, loc []int) string {
const snippetContext = 24
start, end := max(loc[0]-snippetContext, 0), min(loc[1]+snippetContext, len(s))
return strings.Join(strings.Fields(strings.ToValidUTF8(s[start:end], "")), " ")
}
func execText(name, src string, data any) (string, error) {
return execTextFuncs(name, src, data, nil)
func execHTML(name, src string, data any) (string, error) {
return execHTMLFuncs(name, src, data, nil)
}
// execHTMLFuncs is execHTML with template funcs; they must be set before
@@ -618,11 +731,11 @@ func execText(name, src string, data any) (string, error) {
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)
return "", &tmplError{name: name, parse: true, err: err}
}
var buf bytes.Buffer
if err := tmpl.Execute(&buf, data); err != nil {
return "", fmt.Errorf("postcard: execute %s: %w", name, err)
return "", &tmplError{name: name, err: err}
}
return buf.String(), nil
}
@@ -630,11 +743,195 @@ func execHTMLFuncs(name, src string, data any, funcs template.FuncMap) (string,
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)
return "", &tmplError{name: name, parse: true, err: err}
}
var buf bytes.Buffer
if err := tmpl.Execute(&buf, data); err != nil {
return "", fmt.Errorf("postcard: execute %s: %w", name, err)
return "", &tmplError{name: name, err: err}
}
return buf.String(), nil
}
// TemplateFile is a registered template as its plugin ships it.
type TemplateFile struct {
Name string
PluginID string
Subject string
Description string
// Layout is the full name of the layout the file selects.
Layout string
Body string
// Samples holds the file's sample.<path> header keys by path.
Samples map[string]string
// Source is the file's text with CRLF normalized to LF.
Source string
// Hash is the sha256 of Source in hex.
Hash string
}
// LayoutFile is a registered layout as its plugin (or postcard) ships it.
type LayoutFile struct {
Name string
PluginID string
// Title is the name in the file's header.
Title string
Text string
HTML string
Source string
Hash string
}
// PartialFile is a registered partial as its plugin (or postcard) ships it.
type PartialFile struct {
Name string
PluginID string
// Title is the name in the file's header.
Title string
Text string
HTML string
Source string
Hash string
}
func (t *parsedTemplate) file() TemplateFile {
layout := t.layout
if layout == "" || layout == defaultLayoutAlias {
layout = defaultLayoutName
}
samples := make(map[string]string, len(t.samples))
for k, v := range t.samples {
samples[k] = v
}
return TemplateFile{
Name: t.name, PluginID: t.pluginID, Subject: t.subject, Description: t.description,
Layout: layout, Body: t.body, Samples: samples, Source: t.source, Hash: t.hash,
}
}
func (l *parsedLayout) file() LayoutFile {
return LayoutFile{Name: l.name, PluginID: l.pluginID, Title: l.headerName, Text: l.textWrap, HTML: l.htmlWrap, Source: l.source, Hash: l.hash}
}
func (p *parsedPartial) file() PartialFile {
return PartialFile{Name: p.name, PluginID: p.pluginID, Title: p.headerName, Text: p.textWrap, HTML: p.htmlWrap, Source: p.source, Hash: p.hash}
}
// Templates returns the registered templates, sorted by name.
func (c *Catalog) Templates() []TemplateFile {
c.mu.RLock()
defer c.mu.RUnlock()
out := make([]TemplateFile, 0, len(c.templates))
for _, t := range c.templates {
out = append(out, t.file())
}
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
return out
}
// Layouts returns the registered layouts, the built-in ones included,
// sorted by name.
func (c *Catalog) Layouts() []LayoutFile {
c.mu.RLock()
defer c.mu.RUnlock()
out := make([]LayoutFile, 0, len(c.layouts))
for _, l := range c.layouts {
out = append(out, l.file())
}
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
return out
}
// Partials returns the registered partials, the built-in ones included,
// sorted by name.
func (c *Catalog) Partials() []PartialFile {
c.mu.RLock()
defer c.mu.RUnlock()
out := make([]PartialFile, 0, len(c.partials))
for _, p := range c.partials {
out = append(out, p.file())
}
sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
return out
}
// Template returns the registered template of that full name.
func (c *Catalog) Template(name string) (TemplateFile, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
t, ok := c.templates[name]
if !ok {
return TemplateFile{}, false
}
return t.file(), true
}
// Layout returns the registered layout of that full name.
func (c *Catalog) Layout(name string) (LayoutFile, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
l, ok := c.layouts[name]
if !ok {
return LayoutFile{}, false
}
return l.file(), true
}
// Partial returns the registered partial of that full name.
func (c *Catalog) Partial(name string) (PartialFile, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
p, ok := c.partials[name]
if !ok {
return PartialFile{}, false
}
return p.file(), true
}
// FormatTemplate writes a template's subject, layout and body in the file
// format: the header, a == line, the body. It gives a file version and an
// override the same shape, so the two can be compared line by line.
func FormatTemplate(subject, layout, body string) string {
return "subject = \"" + subject + "\"\nlayout = \"" + layout + "\"\n==\n" + body + "\n"
}
// FormatLayout writes a layout's name, text wrapper and HTML wrapper in the
// file format. A non-empty css is appended as a further section; layout
// files have none, so that form is for display and comparison only.
func FormatLayout(name, text, html, css string) string {
out := "name = \"" + name + "\"\n==\n" + text + "\n==\n" + html + "\n"
if css != "" {
out += "==\n" + css + "\n"
}
return out
}
// FormatPartial writes a partial's name, text section and HTML section in
// the file format.
func FormatPartial(name, text, html string) string {
return "name = \"" + name + "\"\n==\n" + text + "\n==\n" + html + "\n"
}
// TemplateLocale returns the locale a template name ends in: the suffix
// after a dash in the last dotted segment of the name, when it is one of
// locales, as acme.blog::mail.welcome-en is the en variant of
// acme.blog::mail.welcome. It returns "" for any other name, so a dashed
// name such as cancel-notice is not read as a locale. The match ignores
// case and the result is spelled as in locales.
func TemplateLocale(name string, locales []string) string {
_, rest, ok := strings.Cut(name, "::")
if !ok {
return ""
}
segment := rest[strings.LastIndex(rest, ".")+1:]
best := ""
for _, locale := range locales {
if locale == "" || len(segment) <= len(locale)+1 || len(locale) <= len(best) {
continue
}
cut := len(segment) - len(locale)
if segment[cut-1] == '-' && strings.EqualFold(segment[cut:], locale) {
best = locale
}
}
return best
}