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

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

641 lines
19 KiB
Go

package postcard
import (
"bytes"
"embed"
"fmt"
"html/template"
"io/fs"
"regexp"
"strings"
"sync"
texttemplate "text/template"
"github.com/yuin/goldmark"
)
const (
builtinPluginID = "postcard"
defaultLayoutAlias = "default"
defaultLayoutName = "postcard::mail.layouts.default"
systemLayoutName = "postcard::mail.layouts.system"
minimalLayoutName = "postcard::mail.layouts.minimal"
mailPrefix = "mail."
assetRoot = "views/mail/"
)
// builtinLayoutAliases are the layout aliases every plugin's templates can
// use. A plugin's own alias of the same name wins, except default, which is
// reserved.
var builtinLayoutAliases = map[string]string{
defaultLayoutAlias: defaultLayoutName,
"system": systemLayoutName,
"minimal": minimalLayoutName,
}
// builtinPartials are the partials postcard ships, callable by bare name.
var builtinPartials = []string{"button", "panel", "subcopy", "table"}
var (
dangerousScheme = regexp.MustCompile(`(?i)(?:javascript|vbscript|data):`)
eventHandler = regexp.MustCompile(`(?i)\son[a-z]+\s*=`)
rawUnsafeTag = regexp.MustCompile(`(?i)<(?:script|iframe|object|embed)\b`)
markdown = goldmark.New()
)
//go:embed assets/default.htm
var defaultLayoutSource string
// builtinAssets holds postcard's own layouts and partials.
//
//go:embed assets
var builtinAssets embed.FS
// Catalog holds registered mail templates, layouts and partials.
type Catalog struct {
mu sync.RWMutex
templates map[string]*parsedTemplate
layouts map[string]*parsedLayout
partials map[string]*parsedPartial
aliases map[string]map[string]string // pluginID -> short name -> full name
}
type parsedTemplate struct {
name string
pluginID string
subject string
description string
layout string // short name from header; empty means default
body string
}
type parsedLayout struct {
name string
pluginID string
headerName string
textWrap string
htmlWrap string
}
// parsedPartial is a partial file: the layout file format, a header, a text
// section and an HTML section.
type parsedPartial struct {
name string
pluginID string
headerName string
textWrap string
htmlWrap string
}
// NewCatalog returns a catalog that already contains postcard's built-in
// layouts (default, system and minimal) and partials (button, panel, table
// and subcopy). It holds no template.
func NewCatalog() *Catalog {
c := &Catalog{
templates: make(map[string]*parsedTemplate),
layouts: make(map[string]*parsedLayout),
partials: make(map[string]*parsedPartial),
aliases: make(map[string]map[string]string),
}
layout, err := parseLayout(defaultLayoutName, builtinPluginID, defaultLayoutSource)
if err != nil {
panic("postcard: default layout: " + err.Error())
}
c.layouts[defaultLayoutName] = layout
for file, name := range map[string]string{"system": systemLayoutName, "minimal": minimalLayoutName} {
raw, err := builtinAssets.ReadFile("assets/" + file + ".htm")
if err != nil {
panic("postcard: " + file + " layout: " + err.Error())
}
layout, err := parseLayout(name, builtinPluginID, string(raw))
if err != nil {
panic("postcard: " + file + " layout: " + err.Error())
}
c.layouts[name] = layout
}
for _, short := range builtinPartials {
raw, err := builtinAssets.ReadFile("assets/partials/" + short + ".htm")
if err != nil {
panic("postcard: " + short + " partial: " + err.Error())
}
partial, err := parsePartial(builtinPartialPrefix+short, builtinPluginID, string(raw))
if err != nil {
panic("postcard: " + short + " partial: " + err.Error())
}
c.partials[partial.name] = partial
}
return c
}
// Register loads declared dotted template and layout names from fsys.
// Each name must be owned by pluginID and map to views/mail/<name>.htm.
func (c *Catalog) Register(pluginID string, fsys fs.FS, templates []string, layouts map[string]string) error {
if c == nil {
return fmt.Errorf("postcard: catalog is nil")
}
if pluginID == "" {
return fmt.Errorf("postcard: plugin id is empty")
}
c.mu.Lock()
defer c.mu.Unlock()
alias := make(map[string]string, len(layouts))
for short, full := range layouts {
if short == "" || full == "" {
return fmt.Errorf("postcard: empty layout alias for %s", pluginID)
}
if short == defaultLayoutAlias {
return fmt.Errorf("postcard: layout alias %q is reserved", short)
}
if err := assertOwner(pluginID, full); err != nil {
return err
}
if _, exists := c.layouts[full]; exists {
return fmt.Errorf("postcard: duplicate layout %s", full)
}
path, err := assetPath(full)
if err != nil {
return err
}
raw, err := fs.ReadFile(fsys, path)
if err != nil {
return fmt.Errorf("postcard: missing layout %s", full)
}
parsed, err := parseLayout(full, pluginID, string(raw))
if err != nil {
return err
}
c.layouts[full] = parsed
alias[short] = full
}
if len(alias) > 0 {
if c.aliases[pluginID] == nil {
c.aliases[pluginID] = make(map[string]string, len(alias))
}
for short, full := range alias {
if _, exists := c.aliases[pluginID][short]; exists {
return fmt.Errorf("postcard: duplicate layout alias %s for %s", short, pluginID)
}
c.aliases[pluginID][short] = full
}
}
for _, name := range templates {
if err := assertOwner(pluginID, name); err != nil {
return err
}
if _, exists := c.templates[name]; exists {
return fmt.Errorf("postcard: duplicate template %s", name)
}
path, err := assetPath(name)
if err != nil {
return err
}
raw, err := fs.ReadFile(fsys, path)
if err != nil {
return fmt.Errorf("postcard: missing template %s", name)
}
parsed, err := parseTemplateFile(name, pluginID, string(raw))
if err != nil {
return err
}
if err := c.resolveLayoutLocked(parsed); err != nil {
return err
}
c.templates[name] = parsed
}
return nil
}
func (c *Catalog) resolveLayoutLocked(t *parsedTemplate) error {
short := strings.TrimSpace(t.layout)
if short == "" || short == defaultLayoutAlias {
t.layout = defaultLayoutAlias
return nil
}
full, ok := c.aliases[t.pluginID][short]
if !ok {
// Not one of the plugin's own aliases: a built-in layout.
full, ok = builtinLayoutAliases[short]
}
if !ok {
return fmt.Errorf("postcard: unknown layout %s", short)
}
if _, ok := c.layouts[full]; !ok {
return fmt.Errorf("postcard: missing layout %s", full)
}
t.layout = full
return nil
}
func (c *Catalog) lookupTemplate(name string) (*parsedTemplate, error) {
c.mu.RLock()
defer c.mu.RUnlock()
t, ok := c.templates[name]
if !ok {
return nil, fmt.Errorf("postcard: unknown template %s", name)
}
return t, nil
}
// RegisterPartials loads declared partial names from fsys. Each name must
// be owned by pluginID, have the form <plugin>::mail.partials.<name> and map
// to views/mail/partials/<name>.htm.
func (c *Catalog) RegisterPartials(pluginID string, fsys fs.FS, partials []string) error {
if c == nil {
return fmt.Errorf("postcard: catalog is nil")
}
if pluginID == "" {
return fmt.Errorf("postcard: plugin id is empty")
}
c.mu.Lock()
defer c.mu.Unlock()
for _, name := range partials {
if err := assertOwner(pluginID, name); err != nil {
return err
}
if _, rest, _ := strings.Cut(name, "::"); !strings.HasPrefix(rest, partialSegment) || rest == partialSegment {
return fmt.Errorf("postcard: invalid partial name %s (want %s::%s<name>)", name, pluginID, partialSegment)
}
if _, exists := c.partials[name]; exists {
return fmt.Errorf("postcard: duplicate partial %s", name)
}
path, err := assetPath(name)
if err != nil {
return err
}
raw, err := fs.ReadFile(fsys, path)
if err != nil {
return fmt.Errorf("postcard: missing partial %s", name)
}
parsed, err := parsePartial(name, pluginID, string(raw))
if err != nil {
return err
}
c.partials[name] = parsed
}
return nil
}
func (c *Catalog) lookupPartial(name string) (*parsedPartial, bool) {
c.mu.RLock()
defer c.mu.RUnlock()
p, ok := c.partials[name]
return p, ok
}
func assertOwner(pluginID, fullName string) error {
prefix := pluginID + "::"
if !strings.HasPrefix(fullName, prefix) {
return fmt.Errorf("postcard: template %s is not owned by %s", fullName, pluginID)
}
return nil
}
func assetPath(fullName string) (string, error) {
_, rest, ok := strings.Cut(fullName, "::")
if !ok {
return "", fmt.Errorf("postcard: invalid mail name %s", fullName)
}
after, ok := strings.CutPrefix(rest, mailPrefix)
if !ok || after == "" {
return "", fmt.Errorf("postcard: invalid mail name %s", fullName)
}
if strings.Contains(after, "..") || strings.ContainsAny(after, `/\`) {
return "", fmt.Errorf("postcard: invalid mail name %s", fullName)
}
return assetRoot + strings.ReplaceAll(after, ".", "/") + ".htm", nil
}
func parseTemplateFile(name, pluginID, src string) (*parsedTemplate, error) {
header, body, err := splitTwo(src)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
}
fields, err := parseINI(header)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
}
return &parsedTemplate{
name: name,
pluginID: pluginID,
subject: fields["subject"],
description: fields["description"],
layout: fields["layout"],
body: strings.TrimSuffix(body, "\n"),
}, nil
}
func parseLayout(name, pluginID, src string) (*parsedLayout, error) {
header, textWrap, htmlWrap, err := splitThree(src)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
}
fields, err := parseINI(header)
if err != nil {
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
}
return &parsedLayout{
name: name,
pluginID: pluginID,
headerName: fields["name"],
textWrap: strings.TrimSuffix(textWrap, "\n"),
htmlWrap: strings.TrimSuffix(htmlWrap, "\n"),
}, nil
}
func parsePartial(name, pluginID, src string) (*parsedPartial, error) {
l, err := parseLayout(name, pluginID, src)
if err != nil {
return nil, err
}
return &parsedPartial{name: l.name, pluginID: l.pluginID, headerName: l.headerName, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, nil
}
func splitTwo(src string) (header, body string, err error) {
parts, err := splitEQ(src, 2)
if err != nil {
return "", "", err
}
return parts[0], parts[1], nil
}
func splitThree(src string) (header, textWrap, htmlWrap string, err error) {
parts, err := splitEQ(src, 3)
if err != nil {
return "", "", "", err
}
return parts[0], parts[1], parts[2], nil
}
func splitEQ(src string, n int) ([]string, error) {
src = strings.ReplaceAll(src, "\r\n", "\n")
lines := strings.Split(src, "\n")
parts := make([]string, 0, n)
start := 0
for i, line := range lines {
if strings.TrimSpace(line) != "==" {
continue
}
parts = append(parts, strings.Join(lines[start:i], "\n"))
start = i + 1
if len(parts) == n-1 {
parts = append(parts, strings.Join(lines[start:], "\n"))
return parts, nil
}
}
return nil, fmt.Errorf("missing == separator")
}
func parseINI(header string) (map[string]string, 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, "=")
if !ok {
return nil, fmt.Errorf("invalid header line %q", line)
}
key = strings.ToLower(strings.TrimSpace(key))
val = strings.TrimSpace(val)
if len(val) >= 2 {
if q := val[0]; (q == '"' || q == '\'') && val[len(val)-1] == q {
val = val[1 : len(val)-1]
}
}
if key == "" {
return nil, fmt.Errorf("invalid header line %q", line)
}
out[key] = val
}
return out, nil
}
type renderOptions struct {
css string
brandCSS string
// overrides are the database overrides to apply; the zero value renders
// the file version.
overrides Overrides
// warn reports a problem with an override that the render recovered
// from. key identifies the problem for rate limiting. Nil drops it.
warn func(key, msg string, args ...any)
}
// renderSource is what one render works from: a file template, or a file
// template with its override applied.
type renderSource struct {
name string // template name, used in parse and execute errors
subject string
body string
layout string // full layout name, the default alias, or an override's layout code
// layoutFromOverride marks a layout an override chose: one that resolves
// to nothing renders with the default layout instead of failing.
layoutFromOverride bool
}
// render renders msg.Template: the file version, or the file version with
// opts.overrides applied. Both go through renderFrom.
func (c *Catalog) render(msg Message, opts renderOptions) (RenderedMessage, error) {
t, err := c.lookupTemplate(msg.Template)
if err != nil {
return RenderedMessage{}, err
}
src := renderSource{name: t.name, subject: t.subject, body: t.body, layout: t.layout}
if ov := opts.overrides.Template; ov != nil {
src.subject, src.body = ov.Subject, ov.Body
if ov.Layout != "" {
src.layout, src.layoutFromOverride = ov.Layout, true
}
}
return c.renderFrom(msg, src, opts)
}
// 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
vars := msg.Vars
if vars == nil {
vars = map[string]any{}
}
subjectSrc := src.subject
if strings.TrimSpace(msg.Subject) != "" {
subjectSrc = msg.Subject
}
subject, err := execHTML(src.name+".subject", subjectSrc, vars)
if err != nil {
return out, err
}
if strings.ContainsAny(subject, "\r\n") {
return out, fmt.Errorf("postcard: subject contains CR/LF")
}
// 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
}
htmlBody, err := markdownHTML(markdownBody)
if err != nil {
return out, err
}
htmlBody = partials.swapHTML(htmlBody)
textBody := partials.swapText(markdownBody)
if err := validateHTML(htmlBody); err != nil {
return out, err
}
layout, err := c.layoutFor(src, opts)
if err != nil {
return out, err
}
// A layout's own CSS goes before mail.css in the css slot.
css := opts.css
if layout.css != "" {
css = layout.css
if opts.css != "" {
css += "\n" + opts.css
}
}
text, err := execTextFuncs(layout.name+".text", layout.textWrap, map[string]any{
"Content": textBody,
"Subject": subject,
"css": css,
"brandCss": opts.brandCSS,
}, texttemplate.FuncMap{"partial": partials.textCall})
if err != nil {
return out, err
}
html, err := execHTMLFuncs(layout.name+".html", layout.htmlWrap, map[string]any{
"Content": template.HTML(htmlBody),
"Subject": subject,
"css": template.CSS(css),
"brandCss": template.CSS(opts.brandCSS),
}, template.FuncMap{"partial": partials.htmlCall})
if err != nil {
return out, err
}
if err := validateHTML(html); err != nil {
return out, err
}
out = RenderedMessage{
To: append([]string(nil), msg.To...),
Cc: append([]string(nil), msg.Cc...),
Bcc: append([]string(nil), msg.Bcc...),
ReplyTo: msg.ReplyTo,
Subject: subject,
HTML: html,
Text: text,
}
return out, nil
}
// renderLayout is the layout one render uses: a file layout, a file layout
// with its override applied, or a database-only layout.
type renderLayout struct {
name string // layout code, used in parse and execute errors
textWrap string
htmlWrap string
css string
}
// layoutFor returns the layout src renders in. An override of that layout,
// or a database-only layout of that code, wins over the file. A layout code
// from a template override that names no layout is reported through
// opts.warn and replaced by the default layout.
func (c *Catalog) layoutFor(src renderSource, opts renderOptions) (renderLayout, error) {
code := src.layout
if code == "" || code == defaultLayoutAlias {
code = defaultLayoutName
}
layout, ok, err := c.layoutByCode(code, opts.overrides.Layouts)
if err != nil || ok {
return layout, err
}
if !src.layoutFromOverride {
return renderLayout{}, fmt.Errorf("postcard: missing layout %s", code)
}
if opts.warn != nil {
opts.warn("layout:"+src.name+":"+code,
"postcard: override names an unknown layout, using the default layout",
"template", src.name, "layout", code)
}
layout, ok, err = c.layoutByCode(defaultLayoutName, opts.overrides.Layouts)
if err == nil && !ok {
err = fmt.Errorf("postcard: missing layout %s", defaultLayoutName)
}
return layout, err
}
func (c *Catalog) layoutByCode(code string, overrides map[string]LayoutOverride) (renderLayout, bool, error) {
if ov, ok := overrides[code]; ok {
return renderLayout{name: code, textWrap: ov.Text, htmlWrap: ov.HTML, css: ov.CSS}, true, nil
}
c.mu.RLock()
l, ok := c.layouts[code]
c.mu.RUnlock()
if !ok {
return renderLayout{}, false, nil
}
return renderLayout{name: l.name, textWrap: l.textWrap, htmlWrap: l.htmlWrap}, true, nil
}
func markdownHTML(src string) (string, error) {
var buf bytes.Buffer
if err := markdown.Convert([]byte(src), &buf); err != nil {
return "", fmt.Errorf("postcard: markdown: %w", err)
}
return buf.String(), nil
}
func validateHTML(html string) error {
if rawUnsafeTag.MatchString(html) {
return fmt.Errorf("postcard: rendered HTML contains raw unsafe tags")
}
if eventHandler.MatchString(html) {
return fmt.Errorf("postcard: rendered HTML contains event handlers")
}
if dangerousScheme.MatchString(html) {
return fmt.Errorf("postcard: rendered HTML contains a dangerous URL scheme")
}
return nil
}
func execHTML(name, src string, data any) (string, error) {
return execHTMLFuncs(name, src, data, nil)
}
func execText(name, src string, data any) (string, error) {
return execTextFuncs(name, src, data, nil)
}
// execHTMLFuncs is execHTML with template funcs; they must be set before
// the source is parsed.
func execHTMLFuncs(name, src string, data any, funcs template.FuncMap) (string, error) {
tmpl, err := template.New(name).Option("missingkey=zero").Funcs(funcs).Parse(src)
if err != nil {
return "", fmt.Errorf("postcard: parse %s: %w", name, err)
}
var buf bytes.Buffer
if err := tmpl.Execute(&buf, data); err != nil {
return "", fmt.Errorf("postcard: execute %s: %w", name, err)
}
return buf.String(), nil
}
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)
}
var buf bytes.Buffer
if err := tmpl.Execute(&buf, data); err != nil {
return "", fmt.Errorf("postcard: execute %s: %w", name, err)
}
return buf.String(), nil
}