mikser-io-post-email 1.0.0 → 1.1.0

package/index.js

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
 import nodemailer from 'nodemailer'
 import {
     runtime,
@@ -14,6 +15,10 @@ import {
     humanizeMs,
     resolveAddresses,
     decideTiming,
+    deliveryHash,
+    markerName,
+    formatMarker,
+    isDelivered,
 } from './lib/pure.js'
 
 // Re-export pure helpers so callers (and tests) can import them
@@ -36,6 +41,7 @@ registerSchema('post_email', `
     CREATE TABLE IF NOT EXISTS mikser_post_email_queue (
         id          TEXT PRIMARY KEY REFERENCES mikser_entities(id) ON DELETE CASCADE,
         eml_path    TEXT NOT NULL,
+        eml_hash    TEXT,
         send_at     INTEGER NOT NULL,
         sent_at     INTEGER,
         expired_at  INTEGER,
@@ -68,20 +74,64 @@ async function composeEml({ from, to, cc, bcc, subject, html }) {
     return built.message
 }
 
+// ---------- send-once ledger -----------------------------------------
+//
+// Durable on-disk delivery markers, so a rebuild never re-sends an email
+// already delivered. The queue table can't gate this: mikser wipes its
+// cache on a config change, and the queue rows cascade off
+// mikser_entities — both drop sent state, and every submission then
+// re-renders and re-fires. So the marker lives OUTSIDE the cache, in a
+// dedicated folder (default `emails/` under the working folder,
+// overridable via `sentFolder`). Mirrors the assets plugin's `.md5`
+// sidecars. Keep this folder out of source control and out of the
+// deploy's delete set.
+const DEFAULT_SENT_FOLDER = 'emails'
+
+function sentFolder(config) {
+    const folder = config.sentFolder ?? DEFAULT_SENT_FOLDER
+    return path.isAbsolute(folder)
+        ? folder
+        : path.join(runtime.options.workingFolder, folder)
+}
+
+function markerFile(config, id) {
+    return path.join(sentFolder(config), markerName(id))
+}
+
+// Has this exact content (at/above the current revision) already been
+// delivered for this id? Disk is the source of truth — it survives the
+// cache-wipe that the DB does not.
+async function alreadySent(config, id, hash) {
+    const file = markerFile(config, id)
+    if (!existsSync(file)) return false
+    try {
+        return isDelivered(await readFile(file, 'utf8'), config.revision ?? 1, hash)
+    } catch {
+        return false
+    }
+}
+
+async function recordSent(config, id, hash) {
+    const file = markerFile(config, id)
+    await mkdir(path.dirname(file), { recursive: true })
+    await writeFile(file, formatMarker(config.revision ?? 1, hash))
+}
+
 // ---------- queue ops ------------------------------------------------
 
-function upsertQueueRow({ id, emlPath, sendAt }) {
+function upsertQueueRow({ id, emlPath, emlHash, sendAt }) {
     useDatabase().handle.prepare(`
-        INSERT INTO mikser_post_email_queue (id, eml_path, send_at)
-        VALUES (?, ?, ?)
+        INSERT INTO mikser_post_email_queue (id, eml_path, eml_hash, send_at)
+        VALUES (?, ?, ?, ?)
         ON CONFLICT(id) DO UPDATE SET
             send_at    = excluded.send_at,
             eml_path   = excluded.eml_path,
+            eml_hash   = excluded.eml_hash,
             sent_at    = NULL,
             expired_at = NULL,
             attempts   = 0,
             last_error = NULL
-    `).run(id, emlPath, sendAt)
+    `).run(id, emlPath, emlHash, sendAt)
 }
 
 function recordExpiredInBand({ id, emlPath, sendAt, reason }) {
@@ -120,7 +170,7 @@ async function drain({ config, logger }) {
     `).run(now - retentionMs, now - retentionMs)
 
     const due = db.handle.prepare(`
-        SELECT id, eml_path, send_at FROM mikser_post_email_queue
+        SELECT id, eml_path, eml_hash, send_at FROM mikser_post_email_queue
         WHERE sent_at IS NULL AND expired_at IS NULL AND send_at <= ?
         ORDER BY send_at
     `).all(now)
@@ -139,6 +189,15 @@ async function drain({ config, logger }) {
             continue
         }
 
+        // Durable send-once guard: an on-disk marker means this exact
+        // content was already delivered (survives the cache-wipe that
+        // reset the row's sent_at). Mark sent and skip re-delivery.
+        if (row.eml_hash && await alreadySent(config, row.id, row.eml_hash)) {
+            markSent(row.id)
+            logger.info('postEmail: %s already delivered, skipping', row.id)
+            continue
+        }
+
         try {
             const emlAbs = path.isAbsolute(row.eml_path)
                 ? row.eml_path
@@ -148,6 +207,7 @@ async function drain({ config, logger }) {
                 logger.info('postEmail: [dryRun] would deliver %s', row.id)
             } else {
                 await transport.sendMail({ raw })
+                if (row.eml_hash) await recordSent(config, row.id, row.eml_hash)
             }
             markSent(row.id)
             logger.info('postEmail: delivered %s', row.id)
@@ -188,23 +248,37 @@ export async function postprocess({ entity, options, config, logger }) {
     const eml = await composeEml({ from, to, cc, bcc, subject, html })
     await writeFile(outputPath, eml)
 
+    // Send-once identity for this delivery (semantic fields, not the .eml
+    // bytes — those carry a fresh Message-ID/Date every compose).
+    const hash = deliveryHash({ from, to, cc, bcc, subject, html })
+
+    // Already delivered this exact content? Skip delivery — whatever the
+    // timing. The .eml audit file above is still refreshed; only the send
+    // is suppressed. This is what stops a rebuild (e.g. after a
+    // config-change cache-wipe) from re-firing the whole submission backlog.
+    if (await alreadySent(config, entity.id, hash)) {
+        logger.info('postEmail: %s already delivered, skipping', entity.id)
+        return { success: true, result: entity.destination }
+    }
+
     const maxDelayMs = parseDuration(entity.meta?.maxDelay ?? config.maxDelay, DEFAULT_MAX_DELAY_MS)
     const timing = decideTiming({ meta: entity.meta ?? {}, maxDelayMs })
 
     if (timing.mode === 'queue') {
-        upsertQueueRow({ id: entity.id, emlPath: entity.destination, sendAt: timing.sendAt })
+        upsertQueueRow({ id: entity.id, emlPath: entity.destination, emlHash: hash, sendAt: timing.sendAt })
         logger.info('postEmail: queued %s for %s', entity.id, new Date(timing.sendAt).toISOString())
     } else if (timing.mode === 'expired') {
         const reason = `overdue by ${humanizeMs(timing.overdueMs)}, past maxDelay ${humanizeMs(maxDelayMs)}`
         recordExpiredInBand({ id: entity.id, emlPath: entity.destination, sendAt: timing.sendAt, reason })
         logger.warn('postEmail: %s expired in-band — %s', entity.id, reason)
     } else {
-        // mode === 'now' — deliver synchronously.
+        // mode === 'now' — deliver synchronously, once.
         try {
             if (config.dryRun) {
                 logger.info('postEmail: [dryRun] would deliver %s', entity.id)
             } else {
                 await transport.sendMail({ from, to, cc, bcc, subject, html })
+                await recordSent(config, entity.id, hash)
             }
             logger.info('postEmail: delivered %s', entity.id)
         } catch (err) {
@@ -225,6 +299,13 @@ export function postEmail(config = {}) {
         const logger = useLogger()
         transport = nodemailer.createTransport(config.transport ?? { jsonTransport: true })
 
+        // Migrate pre-1.1 installs: the queue table predates eml_hash, and
+        // CREATE TABLE IF NOT EXISTS won't add a column to an existing one.
+        try {
+            const db = useDatabase()
+            if (db?.isOpen) db.handle.exec(`ALTER TABLE mikser_post_email_queue ADD COLUMN eml_hash TEXT`)
+        } catch { /* column already present */ }
+
         onFinalized(async () => {
             try {
                 await drain({ config, logger })
@@ -252,22 +333,20 @@ export function postEmail(config = {}) {
         }
     })
 
+    // No `teardown` in the descriptor — deliberately. The engine calls
+    // a postprocessor's teardown in a `finally` at the END OF EVERY
+    // postprocess phase (once per cycle), which is right for plugins
+    // that acquire per-cycle resources in a matching setup() (post-pdf's
+    // Puppeteer browser). This plugin's `transport` + `drainTimer` are
+    // PROCESS-LIFETIME — created once at onLoaded, no setup() to
+    // recreate them — so a per-cycle teardown would null the transport
+    // after the first cycle and every subsequent send would crash on a
+    // null handle. Both resources die cleanly at process exit
+    // (drainTimer is unref'd; the socket closes with the process).
     return {
         name: config.name ?? 'email',
         output,
         options: config,
         postprocess,
-        teardown,
-    }
-}
-
-export async function teardown() {
-    if (drainTimer) {
-        clearInterval(drainTimer)
-        drainTimer = null
-    }
-    if (transport?.close) {
-        try { transport.close() } catch { /* not all transports expose close */ }
     }
-    transport = null
 }

package/lib/pure.js

@@ -1,5 +1,7 @@
 // Pure helpers — no mikser-io, no nodemailer, no sqlite imports.
 // Kept separate so unit tests don't have to load the engine.
+// (node:crypto is a built-in and deterministic, so it stays "pure".)
+import { createHash } from 'node:crypto'
 
 export function parseDuration(value, fallback) {
     if (value == null) return fallback
@@ -89,3 +91,49 @@ export function decideTiming({ meta, maxDelayMs, now = Date.now() }) {
     if (now - ts <= maxDelayMs) return { mode: 'now',     sendAt: ts }
     return                        { mode: 'expired', sendAt: ts, overdueMs: now - ts }
 }
+
+// ---------- send-once ledger (pure parts) ----------------------------
+//
+// A durable on-disk marker lets postEmail skip re-sending an email it
+// already delivered — even after a mikser cache-wipe, which clears the
+// queue table (its rows cascade off mikser_entities). Without this a
+// rebuild re-renders every email document and re-fires it. These are the
+// pure pieces; the fs lives in index.js (see sentFolder handling).
+
+// Stable content hash identifying a delivery. Deliberately NOT the
+// composed .eml bytes: nodemailer stamps a fresh Message-ID and Date on
+// every compose, so hashing the .eml would change on every build and
+// defeat the guard. Hash the semantic fields — same submission ⇒ same
+// hash, a genuinely edited one ⇒ new hash ⇒ resend.
+export function deliveryHash({ from, to, cc, bcc, subject, html }) {
+    const norm = v => Array.isArray(v) ? v.join(',') : (v ?? '')
+    const payload = JSON.stringify({
+        from: norm(from), to: norm(to), cc: norm(cc), bcc: norm(bcc),
+        subject: subject ?? '', html: html ?? '',
+    })
+    return createHash('sha256').update(payload).digest('hex')
+}
+
+// One marker file per delivery identity. Ids carry slashes and other
+// path-hostile characters, so collapse anything non-portable to '_'.
+export function markerName(id) {
+    return `${String(id).replace(/[^A-Za-z0-9._-]/g, '_')}.sent`
+}
+
+// Marker body: "<revision>:<hash>". Bumping config.revision invalidates
+// every marker at once (force-resend), mirroring the assets preset's
+// `revision` export.
+export function formatMarker(revision, hash) {
+    return `${revision}:${hash}`
+}
+
+// "Already delivered this exact content, at or above the current
+// revision?" — the decision a marker body encodes.
+export function isDelivered(markerBody, revision, hash) {
+    if (typeof markerBody !== 'string') return false
+    const idx = markerBody.indexOf(':')
+    if (idx === -1) return false
+    const rev = Number.parseInt(markerBody.slice(0, idx), 10)
+    const stored = markerBody.slice(idx + 1)
+    return Number.isFinite(rev) && rev >= revision && stored === hash
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-post-email",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Email postprocessor for mikser-io — sends rendered output via SMTP and writes .eml audit files. Composes after post-mjml in a chain.",
   "main": "index.js",
   "type": "module",

package/test/unit.test.js

@@ -7,6 +7,7 @@ import {
     parseDuration, humanizeMs,
     resolveSpec, dedupe, resolveAddresses,
     decideTiming,
+    deliveryHash, markerName, formatMarker, isDelivered,
 } from '../lib/pure.js'
 
 describe('parseDuration', () => {
@@ -173,3 +174,53 @@ describe('decideTiming', () => {
         assert.throws(() => decideTiming({ meta: { sendAt: 'soon' }, maxDelayMs: oneHour, now }))
     })
 })
+
+describe('deliveryHash', () => {
+    const base = { from: 'me@x.com', to: 'a@x.com', subject: 'Hi', html: '<p>hi</p>' }
+    it('is deterministic for the same content', () => {
+        assert.equal(deliveryHash(base), deliveryHash({ ...base }))
+    })
+    it('changes when subject or body changes', () => {
+        assert.notEqual(deliveryHash(base), deliveryHash({ ...base, subject: 'Hi!' }))
+        assert.notEqual(deliveryHash(base), deliveryHash({ ...base, html: '<p>bye</p>' }))
+    })
+    it('treats array and joined-string recipients the same', () => {
+        assert.equal(
+            deliveryHash({ ...base, to: ['a@x.com', 'b@x.com'] }),
+            deliveryHash({ ...base, to: 'a@x.com,b@x.com' }),
+        )
+    })
+    it('returns a 64-char hex sha256', () => {
+        assert.match(deliveryHash(base), /^[0-9a-f]{64}$/)
+    })
+})
+
+describe('markerName', () => {
+    it('collapses path-hostile characters to _', () => {
+        assert.equal(markerName('/franchise/123-request'), '_franchise_123-request.sent')
+    })
+    it('keeps portable characters', () => {
+        assert.equal(markerName('a.B_9-x'), 'a.B_9-x.sent')
+    })
+})
+
+describe('formatMarker / isDelivered', () => {
+    const h = 'a'.repeat(64)
+    it('round-trips a delivered marker', () => {
+        assert.equal(isDelivered(formatMarker(1, h), 1, h), true)
+    })
+    it('treats a higher stored revision as delivered', () => {
+        assert.equal(isDelivered(formatMarker(3, h), 2, h), true)
+    })
+    it('rejects a lower stored revision (force-resend on bump)', () => {
+        assert.equal(isDelivered(formatMarker(1, h), 2, h), false)
+    })
+    it('rejects a different hash (content changed)', () => {
+        assert.equal(isDelivered(formatMarker(1, h), 1, 'b'.repeat(64)), false)
+    })
+    it('rejects malformed or missing markers', () => {
+        assert.equal(isDelivered('', 1, h), false)
+        assert.equal(isDelivered('garbage', 1, h), false)
+        assert.equal(isDelivered(undefined, 1, h), false)
+    })
+})