koa-classic-server 2.1.4 → 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)

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>

package/__tests__/useOriginalUrl.test.js

@@ -0,0 +1,213 @@
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  TEST FOR useOriginalUrl OPTION
+//  This test verifies that the useOriginalUrl option works correctly with URL rewriting middleware
+//
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const Koa = require('koa');
+const fs = require('fs');
+const path = require('path');
+
+const rootDir = path.join(__dirname, 'publicWwwTest');
+
+// Create a simple test file if it doesn't exist
+const testFilePath = path.join(rootDir, 'test-page.html');
+const testFileContent = '<!DOCTYPE html><html><head><title>Test Page</title></head><body><h1>Test Page</h1></body></html>';
+
+beforeAll(() => {
+    // Ensure test directory exists
+    if (!fs.existsSync(rootDir)) {
+        fs.mkdirSync(rootDir, { recursive: true });
+    }
+
+    // Create test file
+    if (!fs.existsSync(testFilePath)) {
+        fs.writeFileSync(testFilePath, testFileContent, 'utf-8');
+    }
+});
+
+describe('useOriginalUrl option tests', () => {
+
+    describe('Default behavior (useOriginalUrl: true)', () => {
+        let app;
+        let server;
+
+        beforeAll(() => {
+            app = new Koa();
+
+            // i18n middleware that rewrites URLs
+            app.use(async (ctx, next) => {
+                if (ctx.path.match(/^\/it\//)) {
+                    // Rewrite /it/page.html to /page.html
+                    ctx.url = ctx.path.replace(/^\/it/, '');
+                }
+                await next();
+            });
+
+            // Serve files with default useOriginalUrl: true
+            app.use(koaClassicServer(rootDir, {
+                useOriginalUrl: true  // Default behavior
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('should use ctx.originalUrl (original request path)', async () => {
+            // Request /it/test-page.html
+            // ctx.originalUrl = /it/test-page.html (unchanged)
+            // ctx.url = /test-page.html (rewritten by middleware)
+            // With useOriginalUrl: true, server looks for /it/test-page.html (which doesn't exist)
+            const response = await supertest(server).get('/it/test-page.html');
+
+            // Should return 404 because /it/test-page.html doesn't exist
+            expect(response.status).toBe(404);
+        });
+
+        test('should serve file without rewriting', async () => {
+            // Request /test-page.html directly (no rewriting)
+            const response = await supertest(server).get('/test-page.html');
+
+            // Should return 200 and the file content
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+    });
+
+    describe('URL rewriting support (useOriginalUrl: false)', () => {
+        let app;
+        let server;
+
+        beforeAll(() => {
+            app = new Koa();
+
+            // i18n middleware that rewrites URLs
+            app.use(async (ctx, next) => {
+                if (ctx.path.match(/^\/it\//)) {
+                    // Rewrite /it/page.html to /page.html
+                    ctx.url = ctx.path.replace(/^\/it/, '');
+                }
+                await next();
+            });
+
+            // Serve files with useOriginalUrl: false to use rewritten URL
+            app.use(koaClassicServer(rootDir, {
+                useOriginalUrl: false  // Use ctx.url (rewritten)
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('should use ctx.url (rewritten path)', async () => {
+            // Request /it/test-page.html
+            // ctx.originalUrl = /it/test-page.html (unchanged)
+            // ctx.url = /test-page.html (rewritten by middleware)
+            // With useOriginalUrl: false, server looks for /test-page.html (which exists)
+            const response = await supertest(server).get('/it/test-page.html');
+
+            // Should return 200 and the file content
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+
+        test('should still serve file without rewriting', async () => {
+            // Request /test-page.html directly (no rewriting)
+            const response = await supertest(server).get('/test-page.html');
+
+            // Should return 200 and the file content
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+    });
+
+    describe('Complex i18n routing scenario', () => {
+        let app;
+        let server;
+
+        beforeAll(() => {
+            app = new Koa();
+
+            // More complex i18n middleware
+            app.use(async (ctx, next) => {
+                const langPattern = /^\/(it|fr|de|es)\//;
+                const match = ctx.path.match(langPattern);
+                if (match) {
+                    // Store language in state
+                    ctx.state.lang = match[1];
+                    // Strip language prefix
+                    ctx.url = ctx.path.replace(langPattern, '/');
+                }
+                await next();
+            });
+
+            app.use(koaClassicServer(rootDir, {
+                useOriginalUrl: false
+            }));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('should work with Italian locale (/it/)', async () => {
+            const response = await supertest(server).get('/it/test-page.html');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+
+        test('should work with French locale (/fr/)', async () => {
+            const response = await supertest(server).get('/fr/test-page.html');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+
+        test('should work with German locale (/de/)', async () => {
+            const response = await supertest(server).get('/de/test-page.html');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+
+        test('should work with Spanish locale (/es/)', async () => {
+            const response = await supertest(server).get('/es/test-page.html');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+    });
+
+    describe('Backward compatibility', () => {
+        let app;
+        let server;
+
+        beforeAll(() => {
+            app = new Koa();
+
+            // No URL rewriting middleware
+            // Default useOriginalUrl (should be true)
+            app.use(koaClassicServer(rootDir));
+
+            server = app.listen();
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('should work with default options (backward compatible)', async () => {
+            const response = await supertest(server).get('/test-page.html');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Page');
+        });
+    });
+});

package/docs/CHANGELOG.md

@@ -5,6 +5,131 @@ All notable changes to koa-classic-server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-01-03
+
+### 🔄 Renamed Options (with Backward Compatibility)
+
+#### Renamed Caching Options for Clarity
+- **Old Names** (DEPRECATED): `enableCaching`, `cacheMaxAge`
+- **New Names**: `browserCacheEnabled`, `browserCacheMaxAge`
+- **Reason**: Improved clarity - these options specifically control browser-side HTTP caching
+- **Backward Compatible**: Old names still work but display deprecation warnings
+
+#### Deprecation Warnings
+When using deprecated option names, a warning is displayed on the terminal:
+```
+[koa-classic-server] DEPRECATION WARNING: The "enableCaching" option is deprecated and will be removed in future versions.
+  Current usage: enableCaching: true
+  Recommended:   browserCacheEnabled: true
+  Please update your configuration to use the new option name.
+```
+
+### 📝 Documentation Updates
+
+- Updated README.md with new option names
+- Updated JSDoc comments in index.cjs
+- Added deprecation notes in Options table
+- All examples updated to use new names
+
+### 🔧 Changes
+
+- **index.cjs**: Lines 109-135 - Added backward compatibility logic with deprecation warnings
+- **index.cjs**: Lines 47-58 - Updated JSDoc comments
+- **index.cjs**: Lines 350, 361 - Updated code to use new option names
+- **README.md**: Updated all references to use new names, added deprecation notes
+- **package.json**: Version bumped from `2.2.0` to `2.3.0`
+
+### ⚠️ Migration Guide
+
+**No immediate changes required** - old option names still work.
+
+**Recommended migration:**
+
+```javascript
+// Old (still works, but deprecated)
+app.use(koaClassicServer('/public', {
+  enableCaching: true,
+  cacheMaxAge: 3600
+}));
+
+// New (recommended)
+app.use(koaClassicServer('/public', {
+  browserCacheEnabled: true,
+  browserCacheMaxAge: 3600
+}));
+```
+
+**Timeline:**
+- **v2.3.0**: Old names work with deprecation warnings
+- **Future versions**: Old names may be removed (will be announced in advance)
+
+### 📦 Package Changes
+
+- **Version**: `2.2.0` → `2.3.0`
+- **Semver**: Minor version bump (new feature names, backward compatible)
+
+---
+
+## [2.2.0] - 2026-01-03
+
+### ✨ Features
+
+#### Added useOriginalUrl Option
+- **New Option**: `useOriginalUrl` (Boolean, default: `true`)
+- **Purpose**: Controls URL resolution for file serving - use `ctx.originalUrl` (immutable) or `ctx.url` (mutable)
+- **Use Case**: Compatibility with URL rewriting middleware (i18n, routing)
+- **Backward Compatible**: Default value `true` maintains existing behavior
+
+#### URL Rewriting Middleware Support
+- **Problem Solved**: koa-classic-server previously used `ctx.href` (based on `ctx.originalUrl`), which caused 404 errors when middleware rewrites URLs by modifying `ctx.url`
+- **Solution**: Set `useOriginalUrl: false` to use the rewritten URL from `ctx.url` instead
+- **Example**: i18n middleware that strips language prefixes (`/it/page.html` → `/page.html`)
+
+### 📝 Documentation
+
+- Added comprehensive `useOriginalUrl` documentation in README.md
+- Added JSDoc comments in index.cjs
+- Included practical i18n middleware example
+- Added option to API reference table
+
+### 🔧 Changes
+
+- **index.cjs**: Line 108 - Added `useOriginalUrl` option initialization
+- **index.cjs**: Lines 117-125 - Modified URL construction logic to support both `ctx.originalUrl` and `ctx.url`
+- **README.md**: Added detailed section explaining `useOriginalUrl` with examples
+- **package.json**: Version bumped from `2.1.4` to `2.2.0`
+
+### 💡 Usage Example
+
+```javascript
+// i18n middleware example
+app.use(async (ctx, next) => {
+  if (ctx.path.match(/^\/it\//)) {
+    ctx.url = ctx.path.replace(/^\/it/, ''); // /it/page.html → /page.html
+  }
+  await next();
+});
+
+app.use(koaClassicServer('/www', {
+  useOriginalUrl: false // Use rewritten URL
+}));
+```
+
+### ⚠️ Migration Notes
+
+**No breaking changes** - this is a backward-compatible release.
+
+- **Default behavior unchanged**: `useOriginalUrl` defaults to `true`
+- **No code changes required** for existing implementations
+- **New feature**: Set `useOriginalUrl: false` if you use URL rewriting middleware
+
+### 📦 Package Changes
+
+- **Version**: `2.1.4` → `2.2.0`
+- **Semver**: Minor version bump (new feature, backward compatible)
+
+---
+
 ## [2.1.3] - 2025-11-25
 
 ### 🔧 Configuration Changes

package/index.cjs

@@ -44,11 +44,17 @@ module.exports = function koaClassicServer(
             render: undefined, // Template rendering function: async (ctx, next, filePath) => {}
             ext: [], // File extensions to process with template.render
         },
-        cacheMaxAge: 3600, // Cache-Control max-age in seconds (default: 1 hour)
-        enableCaching: false, // Enable HTTP caching headers (ETag, Last-Modified)
-                              // NOTE: Default is false for development.
-                              // In production, it's recommended to set enableCaching: true
-                              // to reduce bandwidth usage and improve performance.
+        browserCacheMaxAge: 3600, // Browser Cache-Control max-age in seconds (default: 1 hour)
+        browserCacheEnabled: false, // Enable browser HTTP caching headers (ETag, Last-Modified)
+                                    // NOTE: Default is false for development.
+                                    // In production, it's recommended to set browserCacheEnabled: true
+                                    // to reduce bandwidth usage and improve performance.
+        useOriginalUrl: true, // Use ctx.originalUrl (default) or ctx.url
+                              // Set false for URL rewriting middleware (i18n, routing)
+
+        // DEPRECATED OPTIONS (maintained for backward compatibility):
+        // cacheMaxAge: use browserCacheMaxAge instead
+        // enableCaching: use browserCacheEnabled instead
     }
     */
 ) {
@@ -100,11 +106,37 @@ module.exports = function koaClassicServer(
     options.template.ext = Array.isArray(options.template.ext) ? options.template.ext : [];
 
     // OPTIMIZATION: HTTP Caching options
-    // NOTE: Default enableCaching is false for development environments.
+    // NOTE: Default browserCacheEnabled is false for development environments.
     // For production deployments, it's strongly recommended to enable caching
-    // by setting enableCaching: true to benefit from reduced bandwidth and improved performance.
-    options.cacheMaxAge = typeof options.cacheMaxAge === 'number' && options.cacheMaxAge >= 0 ? options.cacheMaxAge : 3600;
-    options.enableCaching = typeof options.enableCaching === 'boolean' ? options.enableCaching : false;
+    // by setting browserCacheEnabled: true to benefit from reduced bandwidth and improved performance.
+
+    // DEPRECATION: Handle legacy option names for backward compatibility
+    if ('cacheMaxAge' in opts && !('browserCacheMaxAge' in opts)) {
+        console.warn(
+            '\x1b[33m%s\x1b[0m',
+            '[koa-classic-server] DEPRECATION WARNING: The "cacheMaxAge" option is deprecated and will be removed in future versions.\n' +
+            '  Current usage: cacheMaxAge: ' + opts.cacheMaxAge + '\n' +
+            '  Recommended:   browserCacheMaxAge: ' + opts.cacheMaxAge + '\n' +
+            '  Please update your configuration to use the new option name.'
+        );
+        options.browserCacheMaxAge = opts.cacheMaxAge;
+    }
+
+    if ('enableCaching' in opts && !('browserCacheEnabled' in opts)) {
+        console.warn(
+            '\x1b[33m%s\x1b[0m',
+            '[koa-classic-server] DEPRECATION WARNING: The "enableCaching" option is deprecated and will be removed in future versions.\n' +
+            '  Current usage: enableCaching: ' + opts.enableCaching + '\n' +
+            '  Recommended:   browserCacheEnabled: ' + opts.enableCaching + '\n' +
+            '  Please update your configuration to use the new option name.'
+        );
+        options.browserCacheEnabled = opts.enableCaching;
+    }
+
+    // Set new option names (with defaults)
+    options.browserCacheMaxAge = typeof options.browserCacheMaxAge === 'number' && options.browserCacheMaxAge >= 0 ? options.browserCacheMaxAge : 3600;
+    options.browserCacheEnabled = typeof options.browserCacheEnabled === 'boolean' ? options.browserCacheEnabled : false;
+    options.useOriginalUrl = typeof options.useOriginalUrl === 'boolean' ? options.useOriginalUrl : true;
 
     return async (ctx, next) => {
         // Check if method is allowed
@@ -113,12 +145,14 @@ module.exports = function koaClassicServer(
             return;
         }
 
-        // Normalize URL (remove trailing slash)
+        // Construct full URL based on useOriginalUrl option
+        const urlToUse = options.useOriginalUrl ? ctx.originalUrl : ctx.url;
+        const fullUrl = ctx.protocol + '://' + ctx.host + urlToUse;
         let pageHref = '';
-        if (ctx.href.charAt(ctx.href.length - 1) === '/') {
-            pageHref = new URL(ctx.href.slice(0, -1));
+        if (fullUrl.charAt(fullUrl.length - 1) === '/') {
+            pageHref = new URL(fullUrl.slice(0, -1));
         } else {
-            pageHref = new URL(ctx.href);
+            pageHref = new URL(fullUrl);
         }
 
         // Check URL prefix
@@ -317,7 +351,7 @@ module.exports = function koaClassicServer(
             }
 
             // OPTIMIZATION: HTTP Caching Headers
-            if (options.enableCaching) {
+            if (options.browserCacheEnabled) {
                 // Generate ETag from mtime timestamp + file size
                 // This ensures ETag changes when file is modified or resized
                 const etag = `"${fileStat.mtime.getTime()}-${fileStat.size}"`;
@@ -328,7 +362,7 @@ module.exports = function koaClassicServer(
                 // Set caching headers
                 ctx.set('ETag', etag);
                 ctx.set('Last-Modified', lastModified);
-                ctx.set('Cache-Control', `public, max-age=${options.cacheMaxAge}, must-revalidate`);
+                ctx.set('Cache-Control', `public, max-age=${options.browserCacheMaxAge}, must-revalidate`);
 
                 // OPTIMIZATION: Handle conditional requests (304 Not Modified)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "2.1.4",
+  "version": "2.3.0",
   "description": "High-performance Koa middleware for serving static files with Apache-like directory listing, HTTP caching, template engine support, and comprehensive security fixes",
   "main": "index.cjs",
   "exports": {