Files
summercms/modules/postcard/mailer.go
Jakub Zych 2bf9081c1b feat(postcard): mail branding and the logo URL
- Brand, DefaultBrand and CompileBrandCSS: thirteen colours, each checked
  as a six-digit hex colour, compiled into CSS for plain elements and the
  built-in layouts and partials
- once the branding row exists its compiled CSS replaces mail.brandCss;
  mail.css still follows, and the file version sent after a failing
  override keeps the Branding
- layouts get logoUrl, built per send from storage.uploads.public_url or
  app.url through attach.AbsolutePublicURL; a logo that cannot be shown is
  left out with a rate-limited warning
- Editor previews and validates a Branding draft (rule colour)

Plan 35-01, task 5.
2026-11-13 11:06:43 +01:00

327 lines
9.4 KiB
Go

package postcard
import (
"context"
"fmt"
"log/slog"
"strings"
"sync"
"time"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/compass"
"git.golem15.com/golem15/summercms/modules/diary"
"git.golem15.com/golem15/summercms/modules/pact"
)
// moduleLog is postcard's logger: records carry component=postcard and follow
// log.components.postcard (diary).
var moduleLog = diary.For("postcard")
// Message is the Send contract for plugin callers.
type Message struct {
Template string
To []string
Cc []string
Bcc []string
ReplyTo string
Vars map[string]any
Subject string
}
// Mailer sends a registered template through the configured driver.
type Mailer interface {
Send(ctx context.Context, msg Message) error
}
// Options configure an app-scoped mailer.
type Options struct {
From string
CSS string
BrandCSS string
// Overrides, when set, is asked once per Send for the database
// overrides of the template being sent. Nil sends the file versions.
Overrides OverrideSource
}
type mailer struct {
catalog *Catalog
driver Driver
opts Options
// source supplies database overrides; nil means files only.
source OverrideSource
// log receives override warnings and failures; nil means moduleLog.
log *slog.Logger
warned warnGate
}
// NewMailer returns a mailer that renders from cat and delivers through
// driver. opts.Overrides, when set, supplies database overrides per send.
func NewMailer(cat *Catalog, driver Driver, opts Options) Mailer {
if cat == nil {
cat = NewCatalog()
}
return &mailer{catalog: cat, driver: driver, opts: opts, source: opts.Overrides}
}
// Send renders msg.Template and delivers it. It performs no locale selection;
// the caller must pass the full dotted name, including any -en suffix. A
// database override of the template is applied when the mailer has an
// OverrideSource; an override that cannot be read or does not render is
// logged and the file version is sent instead.
func (m *mailer) Send(ctx context.Context, msg Message) error {
if m == nil {
return fmt.Errorf("postcard: mailer is nil")
}
if m.driver == nil {
return fmt.Errorf("postcard: driver is nil")
}
if msg.Template == "" {
return fmt.Errorf("postcard: template is empty")
}
if len(msg.To) == 0 && len(msg.Cc) == 0 && len(msg.Bcc) == 0 {
return fmt.Errorf("postcard: no recipients")
}
rendered, err := m.render(ctx, msg)
if err != nil {
return err
}
rendered.From = m.opts.From
_, smtp := m.driver.(*SMTPDriver)
if err := validateRendered(rendered, smtp); err != nil {
return err
}
if err := m.driver.Send(ctx, rendered); err != nil {
return fmt.Errorf("postcard: %w", err)
}
return nil
}
// render renders msg with its database overrides applied. With no source, no
// overrides, or overrides that fail to render or to pass the safety checks,
// it renders the file version.
func (m *mailer) render(ctx context.Context, msg Message) (RenderedMessage, error) {
if _, err := m.catalog.lookupTemplate(msg.Template); err != nil {
return RenderedMessage{}, err
}
ov := m.overrides(ctx, msg.Template)
// The file version carries the Branding too: it is not an override of a
// file, and a failing override must not change how the mail looks.
file := m.options(ov.Brand)
if ov.empty() {
return m.catalog.render(msg, file)
}
with := file
with.overrides = ov
with.warn = m.warn
rendered, err := m.catalog.render(msg, with)
if err == nil {
return rendered, nil
}
// The override is at fault only when the file version renders; a
// failure of both is the caller's (a bad subject, a missing variable)
// and is returned as before.
rendered, fileErr := m.catalog.render(msg, file)
if fileErr != nil {
return RenderedMessage{}, fileErr
}
m.logger().Error("postcard: override failed, sending the file version",
slog.String("template", msg.Template),
slog.String("error", err.Error()),
)
return rendered, nil
}
// options returns the render options of the file version: mail.css, and
// either the saved Branding (its compiled CSS and its logo) or, while none
// has been saved, mail.brandCss. A Branding whose colours do not compile
// keeps mail.brandCss.
func (m *mailer) options(brand *Brand) renderOptions {
opts := renderOptions{css: m.opts.CSS, brandCSS: m.opts.BrandCSS}
if brand == nil {
return opts
}
opts.logoURL = brand.LogoURL
css, err := CompileBrandCSS(*brand)
if err != nil {
m.warn(err.Error(), "postcard: mail branding is not valid, using mail.brandCss",
slog.String("error", err.Error()))
return opts
}
opts.brandCSS = css
return opts
}
// overrides asks the source once. A failed lookup (no connection, tables not
// migrated yet) is a warning, not a send failure: the file version is sent.
func (m *mailer) overrides(ctx context.Context, template string) Overrides {
if m.source == nil {
return Overrides{}
}
ov, err := m.source.MailOverrides(ctx, template)
if err != nil {
m.warn(err.Error(), "postcard: mail overrides unavailable, sending the file version",
slog.String("template", template),
slog.String("error", err.Error()),
)
return Overrides{}
}
for _, warning := range ov.warnings {
m.warn(warning, "postcard: "+warning, slog.String("template", template))
}
return ov
}
func (m *mailer) logger() *slog.Logger {
if m.log != nil {
return m.log
}
return moduleLog
}
// warn logs at warning level, at most once per warnInterval per key.
func (m *mailer) warn(key, msg string, args ...any) {
if !m.warned.allow(key, time.Now()) {
return
}
m.logger().Warn(msg, args...)
}
const (
// warnInterval is how often the same override warning is repeated.
warnInterval = time.Minute
// warnGateSize bounds the keys a warnGate remembers.
warnGateSize = 64
)
// warnGate rate-limits warnings by key. The zero value is ready to use.
type warnGate struct {
mu sync.Mutex
last map[string]time.Time
}
func (g *warnGate) allow(key string, now time.Time) bool {
g.mu.Lock()
defer g.mu.Unlock()
if last, ok := g.last[key]; ok && now.Sub(last) < warnInterval {
return false
}
if g.last == nil || len(g.last) >= warnGateSize {
g.last = make(map[string]time.Time)
}
g.last[key] = now
return true
}
// Activate publishes an app-scoped Mailer before plugin Boot. Catalog files
// are validated later at each plugin's Boot transition. The mailer reads
// database overrides through NewDBSource, so they apply in every process
// that publishes a *gorm.DB on app.
func Activate[P interface{ ID() string }](app *backpack.App, _ []P) error {
if app == nil {
return fmt.Errorf("postcard: app is nil")
}
driver, opts, err := driverFromApp(app)
if err != nil {
return err
}
opts.Overrides = NewDBSource(app)
m := &mailer{
catalog: NewCatalog(),
driver: driver,
opts: opts,
source: opts.Overrides,
}
if err := app.Publish[Mailer](m); err != nil {
return fmt.Errorf("postcard: %w", err)
}
return nil
}
func driverFromApp(app *backpack.App) (Driver, Options, error) {
opts := Options{}
name := "memory"
smtp := SMTPConfig{Port: 587, Timeout: 10 * time.Second}
if app != nil && app.Config != nil {
c := app.Config
if v := strings.TrimSpace(c.String("mail.driver")); v != "" {
name = strings.ToLower(v)
}
opts.From = strings.TrimSpace(c.String("mail.from"))
opts.CSS = c.String("mail.css")
opts.BrandCSS = c.String("mail.brandCss")
smtp = smtpFromConfig(c)
}
switch name {
case "memory":
return NewMemoryDriver(), opts, nil
case "log":
return NewLogDriver(loggerFromApp(app)), opts, nil
case "smtp":
d, err := NewSMTPDriver(smtp)
if err != nil {
return nil, opts, err
}
return d, opts, nil
default:
return nil, opts, fmt.Errorf("postcard: unknown mail.driver %q (use memory, log, or smtp)", name)
}
}
func smtpFromConfig(c *compass.Config) SMTPConfig {
cfg := SMTPConfig{
Host: strings.TrimSpace(c.String("mail.smtp.host")),
Port: c.Int("mail.smtp.port"),
Username: c.String("mail.smtp.username"),
Password: c.String("mail.smtp.password"),
TLS: strings.TrimSpace(c.String("mail.smtp.tls")),
Timeout: 10 * time.Second,
}
if raw := strings.TrimSpace(c.String("mail.smtp.timeout")); raw != "" {
if d, err := time.ParseDuration(raw); err == nil {
cfg.Timeout = d
} else if n := c.Int("mail.smtp.timeout"); n > 0 {
cfg.Timeout = time.Duration(n) * time.Second
}
}
return cfg
}
func loggerFromApp(app *backpack.App) *slog.Logger {
if app != nil {
if log, ok := app.Lookup[*slog.Logger](); ok && log != nil {
return log
}
}
return moduleLog
}
// BootPlugin registers a plugin's declared mail partials (pact.HasMailPartials)
// and its templates and layouts (pact.HasMailTemplates). Either capability is
// optional. Missing files, duplicates, names outside the plugin's namespace
// and unknown layout aliases fail with the dotted name.
func BootPlugin[P interface{ ID() string }](app *backpack.App, p P) error {
hm, hasTemplates := any(p).(pact.HasMailTemplates)
hp, hasPartials := any(p).(pact.HasMailPartials)
if !hasTemplates && !hasPartials {
return nil
}
got, ok := app.Lookup[Mailer]()
if !ok {
return fmt.Errorf("postcard: mailer not published")
}
m, ok := got.(*mailer)
if !ok || m == nil || m.catalog == nil {
return fmt.Errorf("postcard: mailer not published")
}
if hasPartials {
if err := m.catalog.RegisterPartials(p.ID(), hp.MailPartialsFS(), hp.MailPartials()); err != nil {
return err
}
}
if hasTemplates {
return m.catalog.Register(p.ID(), hm.MailTemplatesFS(), hm.MailTemplates(), hm.MailLayouts())
}
return nil
}