koa-classic-server 2.1.4 → 2.4.0

package/README.md

@@ -4,37 +4,31 @@
 
 [![npm version](https://img.shields.io/npm/v/koa-classic-server.svg)](https://www.npmjs.com/package/koa-classic-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-153%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-214%20passing-brightgreen.svg)]()
 
 ---
 
-## 🎉 Version 2.1.3 - Configuration Update
+## 🎉 Version 2.X - Production-Ready Release
 
-Version 2.1.3 updates the default caching behavior for better development experience while maintaining production-ready performance.
+The 2.X series brings major performance improvements, enhanced security, and powerful new features while maintaining full backward compatibility.
 
-### What's New in 2.1.3
-
-✅ **Development-Friendly Defaults** - `enableCaching` now defaults to `false` for easier development
-✅ **Production Guidance** - Clear documentation on enabling caching for production environments
-✅ **Enhanced Documentation** - Comprehensive notes on caching configuration and recommendations
-
-### What's New in 2.1.2
+### Key Features in Version 2.X
 
+✅ **URL Rewriting Support** - Compatible with i18n and routing middleware via `useOriginalUrl` option
+✅ **Improved Caching Controls** - Clear `browserCacheEnabled` and `browserCacheMaxAge` options
+✅ **Development-Friendly Defaults** - Caching disabled by default for easier development
+✅ **Production Optimized** - Enable caching in production for 80-95% bandwidth reduction
 ✅ **Sortable Directory Columns** - Click Name/Type/Size to sort (Apache2-like)
-✅ **Navigation Bug Fixed** - Directory navigation now works correctly after sorting
 ✅ **File Size Display** - Human-readable file sizes (B, KB, MB, GB, TB)
-✅ **HTTP Caching** - 80-95% bandwidth reduction with ETag and Last-Modified
+✅ **HTTP Caching** - ETag and Last-Modified headers with 304 responses
 ✅ **Async/Await** - Non-blocking I/O for high performance
-✅ **153 Tests Passing** - Comprehensive test coverage
-✅ **Flow Documentation** - Complete execution flow diagrams
-✅ **Code Review** - Standardized operators and best practices
-
-### What's New in 2.0
-
-✅ **Performance Optimizations** - 50-70% faster directory listings
+✅ **Performance Optimized** - 50-70% faster directory listings
 ✅ **Enhanced Index Option** - Array format with RegExp support
-✅ **Template Engine Guide** - Complete documentation with examples
-✅ **Security Hardened** - Path traversal, XSS, race condition fixes
+✅ **Template Engine Support** - EJS, Pug, Handlebars, Nunjucks, and more
+✅ **Enterprise Security** - Path traversal, XSS, race condition protection
+✅ **Symlink Support** - Full symbolic link support (NixOS, Docker, npm link, Capistrano)
+✅ **Comprehensive Testing** - 214 tests passing with extensive coverage
+✅ **Complete Documentation** - Detailed guides and examples
 
 [See full changelog →](./docs/CHANGELOG.md)
 
@@ -55,7 +49,8 @@ Version 2.1.3 updates the default caching behavior for better development experi
 - 🔒 **Enterprise Security** - Path traversal, XSS, race condition protection
 - ⚙️ **Highly Configurable** - URL prefixes, reserved paths, index files
 - 🚀 **High Performance** - Async/await, non-blocking I/O, optimized algorithms
-- 🧪 **Well-Tested** - 153 passing tests with comprehensive coverage
+- 🔗 **Symlink Support** - Transparent symlink resolution with directory listing indicators
+- 🧪 **Well-Tested** - 214 passing tests with comprehensive coverage
 - 📦 **Dual Module Support** - CommonJS and ES Modules
 
 ---
@@ -101,8 +96,8 @@ app.use(koaClassicServer(__dirname + '/public', {
   showDirContents: true,
   index: ['index.html', 'index.htm'],
   urlPrefix: '/static',
-  cacheMaxAge: 3600,
-  enableCaching: true
+  browserCacheMaxAge: 3600,
+  browserCacheEnabled: true
 }));
 
 app.listen(3000);
@@ -229,14 +224,14 @@ Enable aggressive caching for static files:
 
 ```javascript
 app.use(koaClassicServer(__dirname + '/public', {
-  enableCaching: true,       // Enable ETag and Last-Modified
-  cacheMaxAge: 86400,        // Cache for 24 hours (in seconds)
+  browserCacheEnabled: true,       // Enable ETag and Last-Modified
+  browserCacheMaxAge: 86400,        // Cache for 24 hours (in seconds)
 }));
 ```
 
 **⚠️ Important: Production Recommendation**
 
-The default value for `enableCaching` is `false` to facilitate development (where you want changes to be immediately visible). **For production environments, it is strongly recommended to set `enableCaching: true`** to benefit from:
+The default value for `browserCacheEnabled` is `false` to facilitate development (where you want changes to be immediately visible). **For production environments, it is strongly recommended to set `browserCacheEnabled: true`** to benefit from:
 
 - 80-95% bandwidth reduction
 - 304 Not Modified responses for unchanged files
@@ -281,8 +276,8 @@ app.use(koaClassicServer(path.join(__dirname, 'public'), {
   index: ['index.html', 'index.htm'],
   urlPrefix: '/assets',
   urlsReserved: ['/admin', '/api', '/.git'],
-  enableCaching: true,
-  cacheMaxAge: 86400,  // 24 hours
+  browserCacheEnabled: true,
+  browserCacheMaxAge: 86400,  // 24 hours
 }));
 
 // Serve dynamic templates
@@ -366,10 +361,18 @@ Creates a Koa middleware for serving static files.
     ext: ['ejs', 'pug', 'hbs']
   },
 
-  // HTTP caching configuration
+  // Browser HTTP caching configuration
   // NOTE: Default is false for development. Set to true in production for better performance!
-  enableCaching: false,     // Enable ETag & Last-Modified (default: false)
-  cacheMaxAge: 3600,        // Cache-Control max-age in seconds (default: 3600 = 1 hour)
+  browserCacheEnabled: false,     // Enable ETag & Last-Modified (default: false)
+  browserCacheMaxAge: 3600,        // Cache-Control max-age in seconds (default: 3600 = 1 hour)
+
+  // URL resolution
+  useOriginalUrl: true,     // Use ctx.originalUrl (default) or ctx.url
+                            // Set false for URL rewriting middleware (i18n, routing)
+
+  // DEPRECATED (use new names above):
+  // enableCaching: use browserCacheEnabled instead
+  // cacheMaxAge: use browserCacheMaxAge instead
 }
 ```
 
@@ -384,8 +387,52 @@ Creates a Koa middleware for serving static files.
 | `urlsReserved` | Array | `[]` | Reserved directory paths (first-level only) |
 | `template.render` | Function | `undefined` | Template rendering function |
 | `template.ext` | Array | `[]` | Extensions for template rendering |
-| `enableCaching` | Boolean | `false` | Enable HTTP caching headers (recommended: `true` in production) |
-| `cacheMaxAge` | Number | `3600` | Cache duration in seconds |
+| `browserCacheEnabled` | Boolean | `false` | Enable browser HTTP caching headers (recommended: `true` in production) |
+| `browserCacheMaxAge` | Number | `3600` | Browser cache duration in seconds |
+| `useOriginalUrl` | Boolean | `true` | Use `ctx.originalUrl` (default) or `ctx.url` for URL resolution |
+| ~~`enableCaching`~~ | Boolean | `false` | **DEPRECATED**: Use `browserCacheEnabled` instead |
+| ~~`cacheMaxAge`~~ | Number | `3600` | **DEPRECATED**: Use `browserCacheMaxAge` instead |
+
+#### useOriginalUrl (Boolean, default: true)
+
+Controls which URL property is used for file resolution:
+- **`true` (default)**: Uses `ctx.originalUrl` (immutable, reflects the original request)
+- **`false`**: Uses `ctx.url` (mutable, can be modified by middleware)
+
+**When to use `false`:**
+
+Set `useOriginalUrl: false` when using URL rewriting middleware such as i18n routers or path rewriters that modify `ctx.url`. This allows koa-classic-server to serve files based on the rewritten URL instead of the original request URL.
+
+**Example with i18n middleware:**
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// i18n middleware that rewrites URLs
+app.use(async (ctx, next) => {
+  if (ctx.path.match(/^\/it\//)) {
+    ctx.url = ctx.path.replace(/^\/it/, ''); // /it/page.html → /page.html
+  }
+  await next();
+});
+
+// Serve files using rewritten URL
+app.use(koaClassicServer(__dirname + '/www', {
+  useOriginalUrl: false  // Use ctx.url (rewritten) instead of ctx.originalUrl
+}));
+
+app.listen(3000);
+```
+
+**How it works:**
+- Request: `GET /it/page.html`
+- `ctx.originalUrl`: `/it/page.html` (unchanged)
+- `ctx.url`: `/page.html` (rewritten by middleware)
+- With `useOriginalUrl: false`: Server looks for `/www/page.html` ✅
+- With `useOriginalUrl: true` (default): Server looks for `/www/it/page.html` ❌ 404
 
 ---
 
@@ -417,6 +464,33 @@ Human-readable format:
 - **Click file name** - Download/view file
 - **Parent Directory** - Go up one level
 
+### Symlink Support
+
+The middleware fully supports symbolic links, which is essential for environments where served files are symlinks rather than regular files:
+
+- **NixOS buildFHSEnv** - Files in www/ appear as symlinks to the Nix store
+- **Docker bind mounts** - Mounted files may appear as symlinks
+- **npm link** - Linked packages are symlinks
+- **Capistrano-style deploys** - The `current` directory is a symlink to the active release
+
+**How it works:**
+
+Symlinks are followed transparently via `fs.promises.stat()`, but only when `dirent.isSymbolicLink()` is true. Regular files incur zero additional overhead.
+
+**Directory listing indicators:**
+
+| Entry type | Indicator | Clickable | Type shown |
+|------------|-----------|-----------|------------|
+| Symlink to file | `( Symlink )` | Yes | Target MIME type |
+| Symlink to directory | `( Symlink )` | Yes | `DIR` |
+| Broken/circular symlink | `( Broken Symlink )` | No | `unknown` |
+| Regular file/directory | none | Yes | Real type |
+
+**Edge cases handled:**
+- Broken symlinks (missing target) return 404 on direct access
+- Circular symlinks (A → B → A) are treated as broken, no infinite loops
+- Symlinks to directories are fully navigable
+
 ---
 
 ## Security
@@ -511,10 +585,11 @@ npm run test:performance
 ```
 
 **Test Coverage:**
-- ✅ 153 tests passing
+- ✅ 214 tests passing
 - ✅ Security tests (path traversal, XSS, race conditions)
 - ✅ EJS template integration tests
 - ✅ Index option tests (strings, arrays, RegExp)
+- ✅ Symlink tests (file, directory, broken, circular, indicators)
 - ✅ Performance benchmarks
 - ✅ Directory sorting tests
 

package/__tests__/deprecation-warnings.test.js

@@ -0,0 +1,217 @@
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  TEST FOR DEPRECATED OPTION NAMES (enableCaching, cacheMaxAge)
+//  This test verifies backward compatibility and deprecation warnings
+//
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const Koa = require('koa');
+const path = require('path');
+
+const rootDir = path.join(__dirname, 'publicWwwTest');
+
+describe('Deprecated option names (backward compatibility)', () => {
+
+    describe('Using deprecated enableCaching option', () => {
+        let app;
+        let server;
+        let consoleWarnSpy;
+
+        beforeAll(() => {
+            // Spy on console.warn to capture deprecation warnings
+            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+            app = new Koa();
+
+            // Use deprecated option name
+            app.use(koaClassicServer(rootDir, {
+                enableCaching: true  // DEPRECATED: should use browserCacheEnabled
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+            consoleWarnSpy.mockRestore();
+        });
+
+        test('should display deprecation warning for enableCaching', () => {
+            expect(consoleWarnSpy).toHaveBeenCalled();
+            const warningMessage = consoleWarnSpy.mock.calls[0][1];
+            expect(warningMessage).toContain('DEPRECATION WARNING');
+            expect(warningMessage).toContain('enableCaching');
+            expect(warningMessage).toContain('browserCacheEnabled');
+        });
+
+        test('should still work with deprecated option', async () => {
+            const response = await supertest(server).get('/test-page.html');
+
+            // Should return the file
+            expect(response.status).toBe(200);
+
+            // Should have caching headers (because enableCaching: true was set)
+            expect(response.headers['etag']).toBeDefined();
+            expect(response.headers['last-modified']).toBeDefined();
+            expect(response.headers['cache-control']).toContain('public');
+        });
+    });
+
+    describe('Using deprecated cacheMaxAge option', () => {
+        let app;
+        let server;
+        let consoleWarnSpy;
+
+        beforeAll(() => {
+            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+            app = new Koa();
+
+            // Use deprecated option name
+            app.use(koaClassicServer(rootDir, {
+                enableCaching: true,  // Also deprecated
+                cacheMaxAge: 7200     // DEPRECATED: should use browserCacheMaxAge
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+            consoleWarnSpy.mockRestore();
+        });
+
+        test('should display deprecation warning for cacheMaxAge', () => {
+            const warningCalls = consoleWarnSpy.mock.calls;
+            const cacheMaxAgeWarning = warningCalls.find(call =>
+                call[1] && call[1].includes('cacheMaxAge')
+            );
+
+            expect(cacheMaxAgeWarning).toBeDefined();
+            expect(cacheMaxAgeWarning[1]).toContain('DEPRECATION WARNING');
+            expect(cacheMaxAgeWarning[1]).toContain('browserCacheMaxAge');
+        });
+
+        test('should use the deprecated cacheMaxAge value', async () => {
+            const response = await supertest(server).get('/test-page.html');
+
+            expect(response.status).toBe(200);
+            expect(response.headers['cache-control']).toContain('max-age=7200');
+        });
+    });
+
+    describe('Using new option names (no warnings)', () => {
+        let app;
+        let server;
+        let consoleWarnSpy;
+
+        beforeAll(() => {
+            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+            app = new Koa();
+
+            // Use NEW option names
+            app.use(koaClassicServer(rootDir, {
+                browserCacheEnabled: true,
+                browserCacheMaxAge: 3600
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+            consoleWarnSpy.mockRestore();
+        });
+
+        test('should NOT display deprecation warnings', () => {
+            // Filter out warnings from other tests (like index option deprecation)
+            const cachingWarnings = consoleWarnSpy.mock.calls.filter(call =>
+                call[1] && (call[1].includes('enableCaching') || call[1].includes('cacheMaxAge'))
+            );
+
+            expect(cachingWarnings.length).toBe(0);
+        });
+
+        test('should work correctly with new option names', async () => {
+            const response = await supertest(server).get('/test-page.html');
+
+            expect(response.status).toBe(200);
+            expect(response.headers['etag']).toBeDefined();
+            expect(response.headers['cache-control']).toContain('max-age=3600');
+        });
+    });
+
+    describe('Using both old and new names (new takes precedence)', () => {
+        let app;
+        let server;
+        let consoleWarnSpy;
+
+        beforeAll(() => {
+            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+            app = new Koa();
+
+            // Use BOTH old and new names - new should take precedence
+            app.use(koaClassicServer(rootDir, {
+                enableCaching: true,           // OLD (deprecated)
+                browserCacheEnabled: false,    // NEW (should take precedence)
+                cacheMaxAge: 7200,             // OLD (deprecated)
+                browserCacheMaxAge: 9999       // NEW (should take precedence)
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+            consoleWarnSpy.mockRestore();
+        });
+
+        test('should NOT display warnings when new names are also provided', () => {
+            // When both old and new names are provided, no warning should be shown
+            const cachingWarnings = consoleWarnSpy.mock.calls.filter(call =>
+                call[1] && (call[1].includes('enableCaching') || call[1].includes('cacheMaxAge'))
+            );
+
+            expect(cachingWarnings.length).toBe(0);
+        });
+
+        test('new option values should take precedence over old ones', async () => {
+            const response = await supertest(server).get('/test-page.html');
+
+            expect(response.status).toBe(200);
+
+            // browserCacheEnabled: false should take precedence over enableCaching: true
+            // So there should be NO caching headers
+            expect(response.headers['etag']).toBeUndefined();
+            expect(response.headers['cache-control']).toContain('no-cache');
+        });
+    });
+
+    describe('Default behavior (no caching options specified)', () => {
+        let app;
+        let server;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir));
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('should default to browserCacheEnabled: false', async () => {
+            const response = await supertest(server).get('/test-page.html');
+
+            expect(response.status).toBe(200);
+
+            // Default is caching disabled
+            expect(response.headers['cache-control']).toContain('no-cache');
+        });
+    });
+});

package/__tests__/publicWwwTest/test-page.html

@@ -0,0 +1 @@
+<!DOCTYPE html><html><head><title>Test Page</title></head><body><h1>Test Page</h1></body></html>