kempo-server 1.7.3 → 1.7.5

package/README.md

@@ -211,435 +211,19 @@ export default async function(request, response) {
 
 ## Configuration
 
-To configure the server, create a configuration file (by default `.config.json`) within the root directory of your server (`public` in the start example [above](#getting-started)). You can specify a different configuration file using the `--config` flag.
+Kempo Server can be customized with a simple JSON configuration file to control caching, middleware, security, routing, and more.
 
-**Important:** 
-- When using a relative path for the `--config` flag, the config file must be located within the server root directory
-- When using an absolute path for the `--config` flag, the config file can be located anywhere on the filesystem
-- The server will throw an error if you attempt to use a relative config file path that points outside the root directory
+For detailed configuration options and examples, see **[CONFIG.md](./CONFIG.md)**.
 
-This json file can have any of the following properties, any property not defined will use the "Default Config".
-
-- [allowedMimes](#allowedmimes)
-- [disallowedRegex](#disallowedregex)
-- [customRoutes](#customroutes)
-- [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.
-
-### Built-in Middleware
-
-#### CORS
-Enable Cross-Origin Resource Sharing for your API:
-
-```json
-{
-  "middleware": {
-    "cors": {
-      "enabled": true,
-      "origin": "*",
-      "methods": ["GET", "POST", "PUT", "DELETE"],
-      "headers": ["Content-Type", "Authorization"]
-    }
-  }
-}
-```
-
-#### Compression
-Automatically compress responses with gzip:
-
-```json
-{
-  "middleware": {
-    "compression": {
-      "enabled": true,
-      "threshold": 1024
-    }
-  }
-}
-```
-
-#### Rate Limiting
-Limit requests per client to prevent abuse:
-
-```json
-{
-  "middleware": {
-    "rateLimit": {
-      "enabled": true,
-      "maxRequests": 100,
-      "windowMs": 60000,
-      "message": "Too many requests"
-    }
-  }
-}
-```
-
-#### Security Headers
-Add security headers to all responses:
-
-```json
-{
-  "middleware": {
-    "security": {
-      "enabled": true,
-      "headers": {
-        "X-Content-Type-Options": "nosniff",
-        "X-Frame-Options": "DENY",
-        "X-XSS-Protection": "1; mode=block"
-      }
-    }
-  }
-}
-```
-
-#### Request Logging
-Log requests with configurable detail:
-
-```json
-{
-  "middleware": {
-    "logging": {
-      "enabled": true,
-      "includeUserAgent": true,
-      "includeResponseTime": true
-    }
-  }
-}
-```
-
-### Custom Middleware
-
-Create your own middleware by writing JavaScript files and referencing them in your config:
-
-```json
-{
-  "middleware": {
-    "custom": ["./middleware/auth.js", "./middleware/analytics.js"]
-  }
-}
-```
-
-#### Custom Middleware Example
-
-```javascript
-// middleware/auth.js
-export default (config) => {
-  return async (req, res, next) => {
-    const token = req.headers.authorization;
-    
-    if (!token) {
-      req.user = null;
-      return await next();
-    }
-    
-    try {
-      // Verify JWT token (example)
-      const user = verifyToken(token);
-      req.user = user;
-      req.permissions = await getUserPermissions(user.id);
-      
-      // Add helper methods
-      req.hasPermission = (permission) => req.permissions.includes(permission);
-      
-    } catch (error) {
-      req.user = null;
-    }
-    
-    await next();
-  };
-};
-```
-
-#### Using Enhanced Requests in Routes
-
-Your route files can now access the enhanced request object:
-
-```javascript
-// api/user/profile/GET.js
-export default async (req, res, params) => {
-  if (!req.user) {
-    return res.status(401).json({ error: 'Authentication required' });
-  }
-  
-  if (!req.hasPermission('user:read')) {
-    return res.status(403).json({ error: 'Insufficient permissions' });
-  }
-  
-  const profile = await getUserProfile(req.user.id);
-  res.json(profile);
-};
-```
-
-### Middleware Order
-
-Middleware executes in this order:
-1. Built-in middleware (cors, compression, rateLimit, security, logging)
-2. Custom middleware (in the order listed in config)
-3. Your route handlers
-
-### Route Interception
-
-Middleware can intercept and handle routes completely, useful for authentication endpoints:
-
-```javascript
-// middleware/auth-routes.js
-export default (config) => {
-  return async (req, res, next) => {
-    const url = new URL(req.url, `http://${req.headers.host}`);
-    
-    // Handle login endpoint
-    if (req.method === 'POST' && url.pathname === '/auth/login') {
-      const credentials = await req.json();
-      const token = await authenticateUser(credentials);
-      
-      if (token) {
-        return res.json({ token, success: true });
-      } else {
-        return res.status(401).json({ error: 'Invalid credentials' });
-      }
-    }
-    
-    await next();
-  };
-};
-```
-
-### allowedMimes
-
-An object mapping file extensions to their MIME types. Files with extensions not in this list will not be served.
-
-```json
-{
-  "allowedMimes": {
-    "html": "text/html",
-    "css": "text/css",
-    "js": "application/javascript",
-    "json": "application/json",
-    "png": "image/png",
-    "jpg": "image/jpeg"
-  }
-}
-```
-
-### disallowedRegex
-
-An array of regular expressions that match paths that should never be served. This provides security by preventing access to sensitive files.
-
-```json
-{
-  "disallowedRegex": [
-    "^/\\..*",
-    "\\.env$",
-    "\\.config$",
-    "password"
-  ]
-}
-```
-
-### routeFiles
-
-An array of filenames that should be treated as route handlers and executed as JavaScript modules.
-
-```json
-{
-  "routeFiles": [
-    "GET.js",
-    "POST.js",
-    "PUT.js",
-    "DELETE.js",
-    "index.js"
-  ]
-}
-```
-
-### noRescanPaths
-
-An array of regex patterns for paths that should not trigger a file system rescan. This improves performance for common static assets.
-
-```json
-{
-  "noRescanPaths": [
-    "/favicon\\.ico$",
-    "/robots\\.txt$",
-    "\\.map$"
-  ]
-}
-```
-
-### customRoutes
-
-An object mapping custom route paths to file paths. Useful for aliasing or serving files from outside the document root.
-
-**Note:** All file paths in customRoutes are resolved relative to the server root directory (the `--root` path). This allows you to reference files both inside and outside the document root.
-
-**Basic Routes:**
-```json
-{
-  "customRoutes": {
-    "/vendor/bootstrap.css": "../node_modules/bootstrap/dist/css/bootstrap.min.css",
-    "/api/status": "./status.js"
-  }
-}
-```
-
-**Wildcard Routes:**
-Wildcard routes allow you to map entire directory structures using the `*` and `**` wildcards:
-
-```json
-{
-  "customRoutes": {
-    "kempo/*": "../node_modules/kempo/dist/*",
-    "assets/*": "../static-files/*",
-    "docs/*": "../documentation/*",
-    "src/**": "../src/**"
-  }
-}
-```
-
-With wildcard routes:
-- `kempo/styles.css` would serve `../node_modules/kempo/dist/styles.css`
-- `assets/logo.png` would serve `../static-files/logo.png`  
-- `docs/readme.md` would serve `../documentation/readme.md`
-- `src/components/Button.js` would serve `../src/components/Button.js`
-
-The `*` wildcard matches any single path segment (anything between `/` characters).
-The `**` wildcard matches any number of path segments, allowing you to map entire directory trees.
-Multiple wildcards can be used in a single route pattern.
-
-### maxRescanAttempts
-
-The maximum number of times to attempt rescanning the file system when a file is not found. Defaults to 3.
-
-```json
-{
-  "maxRescanAttempts": 3
-}
-```
-
-### cache
-
-Configure the intelligent module caching system for improved performance:
+Quick start:
+```bash
+# Create a basic config file
+echo '{"cache": {"enabled": true}}' > .config.json
 
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 100,
-    "maxMemoryMB": 50,
-    "ttlMs": 300000,
-    "maxHeapUsagePercent": 70,
-    "memoryCheckInterval": 30000,
-    "watchFiles": true,
-    "enableMemoryMonitoring": true
-  }
-}
+# Use different configs for different environments
+kempo-server --root public --config dev.config.json
 ```
 
-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
@@ -756,24 +340,6 @@ Kempo Server supports several command line options to customize its behavior:
 kempo-server --root public --port 8080 --host 0.0.0.0 --verbose
 ```
 
-### Configuration File Examples
-
-You can specify different configuration files for different environments:
-
-```bash
-# Development
-kempo-server --root public --config dev.config.json
-
-# Staging
-kempo-server --root public --config staging.config.json
-
-# Production with absolute path
-kempo-server --root public --config /etc/kempo/production.config.json
-
-# Mix with other options
-kempo-server --root dist --port 8080 --config production.config.json --scan
-```
-
 ## Testing
 
 This project uses the Kempo Testing Framework. Tests live in the `tests/` folder and follow these naming conventions:
@@ -796,3 +362,8 @@ npm run tests:gui     # Start the GUI test runner
 For advanced usage (filters, flags, GUI options), see:
 https://github.com/dustinpoissant/kempo-testing-framework
 
+## Documentation
+
+- **[CONFIG.md](./CONFIG.md)** - Comprehensive server configuration guide
+- **[UTILS.md](./UTILS.md)** - Utility modules for Node.js projects
+

package/UTILS.md

@@ -0,0 +1,127 @@
+# Utility Modules
+
+Kempo Server includes some utility modules that can be used in your own Node.js projects. These utilities are built and exported alongside the main server package.
+
+> **Note:** These utilities are included here for convenience but may be moved to their own dedicated package in the future as more Node.js utilities are added.
+
+## CLI Utilities
+
+The CLI utilities provide simple command-line argument parsing functionality.
+
+### Usage
+
+```javascript
+import { getArgs } from 'kempo-server/utils/cli';
+
+// Basic usage - get all arguments as key-value pairs
+const args = getArgs();
+console.log(args); // { port: '3000', host: 'localhost', verbose: true }
+
+// With mapping - map short flags to full names
+const args = getArgs({
+  'p': 'port',
+  'h': 'host',
+  'v': 'verbose'
+});
+console.log(args); // Maps -p to port, -h to host, -v to verbose
+```
+
+### Example
+
+```bash
+node myapp.js --port 8080 -h 127.0.0.1 --verbose
+```
+
+```javascript
+import { getArgs } from 'kempo-server/utils/cli';
+
+const args = getArgs({
+  'h': 'host',
+  'p': 'port',
+  'v': 'verbose'
+});
+
+// Results in:
+// {
+//   host: '127.0.0.1',
+//   port: '8080', 
+//   verbose: true
+// }
+```
+
+## File System Utilities
+
+The file system utilities provide common file and directory operations with Promise-based APIs.
+
+### Usage
+
+```javascript
+import { ensureDir, copyDir } from 'kempo-server/utils/fs-utils';
+
+// Ensure a directory exists (creates all parent directories if needed)
+await ensureDir('./my/nested/directory');
+
+// Copy an entire directory structure recursively
+await copyDir('./source', './destination');
+```
+
+### Functions
+
+#### `ensureDir(dirPath)`
+
+Ensures that a directory exists, creating it and any necessary parent directories if they don't exist. Similar to `mkdir -p`.
+
+- **Parameters:**
+  - `dirPath` (string) - The directory path to ensure exists
+- **Returns:** Promise that resolves when the directory is confirmed to exist
+
+#### `copyDir(srcPath, destPath)`
+
+Recursively copies an entire directory structure from source to destination.
+
+- **Parameters:**
+  - `srcPath` (string) - The source directory to copy from
+  - `destPath` (string) - The destination directory to copy to
+- **Returns:** Promise that resolves when the copy operation is complete
+
+### Example Use Cases
+
+```javascript
+import { ensureDir, copyDir } from 'kempo-server/utils/fs-utils';
+
+// Build script example
+async function buildProject() {
+  // Ensure build directories exist
+  await ensureDir('./dist/assets');
+  await ensureDir('./dist/components');
+  
+  // Copy static assets
+  await copyDir('./src/assets', './dist/assets');
+  await copyDir('./src/public', './dist');
+}
+
+// Backup script example
+async function backupProject() {
+  const timestamp = new Date().toISOString().slice(0, 10);
+  const backupPath = `./backups/${timestamp}`;
+  
+  await ensureDir(backupPath);
+  await copyDir('./src', `${backupPath}/src`);
+  await copyDir('./config', `${backupPath}/config`);
+}
+```
+
+## Installation and Build
+
+These utilities are automatically built when you install kempo-server. They're available through the package's exports:
+
+```json
+{
+  "exports": {
+    "./utils/cli": "./dist/utils/cli.js",
+    "./utils/fs-utils": "./dist/utils/fs-utils.js"
+  }
+}
+```
+
+The utilities are ES modules and require Node.js environments that support ES module imports.

package/dist/defaultConfig.js

@@ -1 +1 @@
-export default{allowedMimes:{html:"text/html",htm:"text/html",shtml:"text/html",css:"text/css",xml:"text/xml",gif:"image/gif",jpeg:"image/jpeg",jpg:"image/jpeg",js:"application/javascript",mjs:"application/javascript",json:"application/json",webp:"image/webp",png:"image/png",svg:"image/svg+xml",svgz:"image/svg+xml",ico:"image/x-icon",webm:"video/webm",mp4:"video/mp4",m4v:"video/mp4",ogv:"video/ogg",mp3:"audio/mpeg",ogg:"audio/ogg",wav:"audio/wav",woff:"font/woff",woff2:"font/woff2",ttf:"font/ttf",otf:"font/otf",eot:"application/vnd.ms-fontobject",pdf:"application/pdf",txt:"text/plain",webmanifest:"application/manifest+json",md:"text/markdown",csv:"text/csv",doc:"application/msword",docx:"application/vnd.openxmlformats-officedocument.wordprocessingml.document",xls:"application/vnd.ms-excel",xlsx:"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",ppt:"application/vnd.ms-powerpoint",pptx:"application/vnd.openxmlformats-officedocument.presentationml.presentation",avif:"image/avif",wasm:"application/wasm"},disallowedRegex:["^/\\..*","\\.config$","\\.env$","\\.git/","\\.htaccess$","\\.htpasswd$","^/node_modules/","^/vendor/","\\.log$","\\.bak$","\\.sql$","\\.ini$","password","config\\.php$","wp-config\\.php$","\\.DS_Store$"],routeFiles:["GET.js","POST.js","PUT.js","DELETE.js","HEAD.js","OPTIONS.js","PATCH.js","CONNECT.js","TRACE.js","index.js"],noRescanPaths:["^\\.well-known/","/favicon\\.ico$","/robots\\.txt$","/sitemap\\.xml$","/apple-touch-icon","/android-chrome-","/browserconfig\\.xml$","/manifest\\.json$","\\.map$","/__webpack_hmr$","/hot-update\\.","/sockjs-node/"],maxRescanAttempts:3,customRoutes:{},middleware:{cors:{enabled:!1,origin:"*",methods:["GET","POST","PUT","DELETE","OPTIONS"],headers:["Content-Type","Authorization"]},compression:{enabled:!1,threshold:1024},rateLimit:{enabled:!1,maxRequests:100,windowMs:6e4,message:"Too many requests"},security:{enabled:!0,headers:{"X-Content-Type-Options":"nosniff","X-Frame-Options":"DENY","X-XSS-Protection":"1; mode=block"}},logging:{enabled:!0,includeUserAgent:!1,includeResponseTime:!0},custom:[]}};
+export default{allowedMimes:{html:"text/html",htm:"text/html",shtml:"text/html",css:"text/css",xml:"text/xml",gif:"image/gif",jpeg:"image/jpeg",jpg:"image/jpeg",js:"application/javascript",mjs:"application/javascript",json:"application/json",webp:"image/webp",png:"image/png",svg:"image/svg+xml",svgz:"image/svg+xml",ico:"image/x-icon",webm:"video/webm",mp4:"video/mp4",m4v:"video/mp4",ogv:"video/ogg",mp3:"audio/mpeg",ogg:"audio/ogg",wav:"audio/wav",woff:"font/woff",woff2:"font/woff2",ttf:"font/ttf",otf:"font/otf",eot:"application/vnd.ms-fontobject",pdf:"application/pdf",txt:"text/plain",webmanifest:"application/manifest+json",md:"text/markdown",csv:"text/csv",doc:"application/msword",docx:"application/vnd.openxmlformats-officedocument.wordprocessingml.document",xls:"application/vnd.ms-excel",xlsx:"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",ppt:"application/vnd.ms-powerpoint",pptx:"application/vnd.openxmlformats-officedocument.presentationml.presentation",avif:"image/avif",wasm:"application/wasm"},disallowedRegex:["^/\\..*","\\.config$","\\.env$","\\.git/","\\.htaccess$","\\.htpasswd$","^/node_modules/","^/vendor/","\\.log$","\\.bak$","\\.sql$","\\.ini$","password","config\\.php$","wp-config\\.php$","\\.DS_Store$"],routeFiles:["GET.js","POST.js","PUT.js","DELETE.js","HEAD.js","OPTIONS.js","PATCH.js","CONNECT.js","TRACE.js","index.js"],noRescanPaths:["^\\.well-known/","/favicon\\.ico$","/robots\\.txt$","/sitemap\\.xml$","/apple-touch-icon","/android-chrome-","/browserconfig\\.xml$","/manifest\\.json$","\\.map$","/__webpack_hmr$","/hot-update\\.","/sockjs-node/"],maxRescanAttempts:3,customRoutes:{},middleware:{cors:{enabled:!1,origin:"*",methods:["GET","POST","PUT","DELETE","OPTIONS"],headers:["Content-Type","Authorization"]},compression:{enabled:!1,threshold:1024},rateLimit:{enabled:!1,maxRequests:100,windowMs:6e4,message:"Too many requests"},security:{enabled:!0,headers:{"X-Content-Type-Options":"nosniff","X-Frame-Options":"DENY","X-XSS-Protection":"1; mode=block"}},logging:{enabled:!0,includeUserAgent:!1,includeResponseTime:!0},custom:[]},cache:{enabled:!1,maxSize:100,maxMemoryMB:50,ttlMs:3e5,maxHeapUsagePercent:70,memoryCheckInterval:3e4,watchFiles:!0,enableMemoryMonitoring:!0}};

package/dist/moduleCache.js

@@ -0,0 +1 @@
+import{watch}from"fs";import path from"path";export default class ModuleCache{constructor(config={}){this.cache=new Map,this.watchers=new Map,this.maxSize=config.maxSize||100,this.maxMemoryMB=config.maxMemoryMB||50,this.ttlMs=config.ttlMs||3e5,this.maxHeapUsagePercent=config.maxHeapUsagePercent||70,this.memoryCheckInterval=config.memoryCheckInterval||3e4,this.watchFiles=!1!==config.watchFiles,this.currentMemoryMB=0,this.stats={hits:0,misses:0,evictions:0,fileChanges:0},!1!==config.enableMemoryMonitoring&&this.startMemoryMonitoring()}startMemoryMonitoring(){this.memoryTimer=setInterval(()=>{const usage=process.memoryUsage(),heapPercent=usage.heapUsed/usage.heapTotal*100;if(heapPercent>this.maxHeapUsagePercent){const clearedCount=this.clearExpiredEntries();for(this.stats.evictions+=clearedCount;this.cache.size>0&&heapPercent>this.maxHeapUsagePercent;)this.evictOldest()}},this.memoryCheckInterval)}destroy(){this.memoryTimer&&clearInterval(this.memoryTimer);for(const watcher of this.watchers.values())watcher.close();this.watchers.clear(),this.cache.clear()}get(filePath,stats){const entry=this.cache.get(filePath);if(!entry)return this.stats.misses++,null;return Date.now()-entry.timestamp>this.ttlMs||entry.mtime<stats.mtime?(this.delete(filePath),this.stats.misses++,null):(this.cache.delete(filePath),this.cache.set(filePath,entry),this.stats.hits++,entry.module)}set(filePath,module,stats,estimatedSizeKB=1){const sizeInMB=estimatedSizeKB/1024;for(;this.cache.size>=this.maxSize||this.currentMemoryMB+sizeInMB>this.maxMemoryMB;)this.evictOldest();const entry={module:module,mtime:stats.mtime,timestamp:Date.now(),sizeKB:estimatedSizeKB,filePath:filePath};this.cache.set(filePath,entry),this.currentMemoryMB+=sizeInMB,this.watchFiles&&this.setupFileWatcher(filePath)}delete(filePath){const entry=this.cache.get(filePath);if(entry){this.cache.delete(filePath),this.currentMemoryMB-=entry.sizeKB/1024;const watcher=this.watchers.get(filePath);return watcher&&(watcher.close(),this.watchers.delete(filePath)),!0}return!1}clear(){const size=this.cache.size;this.cache.clear(),this.currentMemoryMB=0;for(const watcher of this.watchers.values())watcher.close();this.watchers.clear(),this.stats.evictions+=size}evictOldest(){if(0===this.cache.size)return;const[oldestKey,oldestEntry]=this.cache.entries().next().value;this.delete(oldestKey),this.stats.evictions++}clearExpiredEntries(){const now=Date.now();let clearedCount=0;for(const[filePath,entry]of this.cache.entries())now-entry.timestamp>this.ttlMs&&(this.delete(filePath),clearedCount++);return clearedCount}setupFileWatcher(filePath){if(!this.watchers.has(filePath))try{const watcher=watch(filePath,eventType=>{"change"===eventType&&(this.delete(filePath),this.stats.fileChanges++)});watcher.on("error",error=>{this.delete(filePath)}),this.watchers.set(filePath,watcher)}catch(error){console.warn(`Could not watch file ${filePath}: ${error.message}`)}}getStats(){const memoryUsage=process.memoryUsage();return{cache:{size:this.cache.size,maxSize:this.maxSize,memoryUsageMB:Math.round(100*this.currentMemoryMB)/100,maxMemoryMB:this.maxMemoryMB,watchersActive:this.watchers.size},stats:{...this.stats},memory:{heapUsedMB:Math.round(memoryUsage.heapUsed/1024/1024*100)/100,heapTotalMB:Math.round(memoryUsage.heapTotal/1024/1024*100)/100,heapUsagePercent:Math.round(memoryUsage.heapUsed/memoryUsage.heapTotal*100),rssMB:Math.round(memoryUsage.rss/1024/1024*100)/100},config:{ttlMs:this.ttlMs,maxHeapUsagePercent:this.maxHeapUsagePercent,watchFiles:this.watchFiles}}}getHitRate(){const total=this.stats.hits+this.stats.misses;return 0===total?0:Math.round(this.stats.hits/total*100)}logStats(log){const stats=this.getStats();log(`Cache Stats: ${stats.cache.size}/${stats.cache.maxSize} entries, ${stats.cache.memoryUsageMB}/${stats.cache.maxMemoryMB}MB, ${this.getHitRate()}% hit rate`,2)}getCachedFiles(){return Array.from(this.cache.keys()).map(filePath=>({path:filePath,relativePath:path.relative(process.cwd(),filePath),age:Date.now()-this.cache.get(filePath).timestamp,sizeKB:this.cache.get(filePath).sizeKB}))}}

package/dist/router.js

@@ -1 +1 @@
-import path from"path";import{readFile}from"fs/promises";import{pathToFileURL}from"url";import defaultConfig from"./defaultConfig.js";import getFiles from"./getFiles.js";import findFile from"./findFile.js";import serveFile from"./serveFile.js";import MiddlewareRunner from"./middlewareRunner.js";import{corsMiddleware,compressionMiddleware,rateLimitMiddleware,securityMiddleware,loggingMiddleware}from"./builtinMiddleware.js";export default async(flags,log)=>{log("Initializing router",2);const rootPath=path.join(process.cwd(),flags.root);log(`Root path: ${rootPath}`,2);let config=defaultConfig;try{const configFileName=flags.config||".config.json",configPath=path.isAbsolute(configFileName)?configFileName:path.join(rootPath,configFileName);log(`Loading config from: ${configPath}`,2);const configContent=await readFile(configPath,"utf8"),userConfig=JSON.parse(configContent);config={...defaultConfig,...userConfig,allowedMimes:{...defaultConfig.allowedMimes,...userConfig.allowedMimes},middleware:{...defaultConfig.middleware,...userConfig.middleware},customRoutes:{...defaultConfig.customRoutes,...userConfig.customRoutes}},log("User config loaded and merged with defaults",2)}catch(e){log("Using default config (no config file found)",2)}const dis=new Set(config.disallowedRegex);dis.add("^/\\..*"),dis.add("\\.config$"),dis.add("\\.git/"),config.disallowedRegex=[...dis],log(`Config loaded with ${config.disallowedRegex.length} disallowed patterns`,2);let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,1);const middlewareRunner=new MiddlewareRunner;if(config.middleware?.cors?.enabled&&(middlewareRunner.use(corsMiddleware(config.middleware.cors)),log("CORS middleware enabled",2)),config.middleware?.compression?.enabled&&(middlewareRunner.use(compressionMiddleware(config.middleware.compression)),log("Compression middleware enabled",2)),config.middleware?.rateLimit?.enabled&&(middlewareRunner.use(rateLimitMiddleware(config.middleware.rateLimit)),log("Rate limit middleware enabled",2)),config.middleware?.security?.enabled&&(middlewareRunner.use(securityMiddleware(config.middleware.security)),log("Security middleware enabled",2)),config.middleware?.logging?.enabled&&(middlewareRunner.use(loggingMiddleware(config.middleware.logging,log)),log("Logging middleware enabled",2)),config.middleware?.custom&&config.middleware.custom.length>0){log(`Loading ${config.middleware.custom.length} custom middleware files`,2);for(const middlewarePath of config.middleware.custom)try{const resolvedPath=path.resolve(middlewarePath),customMiddleware=(await import(pathToFileURL(resolvedPath))).default;"function"==typeof customMiddleware?(middlewareRunner.use(customMiddleware(config.middleware)),log(`Custom middleware loaded: ${middlewarePath}`,2)):log(`Custom middleware error: ${middlewarePath} does not export a default function`,1)}catch(error){log(`Custom middleware error for ${middlewarePath}: ${error.message}`,1)}}const customRoutes=new Map,wildcardRoutes=new Map;if(config.customRoutes&&Object.keys(config.customRoutes).length>0){log(`Processing ${Object.keys(config.customRoutes).length} custom routes`,2);for(const[urlPath,filePath]of Object.entries(config.customRoutes))try{if(urlPath.includes("*"))wildcardRoutes.set(urlPath,filePath),log(`Wildcard route mapped: ${urlPath} -> ${filePath}`,2);else{const resolvedPath=path.resolve(filePath),{stat:stat}=await import("fs/promises");await stat(resolvedPath),customRoutes.set(urlPath,resolvedPath),log(`Custom route mapped: ${urlPath} -> ${resolvedPath}`,2)}}catch(error){log(`Custom route error for ${urlPath} -> ${filePath}: ${error.message}`,1)}}const matchWildcardRoute=(requestPath,pattern)=>{const regexPattern=pattern.replace(/\*/g,"([^/]+)").replace(/\*\*/g,"(.+)");return new RegExp(`^${regexPattern}$`).exec(requestPath)},rescanAttempts=new Map,dynamicNoRescanPaths=new Set,shouldSkipRescan=requestPath=>config.noRescanPaths.some(pattern=>new RegExp(pattern).test(requestPath))?(log(`Skipping rescan for configured pattern: ${requestPath}`,3),!0):!!dynamicNoRescanPaths.has(requestPath)&&(log(`Skipping rescan for dynamically blacklisted path: ${requestPath}`,3),!0);return async(req,res)=>{await middlewareRunner.run(req,res,async()=>{const requestPath=req.url.split("?")[0];if(log(`${req.method} ${requestPath}`,0),customRoutes.has(requestPath)){const customFilePath=customRoutes.get(requestPath);log(`Serving custom route: ${requestPath} -> ${customFilePath}`,2);try{const fileContent=await readFile(customFilePath),fileExtension=path.extname(customFilePath).toLowerCase().slice(1),mimeType=config.allowedMimes[fileExtension]||"application/octet-stream";return log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`,2),res.writeHead(200,{"Content-Type":mimeType}),void res.end(fileContent)}catch(error){return log(`Error serving custom route ${requestPath}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Internal Server Error")}}const wildcardMatch=(requestPath=>{for(const[pattern,filePath]of wildcardRoutes){const matches=matchWildcardRoute(requestPath,pattern);if(matches)return{filePath:filePath,matches:matches}}return null})(requestPath);if(wildcardMatch){const resolvedFilePath=((filePath,matches)=>{let resolvedPath=filePath;for(let i=1;i<matches.length;i++)resolvedPath=resolvedPath.replace("*",matches[i]);return path.resolve(resolvedPath)})(wildcardMatch.filePath,wildcardMatch.matches);log(`Serving wildcard route: ${requestPath} -> ${resolvedFilePath}`,2);try{const fileContent=await readFile(resolvedFilePath),fileExtension=path.extname(resolvedFilePath).toLowerCase().slice(1),mimeType=config.allowedMimes[fileExtension]||"application/octet-stream";return log(`Serving wildcard file as ${mimeType} (${fileContent.length} bytes)`,2),res.writeHead(200,{"Content-Type":mimeType}),void res.end(fileContent)}catch(error){return log(`Error serving wildcard route ${requestPath}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Internal Server Error")}}const served=await serveFile(files,rootPath,requestPath,req.method,config,req,res,log);if(served||!flags.scan||shouldSkipRescan(requestPath))served||(shouldSkipRescan(requestPath)?log(`404 - Skipped rescan for: ${requestPath}`,2):log(`404 - File not found: ${requestPath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),res.end("Not Found"));else{(requestPath=>{const newAttempts=(rescanAttempts.get(requestPath)||0)+1;rescanAttempts.set(requestPath,newAttempts),newAttempts>=config.maxRescanAttempts&&(dynamicNoRescanPaths.add(requestPath),log(`Path ${requestPath} added to dynamic blacklist after ${newAttempts} failed attempts`,1)),log(`Rescan attempt ${newAttempts}/${config.maxRescanAttempts} for: ${requestPath}`,2)})(requestPath),log("File not found, rescanning directory...",1),files=await getFiles(rootPath,config,log),log(`Rescan found ${files.length} files`,2);await serveFile(files,rootPath,requestPath,req.method,config,req,res,log)||(log(`404 - File not found after rescan: ${requestPath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),res.end("Not Found"))}})}};
+import path from"path";import{readFile}from"fs/promises";import{pathToFileURL}from"url";import defaultConfig from"./defaultConfig.js";import getFiles from"./getFiles.js";import findFile from"./findFile.js";import serveFile from"./serveFile.js";import MiddlewareRunner from"./middlewareRunner.js";import ModuleCache from"./moduleCache.js";import{corsMiddleware,compressionMiddleware,rateLimitMiddleware,securityMiddleware,loggingMiddleware}from"./builtinMiddleware.js";export default async(flags,log)=>{log("Initializing router",2);const rootPath=path.isAbsolute(flags.root)?flags.root:path.join(process.cwd(),flags.root);log(`Root path: ${rootPath}`,2);let config=defaultConfig;try{const configFileName=flags.config||".config.json",configPath=path.isAbsolute(configFileName)?configFileName:path.join(rootPath,configFileName);if(log(`Config file name: ${configFileName}`,2),log(`Config path: ${configPath}`,2),path.isAbsolute(configFileName))log("Config file name is absolute, skipping validation",2);else{const relativeConfigPath=path.relative(rootPath,configPath);if(log(`Relative config path: ${relativeConfigPath}`,2),log(`Starts with '..': ${relativeConfigPath.startsWith("..")}`,2),relativeConfigPath.startsWith("..")||path.isAbsolute(relativeConfigPath))throw log("Validation failed - throwing error",2),new Error(`Config file must be within the server root directory. Config path: ${configPath}, Root path: ${rootPath}`);log("Validation passed",2)}log(`Loading config from: ${configPath}`,2);const configContent=await readFile(configPath,"utf8"),userConfig=JSON.parse(configContent);config={...defaultConfig,...userConfig,allowedMimes:{...defaultConfig.allowedMimes,...userConfig.allowedMimes},middleware:{...defaultConfig.middleware,...userConfig.middleware},customRoutes:{...defaultConfig.customRoutes,...userConfig.customRoutes},cache:{...defaultConfig.cache,...userConfig.cache}},log("User config loaded and merged with defaults",2)}catch(e){if(e.message.includes("Config file must be within the server root directory"))throw e;log("Using default config (no config file found)",2)}const dis=new Set(config.disallowedRegex);dis.add("^/\\..*"),dis.add("\\.config$"),dis.add("\\.git/"),config.disallowedRegex=[...dis],log(`Config loaded with ${config.disallowedRegex.length} disallowed patterns`,2);let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,1);const middlewareRunner=new MiddlewareRunner;if(config.middleware?.cors?.enabled&&(middlewareRunner.use(corsMiddleware(config.middleware.cors)),log("CORS middleware enabled",2)),config.middleware?.compression?.enabled&&(middlewareRunner.use(compressionMiddleware(config.middleware.compression)),log("Compression middleware enabled",2)),config.middleware?.rateLimit?.enabled&&(middlewareRunner.use(rateLimitMiddleware(config.middleware.rateLimit)),log("Rate limit middleware enabled",2)),config.middleware?.security?.enabled&&(middlewareRunner.use(securityMiddleware(config.middleware.security)),log("Security middleware enabled",2)),config.middleware?.logging?.enabled&&(middlewareRunner.use(loggingMiddleware(config.middleware.logging,log)),log("Logging middleware enabled",2)),config.middleware?.custom&&config.middleware.custom.length>0){log(`Loading ${config.middleware.custom.length} custom middleware files`,2);for(const middlewarePath of config.middleware.custom)try{const resolvedPath=path.resolve(middlewarePath),customMiddleware=(await import(pathToFileURL(resolvedPath))).default;"function"==typeof customMiddleware?(middlewareRunner.use(customMiddleware(config.middleware)),log(`Custom middleware loaded: ${middlewarePath}`,2)):log(`Custom middleware error: ${middlewarePath} does not export a default function`,1)}catch(error){log(`Custom middleware error for ${middlewarePath}: ${error.message}`,1)}}let moduleCache=null;config.cache?.enabled&&(moduleCache=new ModuleCache(config.cache),log(`Module cache initialized: ${config.cache.maxSize} max modules, ${config.cache.maxMemoryMB}MB limit, ${config.cache.ttlMs}ms TTL`,2));const customRoutes=new Map,wildcardRoutes=new Map;if(config.customRoutes&&Object.keys(config.customRoutes).length>0){log(`Processing ${Object.keys(config.customRoutes).length} custom routes`,2);for(const[urlPath,filePath]of Object.entries(config.customRoutes))if(urlPath.includes("*")){const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);wildcardRoutes.set(urlPath,resolvedPath),log(`Wildcard route mapped: ${urlPath} -> ${resolvedPath}`,2)}else{const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);customRoutes.set(urlPath,resolvedPath),log(`Custom route mapped: ${urlPath} -> ${resolvedPath}`,2)}}const matchWildcardRoute=(requestPath,pattern)=>{const regexPattern=pattern.replace(/\*\*/g,"(.+)").replace(/\*/g,"([^/]+)");return new RegExp(`^${regexPattern}$`).exec(requestPath)},rescanAttempts=new Map,dynamicNoRescanPaths=new Set,shouldSkipRescan=requestPath=>config.noRescanPaths.some(pattern=>new RegExp(pattern).test(requestPath))?(log(`Skipping rescan for configured pattern: ${requestPath}`,3),!0):!!dynamicNoRescanPaths.has(requestPath)&&(log(`Skipping rescan for dynamically blacklisted path: ${requestPath}`,3),!0),handler=async(req,res)=>{await middlewareRunner.run(req,res,async()=>{const requestPath=req.url.split("?")[0];log(`${req.method} ${requestPath}`,0),log(`customRoutes keys: ${Array.from(customRoutes.keys()).join(", ")}`,1);const normalizePath=p=>{let np=decodeURIComponent(p);return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np},normalizedRequestPath=normalizePath(requestPath);log(`Normalized requestPath: ${normalizedRequestPath}`,1);let matchedKey=null;for(const key of customRoutes.keys())if(normalizePath(key)===normalizedRequestPath){matchedKey=key;break}if(matchedKey){const customFilePath=customRoutes.get(matchedKey);log(`Serving custom route: ${normalizedRequestPath} -> ${customFilePath}`,2);try{const{stat:stat}=await import("fs/promises");try{await stat(customFilePath),log(`Custom route file exists: ${customFilePath}`,2)}catch(e){return log(`Custom route file does NOT exist: ${customFilePath}`,0),res.writeHead(404,{"Content-Type":"text/plain"}),void res.end("Custom route file not found")}const fileContent=await readFile(customFilePath),fileExtension=path.extname(customFilePath).toLowerCase().slice(1),mimeType=config.allowedMimes[fileExtension]||"application/octet-stream";return log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`,2),res.writeHead(200,{"Content-Type":mimeType}),void res.end(fileContent)}catch(error){return log(`Error serving custom route ${normalizedRequestPath}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Internal Server Error")}}const wildcardMatch=(requestPath=>{for(const[pattern,filePath]of wildcardRoutes){const matches=matchWildcardRoute(requestPath,pattern);if(matches)return{filePath:filePath,matches:matches}}return null})(requestPath);if(wildcardMatch){const resolvedFilePath=((filePath,matches)=>{let resolvedPath=filePath,matchIndex=1;for(;resolvedPath.includes("**")&&matchIndex<matches.length;)resolvedPath=resolvedPath.replace("**",matches[matchIndex]),matchIndex++;for(;resolvedPath.includes("*")&&matchIndex<matches.length;)resolvedPath=resolvedPath.replace("*",matches[matchIndex]),matchIndex++;return path.isAbsolute(resolvedPath)?resolvedPath:path.resolve(rootPath,resolvedPath)})(wildcardMatch.filePath,wildcardMatch.matches);log(`Serving wildcard route: ${requestPath} -> ${resolvedFilePath}`,2);try{const fileContent=await readFile(resolvedFilePath),fileExtension=path.extname(resolvedFilePath).toLowerCase().slice(1),mimeType=config.allowedMimes[fileExtension]||"application/octet-stream";return log(`Serving wildcard file as ${mimeType} (${fileContent.length} bytes)`,2),res.writeHead(200,{"Content-Type":mimeType}),void res.end(fileContent)}catch(error){return log(`Error serving wildcard route ${requestPath}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),void res.end("Internal Server Error")}}const served=await serveFile(files,rootPath,requestPath,req.method,config,req,res,log,moduleCache);if(served||!flags.scan||shouldSkipRescan(requestPath))served||(shouldSkipRescan(requestPath)?log(`404 - Skipped rescan for: ${requestPath}`,2):log(`404 - File not found: ${requestPath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),res.end("Not Found"));else{(requestPath=>{const newAttempts=(rescanAttempts.get(requestPath)||0)+1;rescanAttempts.set(requestPath,newAttempts),newAttempts>=config.maxRescanAttempts&&(dynamicNoRescanPaths.add(requestPath),log(`Path ${requestPath} added to dynamic blacklist after ${newAttempts} failed attempts`,1)),log(`Rescan attempt ${newAttempts}/${config.maxRescanAttempts} for: ${requestPath}`,2)})(requestPath),log("File not found, rescanning directory...",1),files=await getFiles(rootPath,config,log),log(`Rescan found ${files.length} files`,2);await serveFile(files,rootPath,requestPath,req.method,config,req,res,log,moduleCache)||(log(`404 - File not found after rescan: ${requestPath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),res.end("Not Found"))}})};return handler.moduleCache=moduleCache,handler.getStats=()=>moduleCache?.getStats()||null,handler.logCacheStats=()=>moduleCache?.logStats(log),handler.clearCache=()=>moduleCache?.clear(),handler};

package/dist/serveFile.js

@@ -1 +1 @@
-import path from"path";import{readFile}from"fs/promises";import{pathToFileURL}from"url";import findFile from"./findFile.js";import createRequestWrapper from"./requestWrapper.js";import createResponseWrapper from"./responseWrapper.js";export default async(files,rootPath,requestPath,method,config,req,res,log)=>{log(`Attempting to serve: ${requestPath}`,3);const[file,params]=await findFile(files,rootPath,requestPath,method,log);if(!file)return log(`No file found for: ${requestPath}`,3),!1;const fileName=path.basename(file);if(log(`Found file: ${file}`,2),config.routeFiles.includes(fileName)){log(`Executing route file: ${fileName}`,2);try{const fileUrl=pathToFileURL(file).href;log(`Loading module from: ${fileUrl}`,3);const module=await import(fileUrl);if("function"==typeof module.default){log(`Executing route function with params: ${JSON.stringify(params)}`,3);const enhancedRequest=createRequestWrapper(req,params),enhancedResponse=createResponseWrapper(res);return await module.default(enhancedRequest,enhancedResponse),log(`Route executed successfully: ${fileName}`,2),!0}return log(`Route file does not export a function: ${fileName}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Route file does not export a function"),!0}catch(error){return log(`Error loading route file ${fileName}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}else{log(`Serving static file: ${fileName}`,2);try{const fileContent=await readFile(file),fileExtension=path.extname(file).toLowerCase().slice(1),mimeType=config.allowedMimes[fileExtension]||"application/octet-stream";return log(`Serving ${file} as ${mimeType} (${fileContent.length} bytes)`,2),res.writeHead(200,{"Content-Type":mimeType}),res.end(fileContent),!0}catch(error){return log(`Error reading file ${file}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}};
+import path from"path";import{readFile,stat}from"fs/promises";import{pathToFileURL}from"url";import findFile from"./findFile.js";import createRequestWrapper from"./requestWrapper.js";import createResponseWrapper from"./responseWrapper.js";export default async(files,rootPath,requestPath,method,config,req,res,log,moduleCache=null)=>{log(`Attempting to serve: ${requestPath}`,3);const[file,params]=await findFile(files,rootPath,requestPath,method,log);if(!file)return log(`No file found for: ${requestPath}`,3),!1;const fileName=path.basename(file);if(log(`Found file: ${file}`,2),config.routeFiles.includes(fileName)){log(`Executing route file: ${fileName}`,2);try{let module;if(moduleCache&&config.cache?.enabled){const fileStats=await stat(file);if(module=moduleCache.get(file,fileStats),module)log(`Using cached module: ${fileName}`,3);else{const fileUrl=pathToFileURL(file).href+`?t=${Date.now()}`;log(`Loading module from: ${fileUrl}`,3),module=await import(fileUrl);const estimatedSizeKB=fileStats.size/1024;moduleCache.set(file,module,fileStats,estimatedSizeKB),log(`Cached module: ${fileName} (${estimatedSizeKB.toFixed(1)}KB)`,3)}}else{const fileUrl=pathToFileURL(file).href+`?t=${Date.now()}`;log(`Loading module from: ${fileUrl}`,3),module=await import(fileUrl)}if("function"==typeof module.default){log(`Executing route function with params: ${JSON.stringify(params)}`,3);const enhancedRequest=createRequestWrapper(req,params),enhancedResponse=createResponseWrapper(res);return moduleCache&&(enhancedRequest._kempoCache=moduleCache),await module.default(enhancedRequest,enhancedResponse),log(`Route executed successfully: ${fileName}`,2),!0}return log(`Route file does not export a function: ${fileName}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Route file does not export a function"),!0}catch(error){return log(`Error loading route file ${fileName}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}else{log(`Serving static file: ${fileName}`,2);try{const fileContent=await readFile(file),fileExtension=path.extname(file).toLowerCase().slice(1),mimeType=config.allowedMimes[fileExtension]||"application/octet-stream";return log(`Serving ${file} as ${mimeType} (${fileContent.length} bytes)`,2),res.writeHead(200,{"Content-Type":mimeType}),res.end(fileContent),!0}catch(error){return log(`Error reading file ${file}: ${error.message}`,0),res.writeHead(500,{"Content-Type":"text/plain"}),res.end("Internal Server Error"),!0}}};