koa-classic-server 2.3.0 → 2.4.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-197%20passing-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-214%20passing-brightgreen.svg)]()
 
 ---
 
@@ -26,7 +26,8 @@ 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
-✅ **Comprehensive Testing** - 197 tests passing with extensive coverage
+✅ **Symlink Support** - Full symbolic link support (NixOS, Docker, npm link, Capistrano)
+✅ **Comprehensive Testing** - 214 tests passing with extensive coverage
 ✅ **Complete Documentation** - Detailed guides and examples
 
 [See full changelog →](./docs/CHANGELOG.md)
@@ -48,7 +49,8 @@ The 2.X series brings major performance improvements, enhanced security, and pow
 - 🔒 **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
+- 🔗 **Symlink Support** - Transparent symlink resolution with directory listing indicators
+- 🧪 **Well-Tested** - 214 passing tests with comprehensive coverage
 - 📦 **Dual Module Support** - CommonJS and ES Modules
 
 ---
@@ -462,6 +464,33 @@ Human-readable format:
 - **Click file name** - Download/view file
 - **Parent Directory** - Go up one level
 
+### Symlink Support
+
+The middleware fully supports symbolic links, which is essential for environments where served files are symlinks rather than regular files:
+
+- **NixOS buildFHSEnv** - Files in www/ appear as symlinks to the Nix store
+- **Docker bind mounts** - Mounted files may appear as symlinks
+- **npm link** - Linked packages are symlinks
+- **Capistrano-style deploys** - The `current` directory is a symlink to the active release
+
+**How it works:**
+
+Symlinks are followed transparently via `fs.promises.stat()`, but only when `dirent.isSymbolicLink()` is true. Regular files incur zero additional overhead.
+
+**Directory listing indicators:**
+
+| Entry type | Indicator | Clickable | Type shown |
+|------------|-----------|-----------|------------|
+| Symlink to file | `( Symlink )` | Yes | Target MIME type |
+| Symlink to directory | `( Symlink )` | Yes | `DIR` |
+| Broken/circular symlink | `( Broken Symlink )` | No | `unknown` |
+| Regular file/directory | none | Yes | Real type |
+
+**Edge cases handled:**
+- Broken symlinks (missing target) return 404 on direct access
+- Circular symlinks (A → B → A) are treated as broken, no infinite loops
+- Symlinks to directories are fully navigable
+
 ---
 
 ## Security
@@ -556,10 +585,11 @@ npm run test:performance
 ```
 
 **Test Coverage:**
-- ✅ 197 tests passing
+- ✅ 214 tests passing
 - ✅ Security tests (path traversal, XSS, race conditions)
 - ✅ EJS template integration tests
 - ✅ Index option tests (strings, arrays, RegExp)
+- ✅ Symlink tests (file, directory, broken, circular, indicators)
 - ✅ Performance benchmarks
 - ✅ Directory sorting tests
 

package/__tests__/symlink.test.js

@@ -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

@@ -5,6 +5,41 @@ 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.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

@@ -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*

package/index.cjs

@@ -138,6 +138,40 @@ module.exports = function koaClassicServer(
     options.browserCacheEnabled = typeof options.browserCacheEnabled === 'boolean' ? options.browserCacheEnabled : false;
     options.useOriginalUrl = typeof options.useOriginalUrl === 'boolean' ? options.useOriginalUrl : true;
 
+    /**
+     * 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.
+     */
+    async function isFileOrSymlinkToFile(dirent, dirPath) {
+        if (dirent.isFile()) return true;
+        if (dirent.isSymbolicLink()) {
+            try {
+                const realStat = await fs.promises.stat(path.join(dirPath, dirent.name));
+                return realStat.isFile();
+            } catch {
+                return false; // Broken or circular symlink
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Returns true if dirent is a directory or a symlink pointing to a directory.
+     * Uses fs.promises.stat (which follows symlinks) only when dirent.isSymbolicLink() is true.
+     */
+    async function isDirOrSymlinkToDir(dirent, dirPath) {
+        if (dirent.isDirectory()) return true;
+        if (dirent.isSymbolicLink()) {
+            try {
+                const realStat = await fs.promises.stat(path.join(dirPath, dirent.name));
+                return realStat.isDirectory();
+            } catch {
+                return false; // Broken or circular symlink
+            }
+        }
+        return false;
+    }
+
     return async (ctx, next) => {
         // Check if method is allowed
         if (!options.method.includes(ctx.method)) {
@@ -259,10 +293,16 @@ module.exports = function koaClassicServer(
                 // Read directory contents
                 const files = await fs.promises.readdir(dirPath, { withFileTypes: true });
 
-                // Filter only files (not directories)
-                const fileNames = files
-                    .filter(dirent => dirent.isFile())
-                    .map(dirent => dirent.name);
+                // Filter files, following symlinks to determine effective type
+                const fileCheckResults = await Promise.all(
+                    files.map(async dirent => ({
+                        name: dirent.name,
+                        isFile: await isFileOrSymlinkToFile(dirent, dirPath)
+                    }))
+                );
+                const fileNames = fileCheckResults
+                    .filter(entry => entry.isFile)
+                    .map(entry => entry.name);
 
                 // Search with priority order (first pattern wins)
                 for (const pattern of indexPatterns) {
@@ -542,27 +582,45 @@ module.exports = function koaClassicServer(
                         itemUri = `${baseUrl}/${encodeURIComponent(s_name)}`;
                     }
 
+                    // Resolve symlinks to their effective type
+                    let effectiveType = type;
+                    let isBrokenSymlink = false;
+                    if (type === 3) {
+                        try {
+                            const realStat = await fs.promises.stat(itemPath);
+                            if (realStat.isFile()) effectiveType = 1;
+                            else if (realStat.isDirectory()) effectiveType = 2;
+                        } catch {
+                            isBrokenSymlink = true; // Broken or circular symlink
+                        }
+                    }
+
                     // Get file size
                     let sizeStr = '-';
                     let sizeBytes = 0;
-                    try {
-                        const itemStat = await fs.promises.stat(itemPath);
-                        if (type === 1) {
-                            sizeBytes = itemStat.size;
-                            sizeStr = formatSize(sizeBytes);
-                        } else {
+                    if (!isBrokenSymlink) {
+                        try {
+                            const itemStat = await fs.promises.stat(itemPath);
+                            if (effectiveType === 1) {
+                                sizeBytes = itemStat.size;
+                                sizeStr = formatSize(sizeBytes);
+                            } else {
+                                sizeStr = '-';
+                            }
+                        } catch (error) {
                             sizeStr = '-';
                         }
-                    } catch (error) {
-                        sizeStr = '-';
                     }
 
-                    const mimeType = type === 2 ? "DIR" : (mime.lookup(itemPath) || 'unknown');
-                    const isReserved = pageHrefOutPrefix.pathname === '/' && options.urlsReserved.includes('/' + s_name) && (type === 2 || type === 3);
+                    const mimeType = effectiveType === 2 ? "DIR" : (mime.lookup(itemPath) || 'unknown');
+                    const isReserved = pageHrefOutPrefix.pathname === '/' && options.urlsReserved.includes('/' + s_name) && (effectiveType === 2 || type === 3);
 
                     items.push({
                         name: s_name,
                         type: type,
+                        effectiveType: effectiveType,
+                        isSymlink: type === 3,
+                        isBrokenSymlink: isBrokenSymlink,
                         mimeType: mimeType,
                         sizeStr: sizeStr,
                         sizeBytes: sizeBytes,
@@ -578,19 +636,19 @@ module.exports = function koaClassicServer(
                     if (sortBy === 'name') {
                         comparison = a.name.localeCompare(b.name);
                     } else if (sortBy === 'type') {
-                        // Sort directories first, then by mime type
-                        if (a.type === 2 && b.type !== 2) {
+                        // Sort directories first, then by mime type (using effectiveType for symlinks)
+                        if (a.effectiveType === 2 && b.effectiveType !== 2) {
                             comparison = -1;
-                        } else if (a.type !== 2 && b.type === 2) {
+                        } else if (a.effectiveType !== 2 && b.effectiveType === 2) {
                             comparison = 1;
                         } else {
                             comparison = a.mimeType.localeCompare(b.mimeType);
                         }
                     } else if (sortBy === 'size') {
-                        // Directories always at top when sorting by size
-                        if (a.type === 2 && b.type !== 2) {
+                        // Directories always at top when sorting by size (using effectiveType for symlinks)
+                        if (a.effectiveType === 2 && b.effectiveType !== 2) {
                             comparison = -1;
-                        } else if (a.type !== 2 && b.type === 2) {
+                        } else if (a.effectiveType !== 2 && b.effectiveType === 2) {
                             comparison = 1;
                         } else {
                             comparison = a.sizeBytes - b.sizeBytes;
@@ -604,16 +662,26 @@ module.exports = function koaClassicServer(
                 // Generate HTML for sorted items
                 for (const item of items) {
                     let rowStart = '';
-                    if (item.type === 1) {
+                    if (item.effectiveType === 1) {
                         rowStart = `<tr><td> FILE `;
                     } else {
                         rowStart = `<tr><td>`;
                     }
 
+                    // Symlink indicator label
+                    const symlinkLabel = item.isBrokenSymlink
+                        ? ' ( Broken Symlink )'
+                        : item.isSymlink
+                            ? ' ( Symlink )'
+                            : '';
+
                     if (item.isReserved) {
-                        parts.push(`${rowStart} ${escapeHtml(item.name)}</td> <td> DIR BUT RESERVED</td><td>${item.sizeStr}</td></tr>`);
+                        parts.push(`${rowStart} ${escapeHtml(item.name)}${symlinkLabel}</td> <td> DIR BUT RESERVED</td><td>${item.sizeStr}</td></tr>`);
+                    } else if (item.isBrokenSymlink) {
+                        // Broken symlink: name visible but not clickable
+                        parts.push(`${rowStart} ${escapeHtml(item.name)}${symlinkLabel}</td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
                     } else {
-                        parts.push(`${rowStart} <a href="${escapeHtml(item.itemUri)}">${escapeHtml(item.name)}</a> </td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
+                        parts.push(`${rowStart} <a href="${escapeHtml(item.itemUri)}">${escapeHtml(item.name)}</a>${symlinkLabel} </td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
                     }
                 }
             }

package/package.json

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