kempo-server 1.6.0 → 1.6.1

package/README.md

@@ -221,8 +221,95 @@ This json file can have any of the following properties, any property not define
 - [routeFiles](#routefiles)
 - [noRescanPaths](#norescanpaths)
 - [maxRescanAttempts](#maxrescanattempts)
+- [cache](#cache)
 - [middleware](#middleware)
 
+## Cache
+
+Kempo Server includes an intelligent module caching system that dramatically improves performance by caching JavaScript route modules in memory. The cache combines multiple strategies:
+
+- **LRU (Least Recently Used)** - Evicts oldest modules when cache fills
+- **Time-based expiration** - Modules expire after configurable TTL
+- **Memory monitoring** - Automatically clears cache if memory usage gets too high
+- **File watching** - Instantly invalidates cache when files change (development)
+
+### Basic Cache Configuration
+
+Enable caching in your `.config.json`:
+
+```json
+{
+  "cache": {
+    "enabled": true,
+    "maxSize": 100,
+    "maxMemoryMB": 50,
+    "ttlMs": 300000,
+    "watchFiles": true
+  }
+}
+```
+
+### Cache Options
+
+- `enabled` (boolean) - Enable/disable caching (default: `true`)
+- `maxSize` (number) - Maximum cached modules (default: `100`) 
+- `maxMemoryMB` (number) - Memory limit in MB (default: `50`)
+- `ttlMs` (number) - Cache lifetime in milliseconds (default: `300000` - 5 minutes)
+- `maxHeapUsagePercent` (number) - Clear cache when heap exceeds % (default: `70`)
+- `memoryCheckInterval` (number) - Memory check frequency in ms (default: `30000`)
+- `watchFiles` (boolean) - Auto-invalidate on file changes (default: `true`)
+- `enableMemoryMonitoring` (boolean) - Enable memory monitoring (default: `true`)
+
+### Environment-Specific Configurations
+
+Use different config files for different environments:
+
+**Development (`dev.config.json`):**
+```json
+{
+  "cache": {
+    "enabled": true,
+    "maxSize": 50,
+    "ttlMs": 300000,
+    "watchFiles": true
+  }
+}
+```
+
+**Production (`prod.config.json`):**
+```json
+{
+  "cache": {
+    "enabled": true,
+    "maxSize": 1000,
+    "maxMemoryMB": 200,
+    "ttlMs": 3600000,
+    "watchFiles": false
+  }
+}
+```
+
+Run with specific config: `node src/index.js --config prod.config.json`
+
+### Cache Monitoring
+
+Monitor cache performance at runtime:
+
+- **View stats:** `GET /_admin/cache` - Returns detailed cache statistics
+- **Clear cache:** `DELETE /_admin/cache` - Clears entire cache
+
+Example response:
+```json
+{
+  "cache": {
+    "size": 45,
+    "maxSize": 100,
+    "memoryUsageMB": 12.5,
+    "hitRate": 87
+  }
+}
+```
+
 ## Middleware
 
 Kempo Server includes a powerful middleware system that allows you to add functionality like authentication, logging, CORS, compression, and more. Middleware runs before your route handlers and can modify requests, responses, or handle requests entirely.
@@ -511,6 +598,37 @@ The maximum number of times to attempt rescanning the file system when a file is
 }
 ```
 
+### cache
+
+Configure the intelligent module caching system for improved performance:
+
+```json
+{
+  "cache": {
+    "enabled": true,
+    "maxSize": 100,
+    "maxMemoryMB": 50,
+    "ttlMs": 300000,
+    "maxHeapUsagePercent": 70,
+    "memoryCheckInterval": 30000,
+    "watchFiles": true,
+    "enableMemoryMonitoring": true
+  }
+}
+```
+
+Cache options:
+- `enabled` - Enable/disable caching (boolean, default: `true`)
+- `maxSize` - Maximum cached modules (number, default: `100`) 
+- `maxMemoryMB` - Memory limit in MB (number, default: `50`)
+- `ttlMs` - Cache lifetime in milliseconds (number, default: `300000`)
+- `maxHeapUsagePercent` - Clear cache when heap exceeds % (number, default: `70`)
+- `memoryCheckInterval` - Memory check frequency in ms (number, default: `30000`)
+- `watchFiles` - Auto-invalidate on file changes (boolean, default: `true`)
+- `enableMemoryMonitoring` - Enable memory monitoring (boolean, default: `true`)
+
+Use different config files for different environments rather than nested objects.
+
 ## Features
 
 - **Zero Dependencies** - No external dependencies required

package/config-examples/development.config.json

@@ -0,0 +1,24 @@
+{
+  "_comment": "Development configuration with aggressive file watching and conservative memory usage",
+  "cache": {
+    "enabled": true,
+    "maxSize": 50,
+    "maxMemoryMB": 25,
+    "ttlMs": 300000,
+    "maxHeapUsagePercent": 65,
+    "memoryCheckInterval": 15000,
+    "watchFiles": true,
+    "enableMemoryMonitoring": true
+  },
+  "middleware": {
+    "cors": {
+      "enabled": true,
+      "origin": "*"
+    },
+    "logging": {
+      "enabled": true,
+      "includeUserAgent": true,
+      "includeResponseTime": true
+    }
+  }
+}

package/config-examples/low-memory.config.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "Low-memory configuration for resource-constrained environments",
+  "cache": {
+    "enabled": true,
+    "maxSize": 20,
+    "maxMemoryMB": 5,
+    "ttlMs": 120000,
+    "maxHeapUsagePercent": 60,
+    "memoryCheckInterval": 10000,
+    "watchFiles": true,
+    "enableMemoryMonitoring": true
+  },
+  "middleware": {
+    "compression": {
+      "enabled": true,
+      "threshold": 512
+    },
+    "logging": {
+      "enabled": true,
+      "includeResponseTime": false
+    }
+  }
+}

package/config-examples/no-cache.config.json

@@ -0,0 +1,13 @@
+{
+  "_comment": "Cache disabled configuration for debugging or special environments",
+  "cache": {
+    "enabled": false
+  },
+  "middleware": {
+    "logging": {
+      "enabled": true,
+      "includeUserAgent": true,
+      "includeResponseTime": true
+    }
+  }
+}

package/config-examples/production.config.json

@@ -0,0 +1,38 @@
+{
+  "_comment": "Production configuration with large cache and disabled file watching",
+  "cache": {
+    "enabled": true,
+    "maxSize": 1000,
+    "maxMemoryMB": 200,
+    "ttlMs": 3600000,
+    "maxHeapUsagePercent": 85,
+    "memoryCheckInterval": 60000,
+    "watchFiles": false,
+    "enableMemoryMonitoring": true
+  },
+  "middleware": {
+    "cors": {
+      "enabled": true,
+      "origin": ["https://myapp.com", "https://www.myapp.com"],
+      "credentials": true
+    },
+    "compression": {
+      "enabled": true,
+      "threshold": 1024
+    },
+    "security": {
+      "enabled": true,
+      "headers": {
+        "X-Content-Type-Options": "nosniff",
+        "X-Frame-Options": "DENY",
+        "X-XSS-Protection": "1; mode=block",
+        "Strict-Transport-Security": "max-age=31536000; includeSubDomains"
+      }
+    },
+    "logging": {
+      "enabled": true,
+      "includeUserAgent": false,
+      "includeResponseTime": true
+    }
+  }
+}

package/docs/.config.json.example

@@ -15,5 +15,15 @@
   "noRescanPaths": [
     "/vendor/"
   ],
-  "maxRescanAttempts": 3
+  "maxRescanAttempts": 3,
+  "cache": {
+    "enabled": true,
+    "maxSize": 150,
+    "maxMemoryMB": 75,
+    "ttlMs": 600000,
+    "maxHeapUsagePercent": 75,
+    "memoryCheckInterval": 20000,
+    "watchFiles": true,
+    "enableMemoryMonitoring": true
+  }
 }

package/docs/api/_admin/cache/DELETE.js

@@ -0,0 +1,28 @@
+/*
+  Clear Cache Admin Endpoint
+*/
+
+export default async (req, res) => {
+  // Find the router instance to access moduleCache
+  const moduleCache = req.moduleCache || req._kempoCache;
+  
+  if (!moduleCache) {
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      error: 'Cache not available',
+      message: 'Module cache is not enabled or accessible'
+    }));
+    return;
+  }
+
+  // Clear cache
+  const sizeBefore = moduleCache.cache.size;
+  moduleCache.clear();
+  
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    message: 'Cache cleared successfully',
+    entriesCleared: sizeBefore,
+    timestamp: new Date().toISOString()
+  }));
+};

package/docs/api/_admin/cache/GET.js

@@ -0,0 +1,53 @@
+/*
+  Cache Administration Endpoint
+  GET /_admin/cache - Returns cache statistics as JSON
+  DELETE /_admin/cache - Clears the entire cache
+*/
+
+export default async (req, res) => {
+  // Find the router instance to access moduleCache
+  // This is a bit of a hack - in practice you'd pass this through middleware
+  const moduleCache = req.moduleCache || req._kempoCache;
+  
+  if (!moduleCache) {
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      error: 'Cache not available',
+      message: 'Module cache is not enabled or accessible'
+    }));
+    return;
+  }
+
+  if (req.method === 'GET') {
+    // Return cache statistics
+    const stats = moduleCache.getStats();
+    const cachedFiles = moduleCache.getCachedFiles();
+    
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      ...stats,
+      cachedFiles: cachedFiles.map(file => ({
+        ...file,
+        ageSeconds: Math.round(file.age / 1000)
+      }))
+    }, null, 2));
+    
+  } else if (req.method === 'DELETE') {
+    // Clear cache
+    const sizeBefore = moduleCache.cache.size;
+    moduleCache.clear();
+    
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      message: 'Cache cleared successfully',
+      entriesCleared: sizeBefore
+    }));
+    
+  } else {
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'Method not allowed',
+      allowed: ['GET', 'DELETE']
+    }));
+  }
+};

package/docs/caching.html

@@ -0,0 +1,235 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset='utf-8'>
+  <meta http-equiv='X-UA-Compatible' content='IE=edge'>
+  <title>Caching - Kempo Server</title>
+  <meta name='viewport' content='width=device-width, initial-scale=1'>
+  <link rel="icon" type="image/png" sizes="48x48" href="./media/icon48.png">
+  <link rel="manifest" href="./manifest.json">
+  <link rel="stylesheet" href="./kempo.min.css" />
+</head>
+<body>
+  <main>
+    <a href="./" class="btn">Home</a>
+    <h1>Module Caching</h1>
+    <p>Kempo Server includes an intelligent module caching system that dramatically improves performance by caching JavaScript route modules in memory.</p>
+
+    <h2>How It Works</h2>
+    <p>The cache system combines multiple strategies to optimize performance while preventing memory issues:</p>
+    <ul>
+      <li><strong>LRU (Least Recently Used)</strong> - Evicts oldest modules when cache fills</li>
+      <li><strong>Time-based expiration</strong> - Modules expire after configurable TTL</li>
+      <li><strong>Memory monitoring</strong> - Automatically clears cache if memory usage gets too high</li>
+      <li><strong>File watching</strong> - Instantly invalidates cache when files change (development)</li>
+    </ul>
+
+    <h2>Basic Configuration</h2>
+    <p>Add a <code>cache</code> object to your <code>.config.json</code> file:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">100</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">50</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">300000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">true</span>
+  }
+}</code></pre>
+
+    <h2>Configuration Options</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>Option</th>
+          <th>Type</th>
+          <th>Default</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><code>enabled</code></td>
+          <td>boolean</td>
+          <td><code>true</code></td>
+          <td>Enable/disable the entire caching system</td>
+        </tr>
+        <tr>
+          <td><code>maxSize</code></td>
+          <td>number</td>
+          <td><code>100</code></td>
+          <td>Maximum number of modules to cache</td>
+        </tr>
+        <tr>
+          <td><code>maxMemoryMB</code></td>
+          <td>number</td>
+          <td><code>50</code></td>
+          <td>Memory limit for cache in megabytes</td>
+        </tr>
+        <tr>
+          <td><code>ttlMs</code></td>
+          <td>number</td>
+          <td><code>300000</code></td>
+          <td>Time to live in milliseconds (5 minutes)</td>
+        </tr>
+        <tr>
+          <td><code>maxHeapUsagePercent</code></td>
+          <td>number</td>
+          <td><code>70</code></td>
+          <td>Clear cache when heap usage exceeds this percentage</td>
+        </tr>
+        <tr>
+          <td><code>memoryCheckInterval</code></td>
+          <td>number</td>
+          <td><code>30000</code></td>
+          <td>How often to check memory usage (milliseconds)</td>
+        </tr>
+        <tr>
+          <td><code>watchFiles</code></td>
+          <td>boolean</td>
+          <td><code>true</code></td>
+          <td>Auto-invalidate cache when files change</td>
+        </tr>
+        <tr>
+          <td><code>enableMemoryMonitoring</code></td>
+          <td>boolean</td>
+          <td><code>true</code></td>
+          <td>Enable automatic memory monitoring</td>
+        </tr>
+      </tbody>
+    </table>
+
+    <h2>Environment-Specific Configuration</h2>
+    <p>Use separate configuration files for different environments instead of nested objects:</p>
+
+    <h3>Development Configuration</h3>
+    <p>Create <code>dev.config.json</code> with settings optimized for development:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">50</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">25</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">300000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">true</span>
+  }
+}</code></pre>
+    <pre><code class="hljs bash">node src/index.js --config dev.config.json</code></pre>
+
+    <h3>Production Configuration</h3>
+    <p>Create <code>prod.config.json</code> with settings optimized for production:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">1000</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">200</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">3600000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">false</span>
+  }
+}</code></pre>
+    <pre><code class="hljs bash">node src/index.js --config prod.config.json</code></pre>
+
+    <h2>Cache Monitoring</h2>
+    <p>Monitor cache performance and manage cached modules at runtime:</p>
+
+    <h3>View Cache Statistics</h3>
+    <pre><code class="hljs bash">curl http://localhost:3000/_admin/cache</code></pre>
+    <p>Returns detailed statistics including:</p>
+    <ul>
+      <li>Cache size and memory usage</li>
+      <li>Hit/miss rates</li>
+      <li>Node.js memory usage</li>
+      <li>List of cached files</li>
+    </ul>
+
+    <h3>Clear Cache</h3>
+    <pre><code class="hljs bash">curl -X DELETE http://localhost:3000/_admin/cache</code></pre>
+    <p>Immediately clears all cached modules.</p>
+
+    <h2>Performance Tuning</h2>
+
+    <h3>Memory Settings</h3>
+    <ul>
+      <li>Set <code>maxMemoryMB</code> to 10-20% of available server RAM</li>
+      <li>Use lower <code>maxHeapUsagePercent</code> (60-70%) for memory-constrained environments</li>
+      <li>Monitor actual usage with <code>/_admin/cache</code> endpoint</li>
+    </ul>
+
+    <h3>Cache Size</h3>
+    <ul>
+      <li>Start with <code>maxSize</code> = 10x your typical concurrent routes</li>
+      <li>Increase if you have many route files and sufficient memory</li>
+      <li>Decrease for microservices with few routes</li>
+    </ul>
+
+    <h3>TTL Settings</h3>
+    <ul>
+      <li><strong>Development:</strong> Short TTL (5-10 minutes) for quick iteration</li>
+      <li><strong>Production:</strong> Longer TTL (30-60 minutes) for stability</li>
+      <li><strong>High-change environments:</strong> Shorter TTL or rely on file watching</li>
+    </ul>
+
+    <h3>File Watching</h3>
+    <ul>
+      <li><strong>Enable</strong> (<code>watchFiles: true</code>) in development for instant invalidation</li>
+      <li><strong>Disable</strong> (<code>watchFiles: false</code>) in production to reduce overhead</li>
+    </ul>
+
+    <h2>Configuration Examples</h2>
+
+    <h3>Minimal Configuration</h3>
+    <p>Just enable caching with defaults:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>
+  }
+}</code></pre>
+
+    <h3>High-Traffic Configuration</h3>
+    <p>For servers with lots of routes and traffic:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">2000</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">500</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">7200000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">false</span>
+  }
+}</code></pre>
+
+    <h3>Memory-Constrained Configuration</h3>
+    <p>For servers with limited RAM:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">25</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">10</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">120000</span>,
+    <span class="hljs-attr">"maxHeapUsagePercent"</span>: <span class="hljs-number">60</span>
+  }
+}</code></pre>
+
+    <h2>Troubleshooting</h2>
+
+    <h3>Cache Not Working</h3>
+    <ul>
+      <li>Verify <code>cache.enabled</code> is <code>true</code></li>
+      <li>Check file permissions for watching</li>
+      <li>Review server logs for cache statistics</li>
+    </ul>
+
+    <h3>Memory Issues</h3>
+    <ul>
+      <li>Reduce <code>maxMemoryMB</code> and <code>maxSize</code></li>
+      <li>Lower <code>maxHeapUsagePercent</code></li>
+      <li>Enable more aggressive memory monitoring</li>
+    </ul>
+
+    <h3>Performance Issues</h3>
+    <ul>
+      <li>Increase cache limits if you have available memory</li>
+      <li>Extend <code>ttlMs</code> for stable route files</li>
+      <li>Monitor hit rates with admin endpoints</li>
+    </ul>
+
+  </main>
+</body>
+</html>