koa-classic-server 2.1.0 → 2.1.2

package/README.md

@@ -1,48 +1,75 @@
 # koa-classic-server
 
-🔒 **Secure Koa middleware for serving static files** with Apache-like directory listing, template engine support, and comprehensive security fixes.
+🚀 **Production-ready Koa middleware** for serving static files with Apache2-like directory listing, sortable columns, HTTP caching, template engine support, and enterprise-grade security.
 
 [![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-146%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-153%20passing-brightgreen.svg)]()
 
-## ⚠️ Version 1.2.0 - Critical Security Update
+---
+
+## 🎉 Version 2.1.2 - Production Release
+
+Version 2.1.2 is a **major production release** featuring performance optimizations, enhanced directory listing, and critical bug fixes.
+
+### What's New in 2.1.2
 
-Version 1.2.0 includes **critical security fixes** for path traversal vulnerabilities and other important improvements. **Upgrade immediately** if you're using version 1.1.0 or earlier.
+✅ **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
+✅ **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 1.2.0
+### What's New in 2.0
 
-✅ **Fixed Path Traversal Vulnerability** - No more unauthorized file access
-✅ **Proper HTTP 404 Status Codes** - Standards-compliant error handling
-✅ **Template Error Handling** - No more server crashes
-✅ **XSS Protection** - HTML escaping in directory listings
-✅ **Race Condition Fixes** - Robust file access
-✅ **146 Tests Passing** - Comprehensive test coverage including EJS integration
+✅ **Performance Optimizations** - 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
 
-[See full changelog](./docs/CHANGELOG.md)
+[See full changelog →](./docs/CHANGELOG.md)
+
+---
 
 ## Features
 
-koa-classic-server is a middleware for serving static files from a directory with Apache 2-like behavior. The contents of a folder on the server will be shown remotely and if you want to access a file, click on it.
+**koa-classic-server** is a high-performance middleware for serving static files with Apache2-like behavior, making file browsing intuitive and powerful.
 
-**Key Features:**
+### Core Features
 
-- 🗂️ **Directory Listing** - Apache-style browseable directories
-- 📄 **Static File Serving** - Automatic MIME type detection
-- 🎨 **Template Engine Support** - Integrate EJS, Pug, Handlebars, etc.
-- 🔒 **Security** - Path traversal protection, XSS prevention
-- ⚙️ **Configurable** - URL prefixes, reserved paths, index files
-- 🧪 **Well-Tested** - 146 tests with comprehensive coverage (security, EJS, performance)
+- 🗂️ **Apache2-like Directory Listing** - Sortable columns (Name, Type, Size)
+- 📄 **Static File Serving** - Automatic MIME type detection with streaming
+- 📊 **Sortable Columns** - Click headers to sort ascending/descending
+- 📏 **File Sizes** - Human-readable display (B, KB, MB, GB, TB)
+- ⚡ **HTTP Caching** - ETag, Last-Modified, 304 responses
+- 🎨 **Template Engine Support** - EJS, Pug, Handlebars, Nunjucks, etc.
+- 🔒 **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
 - 📦 **Dual Module Support** - CommonJS and ES Modules
 
+---
+
 ## Installation
 
 ```bash
 npm install koa-classic-server
 ```
 
+**Requirements:**
+- Node.js >= 12.0.0
+- Koa >= 2.0.0
+
+---
+
 ## Quick Start
 
+### Basic Usage
+
 ```javascript
 const Koa = require('koa');
 const koaClassicServer = require('koa-classic-server');
@@ -56,9 +83,30 @@ app.listen(3000);
 console.log('Server running on http://localhost:3000');
 ```
 
-## Usage
+### With Options
 
-### Import
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+app.use(koaClassicServer(__dirname + '/public', {
+  showDirContents: true,
+  index: ['index.html', 'index.htm'],
+  urlPrefix: '/static',
+  cacheMaxAge: 3600,
+  enableCaching: true
+}));
+
+app.listen(3000);
+```
+
+---
+
+## Complete Usage Guide
+
+### 1. Import
 
 ```javascript
 // CommonJS
@@ -68,9 +116,9 @@ const koaClassicServer = require('koa-classic-server');
 import koaClassicServer from 'koa-classic-server';
 ```
 
-### Basic Examples
+### 2. Basic File Server
 
-#### Example 1: Simple File Server
+Serve static files from a directory:
 
 ```javascript
 const Koa = require('koa');
@@ -80,57 +128,173 @@ const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/public', {
   showDirContents: true,
-  index: ['index.html']  // Array format (recommended)
+  index: ['index.html']
 }));
 
 app.listen(3000);
 ```
 
-#### Example 2: With URL Prefix
+**What it does:**
+- Serves files from `/public` directory
+- Shows directory listing when accessing folders
+- Looks for `index.html` in directories
+- Sortable columns (Name, Type, Size)
+- File sizes displayed in human-readable format
 
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
+### 3. With URL Prefix
 
-const app = new Koa();
+Serve files under a specific URL path:
 
-// Files accessible under /static
-// e.g., http://localhost:3000/static/image.png
-app.use(koaClassicServer(__dirname + '/public', {
+```javascript
+app.use(koaClassicServer(__dirname + '/assets', {
   urlPrefix: '/static',
   showDirContents: true
 }));
+```
 
-app.listen(3000);
+**Result:**
+- `http://localhost:3000/static/image.png` → serves `/assets/image.png`
+- `http://localhost:3000/static/` → shows `/assets` directory listing
+
+### 4. With Reserved Paths
+
+Protect specific directories from being accessed:
+
+```javascript
+app.use(koaClassicServer(__dirname + '/www', {
+  urlsReserved: ['/admin', '/config', '/.git', '/node_modules']
+}));
 ```
 
-#### Example 3: With Template Engine (EJS)
+**Result:**
+- `/admin/*` → passed to next middleware (not served)
+- `/config/*` → protected
+- Other paths → served normally
+
+### 5. With Template Engine (EJS)
+
+Dynamically render templates with data:
 
 ```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
 const ejs = require('ejs');
-const fs = require('fs').promises;
-
-const app = new Koa();
 
 app.use(koaClassicServer(__dirname + '/views', {
   template: {
-    ext: ['ejs'],  // File extensions to process
+    ext: ['ejs', 'html.ejs'],
     render: async (ctx, next, filePath) => {
-      // Read template file
-      const templateContent = await fs.readFile(filePath, 'utf-8');
-
-      // Render with data
-      const html = ejs.render(templateContent, {
+      const data = {
         title: 'My App',
         user: ctx.state.user || { name: 'Guest' },
-        path: ctx.path,
+        items: ['Item 1', 'Item 2', 'Item 3'],
         timestamp: new Date().toISOString()
-      });
+      };
 
+      ctx.body = await ejs.renderFile(filePath, data);
       ctx.type = 'text/html';
-      ctx.body = html;
+    }
+  }
+}));
+```
+
+**Template example (`views/dashboard.ejs`):**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title><%= title %></title>
+</head>
+<body>
+    <h1>Welcome, <%= user.name %>!</h1>
+    <ul>
+    <% items.forEach(item => { %>
+        <li><%= item %></li>
+    <% }); %>
+    </ul>
+    <p>Generated at: <%= timestamp %></p>
+</body>
+</html>
+```
+
+**See complete guide:** [Template Engine Documentation →](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)
+
+### 6. With HTTP Caching
+
+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)
+}));
+```
+
+**Benefits:**
+- 80-95% bandwidth reduction
+- 304 Not Modified responses for unchanged files
+- Faster page loads for returning visitors
+
+**See details:** [HTTP Caching Optimization →](./docs/OPTIMIZATION_HTTP_CACHING.md)
+
+### 7. Multiple Index Files with Priority
+
+Search for multiple index files with custom order:
+
+```javascript
+app.use(koaClassicServer(__dirname + '/public', {
+  index: [
+    'index.html',           // First priority
+    'index.htm',            // Second priority
+    /index\.[eE][jJ][sS]/,  // Third: index.ejs (case-insensitive)
+    'default.html'          // Last priority
+  ]
+}));
+```
+
+**See details:** [Index Option Priority →](./docs/INDEX_OPTION_PRIORITY.md)
+
+### 8. Complete Production Example
+
+Real-world configuration for production:
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+const ejs = require('ejs');
+const path = require('path');
+
+const app = new Koa();
+
+// Serve static assets with caching
+app.use(koaClassicServer(path.join(__dirname, 'public'), {
+  method: ['GET', 'HEAD'],
+  showDirContents: false,  // Disable directory listing in production
+  index: ['index.html', 'index.htm'],
+  urlPrefix: '/assets',
+  urlsReserved: ['/admin', '/api', '/.git'],
+  enableCaching: true,
+  cacheMaxAge: 86400,  // 24 hours
+}));
+
+// Serve dynamic templates
+app.use(koaClassicServer(path.join(__dirname, 'views'), {
+  showDirContents: false,
+  template: {
+    ext: ['ejs'],
+    render: async (ctx, next, filePath) => {
+      const data = {
+        env: process.env.NODE_ENV,
+        user: ctx.state.user,
+        config: ctx.state.config
+      };
+
+      try {
+        ctx.body = await ejs.renderFile(filePath, data);
+        ctx.type = 'text/html';
+      } catch (error) {
+        console.error('Template error:', error);
+        ctx.status = 500;
+        ctx.body = 'Internal Server Error';
+      }
     }
   }
 }));
@@ -138,9 +302,9 @@ app.use(koaClassicServer(__dirname + '/views', {
 app.listen(3000);
 ```
 
-See **[Template Engine Guide](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)** for comprehensive template engine documentation with progressive examples.
+---
 
-## API
+## API Reference
 
 ### koaClassicServer(rootDir, options)
 
@@ -148,56 +312,54 @@ Creates a Koa middleware for serving static files.
 
 **Parameters:**
 
-- `rootDir` (String, required): Absolute path to the directory containing static files
-- `options` (Object, optional): Configuration options
+- **`rootDir`** (String, required): Absolute path to the directory containing files
+- **`options`** (Object, optional): Configuration options
 
 **Returns:** Koa middleware function
 
-## Options
+### Options
 
 ```javascript
-const options = {
+{
   // HTTP methods allowed (default: ['GET'])
   method: ['GET', 'HEAD'],
 
   // Show directory contents (default: true)
   showDirContents: true,
 
-  // Index file configuration (default: [])
-  // RECOMMENDED: Use array format (string format is deprecated)
-  // Formats:
-  //   - Array of strings: ['index.html', 'index.htm', 'default.html']
-  //   - Array of RegExp: [/index\.html/i] (case-insensitive)
-  //   - Mixed array: ['index.html', /INDEX\.HTM/i]
-  // Priority: First match wins (array order determines search priority)
-  //
-  // DEPRECATED: String format 'index.html' still works but will be removed
-  // in future versions. Please use array format: ['index.html']
-  //
-  // See INDEX_OPTION_PRIORITY.md for detailed behavior documentation
-  index: ['index.html'],
+  // Index file configuration
+  // Array format (recommended):
+  //   - Strings: exact matches ['index.html', 'default.html']
+  //   - RegExp: pattern matches [/index\.html/i]
+  //   - Mixed: ['index.html', /INDEX\.HTM/i]
+  // Priority determined by array order (first match wins)
+  // See docs/INDEX_OPTION_PRIORITY.md for details
+  index: ['index.html', 'index.htm'],
 
   // URL path prefix (default: '')
-  // Files will be served under this prefix
+  // Files served under this prefix
   urlPrefix: '/static',
 
   // Reserved paths (default: [])
-  // These directories won't be accessible
-  // Note: Only works for first-level directories
-  urlsReserved: ['/admin', '/private'],
+  // First-level directories passed to next middleware
+  urlsReserved: ['/admin', '/api', '/.git'],
 
   // Template engine configuration
   template: {
     // Template rendering function
     render: async (ctx, next, filePath) => {
       // Your rendering logic
-      ctx.body = await yourTemplateEngine.render(filePath, data);
+      ctx.body = await yourEngine.render(filePath, data);
     },
 
-    // File extensions to process with template.render
+    // File extensions to process
     ext: ['ejs', 'pug', 'hbs']
-  }
-};
+  },
+
+  // HTTP caching configuration
+  enableCaching: true,      // Enable ETag & Last-Modified (default: true)
+  cacheMaxAge: 3600,        // Cache-Control max-age in seconds (default: 3600 = 1 hour)
+}
 ```
 
 ### Options Details
@@ -206,133 +368,383 @@ const options = {
 |--------|------|---------|-------------|
 | `method` | Array | `['GET']` | Allowed HTTP methods |
 | `showDirContents` | Boolean | `true` | Show directory listing |
-| `index` | String | `''` | Index file name |
+| `index` | Array/String | `[]` | Index file patterns (array format recommended) |
 | `urlPrefix` | String | `''` | URL path prefix |
-| `urlsReserved` | Array | `[]` | Reserved directory paths |
+| `urlsReserved` | Array | `[]` | Reserved directory paths (first-level only) |
 | `template.render` | Function | `undefined` | Template rendering function |
 | `template.ext` | Array | `[]` | Extensions for template rendering |
+| `enableCaching` | Boolean | `true` | Enable HTTP caching headers |
+| `cacheMaxAge` | Number | `3600` | Cache duration in seconds |
+
+---
+
+## Directory Listing Features
+
+### Sortable Columns
+
+Click on column headers to sort:
+
+- **Name** - Alphabetical sorting (A-Z or Z-A)
+- **Type** - Sort by MIME type (directories always first)
+- **Size** - Sort by file size (directories always first)
+
+Visual indicators:
+- **↑** - Ascending order
+- **↓** - Descending order
+
+### File Size Display
+
+Human-readable format:
+- `1.5 KB` - Kilobytes
+- `2.3 MB` - Megabytes
+- `1.2 GB` - Gigabytes
+- `-` - Directories (no size)
+
+### Navigation
+
+- **Click folder name** - Enter directory
+- **Click file name** - Download/view file
+- **Parent Directory** - Go up one level
+
+---
 
 ## Security
 
-### Path Traversal Protection
+### Built-in Protection
+
+koa-classic-server includes enterprise-grade security:
 
-koa-classic-server 1.2.0 protects against path traversal attacks:
+#### 1. Path Traversal Protection
+
+Prevents access to files outside `rootDir`:
 
 ```javascript
-// ❌ These requests are blocked (return 403 Forbidden)
-GET /../../../etc/passwd
-GET /../config/database.yml
-GET /%2e%2e%2fpackage.json
+// ❌ Blocked requests
+GET /../../../etc/passwd       → 403 Forbidden
+GET /../config/database.yml    → 403 Forbidden
+GET /%2e%2e%2fpackage.json     → 403 Forbidden
 ```
 
-### Protected Directories
+#### 2. XSS Protection
 
-Use `urlsReserved` to protect sensitive directories:
+All filenames and paths are HTML-escaped:
 
 ```javascript
-app.use(koaClassicServer(__dirname + '/www', {
-  urlsReserved: ['/config', '/private', '/.git', '/node_modules']
+// Malicious filename: <script>alert('xss')</script>.txt
+// Displayed as: &lt;script&gt;alert('xss')&lt;/script&gt;.txt
+// ✅ Safe - script doesn't execute
+```
+
+#### 3. Reserved URLs
+
+Protect sensitive directories:
+
+```javascript
+app.use(koaClassicServer(__dirname, {
+  urlsReserved: ['/admin', '/config', '/.git', '/node_modules']
 }));
 ```
 
-### XSS Protection
+#### 4. Race Condition Protection
+
+File access is verified before streaming:
+
+```javascript
+// File deleted between check and access?
+// ✅ Returns 404 instead of crashing
+```
+
+**See full security audit:** [Security Tests →](./__tests__/security.test.js)
+
+---
+
+## Performance
 
-All filenames and paths in directory listings are HTML-escaped to prevent XSS attacks.
+### Optimizations
 
-## Error Handling
+Version 2.x includes major performance improvements:
 
-koa-classic-server properly handles errors:
+- **Async/Await** - Non-blocking I/O, event loop never blocked
+- **Array Join** - 30-40% less memory vs string concatenation
+- **HTTP Caching** - 80-95% bandwidth reduction
+- **Single stat() Call** - No double file system access
+- **Streaming** - Large files streamed efficiently
 
-- **404** - File/directory not found
-- **403** - Forbidden (path traversal attempts, reserved directories)
-- **500** - Template rendering errors, file access errors
+### Benchmarks
+
+Performance results on directory with 1,000 files:
+
+```
+Before (v1.x):     ~350ms per request
+After (v2.x):      ~190ms per request
+Improvement:       46% faster
+```
+
+**See detailed benchmarks:** [Performance Analysis →](./docs/PERFORMANCE_ANALYSIS.md)
+
+---
 
 ## Testing
 
+Run the comprehensive test suite:
+
 ```bash
 # Run all tests
 npm test
 
 # Run security tests only
 npm run test:security
+
+# Run performance benchmarks
+npm run test:performance
 ```
 
-## Middleware Behavior
+**Test Coverage:**
+- ✅ 153 tests passing
+- ✅ Security tests (path traversal, XSS, race conditions)
+- ✅ EJS template integration tests
+- ✅ Index option tests (strings, arrays, RegExp)
+- ✅ Performance benchmarks
+- ✅ Directory sorting tests
 
-### Directory Handling
+---
 
-1. If `index` file exists → serve index file
-2. If `showDirContents: true` → show directory listing
-3. If `showDirContents: false` → return 404
+## Complete Documentation
 
-### File Handling
+### Core Documentation
 
-1. Check if file extension matches `template.ext`
-2. If yes → call `template.render()`
-3. If no → serve static file with appropriate MIME type
+- **[DOCUMENTATION.md](./docs/DOCUMENTATION.md)** - Complete API reference and usage guide
+- **[FLOW_DIAGRAM.md](./docs/FLOW_DIAGRAM.md)** - Visual flow diagrams and code execution paths
+- **[CHANGELOG.md](./docs/CHANGELOG.md)** - Version history and release notes
 
-### Reserved URLs
+### Template Engine
 
-Requests to reserved paths are passed to the next middleware.
+- **[TEMPLATE_ENGINE_GUIDE.md](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)** - Complete guide to template engine integration
+  - Progressive examples (simple to enterprise)
+  - EJS, Pug, Handlebars, Nunjucks support
+  - Best practices and troubleshooting
 
-## Migration from 1.1.0
+### Configuration
 
-Upgrading is simple! No code changes required:
+- **[INDEX_OPTION_PRIORITY.md](./docs/INDEX_OPTION_PRIORITY.md)** - Detailed priority behavior for `index` option
+  - String vs Array vs RegExp formats
+  - Priority order examples
+  - Migration guide from v1.x
 
-```bash
-npm update koa-classic-server
-```
+- **[EXAMPLES_INDEX_OPTION.md](./docs/EXAMPLES_INDEX_OPTION.md)** - 10 practical examples of `index` option with RegExp
+  - Case-insensitive matching
+  - Multiple extensions
+  - Complex patterns
 
-**What changed:**
-- 404 status codes now correct (was 200)
-- Path traversal blocked (was allowed)
-- Template errors return 500 (was crash)
+### Performance
 
-See [CHANGELOG.md](./CHANGELOG.md) for detailed information.
+- **[PERFORMANCE_ANALYSIS.md](./docs/PERFORMANCE_ANALYSIS.md)** - Performance optimization analysis
+  - Before/after comparisons
+  - Memory usage analysis
+  - Bottleneck identification
 
-## Complete Documentation
+- **[PERFORMANCE_COMPARISON.md](./docs/PERFORMANCE_COMPARISON.md)** - Detailed performance benchmarks
+  - Request latency
+  - Throughput metrics
+  - Concurrent request handling
 
-For complete documentation with all features, examples, troubleshooting, and best practices, see:
+- **[OPTIMIZATION_HTTP_CACHING.md](./docs/OPTIMIZATION_HTTP_CACHING.md)** - HTTP caching implementation details
+  - ETag generation
+  - Last-Modified headers
+  - 304 Not Modified responses
+
+- **[BENCHMARKS.md](./docs/BENCHMARKS.md)** - Benchmark results and methodology
+
+### Code Quality
 
-- **[DOCUMENTATION.md](./docs/DOCUMENTATION.md)** - Complete API reference and usage guide
-- **[FLOW_DIAGRAM.md](./docs/FLOW_DIAGRAM.md)** - Visual flow diagrams and code execution paths
-- **[TEMPLATE_ENGINE_GUIDE.md](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)** - Complete guide to template engine integration (EJS, Pug, Handlebars, Nunjucks)
-- **[INDEX_OPTION_PRIORITY.md](./docs/INDEX_OPTION_PRIORITY.md)** - Detailed priority behavior for `index` option (string, array, RegExp)
-- **[EXAMPLES_INDEX_OPTION.md](./docs/EXAMPLES_INDEX_OPTION.md)** - 10 practical examples of `index` option with RegExp
-- **[PERFORMANCE_ANALYSIS.md](./docs/PERFORMANCE_ANALYSIS.md)** - Performance optimization analysis
-- **[PERFORMANCE_COMPARISON.md](./docs/PERFORMANCE_COMPARISON.md)** - Before/after performance benchmarks
 - **[CODE_REVIEW.md](./docs/CODE_REVIEW.md)** - Code quality analysis and review
+  - Security audit
+  - Best practices
+  - Standardization improvements
+
+- **[DEBUG_REPORT.md](./docs/DEBUG_REPORT.md)** - Known limitations and debugging info
+  - Reserved URLs behavior
+  - Edge cases
+  - Troubleshooting tips
+
+---
+
+## Migration Guide
+
+### From v1.x to v2.x
+
+**Breaking Changes:**
+- `index` option: String format deprecated (still works), use array format
+
+**Migration:**
+
+```javascript
+// v1.x (deprecated)
+{
+  index: 'index.html'
+}
+
+// v2.x (recommended)
+{
+  index: ['index.html']
+}
+```
+
+**New Features:**
+- HTTP caching (enabled by default)
+- Sortable directory columns
+- File size display
+- Enhanced index option with RegExp
+
+**See full migration guide:** [CHANGELOG.md](./docs/CHANGELOG.md)
+
+---
+
+## Examples
+
+### Example 1: Simple Static Server
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+app.use(koaClassicServer(__dirname + '/public'));
+app.listen(3000);
+```
+
+### Example 2: Multi-Directory Server
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+
+const app = new Koa();
+
+// Serve static assets
+app.use(koaClassicServer(__dirname + '/public', {
+  urlPrefix: '/static',
+  showDirContents: false
+}));
+
+// Serve user uploads
+app.use(koaClassicServer(__dirname + '/uploads', {
+  urlPrefix: '/files',
+  showDirContents: true
+}));
+
+app.listen(3000);
+```
+
+### Example 3: Development Server with Templates
+
+```javascript
+const Koa = require('koa');
+const koaClassicServer = require('koa-classic-server');
+const ejs = require('ejs');
+
+const app = new Koa();
+
+// Development mode - show directories
+app.use(koaClassicServer(__dirname + '/src', {
+  showDirContents: true,
+  template: {
+    ext: ['ejs'],
+    render: async (ctx, next, filePath) => {
+      ctx.body = await ejs.renderFile(filePath, {
+        dev: true,
+        timestamp: Date.now()
+      });
+      ctx.type = 'text/html';
+    }
+  }
+}));
+
+app.listen(3000);
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: 404 errors for all files**
+
+Check that `rootDir` is an absolute path:
+
+```javascript
+// ❌ Wrong (relative path)
+koaClassicServer('./public')
+
+// ✅ Correct (absolute path)
+koaClassicServer(__dirname + '/public')
+koaClassicServer(path.join(__dirname, 'public'))
+```
+
+**Issue: Reserved URLs not working**
+
+Reserved URLs only work for first-level directories:
+
+```javascript
+urlsReserved: ['/admin']  // ✅ Blocks /admin/*
+urlsReserved: ['/admin/users']  // ❌ Doesn't work (nested)
+```
+
+**Issue: Directory sorting not working**
+
+Make sure you're accessing directories without query params initially. The sorting is applied when you click headers.
+
+**See full troubleshooting:** [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md)
+
+---
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass (`npm test`)
+5. Submit a pull request
+
+---
 
 ## Known Limitations
 
 - Reserved URLs only work for first-level directories
+- Template rendering is synchronous per request
 
 See [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md) for technical details.
 
+---
+
 ## License
 
-MIT
+MIT License - see LICENSE file for details
+
+---
 
 ## Author
 
 Italo Paesano
 
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md)
+---
 
 ## Links
 
-- [Full Documentation](./docs/DOCUMENTATION.md)
-- [Debug Report](./docs/DEBUG_REPORT.md)
-- [Changelog](./CHANGELOG.md)
-- [Repository](https://github.com/italopaesano/koa-classic-server)
-- [npm Package](https://www.npmjs.com/package/koa-classic-server)
+- **[npm Package](https://www.npmjs.com/package/koa-classic-server)** - Official npm package
+- **[GitHub Repository](https://github.com/italopaesano/koa-classic-server)** - Source code
+- **[Issue Tracker](https://github.com/italopaesano/koa-classic-server/issues)** - Report bugs
+- **[Full Documentation](./docs/DOCUMENTATION.md)** - Complete reference
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](./docs/CHANGELOG.md) for version history.
 
 ---
 
-**⚠️ Security Notice:** Version 1.2.0 fixes critical vulnerabilities. Update immediately if using 1.1.0 or earlier.
+**⚠️ Security Notice:** Always use the latest version for security updates and bug fixes.

package/package.json

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