Gap G-35-1 (supersedes D-05), tracer slice: - postcard: migration 202611130001_mail_template_base_code (base_code column and index); SyncIndex writes base_code; EnsureLocaleRows creates the <template>-<locale> rows of locales that ship no file; TemplateBase and Catalog.TemplateFor; send, preview and validation resolve a missing <template>-<locale> to the locale's customization, else the base's customization, else the base file. Names with their own file send as before. - cabana: mail locales are the translator's plus the TranslationWriter's enabled locales; sync ensures the locale rows and re-syncs when the locale set changes; record lookups admit fallback-locale rows; the record title is the base code; RecordMeta.LocaleVariants (RecordLocaleVariant) on the show and update responses. - admin: LocaleVariantSwitcher in the update form header, from meta.localeVariants, behind the unsaved-changes confirm. - tests: TestMailOverrideSmoke/locale_fallback, TestMailScreensSmoke/locales, LocaleVariantSwitcher.test.ts.
1000 lines
30 KiB
Go
1000 lines
30 KiB
Go
package postcard
|
|
|
|
import (
|
|
"bytes"
|
|
"crypto/sha256"
|
|
"embed"
|
|
"encoding/hex"
|
|
"errors"
|
|
"fmt"
|
|
"html/template"
|
|
"io/fs"
|
|
"regexp"
|
|
"sort"
|
|
"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
|
|
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 {
|
|
name string
|
|
pluginID string
|
|
headerName string
|
|
textWrap string
|
|
htmlWrap string
|
|
source string
|
|
hash 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
|
|
source string
|
|
hash 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
|
|
}
|
|
|
|
// localeTag matches the locale tag a fallback-locale name ends in: a
|
|
// two-letter language, optionally followed by a dash or an underscore and
|
|
// a 2-8 character alphanumeric subtag (de, pt-BR, zh_Hant).
|
|
var localeTag = regexp.MustCompile(`^[A-Za-z]{2}(?:[-_][A-Za-z0-9]{2,8})?$`)
|
|
|
|
// resolveTemplate is the lookup every send, preview and validation goes
|
|
// through. A name with its own file is that file. A name the catalog does
|
|
// not hold of the form <base>-<tag>, where <base> is a registered template
|
|
// and <tag> a locale tag, is the base's file: a locale that ships no file
|
|
// of its own sends the default-locale version. When several bases match,
|
|
// the longest one wins. Any other name is an unknown template.
|
|
func (c *Catalog) resolveTemplate(name string) (*parsedTemplate, error) {
|
|
c.mu.RLock()
|
|
defer c.mu.RUnlock()
|
|
if t, ok := c.templates[name]; ok {
|
|
return t, nil
|
|
}
|
|
if t := c.fallbackLocked(name); t != nil {
|
|
return t, nil
|
|
}
|
|
return nil, fmt.Errorf("postcard: unknown template %s", name)
|
|
}
|
|
|
|
// fallbackLocked returns the base template a fallback-locale name resolves
|
|
// to, or nil. The caller holds c.mu.
|
|
func (c *Catalog) fallbackLocked(name string) *parsedTemplate {
|
|
_, rest, ok := strings.Cut(name, "::")
|
|
if !ok {
|
|
return nil
|
|
}
|
|
// The tag holds no dot, so the dash is in the last dotted segment.
|
|
start := len(name) - len(rest) + strings.LastIndex(rest, ".") + 1
|
|
for i := len(name) - 1; i > start; i-- {
|
|
if name[i] != '-' || !localeTag.MatchString(name[i+1:]) {
|
|
continue
|
|
}
|
|
if t, ok := c.templates[name[:i]]; ok {
|
|
return t
|
|
}
|
|
}
|
|
return 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) {
|
|
src = normalizeNewlines(src)
|
|
header, body, err := splitTwo(src)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("postcard: parse %s: %w", name, err)
|
|
}
|
|
fields, samples, err := parseHeader(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"),
|
|
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)
|
|
}
|
|
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"),
|
|
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, source: l.source, hash: l.hash}, 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 = normalizeNewlines(src)
|
|
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")
|
|
}
|
|
|
|
// 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
|
|
}
|
|
rawKey, val, ok := strings.Cut(line, "=")
|
|
if !ok {
|
|
return nil, nil, fmt.Errorf("invalid header line %q", line)
|
|
}
|
|
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 {
|
|
val = val[1 : len(val)-1]
|
|
}
|
|
}
|
|
if key == "" {
|
|
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, samples, nil
|
|
}
|
|
|
|
type renderOptions struct {
|
|
css string
|
|
brandCSS string
|
|
// logoURL is the Branding logo's absolute URL, or empty.
|
|
logoURL 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.resolveTemplate(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)
|
|
}
|
|
|
|
// 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) {
|
|
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{}
|
|
}
|
|
subjectSrc := src.subject
|
|
if strings.TrimSpace(msg.Subject) != "" {
|
|
subjectSrc = msg.Subject
|
|
}
|
|
subject, err := execHTML(src.name+".subject", subjectSrc, vars)
|
|
if err != nil {
|
|
return out, partSubject, err
|
|
}
|
|
if strings.ContainsAny(subject, "\r\n") {
|
|
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, partBody, err
|
|
}
|
|
htmlBody, err := markdownHTML(markdownBody)
|
|
if err != nil {
|
|
return out, partBody, err
|
|
}
|
|
htmlBody = partials.swapHTML(htmlBody)
|
|
textBody := partials.swapText(markdownBody)
|
|
if err := validateHTML(htmlBody); err != nil {
|
|
return out, partBody, err
|
|
}
|
|
layout, err := c.layoutFor(src, opts)
|
|
if err != nil {
|
|
return out, partLayout, 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,
|
|
"logoUrl": opts.logoURL,
|
|
}, texttemplate.FuncMap{"partial": partials.textCall})
|
|
if err != nil {
|
|
return out, partLayoutText, 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),
|
|
"logoUrl": opts.logoURL,
|
|
}, template.FuncMap{"partial": partials.htmlCall})
|
|
if err != nil {
|
|
return out, partLayoutHTML, err
|
|
}
|
|
if err := validateHTML(html); err != nil {
|
|
return out, partLayoutHTML, 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 loc := rawUnsafeTag.FindStringIndex(html); loc != nil {
|
|
return &unsafeError{msg: "rendered HTML contains raw unsafe tags", snippet: snippetAt(html, loc)}
|
|
}
|
|
if loc := eventHandler.FindStringIndex(html); loc != nil {
|
|
return &unsafeError{msg: "rendered HTML contains event handlers", snippet: snippetAt(html, loc)}
|
|
}
|
|
if loc := dangerousScheme.FindStringIndex(html); loc != nil {
|
|
return &unsafeError{msg: "rendered HTML contains a dangerous URL scheme", snippet: snippetAt(html, loc)}
|
|
}
|
|
return 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 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
|
|
// 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 "", &tmplError{name: name, parse: true, err: err}
|
|
}
|
|
var buf bytes.Buffer
|
|
if err := tmpl.Execute(&buf, data); err != nil {
|
|
return "", &tmplError{name: name, err: 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 "", &tmplError{name: name, parse: true, err: err}
|
|
}
|
|
var buf bytes.Buffer
|
|
if err := tmpl.Execute(&buf, data); err != nil {
|
|
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
|
|
}
|
|
|
|
// TemplateFor returns the file a template name renders from: the name's
|
|
// own file, or, for a <template>-<locale> name whose locale ships no file,
|
|
// the file of the base template (see the send-resolution rule in the
|
|
// package README). The returned Name is the base's in the second case,
|
|
// which is how a caller tells the two apart.
|
|
func (c *Catalog) TemplateFor(name string) (TemplateFile, bool) {
|
|
t, err := c.resolveTemplate(name)
|
|
if err != nil {
|
|
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
|
|
}
|
|
|
|
// TemplateBase returns the name of the template a locale variant belongs
|
|
// to: name without the locale suffix TemplateLocale finds in it, or name
|
|
// itself when it has none. acme.blog::mail.welcome-en and
|
|
// acme.blog::mail.welcome share the base acme.blog::mail.welcome.
|
|
func TemplateBase(name string, locales []string) string {
|
|
locale := TemplateLocale(name, locales)
|
|
if locale == "" {
|
|
return name
|
|
}
|
|
return name[:len(name)-len(locale)-1]
|
|
}
|