npm - koa-classic-server - Versions diffs - 2.3.0 → 2.5.0 - Mend

koa-classic-server 2.3.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md +92 -7
package/__tests__/hideExtension.test.js +550 -0
package/__tests__/publicWwwTest/hideext-test/about/index.html +1 -0
package/__tests__/publicWwwTest/hideext-test/about.EJS +1 -0
package/__tests__/publicWwwTest/hideext-test/about.ejs +2 -0
package/__tests__/publicWwwTest/hideext-test/blog/articolo.ejs +2 -0
package/__tests__/publicWwwTest/hideext-test/conflict-test/pagina +1 -0
package/__tests__/publicWwwTest/hideext-test/conflict-test/pagina.ejs +1 -0
package/__tests__/publicWwwTest/hideext-test/file.ejs.bak +1 -0
package/__tests__/publicWwwTest/hideext-test/index.ejs +2 -0
package/__tests__/publicWwwTest/hideext-test/photo.txt +1 -0
package/__tests__/publicWwwTest/hideext-test/sezione/index.ejs +1 -0
package/__tests__/publicWwwTest/hideext-test/style.css +1 -0
package/__tests__/symlink.test.js +438 -0
package/docs/CHANGELOG.md +87 -0
package/docs/DOCUMENTATION.md +53 -5
package/index.cjs +186 -23
package/package.json +1 -1
package/.vscode/OLD_launch.json +0 -26
package/.vscode/launch.json +0 -41
package/.vscode/settings.json +0 -0

package/__tests__/symlink.test.js ADDED Viewed

@@ -0,0 +1,438 @@
+/**
+ * Symlink support tests for koa-classic-server
+ *
+ * Context: On NixOS with buildFHSEnv (chroot-like environment used for Playwright tests),
+ * files in the www/ directory appear as symlinks to the Nix store instead of regular files.
+ * This caused two failures:
+ *   - GET / returned a directory listing ("Index of /") instead of rendering index.ejs
+ *   - GET /index.ejs returned 404 instead of 200
+ *
+ * Root cause: fs.readdir({ withFileTypes: true }) classifies symlinks as
+ * isSymbolicLink()=true, isFile()=false. The findIndexFile() function filtered
+ * with dirent.isFile(), excluding all symlinks from index file discovery.
+ *
+ * The fix introduces isFileOrSymlinkToFile() / isDirOrSymlinkToDir() helpers
+ * that follow symlinks via fs.promises.stat() only when dirent.isSymbolicLink()
+ * is true, adding zero overhead for regular files.
+ *
+ * These tests also cover: Docker bind mounts, npm link, Capistrano-style deploys,
+ * and any other scenario where files are served through symbolic links.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const Koa = require('koa');
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+// Detect if the OS supports symlinks (Windows without dev mode may not)
+let symlinkSupported = true;
+try {
+    const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'symlink-check-'));
+    const testFile = path.join(testDir, 'target');
+    const testLink = path.join(testDir, 'link');
+    fs.writeFileSync(testFile, 'test');
+    fs.symlinkSync(testFile, testLink);
+    fs.rmSync(testDir, { recursive: true, force: true });
+} catch {
+    symlinkSupported = false;
+}
+const describeIfSymlinks = symlinkSupported ? describe : describe.skip;
+describeIfSymlinks('koa-classic-server - symlink support', () => {
+    let tmpDir;
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-symlink-test-'));
+        // --- Regular files ---
+        fs.writeFileSync(
+            path.join(tmpDir, 'index.html'),
+            '<html><head><title>Regular Index</title></head><body>Hello</body></html>'
+        );
+        fs.writeFileSync(
+            path.join(tmpDir, 'style.css'),
+            'body { color: red; }'
+        );
+        // --- Real file that will be the symlink target for index.ejs ---
+        fs.writeFileSync(
+            path.join(tmpDir, 'real-index.ejs'),
+            '<html><head><title>EJS via Symlink</title></head><body><h1>Works</h1></body></html>'
+        );
+        // --- Symlink to file (the core bug scenario) ---
+        fs.symlinkSync(
+            path.join(tmpDir, 'real-index.ejs'),
+            path.join(tmpDir, 'index.ejs')
+        );
+        // --- Symlink to regular file (non-index) ---
+        fs.symlinkSync(
+            path.join(tmpDir, 'style.css'),
+            path.join(tmpDir, 'linked-style.css')
+        );
+        // --- Real subdirectory with a file ---
+        const realSubdir = path.join(tmpDir, 'real-subdir');
+        fs.mkdirSync(realSubdir);
+        fs.writeFileSync(
+            path.join(realSubdir, 'file.txt'),
+            'content inside real-subdir'
+        );
+        // --- Symlink to directory ---
+        fs.symlinkSync(
+            realSubdir,
+            path.join(tmpDir, 'linked-subdir')
+        );
+        // --- Broken symlink (target does not exist) ---
+        fs.symlinkSync(
+            path.join(tmpDir, 'non-existent-file.html'),
+            path.join(tmpDir, 'broken-link.html')
+        );
+        // --- Circular symlinks ---
+        try {
+            fs.symlinkSync(
+                path.join(tmpDir, 'circular-b'),
+                path.join(tmpDir, 'circular-a')
+            );
+            fs.symlinkSync(
+                path.join(tmpDir, 'circular-a'),
+                path.join(tmpDir, 'circular-b')
+            );
+        } catch {
+            // Some systems may not support circular symlinks creation
+        }
+    });
+    afterAll(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    // =========================================================================
+    // 1. REGRESSION - Regular file as index
+    // =========================================================================
+    describe('regular file as index (regression)', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: ['index.html'],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET / serves regular index.html, not directory listing', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('Regular Index');
+            expect(res.text).not.toContain('Index of');
+        });
+    });
+    // =========================================================================
+    // 2. BUG FIX - Symlink to file as index
+    // =========================================================================
+    describe('symlink to file as index (bug fix)', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: ['index.ejs'],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET / serves symlinked index.ejs, not directory listing', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('EJS via Symlink');
+            expect(res.text).not.toContain('Index of');
+        });
+    });
+    // =========================================================================
+    // 3. BUG FIX - Direct GET to symlinked file returns 200
+    // =========================================================================
+    describe('direct GET to symlinked file (bug fix)', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: [],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET /index.ejs via symlink returns 200', async () => {
+            const res = await request.get('/index.ejs');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('EJS via Symlink');
+        });
+        test('GET /linked-style.css via symlink returns 200 with correct mime', async () => {
+            const res = await request.get('/linked-style.css');
+            expect(res.status).toBe(200);
+            expect(res.headers['content-type']).toMatch(/css/);
+            expect(res.text).toContain('body { color: red; }');
+        });
+    });
+    // =========================================================================
+    // 4. BUG FIX - Symlink to file with template engine
+    // =========================================================================
+    describe('EJS template via symlink (bug fix)', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: ['index.ejs'],
+                showDirContents: true,
+                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('GET / renders EJS template through symlink', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.headers['content-type']).toMatch(/html/);
+            expect(res.text).toContain('EJS via Symlink');
+        });
+    });
+    // =========================================================================
+    // 5. Directory as symlink
+    // =========================================================================
+    describe('symlink to directory', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: [],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET /linked-subdir/ lists directory contents', async () => {
+            const res = await request.get('/linked-subdir/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('file.txt');
+        });
+        test('GET /linked-subdir/file.txt serves file inside symlinked dir', async () => {
+            const res = await request.get('/linked-subdir/file.txt');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('content inside real-subdir');
+        });
+    });
+    // =========================================================================
+    // 6. Broken symlink
+    // =========================================================================
+    describe('broken symlink', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: [],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET /broken-link.html returns 404, not crash', async () => {
+            const res = await request.get('/broken-link.html');
+            expect(res.status).toBe(404);
+        });
+    });
+    // =========================================================================
+    // 7. Circular symlink
+    // =========================================================================
+    describe('circular symlink', () => {
+        let server, request;
+        let circularExists = false;
+        beforeAll(() => {
+            circularExists = fs.existsSync(path.join(tmpDir, 'circular-a'));
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: [],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET /circular-a does not cause infinite loop', async () => {
+            if (!circularExists) {
+                // Skip if circular symlinks could not be created on this OS
+                return;
+            }
+            const res = await request.get('/circular-a');
+            // Should return an error status, not hang
+            expect([404, 500]).toContain(res.status);
+        });
+    });
+    // =========================================================================
+    // 8. REGRESSION - Regular non-index file unchanged
+    // =========================================================================
+    describe('regular non-index file (regression)', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: ['index.html'],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET /style.css serves regular file correctly', async () => {
+            const res = await request.get('/style.css');
+            expect(res.status).toBe(200);
+            expect(res.headers['content-type']).toMatch(/css/);
+            expect(res.text).toContain('body { color: red; }');
+        });
+    });
+    // =========================================================================
+    // 9. Directory listing shows symlink indicators
+    // =========================================================================
+    describe('directory listing symlink indicators', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: [],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('symlink to file shows ( Symlink ) indicator', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            // index.ejs is a symlink to a file
+            expect(res.text).toContain('index.ejs');
+            expect(res.text).toMatch(/index\.ejs<\/a>\s*\( Symlink \)/);
+        });
+        test('symlink to directory shows ( Symlink ) indicator', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('linked-subdir');
+            expect(res.text).toMatch(/linked-subdir<\/a>\s*\( Symlink \)/);
+        });
+        test('broken symlink shows ( Broken Symlink ) indicator without link', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('broken-link.html');
+            expect(res.text).toContain('( Broken Symlink )');
+            // Broken symlink name should NOT be wrapped in <a> tag
+            expect(res.text).not.toMatch(/<a[^>]*>broken-link\.html<\/a>/);
+        });
+        test('regular file does NOT show symlink indicator', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('style.css');
+            // style.css (not linked-style.css) should not have any symlink indicator
+            expect(res.text).not.toMatch(/>style\.css<\/a>\s*\( Symlink \)/);
+            expect(res.text).not.toMatch(/>style\.css<\/a>\s*\( Broken Symlink \)/);
+        });
+        test('symlink to file shows target mime type, not "unknown"', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            // linked-style.css is a symlink to style.css - should show text/css mime
+            expect(res.text).toMatch(/linked-style\.css[\s\S]*?text\/css/);
+        });
+        test('symlink to directory shows DIR type', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            // linked-subdir is a symlink to a directory - should show DIR
+            expect(res.text).toMatch(/linked-subdir[\s\S]*?DIR/);
+        });
+    });
+    // =========================================================================
+    // 10. Symlink as index with RegExp pattern
+    // =========================================================================
+    describe('symlink as index with RegExp pattern', () => {
+        let server, request;
+        beforeAll(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(tmpDir, {
+                index: [/index\.[eE][jJ][sS]/],
+                showDirContents: true
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+        afterAll(() => { server?.close(); });
+        test('GET / finds symlinked index.ejs via RegExp pattern', async () => {
+            const res = await request.get('/');
+            expect(res.status).toBe(200);
+            expect(res.text).toContain('EJS via Symlink');
+            expect(res.text).not.toContain('Index of');
+        });
+    });
+});

package/docs/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,93 @@ 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.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
+#### Fixed Symlink Support in Index File Discovery and Directory Listing
+- **Issue**: On systems where served files are symbolic links (NixOS buildFHSEnv, Docker bind mounts, `npm link`, Capistrano-style deploys), `findIndexFile()` failed because `dirent.isFile()` returns `false` for symlinks. This caused `GET /` to show directory listing instead of rendering the index file, and `GET /index.ejs` to return 404.
+- **Impact**: HIGH - Server unusable on NixOS/buildFHSEnv and similar environments
+- **Fix**: Added `isFileOrSymlinkToFile()` / `isDirOrSymlinkToDir()` helpers that follow symlinks via `fs.promises.stat()` only when `dirent.isSymbolicLink()` is true, adding zero overhead for regular files.
+- **Code**: `index.cjs` - new helpers + `findIndexFile()` + `show_dir()`
+### ✨ Improvements
+#### Directory Listing Symlink Indicators
+- Symlinks to files/directories show `( Symlink )` label next to the name
+- Broken/circular symlinks show `( Broken Symlink )` label (name visible but not clickable)
+- Symlinks resolved to effective type for MIME and size display (e.g. symlink to dir shows `DIR`)
+- Sorting uses effective type (symlink-to-dir sorts with directories)
+### 🧪 Testing
+- Added `__tests__/symlink.test.js` with 17 tests covering:
+  - Regular file as index (regression)
+  - Symlink to file as index (string and RegExp patterns)
+  - Direct GET to symlinked file
+  - EJS template via symlink
+  - Symlink to directory (listing and file access)
+  - Broken and circular symlinks
+  - Directory listing indicators (`( Symlink )`, `( Broken Symlink )`)
+  - Regular file regression (no false symlink indicator)
+- All 187 existing tests still pass (zero regressions)
+### 📦 Package Changes
+- **Semver**: Minor version bump (new feature, backward compatible)
+---
 ## [2.3.0] - 2026-01-03
 ### 🔄 Renamed Options (with Backward Compatibility)

package/docs/DOCUMENTATION.md CHANGED Viewed

@@ -35,7 +35,7 @@
 - Navigazione parent directory con link ".. Parent Directory"
 - Indicazione chiara del tipo di risorsa (DIR, MIME type)
 - Gestione e visualizzazione cartelle riservate
-- Supporto link simbolici
+- Supporto completo link simbolici (symlink a file, directory, broken e circolari)
 #### 3. Supporto Template Engine
 - Integrazione flessibile con motori di template (es. EJS, Pug, Handlebars)
@@ -777,6 +777,49 @@ http://localhost:3000/file.txt/ → http://localhost:3000/file.txt
 Questo assicura comportamento coerente indipendentemente dal trailing slash.
+### Gestione dei Link Simbolici (Symlink)
+Il middleware supporta completamente i link simbolici (symlink). Questo è fondamentale in ambienti dove i file serviti sono symlink anziché file regolari, come ad esempio:
+- **NixOS con buildFHSEnv** (chroot-like): i file nella directory www/ appaiono come symlink al Nix store
+- **Docker bind mounts**: i file montati possono risultare come symlink
+- **npm link**: i pacchetti linkati sono symlink
+- **Deploy Capistrano-style**: la directory `current` è un symlink alla release attiva
+#### Comportamento
+Il middleware segue i symlink in modo trasparente tramite `fs.promises.stat()` (che risolve il symlink al target reale), ma solo quando `dirent.isSymbolicLink()` è `true`. Per i file regolari non viene effettuata alcuna chiamata aggiuntiva (zero overhead).
+#### Risoluzione Index File
+Quando il middleware cerca un file index in una directory (opzione `index`), i symlink che puntano a file regolari vengono inclusi nella ricerca, sia con pattern stringa che RegExp:
+```
+Directory:
+  index.ejs → /nix/store/.../index.ejs  (symlink a file)
+  style.css                              (file regolare)
+Config: index: ['index.ejs']
+Risultato: Serve index.ejs attraverso il symlink ✓
+```
+#### Directory Listing
+Nel directory listing, i symlink sono identificati visivamente:
+| Caso | Indicatore | Cliccabile | Tipo mostrato |
+|------|-----------|------------|---------------|
+| Symlink a file | `( Symlink )` | Sì | MIME type del target |
+| Symlink a directory | `( Symlink )` | Sì | `DIR` |
+| Symlink rotto/circolare | `( Broken Symlink )` | No | `unknown` |
+| File/directory regolare | nessuno | Sì | tipo reale |
+#### Casi Limite
+- **Broken symlink** (target inesistente): il GET diretto restituisce 404; nel listing il nome appare senza link
+- **Symlink circolare** (A → B → A): trattato come broken symlink, nessun loop infinito
+- **Symlink a directory**: navigabile come una directory regolare, i file al suo interno sono accessibili
 ### MIME Types
 MIME types riconosciuti automaticamente tramite estensione file:
@@ -1494,7 +1537,7 @@ app.use(koaClassicServer(__dirname + '/public', {
 ## Informazioni Aggiuntive
 ### Versione
-**1.1.0**
+**2.4.0**
 ### Autore
 **Italo Paesano**
@@ -1558,8 +1601,13 @@ Contributi benvenuti! Per favore:
 ### Changelog
+#### v1.2.0
+- Fix: supporto completo link simbolici in `findIndexFile()` e directory listing
+- Nuovi helper `isFileOrSymlinkToFile()` / `isDirOrSymlinkToDir()` (zero overhead per file regolari)
+- Directory listing: indicatori `( Symlink )` e `( Broken Symlink )`, tipo effettivo (MIME/DIR) per symlink
+- 17 nuovi test per tutti gli scenari symlink (NixOS, Docker, npm link, broken, circular)
 #### v1.1.0
-- Versione attuale
 - Supporto conditional exports
 - Test suite completa
@@ -1580,6 +1628,6 @@ Repository con esempi completi disponibile nella cartella `customTest/` del prog
 ---
-**Documentazione generata per koa-classic-server v1.1.0**
+**Documentazione generata per koa-classic-server v2.4.0**
-*Ultimo aggiornamento: 2025-11-17*
+*Ultimo aggiornamento: 2026-02-28*