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:
@@ -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. |
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
12
modules/postcard/assets/sample.htm
Normal file
12
modules/postcard/assets/sample.htm
Normal 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
473
modules/postcard/editor.go
Normal 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
|
||||
}
|
||||
763
modules/postcard/editor_smoke_test.go
Normal file
763
modules/postcard/editor_smoke_test.go
Normal 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) }
|
||||
@@ -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
253
modules/postcard/samples.go
Normal 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
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user