CACHING switch

Author: thehabes

cache/docs/CACHE_METRICS_REPORT.md

@@ -1,14 +1,14 @@
 # RERUM Cache Metrics & Functionality Report
 
-**Generated**: Fri Oct 24 16:38:52 CDT 2025  
+**Generated**: Mon Oct 27 18:50:18 UTC 2025  
 **Test Duration**: Full integration and performance suite  
 **Server**: http://localhost:3001
 
 ---
 
 ## Executive Summary
 
-**Overall Test Results**: 32 passed, 1 failed, 0 skipped (33 total)
+**Overall Test Results**: 37 passed, 0 failed, 0 skipped (37 total)
 
 ### Cache Performance Summary
 
@@ -33,7 +33,7 @@
 | `/history` | ✅ Functional | Get object version history |
 | `/since` | ✅ Functional | Get objects modified since timestamp |
 | `/create` | ✅ Functional | Create new objects |
-| `/update` | ⚠️  Partial Failures (1/50) | Update existing objects |
+| `/update` | ✅ Functional | Update existing objects |
 | `/patch` | ✅ Functional | Patch existing object properties |
 | `/set` | ✅ Functional | Add new properties to objects |
 | `/unset` | ✅ Functional | Remove properties from objects |
@@ -48,12 +48,12 @@
 
 | Endpoint | Cold Cache (DB) | Warm Cache (Memory) | Speedup | Benefit |
 |----------|-----------------|---------------------|---------|---------|
-| `/query` | 421 | N/A | N/A | N/A |
-| `/search` | 341 | N/A | N/A | N/A |
-| `/searchPhrase` | 62 | N/A | N/A | N/A |
-| `/id` | 502 | N/A | N/A | N/A |
-| `/history` | 867 | N/A | N/A | N/A |
-| `/since` | 858 | N/A | N/A | N/A |
+| `/query` | 348 | N/A | N/A | N/A |
+| `/search` | 104 | N/A | N/A | N/A |
+| `/searchPhrase` | 25 | N/A | N/A | N/A |
+| `/id` | 412 | N/A | N/A | N/A |
+| `/history` | 728 | N/A | N/A | N/A |
+| `/since` | 873 | N/A | N/A | N/A |
 
 **Interpretation**:
 - **Cold Cache**: First request hits database (cache miss)
@@ -69,13 +69,13 @@
 
 | Endpoint | Empty Cache | Full Cache (1000 entries) | Overhead | Impact |
 |----------|-------------|---------------------------|----------|--------|
-| `/create` | 251ms | 59ms | -192ms | ✅ None |
-| `/update` | N/A | N/A | N/A | N/A |
-| `/patch` | 668ms | 493ms | -175ms | ✅ None |
-| `/set` | 491ms | 478ms | -13ms | ✅ None |
-| `/unset` | 680ms | 498ms | -182ms | ✅ None |
-| `/delete` | 493ms | 473ms | -20ms | ✅ None |
-| `/overwrite` | 490ms | 680ms | +190ms | ⚠️  Moderate |
+| `/create` | 23ms | 23ms | +0ms | ✅ Negligible |
+| `/update` | 421ms | 437ms | +16ms | ⚠️  Moderate |
+| `/patch` | 420ms | 424ms | +4ms | ✅ Negligible |
+| `/set` | 431ms | 424ms | -7ms | ✅ None |
+| `/unset` | 423ms | 423ms | +0ms | ✅ Negligible |
+| `/delete` | 441ms | 460ms | +19ms | ⚠️  Moderate |
+| `/overwrite` | 422ms | 421ms | -1ms | ✅ None |
 
 **Interpretation**:
 - **Empty Cache**: Write with no cache to invalidate
@@ -97,9 +97,9 @@
 - Net benefit on 1000 reads: ~0ms saved (assuming 70% hit rate)
 
 **Cache Costs (Writes)**:
-- Average overhead per write: ~-65ms
-- Overhead percentage: ~-12%
-- Net cost on 1000 writes: ~-65000ms
+- Average overhead per write: ~4ms
+- Overhead percentage: ~1%
+- Net cost on 1000 writes: ~4000ms
 - Tested endpoints: create, update, patch, set, unset, delete, overwrite
 
 **Break-Even Analysis**:
@@ -111,17 +111,17 @@ For a workload with:
 
 ```
 Without Cache:
-  800 reads × 421ms = 336800ms
-  200 writes × 251ms = 50200ms
-  Total: 387000ms
+  800 reads × 348ms = 278400ms
+  200 writes × 23ms = 4600ms
+  Total: 283000ms
 
 With Cache:
   560 cached reads × 5ms = 2800ms
-  240 uncached reads × 421ms = 101040ms
-  200 writes × 59ms = 11800ms
-  Total: 115640ms
+  240 uncached reads × 348ms = 83520ms
+  200 writes × 23ms = 4600ms
+  Total: 90920ms
 
-Net Improvement: 271360ms faster (~71% improvement)
+Net Improvement: 192080ms faster (~68% improvement)
 ```
 
 ---
@@ -132,8 +132,8 @@ Net Improvement: 271360ms faster (~71% improvement)
 
 The cache layer provides:
 1. **Significant read performance improvements** (0ms average speedup)
-2. **Minimal write overhead** (-65ms average, ~-12% of write time)
-3. **All endpoints functioning correctly** (32 passed tests)
+2. **Minimal write overhead** (4ms average, ~1% of write time)
+3. **All endpoints functioning correctly** (37 passed tests)
 
 ### 📊 Monitoring Recommendations
 
@@ -164,7 +164,7 @@ Consider tuning based on:
 - Server: http://localhost:3001
 - Test Framework: Bash + curl
 - Metrics Collection: Millisecond-precision timing
-- Test Objects Created: 201
+- Test Objects Created: 202
 - All test objects cleaned up: ✅
 
 **Test Coverage**:
@@ -176,6 +176,6 @@ Consider tuning based on:
 
 ---
 
-**Report Generated**: Fri Oct 24 16:38:52 CDT 2025  
+**Report Generated**: Mon Oct 27 18:50:18 UTC 2025  
 **Format Version**: 1.0  
 **Test Suite**: cache-metrics.sh

cache/docs/DETAILED.md

@@ -39,6 +39,7 @@ These are typically pre-installed on Linux/macOS systems. If missing, install vi
 ## Cache Configuration
 
 ### Default Settings
+- **Enabled by default**: Set `CACHING=false` to disable
 - **Max Length**: 1000 entries
 - **Max Bytes**: 1GB (1,000,000,000 bytes)
 - **TTL (Time-To-Live)**: 5 minutes (300,000ms)
@@ -47,11 +48,23 @@ These are typically pre-installed on Linux/macOS systems. If missing, install vi
 
 ### Environment Variables
 ```bash
+CACHING=true                 # Enable/disable caching layer (true/false)
 CACHE_MAX_LENGTH=1000        # Maximum number of cached entries
 CACHE_MAX_BYTES=1000000000   # Maximum memory usage in bytes
 CACHE_TTL=300000             # Time-to-live in milliseconds
 ```
 
+### Enabling/Disabling Cache
+
+**To disable caching completely**, set `CACHING=false` in your `.env` file:
+- All cache middleware will be bypassed
+- No cache lookups, storage, or invalidation
+- No `X-Cache` headers in responses
+- No overhead from cache operations
+- Useful for debugging or performance comparison
+
+**To enable caching** (default), set `CACHING=true` or leave it unset.
+
 ### Limit Enforcement Details
 
 The cache implements **dual limits** for defense-in-depth:

cache/docs/SHORT.md

@@ -92,12 +92,22 @@ Immediately clears all cached entries (useful for testing or troubleshooting).
 ## Configuration
 
 Cache behavior can be adjusted via environment variables:
+- `CACHING` - Enable/disable caching layer (default: `true`, set to `false` to disable)
 - `CACHE_MAX_LENGTH` - Maximum entries (default: 1000)
 - `CACHE_MAX_BYTES` - Maximum memory usage (default: 1GB)
 - `CACHE_TTL` - Time-to-live in milliseconds (default: 300000 = 5 minutes)
 
 **Note**: Limits are well-balanced for typical usage. With standard RERUM queries (100 items per page), 1000 cached entries use only ~26 MB (~2.7% of the 1GB byte limit). The byte limit serves as a safety net for edge cases.
 
+### Disabling Cache
+
+To disable caching completely, set `CACHING=false` in your `.env` file. This will:
+- Skip all cache lookups (no cache hits)
+- Skip cache storage (no cache writes)
+- Skip cache invalidation (no overhead on writes)
+- Remove `X-Cache` headers from responses
+- Useful for debugging or when caching is not desired
+
 ## Backwards Compatibility
 
 ✅ **Fully backwards compatible**

cache/middleware.js

@@ -13,6 +13,11 @@ import cache from './index.js'
  * Caches results based on query parameters, limit, and skip
  */
 const cacheQuery = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     // Only cache POST requests with body
     if (req.method !== 'POST' || !req.body) {
         return next()
@@ -61,6 +66,11 @@ const cacheQuery = (req, res, next) => {
  * Caches results based on search text and options
  */
 const cacheSearch = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     if (req.method !== 'POST' || !req.body) {
         return next()
     }
@@ -105,6 +115,11 @@ const cacheSearch = (req, res, next) => {
  * Caches results based on search phrase and options
  */
 const cacheSearchPhrase = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     if (req.method !== 'POST' || !req.body) {
         return next()
     }
@@ -149,6 +164,11 @@ const cacheSearchPhrase = (req, res, next) => {
  * Caches individual object lookups by ID
  */
 const cacheId = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     if (req.method !== 'GET') {
         return next()
     }
@@ -189,6 +209,11 @@ const cacheId = (req, res, next) => {
  * Caches version history lookups by ID
  */
 const cacheHistory = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     if (req.method !== 'GET') {
         return next()
     }
@@ -228,6 +253,11 @@ const cacheHistory = (req, res, next) => {
  * Caches descendant version lookups by ID
  */
 const cacheSince = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     if (req.method !== 'GET') {
         return next()
     }
@@ -267,6 +297,11 @@ const cacheSince = (req, res, next) => {
  * Invalidates cache entries when objects are created, updated, or deleted
  */
 const invalidateCache = (req, res, next) => {
+    // Skip cache invalidation if caching is disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     // Store original response methods
     const originalJson = res.json.bind(res)
     const originalSend = res.send.bind(res)
@@ -457,6 +492,11 @@ const cacheClear = (req, res) => {
  * Cache key includes ManuscriptWitness URI and pagination parameters
  */
 const cacheGogFragments = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     // Only cache if request has valid body with ManuscriptWitness
     const manID = req.body?.["ManuscriptWitness"]
     if (!manID || !manID.startsWith("http")) {
@@ -499,6 +539,11 @@ const cacheGogFragments = (req, res, next) => {
  * Cache key includes ManuscriptWitness URI and pagination parameters
  */
 const cacheGogGlosses = (req, res, next) => {
+    // Skip caching if disabled
+    if (process.env.CACHING !== 'true') {
+        return next()
+    }
+
     // Only cache if request has valid body with ManuscriptWitness
     const manID = req.body?.["ManuscriptWitness"]
     if (!manID || !manID.startsWith("http")) {