domma-cms 1.6.59 → 1.7.0

package/docs/cache.md

@@ -0,0 +1,96 @@
+# Caching
+
+Domma CMS caches assembled public page responses so the markdown → shortcode → template pipeline runs only once per (url, file version, viewer roles, origin) until something it depends on changes. The cache is on by default in production (`NODE_ENV=production`) and off in development.
+
+## Config
+
+`config/cache.json` (optional - absent means use defaults baked into the loader):
+
+```json
+{
+  "enabled": true,
+  "driver": "memory",
+  "memory": { "maxItems": 1000, "defaultTtlSeconds": 3600 },
+  "redis": { "url": "redis://localhost:6379", "keyPrefix": "domma:" }
+}
+```
+
+- `enabled: false` short-circuits every read straight to the producer. Use in development to see fresh renders on every refresh.
+- `driver`:
+  - `"memory"` - default, in-process LRU with TTL and a tag index. Zero dependencies.
+  - `"none"` - same as `enabled: false` but expressed via the driver name.
+  - `"redis"` - optional, requires the `redis` package (in `optionalDependencies` - Pro feature). Loaded dynamically so the free tier never imports it.
+
+A template lives at `config/cache.json.example`.
+
+## What gets cached
+
+The full rendered HTML for each public page response, keyed by:
+
+```
+page:<urlPath>:m<fileMtime>:role<roles>:o<origin>
+```
+
+- `m<fileMtime>` - the page file's modification time, so any change to the file (editor save, script, `git pull`) produces a fresh entry even if no invalidation fired. Stale entries age out via TTL/LRU.
+- `role<roles>` - the sorted set of **all** the viewer's roles (primary plus additional), joined with `+` - e.g. `roleadmin+blog-editor`. Anonymous visitors get `roleanon` and share one entry.
+- `o<origin>` - the site origin (from `site.baseUrl` or the request), so a multi-domain deployment keeps separate entries per host.
+
+For example: `page:/about:m1727430000000:roleanon:ohttps://example.com`.
+
+Admin API responses, login pages and error pages are not cached. Drafts (including draft previews) are never cached, and a page containing a row-level `[view]` is rendered fresh for each signed-in viewer.
+
+Cache keys are versioned with a `v1:` prefix. Bumping the version (in `server/services/cache/index.js`) auto-invalidates the entire cache without needing `clear()` - useful if the cached value shape ever changes.
+
+## What invalidates
+
+Tag-based. When an admin saves a page, only entries tagged `page:<that-url>` are flushed - not the whole cache. The full tag set:
+
+| Tag                  | Set by                                                | Flushed by                                            |
+|----------------------|-------------------------------------------------------|-------------------------------------------------------|
+| `page:<urlPath>`     | the public route, on every cached entry              | `content.js`: createPage / updatePage / renamePage / deletePage |
+| `collection:<slug>`  | the `[collection]` shortcode processor                | `collections.js`: createCollection, updateCollection, deleteCollection, createEntry, updateEntry, deleteEntry, clearEntries, importEntries |
+| `form:<slug>`        | the `[form]` shortcode processor                      | `forms.js`: writeForm, deleteForm                    |
+| `block:<name>`       | the `[block]` shortcode processor                     | `blocks.js`: saveBlock, deleteBlock                  |
+| `view:<slug>`        | the `[view]` shortcode processor                      | `views.js`: createView, updateView, deleteView       |
+| `nav`                | the public route, on every cached entry              | `routes/api/navigation.js`: PUT /api/navigation; menu create/update/delete (`routes/api/menus.js`, `services/menus.js`); menu-location changes |
+| `site`               | the public route, on every cached entry              | `routes/api/settings.js`: PUT /api/settings and PUT /api/settings/custom-css; theme settings changes (`themeSettings.js`); context-menu changes (`contextMenus.js`); menu changes; SEO settings |
+| `sitemap`            | `/sitemap.xml` (10-minute TTL)                        | `content.js`: createPage / updatePage / renamePage / deletePage; SEO sitemap sources (`sitemapChanged`) |
+
+The markdown pipeline auto-attaches the appropriate shortcode tags as it processes a page - embedding `[collection slug="faq"]` causes the rendered page to be tagged `collection:faq`, so a FAQ entry edit transparently busts every page that displays the FAQ. There is no central embed-map to maintain.
+
+## Manual flush, inspection, and on/off
+
+| Endpoint                 | Behaviour                                                                 |
+|--------------------------|---------------------------------------------------------------------------|
+| `GET  /api/cache/status` | Full stats: `enabled`, `driver`, `size`, `maxItems`, `hits`, `misses`, `writes`, `invalidations`, `hitRate`, `lastClearedAt`, `lastInvalidationAt`, `initialisedAt` |
+| `GET  /api/cache/keys`   | `{entries: [{key, tags, expiresAt}]}` - keys only, no values (they can be MB of HTML) |
+| `POST /api/cache/clear`  | Flush every cached entry. Returns updated stats. |
+| `POST /api/cache/toggle` | `{enabled: boolean}` - flip on/off **and persist to `config/cache.json`** so the choice survives a restart. Returns updated stats. |
+
+All endpoints require an admin Bearer token. The dashboard has a cache widget showing the same data plus an on/off switch; the Settings → Cache tab includes a viewer that lists every cached key with its tags.
+
+When you toggle the cache **off**, the in-memory data is preserved - toggle back on and your warm entries are still there. When you turn it **off in `config/cache.json`** and restart, the next boot starts with a `NoneDriver` and no data.
+
+## Thundering-herd safety
+
+If three concurrent requests hit a cold key, the producer runs exactly once - the other two await the first's result via an in-flight promise map. This matters for popular pages on cache cold-start: without coalescing, N parallel requests trigger N parallel renders, each writing the same value back to the cache.
+
+## Adding a new shortcode that needs invalidation
+
+1. In the shortcode's processor (`server/services/markdown.js`), accept a `tagSet` argument and call `tagSet?.add('<prefix>:' + attrs.slug)` when you process each occurrence.
+2. Add a corresponding call in `parseMarkdown`'s pipeline to forward the `tagSet` you already create.
+3. In the service that owns the data, import `* as cache from './cache/index.js'` and add `await cache.invalidateTags(['<prefix>:' + id])` after every successful write/delete.
+
+That's it - no central registry to update. The tag flows from producer to cache to invalidator without any glue code.
+
+## Verification
+
+Cold/warm performance gap:
+
+```
+NODE_ENV=production node server/server.js   # in one terminal
+curl -s -o /dev/null -w "Cold: %{time_total}s\n" http://localhost:4096/
+curl -s -o /dev/null -w "Warm: %{time_total}s\n" http://localhost:4096/
+```
+
+Warm should be meaningfully faster (typically 20-50ms cold vs sub-millisecond warm for a non-trivial page).