koa-classic-server 3.0.0 → 3.1.0

package/docs/DOCUMENTATION.md

@@ -1,1864 +0,0 @@
-# KOA-CLASSIC-SERVER - Documentazione Completa
-
-## Indice
-
-- [Descrizione del Modulo](#descrizione-del-modulo)
-- [Installazione](#installazione)
-- [Avvio Rapido](#avvio-rapido)
-- [Configurazione](#configurazione)
-- [Esempi d'Uso](#esempi-duso)
-- [API Reference](#api-reference)
-- [Comportamento del Middleware](#comportamento-del-middleware)
-- [Testing](#testing)
-- [Troubleshooting](#troubleshooting)
-- [Problemi Noti](#problemi-noti)
-- [Best Practices](#best-practices)
-
----
-
-## Descrizione del Modulo
-
-### Panoramica
-
-**koa-classic-server** è un middleware per Koa.js che emula il comportamento di Apache 2 per la gestione di file statici. Il modulo permette di servire file e directory con funzionalità avanzate di directory listing, supporto per template engine, gestione di URL riservati e configurazione flessibile.
-
-### Caratteristiche Principali
-
-#### 1. Servizio File Statici
-- Serve file statici da una directory specificata
-- Riconoscimento automatico dei MIME types
-- Gestione corretta di encoding e content-disposition
-- Supporto per caratteri speciali e Unicode nei nomi file
-
-#### 2. Directory Listing
-- Visualizzazione del contenuto delle directory in formato HTML tabellare
-- Navigazione parent directory con link ".. Parent Directory"
-- Indicazione chiara del tipo di risorsa (DIR, MIME type)
-- Gestione e visualizzazione cartelle riservate
-- 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)
-- Rendering personalizzato per estensioni specifiche
-- Callback configurabile per il rendering
-- Accesso completo al contesto Koa (ctx, next)
-
-#### 4. Gestione URL Avanzata
-- Supporto per URL prefix (es. `/public`, `/static`, `/files`)
-- URL riservati non accessibili da remoto
-- Normalizzazione automatica degli URL (rimozione trailing slash)
-- Decodifica URI corretta per spazi e caratteri speciali
-- Gestione case-sensitive dei path
-
-#### 5. Compatibilità Moduli
-- Supporto CommonJS (`require`)
-- Supporto ES Modules (`import`)
-- Conditional exports in package.json per massima compatibilità
-
-### Architettura
-
-```
-koa-classic-server/
-├── index.cjs          # Implementazione principale (CommonJS)
-├── index.mjs          # Wrapper ES Modules
-├── package.json       # Configurazione con conditional exports
-├── __tests__/         # Suite di test Jest
-│   ├── index.test.js  # Test completi
-│   └── publicWwwTest/ # Cartella di test
-├── customTest/        # Utility per test manuali
-│   ├── loadConfig.util.js      # Script interattivo
-│   └── serversToLoad.util.js   # Configurazioni test
-├── LICENSE            # Licenza MIT
-├── README.md          # Documentazione base
-└── DOCUMENTATION.md   # Questa documentazione
-```
-
-### Flusso di Esecuzione
-
-Il middleware segue questo flusso per ogni richiesta HTTP:
-
-1. **Validazione Metodo HTTP**: Verifica che il metodo sia tra quelli ammessi
-2. **Normalizzazione URL**: Rimuove trailing slash e normalizza il path
-3. **Verifica URL Prefix**: Controlla che la richiesta cada sotto il prefix configurato
-4. **Controllo URL Riservati**: Verifica che non sia una risorsa protetta
-5. **Risoluzione Path**: Costruisce il path completo file/directory
-6. **Esistenza Risorsa**: Verifica che file o directory esistano
-7. **Gestione Risorsa**:
-   - **File**: Template rendering o servizio statico
-   - **Directory**: Index file o directory listing
-
-### Dipendenze
-
-#### Production
-- **mime-types** (^2.1.35): Riconoscimento automatico MIME types
-
-#### Peer Dependencies
-- **koa** (^2.0.0 || >=3.1.2): Framework web minimale per Node.js
-
-#### Development
-- **jest** (^30.2.0): Framework di testing
-- **supertest** (^7.2.2): Testing richieste HTTP
-- **inquirer** (^13.3.0): CLI interattiva per testing manuale
-- **autocannon** (^8.0.0): HTTP benchmarking
-- **ejs** (^3.1.10): Template engine per i test
-
----
-
-## Installazione
-
-### Installazione via npm
-
-```bash
-npm install koa-classic-server
-```
-
-### Installazione via yarn
-
-```bash
-yarn add koa-classic-server
-```
-
-### Requisiti
-
-- **Node.js**: 12.20+ (raccomandato 14+)
-- **Koa**: 2.x
-
----
-
-## Avvio Rapido
-
-### Esempio Minimale
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-// Serve tutti i file dalla cartella "public"
-app.use(koaClassicServer(__dirname + '/public'));
-
-app.listen(3000);
-console.log('Server avviato su http://localhost:3000');
-```
-
-Questa configurazione base:
-- Serve tutti i file dalla cartella `public`
-- Mostra il contenuto delle directory
-- Accetta solo richieste GET
-- Nessun URL prefix o percorso riservato
-
-### Esempio con Opzioni
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-app.use(koaClassicServer(__dirname + '/public', {
-  dirListing: { enabled: true },
-  index: 'index.html',
-  urlPrefix: '/static'
-}));
-
-app.listen(3000);
-console.log('Server avviato su http://localhost:3000/static');
-```
-
----
-
-## Configurazione
-
-### Sintassi
-
-```javascript
-koaClassicServer(rootDir, options)
-```
-
-### Parametri
-
-| Parametro | Tipo | Obbligatorio | Descrizione |
-|-----------|------|--------------|-------------|
-| `rootDir` | String | Sì | Path assoluto della directory da servire |
-| `options` | Object | No | Oggetto di configurazione |
-
-### Opzioni Disponibili
-
-```javascript
-const options = {
-  // Metodi HTTP ammessi
-  // Default: ['GET']
-  method: ['GET', 'HEAD'],
-
-  // Mostra il contenuto delle directory
-  // Default: true
-  dirListing: { enabled: true },
-
-  // Nome del file index da caricare automaticamente nelle directory
-  // Se presente, viene caricato invece del directory listing
-  // Default: ''
-  index: 'index.html',
-
-  // Prefisso URL da rimuovere dal path
-  // Es: '/public' significa che i file sono accessibili sotto /public/
-  // Default: ''
-  urlPrefix: '/public',
-
-  // Array di percorsi riservati (non accessibili da remoto)
-  // Funziona solo per directory di primo livello
-  // Default: []
-  urlsReserved: ['/api', '/admin', '/config'],
-
-  // Configurazione template engine
-  template: {
-    // Funzione di rendering personalizzata
-    // Riceve: ctx (contesto Koa), next (middleware successivo), filePath (path file)
-    // Default: undefined
-    render: async (ctx, next, filePath) => {
-      // Implementazione custom
-      // Es: ctx.body = await ejs.renderFile(filePath, data);
-    },
-
-    // Array di estensioni file da processare con template.render
-    // Se un file ha una di queste estensioni, viene chiamato render()
-    // Default: []
-    ext: ['ejs', 'EJS', 'pug', 'html']
-  }
-};
-```
-
-### Dettaglio Opzioni
-
-#### `method` (Array)
-
-Specifica i metodi HTTP accettati dal middleware. Se una richiesta usa un metodo non presente nell'array, viene passata al middleware successivo.
-
-```javascript
-// Solo GET
-method: ['GET']
-
-// GET e HEAD (utile per check esistenza file)
-method: ['GET', 'HEAD']
-
-// Multipli metodi (uso avanzato)
-method: ['GET', 'HEAD', 'POST']
-```
-
-#### `dirListing.enabled` (Boolean)
-
-Controlla se mostrare il contenuto delle directory.
-
-```javascript
-// Mostra directory listing
-dirListing: { enabled: true }
-
-// Non mostra directory (restituisce "Not Found")
-dirListing: { enabled: false }
-```
-
-#### `index` (String)
-
-Nome del file da caricare automaticamente quando si accede a una directory.
-
-```javascript
-// Carica index.html se presente
-index: 'index.html'
-
-// Carica default.htm se presente
-index: 'default.htm'
-
-// Nessun index (mostra sempre directory listing)
-index: ''
-```
-
-**Comportamento:**
-1. Utente accede a `/cartella/`
-2. Se esiste `/cartella/index.html` → viene servito
-3. Altrimenti → mostra directory listing (se `dirListing: { enabled: true }`)
-
-#### `urlPrefix` (String)
-
-Prefisso URL che il middleware deve intercettare. Utile per montare il file server sotto un percorso specifico.
-
-```javascript
-// File accessibili sotto /static
-// Es: /static/image.png, /static/css/style.css
-urlPrefix: '/static'
-
-// File accessibili sotto /public
-urlPrefix: '/public'
-
-// Nessun prefix (root del server)
-urlPrefix: ''
-```
-
-**Importante:**
-- Il prefix viene rimosso prima di cercare il file nel filesystem
-- Richiesta: `/static/image.png` → cerca `rootDir/image.png`
-
-#### `urlsReserved` (Array)
-
-Array di percorsi protetti, non accessibili da remoto. Utile per proteggere directory sensibili.
-
-```javascript
-urlsReserved: ['/config', '/private', '/.env']
-```
-
-**Limitazioni:**
-- Funziona solo per directory di primo livello
-- Non supporta percorsi annidati
-- Non supporta wildcard
-
-**Esempio:**
-```javascript
-// ✅ Funziona
-urlsReserved: ['/admin']
-// Blocca: /admin, /admin/file.txt, /admin/sub/file.txt
-
-// ❌ Non funziona come ci si aspetta
-urlsReserved: ['/folder/subfolder']
-// Non blocca percorsi annidati
-```
-
-#### `template.render` (Function)
-
-Funzione personalizzata per il rendering di template.
-
-**Firma:**
-```javascript
-async function render(ctx, next, filePath) {
-  // ctx: Contesto Koa
-  // next: Middleware successivo
-  // filePath: Path completo del file da renderizzare
-
-  // Esempio EJS
-  ctx.body = await ejs.renderFile(filePath, {
-    // Dati passati al template
-    title: 'My Page',
-    user: ctx.state.user
-  });
-}
-```
-
-#### `template.ext` (Array)
-
-Array di estensioni file che devono essere processate con `template.render`.
-
-```javascript
-// Solo file .ejs
-ext: ['ejs']
-
-// File .ejs e .EJS (case-sensitive)
-ext: ['ejs', 'EJS']
-
-// Multipli template engine
-ext: ['ejs', 'pug', 'html', 'hbs']
-```
-
-**Comportamento:**
-- Se file ha estensione in `ext` E `render` è definito → esegue rendering
-- Altrimenti → serve file normalmente
-
----
-
-## Esempi d'Uso
-
-### 1. Server Base con Directory Listing
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-app.use(koaClassicServer(__dirname + '/public', {
-  dirListing: { enabled: true },
-  index: 'index.html'
-}));
-
-app.listen(3000);
-console.log('Server su http://localhost:3000');
-```
-
-**Funzionalità:**
-- Serve file da `public/`
-- Mostra directory listing
-- Carica `index.html` automaticamente se presente
-
----
-
-### 2. Server con URL Prefix
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-// File accessibili sotto /static
-app.use(koaClassicServer(__dirname + '/public', {
-  urlPrefix: '/static',
-  method: ['GET', 'HEAD'],
-  dirListing: { enabled: true }
-}));
-
-// Altri middleware per route diverse
-app.use(async (ctx) => {
-  ctx.body = 'Homepage del sito';
-});
-
-app.listen(3000);
-```
-
-**URL esempi:**
-- `http://localhost:3000/` → Homepage
-- `http://localhost:3000/static/` → Directory listing di public/
-- `http://localhost:3000/static/image.png` → public/image.png
-
----
-
-### 3. Server con Cartelle Protette
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-app.use(koaClassicServer(__dirname + '/www', {
-  dirListing: { enabled: true },
-  // Protegge directory sensibili
-  urlsReserved: ['/config', '/private', '/.git', '/node_modules']
-}));
-
-app.listen(3000);
-```
-
-**Comportamento:**
-- `/config/` → Not Found (protetto)
-- `/private/secret.txt` → Not Found (protetto)
-- `/public/file.txt` → Accessibile
-
----
-
-### 4. Server con Template Engine (EJS)
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-const ejs = require('ejs');
-
-const app = new Koa();
-
-app.use(koaClassicServer(__dirname + '/views', {
-  dirListing: { enabled: false },
-  template: {
-    render: async (ctx, next, filePath) => {
-      // Rendering EJS con dati
-      ctx.body = await ejs.renderFile(filePath, {
-        title: 'My App',
-        filePath: filePath,
-        href: ctx.href,
-        query: ctx.query,
-        user: ctx.state.user || 'Guest'
-      });
-    },
-    ext: ['ejs', 'EJS']
-  }
-}));
-
-app.listen(3000);
-console.log('Server con EJS su http://localhost:3000');
-```
-
----
-
-### 5. Server Multi-Directory
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-// File statici pubblici
-app.use(koaClassicServer(__dirname + '/public', {
-  urlPrefix: '/public',
-  dirListing: { enabled: true }
-}));
-
-// Asset (CSS, JS, images)
-app.use(koaClassicServer(__dirname + '/assets', {
-  urlPrefix: '/assets',
-  dirListing: { enabled: false }
-}));
-
-// Download area
-app.use(koaClassicServer(__dirname + '/downloads', {
-  urlPrefix: '/downloads',
-  dirListing: { enabled: true },
-  index: 'README.txt'
-}));
-
-app.listen(3000);
-```
-
----
-
-### 6. Configurazione Completa Produzione
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-const ejs = require('ejs');
-const path = require('path');
-
-const app = new Koa();
-
-// Logging middleware
-app.use(async (ctx, next) => {
-  const start = Date.now();
-  await next();
-  const ms = Date.now() - start;
-  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`);
-});
-
-// Error handling
-app.on('error', (err, ctx) => {
-  console.error('Server error:', err);
-});
-
-// Template render function
-const templateRender = async (ctx, next, filePath) => {
-  try {
-    ctx.body = await ejs.renderFile(filePath, {
-      filePath: filePath,
-      href: ctx.href,
-      query: ctx.query,
-      method: ctx.method,
-      env: process.env.NODE_ENV
-    });
-  } catch (err) {
-    console.error('Template render error:', err);
-    ctx.status = 500;
-    ctx.body = 'Template Error';
-  }
-};
-
-// File server
-app.use(koaClassicServer(path.join(__dirname, 'public'), {
-  method: ['GET', 'HEAD'],
-  dirListing: { enabled: process.env.NODE_ENV !== 'production' },
-  index: 'index.html',
-  urlPrefix: '/files',
-  urlsReserved: ['/admin', '/private', '/config', '/.env'],
-  template: {
-    render: templateRender,
-    ext: ['ejs', 'html']
-  }
-}));
-
-// 404 fallback
-app.use(async (ctx) => {
-  ctx.status = 404;
-  ctx.body = 'Pagina non trovata';
-});
-
-const port = process.env.PORT || 3000;
-app.listen(port, () => {
-  console.log(`Server avviato su http://localhost:${port}`);
-  console.log(`Ambiente: ${process.env.NODE_ENV || 'development'}`);
-});
-```
-
----
-
-### 7. Integrazione con Router Koa
-
-```javascript
-const Koa = require('koa');
-const Router = require('@koa/router');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-const router = new Router();
-
-// API routes
-router.get('/api/users', (ctx) => {
-  ctx.body = { users: ['Alice', 'Bob'] };
-});
-
-router.post('/api/login', (ctx) => {
-  ctx.body = { token: 'xyz123' };
-});
-
-// Monta il router
-app.use(router.routes());
-app.use(router.allowedMethods());
-
-// File statici (dopo le route API)
-app.use(koaClassicServer(__dirname + '/public', {
-  dirListing: { enabled: true }
-}));
-
-app.listen(3000);
-```
-
-**Ordine importante:**
-1. Router con API dinamiche
-2. File server statico
-3. Questo permette alle API di avere precedenza sui file
-
----
-
-## API Reference
-
-### koaClassicServer(rootDir, options)
-
-Crea e restituisce un middleware Koa per servire file statici.
-
-**Parametri:**
-
-- `rootDir` (String, required): Path assoluto directory root
-- `options` (Object, optional): Oggetto configurazione
-
-**Restituisce:**
-
-- Function: Middleware Koa `async (ctx, next) => {...}`
-
-**Esempio:**
-
-```javascript
-const middleware = koaClassicServer('/path/to/files', {
-  dirListing: { enabled: true }
-});
-
-app.use(middleware);
-```
-
-### Oggetto Options
-
-Vedi sezione [Configurazione](#configurazione) per dettagli completi.
-
-### Context (ctx) nel Template Render
-
-Quando usi `template.render`, hai accesso completo al contesto Koa:
-
-```javascript
-template: {
-  render: async (ctx, next, filePath) => {
-    // ctx.request - Oggetto richiesta
-    console.log(ctx.request.method);  // 'GET', 'POST', etc.
-    console.log(ctx.request.url);     // '/path/to/file'
-    console.log(ctx.request.header);  // Headers HTTP
-
-    // ctx.response - Oggetto risposta
-    ctx.response.type = 'text/html';
-    ctx.response.body = '<html>...</html>';
-
-    // Shortcuts
-    console.log(ctx.method);   // 'GET'
-    console.log(ctx.url);      // '/path/to/file'
-    console.log(ctx.href);     // 'http://localhost:3000/path/to/file'
-    console.log(ctx.query);    // { key: 'value' }
-    console.log(ctx.path);     // '/path/to/file'
-
-    // State (dati condivisi tra middleware)
-    console.log(ctx.state.user);
-
-    // Cookies
-    console.log(ctx.cookies.get('session'));
-
-    // filePath - Path completo del file
-    console.log(filePath);  // '/var/www/public/page.ejs'
-  }
-}
-```
-
----
-
-## Comportamento del Middleware
-
-### Gestione delle Directory
-
-#### Caso 1: dirListing.enabled = true, index presente
-
-```
-Richiesta: GET /cartella/
-Filesystem:
-  /cartella/index.html ✓ (esiste)
-  /cartella/file1.txt
-
-Risultato: Serve /cartella/index.html
-```
-
-#### Caso 2: dirListing.enabled = true, index assente
-
-```
-Richiesta: GET /cartella/
-Filesystem:
-  /cartella/file1.txt
-  /cartella/file2.jpg
-
-Risultato: Mostra directory listing HTML
-```
-
-#### Caso 3: dirListing.enabled = false
-
-```
-Richiesta: GET /cartella/
-
-Risultato: "Not Found" (indipendentemente da index)
-```
-
-### Gestione dei File
-
-#### File Normale
-
-```
-Richiesta: GET /document.pdf
-Filesystem: /document.pdf (esiste)
-
-Risultato:
-  Status: 200
-  Content-Type: application/pdf
-  Content-Disposition: inline; filename=document.pdf
-  Body: [file stream]
-```
-
-#### File Template
-
-```
-Richiesta: GET /page.ejs
-Filesystem: /page.ejs (esiste)
-Config: template.ext = ['ejs'], template.render definito
-
-Risultato:
-  Status: 200
-  Content-Type: [settato da template.render]
-  Body: [output renderizzato]
-```
-
-### URL Riservati
-
-```
-Config: urlsReserved = ['/admin', '/private']
-
-Richiesta: GET /admin/config.json
-Risultato: Passa a middleware successivo (salta koa-classic-server)
-
-Richiesta: GET /admin/
-Risultato: Directory listing mostra "DIR BUT RESERVED"
-
-Richiesta: GET /public/file.txt
-Risultato: File servito normalmente
-```
-
-### Parent Directory Navigation
-
-Nel directory listing, viene sempre mostrato link alla parent directory, tranne nella root:
-
-```html
-<!-- Root: http://localhost:3000/ -->
-<!-- Nessun parent directory link -->
-
-<!-- Sub-directory: http://localhost:3000/folder/ -->
-<table>
-  <tr><td><a href="http://localhost:3000"><b>.. Parent Directory</b></a></td><td>DIR</td></tr>
-  <!-- altri file... -->
-</table>
-```
-
-### Normalizzazione URL
-
-Il middleware normalizza automaticamente gli URL:
-
-```
-http://localhost:3000/folder/  → http://localhost:3000/folder
-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:
-
-```javascript
-.html → text/html
-.css  → text/css
-.js   → application/javascript
-.json → application/json
-.png  → image/png
-.jpg  → image/jpeg
-.pdf  → application/pdf
-.txt  → text/plain
-// ... e molti altri
-```
-
-Se MIME type non riconosciuto:
-```
-Estensione sconosciuta → 'unknow' (nel directory listing)
-```
-
----
-
-## Testing
-
-### Test Automatici (Jest)
-
-Il progetto include una suite completa di test.
-
-```bash
-# Esegui tutti i test
-npm test
-
-# Test con coverage
-npm test -- --coverage
-
-# Test in watch mode
-npm test -- --watch
-```
-
-### Test Coverage
-
-I test coprono:
-
-- ✅ Servizio file statici
-- ✅ Directory listing
-- ✅ URL prefix
-- ✅ URL riservati
-- ✅ File index
-- ✅ Percorsi non esistenti
-- ✅ Metodi HTTP
-- ✅ Caratteri speciali nei nomi file
-- ⚠️ Template rendering (parziale)
-- ⚠️ Directory listing completo (parziale)
-
-### Test Manuali Interattivi
-
-Per testare manualmente diverse configurazioni:
-
-```bash
-npm run loadConfig
-```
-
-Questo comando:
-1. Mostra menu interattivo con configurazioni predefinite
-2. Avvia server con configurazione scelta
-3. Permette test manuale via browser
-
-**Configurazioni disponibili:**
-- Test generico base
-- Test con URL prefix `/public`
-- Test con file index
-- Test con percorsi riservati
-
-### Struttura Test
-
-```
-__tests__/
-├── index.test.js       # Suite principale
-└── publicWwwTest/      # Cartella test con file/directory campione
-    ├── file.txt
-    ├── image.png
-    ├── subfolder/
-    └── ...
-```
-
-### Scrivere Nuovi Test
-
-Esempio test personalizzato:
-
-```javascript
-const supertest = require('supertest');
-const koaClassicServer = require('../index.cjs');
-const Koa = require('koa');
-
-describe('My custom test', () => {
-  let app, server;
-
-  beforeAll(() => {
-    app = new Koa();
-    app.use(koaClassicServer(__dirname + '/test-files', {
-      dirListing: { enabled: true }
-    }));
-    server = app.listen();
-  });
-
-  test('should serve HTML file', async () => {
-    const res = await supertest(server).get('/index.html');
-    expect(res.status).toBe(200);
-    expect(res.type).toMatch(/text\/html/);
-  });
-
-  afterAll(() => {
-    server.close();
-  });
-});
-```
-
----
-
-## Troubleshooting
-
-### File non viene servito
-
-**Problema:** Richiesta a file esistente restituisce 404
-
-**Soluzioni:**
-
-1. Verifica path assoluto:
-```javascript
-// ❌ Path relativo
-koaClassicServer('./public')
-
-// ✅ Path assoluto
-koaClassicServer(__dirname + '/public')
-koaClassicServer(path.join(__dirname, 'public'))
-```
-
-2. Controlla URL prefix:
-```javascript
-// Config
-urlPrefix: '/static'
-
-// ❌ URL sbagliato
-http://localhost:3000/file.txt
-
-// ✅ URL corretto
-http://localhost:3000/static/file.txt
-```
-
-3. Verifica URL riservati:
-```javascript
-// Config
-urlsReserved: ['/protected']
-
-// ❌ File in cartella protetta
-GET /protected/file.txt → 404
-
-// ✅ File fuori da cartella protetta
-GET /public/file.txt → 200
-```
-
----
-
-### Template non viene renderizzato
-
-**Problema:** File template viene servito come testo invece di essere renderizzato
-
-**Soluzioni:**
-
-1. Verifica estensione in `template.ext`:
-```javascript
-// File: page.ejs
-
-// ❌ Estensione mancante
-template: {
-  render: renderFunction,
-  ext: ['html']  // manca 'ejs'
-}
-
-// ✅ Estensione presente
-template: {
-  render: renderFunction,
-  ext: ['ejs', 'EJS']
-}
-```
-
-2. Verifica `template.render` sia funzione:
-```javascript
-// ❌ render non definito
-template: {
-  ext: ['ejs']
-  // render mancante!
-}
-
-// ✅ render definito
-template: {
-  render: async (ctx, next, filePath) => {
-    ctx.body = await ejs.renderFile(filePath, {});
-  },
-  ext: ['ejs']
-}
-```
-
-3. Installa template engine:
-```bash
-npm install ejs
-```
-
----
-
-### Directory listing non funziona
-
-**Problema:** Accesso a directory restituisce "Not Found"
-
-**Soluzione:**
-
-```javascript
-// ❌ dirListing.enabled disabilitato
-dirListing: { enabled: false }
-
-// ✅ dirListing.enabled abilitato
-dirListing: { enabled: true }
-```
-
----
-
-### URL riservati non proteggono
-
-**Problema:** File in cartelle riservate sono accessibili
-
-**Cause comuni:**
-
-1. **Percorsi annidati non supportati:**
-```javascript
-// ❌ Non funziona
-urlsReserved: ['/path/to/protected']
-
-// ✅ Solo primo livello
-urlsReserved: ['/protected']
-```
-
-2. **Spazi nei nomi (bug noto):**
-```javascript
-// ⚠️ Problematico
-urlsReserved: ['/percorso riservato']
-
-// ✅ Usa underscore o trattini
-urlsReserved: ['/percorso_riservato', '/percorso-riservato']
-```
-
----
-
-### Metodo HTTP non accettato
-
-**Problema:** Richieste POST/PUT/DELETE non funzionano
-
-**Soluzione:**
-
-```javascript
-// ❌ Solo GET (default)
-method: ['GET']
-
-// ✅ Aggiungi metodi necessari
-method: ['GET', 'POST', 'PUT', 'DELETE']
-```
-
-**Nota:** Di solito file server necessita solo GET e HEAD
-
----
-
-### Caratteri speciali in nomi file
-
-**Problema:** File con spazi o caratteri speciali non accessibili
-
-**Soluzione:**
-
-Il middleware gestisce automaticamente URI encoding. Assicurati che il client codifichi correttamente:
-
-```javascript
-// ❌ Non encodato
-GET /my file.txt
-
-// ✅ Encodato (automatico nei browser)
-GET /my%20file.txt
-```
-
-In JavaScript:
-```javascript
-const filename = 'my file.txt';
-const url = '/' + encodeURIComponent(filename);
-// url = '/my%20file.txt'
-```
-
----
-
-### Performance con molti file
-
-**Problema:** Directory listing lento con migliaia di file
-
-**Soluzioni:**
-
-1. Disabilita directory listing:
-```javascript
-dirListing: { enabled: false }
-```
-
-2. Usa file index:
-```javascript
-dirListing: { enabled: true },
-index: 'index.html'  // Carica index invece di listing
-```
-
-3. Considera soluzioni alternative per grandi quantità di file (es. nginx, CDN)
-
----
-
-## Problemi Noti
-
-### 1. Status Code 404 Mancante
-
-**Problema:** Quando una risorsa non viene trovata, lo status code è 200 invece di 404
-
-**File:** `index.cjs:110`
-
-```javascript
-if (!fs.existsSync(toOpen)) {
-  ctx.body = requestedUrlNotFound();
-  // Manca: ctx.status = 404;
-  return;
-}
-```
-
-**Workaround:**
-```javascript
-// Middleware successivo per gestire 404
-app.use(async (ctx) => {
-  if (!ctx.body) {
-    ctx.status = 404;
-    ctx.body = 'Not Found';
-  }
-});
-```
-
----
-
-### 2. URL Riservati con Spazi
-
-**Problema:** Il controllo URL riservati non funziona con percorsi contenenti spazi
-
-**File:** `index.cjs:87-96`
-
-**Limitazione:** Problemi con URI encoding negli URL riservati
-
-**Workaround:** Evita spazi nei nomi delle cartelle riservate:
-```javascript
-// ❌ Non funziona
-urlsReserved: ['/percorso riservato']
-
-// ✅ Funziona
-urlsReserved: ['/percorso_riservato', '/percorso-riservato']
-```
-
----
-
-### 3. URL Riservati Solo Primo Livello
-
-**Problema:** URL riservati funzionano solo per directory di primo livello, non per percorsi annidati
-
-**File:** `index.cjs:87-96`
-
-**Limitazione:** Design della funzionalità
-
-```javascript
-// ❌ Non supportato
-urlsReserved: ['/path/to/protected']
-
-// ✅ Supportato
-urlsReserved: ['/protected']
-// Blocca: /protected, /protected/file.txt, /protected/sub/file.txt
-```
-
----
-
-### 4. Test Coverage Incompleto
-
-**Problema:** Test non coprono completamente:
-- Contenuto HTML del directory listing
-- Tutti i casi di template rendering
-
-**File:** `__tests__/index.test.js:1-11`
-
-**Impatto:** Possibili bug non rilevati in queste aree
-
----
-
-### 5. Single Index File
-
-**Problema:** Supporto per un solo nome file index, non array di fallback
-
-**Limitazione:** Design attuale
-
-```javascript
-// ❌ Non supportato
-index: ['index.html', 'index.htm', 'default.html']
-
-// ✅ Supportato
-index: 'index.html'
-```
-
-**Workaround:** Standardizza su un solo nome file index
-
----
-
-## Best Practices
-
-### 1. Sicurezza
-
-#### Usa Path Assoluti
-```javascript
-// ✅ Corretto
-const path = require('path');
-app.use(koaClassicServer(path.join(__dirname, 'public')));
-
-// ❌ Evita path relativi
-app.use(koaClassicServer('./public'));
-```
-
-#### Proteggi Directory Sensibili
-```javascript
-app.use(koaClassicServer(__dirname + '/www', {
-  urlsReserved: [
-    '/config',
-    '/.env',
-    '/.git',
-    '/node_modules',
-    '/private',
-    '/admin'
-  ]
-}));
-```
-
-#### Limita Metodi HTTP
-```javascript
-// Solo lettura
-method: ['GET', 'HEAD']
-
-// Evita metodi di scrittura per file server
-// method: ['POST', 'PUT', 'DELETE']  ❌
-```
-
-#### Disabilita Directory Listing in Produzione
-```javascript
-app.use(koaClassicServer(rootDir, {
-  dirListing: { enabled: process.env.NODE_ENV !== 'production' },
-  index: 'index.html'
-}));
-```
-
-#### DNS Rebinding — valida l'header `Host` a monte
-
-`koa-classic-server` **non valida l'header `Host`** delle richieste in entrata. Questo è intenzionale: la validazione del Virtual Host appartiene allo strato di rete (reverse proxy o middleware Koa applicativo), non a un file server.
-
-In assenza di tale validazione, un host LAN/loopback (es. `127.0.0.1`, `192.168.x.x`) è vulnerabile a **DNS rebinding**: un attaccante remoto può far risolvere il proprio dominio all'IP della vittima ed eseguire richieste cross-origin verso il server locale come se provenissero da un'origine legittima del browser.
-
-**Quando è un problema concreto**
-- Server raggiunto da `localhost` / IP privati senza reverse proxy davanti.
-- Browser dell'utente che visita pagine non fidate mentre il server è attivo.
-
-**Quando NON è un problema**
-- Deploy dietro reverse proxy (nginx, Caddy, Apache, Traefik) configurato con allowlist di `server_name` / hostname.
-- Server raggiungibile solo da IP pubblico dietro CDN/WAF.
-- Binding esplicito a interfaccia non instradabile (`app.listen(port, '127.0.0.1')`) e nessun browser locale espone l'utente a pagine ostili.
-
-**Mitigazione 1 — reverse proxy (raccomandato in produzione)**
-
-Esempio nginx:
-```nginx
-server {
-    listen 80;
-    server_name app.example.com;      # ← allowlist
-    location / { proxy_pass http://127.0.0.1:3000; }
-}
-# Tutte le richieste con Host diverso da app.example.com vengono rifiutate qui.
-```
-
-**Mitigazione 2 — middleware Koa applicativo (utile in dev/LAN)**
-
-Antepone una guardia su `ctx.host` PRIMA di `koa-classic-server`:
-
-```javascript
-const ALLOWED_HOSTS = new Set([
-  'app.example.com',
-  'localhost:3000',
-  '127.0.0.1:3000',
-]);
-
-app.use(async (ctx, next) => {
-  // ctx.host include la porta (es. "localhost:3000")
-  if (!ALLOWED_HOSTS.has(ctx.host)) {
-    ctx.status = 421; // Misdirected Request
-    ctx.body = 'Host not allowed';
-    return;
-  }
-  await next();
-});
-
-app.use(koaClassicServer(rootDir));
-```
-
-> ⚠️ Se il proxy a monte termina TLS e inoltra all'app, configura `app.proxy = true` e usa `ctx.hostname` con `X-Forwarded-Host` solo se il proxy è fidato.
-
-#### Limiti dei Security Headers sui file statici
-
-`koa-classic-server` imposta automaticamente i seguenti header SOLO sulle **risposte generate** dal middleware (directory listing HTML, pagine di errore 400/403/404/405/500):
-
-| Header | Valore |
-|---|---|
-| `Content-Security-Policy` | `default-src 'none'; ...` (hash-based per il listing, fully restrictive per gli errori) |
-| `X-Content-Type-Options` | `nosniff` |
-| `X-Frame-Options` | `DENY` |
-| `Referrer-Policy` | `no-referrer` |
-| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
-
-**Cosa NON riceve questi header**
-
-I **file statici** serviti dal disco (HTML, JS, CSS, immagini, font, video, qualsiasi altra estensione) sono restituiti **senza** alcun header di sicurezza aggiunto. Questo è **by-design**:
-
-- Le policy di sicurezza appropriate sono diverse caso per caso (CSP per app SPA, sandbox per documenti, COEP/COOP per pagine con SharedArrayBuffer, ecc.).
-- Imporre una CSP rigida di default romperebbe la maggior parte dei siti reali (script inline, CDN, Google Fonts, ecc.).
-- L'utente possiede la propria policy e deve dichiararla esplicitamente.
-
-> ⚠️ Non assumere che il middleware "metta in sicurezza" i tuoi file: gli header sopra elencati vengono inviati **solo** quando la risposta è generata dal middleware stesso.
-
-**Come aggiungere security headers ai file statici**
-
-Inserisci un middleware Koa **prima** di `koa-classic-server`. Il middleware si applica a ogni risposta uscente, statica o generata che sia, e i `ctx.set()` rimangono attivi anche dopo che il file server scrive il body:
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-// 1) Header globali su TUTTE le risposte (statiche + generate).
-app.use(async (ctx, next) => {
-  // Header sempre validi per un file server pubblico:
-  ctx.set('X-Content-Type-Options', 'nosniff');
-  ctx.set('Referrer-Policy', 'strict-origin-when-cross-origin');
-  ctx.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
-
-  // CSP per file HTML serviti dall'utente (mantieni il file server per gli altri MIME).
-  // Esempio strict-by-default per un sito statico moderno:
-  if (ctx.path.endsWith('.html') || ctx.path === '/' || ctx.path.endsWith('/')) {
-    ctx.set('Content-Security-Policy',
-      "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " +
-      "script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
-    );
-  }
-
-  await next();
-});
-
-// 2) Quindi il file server.
-app.use(koaClassicServer(__dirname + '/public'));
-
-app.listen(3000);
-```
-
-**Note operative**
-
-- Il middleware sopra **non sovrascrive** gli header che `koa-classic-server` imposta sulle proprie pagine (listing/errori): Koa preserva il primo `set()`, ma se vuoi essere esplicito puoi applicare le tue policy solo a `ctx.status < 400` e a `Content-Type` HTML.
-- Una CSP rigida con `default-src 'self'` rompe pagine che usano script inline o CDN: parti **report-only** (`Content-Security-Policy-Report-Only`) per rilevare le violazioni prima di enforce-arla.
-- Per progetti SPA/PWA che richiedono `SharedArrayBuffer`, considera anche `Cross-Origin-Opener-Policy: same-origin` e `Cross-Origin-Embedder-Policy: require-corp`.
-
-#### Security Checklist & Suggested Configuration
-
-`koa-classic-server` parte dal principio **"file server first"** (vedi [`CLAUDE.md`](../CLAUDE.md)): i default servono i file senza restrizioni di policy nascoste. L'operatore irrobustisce il deploy tramite **configurazione esplicita**.
-
-##### Checklist per categoria
-
-**Static site / public asset serving**
-
-| ✓ | Cosa | Snippet |
-|---|---|---|
-| ☐ | Nascondi dot-files con potenziali segreti | `hidden: { dotFiles: { default: 'hidden', whitelist: ['.well-known'] } }` |
-| ☐ | Blocca dot-directories tipo `.git` | `hidden: { dotDirs: { default: 'hidden', whitelist: ['.well-known'] } }` |
-| ☐ | Disabilita listing in produzione | `dirListing: { enabled: false }` + `index` |
-| ☐ | Abilita HTTP caching | `browserCacheEnabled: true, browserCacheMaxAge: 86400` |
-| ☐ | Restringi i metodi | `method: ['GET', 'HEAD']` |
-| ☐ | Riserva path applicativi | `urlsReserved: ['/api', '/admin']` |
-| ☐ | Aggiungi security headers upstream sui file utente | middleware Koa upstream (vedi *Limiti dei Security Headers* sopra) |
-
-**User uploads / multi-tenant / directory scrivibili da terzi**
-
-| ✓ | Cosa | Snippet |
-|---|---|---|
-| ☐ | Cap entries più stretto contro dir gonfiate | `dirListing: { maxEntries: 1000 }` |
-| ☐ | Hide dot-files a ogni profondità | `hidden: { dotFiles: { default: 'hidden' }, dotDirs: { default: 'hidden' } }` |
-| ☐ | Blocklist path-aware per pattern noti | `hidden: { alwaysHide: ['*.key', '*.pem', /\.secret$/, 'config/secrets/**'] }` |
-| ☐ | Monitora la crescita dir esternamente (cron + alert) | — |
-
-> **Caveat v3.0:** `dirListing.maxEntries` bounda rendering/CPU ma NON la lettura iniziale `readdir()`. Per workload adversarial (utenti non fidati che possono creare milioni di file) la protezione RAM completa arriverà con il `readMode: 'bounded'` di v3.1 (vedi `[F-1]` in `docs/security_improvement_for_V3.md`).
-
-**Production hygiene (qualsiasi deploy)**
-
-| ✓ | Cosa | Snippet |
-|---|---|---|
-| ☐ | Allowlist Host upstream | nginx `server_name` o middleware Koa allowlist su `ctx.host` |
-| ☐ | Disabilita template engine se non SSR | ometti `template` |
-| ☐ | Tune `template.renderTimeout` | abbassa da 30 s per SLA stretti |
-| ☐ | Logger strutturato (Pino/Winston) | `logger: pino()` |
-| ☐ | Pin patch version + `npm audit` in CI | `package.json` + workflow CI |
-
-##### Suggested production security configuration
-
-Una sola configurazione di partenza che copre l'80% dei deploy. Tweak per workload specifici.
-
-```javascript
-const Koa  = require('koa');
-const pino = require('pino')({ level: 'info' });
-const path = require('path');
-const koaClassicServer = require('koa-classic-server');
-
-const app = new Koa();
-
-// 1) Host allowlist — mitiga DNS rebinding su esposizione LAN/loopback.
-const ALLOWED_HOSTS = new Set([
-  'app.example.com',
-  'localhost:3000',
-]);
-app.use(async (ctx, next) => {
-  if (!ALLOWED_HOSTS.has(ctx.host)) {
-    ctx.status = 421;
-    ctx.body = 'Misdirected Request';
-    return;
-  }
-  await next();
-});
-
-// 2) Security headers sui file utente (il middleware li imposta solo su
-//    listing/errori, NON sui file statici — by design).
-app.use(async (ctx, next) => {
-  ctx.set('X-Content-Type-Options',    'nosniff');
-  ctx.set('Referrer-Policy',           'strict-origin-when-cross-origin');
-  ctx.set('Strict-Transport-Security', 'max-age=63072000; includeSubDomains');
-  await next();
-});
-
-// 3) Il file server con default irrobustiti per produzione.
-app.use(koaClassicServer(path.join(__dirname, 'public'), {
-  method: ['GET', 'HEAD'],
-
-  index: ['index.html'],
-
-  dirListing: {
-    enabled:        process.env.NODE_ENV !== 'production',
-    maxEntries:     10000,                // più stretto del default 100000 anti-OOM
-    entriesPerPage: 100,
-  },
-
-  hidden: {
-    dotFiles: {
-      default:   'hidden',                // hardening esplicito vs default 'visible' filosofico
-      whitelist: ['.well-known'],         // ACME / Let's Encrypt
-    },
-    dotDirs: {
-      default:   'hidden',
-      whitelist: ['.well-known'],
-    },
-    alwaysHide: ['*.key', '*.pem', /^backup-/, /\.secret$/],
-  },
-
-  browserCacheEnabled: true,
-  browserCacheMaxAge:  86400,             // 24 h cache
-
-  logger: pino,                           // structured logging
-
-  urlsReserved: ['/api', '/admin'],       // route applicative gestite altrove
-}));
-
-app.listen(3000);
-```
-
-Per **user-uploads / multi-tenant**: oltre al blocco sopra, riduci `dirListing.maxEntries` a `1000` e monitora la dimensione della directory dall'esterno fino a quando v3.1 non aggiunge il `readMode: 'bounded'`.
-
----
-
-### 2. Performance
-
-#### Usa Variabili d'Ambiente
-```javascript
-const isProduction = process.env.NODE_ENV === 'production';
-
-app.use(koaClassicServer(rootDir, {
-  dirListing: { enabled: !isProduction },
-  method: ['GET', 'HEAD']
-}));
-```
-
-#### Middleware Logging Efficiente
-```javascript
-// Solo in development
-if (process.env.NODE_ENV !== 'production') {
-  app.use(async (ctx, next) => {
-    console.log(`${ctx.method} ${ctx.url}`);
-    await next();
-  });
-}
-```
-
-#### Cache Headers (middleware aggiuntivo)
-```javascript
-// Aggiungi cache headers per file statici
-app.use(async (ctx, next) => {
-  await next();
-  if (ctx.method === 'GET' && ctx.status === 200) {
-    ctx.set('Cache-Control', 'public, max-age=86400'); // 24h
-  }
-});
-
-app.use(koaClassicServer(rootDir));
-```
-
----
-
-### 3. Organizzazione Codice
-
-#### Separa Configurazione
-```javascript
-// config/fileServer.js
-const path = require('path');
-
-module.exports = {
-  rootDir: path.join(__dirname, '../public'),
-  options: {
-    method: ['GET', 'HEAD'],
-    dirListing: { enabled: true },
-    index: 'index.html',
-    urlPrefix: '/static',
-    urlsReserved: ['/admin', '/config']
-  }
-};
-
-// app.js
-const fileServerConfig = require('./config/fileServer');
-app.use(koaClassicServer(
-  fileServerConfig.rootDir,
-  fileServerConfig.options
-));
-```
-
-#### Template Rendering Modulare
-```javascript
-// lib/templateRenderer.js
-const ejs = require('ejs');
-
-module.exports = async function renderTemplate(ctx, next, filePath) {
-  try {
-    ctx.body = await ejs.renderFile(filePath, {
-      title: getPageTitle(filePath),
-      user: ctx.state.user,
-      ...ctx.state.templateData
-    });
-  } catch (error) {
-    console.error('Template error:', error);
-    ctx.status = 500;
-    ctx.body = 'Rendering Error';
-  }
-};
-
-function getPageTitle(filePath) {
-  // Logica per estrarre titolo
-  return 'My Page';
-}
-
-// app.js
-const templateRenderer = require('./lib/templateRenderer');
-
-app.use(koaClassicServer(rootDir, {
-  template: {
-    render: templateRenderer,
-    ext: ['ejs', 'html']
-  }
-}));
-```
-
----
-
-### 4. Error Handling
-
-#### Global Error Handler
-```javascript
-app.on('error', (err, ctx) => {
-  console.error('Server error:', {
-    error: err.message,
-    stack: err.stack,
-    url: ctx.url,
-    method: ctx.method,
-    ip: ctx.ip
-  });
-});
-```
-
-#### Try-Catch in Template Render
-```javascript
-template: {
-  render: async (ctx, next, filePath) => {
-    try {
-      ctx.body = await ejs.renderFile(filePath, data);
-    } catch (error) {
-      console.error('Render error:', error);
-      ctx.status = 500;
-      ctx.body = 'Template Error';
-    }
-  },
-  ext: ['ejs']
-}
-```
-
-#### 404 Fallback
-```javascript
-// Ultimo middleware
-app.use(async (ctx) => {
-  ctx.status = 404;
-  ctx.type = 'html';
-  ctx.body = `
-    <!DOCTYPE html>
-    <html>
-      <head><title>404</title></head>
-      <body>
-        <h1>Pagina Non Trovata</h1>
-        <p>La risorsa richiesta non esiste.</p>
-      </body>
-    </html>
-  `;
-});
-```
-
----
-
-### 5. Development vs Production
-
-```javascript
-const Koa = require('koa');
-const koaClassicServer = require('koa-classic-server');
-const path = require('path');
-
-const app = new Koa();
-const isDev = process.env.NODE_ENV !== 'production';
-
-// Logging solo in development
-if (isDev) {
-  app.use(async (ctx, next) => {
-    const start = Date.now();
-    await next();
-    console.log(`${ctx.method} ${ctx.url} - ${Date.now() - start}ms`);
-  });
-}
-
-// File server con configurazione ambiente-specifica
-app.use(koaClassicServer(path.join(__dirname, 'public'), {
-  dirListing: { enabled: isDev },  // Solo in dev
-  index: 'index.html',
-  urlPrefix: isDev ? '' : '/static',  // Prefix solo in prod
-  urlsReserved: ['/admin', '/config', '/.env'],
-  template: {
-    render: isDev ? devTemplateRender : prodTemplateRender,
-    ext: ['ejs']
-  }
-}));
-
-// Error details solo in development
-app.on('error', (err, ctx) => {
-  if (isDev) {
-    console.error('Error details:', err);
-  } else {
-    console.error('Error:', err.message);
-  }
-});
-
-app.listen(process.env.PORT || 3000);
-```
-
----
-
-### 6. Testing
-
-#### Testa Configurazioni Diverse
-```javascript
-// __tests__/server.test.js
-const configs = [
-  { name: 'base', options: {} },
-  { name: 'with-prefix', options: { urlPrefix: '/public' } },
-  { name: 'no-listing', options: { dirListing: { enabled: false } } }
-];
-
-configs.forEach(({ name, options }) => {
-  describe(`Config: ${name}`, () => {
-    let server;
-
-    beforeAll(() => {
-      const app = new Koa();
-      app.use(koaClassicServer(testDir, options));
-      server = app.listen();
-    });
-
-    test('serves files', async () => {
-      // test...
-    });
-
-    afterAll(() => server.close());
-  });
-});
-```
-
----
-
-### 7. Documentazione
-
-#### Commenta Configurazioni Complesse
-```javascript
-app.use(koaClassicServer(__dirname + '/public', {
-  // Mostra directory solo in development per sicurezza
-  dirListing: { enabled: process.env.NODE_ENV !== 'production' },
-
-  // Protegge configurazioni sensibili
-  // Nota: funziona solo per directory di primo livello
-  urlsReserved: ['/config', '/private'],
-
-  // Template EJS per pagine dinamiche
-  // Rendering con dati utente e query params
-  template: {
-    render: ejsRenderer,
-    ext: ['ejs']
-  }
-}));
-```
-
----
-
-## Informazioni Aggiuntive
-
-### Versione
-**2.4.0**
-
-### Autore
-**Italo Paesano**
-
-### Licenza
-**MIT**
-
-### Keywords
-- file
-- server
-- koa
-- middleware
-- static
-- apache
-
-### Compatibilità
-
-#### Node.js
-- **Minimo:** 12.20+
-- **Raccomandato:** 14+
-- **Testato:** 14, 16, 18, 20
-
-#### Koa
-- **Versione:** 2.x
-
-### Conditional Exports
-
-Il modulo usa conditional exports per supportare sia CommonJS che ES Modules:
-
-```json
-{
-  "main": "index.cjs",
-  "exports": {
-    "import": "./index.mjs",
-    "require": "./index.cjs"
-  }
-}
-```
-
-Questo permette:
-```javascript
-// CommonJS
-const koaClassicServer = require('koa-classic-server');
-
-// ES Modules
-import koaClassicServer from 'koa-classic-server';
-```
-
-### Repository
-
-Segnala bug o richiedi funzionalità tramite GitHub Issues.
-
-### Contributing
-
-Contributi benvenuti! Per favore:
-1. Fork del repository
-2. Crea branch per feature (`git checkout -b feature/AmazingFeature`)
-3. Commit modifiche (`git commit -m 'Add AmazingFeature'`)
-4. Push al branch (`git push origin feature/AmazingFeature`)
-5. Apri Pull Request
-
-### 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
-- Supporto conditional exports
-- Test suite completa
-
----
-
-## Risorse Aggiuntive
-
-### Link Utili
-
-- [Documentazione Koa](https://koajs.com/)
-- [MIME Types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
-- [Node.js Path Module](https://nodejs.org/api/path.html)
-- [EJS Documentation](https://ejs.co/)
-
-### Esempi Completi
-
-Repository con esempi completi disponibile nella cartella `customTest/` del progetto.
-
----
-
-**Documentazione generata per koa-classic-server v2.4.0**
-
-*Ultimo aggiornamento: 2026-02-28*