koa-classic-server 2.0.0 → 2.1.0

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-71%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-146%20passing-brightgreen.svg)]()
 
 ## ⚠️ Version 1.2.0 - Critical Security Update
 
@@ -17,9 +17,9 @@ Version 1.2.0 includes **critical security fixes** for path traversal vulnerabil
 ✅ **Template Error Handling** - No more server crashes
 ✅ **XSS Protection** - HTML escaping in directory listings
 ✅ **Race Condition Fixes** - Robust file access
-✅ **71 Tests Passing** - Comprehensive test coverage
+✅ **146 Tests Passing** - Comprehensive test coverage including EJS integration
 
-[See full changelog](./CHANGELOG.md)
+[See full changelog](./docs/CHANGELOG.md)
 
 ## Features
 
@@ -32,7 +32,7 @@ koa-classic-server is a middleware for serving static files from a directory wit
 - 🎨 **Template Engine Support** - Integrate EJS, Pug, Handlebars, etc.
 - 🔒 **Security** - Path traversal protection, XSS prevention
 - ⚙️ **Configurable** - URL prefixes, reserved paths, index files
-- 🧪 **Well-Tested** - 71 tests with security coverage
+- 🧪 **Well-Tested** - 146 tests with comprehensive coverage (security, EJS, performance)
 - 📦 **Dual Module Support** - CommonJS and ES Modules
 
 ## Installation
@@ -110,24 +110,36 @@ app.listen(3000);
 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
     render: async (ctx, next, filePath) => {
-      ctx.body = await ejs.renderFile(filePath, {
+      // Read template file
+      const templateContent = await fs.readFile(filePath, 'utf-8');
+
+      // Render with data
+      const html = ejs.render(templateContent, {
         title: 'My App',
-        user: ctx.state.user
+        user: ctx.state.user || { name: 'Guest' },
+        path: ctx.path,
+        timestamp: new Date().toISOString()
       });
-    },
-    ext: ['ejs', 'html']
+
+      ctx.type = 'text/html';
+      ctx.body = html;
+    }
   }
 }));
 
 app.listen(3000);
 ```
 
+See **[Template Engine Guide](./docs/template-engine/TEMPLATE_ENGINE_GUIDE.md)** for comprehensive template engine documentation with progressive examples.
+
 ## API
 
 ### koaClassicServer(rootDir, options)
@@ -282,11 +294,14 @@ See [CHANGELOG.md](./CHANGELOG.md) for detailed information.
 
 For complete documentation with all features, examples, troubleshooting, and best practices, see:
 
-- **[DOCUMENTATION.md](./DOCUMENTATION.md)** - Complete API reference and usage guide
-- **[INDEX_OPTION_PRIORITY.md](./INDEX_OPTION_PRIORITY.md)** - Detailed priority behavior for `index` option (string, array, RegExp)
-- **[EXAMPLES_INDEX_OPTION.md](./EXAMPLES_INDEX_OPTION.md)** - 10 practical examples of `index` option with RegExp
-- **[PERFORMANCE_ANALYSIS.md](./PERFORMANCE_ANALYSIS.md)** - Performance optimization analysis
-- **[PERFORMANCE_COMPARISON.md](./PERFORMANCE_COMPARISON.md)** - Before/after performance benchmarks
+- **[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
 
 ## Contributing
 
@@ -295,9 +310,8 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 ## Known Limitations
 
 - Reserved URLs only work for first-level directories
-- Single index file name (no fallback array)
 
-See [DEBUG_REPORT.md](./DEBUG_REPORT.md) for technical details.
+See [DEBUG_REPORT.md](./docs/DEBUG_REPORT.md) for technical details.
 
 ## License
 
@@ -313,8 +327,8 @@ See [CHANGELOG.md](./CHANGELOG.md)
 
 ## Links
 
-- [Full Documentation](./DOCUMENTATION.md)
-- [Debug Report](./DEBUG_REPORT.md)
+- [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)

package/__tests__/directory-sorting-links.test.js

@@ -0,0 +1,135 @@
+const Koa = require('koa');
+const request = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const path = require('path');
+
+describe('Directory Sorting Links Bug Tests', () => {
+    let app;
+    let server;
+
+    beforeAll(() => {
+        app = new Koa();
+        const publicDir = path.join(__dirname, 'publicWwwTest');
+
+        app.use(koaClassicServer(publicDir, {
+            method: ['GET'],
+            showDirContents: true
+        }));
+
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+    });
+
+    describe('Bug: Links with query parameters in path', () => {
+        test('File links should not contain sort query parameters in path', async () => {
+            const response = await request(server)
+                .get('/?sort=name&order=asc')
+                .expect(200);
+
+            console.log('Testing for bug...');
+            console.log('Looking for malformed URLs like: ?sort=name&order=asc/');
+
+            // The bug creates malformed URLs like: href="http://localhost:3000/?sort=name&order=asc/test.txt"
+            // Should NOT contain query params before slash
+            expect(response.text).not.toContain('?sort=name&order=asc/');
+
+            // Also check specific pattern
+            const malformedPattern = /href="[^"]*\?sort=[^"]*\//;
+            expect(response.text).not.toMatch(malformedPattern);
+        });
+
+        test('Directory links should not contain query parameters in path', async () => {
+            const response = await request(server)
+                .get('/?sort=size&order=desc')
+                .expect(200);
+
+            // Bug would create: href="http://localhost/?sort=size&order=desc/cartella"
+            expect(response.text).not.toContain('?sort=size&order=desc/');
+
+            // Check for malformed href pattern
+            const malformedPattern = /href="[^"]*\?sort=[^"]*\//;
+            expect(response.text).not.toMatch(malformedPattern);
+        });
+    });
+
+    describe('Functional: Navigation after sorting', () => {
+        test('Should enter folder after sorting by name', async () => {
+            // Load root with sorting
+            const rootResponse = await request(server)
+                .get('/?sort=name&order=asc')
+                .expect(200);
+
+            expect(rootResponse.text).toContain('cartella');
+
+            // Enter cartella folder
+            const folderResponse = await request(server)
+                .get('/cartella')
+                .expect(200);
+
+            expect(folderResponse.text).toContain('sottocartella');
+        });
+
+        test('Should navigate subfolders after sorting by size', async () => {
+            await request(server)
+                .get('/?sort=size&order=desc')
+                .expect(200);
+
+            // Enter cartella
+            const folderResponse = await request(server)
+                .get('/cartella')
+                .expect(200);
+
+            expect(folderResponse.text).toContain('sottocartella');
+
+            // Enter sottocartella
+            const subfolderResponse = await request(server)
+                .get('/cartella/sottocartella')
+                .expect(200);
+
+            expect(subfolderResponse.text).toContain('ciao.html');
+        });
+
+        test('Should access file after sorting by type', async () => {
+            await request(server)
+                .get('/?sort=type&order=asc')
+                .expect(200);
+
+            // Access file
+            const fileResponse = await request(server)
+                .get('/test.txt')
+                .expect(200);
+
+            expect(fileResponse.text).toContain('hello world');
+        });
+    });
+
+    describe('Regression: Sort links still work', () => {
+        test('Sort header links should work', async () => {
+            const response = await request(server)
+                .get('/')
+                .expect(200);
+
+            // Sort links SHOULD have query parameters
+            expect(response.text).toContain('?sort=name');
+            expect(response.text).toContain('?sort=type');
+            expect(response.text).toContain('?sort=size');
+        });
+
+        test('Sort indicators should toggle', async () => {
+            const response1 = await request(server)
+                .get('/?sort=name&order=asc')
+                .expect(200);
+
+            expect(response1.text).toContain('↑');
+
+            const response2 = await request(server)
+                .get('/?sort=name&order=desc')
+                .expect(200);
+
+            expect(response2.text).toContain('↓');
+        });
+    });
+});

package/__tests__/ejs.test.js

@@ -0,0 +1,299 @@
+const Koa = require('koa');
+const koaClassicServer = require('../index.cjs');
+const supertest = require('supertest');
+const path = require('path');
+const fs = require('fs');
+const ejs = require('ejs');
+
+describe('EJS Template Engine Integration Tests', () => {
+    let app;
+    let server;
+    let request;
+
+    beforeAll(() => {
+        app = new Koa();
+
+        const rootDir = path.join(__dirname, 'publicWwwTest');
+
+        // Configure koaClassicServer with EJS template support
+        app.use(
+            koaClassicServer(rootDir, {
+                method: ['GET'],
+                showDirContents: true,
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        // Read the template file
+                        const templateContent = await fs.promises.readFile(filePath, 'utf-8');
+
+                        // Prepare data for different templates
+                        const data = getTemplateData(filePath);
+
+                        // Render with EJS
+                        const html = ejs.render(templateContent, data);
+
+                        ctx.type = 'text/html';
+                        ctx.body = html;
+                    }
+                }
+            })
+        );
+
+        server = app.listen();
+        request = supertest(server);
+    });
+
+    afterAll(() => {
+        if (server) {
+            server.close();
+        }
+    });
+
+    // Helper function to provide data for each template
+    function getTemplateData(filePath) {
+        const basename = path.basename(filePath, '.ejs');
+
+        const dataMap = {
+            'simple': {
+                title: 'Simple EJS Test',
+                heading: 'Hello from EJS',
+                message: 'This is a simple template test',
+                timestamp: '2025-11-18'
+            },
+            'with-loop': {
+                items: [
+                    { name: 'Item 1', value: 100 },
+                    { name: 'Item 2', value: 200 },
+                    { name: 'Item 3', value: 300 }
+                ]
+            },
+            'with-conditional': {
+                isLoggedIn: true,
+                username: 'TestUser',
+                role: 'admin',
+                notifications: 5
+            },
+            'with-escaping': {
+                userInput: '<script>alert("XSS")</script>',
+                htmlContent: '<strong>Bold text</strong>',
+                safeText: 'Plain & safe text',
+                allowedHtml: '<em>Emphasized text</em>'
+            },
+            'complex': {
+                pageTitle: 'E-Commerce Products',
+                user: {
+                    name: 'Mario Rossi'
+                },
+                products: [
+                    {
+                        id: 1,
+                        name: 'Laptop',
+                        description: 'High-performance laptop',
+                        price: 999.99,
+                        discount: 10,
+                        inStock: true
+                    },
+                    {
+                        id: 2,
+                        name: 'Mouse',
+                        description: 'Wireless mouse',
+                        price: 29.99,
+                        discount: 0,
+                        inStock: true
+                    },
+                    {
+                        id: 3,
+                        name: 'Keyboard',
+                        description: 'Mechanical keyboard',
+                        price: 149.99,
+                        discount: 15,
+                        inStock: false
+                    }
+                ]
+            },
+            'testEjs': {
+                // For the existing test file
+            }
+        };
+
+        return dataMap[basename] || {};
+    }
+
+    describe('Simple Template - simple.ejs', () => {
+        test('Should render simple template with variables', async () => {
+            const response = await request.get('/ejs-templates/simple.ejs');
+
+            expect(response.status).toBe(200);
+            expect(response.type).toBe('text/html');
+            expect(response.text).toContain('Simple EJS Test');
+            expect(response.text).toContain('Hello from EJS');
+            expect(response.text).toContain('This is a simple template test');
+            expect(response.text).toContain('2025-11-18');
+        });
+    });
+
+    describe('Loop Template - with-loop.ejs', () => {
+        test('Should render template with forEach loop', async () => {
+            const response = await request.get('/ejs-templates/with-loop.ejs');
+
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Lista di Items');
+            expect(response.text).toContain('Item 1 - 100');
+            expect(response.text).toContain('Item 2 - 200');
+            expect(response.text).toContain('Item 3 - 300');
+            expect(response.text).toContain('Totale items: 3');
+            expect(response.text).toContain('data-index="0"');
+            expect(response.text).toContain('data-index="1"');
+            expect(response.text).toContain('data-index="2"');
+        });
+    });
+
+    describe('Conditional Template - with-conditional.ejs', () => {
+        test('Should render template with if/else conditionals (logged in)', async () => {
+            const response = await request.get('/ejs-templates/with-conditional.ejs');
+
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Benvenuto, TestUser!');
+            expect(response.text).toContain('Ruolo: admin');
+            expect(response.text).toContain('Hai 5 nuove notifiche');
+            // Should NOT contain guest panel
+            expect(response.text).not.toContain('Benvenuto, ospite!');
+        });
+    });
+
+    describe('Escaping Template - with-escaping.ejs', () => {
+        test('Should properly escape HTML in <%= %> tags', async () => {
+            const response = await request.get('/ejs-templates/with-escaping.ejs');
+
+            expect(response.status).toBe(200);
+
+            // HTML should be escaped (safe)
+            // Note: EJS uses &#34; instead of &quot; for quotes
+            expect(response.text).toContain('&lt;script&gt;alert(&#34;XSS&#34;)&lt;/script&gt;');
+
+            // HTML should NOT be escaped (unsafe - unescaped output)
+            expect(response.text).toContain('<strong>Bold text</strong>');
+
+            // Safe text with & should be escaped
+            expect(response.text).toContain('Plain &amp; safe text');
+
+            // Allowed HTML should be rendered
+            expect(response.text).toContain('<em>Emphasized text</em>');
+        });
+
+        test('Should protect against XSS attacks', async () => {
+            const response = await request.get('/ejs-templates/with-escaping.ejs');
+
+            // The escaped section should not contain executable script tags
+            const escapedSection = response.text.match(/<div class="escaped">[\s\S]*?<\/div>/)[0];
+            expect(escapedSection).not.toContain('<script>');
+            expect(escapedSection).toContain('&lt;script&gt;');
+        });
+    });
+
+    describe('Complex Template - complex.ejs', () => {
+        test('Should render complex template with all features', async () => {
+            const response = await request.get('/ejs-templates/complex.ejs');
+
+            expect(response.status).toBe(200);
+
+            // Page title
+            expect(response.text).toContain('E-Commerce Products');
+
+            // User greeting
+            expect(response.text).toContain('Ciao, Mario Rossi!');
+
+            // Products list
+            expect(response.text).toContain('Laptop');
+            expect(response.text).toContain('High-performance laptop');
+            expect(response.text).toContain('€999.99');
+
+            // Discount calculation
+            expect(response.text).toContain('Sconto: 10%');
+            expect(response.text).toContain('€899.99'); // 999.99 - 10%
+
+            // Mouse without discount
+            expect(response.text).toContain('Mouse');
+            expect(response.text).toContain('€29.99');
+
+            // Keyboard out of stock
+            expect(response.text).toContain('Keyboard');
+            expect(response.text).toContain('Non disponibile');
+
+            // Total count
+            expect(response.text).toContain('Totale prodotti: 3');
+        });
+
+        test('Should have correct product data attributes', async () => {
+            const response = await request.get('/ejs-templates/complex.ejs');
+
+            expect(response.text).toContain('data-id="1"');
+            expect(response.text).toContain('data-id="2"');
+            expect(response.text).toContain('data-id="3"');
+        });
+
+        test('Should show "Add to cart" button only for in-stock items', async () => {
+            const response = await request.get('/ejs-templates/complex.ejs');
+
+            // Count "Aggiungi al carrello" buttons - should be 2 (Laptop and Mouse)
+            const buttonMatches = response.text.match(/Aggiungi al carrello/g);
+            expect(buttonMatches).toHaveLength(2);
+
+            // Count "Non disponibile" - should be 1 (Keyboard)
+            const outOfStockMatches = response.text.match(/Non disponibile/g);
+            expect(outOfStockMatches).toHaveLength(1);
+        });
+    });
+
+    describe('Index Template - index.ejs', () => {
+        test('Should render index page with links', async () => {
+            const response = await request.get('/ejs-templates/index.ejs');
+
+            expect(response.status).toBe(200);
+            expect(response.text).toContain('Test Templates EJS');
+            expect(response.text).toContain('simple.ejs');
+            expect(response.text).toContain('with-loop.ejs');
+            expect(response.text).toContain('with-conditional.ejs');
+            expect(response.text).toContain('with-escaping.ejs');
+            expect(response.text).toContain('complex.ejs');
+        });
+    });
+
+    describe('Existing EJS file - testEjs.ejs', () => {
+        test('Should render existing testEjs.ejs file', async () => {
+            const response = await request.get('/cartella/sottocartella/provaEjs/testEjs.ejs');
+
+            expect(response.status).toBe(200);
+            expect(response.type).toBe('text/html');
+            expect(response.text).toContain('<h1>hello world</h1>');
+        });
+    });
+
+    describe('Error Handling', () => {
+        test('Should return 404 for non-existent .ejs file', async () => {
+            const response = await request.get('/ejs-templates/non-existent.ejs');
+
+            expect(response.status).toBe(404);
+        });
+    });
+
+    describe('Performance', () => {
+        test('Should render complex template in reasonable time', async () => {
+            const start = Date.now();
+            const response = await request.get('/ejs-templates/complex.ejs');
+            const duration = Date.now() - start;
+
+            expect(response.status).toBe(200);
+            expect(duration).toBeLessThan(100); // Should render in less than 100ms
+        });
+
+        test('Should render simple template very quickly', async () => {
+            const start = Date.now();
+            const response = await request.get('/ejs-templates/simple.ejs');
+            const duration = Date.now() - start;
+
+            expect(response.status).toBe(200);
+            expect(duration).toBeLessThan(50); // Should render in less than 50ms
+        });
+    });
+});

package/__tests__/performance.test.js

@@ -17,15 +17,84 @@ const koaClassicServer = require('../index.cjs');
 const path = require('path');
 const fs = require('fs');
 
-const BENCHMARK_DIR = path.join(__dirname, '../benchmark-data');
+const BENCHMARK_DIR = path.join(__dirname, 'benchmark-data');
 
-// Check if benchmark data exists
-if (!fs.existsSync(BENCHMARK_DIR)) {
-    console.error('\n❌ Benchmark data not found!');
-    console.error('Please run: node scripts/setup-benchmark.js\n');
-    process.exit(1);
+// Auto-setup benchmark data if not exists
+function setupBenchmarkData() {
+    if (fs.existsSync(BENCHMARK_DIR)) {
+        return; // Data already exists
+    }
+
+    console.log('\n🔧 Setting up benchmark data automatically...\n');
+
+    // Create benchmark directory
+    fs.mkdirSync(BENCHMARK_DIR, { recursive: true });
+
+    // Create small files (1KB each)
+    console.log('  Creating 100 small files (1KB each)...');
+    const smallDir = path.join(BENCHMARK_DIR, 'small-files');
+    fs.mkdirSync(smallDir);
+    for (let i = 1; i <= 100; i++) {
+        const content = 'X'.repeat(1024);
+        fs.writeFileSync(path.join(smallDir, `file-${i}.txt`), content);
+    }
+
+    // Create medium files (100KB each)
+    console.log('  Creating 50 medium files (100KB each)...');
+    const mediumDir = path.join(BENCHMARK_DIR, 'medium-files');
+    fs.mkdirSync(mediumDir);
+    for (let i = 1; i <= 50; i++) {
+        const content = 'X'.repeat(100 * 1024);
+        fs.writeFileSync(path.join(mediumDir, `file-${i}.txt`), content);
+    }
+
+    // Create large files (1MB each)
+    console.log('  Creating 10 large files (1MB each)...');
+    const largeDir = path.join(BENCHMARK_DIR, 'large-files');
+    fs.mkdirSync(largeDir);
+    for (let i = 1; i <= 10; i++) {
+        const content = 'X'.repeat(1024 * 1024);
+        fs.writeFileSync(path.join(largeDir, `file-${i}.txt`), content);
+    }
+
+    // Create directory with 1000 files
+    console.log('  Creating directory with 1000 files...');
+    const largeDirListing = path.join(BENCHMARK_DIR, 'large-directory');
+    fs.mkdirSync(largeDirListing);
+    for (let i = 1; i <= 1000; i++) {
+        const content = `File number ${i}\n`;
+        fs.writeFileSync(path.join(largeDirListing, `item-${String(i).padStart(4, '0')}.txt`), content);
+    }
+
+    // Create directory with 10,000 files
+    console.log('  Creating directory with 10,000 files (this may take a moment)...');
+    const veryLargeDirListing = path.join(BENCHMARK_DIR, 'very-large-directory');
+    fs.mkdirSync(veryLargeDirListing);
+    for (let i = 1; i <= 10000; i++) {
+        const content = `File number ${i}\n`;
+        fs.writeFileSync(path.join(veryLargeDirListing, `item-${String(i).padStart(5, '0')}.txt`), content);
+    }
+
+    // Create HTML file for caching test
+    const htmlContent = `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Benchmark Test</title>
+</head>
+<body>
+    <h1>Benchmark Test Page</h1>
+    <p>${'Lorem ipsum dolor sit amet. '.repeat(100)}</p>
+</body>
+</html>`;
+    fs.writeFileSync(path.join(BENCHMARK_DIR, 'test.html'), htmlContent);
+
+    console.log('\n✅ Benchmark data setup complete!\n');
 }
 
+// Setup benchmark data automatically if needed
+setupBenchmarkData();
+
 // Helper to measure execution time
 function measureTime(fn) {
     const start = process.hrtime.bigint();