domma-cms 0.16.0 → 0.18.0

package/server/services/cache/drivers/MemoryDriver.js

@@ -0,0 +1,118 @@
+import {LRU} from '../lru.js';
+
+/**
+ * In-memory cache driver with TTL and tag invalidation.
+ *
+ * Each entry is stored as {value, expiresAt, tags}. TTL is lazy — entries
+ * past their expiresAt are returned as undefined on the next get and dropped.
+ *
+ * Tag index: a Map<tag, Set<key>>. set() with {tags} adds the key to each
+ * tag's set; invalidateTags() iterates the listed tags and deletes every
+ * key in their sets. The forward index (entry.tags) lets us clean up old
+ * links when a key is re-set with a different tag list.
+ */
+export class MemoryDriver {
+    /**
+     * @param {{maxItems?: number, defaultTtlSeconds?: number}} options
+     */
+    constructor(options = {}) {
+        const maxItems = options.maxItems ?? 1000;
+        this._defaultTtlSeconds = options.defaultTtlSeconds ?? null;
+        this._lru = new LRU(maxItems);
+        /** @type {Map<string, Set<string>>} */
+        this._tagIndex = new Map();
+        this._now = () => Date.now();
+    }
+
+    async get(key) {
+        const entry = this._lru.get(key);
+        if (!entry) return undefined;
+        if (entry.expiresAt !== null && entry.expiresAt <= this._now()) {
+            this._removeKey(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+
+    async set(key, value, opts = {}) {
+        const existing = this._lru.get(key);
+        if (existing && existing.tags) {
+            for (const t of existing.tags) {
+                const set = this._tagIndex.get(t);
+                if (set) {
+                    set.delete(key);
+                    if (set.size === 0) this._tagIndex.delete(t);
+                }
+            }
+        }
+
+        const ttl = opts.ttlSeconds ?? this._defaultTtlSeconds;
+        const expiresAt = ttl ? this._now() + ttl * 1000 : null;
+        const tags = opts.tags && opts.tags.length ? [...opts.tags] : null;
+
+        this._lru.set(key, {value, expiresAt, tags});
+
+        if (tags) {
+            for (const t of tags) {
+                let set = this._tagIndex.get(t);
+                if (!set) {
+                    set = new Set();
+                    this._tagIndex.set(t, set);
+                }
+                set.add(key);
+            }
+        }
+    }
+
+    async invalidateTags(tags) {
+        for (const t of tags) {
+            const set = this._tagIndex.get(t);
+            if (!set) continue;
+            for (const key of [...set]) {
+                this._removeKey(key);
+            }
+        }
+    }
+
+    async clear() {
+        this._lru.clear();
+        this._tagIndex.clear();
+    }
+
+    /** Current entry count (sync — for the dashboard widget). */
+    size() {
+        return this._lru.size;
+    }
+
+    /**
+     * Snapshot the currently cached entries as `{key, tags, expiresAt}`.
+     * No values — they can be megabytes of HTML. Uses `entries()` (non-mutating)
+     * so the LRU order is preserved through the iteration.
+     */
+    listEntries() {
+        const out = [];
+        for (const [key, entry] of this._lru.entries()) {
+            if (!entry) continue;
+            out.push({
+                key,
+                tags: entry.tags ? [...entry.tags] : [],
+                expiresAt: entry.expiresAt
+            });
+        }
+        return out;
+    }
+
+    _removeKey(key) {
+        const entry = this._lru.get(key);
+        if (entry && entry.tags) {
+            for (const t of entry.tags) {
+                const set = this._tagIndex.get(t);
+                if (set) {
+                    set.delete(key);
+                    if (set.size === 0) this._tagIndex.delete(t);
+                }
+            }
+        }
+        this._lru.delete(key);
+    }
+}

package/server/services/cache/drivers/NoneDriver.js

@@ -0,0 +1,12 @@
+/**
+ * Null driver — used when the cache is disabled.
+ * Every read misses; every write is dropped on the floor.
+ */
+export class NoneDriver {
+    async get()              { return undefined; }
+    async set()              { /* no-op */ }
+    async invalidateTags()   { /* no-op */ }
+    async clear()            { /* no-op */ }
+    size()                   { return 0; }
+    listEntries()            { return []; }
+}

package/server/services/cache/index.js

@@ -0,0 +1,229 @@
+import {MemoryDriver} from './drivers/MemoryDriver.js';
+import {NoneDriver} from './drivers/NoneDriver.js';
+
+const KEY_VERSION = 'v1:';
+
+let _driver = new NoneDriver();
+let _enabled = false;
+let _lastConfig = null;
+/** @type {Map<string, Promise<*>>} */
+const _inflight = new Map();
+
+const _stats = {
+    hits: 0,
+    misses: 0,
+    writes: 0,
+    invalidations: 0,
+    lastClearedAt: null,
+    lastInvalidationAt: null,
+    initialisedAt: null
+};
+
+/**
+ * @param {{
+ *   enabled?: boolean,
+ *   driver?: 'memory' | 'none' | 'redis',
+ *   memory?: {maxItems?: number, defaultTtlSeconds?: number},
+ *   redis?: {url: string, keyPrefix?: string}
+ * }} config
+ */
+export async function initCache(config = {}) {
+    _lastConfig = {...config};
+    _stats.initialisedAt = new Date().toISOString();
+    if (config.enabled === false) {
+        _driver = new NoneDriver();
+        _enabled = false;
+        return;
+    }
+    const name = config.driver ?? 'memory';
+    if (name === 'memory') {
+        _driver = new MemoryDriver(config.memory ?? {});
+        _enabled = true;
+        return;
+    }
+    if (name === 'none') {
+        _driver = new NoneDriver();
+        _enabled = false;
+        return;
+    }
+    if (name === 'redis') {
+        const {RedisDriver} = await import('./drivers/RedisDriver.js');
+        _driver = new RedisDriver(config.redis ?? {});
+        await _driver.connect();
+        _enabled = true;
+        return;
+    }
+    throw new Error(`Unknown cache driver: ${name}`);
+}
+
+/**
+ * Flip the cache on or off at runtime.
+ *
+ * When turning on, re-initialise with the last config (or sensible defaults)
+ * so a previously disabled cache gets a real driver. When turning off, keep
+ * the driver in place but short-circuit reads/writes — preserves cached data
+ * if the user toggles back on. The persistence of this choice across restarts
+ * is the caller's responsibility (the route handler writes to config/cache.json).
+ */
+export async function setEnabled(enabled) {
+    if (Boolean(enabled) === _enabled) return;
+    if (enabled) {
+        if (_driver instanceof NoneDriver) {
+            // No usable driver yet — bootstrap one from last-known config.
+            const cfg = {...(_lastConfig || {}), enabled: true};
+            if (!cfg.driver || cfg.driver === 'none') cfg.driver = 'memory';
+            await initCache(cfg);
+        } else {
+            // Memory/Redis driver still live — flip the flag and preserve data.
+            _enabled = true;
+        }
+    } else {
+        _enabled = false;
+        _inflight.clear();
+    }
+}
+
+export function isEnabled() {
+    return _enabled;
+}
+
+export async function get(key) {
+    return _driver.get(_vk(key));
+}
+
+export async function set(key, value, opts = {}) {
+    return _driver.set(_vk(key), value, opts);
+}
+
+export async function invalidateTags(tags) {
+    if (!Array.isArray(tags) || tags.length === 0) return;
+    _stats.invalidations++;
+    _stats.lastInvalidationAt = new Date().toISOString();
+    return _driver.invalidateTags(tags);
+}
+
+export async function clear() {
+    _inflight.clear();
+    _stats.lastClearedAt = new Date().toISOString();
+    return _driver.clear();
+}
+
+/**
+ * List the cache's keys with their tags and expiry. Values are deliberately
+ * excluded — cached entries can be megabytes of HTML.
+ * @returns {{key: string, tags: string[], expiresAt: number|null}[]}
+ */
+export function listEntries() {
+    if (typeof _driver.listEntries !== 'function') return [];
+    return _driver.listEntries().map(e => ({
+        ...e,
+        // Strip the internal v1: version prefix for display.
+        key: e.key.startsWith(KEY_VERSION) ? e.key.slice(KEY_VERSION.length) : e.key
+    }));
+}
+
+/**
+ * Snapshot of cache health for the dashboard widget.
+ * Counts are process-lifetime; restart resets them.
+ */
+export function getStats() {
+    const total = _stats.hits + _stats.misses;
+    return {
+        enabled: _enabled,
+        driver: _enabled ? (_lastConfig?.driver || 'memory') : 'disabled',
+        size: typeof _driver.size === 'function' ? _driver.size() : null,
+        maxItems: _lastConfig?.memory?.maxItems ?? null,
+        hits: _stats.hits,
+        misses: _stats.misses,
+        writes: _stats.writes,
+        invalidations: _stats.invalidations,
+        hitRate: total > 0 ? _stats.hits / total : null,
+        lastClearedAt: _stats.lastClearedAt,
+        lastInvalidationAt: _stats.lastInvalidationAt,
+        initialisedAt: _stats.initialisedAt
+    };
+}
+
+/**
+ * Get-or-set with in-flight coalescing.
+ *
+ * Producer may return either a raw value, or an object with a `_cacheTags`
+ * array — those tags are merged into opts.tags before storing, and the
+ * `_cacheTags` field is stripped from both the cached and returned value.
+ * This lets producers report tags discovered during rendering (e.g. the
+ * markdown pipeline noting embedded collection slugs) without the caller
+ * needing to know them up front.
+ *
+ * @param {string} key
+ * @param {() => Promise<*>} producer
+ * @param {{ttlSeconds?: number, tags?: string[]}} [opts]
+ */
+export async function wrap(key, producer, opts = {}) {
+    if (!_enabled) {
+        const raw = await producer();
+        return _stripCacheTags(raw);
+    }
+
+    const vkey = _vk(key);
+    const hit = await _driver.get(vkey);
+    if (hit !== undefined) {
+        _stats.hits++;
+        return hit;
+    }
+
+    if (_inflight.has(vkey)) return _inflight.get(vkey);
+
+    _stats.misses++;
+    const promise = (async () => {
+        try {
+            const raw = await producer();
+            const {value, extraTags} = _extractCacheTags(raw);
+            const setOpts = {...opts};
+            if (extraTags) {
+                setOpts.tags = [...(opts.tags ?? []), ...extraTags];
+            }
+            await _driver.set(vkey, value, setOpts);
+            _stats.writes++;
+            return value;
+        } finally {
+            _inflight.delete(vkey);
+        }
+    })();
+
+    _inflight.set(vkey, promise);
+    return promise;
+}
+
+function _vk(key) {
+    return KEY_VERSION + key;
+}
+
+function _extractCacheTags(raw) {
+    if (raw && typeof raw === 'object' && Array.isArray(raw._cacheTags)) {
+        const {_cacheTags, ...value} = raw;
+        return {value, extraTags: _cacheTags};
+    }
+    return {value: raw, extraTags: null};
+}
+
+function _stripCacheTags(raw) {
+    if (raw && typeof raw === 'object' && Array.isArray(raw._cacheTags)) {
+        const {_cacheTags, ...value} = raw;
+        return value;
+    }
+    return raw;
+}
+
+export function _resetForTests() {
+    _driver = new NoneDriver();
+    _enabled = false;
+    _lastConfig = null;
+    _inflight.clear();
+    _stats.hits = 0;
+    _stats.misses = 0;
+    _stats.writes = 0;
+    _stats.invalidations = 0;
+    _stats.lastClearedAt = null;
+    _stats.lastInvalidationAt = null;
+    _stats.initialisedAt = null;
+}

package/server/services/cache/lru.js

@@ -0,0 +1,61 @@
+/**
+ * Bounded LRU built on the insertion-order property of Map.
+ * On hit, delete + re-set the entry so it becomes the most-recent.
+ * On set when at capacity, delete the first (oldest) key.
+ */
+export class LRU {
+    /**
+     * @param {number} maxItems
+     */
+    constructor(maxItems) {
+        if (!Number.isInteger(maxItems) || maxItems < 1) {
+            throw new TypeError('LRU: maxItems must be a positive integer');
+        }
+        this._max = maxItems;
+        this._map = new Map();
+    }
+
+    get size() {
+        return this._map.size;
+    }
+
+    get(key) {
+        if (!this._map.has(key)) return undefined;
+        const value = this._map.get(key);
+        this._map.delete(key);
+        this._map.set(key, value);
+        return value;
+    }
+
+    /** Read without promoting. Use for snapshots / iteration. */
+    peek(key) {
+        return this._map.get(key);
+    }
+
+    /** Iterate `[key, value]` pairs in oldest-to-newest order, no mutation. */
+    entries() {
+        return this._map.entries();
+    }
+
+    set(key, value) {
+        if (this._map.has(key)) {
+            this._map.delete(key);
+        } else if (this._map.size >= this._max) {
+            const oldest = this._map.keys().next().value;
+            this._map.delete(oldest);
+        }
+        this._map.set(key, value);
+    }
+
+    delete(key) {
+        return this._map.delete(key);
+    }
+
+    clear() {
+        this._map.clear();
+    }
+
+    keys() {
+        return this._map.keys();
+    }
+}

package/server/services/collections.js

@@ -11,6 +11,7 @@ import path from 'path';
 import {v4 as uuidv4} from 'uuid';
 import {config} from '../config.js';
 import {getAdapter, invalidate} from './adapterRegistry.js';
+import * as cache from './cache/index.js';
 
 const COLLECTIONS_DIR = path.resolve(config.content.collectionsDir);
 
@@ -149,6 +150,7 @@ export async function createCollection({title, slug, description = '', fields =
 
     await writeSchema(schema);
     await (await getAdapter(finalSlug)).insertMany(finalSlug, []);
+    await cache.invalidateTags([`collection:${finalSlug}`]);
     return schema;
 }
 
@@ -191,6 +193,7 @@ export async function updateCollection(slug, updates) {
 
     // Invalidate cached adapter in case storage config changed.
     invalidate(slug);
+    await cache.invalidateTags([`collection:${slug}`]);
 
     return updated;
 }
@@ -218,6 +221,7 @@ export async function deleteCollection(slug) {
 
     invalidate(slug);
     await fs.rm(collectionDir(slug), { recursive: true, force: true });
+    await cache.invalidateTags([`collection:${slug}`]);
 }
 
 // ---------------------------------------------------------------------------
@@ -304,7 +308,9 @@ export async function createEntry(slug, data, { createdBy = null, source = 'admi
     };
 
     const adapter = await getAdapter(slug);
-    return adapter.insert(slug, entry);
+    const created = await adapter.insert(slug, entry);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return created;
 }
 
 /**
@@ -333,7 +339,9 @@ export async function updateEntry(slug, entryId, data) {
         meta: { ...existing.meta, updatedAt: new Date().toISOString() }
     };
 
-    return adapter.update(slug, entryId, updated);
+    const result = await adapter.update(slug, entryId, updated);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 /**
@@ -346,7 +354,9 @@ export async function updateEntry(slug, entryId, data) {
  */
 export async function deleteEntry(slug, entryId) {
     const adapter = await getAdapter(slug);
-    return adapter.remove(slug, entryId);
+    const result = await adapter.remove(slug, entryId);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 /**
@@ -359,7 +369,9 @@ export async function clearEntries(slug) {
     const schema = await getCollection(slug);
     if (!schema) throw new Error(`Collection "${slug}" not found`);
     const adapter = await getAdapter(slug);
-    return adapter.clear(slug);
+    const result = await adapter.clear(slug);
+    await cache.invalidateTags([`collection:${slug}`]);
+    return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -433,6 +445,7 @@ export async function importEntries(slug, incoming, { createdBy = null } = {}) {
     const adapter = await getAdapter(slug);
     if (valid.length > 0) {
         await adapter.insertMany(slug, valid);
+        await cache.invalidateTags([`collection:${slug}`]);
     }
 
     return { imported: valid.length, skipped, errors };

package/server/services/content.js

@@ -9,6 +9,7 @@ import {parseMarkdown, serialiseMarkdown} from './markdown.js';
 import {config} from '../config.js';
 import {hooks} from './hooks.js';
 import {createVersion, deleteAllVersions, renameVersionDir} from './versions.js';
+import * as cache from './cache/index.js';
 
 const CONTENT_DIR = config.content.contentDir;
 const PAGES_DIR = path.join(CONTENT_DIR, 'pages');
@@ -77,6 +78,7 @@ export async function createPage(urlPath, frontmatter, body) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body || ''), 'utf8');
     const page = await readPageFile(filePath);
+    await cache.invalidateTags([`page:${urlPath}`]);
     hooks.emit('content:pageCreated', {page, urlPath});
     return page;
 }
@@ -111,6 +113,7 @@ export async function updatePage(urlPath, frontmatter, body, {author} = {}) {
 
     await fs.writeFile(filePath, serialiseMarkdown(meta, body ?? existingContent), 'utf8');
     const page = await readPageFile(filePath);
+    await cache.invalidateTags([`page:${urlPath}`]);
     hooks.emit('content:pageUpdated', {page, urlPath});
     return page;
 }
@@ -128,6 +131,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
     const newFile = urlPathToFilePath(newUrlPath);
     await fs.mkdir(path.dirname(newFile), { recursive: true });
     await fs.rename(oldFile, newFile);
+    await cache.invalidateTags([`page:${oldUrlPath}`, `page:${newUrlPath}`]);
     try {
         await renameVersionDir(oldUrlPath, newUrlPath);
     } catch {
@@ -144,6 +148,7 @@ export async function renamePage(oldUrlPath, newUrlPath) {
 export async function deletePage(urlPath) {
     const filePath = await resolveExistingFilePath(urlPath);
     await fs.unlink(filePath);
+    await cache.invalidateTags([`page:${urlPath}`]);
     hooks.emit('content:pageDeleted', {urlPath});
     try {
         await deleteAllVersions(urlPath);
@@ -288,9 +293,9 @@ async function collectMdFiles(dir) {
  */
 async function readPageFile(filePath) {
     const raw = await fs.readFile(filePath, 'utf8');
-    const { data, content, html, usedComponents } = await parseMarkdown(raw);
+    const { data, content, html, usedComponents, tags } = await parseMarkdown(raw);
     const urlPath = filePathToUrlPath(filePath);
-    return { ...data, urlPath, content, html, usedComponents };
+    return { ...data, urlPath, content, html, usedComponents, tags };
 }
 
 /**

package/server/services/email.js

@@ -4,6 +4,32 @@
  */
 import nodemailer from 'nodemailer';
 
+let lastSendResult = null;
+
+/**
+ * Return the most recent email send result, or null if no send has occurred.
+ *
+ * @returns {{ ok: boolean, at: string, info: string|null } | null}
+ */
+export function getLastSendResult() {
+    return lastSendResult;
+}
+
+/**
+ * Record the outcome of an email send for health reporting.
+ *
+ * @param {boolean} ok
+ * @param {string|null} info
+ * @returns {void}
+ */
+function recordSendResult(ok, info) {
+    lastSendResult = {
+        ok,
+        at: new Date().toISOString(),
+        info: info || null
+    };
+}
+
 /**
  * Escape HTML special characters for safe use in email bodies.
  *
@@ -58,17 +84,24 @@ export async function createTransport(smtp) {
  * @throws {Error} If sending the email fails.
  */
 export async function sendEmail(transport, {from, fromName, to, subject, html, text}) {
-    const info = await transport.sendMail({
-        from: `"${fromName}" <${from}>`,
-        to,
-        subject,
-        text,
-        html
-    });
+    try {
+        const info = await transport.sendMail({
+            from: `"${fromName}" <${from}>`,
+            to,
+            subject,
+            text,
+            html
+        });
+        recordSendResult(true, info.messageId);
 
-    const previewUrl = nodemailer.getTestMessageUrl(info);
-    if (previewUrl) {
-        console.log('[email] Preview URL:', previewUrl);
+        const previewUrl = nodemailer.getTestMessageUrl(info);
+        if (previewUrl) {
+            console.log('[email] Preview URL:', previewUrl);
+        }
+        return info;
+    } catch (err) {
+        recordSendResult(false, err.message);
+        throw err;
     }
 }
 
@@ -112,16 +145,23 @@ export async function sendFormEmail(transport, { from, fromName, to, subject, fo
 
     const text = `New form submission: ${formTitle}\n\n${plainRows}`;
 
-    const info = await transport.sendMail({
-        from: `"${fromName}" <${from}>`,
-        to,
-        subject,
-        text,
-        html
-    });
+    try {
+        const info = await transport.sendMail({
+            from: `"${fromName}" <${from}>`,
+            to,
+            subject,
+            text,
+            html
+        });
+        recordSendResult(true, info.messageId);
 
-    const previewUrl = nodemailer.getTestMessageUrl(info);
-    if (previewUrl) {
-        console.log('[email] Preview URL:', previewUrl);
+        const previewUrl = nodemailer.getTestMessageUrl(info);
+        if (previewUrl) {
+            console.log('[email] Preview URL:', previewUrl);
+        }
+        return info;
+    } catch (err) {
+        recordSendResult(false, err.message);
+        throw err;
     }
 }

package/server/services/forms.js

@@ -6,6 +6,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import {fileURLToPath} from 'url';
+import * as cache from './cache/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT      = path.resolve(__dirname, '..', '..');
@@ -43,6 +44,7 @@ export async function writeForm(slug, data) {
     await ensureFormsDir();
     const file = path.join(FORMS_DIR, `${slug}.json`);
     await fs.writeFile(file, JSON.stringify(data, null, 4) + '\n', 'utf8');
+    await cache.invalidateTags([`form:${slug}`]);
 }
 
 /**
@@ -78,6 +80,7 @@ export async function listForms() {
  */
 export async function deleteForm(slug) {
     await fs.unlink(path.join(FORMS_DIR, `${slug}.json`));
+    await cache.invalidateTags([`form:${slug}`]);
 }
 
 /**