koa-classic-server 2.1.4 → 2.4.0

package/docs/CHANGELOG.md

@@ -5,6 +5,166 @@ 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)
+
+#### Renamed Caching Options for Clarity
+- **Old Names** (DEPRECATED): `enableCaching`, `cacheMaxAge`
+- **New Names**: `browserCacheEnabled`, `browserCacheMaxAge`
+- **Reason**: Improved clarity - these options specifically control browser-side HTTP caching
+- **Backward Compatible**: Old names still work but display deprecation warnings
+
+#### Deprecation Warnings
+When using deprecated option names, a warning is displayed on the terminal:
+```
+[koa-classic-server] DEPRECATION WARNING: The "enableCaching" option is deprecated and will be removed in future versions.
+  Current usage: enableCaching: true
+  Recommended:   browserCacheEnabled: true
+  Please update your configuration to use the new option name.
+```
+
+### 📝 Documentation Updates
+
+- Updated README.md with new option names
+- Updated JSDoc comments in index.cjs
+- Added deprecation notes in Options table
+- All examples updated to use new names
+
+### 🔧 Changes
+
+- **index.cjs**: Lines 109-135 - Added backward compatibility logic with deprecation warnings
+- **index.cjs**: Lines 47-58 - Updated JSDoc comments
+- **index.cjs**: Lines 350, 361 - Updated code to use new option names
+- **README.md**: Updated all references to use new names, added deprecation notes
+- **package.json**: Version bumped from `2.2.0` to `2.3.0`
+
+### ⚠️ Migration Guide
+
+**No immediate changes required** - old option names still work.
+
+**Recommended migration:**
+
+```javascript
+// Old (still works, but deprecated)
+app.use(koaClassicServer('/public', {
+  enableCaching: true,
+  cacheMaxAge: 3600
+}));
+
+// New (recommended)
+app.use(koaClassicServer('/public', {
+  browserCacheEnabled: true,
+  browserCacheMaxAge: 3600
+}));
+```
+
+**Timeline:**
+- **v2.3.0**: Old names work with deprecation warnings
+- **Future versions**: Old names may be removed (will be announced in advance)
+
+### 📦 Package Changes
+
+- **Version**: `2.2.0` → `2.3.0`
+- **Semver**: Minor version bump (new feature names, backward compatible)
+
+---
+
+## [2.2.0] - 2026-01-03
+
+### ✨ Features
+
+#### Added useOriginalUrl Option
+- **New Option**: `useOriginalUrl` (Boolean, default: `true`)
+- **Purpose**: Controls URL resolution for file serving - use `ctx.originalUrl` (immutable) or `ctx.url` (mutable)
+- **Use Case**: Compatibility with URL rewriting middleware (i18n, routing)
+- **Backward Compatible**: Default value `true` maintains existing behavior
+
+#### URL Rewriting Middleware Support
+- **Problem Solved**: koa-classic-server previously used `ctx.href` (based on `ctx.originalUrl`), which caused 404 errors when middleware rewrites URLs by modifying `ctx.url`
+- **Solution**: Set `useOriginalUrl: false` to use the rewritten URL from `ctx.url` instead
+- **Example**: i18n middleware that strips language prefixes (`/it/page.html` → `/page.html`)
+
+### 📝 Documentation
+
+- Added comprehensive `useOriginalUrl` documentation in README.md
+- Added JSDoc comments in index.cjs
+- Included practical i18n middleware example
+- Added option to API reference table
+
+### 🔧 Changes
+
+- **index.cjs**: Line 108 - Added `useOriginalUrl` option initialization
+- **index.cjs**: Lines 117-125 - Modified URL construction logic to support both `ctx.originalUrl` and `ctx.url`
+- **README.md**: Added detailed section explaining `useOriginalUrl` with examples
+- **package.json**: Version bumped from `2.1.4` to `2.2.0`
+
+### 💡 Usage Example
+
+```javascript
+// i18n middleware example
+app.use(async (ctx, next) => {
+  if (ctx.path.match(/^\/it\//)) {
+    ctx.url = ctx.path.replace(/^\/it/, ''); // /it/page.html → /page.html
+  }
+  await next();
+});
+
+app.use(koaClassicServer('/www', {
+  useOriginalUrl: false // Use rewritten URL
+}));
+```
+
+### ⚠️ Migration Notes
+
+**No breaking changes** - this is a backward-compatible release.
+
+- **Default behavior unchanged**: `useOriginalUrl` defaults to `true`
+- **No code changes required** for existing implementations
+- **New feature**: Set `useOriginalUrl: false` if you use URL rewriting middleware
+
+### 📦 Package Changes
+
+- **Version**: `2.1.4` → `2.2.0`
+- **Semver**: Minor version bump (new feature, backward compatible)
+
+---
+
 ## [2.1.3] - 2025-11-25
 
 ### 🔧 Configuration Changes

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

@@ -44,11 +44,17 @@ module.exports = function koaClassicServer(
             render: undefined, // Template rendering function: async (ctx, next, filePath) => {}
             ext: [], // File extensions to process with template.render
         },
-        cacheMaxAge: 3600, // Cache-Control max-age in seconds (default: 1 hour)
-        enableCaching: false, // Enable HTTP caching headers (ETag, Last-Modified)
-                              // NOTE: Default is false for development.
-                              // In production, it's recommended to set enableCaching: true
-                              // to reduce bandwidth usage and improve performance.
+        browserCacheMaxAge: 3600, // Browser Cache-Control max-age in seconds (default: 1 hour)
+        browserCacheEnabled: false, // Enable browser HTTP caching headers (ETag, Last-Modified)
+                                    // NOTE: Default is false for development.
+                                    // In production, it's recommended to set browserCacheEnabled: true
+                                    // to reduce bandwidth usage and improve performance.
+        useOriginalUrl: true, // Use ctx.originalUrl (default) or ctx.url
+                              // Set false for URL rewriting middleware (i18n, routing)
+
+        // DEPRECATED OPTIONS (maintained for backward compatibility):
+        // cacheMaxAge: use browserCacheMaxAge instead
+        // enableCaching: use browserCacheEnabled instead
     }
     */
 ) {
@@ -100,11 +106,71 @@ module.exports = function koaClassicServer(
     options.template.ext = Array.isArray(options.template.ext) ? options.template.ext : [];
 
     // OPTIMIZATION: HTTP Caching options
-    // NOTE: Default enableCaching is false for development environments.
+    // NOTE: Default browserCacheEnabled is false for development environments.
     // For production deployments, it's strongly recommended to enable caching
-    // by setting enableCaching: true to benefit from reduced bandwidth and improved performance.
-    options.cacheMaxAge = typeof options.cacheMaxAge === 'number' && options.cacheMaxAge >= 0 ? options.cacheMaxAge : 3600;
-    options.enableCaching = typeof options.enableCaching === 'boolean' ? options.enableCaching : false;
+    // by setting browserCacheEnabled: true to benefit from reduced bandwidth and improved performance.
+
+    // DEPRECATION: Handle legacy option names for backward compatibility
+    if ('cacheMaxAge' in opts && !('browserCacheMaxAge' in opts)) {
+        console.warn(
+            '\x1b[33m%s\x1b[0m',
+            '[koa-classic-server] DEPRECATION WARNING: The "cacheMaxAge" option is deprecated and will be removed in future versions.\n' +
+            '  Current usage: cacheMaxAge: ' + opts.cacheMaxAge + '\n' +
+            '  Recommended:   browserCacheMaxAge: ' + opts.cacheMaxAge + '\n' +
+            '  Please update your configuration to use the new option name.'
+        );
+        options.browserCacheMaxAge = opts.cacheMaxAge;
+    }
+
+    if ('enableCaching' in opts && !('browserCacheEnabled' in opts)) {
+        console.warn(
+            '\x1b[33m%s\x1b[0m',
+            '[koa-classic-server] DEPRECATION WARNING: The "enableCaching" option is deprecated and will be removed in future versions.\n' +
+            '  Current usage: enableCaching: ' + opts.enableCaching + '\n' +
+            '  Recommended:   browserCacheEnabled: ' + opts.enableCaching + '\n' +
+            '  Please update your configuration to use the new option name.'
+        );
+        options.browserCacheEnabled = opts.enableCaching;
+    }
+
+    // Set new option names (with defaults)
+    options.browserCacheMaxAge = typeof options.browserCacheMaxAge === 'number' && options.browserCacheMaxAge >= 0 ? options.browserCacheMaxAge : 3600;
+    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
@@ -113,12 +179,14 @@ module.exports = function koaClassicServer(
             return;
         }
 
-        // Normalize URL (remove trailing slash)
+        // Construct full URL based on useOriginalUrl option
+        const urlToUse = options.useOriginalUrl ? ctx.originalUrl : ctx.url;
+        const fullUrl = ctx.protocol + '://' + ctx.host + urlToUse;
         let pageHref = '';
-        if (ctx.href.charAt(ctx.href.length - 1) === '/') {
-            pageHref = new URL(ctx.href.slice(0, -1));
+        if (fullUrl.charAt(fullUrl.length - 1) === '/') {
+            pageHref = new URL(fullUrl.slice(0, -1));
         } else {
-            pageHref = new URL(ctx.href);
+            pageHref = new URL(fullUrl);
         }
 
         // Check URL prefix
@@ -225,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) {
@@ -317,7 +391,7 @@ module.exports = function koaClassicServer(
             }
 
             // OPTIMIZATION: HTTP Caching Headers
-            if (options.enableCaching) {
+            if (options.browserCacheEnabled) {
                 // Generate ETag from mtime timestamp + file size
                 // This ensures ETag changes when file is modified or resized
                 const etag = `"${fileStat.mtime.getTime()}-${fileStat.size}"`;
@@ -328,7 +402,7 @@ module.exports = function koaClassicServer(
                 // Set caching headers
                 ctx.set('ETag', etag);
                 ctx.set('Last-Modified', lastModified);
-                ctx.set('Cache-Control', `public, max-age=${options.cacheMaxAge}, must-revalidate`);
+                ctx.set('Cache-Control', `public, max-age=${options.browserCacheMaxAge}, must-revalidate`);
 
                 // OPTIMIZATION: Handle conditional requests (304 Not Modified)
 
@@ -508,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,
@@ -544,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;
@@ -570,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.1.4",
+  "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": {