From 67f71643021ce8d19776f559cd4b95d85be316aa Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 20:39:45 +0100 Subject: [PATCH] feat(cabana): mail templates list grouped by template with per-locale status Gap G-35-1 (supersedes D-05; D-06 reset and D-07 drift per locale): - the templates list keeps one row per template (the base row, or the lowest variant when only variants ship) with a Customized locales column (Default, then locale codes, at most three then +N); - row states and the status filter aggregate over the template's locale versions; the locale filter is removed; - a not-customized locale without a file shows the base row's current subject, body and layout; its info partial says so, its file version compares with the base file, and Reset returns it to the base file (postcard.ResetOverride accepts a fallback-locale code); - copy: mail.template.customized_locales, mail.info_locale_default, mail.info_locale_fallback (en/pl); - tests: TestMailScreensSmoke/locales_list, templates and drift updated, TestMailDrift on the grouped row, TestMailTemplateFilterScopes. --- docs/services/mail.md | 4 +- modules/cabana/README.md | 4 +- .../controllers/mailtemplates/_info.htm | 4 +- .../mailtemplates/config_filter.yaml | 5 - .../models/mailtemplate/columns.yaml | 5 +- modules/cabana/crud.go | 5 + modules/cabana/mail_admin.go | 360 +++++++++++++----- .../cabana/mail_lifecycle_postgres_test.go | 8 +- modules/cabana/mail_screens_smoke_test.go | 158 +++++++- modules/cabana/mail_unit_test.go | 8 + modules/phrasebook/backend/lang/en/lang.yaml | 3 + modules/phrasebook/backend/lang/pl/lang.yaml | 3 + modules/postcard/README.md | 2 +- modules/postcard/store.go | 9 +- 14 files changed, 460 insertions(+), 118 deletions(-) diff --git a/docs/services/mail.md b/docs/services/mail.md index 02ab836a..5ac65288 100644 --- a/docs/services/mail.md +++ b/docs/services/mail.md @@ -169,11 +169,11 @@ The log lines carry the component `postcard`. In a test, pass any `postcard.Over Every application with an admin gets the mail screens in Settings → Mail, with no setup in the application or its plugins. They are served by the admin itself (cabana) over postcard's tables: -- **Mail templates** lists every template the application's plugins register, one row per file, so `acme.blog::mail.welcome` and `acme.blog::mail.welcome-en` are separate rows. The list shows the code, the subject, the file's description, the locale (the suffix after the last dash when it is one of the application's locales, otherwise Default) and the layout. The form edits the subject, the Markdown message and the layout, chosen from every file layout and every layout created in the admin. The description stays the file's. +- **Mail templates** lists every template the application's plugins register, one row per template however many locales the application has: `acme.blog::mail.welcome` and its `acme.blog::mail.welcome-en` variant are one row. The list shows the code, the subject, the file's description, the customized locales (Default and the locale codes whose version was customized, at most three and then +N) and the layout. The Customized and File changed badges and the status filter (customized, not customized, file changed) are about the whole template: any of its locale versions. The form edits the subject, the Markdown message and the layout, chosen from every file layout and every layout created in the admin. The description stays the file's. A **Language** select under the title switches between the template's versions: Default (the template's own file), every locale with its own file, and every other locale of the application. A locale with neither a file nor a customization shows the default version, which is what it sends; saving it creates that locale's own version, and Reset to file version returns it to the default version. The application's locales are the admin's translation locales plus the content locales of a translate plugin, when one is installed. The screen needs `system.manage_mail_templates` (see [Users and permissions](../backend/users-and-permissions.md#permissions)). Templates come from files, so the list has no create and no delete. -The rows exist before anyone edits a template: when the admin starts, it writes an index row for every file template, layout and partial (`postcard.SyncIndex`), and keeps a row that is not customized equal to its file. A row whose plugin is no longer installed stays in the table but is not listed. If the tables are not there yet when the admin starts, the first open of a mail list writes the rows. +The rows exist before anyone edits a template: when the admin starts, it writes an index row for every file template, layout and partial (`postcard.SyncIndex`) and for every locale a template ships no file for (`postcard.EnsureLocaleRows`), and keeps a row that is not customized equal to its file. A row whose plugin is no longer installed stays in the table but is not listed. If the tables are not there yet when the admin starts, the first open of a mail list writes the rows. Saving a template stores your subject, message and layout in its row and marks it customized, together with the hash of the file the change was based on. From then on your version is sent instead of the file, until the template is reset to the file version. A save is checked the way a send would render it (`postcard.Editor.Validate`): a message that does not parse, does not render with the sample values or fails the safety checks is refused with a line under the field, and nothing is stored. diff --git a/modules/cabana/README.md b/modules/cabana/README.md index 0bb2e22b..63ea8fd6 100644 --- a/modules/cabana/README.md +++ b/modules/cabana/README.md @@ -59,7 +59,7 @@ Use cases: - Form fields on another plugin's controller: a `pact.AdminActionExtension` with `Form` set to a `pact.AdminFormExtension` places fields and tabs in any admin controller's form by its ID. Its fields document is the `fields.yaml` format plus `before:`/`after:` anchors, `zone:` (only the tab zone for now) and a `tabs:` list, compiled at boot with every `fields.yaml` check; extensions apply in plugin activation order and the form is sent in the compiled order, so the SPA adds no ordering. `Hide` removes owner fields, `Permissions` and `Visible` decide per request who sees the fields (schema, show and save alike), widget fields run the extension's `Actions` and partial fields render from its `Dir` through `PartialData`. Extension values leave the save body before any owner path reads them; `Save` runs in the record's save transaction after the owner row is written (`pact.AdminFormErrors` answers 422, its notices join `meta.notices`) and `Load` serves the values on show. A form no extension lays out compiles unchanged. Unknown anchors, duplicate names, anchor cycles, anchors outside `Requires()`, other zones, `fileupload` fields and clashing widget action or partial names stop the boot naming the plugin, the controller and the name. - Plugins screen: Settings → System → Plugins opens the admin SPA route `/system/plugins` (the settings entry carries `path` instead of a controller) for administrators holding `cabana.PermissionViewPlugins` (`backend.view_plugins`, granted to no role in code; superusers always pass). GET `/plugins` lists the plugins the application was built with from the `party.Installed` metadata `summer build` bakes (name, description, version, source, module and package), or only the IDs of `party.Activated` for an application built before that metadata existed, with the framework version and the state of the plugin registry (`plugins.registry_url`, read through `kiosk.RegistryURL`). With the registry configured, cabana (never the SPA) looks up each versioned plugin's releases through `kiosk.Client` and marks an update when `kiosk.NewestCompatible` finds a release newer than the installed version by `kiosk.Newer` (a `git describe` string or a pseudo-version compares by the tag it builds on), with the `summer plugin:update ` command; GET `/plugins/marketplace` searches the registry and adds installed and compatibility markers (compatible when `summer plugin:install` can install some release with the built framework, looking up the releases of a plugin whose newest one needs a newer framework; always compatible when the built framework version is not a release) and the `summer plugin:install ` command. Registry calls have a 4 second timeout, at most four run at once, and answers are cached in process (searches 5 minutes, at most 256 distinct searches with expired and then the oldest dropped first, releases 15 minutes, failures 1 minute); a failing registry gives `status` unavailable and never a non-200 answer. - Administrators screen: when some plugin registers admin controllers, `cabana.Activate` also compiles the admin's own screens, an internal plugin with ID `summercms.cabana`. Settings → System → Administrators (controller `cabana.AdministratorsControllerID`, permission `cabana.PermissionManageUsers`) lists backend administrators with their role and last sign-in, opens a preview of each, where record actions (the admin's own and contributed ones) are offered, and creates and edits administrators: login, email, names, a password (hashed at `admin.password.bcrypt_cost`, at least 4 characters and at most 72 bytes), the role and per-administrator permission overrides. The server enforces the privilege rules in the save transaction: only a superuser sees superusers or sends the superuser switch, an administrator can neither grant permissions or roles above their own grants nor change an administrator who holds more than they do, their own role, superuser flag, permissions and password are not changed here, and the last active superuser cannot be demoted. A password set for another administrator ends their sessions (personal API tokens stay valid, as with `admin:reset-password`). Administrators are activated, deactivated and restored by record and bulk actions and deleted softly through `deleted_at` (never hard-deleted); the list shows deleted and deactivated rows with their row states and filters deleted ones, and the preview shows a status hint. Deactivating or deleting an administrator ends their sessions and stops their personal API tokens; the last active superuser cannot be demoted, deactivated or deleted on any of these paths (a transaction-scoped advisory lock serializes the check). The permission codes `cabana.PermissionManageUsers` and `cabana.PermissionManageRoles` are registered with no role grant, so after an upgrade only superusers see the screens until an administrator grants them. An application without admin controllers still activates no admin. -- Mail screens (Settings → Mail): when the application publishes postcard's Mailer (`postcard.EditorFrom` succeeds; `party.Activate` runs `postcard.Activate`), the internal plugin also registers the mail screens over postcard's tables, the permission codes `cabana.PermissionManageMailTemplates` (`system.manage_mail_templates`) and `cabana.PermissionManageMailLayouts` (`system.manage_mail_layouts`), both granted to no role in code, and their Settings entries in category `backend::lang.settings.category_mail`. Mail templates (controller `cabana.MailTemplatesControllerID`, model `cabana.MailTemplate`) lists the templates of this process's catalog (rows of uninstalled plugins are hidden) with code, subject, description, locale (Default for a name without a locale suffix) and layout, and edits the subject, the Markdown body and the layout (a `relation` over `cabana.MailLayout` rows: every database-only layout and the catalog's file layouts). There is no create and no delete. A save marks the row customized, stamps `base_hash` with the file's current hash and `customized_at`, and validates the result through `postcard.Editor.Validate` inside the save's transaction; a `postcard.DraftError` is a 422 on its field with `backend::lang.mail.invalid_` (`:message`, `:name`). The index rows are written by `postcard.SyncIndex` and `postcard.EnsureLocaleRows` through `lagoon.OnDatabase` at activation; a failed sync is logged and retried on the first mail list request of the process, and a list request syncs again when the mail locales changed. The mail locales are the locales the translator's catalog holds plus, when a `cabana.TranslationWriter` is published, its enabled locales; the default locale is the writer's default locale, else the translator's. A template is one record per locale version: its own row (Default), a row per locale variant file (`welcome-en`) and a row per other mail locale that ships no file (`welcome-de`, created by `postcard.EnsureLocaleRows`, showing and sending the default version until it is customized). The update form's locale switcher lists them (`meta.localeVariants`); the record title is the template's base code, and the show response first ensures the template's missing locale rows, so a newly enabled locale can be opened without a restart. A save of a locale without a file stamps `base_hash` with the base file's hash. Mail layouts (`cabana.MailLayoutsControllerID`, model `cabana.MailLayout`) lists postcard's default layout first, then the file layouts and the custom (database-only, `source` NULL, shown as Custom) layouts by name; it creates custom layouts (code `^[a-z0-9-]+$`, free, create-only) and deletes them, refusing one that template rows still reference with a `cabana.ForbiddenError` whose message names the layout and the count (CLDR plural). Mail partials (`cabana.MailPartialsControllerID`, model `cabana.MailPartial`) edits the partials' HTML and text sections. Both need `cabana.PermissionManageMailLayouts`; saves are stamped and validated as templates are. On all three, the record action `reset` (danger, offered on a customized file-backed row) calls `postcard.ResetOverride` in the action's transaction; rows from files are never deleted. The list row states are `customized` (an override) and `outdated` (an override whose `base_hash` differs from the file's `file_hash`), the lists have a status filter (customized, not customized, outdated) and templates a locale filter, and the forms carry the `info` and `file_version` partials: the file, the status, the sample variables or the partial's call, the drift callout, and a 3-line-context LCS line diff of the serialized override (`postcard.FormatTemplate`, `FormatLayout`, `FormatPartial`) against the file, skipped above 2000 lines per side. The mail controllers declare `recordActions` without a preview block: the admin offers them in the update form's footer, a boot rule only these internal controllers are exempt from. Layout and partial content fields use the built-in `codeeditor` type (`language: html|css|text`, optional `mailImages`); Branding is the settings form `mail_brand` on `cabana.MailBrandSetting` (postcard's brand row, 13 `colorpicker` colours and a `mailimage` logo; the first save switches mail from `mail.brandCss` to the compiled colours). Mail images is the singleton controller `cabana.MailImagesControllerID` (`cabana.MailImageLibrary`) with a public attachMany `images` fileupload; GET/POST `/mail/images` and GET `/mail/images/{id}` return absolute public URLs (`attach.AbsolutePublicURL`) and refuse with `mail.images.no_public_url` when neither `storage.uploads.public_url` nor `app.url` is set. Listing answers either mail permission; upload and the singleton form need `system.manage_mail_layouts`. POST `/mail/preview` renders an unsaved draft (`cabana.AdminMailPreviewRequest`: `mode`, `id`, `values`) through `postcard.Editor.Preview` and answers `cabana.AdminMailPreviewResult` (subject, html, text); mode `template` needs `system.manage_mail_templates`, modes `layout`, `partial` and `branding` need `system.manage_mail_layouts`. POST `/mail/test-send` (interactive sessions only) sends a template, layout or partial draft to the signed-in administrator's own email (`cabana.AdminMailTestSendResult`), refuses recipient keys in the body, and is limited to five sends per administrator per ten minutes through a published `cooler.Attempter` when `serve` has one, otherwise an in-process fixed window (429 with `Retry-After`). Forms carry `mailpreview` fields (`mode` matching the screen). +- Mail screens (Settings → Mail): when the application publishes postcard's Mailer (`postcard.EditorFrom` succeeds; `party.Activate` runs `postcard.Activate`), the internal plugin also registers the mail screens over postcard's tables, the permission codes `cabana.PermissionManageMailTemplates` (`system.manage_mail_templates`) and `cabana.PermissionManageMailLayouts` (`system.manage_mail_layouts`), both granted to no role in code, and their Settings entries in category `backend::lang.settings.category_mail`. Mail templates (controller `cabana.MailTemplatesControllerID`, model `cabana.MailTemplate`) lists one row per template of this process's catalog (rows of uninstalled plugins are hidden; the row is the template's own, or the lowest locale variant when only variants ship) with code, subject, description, customized locales (`cabana.MailTemplate.CustomizedLocales`: Default and the locale codes of the customized versions, at most three then +N) and layout, and edits the subject, the Markdown body and the layout (a `relation` over `cabana.MailLayout` rows: every database-only layout and the catalog's file layouts). There is no create and no delete. A save marks the row customized, stamps `base_hash` with the file's current hash and `customized_at`, and validates the result through `postcard.Editor.Validate` inside the save's transaction; a `postcard.DraftError` is a 422 on its field with `backend::lang.mail.invalid_` (`:message`, `:name`). The index rows are written by `postcard.SyncIndex` and `postcard.EnsureLocaleRows` through `lagoon.OnDatabase` at activation; a failed sync is logged and retried on the first mail list request of the process, and a list request syncs again when the mail locales changed. The mail locales are the locales the translator's catalog holds plus, when a `cabana.TranslationWriter` is published, its enabled locales; the default locale is the writer's default locale, else the translator's. A template is one record per locale version: its own row (Default), a row per locale variant file (`welcome-en`) and a row per other mail locale that ships no file (`welcome-de`, created by `postcard.EnsureLocaleRows`, showing and sending the default version until it is customized). The update form's locale switcher lists them (`meta.localeVariants`); the record title is the template's base code, and the show response first ensures the template's missing locale rows, so a newly enabled locale can be opened without a restart. A save of a locale without a file stamps `base_hash` with the base file's hash; until it is customized, its form shows the base template's current version (its customization when there is one), and reset returns it to the base file. Mail layouts (`cabana.MailLayoutsControllerID`, model `cabana.MailLayout`) lists postcard's default layout first, then the file layouts and the custom (database-only, `source` NULL, shown as Custom) layouts by name; it creates custom layouts (code `^[a-z0-9-]+$`, free, create-only) and deletes them, refusing one that template rows still reference with a `cabana.ForbiddenError` whose message names the layout and the count (CLDR plural). Mail partials (`cabana.MailPartialsControllerID`, model `cabana.MailPartial`) edits the partials' HTML and text sections. Both need `cabana.PermissionManageMailLayouts`; saves are stamped and validated as templates are. On all three, the record action `reset` (danger, offered on a customized file-backed row) calls `postcard.ResetOverride` in the action's transaction; rows from files are never deleted. The list row states are `customized` (an override) and `outdated` (an override whose `base_hash` differs from the file's `file_hash`), the lists have a status filter (customized, not customized, outdated); on the templates list both apply to the whole template, any of its locale versions. The forms carry the `info` and `file_version` partials: the file (the base template's for a locale without a file), the status, on a template with locale versions the Default line or the line of a locale without a file (`backend::lang.mail.info_locale_default`, `info_locale_fallback`), the sample variables or the partial's call, the drift callout, and a 3-line-context LCS line diff of the serialized override (`postcard.FormatTemplate`, `FormatLayout`, `FormatPartial`) against the file, skipped above 2000 lines per side. The mail controllers declare `recordActions` without a preview block: the admin offers them in the update form's footer, a boot rule only these internal controllers are exempt from. Layout and partial content fields use the built-in `codeeditor` type (`language: html|css|text`, optional `mailImages`); Branding is the settings form `mail_brand` on `cabana.MailBrandSetting` (postcard's brand row, 13 `colorpicker` colours and a `mailimage` logo; the first save switches mail from `mail.brandCss` to the compiled colours). Mail images is the singleton controller `cabana.MailImagesControllerID` (`cabana.MailImageLibrary`) with a public attachMany `images` fileupload; GET/POST `/mail/images` and GET `/mail/images/{id}` return absolute public URLs (`attach.AbsolutePublicURL`) and refuse with `mail.images.no_public_url` when neither `storage.uploads.public_url` nor `app.url` is set. Listing answers either mail permission; upload and the singleton form need `system.manage_mail_layouts`. POST `/mail/preview` renders an unsaved draft (`cabana.AdminMailPreviewRequest`: `mode`, `id`, `values`) through `postcard.Editor.Preview` and answers `cabana.AdminMailPreviewResult` (subject, html, text); mode `template` needs `system.manage_mail_templates`, modes `layout`, `partial` and `branding` need `system.manage_mail_layouts`. POST `/mail/test-send` (interactive sessions only) sends a template, layout or partial draft to the signed-in administrator's own email (`cabana.AdminMailTestSendResult`), refuses recipient keys in the body, and is limited to five sends per administrator per ten minutes through a published `cooler.Attempter` when `serve` has one, otherwise an in-process fixed window (429 with `Retry-After`). Forms carry `mailpreview` fields (`mode` matching the screen). - Danger record actions: `pact.AdminRecordAction.Danger` is served as `danger` on the record response's `cabana.RecordAction` (absent when false, so existing payloads are unchanged); the admin's confirm dialog then uses its danger variant. - Prompted record actions: a `pact.AdminRecordAction` with a `Prompt` (`pact.AdminActionPrompt`) asks the administrator for one text value in its confirm dialog. The record response serves it as `prompt` on the action's `cabana.RecordAction` (absent for every other action, so existing payloads are unchanged), and the action route accepts the body key `payload`, a JSON string, only for such an action: trimmed, not empty and at most `max_length` runes (422 on `payload` with `backend::lang.form.action_prompt_required` or `action_prompt_too_long`, `backend::lang.form.action_prompt_invalid` for another JSON type), then handed to `Run` as `pact.AdminRecordActionInput.Value`. Every other record action keeps refusing `record_id`, `values` and `payload`. A prompt without a label fails boot, owned or contributed. - My account contributions: a plugin implementing `pact.HasAccountContributions` adds sections (`pact.AccountContribution`) to the administrator's own account page, each with a status line and buttons (`pact.AccountAction`). GET `/account/contributions` lists them for the signed-in administrator and POST `/account/contributions/{name}/actions/{action}` runs one for that administrator only, behind the interactive-only guard, the action's permissions and its `Applies` rule, inside a transaction; the answer may carry a URL the admin opens in a new tab. That URL is kept only when it is an absolute `http`/`https` URL with a host or a same-origin path (one leading `/`); anything else, `javascript:` and `data:` included, is dropped and logged without the URL. A section whose `Status` fails is listed with an empty status and `error: true`, and an action whose `Applies` fails is left out and marks its section `error: true` as well; both are logged and the other sections are answered as usual. A status is translated only when it is a phrase key. Names are generic: cabana never names the contributing plugin. The existing `/account*` and `/auth/me` payloads are unchanged. A non-identifier or duplicate section name, an empty label, a duplicate or non-identifier action name, a nil `Run` or an empty action label stops the boot. @@ -440,4 +440,4 @@ The Roles form's holders list is covered by the Docker-free TestRolesHoldersPart The Plugins screen is covered by the Docker-free TestPluginsScreenSmoke in `plugins_smoke_test.go`: the installed list from `party.Installed` and the `party.Activated` fallback, 401 and 403 without `cabana.PermissionViewPlugins`, the settings entry with its `path` only for allowed administrators, and against a fake registry the update rule (a git describe version compares by its base tag), unlisted and local plugins, a failing or slow registry, a disabled one (no request), the marketplace search with its validation and the cache windows. -The mail screens are covered by the Postgres test TestMailScreensSmoke in `mail_screens_smoke_test.go`, on a fixture plugin with two templates, a layout and a partial: the templates list and form, an override that the next send uses, a refused unsafe body that leaves the row unchanged, the permission split and the Settings → Mail tiles per permission; layouts (order, custom layout create, code format and uniqueness, the `{{ .Content }}` check, a customized layout in the next send), partials (parse error, usage line), reset, the in-use delete refusal, `meta.deletable`, drift (a second process booted over a changed file: row states, the status and locale filters, the info and file version partials, a save that clears the drift), the line diff, and locales (with a published `cabana.TranslationWriter` enabling pl, en and de: the template's `meta.localeVariants`, the base-code title, a save of the de version that the next send of `