Files
summercms/modules/postcard/store.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

498 lines
19 KiB
Go

package postcard
import (
"context"
"database/sql"
"fmt"
"git.golem15.com/golem15/summercms/modules/backpack"
"git.golem15.com/golem15/summercms/modules/lagoon/attach"
"github.com/go-gormigrate/gormigrate/v2"
"gorm.io/gorm"
"gorm.io/gorm/logger"
)
// The mail tables postcard owns. Admin code builds its models over these
// names; postcard itself reads them with plain SQL.
const (
// TemplatesTable holds one row per mail template.
TemplatesTable = "system_mail_templates"
// LayoutsTable holds one row per mail layout, file-backed or database-only.
LayoutsTable = "system_mail_layouts"
// PartialsTable holds one row per mail partial.
PartialsTable = "system_mail_partials"
// BrandTable holds the mail branding settings (a single row, id 1).
BrandTable = "system_mail_brand_settings"
// ImageLibraryTable holds the one row the mail image library attaches
// its files to.
ImageLibraryTable = "system_mail_image_library"
)
// Migrations creates the mail tables. lagoon runs it as a framework set
// under the summercms.postcard history, after the system_files set.
//
// A row is an override only while is_custom is true. file_hash is the hash
// of the current file and base_hash the hash of the file the override was
// written against, so a customized row is outdated when the two differ.
var Migrations = []*gormigrate.Migration{
{
ID: "202611060001_create_system_mail_tables",
Migrate: func(tx *gorm.DB) error {
stmts := []string{
`CREATE TABLE ` + LayoutsTable + ` (
id SERIAL PRIMARY KEY,
code TEXT NOT NULL UNIQUE,
source TEXT,
name TEXT NOT NULL,
content_html TEXT NOT NULL DEFAULT '',
content_text TEXT NOT NULL DEFAULT '',
content_css TEXT NOT NULL DEFAULT '',
is_custom BOOLEAN NOT NULL DEFAULT FALSE,
file_hash TEXT,
base_hash TEXT,
customized_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)`,
`CREATE TABLE ` + TemplatesTable + ` (
id SERIAL PRIMARY KEY,
code TEXT NOT NULL UNIQUE,
source TEXT NOT NULL,
locale TEXT,
description TEXT NOT NULL DEFAULT '',
subject TEXT NOT NULL DEFAULT '',
body TEXT NOT NULL DEFAULT '',
layout_id INTEGER REFERENCES ` + LayoutsTable + `(id) ON DELETE RESTRICT,
is_custom BOOLEAN NOT NULL DEFAULT FALSE,
file_hash TEXT,
base_hash TEXT,
customized_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)`,
`CREATE INDEX ` + TemplatesTable + `_layout_id_index ON ` + TemplatesTable + ` (layout_id)`,
`CREATE TABLE ` + PartialsTable + ` (
id SERIAL PRIMARY KEY,
code TEXT NOT NULL UNIQUE,
source TEXT NOT NULL,
name TEXT NOT NULL DEFAULT '',
content_html TEXT NOT NULL DEFAULT '',
content_text TEXT NOT NULL DEFAULT '',
is_custom BOOLEAN NOT NULL DEFAULT FALSE,
file_hash TEXT,
base_hash TEXT,
customized_at TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)`,
`CREATE TABLE ` + BrandTable + ` (
id INTEGER PRIMARY KEY,
logo_file_id INTEGER,
body_bg TEXT NOT NULL DEFAULT '',
content_bg TEXT NOT NULL DEFAULT '',
header_color TEXT NOT NULL DEFAULT '',
footer_color TEXT NOT NULL DEFAULT '',
heading_color TEXT NOT NULL DEFAULT '',
text_color TEXT NOT NULL DEFAULT '',
link_color TEXT NOT NULL DEFAULT '',
button_text_color TEXT NOT NULL DEFAULT '',
button_primary_bg TEXT NOT NULL DEFAULT '',
button_positive_bg TEXT NOT NULL DEFAULT '',
button_negative_bg TEXT NOT NULL DEFAULT '',
panel_bg TEXT NOT NULL DEFAULT '',
table_border_color TEXT NOT NULL DEFAULT '',
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)`,
`CREATE TABLE ` + ImageLibraryTable + ` (
id SERIAL PRIMARY KEY,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)`,
}
for _, stmt := range stmts {
if err := tx.Exec(stmt).Error; err != nil {
return err
}
}
return nil
},
Rollback: func(tx *gorm.DB) error {
// Templates first: they reference layouts.
for _, table := range []string{ImageLibraryTable, BrandTable, PartialsTable, TemplatesTable, LayoutsTable} {
if err := tx.Exec("DROP TABLE IF EXISTS " + table).Error; err != nil {
return err
}
}
return nil
},
},
}
// OverrideSource supplies the database overrides one render needs.
type OverrideSource interface {
// MailOverrides returns the overrides for one send of template. An
// empty template asks for everything except a template override. A nil
// or empty field means the file version is used.
MailOverrides(ctx context.Context, template string) (Overrides, error)
}
// Overrides is what an OverrideSource returns for one render.
type Overrides struct {
// Template is the customized subject, body and layout of the template
// being sent, or nil.
Template *TemplateOverride
// Layouts holds layout content by layout code: the full name of a
// customized file layout, or the code of a database-only layout. The
// layout a render uses is taken from here when its code is present.
Layouts map[string]LayoutOverride
// Partials holds the customized sections of partials by full name.
Partials map[string]PartialOverride
// Brand is the saved Branding, or nil while it has never been saved.
// Its LogoURL is already absolute.
Brand *Brand
// warnings are problems the source worked around, for the mailer to
// log: a logo that cannot be shown, for example.
warnings []string
}
// empty reports whether o holds no override of a file. Branding is not one:
// it applies to the file version too.
func (o Overrides) empty() bool {
return o.Template == nil && len(o.Layouts) == 0 && len(o.Partials) == 0
}
// TemplateOverride replaces a template's subject, body and layout.
type TemplateOverride struct {
Subject string
Body string
// Layout is a layout code: the full name of a file layout or the code
// of a database-only one. Empty keeps the file's layout.
Layout string
}
// LayoutOverride is a layout's content from the database: the HTML and text
// wrappers, and CSS that is placed before mail.css in the layout's css slot.
type LayoutOverride struct {
Name string
HTML string
Text string
CSS string
}
// PartialOverride replaces a partial's HTML and text sections.
type PartialOverride struct {
HTML string
Text string
}
// NewDBSource returns the OverrideSource that reads postcard's tables. It
// looks the *gorm.DB up on app at every call and never caches a row, so an
// edit is effective on the next send in every process that shares the
// database. With no database published it returns no overrides and no error.
//
// One call reads, in one read-only transaction, the customized row of the
// template, every customized file layout and every database-only layout,
// every customized partial, and the Branding row. The logo's URL is built
// here, from the application's configuration (attach.AbsolutePublicURL), so
// it is the same in every process.
func NewDBSource(app *backpack.App) OverrideSource {
return &dbSource{app: app}
}
type dbSource struct {
app *backpack.App
}
// MailOverrides implements OverrideSource. name is the template's full name.
func (s *dbSource) MailOverrides(ctx context.Context, name string) (Overrides, error) {
var out Overrides
if s == nil || s.app == nil {
return out, nil
}
gdb, ok := s.app.Lookup[*gorm.DB]()
if !ok || gdb == nil {
return out, nil
}
// The mailer reports a failed lookup itself, rate-limited; GORM's own
// error line per send would repeat it for every message.
db := gdb.Session(&gorm.Session{Logger: gdb.Logger.LogMode(logger.Silent)}).WithContext(ctx)
err := db.Transaction(func(tx *gorm.DB) error {
if name != "" {
var rows []struct {
Subject string
Body string
Layout string
}
err := tx.Raw(`SELECT t.subject, t.body, COALESCE(l.code, '') AS layout
FROM `+TemplatesTable+` t
LEFT JOIN `+LayoutsTable+` l ON l.id = t.layout_id
WHERE t.code = ? AND t.is_custom`, name).Scan(&rows).Error
if err != nil {
return err
}
if len(rows) > 0 {
out.Template = &TemplateOverride{Subject: rows[0].Subject, Body: rows[0].Body, Layout: rows[0].Layout}
}
}
// is_custom is set on a customized file layout and on every
// database-only layout.
var layouts []struct {
Code string
Name string
ContentHTML string `gorm:"column:content_html"`
ContentText string `gorm:"column:content_text"`
ContentCSS string `gorm:"column:content_css"`
}
if err := tx.Raw(`SELECT code, name, content_html, content_text, content_css FROM ` + LayoutsTable + ` WHERE is_custom`).Scan(&layouts).Error; err != nil {
return err
}
for _, l := range layouts {
if out.Layouts == nil {
out.Layouts = make(map[string]LayoutOverride, len(layouts))
}
out.Layouts[l.Code] = LayoutOverride{Name: l.Name, HTML: l.ContentHTML, Text: l.ContentText, CSS: l.ContentCSS}
}
var partials []struct {
Code string
ContentHTML string `gorm:"column:content_html"`
ContentText string `gorm:"column:content_text"`
}
if err := tx.Raw(`SELECT code, content_html, content_text FROM ` + PartialsTable + ` WHERE is_custom`).Scan(&partials).Error; err != nil {
return err
}
for _, p := range partials {
if out.Partials == nil {
out.Partials = make(map[string]PartialOverride, len(partials))
}
out.Partials[p.Code] = PartialOverride{HTML: p.ContentHTML, Text: p.ContentText}
}
return s.brand(tx, &out)
}, &sql.TxOptions{ReadOnly: true, Isolation: sql.LevelRepeatableRead})
if err != nil {
return Overrides{}, fmt.Errorf("postcard: mail overrides: %w", err)
}
return out, nil
}
// brand reads the Branding row into out.Brand: nil while the row does not
// exist, which is what keeps mail.brandCss in use until Branding is saved.
func (s *dbSource) brand(tx *gorm.DB, out *Overrides) error {
var rows []struct {
LogoFileID *int64
BodyBg string
ContentBg string
HeaderColor string
FooterColor string
HeadingColor string
TextColor string
LinkColor string
ButtonTextColor string
ButtonPrimaryBg string
ButtonPositiveBg string
ButtonNegativeBg string
PanelBg string
TableBorderColor string
}
err := tx.Raw(`SELECT logo_file_id, body_bg, content_bg, header_color, footer_color, heading_color, text_color,
link_color, button_text_color, button_primary_bg, button_positive_bg, button_negative_bg, panel_bg, table_border_color
FROM ` + BrandTable + ` WHERE id = 1`).Scan(&rows).Error
if err != nil {
return err
}
if len(rows) == 0 {
return nil
}
r := rows[0]
out.Brand = &Brand{
BodyBg: r.BodyBg, ContentBg: r.ContentBg, HeaderColor: r.HeaderColor, FooterColor: r.FooterColor,
HeadingColor: r.HeadingColor, TextColor: r.TextColor, LinkColor: r.LinkColor, ButtonTextColor: r.ButtonTextColor,
ButtonPrimaryBg: r.ButtonPrimaryBg, ButtonPositiveBg: r.ButtonPositiveBg, ButtonNegativeBg: r.ButtonNegativeBg,
PanelBg: r.PanelBg, TableBorderColor: r.TableBorderColor,
}
if r.LogoFileID == nil {
return nil
}
// A logo that cannot be shown is left out and reported; the mail and
// the other overrides are not affected. The files table is read under
// a savepoint, so a failure there does not abort the transaction.
var disks []string
err = tx.Transaction(func(sp *gorm.DB) error {
return sp.Raw(`SELECT disk_name FROM system_files WHERE id = ? AND is_public`, *r.LogoFileID).Scan(&disks).Error
})
switch {
case err != nil:
out.warnings = append(out.warnings, "mail branding logo: the file cannot be read: "+err.Error())
case len(disks) == 0:
out.warnings = append(out.warnings, "mail branding logo: the file is missing or is not public")
default:
logo, err := attach.AbsolutePublicURL(s.app.Config, attach.BlobKey(disks[0]))
if err != nil {
out.warnings = append(out.warnings, "mail branding logo: "+err.Error())
break
}
out.Brand.LogoURL = logo
}
return nil
}
// syncLockKey names the advisory lock that serializes SyncIndex runs.
const syncLockKey = "summercms.postcard.sync"
// SyncIndex gives every template, layout and partial of cat its index row,
// keyed by code, so that admin lists, forms and relations can work on rows.
// It runs layouts first, then templates (whose layout_id points at the
// layout row of the file's layout), then partials.
//
// For a row that is not customized the content columns mirror the file. For
// a customized row they are left alone: only source, description, locale,
// name and file_hash follow the file, which is what makes a changed file
// show as a difference between base_hash and file_hash. No row is deleted,
// database-only layouts are not touched, and a row that already matches is
// not written. locales are the application's locales, for TemplateLocale.
//
// It is safe to call from several processes at once. It fails when the
// tables are not migrated yet; the caller decides when to try again.
func SyncIndex(ctx context.Context, db *gorm.DB, cat *Catalog, locales []string) error {
if db == nil {
return fmt.Errorf("postcard: sync index: database is nil")
}
if cat == nil {
return fmt.Errorf("postcard: sync index: catalog is nil")
}
layouts, templates, partials := cat.Layouts(), cat.Templates(), cat.Partials()
err := db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
if err := tx.Exec(`SELECT pg_advisory_xact_lock(hashtext(?))`, syncLockKey).Error; err != nil {
return err
}
for _, l := range layouts {
if err := tx.Exec(`INSERT INTO `+LayoutsTable+` AS t (code, source, name, content_html, content_text, content_css, file_hash)
VALUES (?, ?, ?, ?, ?, '', ?)
ON CONFLICT (code) DO UPDATE SET
source = EXCLUDED.source,
name = EXCLUDED.name,
file_hash = EXCLUDED.file_hash,
content_html = CASE WHEN t.is_custom THEN t.content_html ELSE EXCLUDED.content_html END,
content_text = CASE WHEN t.is_custom THEN t.content_text ELSE EXCLUDED.content_text END,
content_css = CASE WHEN t.is_custom THEN t.content_css ELSE EXCLUDED.content_css END,
updated_at = NOW()
WHERE t.source IS DISTINCT FROM EXCLUDED.source
OR t.name IS DISTINCT FROM EXCLUDED.name
OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
OR (NOT t.is_custom AND (t.content_html, t.content_text, t.content_css)
IS DISTINCT FROM (EXCLUDED.content_html, EXCLUDED.content_text, EXCLUDED.content_css))`,
l.Name, l.PluginID, rowName(l.Title, l.Name), l.HTML, l.Text, l.Hash).Error; err != nil {
return err
}
}
for _, f := range templates {
if err := tx.Exec(`INSERT INTO `+TemplatesTable+` AS t (code, source, locale, description, subject, body, layout_id, file_hash)
VALUES (?, ?, NULLIF(?, ''), ?, ?, ?, (SELECT id FROM `+LayoutsTable+` WHERE code = ?), ?)
ON CONFLICT (code) DO UPDATE SET
source = EXCLUDED.source,
locale = EXCLUDED.locale,
description = EXCLUDED.description,
file_hash = EXCLUDED.file_hash,
subject = CASE WHEN t.is_custom THEN t.subject ELSE EXCLUDED.subject END,
body = CASE WHEN t.is_custom THEN t.body ELSE EXCLUDED.body END,
layout_id = CASE WHEN t.is_custom THEN t.layout_id ELSE EXCLUDED.layout_id END,
updated_at = NOW()
WHERE t.source IS DISTINCT FROM EXCLUDED.source
OR t.locale IS DISTINCT FROM EXCLUDED.locale
OR t.description IS DISTINCT FROM EXCLUDED.description
OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
OR (NOT t.is_custom AND (t.subject, t.body, t.layout_id)
IS DISTINCT FROM (EXCLUDED.subject, EXCLUDED.body, EXCLUDED.layout_id))`,
f.Name, f.PluginID, TemplateLocale(f.Name, locales), f.Description, f.Subject, f.Body, f.Layout, f.Hash).Error; err != nil {
return err
}
}
for _, p := range partials {
if err := tx.Exec(`INSERT INTO `+PartialsTable+` AS t (code, source, name, content_html, content_text, file_hash)
VALUES (?, ?, ?, ?, ?, ?)
ON CONFLICT (code) DO UPDATE SET
source = EXCLUDED.source,
name = EXCLUDED.name,
file_hash = EXCLUDED.file_hash,
content_html = CASE WHEN t.is_custom THEN t.content_html ELSE EXCLUDED.content_html END,
content_text = CASE WHEN t.is_custom THEN t.content_text ELSE EXCLUDED.content_text END,
updated_at = NOW()
WHERE t.source IS DISTINCT FROM EXCLUDED.source
OR t.name IS DISTINCT FROM EXCLUDED.name
OR t.file_hash IS DISTINCT FROM EXCLUDED.file_hash
OR (NOT t.is_custom AND (t.content_html, t.content_text)
IS DISTINCT FROM (EXCLUDED.content_html, EXCLUDED.content_text))`,
p.Name, p.PluginID, rowName(p.Title, p.Name), p.HTML, p.Text, p.Hash).Error; err != nil {
return err
}
}
return nil
})
if err != nil {
return fmt.Errorf("postcard: sync index: %w", err)
}
return nil
}
// rowName is the name column of a layout or partial row: the name in the
// file's header, or the full name when the header has none.
func rowName(title, full string) string {
if title != "" {
return title
}
return full
}
// ResetOverride returns one file-backed row to its file version: the content
// columns mirror the file again and is_custom, base_hash and customized_at
// are cleared. kind is KindTemplate, KindLayout or KindPartial and code the
// row's code. A database-only layout has no file version: it is refused, and
// so is a code cat does not hold.
func ResetOverride(ctx context.Context, db *gorm.DB, cat *Catalog, kind Kind, code string) error {
if db == nil {
return fmt.Errorf("postcard: reset %s: database is nil", code)
}
if cat == nil {
return fmt.Errorf("postcard: reset %s: catalog is nil", code)
}
db = db.WithContext(ctx)
var res *gorm.DB
switch kind {
case KindTemplate:
f, ok := cat.Template(code)
if !ok {
return fmt.Errorf("postcard: reset %s: no file version", code)
}
res = db.Exec(`UPDATE `+TemplatesTable+` SET subject = ?, body = ?,
layout_id = (SELECT id FROM `+LayoutsTable+` WHERE code = ?),
file_hash = ?, is_custom = FALSE, base_hash = NULL, customized_at = NULL, updated_at = NOW()
WHERE code = ? AND source IS NOT NULL`, f.Subject, f.Body, f.Layout, f.Hash, code)
case KindLayout:
f, ok := cat.Layout(code)
if !ok {
return fmt.Errorf("postcard: reset %s: no file version", code)
}
res = db.Exec(`UPDATE `+LayoutsTable+` SET name = ?, content_html = ?, content_text = ?, content_css = '',
file_hash = ?, is_custom = FALSE, base_hash = NULL, customized_at = NULL, updated_at = NOW()
WHERE code = ? AND source IS NOT NULL`, rowName(f.Title, f.Name), f.HTML, f.Text, f.Hash, code)
case KindPartial:
f, ok := cat.Partial(code)
if !ok {
return fmt.Errorf("postcard: reset %s: no file version", code)
}
res = db.Exec(`UPDATE `+PartialsTable+` SET name = ?, content_html = ?, content_text = ?,
file_hash = ?, is_custom = FALSE, base_hash = NULL, customized_at = NULL, updated_at = NOW()
WHERE code = ? AND source IS NOT NULL`, rowName(f.Title, f.Name), f.HTML, f.Text, f.Hash, code)
default:
return fmt.Errorf("postcard: reset %s: kind %q has no file version", code, kind)
}
if res.Error != nil {
return fmt.Errorf("postcard: reset %s: %w", code, res.Error)
}
if res.RowsAffected == 0 {
return fmt.Errorf("postcard: reset %s: no index row", code)
}
return nil
}