Files
summercms/modules/postcard/store.go
Jakub Zych 495319ee21 feat(postcard): sample values, file hashes, index sync and the draft editor
- sample.<path> header keys and a parse-tree walker that fills every other
  variable with a visible [path] placeholder, nested fields and range
  targets included
- every file entry carries the sha256 of its CRLF-normalized text; the
  catalog lists its files (Templates, Layouts, Partials) for admin code
- SyncIndex upserts one index row per file and never touches the override
  columns of a customized row; ResetOverride returns a row to its file
- Editor validates, previews and test-sends a template, layout or partial
  draft through the render path of Send and reports field and rule
- pact.RowStateCustomized and pact.RowStateOutdated

Plan 35-01, task 4.
2026-11-13 10:57:05 +01:00

426 lines
16 KiB
Go

package postcard
import (
"context"
"database/sql"
"fmt"
"git.golem15.com/golem15/summercms/modules/backpack"
"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
}
// empty reports whether o changes nothing about a render.
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, and
// every customized partial.
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 nil
}, &sql.TxOptions{ReadOnly: true, Isolation: sql.LevelRepeatableRead})
if err != nil {
return Overrides{}, fmt.Errorf("postcard: mail overrides: %w", err)
}
return out, 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
}