diff --git a/docs/services/mail.md b/docs/services/mail.md index 2afc47da..a42774a6 100644 --- a/docs/services/mail.md +++ b/docs/services/mail.md @@ -61,6 +61,22 @@ Three layouts are available to every plugin's templates without declaring an ali A plugin's own alias wins over `system` and `minimal`; `default` cannot be redefined. +## Sample values for previews + +A preview of a template has no caller to pass its variables. A template can therefore give sample values in its header, one key per variable: `sample.` followed by the variable's path, in the variable's own case. + +```text +subject = "Your order {{ .order.code }}" +sample.name = "Ada" +sample.order.code = "ZAM-1" +== +Hi {{ .name }}, we received the payment for **{{ .order.code }}** from {{ .company }}. +``` + +The keys are optional and sending ignores them. Where a preview finds no sample, it shows the variable's path in square brackets, so the body above previews as "Hi Ada, we received the payment for **ZAM-1** from [company]." Nested fields and lists work without samples too: `{{ range .order.items }}{{ .description }}{{ end }}` previews one item, `[order.items.description]`. Saving an edited template runs the same render, so an edit that uses a variable the plugin never passes still shows up as a placeholder, not as an error. + +Previews, the checks on save and test sends are `postcard.Editor`; see the [postcard README](../../modules/postcard/README.md) for its API. + ## Sending At boot, `postcard.Activate` publishes one `postcard.Mailer` on the application, and `postcard.BootPlugin` registers each plugin's templates as it boots. Look the mailer up with `app.Lookup[postcard.Mailer]()` and send a `postcard.Message` with the template name, the recipients and the variables. Tests build the catalog and a memory driver directly, and read back what was sent: diff --git a/modules/pact/README.md b/modules/pact/README.md index 7d679e00..f5529f05 100644 --- a/modules/pact/README.md +++ b/modules/pact/README.md @@ -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. | diff --git a/modules/pact/capabilities.go b/modules/pact/capabilities.go index f1b98914..0342981b 100644 --- a/modules/pact/capabilities.go +++ b/modules/pact/capabilities.go @@ -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) } diff --git a/modules/postcard/README.md b/modules/postcard/README.md index c539bf34..64202862 100644 --- a/modules/postcard/README.md +++ b/modules/postcard/README.md @@ -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.` 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. diff --git a/modules/postcard/assets/sample.htm b/modules/postcard/assets/sample.htm new file mode 100644 index 00000000..3db72539 --- /dev/null +++ b/modules/postcard/assets/sample.htm @@ -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. diff --git a/modules/postcard/editor.go b/modules/postcard/editor.go new file mode 100644 index 00000000..4641a068 --- /dev/null +++ b/modules/postcard/editor.go @@ -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) 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 +} diff --git a/modules/postcard/editor_smoke_test.go b/modules/postcard/editor_smoke_test.go new file mode 100644 index 00000000..8158f337 --- /dev/null +++ b/modules/postcard/editor_smoke_test.go @@ -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 +== +
{{ .Content }}
+`)}, + "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: `
{{ .Content }}
`, Text: "{{ .Content }}", CSS: ".promo{margin:0}"} + partial := Draft{Kind: KindPartial, Name: editorNote, HTML: `{{ .text }}`, 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" }), "body", "unsafe", "