Both defects came out of Phase 13's acceptance walk, and neither was visible to any test. **1. The one-shot rule-group guard was not a guard.** `seedRuleGroup` and `coreRules.seedGroup` both read their settings stamp, inserted the whole group, and wrote the stamp AFTER the loop. Two instances booting in the same moment both read "absent" and both insert -- the walk ended up with 52 module rules where the module ships 26. `docker compose up --scale app=2` and a rolling restart both start two instances on purpose, so this is ordinary rather than exotic. `settings.db` gains `claim(key, value)`: the same `INSERT IGNORE` as `seedDefault`, reporting its own `affectedRows`, so exactly one caller can win a key. The atomicity is the PRIMARY KEY's -- no transaction, no lock, the same bargain `engagementWorker`'s row claim already makes. Both seeders claim before inserting. The trade the code already documented is unchanged, only its order: a process that dies mid-loop leaves the group stamped and partly seeded, and the missing rules are an operator's visit to the "new rule" form. A duplicate rule is two mails per event, for every rule in the group, which both functions' own comments already call the worse outcome. **Why no test caught it:** the stubs supplied `get` and `set` over a Map, which cannot race, so they agreed with the bug -- Phase 4a's `foundRows` finding in a different costume. The fake is now `claim`-shaped and decides without yielding, exactly as the table does, and both suites gained a test that runs two seeders with `Promise.all` and asserts one insert each. Verified by reverting the fix: the module test then reports every rule inserted twice. **2. A rule that names a `digest` body could not be saved.** `registries.js` `checkSeedRule` permits `digest` in as many words -- it is the body `teamDigestWorker` renders for a rule whose email channel an individual set to digest mode, so it never appears in `channels` and never could -- and MODULE_API.md 2.4 tells modules they may point `template_keys` at `notify.digest`. `engagementRules.model.js` then rejected any key that was not one of the rule's channels. So every rule shipping a digest body answered an operator who opened it and pressed Save with a 400 naming a key they had never typed: core's own Team and news rules, and sixteen of module-uo's. The only way to save was to delete the digest body, silently dropping digest support from that rule. The two validators now agree; anything that is neither a channel nor `digest` is still refused, with a test for each direction. No MODULE_API bump: no member is added, removed or changed, and the documented contract is what the code now honours rather than something new. Co-Authored-By: Claude <noreply@anthropic.com>
195 lines
8.3 KiB
JavaScript
195 lines
8.3 KiB
JavaScript
// ── Seeding what a module ships (ENGAGEMENT.md Phase 11b, decision 7) ──────
|
|
//
|
|
// Core's own bodies and rules are seeded from `seedDefaults()`, and a module's
|
|
// cannot be: `server.js` calls `seedDefaults()` BEFORE it requires `app.js`, and
|
|
// requiring `app.js` is what scans the volume and runs the loader. At the moment
|
|
// core seeds, no module has registered anything at all.
|
|
//
|
|
// So this runs from `modules/lifecycle.js` `boot()` instead — after the
|
|
// `installed_modules` reconcile, so a module the operator disabled or one that
|
|
// failed to load is skipped rather than seeded, and BEFORE the `onBoot`
|
|
// dispatch, so a module that warms a cache in `onBoot` may assume its rules
|
|
// exist.
|
|
//
|
|
// **It reuses core's two seeders rather than reimplementing them**, which is the
|
|
// whole argument for the registry existing (decision 7): `seedOne` owns the
|
|
// `customized` skip and the `seed_version` comparison, `validateEmailBlocks`
|
|
// owns what a renderable body is, and a module supplies data. A copy of either
|
|
// living outside this directory would drift the first time core improved the
|
|
// original — and the drift would surface as a mail somebody already received.
|
|
//
|
|
// ── The asymmetry, once more, because it is the thing to get right ─────────
|
|
//
|
|
// **Templates are re-ensured every boot.** A row carries `seed_key`,
|
|
// `seed_version` and `customized`, so re-ensuring is how a better default
|
|
// reaches a deployment without stealing an operator's edit (§4.6.1 property 3),
|
|
// and a template added in a later module version reaches every deployment rather
|
|
// than only fresh ones.
|
|
//
|
|
// **Rule groups are one-shot, each under its own settings guard.** Re-ensuring a
|
|
// rule would resurrect one an operator deleted and reset one they enabled. This
|
|
// is 11a's seed-key finding as a mechanism: a rule appended to an existing group
|
|
// reaches fresh installs only, and a rule that must reach already-stamped
|
|
// deployments takes a new group key. The module chooses; this file honours it.
|
|
//
|
|
// **Never throws.** It is on the boot path beside every other `safe()`-wrapped
|
|
// step in `lifecycle.boot()`, and a body that would not seed costs the shipped
|
|
// default — `renderByKey`'s fallback stays in charge — not the deployment.
|
|
|
|
const templatesDb = require('../model/engagement/engagementTemplates.db')
|
|
const rulesDb = require('../model/engagement/engagementRules.db')
|
|
const settingsDb = require('../model/settings/settings.db')
|
|
const emailBlocks = require('../emailBlocks')
|
|
const log = require('../utils/logger')('engagement')
|
|
|
|
/**
|
|
* The one-shot guard for one module's rule group.
|
|
*
|
|
* Namespaced by owner AND by group so two modules may use the same group name,
|
|
* and so a module can add a second group later without touching the first. Its
|
|
* VALUE is the timestamp — purely so an operator reading the settings table can
|
|
* tell when it ran; only its presence is read.
|
|
*/
|
|
const guardKey = (owner, group) => `engagement_module_rules_seeded:${owner}:${group}`
|
|
|
|
/**
|
|
* Ensure one module's templates, and bring un-customized rows up to the current
|
|
* seed. Idempotent.
|
|
*/
|
|
async function seedModuleTemplates(owner, templates, deps = {}) {
|
|
const templates_ = deps.templatesDb || templatesDb
|
|
const counts = { inserted: 0, updated: 0, skipped: 0, invalid: 0 }
|
|
for (const seed of templates) {
|
|
// Validated against the block registry before it is stored, exactly as core's
|
|
// own seeds are and for the same reason: a shipped block array no renderer
|
|
// understands sitting in the table reads to an operator as their deployment
|
|
// being broken. Refusing to write it leaves the fallback in charge and puts
|
|
// the reason in the boot log, with the module named.
|
|
const { valid, errors } = emailBlocks.validateEmailBlocks(seed.blocks)
|
|
if (!valid) {
|
|
log.error('a module template is invalid and was not seeded', { owner, key: seed.key, errors })
|
|
counts.invalid += 1
|
|
continue
|
|
}
|
|
try {
|
|
counts[await templates_.seedOne(seed)] += 1
|
|
} catch (err) {
|
|
log.error('module template seed failed', { owner, key: seed.key, message: err.message })
|
|
}
|
|
}
|
|
|
|
// The third arm of §4.6.1 property 3: a customized row is never touched, and
|
|
// the fact that a better default now exists is surfaced instead of applied.
|
|
let stale = []
|
|
try {
|
|
stale = await templates_.staleCustomized(
|
|
templates.map((t) => ({ key: t.key, seedVersion: t.seedVersion })),
|
|
)
|
|
} catch {
|
|
stale = []
|
|
}
|
|
if (stale.length) {
|
|
log.info('customized module templates have a newer shipped default', {
|
|
owner,
|
|
keys: stale.map((t) => t.key),
|
|
})
|
|
}
|
|
return { ...counts, stale: stale.map((t) => t.key) }
|
|
}
|
|
|
|
/**
|
|
* Seed one named rule group, once, under its own guard.
|
|
*
|
|
* Mirrors `coreRules.seedGroup` deliberately, including the claim-before-insert
|
|
* ordering and what it costs: re-running would duplicate the rules that DID
|
|
* insert, and a duplicate rule is two mails per event — worse than the one
|
|
* missing rule an operator can add from the Rules screen. The guard is taken
|
|
* atomically for the same reason; see the comment at the claim.
|
|
*/
|
|
async function seedRuleGroup(owner, group, deps = {}) {
|
|
const rules_ = deps.rulesDb || rulesDb
|
|
const settings_ = deps.settingsDb || settingsDb
|
|
const summary = { inserted: 0, skipped: 0 }
|
|
const key = guardKey(owner, group.key)
|
|
try {
|
|
// **Claim BEFORE inserting, not after.** The guard used to be a `get()` here
|
|
// and a `set()` after the loop, which is not a guard under concurrency: two
|
|
// processes starting in the same moment both read "absent" and both insert
|
|
// the whole group. That is not hypothetical — `docker compose up
|
|
// --scale app=2` and a rolling restart both boot two instances deliberately,
|
|
// and Phase 13's acceptance walk hit it with two, ending up with 52 module
|
|
// rules where the module ships 26. `claim()` is an `INSERT IGNORE` reporting
|
|
// its own `affectedRows`, so exactly one caller wins.
|
|
//
|
|
// The cost is the one this function already accepted below: a process that
|
|
// dies mid-loop leaves the group stamped and partly seeded, and the missing
|
|
// rules are an operator's visit to the "new rule" form. Duplicates are the
|
|
// worse failure — two mails per event, for every rule in the group — which
|
|
// is why the order is this way round rather than the other.
|
|
if (!(await settings_.claim(key, new Date().toISOString()))) {
|
|
return { ...summary, skipped: group.rules.length }
|
|
}
|
|
|
|
for (const rule of group.rules) {
|
|
try {
|
|
await rules_.insert(rule)
|
|
summary.inserted += 1
|
|
} catch (err) {
|
|
log.error('module rule seed failed', {
|
|
owner,
|
|
group: group.key,
|
|
trigger: rule.trigger_id,
|
|
message: err.message,
|
|
})
|
|
}
|
|
}
|
|
if (summary.inserted) {
|
|
log.info('seeded module engagement rules, all disabled', {
|
|
owner,
|
|
group: group.key,
|
|
rules: summary.inserted,
|
|
note: group.note || undefined,
|
|
})
|
|
}
|
|
} catch (err) {
|
|
log.error('module rule group seeding failed', { owner, group: group.key, message: err.message })
|
|
}
|
|
return summary
|
|
}
|
|
|
|
/**
|
|
* Seed every registered module's engagement content.
|
|
*
|
|
* @param {object} [deps]
|
|
* @param {Function} [deps.seeds] () => [{ owner, templates, ruleGroups }]
|
|
* @param {Set} [deps.skip] owners not to seed (disabled or failed)
|
|
* @param {object} [deps.templatesDb] / [deps.rulesDb] / [deps.settingsDb] — test seams
|
|
*/
|
|
async function seedModuleEngagement({ seeds, skip = new Set(), ...dbs } = {}) {
|
|
// eslint-disable-next-line global-require
|
|
const read = seeds || require('../modules/registries').allEngagementSeeds
|
|
const totals = { templates: 0, rules: 0 }
|
|
|
|
for (const entry of read()) {
|
|
if (skip.has(entry.owner)) {
|
|
log.info('skipping engagement seeds for a module that is not booting', { owner: entry.owner })
|
|
continue
|
|
}
|
|
const t = await seedModuleTemplates(entry.owner, entry.templates || [], dbs)
|
|
totals.templates += t.inserted + t.updated
|
|
for (const group of entry.ruleGroups || []) {
|
|
const r = await seedRuleGroup(entry.owner, group, dbs)
|
|
totals.rules += r.inserted
|
|
}
|
|
log.info('module engagement seeds ensured', { owner: entry.owner, ...t })
|
|
}
|
|
return totals
|
|
}
|
|
|
|
module.exports = {
|
|
seedModuleEngagement,
|
|
seedModuleTemplates,
|
|
seedRuleGroup,
|
|
guardKey,
|
|
}
|