domma-cms 0.17.0 → 0.21.0

package/server/services/blocks.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 BLOCKS_DIR = path.resolve(__dirname, '../../content/blocks');
@@ -257,9 +258,12 @@ export async function listBlocks() {
         const name = file.slice(0, -5);
         const fileStat = await fs.stat(path.join(BLOCKS_DIR, file)).catch(() => null);
         let bundled = false;
+        let meta = null;
         try {
-            const meta = JSON.parse(await fs.readFile(path.join(BLOCKS_DIR, `${name}.meta.json`), 'utf8'));
-            bundled = !!meta.bundled;
+            const m = JSON.parse(await fs.readFile(path.join(BLOCKS_DIR, `${name}.meta.json`), 'utf8'));
+            bundled = !!m.bundled;
+            // Surface the full sidecar so callers can filter by meta.project etc.
+            meta = m;
         } catch { /* no meta file */
         }
         blocks.push({
@@ -267,6 +271,7 @@ export async function listBlocks() {
             size: fileStat?.size ?? 0,
             updatedAt: fileStat?.mtime?.toISOString() ?? null,
             bundled,
+            ...(meta && {meta}),
         });
     }
     return blocks.sort((a, b) => a.name.localeCompare(b.name));
@@ -284,9 +289,12 @@ export async function getBlock(name) {
     try {
         const content = await fs.readFile(blockFilePath(name), 'utf8');
         let bundled = false;
+        let meta = null;
         try {
-            const meta = JSON.parse(await fs.readFile(blockMetaPath(name), 'utf8'));
-            bundled = !!meta.bundled;
+            const metaFile = JSON.parse(await fs.readFile(blockMetaPath(name), 'utf8'));
+            bundled = !!metaFile.bundled;
+            // Preserve the full meta sidecar so callers can read meta.project etc.
+            meta = metaFile;
         } catch { /* no meta file */
         }
         let css = '';
@@ -294,7 +302,7 @@ export async function getBlock(name) {
             css = await fs.readFile(blockCssPath(name), 'utf8');
         } catch { /* no CSS file — treat as empty */
         }
-        return {name, content, css, bundled};
+        return {name, content, css, bundled, ...(meta && {meta})};
     } catch (err) {
         if (err.code === 'ENOENT') {
             const notFound = new Error('Block not found');
@@ -316,7 +324,7 @@ export async function getBlock(name) {
  * @returns {Promise<{success: boolean, name: string}>}
  * @throws {Error} With code INVALID_NAME on bad name, or CSS_TOO_LARGE when CSS exceeds cap
  */
-export async function saveBlock(name, content, {bundled, css} = {}) {
+export async function saveBlock(name, content, {bundled, css, meta} = {}) {
     assertValidName(name);
     if (typeof css === 'string' && css.length > MAX_CSS_SIZE) {
         const err = new Error(`CSS exceeds ${MAX_CSS_SIZE} byte limit`);
@@ -326,8 +334,13 @@ export async function saveBlock(name, content, {bundled, css} = {}) {
     await fs.mkdir(BLOCKS_DIR, {recursive: true});
     await fs.writeFile(blockFilePath(name), content, 'utf8');
     const metaPath = blockMetaPath(name);
-    if (bundled) {
-        await fs.writeFile(metaPath, JSON.stringify({bundled: true}, null, 2) + '\n', 'utf8');
+    // Merge sidecar meta — bundled flag plus any caller-supplied fields (eg meta.project).
+    const sidecar = {
+        ...(meta && typeof meta === 'object' ? meta : {}),
+        ...(bundled ? {bundled: true} : {})
+    };
+    if (Object.keys(sidecar).length > 0) {
+        await fs.writeFile(metaPath, JSON.stringify(sidecar, null, 2) + '\n', 'utf8');
     } else {
         await fs.unlink(metaPath).catch(() => {
         });
@@ -341,6 +354,7 @@ export async function saveBlock(name, content, {bundled, css} = {}) {
             });
         }
     }
+    await cache.invalidateTags([`block:${name}`]);
     return {success: true, name};
 }
 
@@ -368,6 +382,7 @@ export async function deleteBlock(name) {
     });
     await fs.unlink(blockMetaPath(name)).catch(() => {
     });
+    await cache.invalidateTags([`block:${name}`]);
 }
 
 // ---------------------------------------------------------------------------

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();
+    }
+}