kempo-server 1.9.13 → 1.9.15

package/README.md

@@ -342,6 +342,8 @@ Kempo Server supports several command line options to customize its behavior:
 kempo-server --root public --port 8080 --host 0.0.0.0 --verbose
 ```
 
+**Note:** To enable automatic rescanning for new files during development, set `maxRescanAttempts` in your config file (default is 3). Set to 0 to disable rescanning.
+
 ## Testing
 
 This project uses the Kempo Testing Framework. Tests live in the `tests/` folder and follow these naming conventions:

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import http from"http";import router from"./router.js";import getFlags from"./getFlags.js";const flags=getFlags(process.argv.slice(2),{port:3e3,logging:2,root:"./",scan:!1,config:".config.json"},{p:"port",l:"logging",r:"root",s:"scan",c:"config"});if("string"==typeof flags.logging)switch(flags.logging.toLowerCase()){case"silent":flags.logging=0;break;case"minimal":flags.logging=1;break;case"verbose":flags.logging=3;break;case"debug":flags.logging=4;break;default:flags.logging=2}const log=(message,level=2)=>{level<=flags.logging&&console.log(message)};http.createServer(await router(flags,log)).listen(flags.port),log(`Server started at: http://localhost:${flags.port}`);
+import http from"http";import router from"./router.js";import getFlags from"./getFlags.js";const flags=getFlags(process.argv.slice(2),{port:3e3,logging:2,root:"./",config:".config.json"},{p:"port",l:"logging",r:"root",c:"config"});if("string"==typeof flags.logging)switch(flags.logging.toLowerCase()){case"silent":flags.logging=0;break;case"minimal":flags.logging=1;break;case"verbose":flags.logging=3;break;case"debug":flags.logging=4;break;default:flags.logging=2}const log=(message,level=2)=>{level<=flags.logging&&console.log(message)};http.createServer(await router(flags,log)).listen(flags.port),log(`Server started at: http://localhost:${flags.port}`);

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 ModuleCache from"./moduleCache.js";import{corsMiddleware,compressionMiddleware,rateLimitMiddleware,securityMiddleware,loggingMiddleware}from"./builtinMiddleware.js";export default async(flags,log)=>{log("Initializing router",3);const rootPath=path.isAbsolute(flags.root)?flags.root:path.join(process.cwd(),flags.root);log(`Root path: ${rootPath}`,3);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}`,3),log(`Config path: ${configPath}`,3),path.isAbsolute(configFileName))log("Config file name is absolute, skipping validation",4);else{const relativeConfigPath=path.relative(rootPath,configPath);if(log(`Relative config path: ${relativeConfigPath}`,4),log(`Starts with '..': ${relativeConfigPath.startsWith("..")}`,4),relativeConfigPath.startsWith("..")||path.isAbsolute(relativeConfigPath))throw log("Validation failed - throwing error",4),new Error(`Config file must be within the server root directory. Config path: ${configPath}, Root path: ${rootPath}`);log("Validation passed",4)}log(`Loading config from: ${configPath}`,3);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",3)}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)",3)}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`,3);let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,2);const middlewareRunner=new MiddlewareRunner;if(config.middleware?.cors?.enabled&&(middlewareRunner.use(corsMiddleware(config.middleware.cors)),log("CORS middleware enabled",3)),config.middleware?.compression?.enabled&&(middlewareRunner.use(compressionMiddleware(config.middleware.compression)),log("Compression middleware enabled",3)),config.middleware?.rateLimit?.enabled&&(middlewareRunner.use(rateLimitMiddleware(config.middleware.rateLimit)),log("Rate limit middleware enabled",3)),config.middleware?.security?.enabled&&(middlewareRunner.use(securityMiddleware(config.middleware.security)),log("Security middleware enabled",3)),config.middleware?.logging?.enabled&&(middlewareRunner.use(loggingMiddleware(config.middleware.logging,log)),log("Logging middleware enabled",3)),config.middleware?.custom&&config.middleware.custom.length>0){log(`Loading ${config.middleware.custom.length} custom middleware files`,3);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}`,3)):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`,3);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}`,3)}else{const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);customRoutes.set(urlPath,resolvedPath),log(`Custom route mapped: ${urlPath} -> ${resolvedPath}`,3)}}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}`,4),log(`customRoutes keys: ${Array.from(customRoutes.keys()).join(", ")}`,4);const normalizePath=p=>{try{let np=decodeURIComponent(p);return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}catch(e){log(`Warning: Failed to decode URI component "${p}": ${e.message}`,1);let np=p;return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}},normalizedRequestPath=normalizePath(requestPath);log(`Normalized requestPath: ${normalizedRequestPath}`,4);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}`,3);try{const{stat:stat}=await import("fs/promises");try{await stat(customFilePath),log(`Custom route file exists: ${customFilePath}`,4)}catch(e){return log(`Custom route file does NOT exist: ${customFilePath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),void res.end("Custom route file not found")}const fileExtension=path.extname(customFilePath).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(customFilePath,encoding);log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`,2);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),void res.end(fileContent)}catch(error){return log(`Error serving custom route ${normalizedRequestPath}: ${error.message}`,1),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}`,3);try{const fileExtension=path.extname(resolvedFilePath).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(resolvedFilePath,encoding);log(`Serving wildcard file as ${mimeType} (${fileContent.length} bytes)`,4);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),void res.end(fileContent)}catch(error){return log(`Error serving wildcard route ${requestPath}: ${error.message}`,1),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{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)?rescanAttempts.delete(requestPath):((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}`,3)})(requestPath),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};
+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",3);const rootPath=path.isAbsolute(flags.root)?flags.root:path.join(process.cwd(),flags.root);log(`Root path: ${rootPath}`,3);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}`,3),log(`Config path: ${configPath}`,3),path.isAbsolute(configFileName))log("Config file name is absolute, skipping validation",4);else{const relativeConfigPath=path.relative(rootPath,configPath);if(log(`Relative config path: ${relativeConfigPath}`,4),log(`Starts with '..': ${relativeConfigPath.startsWith("..")}`,4),relativeConfigPath.startsWith("..")||path.isAbsolute(relativeConfigPath))throw log("Validation failed - throwing error",4),new Error(`Config file must be within the server root directory. Config path: ${configPath}, Root path: ${rootPath}`);log("Validation passed",4)}log(`Loading config from: ${configPath}`,3);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",3)}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)",3)}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`,3);let files=await getFiles(rootPath,config,log);log(`Initial scan found ${files.length} files`,2);const middlewareRunner=new MiddlewareRunner;if(config.middleware?.cors?.enabled&&(middlewareRunner.use(corsMiddleware(config.middleware.cors)),log("CORS middleware enabled",3)),config.middleware?.compression?.enabled&&(middlewareRunner.use(compressionMiddleware(config.middleware.compression)),log("Compression middleware enabled",3)),config.middleware?.rateLimit?.enabled&&(middlewareRunner.use(rateLimitMiddleware(config.middleware.rateLimit)),log("Rate limit middleware enabled",3)),config.middleware?.security?.enabled&&(middlewareRunner.use(securityMiddleware(config.middleware.security)),log("Security middleware enabled",3)),config.middleware?.logging?.enabled&&(middlewareRunner.use(loggingMiddleware(config.middleware.logging,log)),log("Logging middleware enabled",3)),config.middleware?.custom&&config.middleware.custom.length>0){log(`Loading ${config.middleware.custom.length} custom middleware files`,3);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}`,3)):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`,3);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}`,3)}else{const resolvedPath=path.isAbsolute(filePath)?filePath:path.resolve(rootPath,filePath);customRoutes.set(urlPath,resolvedPath),log(`Custom route mapped: ${urlPath} -> ${resolvedPath}`,3)}}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}`,4),log(`customRoutes keys: ${Array.from(customRoutes.keys()).join(", ")}`,4);const normalizePath=p=>{try{let np=decodeURIComponent(p);return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}catch(e){log(`Warning: Failed to decode URI component "${p}": ${e.message}`,1);let np=p;return np.startsWith("/")||(np="/"+np),np.length>1&&np.endsWith("/")&&(np=np.slice(0,-1)),np}},normalizedRequestPath=normalizePath(requestPath);log(`Normalized requestPath: ${normalizedRequestPath}`,4);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}`,3);try{const{stat:stat}=await import("fs/promises");try{await stat(customFilePath),log(`Custom route file exists: ${customFilePath}`,4)}catch(e){return log(`Custom route file does NOT exist: ${customFilePath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),void res.end("Custom route file not found")}const fileExtension=path.extname(customFilePath).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(customFilePath,encoding);log(`Serving custom file as ${mimeType} (${fileContent.length} bytes)`,2);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),void res.end(fileContent)}catch(error){return log(`Error serving custom route ${normalizedRequestPath}: ${error.message}`,1),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}`,3);try{const fileExtension=path.extname(resolvedFilePath).toLowerCase().slice(1),mimeConfig=config.allowedMimes[fileExtension];let mimeType,encoding;"string"==typeof mimeConfig?(mimeType=mimeConfig,encoding=mimeType.startsWith("text/")?"utf8":void 0):(mimeType=mimeConfig?.mime||"application/octet-stream",encoding="utf8"===mimeConfig?.encoding?"utf8":void 0);const fileContent=await readFile(resolvedFilePath,encoding);log(`Serving wildcard file as ${mimeType} (${fileContent.length} bytes)`,4);const contentType="utf8"===encoding&&mimeType.startsWith("text/")?`${mimeType}; charset=utf-8`:mimeType;return res.writeHead(200,{"Content-Type":contentType}),void res.end(fileContent)}catch(error){return log(`Error serving wildcard route ${requestPath}: ${error.message}`,1),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&&config.maxRescanAttempts>0&&!shouldSkipRescan(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)?rescanAttempts.delete(requestPath):((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}`,3)})(requestPath),log(`404 - File not found after rescan: ${requestPath}`,1),res.writeHead(404,{"Content-Type":"text/plain"}),res.end("Not Found"))}else 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"))})};return handler.moduleCache=moduleCache,handler.getStats=()=>moduleCache?.getStats()||null,handler.logCacheStats=()=>moduleCache?.logStats(log),handler.clearCache=()=>moduleCache?.clear(),handler};

package/docs/getting-started.html

@@ -60,7 +60,7 @@
 
     <h3>Configuration File Examples</h3>
     <p>You can specify different configuration files for different environments:</p>
-    <pre><code class="hljs bash"># Development<br />kempo-server --root public --config dev.config.json<br /><br /># Staging<br />kempo-server --root public --config staging.config.json<br /><br /># Production with absolute path<br />kempo-server --root public --config /etc/kempo/production.config.json<br /><br /># Mix with other options<br />kempo-server --root dist --port 8080 --config production.config.json --scan</code></pre>
+    <pre><code class="hljs bash"># Development<br />kempo-server --root public --config dev.config.json<br /><br /># Staging<br />kempo-server --root public --config staging.config.json<br /><br /># Production with absolute path<br />kempo-server --root public --config /etc/kempo/production.config.json<br /><br /># Mix with other options<br />kempo-server --root dist --port 8080 --config production.config.json</code></pre>
 
     <h2>What's Next?</h2>
     <p>Now that you have Kempo Server running, explore these topics:</p>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kempo-server",
   "type": "module",
-  "version": "1.9.13",
+  "version": "1.9.15",
   "description": "A lightweight, zero-dependency, file based routing server.",
   "main": "dist/index.js",
   "exports": {

package/src/index.js

@@ -7,13 +7,11 @@ const flags = getFlags(process.argv.slice(2), {
   port: 3000,
   logging: 2,
   root: './',
-  scan: false,
   config: '.config.json'
 }, {
   p: 'port',
   l: 'logging',
   r: 'root',
-  s: 'scan',
   c: 'config'
 });
 

package/src/router.js

@@ -254,7 +254,7 @@ export default async (flags, log) => {
     const newAttempts = currentAttempts + 1;
     rescanAttempts.set(requestPath, newAttempts);
     
-    if (newAttempts >= config.maxRescanAttempts) {
+    if (newAttempts > config.maxRescanAttempts) {
       dynamicNoRescanPaths.add(requestPath);
       log(`Path ${requestPath} added to dynamic blacklist after ${newAttempts} failed attempts`, 1);
     }
@@ -375,8 +375,8 @@ export default async (flags, log) => {
       // Try to serve the file normally
       const served = await serveFile(files, rootPath, requestPath, req.method, config, req, res, log, moduleCache);
       
-      // If not served and scan flag is enabled, try rescanning once (with blacklist check)
-      if (!served && flags.scan && !shouldSkipRescan(requestPath)) {
+      // If not served and rescanning is enabled (maxRescanAttempts > 0), try rescanning (with blacklist check)
+      if (!served && config.maxRescanAttempts > 0 && !shouldSkipRescan(requestPath)) {
         log('File not found, rescanning directory...', 1);
         files = await getFiles(rootPath, config, log);
         log(`Rescan found ${files.length} files`, 2);

package/tests/config-flag.node-test.js

@@ -1,4 +1,4 @@
-import http from 'http';
+import http from 'http';
 import path from 'path';
 import {withTempDir} from './utils/temp-dir.js';
 import {write} from './utils/file-writer.js';
@@ -14,13 +14,11 @@ export default {
       port: 3000,
       logging: 2,
       root: './',
-      scan: false,
       config: '.config.json'
     }, {
       p: 'port',
       l: 'logging',
       r: 'root',
-      s: 'scan',
       c: 'config'
     });
     
@@ -43,13 +41,11 @@ export default {
       port: 3000,
       logging: 2,
       root: './',
-      scan: false,
       config: '.config.json'
     }, {
       p: 'port',
       l: 'logging',
       r: 'root',
-      s: 'scan',
       c: 'config'
     });
     
@@ -69,13 +65,11 @@ export default {
       port: 3000,
       logging: 2,
       root: './',
-      scan: false,
       config: '.config.json'
     }, {
       p: 'port',
       l: 'logging',
       r: 'root',
-      s: 'scan',
       c: 'config'
     });
     
@@ -103,7 +97,7 @@ export default {
       
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false, config: '.config.json'};
+      const flags = {root: '.', logging: 0, rescan: false, config: '.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -142,7 +136,7 @@ export default {
       
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false, config: 'dev.config.json'};
+      const flags = {root: '.', logging: 0, rescan: false, config: 'dev.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -182,7 +176,7 @@ export default {
       
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false, config: configPath};
+      const flags = {root: '.', logging: 0, rescan: false, config: configPath};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -214,7 +208,7 @@ export default {
       const prev = process.cwd();
       process.chdir(dir);
       // Point to non-existent config file
-      const flags = {root: '.', logging: 0, scan: false, config: 'nonexistent.config.json'};
+      const flags = {root: '.', logging: 0, rescan: false, config: 'nonexistent.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -247,7 +241,7 @@ export default {
       
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false, config: 'bad.config.json'};
+      const flags = {root: '.', logging: 0, rescan: false, config: 'bad.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -287,7 +281,7 @@ export default {
       
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false, config: 'partial.config.json'};
+      const flags = {root: '.', logging: 0, rescan: false, config: 'partial.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -336,7 +330,7 @@ export default {
       
       try {
         // Try to use config file outside server root with relative path
-        const flags = {root: '.', logging: 0, scan: false, config: '../config-outside-root/outside.config.json'};
+        const flags = {root: '.', logging: 0, rescan: false, config: '../config-outside-root/outside.config.json'};
         
         log('Test setup:');
         log('dir: ' + dir);

package/tests/getFlags.node-test.js

@@ -2,20 +2,20 @@ import getFlags from '../src/getFlags.js';
 
 export default {
   'parses long flags with values and booleans': async ({pass, fail}) => {
-    const args = ['--port', '8080', '--scan'];
-    const flags = getFlags(args, {port: 3000, scan: false});
+    const args = ['--port', '8080', '--verbose'];
+    const flags = getFlags(args, {port: 3000, verbose: false});
     
     if(flags.port !== '8080') return fail('port not parsed');
-    if(flags.scan !== true) return fail('scan boolean not parsed');
+    if(flags.verbose !== true) return fail('verbose boolean not parsed');
     
     pass('parsed long flags');
   },
   'parses short flags using map and preserves defaults': async ({pass, fail}) => {
-    const args = ['-p', '9090', '-s'];
-    const flags = getFlags(args, {port: 3000, scan: false}, {p: 'port', s: 'scan'});
+    const args = ['-p', '9090', '-v'];
+    const flags = getFlags(args, {port: 3000, verbose: false}, {p: 'port', v: 'verbose'});
     
     if(flags.port !== '9090') return fail('short mapped value failed');
-    if(flags.scan !== true) return fail('short mapped boolean failed');
+    if(flags.verbose !== true) return fail('short mapped boolean failed');
     
     pass('short flags parsed');
   },

package/tests/mimeTypes-merge.node-test.js

@@ -1,4 +1,4 @@
-import defaultConfig from '../src/defaultConfig.js';
+import defaultConfig from '../src/defaultConfig.js';
 import router from '../src/router.js';
 import http from 'http';
 import { mkdtemp, writeFile, rm } from 'fs/promises';
@@ -49,7 +49,7 @@ export default {
   if(mergedConfig.js.mime !== 'text/javascript' || mergedConfig.js.encoding !== 'utf8') return fail('js mime/encoding merge failed');
   if(mergedConfig.css.mime !== 'text/css' || mergedConfig.css.encoding !== 'utf8') return fail('css mime/encoding merge failed');
       
-      const flags = {root: dir, logging: 0, scan: false, config: '.config.json'};
+      const flags = {root: dir, logging: 0, config: '.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -103,7 +103,7 @@ export default {
       await write(dir, 'test.js', 'console.log("test");');
       await write(dir, 'test.custom', 'custom content');
       
-      const flags = {root: dir, logging: 0, scan: false, config: '.config.json'};
+      const flags = {root: dir, logging: 0, config: '.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -151,7 +151,7 @@ export default {
       await write(dir, 'test.png', 'fake png');
       await write(dir, 'test.custom', 'custom');
       
-      const flags = {root: dir, logging: 0, scan: false, config: '.config.json'};
+      const flags = {root: dir, logging: 0, config: '.config.json'};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);

package/tests/router-maxRescanAttempts.node-test.js

@@ -1,4 +1,4 @@
-import http from 'http';
+import http from 'http';
 import {withTestDir} from './utils/test-dir.js';
 import {write} from './utils/file-writer.js';
 import {randomPort} from './utils/port.js';
@@ -10,7 +10,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: true};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       
       await write(dir, '.config.json', JSON.stringify({
@@ -55,7 +55,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: true};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       
       await write(dir, '.config.json', JSON.stringify({
@@ -103,7 +103,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: true};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       
       await write(dir, '.config.json', JSON.stringify({
@@ -144,7 +144,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: true};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       
       await write(dir, '.config.json', JSON.stringify({
@@ -206,7 +206,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: true};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       
       await write(dir, '.config.json', JSON.stringify({
@@ -242,13 +242,17 @@ export default {
     pass('respects noRescanPaths patterns');
   },
 
-  'scan flag disabled prevents rescanning': async ({pass, fail}) => {
+  'maxRescanAttempts set to 0 disables rescanning': async ({pass, fail}) => {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       
+      await write(dir, '.config.json', JSON.stringify({
+        maxRescanAttempts: 0
+      }));
+      
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
       const port = randomPort();
@@ -268,12 +272,12 @@ export default {
       if(stillMiss.res.statusCode !== 404) {
         server.close();
         process.chdir(prev);
-        return fail('should not rescan when scan flag is disabled');
+        return fail('should not rescan when maxRescanAttempts is 0');
       }
       
       server.close();
       process.chdir(prev);
     });
-    pass('scan disabled prevents rescan');
+    pass('maxRescanAttempts: 0 disables rescan');
   }
 };

package/tests/router-wildcard-double-asterisk.node-test.js

@@ -1,4 +1,4 @@
-import http from 'http';
+import http from 'http';
 import path from 'path';
 import {withTempDir} from './utils/temp-dir.js';
 import {write} from './utils/file-writer.js';
@@ -23,7 +23,7 @@ export default {
         const prev = process.cwd();
         process.chdir(dir);
         
-        const flags = {root: 'docs', logging: 0, scan: false};
+        const flags = {root: 'docs', logging: 0};
         const logFn = () => {};
         
         // Configure double asterisk wildcard route
@@ -84,7 +84,7 @@ export default {
         const prev = process.cwd();
         process.chdir(dir);
         
-        const flags = {root: 'docs', logging: 0, scan: false};
+        const flags = {root: 'docs', logging: 0};
         const logFn = () => {};
         
         // Configure single asterisk wildcard route
@@ -138,7 +138,7 @@ export default {
         const prev = process.cwd();
         process.chdir(dir);
         
-        const flags = {root: 'docs', logging: 0, scan: false};
+        const flags = {root: 'docs', logging: 0};
         const logFn = () => {};
         
         // Configure wildcard route that overrides static file
@@ -188,7 +188,7 @@ export default {
         process.chdir(dir);
         
         // Server root is the current directory (dir)
-        const flags = {root: '.', logging: 0, scan: false};
+        const flags = {root: '.', logging: 0};
         const logFn = () => {};
         
         // Configure wildcard route to serve from ./src/**

package/tests/router-wildcard.node-test.js

@@ -1,4 +1,4 @@
-import http from 'http';
+import http from 'http';
 import path from 'path';
 import {withTempDir} from './utils/temp-dir.js';
 import {write} from './utils/file-writer.js';
@@ -23,7 +23,7 @@ export default {
         const prev = process.cwd();
         process.chdir(dir);
         
-        const flags = {root: 'docs', logging: 0, scan: false};
+        const flags = {root: 'docs', logging: 0};
         const logFn = () => {};
         
         // Configure double asterisk wildcard route
@@ -84,7 +84,7 @@ export default {
         const prev = process.cwd();
         process.chdir(dir);
         
-        const flags = {root: 'docs', logging: 0, scan: false};
+        const flags = {root: 'docs', logging: 0};
         const logFn = () => {};
         
         // Configure single asterisk wildcard route
@@ -138,7 +138,7 @@ export default {
         const prev = process.cwd();
         process.chdir(dir);
         
-        const flags = {root: 'docs', logging: 0, scan: false};
+        const flags = {root: 'docs', logging: 0};
         const logFn = () => {};
         
         // Configure wildcard route that overrides static file

package/tests/router.node-test.js

@@ -1,4 +1,4 @@
-import http from 'http';
+import http from 'http';
 import path from 'path';
 import {withTestDir} from './utils/test-dir.js';
 import {write} from './utils/file-writer.js';
@@ -13,7 +13,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);
@@ -44,7 +44,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: true};
+      const flags = {root: '.', logging: 0};
       const handler = await router(flags, log);
       const server = http.createServer(handler);
       const port = randomPort();
@@ -77,7 +77,7 @@ export default {
       const fileB = path.join(dir, 'b/1.txt');
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       // write config before init
       await write(dir, '.config.json', JSON.stringify({
@@ -113,7 +113,7 @@ export default {
     await withTestDir(async (dir) => {
       const prev = process.cwd();
       process.chdir(dir);
-      const flags = {root: '.', logging: 0, scan: false};
+      const flags = {root: '.', logging: 0};
       const logFn = () => {};
       const handler = await router(flags, logFn);
       const server = http.createServer(handler);