koa-classic-server 2.1.3 → 2.3.0

package/README.md

@@ -4,37 +4,30 @@
 
 [![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-197%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
+✅ **Comprehensive Testing** - 197 tests passing with extensive coverage
+✅ **Complete Documentation** - Detailed guides and examples
 
 [See full changelog →](./docs/CHANGELOG.md)
 
@@ -101,8 +94,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 +222,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 +274,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 +359,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 +385,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
 
 ---
 
@@ -511,7 +556,7 @@ npm run test:performance
 ```
 
 **Test Coverage:**
-- ✅ 153 tests passing
+- ✅ 197 tests passing
 - ✅ Security tests (path traversal, XSS, race conditions)
 - ✅ EJS template integration tests
 - ✅ Index option tests (strings, arrays, RegExp)