koa-classic-server 2.4.0 → 2.5.1

package/README.md

@@ -4,7 +4,7 @@
 
 [![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-214%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-309%20passing-brightgreen.svg)]()
 
 ---
 
@@ -26,8 +26,9 @@ The 2.X series brings major performance improvements, enhanced security, and pow
 ✅ **Enhanced Index Option** - Array format with RegExp support
 ✅ **Template Engine Support** - EJS, Pug, Handlebars, Nunjucks, and more
 ✅ **Enterprise Security** - Path traversal, XSS, race condition protection
+✅ **Clean URLs** - Hide file extensions with `hideExtension` (mod_rewrite-like behavior)
 ✅ **Symlink Support** - Full symbolic link support (NixOS, Docker, npm link, Capistrano)
-✅ **Comprehensive Testing** - 214 tests passing with extensive coverage
+✅ **Comprehensive Testing** - 309 tests passing with extensive coverage
 ✅ **Complete Documentation** - Detailed guides and examples
 
 [See full changelog →](./docs/CHANGELOG.md)
@@ -50,7 +51,8 @@ The 2.X series brings major performance improvements, enhanced security, and pow
 - ⚙️ **Highly Configurable** - URL prefixes, reserved paths, index files
 - 🚀 **High Performance** - Async/await, non-blocking I/O, optimized algorithms
 - 🔗 **Symlink Support** - Transparent symlink resolution with directory listing indicators
-- 🧪 **Well-Tested** - 214 passing tests with comprehensive coverage
+- 🌐 **Clean URLs** - Hide file extensions for SEO-friendly URLs via `hideExtension`
+- 🧪 **Well-Tested** - 309 passing tests with comprehensive coverage
 - 📦 **Dual Module Support** - CommonJS and ES Modules
 
 ---
@@ -218,7 +220,177 @@ app.use(koaClassicServer(__dirname + '/views', {
 
 **See complete guide:** [Template Engine Documentation →](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)
 
-### 6. With HTTP Caching
+### 6. Clean URLs with hideExtension
+
+Hide file extensions from URLs, similar to Apache's `mod_rewrite`:
+
+```javascript
+const ejs = require('ejs');
+
+app.use(koaClassicServer(__dirname + '/public', {
+  showDirContents: true,
+  index: ['index.ejs'],
+  hideExtension: {
+    ext: '.ejs',      // Extension to hide (required)
+    redirect: 301     // HTTP redirect code (optional, default: 301)
+  },
+  template: {
+    ext: ['ejs'],
+    render: async (ctx, next, filePath) => {
+      ctx.body = await ejs.renderFile(filePath, data);
+      ctx.type = 'text/html';
+    }
+  }
+}));
+```
+
+**URL Behavior:**
+
+| Request URL | Action | Result |
+|-------------|--------|--------|
+| `/about` | Resolves `about.ejs` | Serves file (200) |
+| `/blog/article` | Resolves `blog/article.ejs` | Serves file (200) |
+| `/about.ejs` | Redirect | 301 → `/about` |
+| `/about.ejs?lang=it` | Redirect | 301 → `/about?lang=it` |
+| `/index.ejs` | Redirect | 301 → `/` |
+| `/section/index.ejs` | Redirect | 301 → `/section/` |
+| `/style.css` | No interference | Normal flow |
+| `/about/` | No interference | Shows directory listing |
+
+**Conflict Resolution:**
+
+- **Directory vs file**: When both `about/` directory and `about.ejs` file exist, `/about` serves the file. Use `/about/` to access the directory.
+- **Extensionless vs extension**: When both `about` (no ext) and `about.ejs` exist, `/about` always serves `about.ejs`. The extensionless file becomes unreachable.
+
+> **Note**: This conflict resolution behavior differs from Apache/Nginx, where directories typically take priority over files with the same base name.
+
+### 7. URL Rewriting Support (useOriginalUrl)
+
+When using URL rewriting middleware (i18n, routing), set `useOriginalUrl: false` so koa-classic-server resolves files from the rewritten URL instead of the original one:
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// i18n middleware: strips language prefix and rewrites ctx.url
+app.use(async (ctx, next) => {
+  const langMatch = ctx.path.match(/^\/(it|en|fr|de|es)\//);
+  if (langMatch) {
+    ctx.state.lang = langMatch[1];       // Save language for templates
+    ctx.url = ctx.path.replace(/^\/(it|en|fr|de|es)/, '') + ctx.search;
+  }
+  await next();
+});
+
+// Serve files using the rewritten URL
+app.use(koaClassicServer(__dirname + '/public', {
+  useOriginalUrl: false  // Use ctx.url (rewritten) instead of ctx.originalUrl
+}));
+
+app.listen(3000);
+```
+
+**How it works:**
+
+| Request | `ctx.originalUrl` | `ctx.url` (rewritten) | File resolved |
+|---------|-------------------|----------------------|---------------|
+| `/it/page.html` | `/it/page.html` | `/page.html` | `public/page.html` |
+| `/en/page.html` | `/en/page.html` | `/page.html` | `public/page.html` |
+| `/page.html` | `/page.html` | `/page.html` | `public/page.html` |
+
+- With `useOriginalUrl: true` (default): the server would look for `public/it/page.html` (which doesn't exist)
+- With `useOriginalUrl: false`: the server looks for `public/page.html` (correct)
+
+### 8. Advanced hideExtension Scenarios
+
+#### Recommended file structure
+
+```
+views/
+├── index.ejs              ← / (home page)
+├── about.ejs              ← /about
+├── contact.ejs            ← /contact
+├── blog/
+│   ├── index.ejs          ← /blog/
+│   ├── first-post.ejs     ← /blog/first-post
+│   └── second-post.ejs    ← /blog/second-post
+├── docs/
+│   ├── index.ejs          ← /docs/
+│   ├── getting-started.ejs ← /docs/getting-started
+│   └── api-reference.ejs  ← /docs/api-reference
+└── assets/
+    ├── style.css          ← /assets/style.css (served normally)
+    └── script.js          ← /assets/script.js (served normally)
+```
+
+#### hideExtension with i18n middleware
+
+Combine `hideExtension` with `useOriginalUrl: false` for multilingual sites with clean URLs:
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+const ejs = require('ejs');
+
+const app = new Koa();
+
+// i18n middleware: /it/about → ctx.url = /about, ctx.state.lang = 'it'
+app.use(async (ctx, next) => {
+  const langMatch = ctx.path.match(/^\/(it|en|fr)\//);
+  if (langMatch) {
+    ctx.state.lang = langMatch[1];
+    ctx.url = ctx.path.replace(/^\/(it|en|fr)/, '') + ctx.search;
+  } else {
+    ctx.state.lang = 'en';  // Default language
+  }
+  await next();
+});
+
+app.use(koaClassicServer(__dirname + '/views', {
+  index: ['index.ejs'],
+  useOriginalUrl: false,     // Resolve files from rewritten URL
+  hideExtension: {
+    ext: '.ejs',
+    redirect: 301
+  },
+  template: {
+    ext: ['ejs'],
+    render: async (ctx, next, filePath) => {
+      ctx.body = await ejs.renderFile(filePath, { lang: ctx.state.lang });
+      ctx.type = 'text/html';
+    }
+  }
+}));
+
+app.listen(3000);
+```
+
+**Result:**
+
+| Request | Rewritten URL | File resolved | Redirect target |
+|---------|---------------|---------------|-----------------|
+| `/it/about` | `/about` | `views/about.ejs` | — |
+| `/en/blog/first-post` | `/blog/first-post` | `views/blog/first-post.ejs` | — |
+| `/it/about.ejs` | `/about.ejs` | — | 301 → `/it/about` (preserves `/it/` prefix) |
+
+> **Note**: Redirects always use `ctx.originalUrl` to preserve the language prefix, regardless of the `useOriginalUrl` setting.
+
+#### Temporary redirect (302)
+
+Use `redirect: 302` instead of 301 when the URL mapping may change (staging, A/B testing, or during migration):
+
+```javascript
+hideExtension: {
+  ext: '.ejs',
+  redirect: 302   // Temporary redirect — browsers won't cache it
+}
+```
+
+> **When to use 302**: A 301 (permanent) tells browsers and search engines to cache the redirect. Use 302 (temporary) during development, staging, or when you're not yet sure the clean URL structure is final.
+
+### 9. With HTTP Caching
 
 Enable aggressive caching for static files:
 
@@ -240,7 +412,7 @@ The default value for `browserCacheEnabled` is `false` to facilitate development
 
 **See details:** [HTTP Caching Optimization →](./docs/OPTIMIZATION_HTTP_CACHING.md)
 
-### 7. Multiple Index Files with Priority
+### 10. Multiple Index Files with Priority
 
 Search for multiple index files with custom order:
 
@@ -257,7 +429,7 @@ app.use(koaClassicServer(__dirname + '/public', {
 
 **See details:** [Index Option Priority →](./docs/INDEX_OPTION_PRIORITY.md)
 
-### 8. Complete Production Example
+### 11. Complete Production Example
 
 Real-world configuration for production:
 
@@ -280,9 +452,15 @@ app.use(koaClassicServer(path.join(__dirname, 'public'), {
   browserCacheMaxAge: 86400,  // 24 hours
 }));
 
-// Serve dynamic templates
+// Serve dynamic templates with clean URLs
 app.use(koaClassicServer(path.join(__dirname, 'views'), {
   showDirContents: false,
+  index: ['index.ejs'],
+  useOriginalUrl: false,  // Use ctx.url (for i18n or routing middleware)
+  hideExtension: {
+    ext: '.ejs',           // /about → serves about.ejs
+    redirect: 301          // /about.ejs → 301 redirect to /about
+  },
   template: {
     ext: ['ejs'],
     render: async (ctx, next, filePath) => {
@@ -370,6 +548,12 @@ Creates a Koa middleware for serving static files.
   useOriginalUrl: true,     // Use ctx.originalUrl (default) or ctx.url
                             // Set false for URL rewriting middleware (i18n, routing)
 
+  // Clean URLs - hide file extension from URLs (mod_rewrite-like)
+  hideExtension: {
+    ext: '.ejs',            // Extension to hide (required, must start with '.')
+    redirect: 301           // HTTP redirect code (optional, default: 301)
+  },
+
   // DEPRECATED (use new names above):
   // enableCaching: use browserCacheEnabled instead
   // cacheMaxAge: use browserCacheMaxAge instead
@@ -390,6 +574,8 @@ Creates a Koa middleware for serving static files.
 | `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 |
+| `hideExtension.ext` | String | - | Extension to hide (e.g. `'.ejs'`). Enables clean URL feature |
+| `hideExtension.redirect` | Number | `301` | HTTP redirect code for URLs with extension |
 | ~~`enableCaching`~~ | Boolean | `false` | **DEPRECATED**: Use `browserCacheEnabled` instead |
 | ~~`cacheMaxAge`~~ | Number | `3600` | **DEPRECATED**: Use `browserCacheMaxAge` instead |
 
@@ -585,10 +771,11 @@ npm run test:performance
 ```
 
 **Test Coverage:**
-- ✅ 214 tests passing
+- ✅ 309 tests passing
 - ✅ Security tests (path traversal, XSS, race conditions)
 - ✅ EJS template integration tests
 - ✅ Index option tests (strings, arrays, RegExp)
+- ✅ hideExtension tests (clean URLs, redirects, conflicts, validation)
 - ✅ Symlink tests (file, directory, broken, circular, indicators)
 - ✅ Performance benchmarks
 - ✅ Directory sorting tests

package/__tests__/hideExtension.test.js

@@ -0,0 +1,550 @@
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  TEST FOR hideExtension OPTION
+//  This test verifies that the hideExtension option works correctly:
+//  - Clean URL resolution (URL without extension → file with extension)
+//  - Redirect from URL with extension to clean URL
+//  - Query string preservation
+//  - Conflict resolution (directory vs file, extensionless vs extension)
+//  - Input validation
+//  - Interaction with existing options (urlsReserved, useOriginalUrl, template)
+//
+//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const Koa = require('koa');
+const fs = require('fs');
+const path = require('path');
+const ejs = require('ejs');
+
+const rootDir = path.join(__dirname, 'publicWwwTest', 'hideext-test');
+
+describe('hideExtension option tests', () => {
+
+    // ==========================================
+    // Clean URL Resolution
+    // ==========================================
+    describe('Clean URL resolution', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                index: ['index.ejs'],
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const content = await fs.promises.readFile(filePath, 'utf-8');
+                        ctx.type = 'text/html';
+                        ctx.body = content;
+                    }
+                }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/about serves about.ejs', async () => {
+            const response = await request.get('/about');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('About Page');
+        });
+
+        test('/blog/articolo serves blog/articolo.ejs (multi-level path)', async () => {
+            const response = await request.get('/blog/articolo');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Blog Article');
+        });
+
+        test('/style.css serves style.css (no interference with other extensions)', async () => {
+            const response = await request.get('/style.css');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('body { color: red; }');
+        });
+
+        test('/ serves the index file via existing index flow', async () => {
+            const response = await request.get('/');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Home Page');
+        });
+    });
+
+    // ==========================================
+    // Redirect URL with extension → clean URL
+    // ==========================================
+    describe('Redirect URL with extension to clean URL', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                index: ['index.ejs'],
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const content = await fs.promises.readFile(filePath, 'utf-8');
+                        ctx.type = 'text/html';
+                        ctx.body = content;
+                    }
+                }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/about.ejs → redirect 301 to /about', async () => {
+            const response = await request.get('/about.ejs');
+            expect(response.status).toBe(301);
+            expect(response.headers.location).toBe('/about');
+        });
+
+        test('/blog/articolo.ejs → redirect 301 to /blog/articolo', async () => {
+            const response = await request.get('/blog/articolo.ejs');
+            expect(response.status).toBe(301);
+            expect(response.headers.location).toBe('/blog/articolo');
+        });
+
+        test('/about.ejs?lang=it → redirect 301 to /about?lang=it (preserves query string)', async () => {
+            const response = await request.get('/about.ejs?lang=it');
+            expect(response.status).toBe(301);
+            expect(response.headers.location).toBe('/about?lang=it');
+        });
+
+        test('/index.ejs → redirect to /', async () => {
+            const response = await request.get('/index.ejs');
+            expect(response.status).toBe(301);
+            expect(response.headers.location).toBe('/');
+        });
+
+        test('/sezione/index.ejs → redirect to /sezione/', async () => {
+            const response = await request.get('/sezione/index.ejs');
+            expect(response.status).toBe(301);
+            expect(response.headers.location).toBe('/sezione/');
+        });
+    });
+
+    // ==========================================
+    // Custom redirect code (302)
+    // ==========================================
+    describe('Custom redirect code', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                index: ['index.ejs'],
+                hideExtension: { ext: '.ejs', redirect: 302 }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/about.ejs → redirect 302 to /about', async () => {
+            const response = await request.get('/about.ejs');
+            expect(response.status).toBe(302);
+            expect(response.headers.location).toBe('/about');
+        });
+    });
+
+    // ==========================================
+    // Directory/file conflict (showDirContents: true)
+    // ==========================================
+    describe('Directory/file conflict with showDirContents: true', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                index: ['index.html'],
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const content = await fs.promises.readFile(filePath, 'utf-8');
+                        ctx.type = 'text/html';
+                        ctx.body = content;
+                    }
+                }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/about serves about.ejs (file wins over directory)', async () => {
+            const response = await request.get('/about');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('About Page');
+        });
+
+        test('/about/ shows the directory index or directory contents', async () => {
+            const response = await request.get('/about/');
+            expect(response.status).toBe(200);
+            // The about/ directory has index.html, so it's served as the index file
+            expect(response.text).toContain('About Directory Index');
+        });
+    });
+
+    // ==========================================
+    // Trailing slash without directory → 404
+    // ==========================================
+    describe('Trailing slash without directory', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                hideExtension: { ext: '.ejs' }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/nonexistent/ returns 404', async () => {
+            const response = await request.get('/nonexistent/');
+            expect(response.status).toBe(404);
+        });
+    });
+
+    // ==========================================
+    // File without extension vs .ejs conflict
+    // ==========================================
+    describe('File without extension vs .ejs conflict', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const content = await fs.promises.readFile(filePath, 'utf-8');
+                        ctx.type = 'text/html';
+                        ctx.body = content;
+                    }
+                }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/conflict-test/pagina serves pagina.ejs (ejs wins over extensionless file)', async () => {
+            const response = await request.get('/conflict-test/pagina');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Pagina EJS');
+        });
+    });
+
+    // ==========================================
+    // Interaction with urlsReserved
+    // ==========================================
+    describe('Interaction with urlsReserved', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+
+            // Add a "next" middleware to catch reserved URLs
+            app.use(async (ctx, next) => {
+                await next();
+                if (ctx.status === 404 && ctx._passedToNext) {
+                    ctx.status = 200;
+                    ctx.body = 'RESERVED';
+                }
+            });
+
+            const middleware = koaClassicServer(rootDir, {
+                showDirContents: true,
+                index: ['index.ejs'],
+                urlsReserved: ['/blog'],
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const content = await fs.promises.readFile(filePath, 'utf-8');
+                        ctx.type = 'text/html';
+                        ctx.body = content;
+                    }
+                }
+            });
+
+            // Wrap middleware to track next() calls
+            app.use(async (ctx, next) => {
+                const originalNext = next;
+                await middleware(ctx, async () => {
+                    ctx._passedToNext = true;
+                    await originalNext();
+                });
+            });
+
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/blog is reserved (passed to next middleware)', async () => {
+            const response = await request.get('/blog');
+            // blog is a directory and is reserved, so it passes to next
+            expect(response.text).toBe('RESERVED');
+        });
+
+        test('/about still resolves about.ejs normally', async () => {
+            const response = await request.get('/about');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('About Page');
+        });
+    });
+
+    // ==========================================
+    // Interaction with useOriginalUrl
+    // ==========================================
+    describe('Interaction with useOriginalUrl', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+
+            // i18n middleware that rewrites URLs
+            app.use(async (ctx, next) => {
+                if (ctx.path.match(/^\/it\//)) {
+                    ctx.url = ctx.path.replace(/^\/it/, '');
+                }
+                await next();
+            });
+
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                useOriginalUrl: false,
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const content = await fs.promises.readFile(filePath, 'utf-8');
+                        ctx.type = 'text/html';
+                        ctx.body = content;
+                    }
+                }
+            }));
+
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('redirect uses ctx.originalUrl (preserves /it/ prefix)', async () => {
+            const response = await request.get('/it/about.ejs');
+            expect(response.status).toBe(301);
+            // Redirect should use originalUrl: /it/about (not /about)
+            expect(response.headers.location).toBe('/it/about');
+        });
+
+        test('clean URL resolves through rewritten URL', async () => {
+            const response = await request.get('/it/about');
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('About Page');
+        });
+    });
+
+    // ==========================================
+    // Case-sensitive extension matching
+    // ==========================================
+    describe('Case-sensitive extension matching', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                hideExtension: { ext: '.ejs' }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/about.EJS is not handled by hideExtension (case-sensitive)', async () => {
+            const response = await request.get('/about.EJS');
+            // The file about.EJS exists, should be served normally (not redirected)
+            expect(response.status).toBe(200);
+            // Should NOT be a redirect
+            expect(response.status).not.toBe(301);
+        });
+    });
+
+    // ==========================================
+    // URLs with different extensions (no interference)
+    // ==========================================
+    describe('URLs with different extensions', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                hideExtension: { ext: '.ejs' }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('/file.ejs.bak is not interfered with', async () => {
+            const response = await request.get('/file.ejs.bak');
+            // .bak is the extension, not .ejs - should be served normally
+            expect(response.status).toBe(200);
+            expect(response.status).not.toBe(301);
+        });
+
+        test('/photo.txt is not interfered with', async () => {
+            const response = await request.get('/photo.txt');
+            expect(response.status).toBe(200);
+            expect(response.status).not.toBe(301);
+        });
+
+        test('/style.css is not interfered with', async () => {
+            const response = await request.get('/style.css');
+            expect(response.status).toBe(200);
+            expect(response.status).not.toBe(301);
+        });
+    });
+
+    // ==========================================
+    // Template engine integration
+    // ==========================================
+    describe('Template engine integration', () => {
+        let app, server, request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(rootDir, {
+                showDirContents: true,
+                index: ['index.ejs'],
+                hideExtension: { ext: '.ejs' },
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        const templateContent = await fs.promises.readFile(filePath, 'utf-8');
+                        const html = ejs.render(templateContent, { title: 'Test Title' });
+                        ctx.type = 'text/html';
+                        ctx.body = html;
+                    }
+                }
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => { server.close(); });
+
+        test('file resolved via hideExtension passes correctly to template engine', async () => {
+            const response = await request.get('/about');
+            expect(response.status).toBe(200);
+            expect(response.type).toBe('text/html');
+            expect(response.text).toContain('About Page');
+        });
+    });
+
+    // ==========================================
+    // Input Validation
+    // ==========================================
+    describe('Input validation', () => {
+
+        test('hideExtension: true → throws Error', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {
+                    hideExtension: true
+                });
+            }).toThrow();
+        });
+
+        test('hideExtension: {} → throws Error (missing ext)', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {
+                    hideExtension: {}
+                });
+            }).toThrow();
+        });
+
+        test('hideExtension: { ext: "" } → throws Error (empty ext)', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {
+                    hideExtension: { ext: '' }
+                });
+            }).toThrow();
+        });
+
+        test('hideExtension: { ext: "ejs" } → warning + normalizes to ".ejs"', () => {
+            const originalWarn = console.warn;
+            const warnings = [];
+            console.warn = (...args) => { warnings.push(args); };
+
+            try {
+                const middleware = koaClassicServer(rootDir, {
+                    hideExtension: { ext: 'ejs' }
+                });
+                // Should not throw
+                expect(middleware).toBeDefined();
+                // Should have issued a warning
+                expect(warnings.length).toBeGreaterThan(0);
+                expect(warnings[0][1]).toContain('hideExtension.ext should start with a dot');
+            } finally {
+                console.warn = originalWarn;
+            }
+        });
+
+        test('hideExtension: { ext: ".ejs", redirect: "abc" } → throws Error (redirect not numeric)', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {
+                    hideExtension: { ext: '.ejs', redirect: 'abc' }
+                });
+            }).toThrow();
+        });
+
+        test('hideExtension: { ext: ".ejs" } → valid, default redirect 301', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {
+                    hideExtension: { ext: '.ejs' }
+                });
+            }).not.toThrow();
+        });
+
+        test('hideExtension: { ext: ".ejs", redirect: 302 } → valid', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {
+                    hideExtension: { ext: '.ejs', redirect: 302 }
+                });
+            }).not.toThrow();
+        });
+
+        test('hideExtension: undefined → feature disabled (no error)', () => {
+            expect(() => {
+                koaClassicServer(rootDir, {});
+            }).not.toThrow();
+        });
+    });
+});

package/__tests__/publicWwwTest/hideext-test/about/index.html

@@ -0,0 +1 @@
+<h1>About Directory Index</h1>

package/__tests__/publicWwwTest/hideext-test/about.EJS

@@ -0,0 +1 @@
+<h1>About UPPERCASE</h1>

package/__tests__/publicWwwTest/hideext-test/about.ejs

@@ -0,0 +1,2 @@
+<h1>About Page</h1>
+<p>This is the about page rendered from about.ejs</p>

package/__tests__/publicWwwTest/hideext-test/blog/articolo.ejs

@@ -0,0 +1,2 @@
+<h1>Blog Article</h1>
+<p>This is a blog article rendered from blog/articolo.ejs</p>

package/__tests__/publicWwwTest/hideext-test/conflict-test/pagina

@@ -0,0 +1 @@
+plain pagina file

package/__tests__/publicWwwTest/hideext-test/conflict-test/pagina.ejs

@@ -0,0 +1 @@
+<h1>Pagina EJS</h1>

package/__tests__/publicWwwTest/hideext-test/file.ejs.bak

@@ -0,0 +1 @@
+backup file

package/__tests__/publicWwwTest/hideext-test/index.ejs

@@ -0,0 +1,2 @@
+<h1>Home Page</h1>
+<p>This is the index page</p>

package/__tests__/publicWwwTest/hideext-test/photo.txt

@@ -0,0 +1 @@
+This is a photo description file

package/__tests__/publicWwwTest/hideext-test/sezione/index.ejs

@@ -0,0 +1 @@
+<h1>Sezione Index</h1>

package/__tests__/publicWwwTest/hideext-test/style.css

@@ -0,0 +1 @@
+body { color: red; }

package/docs/CHANGELOG.md

@@ -5,6 +5,75 @@ 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.5.1] - 2026-03-01
+
+### 📝 Documentation
+
+- Added dedicated usage example for `useOriginalUrl` (Section 7) with realistic i18n middleware scenario (/it/, /en/, /fr/)
+- Added "Advanced hideExtension Scenarios" section (Section 8):
+  - Recommended file/directory structure (ASCII tree)
+  - Combined `hideExtension` + i18n middleware example with `useOriginalUrl: false`
+  - Temporary redirect (302) variant with guidance on 301 vs 302 usage
+- Added `hideExtension` and `useOriginalUrl` to the Complete Production Example (Section 11)
+
+### 📦 Package Changes
+- **Version**: `2.5.0` → `2.5.1`
+- **Semver**: Patch version bump (documentation only, no code changes)
+
+---
+
+## [2.5.0] - 2026-02-28
+
+### ✨ New Feature
+
+#### hideExtension - Clean URLs (mod_rewrite-like)
+- **New Option**: `hideExtension: { ext: '.ejs', redirect: 301 }`
+- **Purpose**: Hide file extensions from URLs for SEO-friendly clean URLs
+- **Clean URL Resolution**: `/about` → serves `about.ejs` (when file exists)
+- **Extension Redirect**: `/about.ejs` → 301 redirect to `/about` (preserves query string)
+- **Index File Redirect**: `/index.ejs` → redirect to `/`, `/section/index.ejs` → redirect to `/section/`
+- **Conflict Resolution**: `.ejs` file wins over both directories and extensionless files with same base name
+- **Case-Sensitive**: Extension matching is case-sensitive (`.ejs` ≠ `.EJS`)
+- **No Interference**: URLs with other extensions (`.css`, `.png`, etc.) pass through normally
+- **Trailing Slash**: `/about/` always means directory, never resolves to file
+- **Redirect uses `ctx.originalUrl`**: Preserves URL prefixes from upstream middleware (i18n, routing)
+
+#### Input Validation
+- `hideExtension: true` → throws Error (must be an object)
+- `hideExtension: {}` → throws Error (missing `ext`)
+- `hideExtension: { ext: '' }` → throws Error (empty ext)
+- `hideExtension: { ext: 'ejs' }` → warning + auto-normalizes to `.ejs`
+- `hideExtension: { ext: '.ejs', redirect: 'abc' }` → throws Error (redirect must be number)
+
+#### Integration with Existing Options
+- **urlsReserved**: Checked before `hideExtension`, no interference
+- **urlPrefix**: `hideExtension` works on path after prefix removal
+- **useOriginalUrl**: Resolution follows setting; redirect always uses `ctx.originalUrl`
+- **template**: Resolved files pass through template engine normally
+- **method**: `hideExtension` only applies to allowed HTTP methods
+
+### 🧪 Testing
+- Added `__tests__/hideExtension.test.js` with 31 tests covering:
+  - Clean URL resolution (single and multi-level paths)
+  - Extension redirect (301/302, query string preservation)
+  - Directory/file conflict resolution
+  - Trailing slash behavior
+  - Extensionless file conflict
+  - Index file redirect (`/index.ejs` → `/`)
+  - `urlsReserved` interaction
+  - `useOriginalUrl` interaction (redirect preserves prefix)
+  - Case-sensitive matching
+  - No interference with other extensions
+  - Template engine integration
+  - Input validation (7 validation tests)
+- All 278 existing tests still pass (zero regressions)
+
+### 📦 Package Changes
+- **Version**: `2.4.0` → `2.5.0`
+- **Semver**: Minor version bump (new feature, backward compatible)
+
+---
+
 ## [2.4.0] - 2026-02-28
 
 ### 🐛 Bug Fix

package/index.cjs

@@ -51,6 +51,10 @@ module.exports = function koaClassicServer(
                                     // to reduce bandwidth usage and improve performance.
         useOriginalUrl: true, // Use ctx.originalUrl (default) or ctx.url
                               // Set false for URL rewriting middleware (i18n, routing)
+        hideExtension: {     // Hide file extension from URLs (clean URLs like mod_rewrite)
+            ext: '.ejs',     // Extension to hide (required, string, case-sensitive, must start with '.')
+            redirect: 301    // HTTP redirect code for URLs with extension (optional, default: 301)
+        },
 
         // DEPRECATED OPTIONS (maintained for backward compatibility):
         // cacheMaxAge: use browserCacheMaxAge instead
@@ -138,6 +142,35 @@ module.exports = function koaClassicServer(
     options.browserCacheEnabled = typeof options.browserCacheEnabled === 'boolean' ? options.browserCacheEnabled : false;
     options.useOriginalUrl = typeof options.useOriginalUrl === 'boolean' ? options.useOriginalUrl : true;
 
+    // Validate and normalize hideExtension option
+    if (options.hideExtension !== undefined && options.hideExtension !== null) {
+        if (typeof options.hideExtension !== 'object' || Array.isArray(options.hideExtension)) {
+            throw new Error('[koa-classic-server] hideExtension must be an object with an "ext" property. Example: { ext: ".ejs" }');
+        }
+        if (!options.hideExtension.ext || typeof options.hideExtension.ext !== 'string') {
+            throw new Error('[koa-classic-server] hideExtension.ext is required and must be a non-empty string. Example: { ext: ".ejs" }');
+        }
+        // Normalize ext: add leading dot if missing
+        if (!options.hideExtension.ext.startsWith('.')) {
+            console.warn(
+                '\x1b[33m%s\x1b[0m',
+                '[koa-classic-server] WARNING: hideExtension.ext should start with a dot.\n' +
+                `  Current usage: ext: "${options.hideExtension.ext}"\n` +
+                `  Corrected to:  ext: ".${options.hideExtension.ext}"\n` +
+                '  Please update your configuration.'
+            );
+            options.hideExtension.ext = '.' + options.hideExtension.ext;
+        }
+        // Validate redirect code
+        if (options.hideExtension.redirect !== undefined) {
+            if (typeof options.hideExtension.redirect !== 'number') {
+                throw new Error('[koa-classic-server] hideExtension.redirect must be a number (e.g. 301, 302). Got: ' + typeof options.hideExtension.redirect);
+            }
+        } else {
+            options.hideExtension.redirect = 301;
+        }
+    }
+
     /**
      * Returns true if dirent is a regular file or a symlink pointing to a regular file.
      * Uses fs.promises.stat (which follows symlinks) only when dirent.isSymbolicLink() is true.
@@ -242,6 +275,68 @@ module.exports = function koaClassicServer(
 
         let toOpen = fullPath;
 
+        // hideExtension logic: redirect URLs with extension and resolve clean URLs
+        // Track if original URL had trailing slash (stripped by pageHref construction above)
+        const originalUrlPath = new URL(ctx.protocol + '://' + ctx.host + urlToUse).pathname;
+        const hadTrailingSlash = originalUrlPath.length > 1 && originalUrlPath.endsWith('/');
+
+        if (options.hideExtension) {
+            const hideExt = options.hideExtension.ext;
+            const hideRedirect = options.hideExtension.redirect;
+
+            // Check if URL ends with the configured extension → redirect to clean URL
+            // Use the original path (before trailing slash stripping) for accurate matching
+            const pathForExtCheck = hadTrailingSlash ? originalUrlPath.slice(0, -1) : requestedPath;
+            if (pathForExtCheck.endsWith(hideExt)) {
+                // Build redirect target using ctx.originalUrl (always, regardless of useOriginalUrl)
+                const originalUrlObj = new URL(ctx.protocol + '://' + ctx.host + ctx.originalUrl);
+                let redirectPath = originalUrlObj.pathname;
+
+                // Remove the extension from the path
+                redirectPath = redirectPath.slice(0, redirectPath.length - hideExt.length);
+
+                // Special case: /index.ejs → /, /sezione/index.ejs → /sezione/
+                const baseName = path.basename(redirectPath);
+                // Check if the remaining path points to an index file
+                if (options.index && options.index.length > 0) {
+                    for (const pattern of options.index) {
+                        if (typeof pattern === 'string' && (baseName + hideExt) === pattern) {
+                            // Redirect to the directory (with trailing slash)
+                            redirectPath = redirectPath.slice(0, redirectPath.length - baseName.length);
+                            break;
+                        }
+                    }
+                }
+
+                // Preserve query string
+                const redirectUrl = redirectPath + (originalUrlObj.search || '');
+
+                ctx.status = hideRedirect;
+                ctx.redirect(redirectUrl);
+                return;
+            }
+
+            // Check if URL has no extension → try adding the configured extension
+            // Skip if original URL had trailing slash (trailing slash = directory intent)
+            const extOfRequested = path.extname(requestedPath);
+            if (!extOfRequested && requestedPath !== '' && !requestedPath.endsWith('/') && !hadTrailingSlash) {
+                const pathWithExt = fullPath + hideExt;
+
+                // Security check: ensure resolved path is still within rootDir
+                if (pathWithExt.startsWith(normalizedRootDir)) {
+                    try {
+                        const statWithExt = await fs.promises.stat(pathWithExt);
+                        if (statWithExt.isFile()) {
+                            // File with extension exists, serve it
+                            toOpen = pathWithExt;
+                        }
+                    } catch {
+                        // File with extension doesn't exist, continue normal flow
+                    }
+                }
+            }
+        }
+
         // OPTIMIZATION: Check if file/directory exists (async, non-blocking)
         let stat;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "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": {

package/.vscode/OLD_launch.json

@@ -1,26 +0,0 @@
-{
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-    {
-        "name": "Attach by Process ID",
-        "processId": "${command:PickProcess}",
-        "request": "attach",
-        "skipFiles": [
-            "<node_internals>/**"
-        ],
-        "type": "node"
-    },
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "Launch Program",
-            "skipFiles": [
-                "<node_internals>/**"
-            ],
-            "program": "${workspaceFolder}/index.cjs"
-        }
-    ]
-}

package/.vscode/launch.json

@@ -1,41 +0,0 @@
-{
-    "version": "0.2.0",
-    "configurations": [
-      {
-        "name": "Attach by Process ID",
-        "processId": "${command:PickProcess}",
-        "request": "attach",
-        "skipFiles": [
-          "<node_internals>/**"
-        ],
-        "type": "node"
-      },
-      {
-        "type": "node",
-        "request": "launch",
-        "name": "Launch Program",
-        "skipFiles": [
-          "<node_internals>/**"
-        ],
-        "program": "${workspaceFolder}/index.cjs"
-      },
-      {
-        "name": "Debug Jest Tests",
-        "type": "node",
-        "request": "launch",
-        "runtimeExecutable": "node",
-        "runtimeArgs": [
-          "--inspect-brk",
-          "${workspaceFolder}/node_modules/jest/bin/jest.js",
-          "--runInBand"
-        ],
-        "port": 9229,
-        "console": "integratedTerminal",
-        "internalConsoleOptions": "neverOpen",
-        "skipFiles": [
-          "<node_internals>/**"
-        ]
-      }
-    ]
-  }
-