koa-classic-server 3.0.0 → 3.1.0

package/docs/ACTION_PLAN.md

@@ -1,293 +0,0 @@
-# Piano d'Azione — koa-classic-server
-
-> Documento di lavoro per il miglioramento progressivo del progetto.
-> Ogni fase segue il ciclo: **Descrizione → Soluzioni proposte → Domande → Implementazione → Test → Avanzamento**
-
----
-
-## Indice delle fasi
-
-| # | Fase | Priorità | Stato |
-|---|------|----------|-------|
-| 1 | [File nascosti nel directory listing](#fase-1--file-nascosti-nel-directory-listing) | Alta | ⬜ Da fare |
-| 2 | [Opzione glob per escludere file sensibili](#fase-2--opzione-glob-per-escludere-file-sensibili) | Alta | ⬜ Da fare |
-| 3 | [Content-Security-Policy nell'HTML generato](#fase-3--content-security-policy-nellhtml-generato) | Media | ⬜ Da fare |
-| 4 | [Aggiunta ESLint e standardizzazione `===`](#fase-4--aggiunta-eslint-e-standardizzazione-) | Media | ⬜ Da fare |
-| 5 | [Range Requests HTTP 206](#fase-5--range-requests-http-206) | Media | ⬜ Da fare |
-| 6 | [Gzip / Brotli compression](#fase-6--gzip--brotli-compression) | Media | ⬜ Da fare |
-| 7 | [Traduzione commenti in inglese nei test](#fase-7--traduzione-commenti-in-inglese-nei-test) | Bassa | ⬜ Da fare |
-| 8 | [Roadmap rimozione opzioni deprecate (v3.0.0)](#fase-8--roadmap-rimozione-opzioni-deprecate-v300) | Bassa | ⬜ Da fare |
-
----
-
-> **Legenda stato:** ⬜ Da fare · 🔄 In corso · ✅ Completato · ⏸️ In pausa
-
----
-
-## Processo standard per ogni fase
-
-Per ogni fase si segue sempre questo ciclo:
-
-1. **Descrizione** — Spiegazione del problema e del suo impatto
-2. **Soluzioni proposte** — Almeno 2 alternative valutate con pro/contro
-3. **Domande** — Se le informazioni disponibili sono < 90%, si chiedono chiarimenti prima di procedere
-4. **Implementazione** — Modifica del codice sul branch `claude/project-review-EN6kt`
-5. **Test** — Esecuzione della suite di test e verifica regressioni
-6. **Avanzamento** — Aggiornamento dello stato in questo file e passaggio alla fase successiva
-
----
-
-## Fase 1 — File nascosti nel directory listing
-
-**Stato:** ⬜ Da fare
-**Priorità:** Alta
-**File coinvolti:** `index.cjs` (funzione `show_dir`)
-
-### Descrizione del problema
-
-Il directory listing mostra **tutti** i file e le cartelle presenti nella webroot, inclusi quelli che iniziano con `.` (dot files), come:
-
-- `.env` — variabili d'ambiente con credenziali
-- `.gitignore`, `.gitattributes` — metadati Git
-- `.htpasswd` — password Apache
-- `.DS_Store` — metadati macOS
-- `.npmrc` — configurazioni npm con token
-
-Server come Apache e Nginx nascondono questi file per default. Un file dimenticato nella webroot potrebbe esporre informazioni sensibili agli utenti del browser.
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 2 — Opzione glob per escludere file sensibili
-
-**Stato:** ⬜ Da fare
-**Priorità:** Alta
-**File coinvolti:** `index.cjs` (opzioni di configurazione + `show_dir`)
-
-### Descrizione del problema
-
-Non esiste un'opzione per escludere file o cartelle specifici dal serving e dal directory listing tramite pattern (glob o RegExp). Se un file come `config.json`, `secrets.yaml` o qualsiasi altro file sensibile si trova nella webroot, viene servito senza restrizioni.
-
-Esempi di pattern utili:
-- `*.env` — tutti i file .env
-- `**/*.secret` — file con estensione .secret
-- `private/**` — intera cartella private
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 3 — Content-Security-Policy nell'HTML generato
-
-**Stato:** ⬜ Da fare
-**Priorità:** Media
-**File coinvolti:** `index.cjs` (funzione `show_dir`)
-
-### Descrizione del problema
-
-Le pagine HTML generate dal directory listing non includono un header `Content-Security-Policy`. Senza CSP, il browser non ha indicazioni su quali risorse sono autorizzate, aumentando il rischio di attacchi XSS in caso di eventuali vulnerabilità future nel codice di generazione HTML.
-
-Il progetto già implementa l'escape HTML (funzione `escapeHtml`), ma aggiungere CSP è un ulteriore livello di difesa in profondità.
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 4 — Aggiunta ESLint e standardizzazione `===`
-
-**Stato:** ⬜ Da fare
-**Priorità:** Media
-**File coinvolti:** `index.cjs`, `package.json`, nuovi file di config
-
-### Descrizione del problema
-
-Il codice usa `==` (uguaglianza debole con coercizione di tipo) in circa 25 punti, documentati in `docs/CODE_REVIEW.md`. Anche se nel contesto attuale non causano bug, l'uso di `===` è la best practice JavaScript e previene errori sottili in futuro.
-
-Inoltre il progetto non ha alcun linter o formatter configurato, il che rende difficile mantenere la coerenza stilistica nel tempo e nelle contribuzioni esterne.
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 5 — Range Requests HTTP 206
-
-**Stato:** ⬜ Da fare
-**Priorità:** Media
-**File coinvolti:** `index.cjs` (logica di file serving)
-
-### Descrizione del problema
-
-Il middleware non supporta l'header `Range` delle richieste HTTP. Questo significa che:
-
-- File audio e video non possono essere riprodotti in streaming dai browser
-- Download di file grandi non possono essere ripresi dopo interruzione
-- Strumenti come `curl --range` non funzionano
-
-Il supporto HTTP 206 (Partial Content) è lo standard per la distribuzione di contenuti multimediali e file di grandi dimensioni.
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 6 — Gzip / Brotli compression
-
-**Stato:** ⬜ Da fare
-**Priorità:** Media
-**File coinvolti:** `index.cjs`, `package.json`
-
-### Descrizione del problema
-
-Il middleware serve tutti i file senza compressione. Per file di testo (HTML, CSS, JS, JSON, SVG), la compressione può ridurre le dimensioni del 60-80%, con impatto diretto su:
-
-- Velocità di caricamento per gli utenti
-- Consumo di banda del server
-- Score Lighthouse / Web Vitals
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 7 — Traduzione commenti in inglese nei test
-
-**Stato:** ⬜ Da fare
-**Priorità:** Bassa
-**File coinvolti:** `__tests__/dt-unknown.test.js` e altri
-
-### Descrizione del problema
-
-Alcuni file di test contengono commenti in italiano, il che riduce l'accessibilità del codice per i contribuenti internazionali. Per un progetto open source pubblicato su npm, la lingua standard della codebase dovrebbe essere l'inglese.
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-## Fase 8 — Roadmap rimozione opzioni deprecate (v3.0.0)
-
-**Stato:** ⬜ Da fare
-**Priorità:** Bassa
-**File coinvolti:** `index.cjs`, `docs/CHANGELOG.md`, `README.md`
-
-### Descrizione del problema
-
-Le opzioni legacy `cacheMaxAge` ed `enableCaching` sono ancora supportate con deprecation warning ma non hanno una data di rimozione pianificata. Mantenerle a tempo indeterminato appesantisce il codice e può confondere i nuovi utenti che leggono la documentazione.
-
-Una roadmap chiara verso `v3.0.0` con breaking changes definiti aiuta gli utenti a pianificare la migrazione.
-
-### Soluzioni proposte
-
-*Da definire nella sessione di lavoro dedicata a questa fase.*
-
-### Domande
-
-*Da porre prima dell'implementazione se necessario.*
-
-### Implementazione
-
-*Da eseguire dopo la scelta della soluzione.*
-
-### Test
-
-*Da verificare dopo l'implementazione.*
-
----
-
-*Documento aggiornato: 2026-03-21*

package/docs/BENCHMARKS.md

@@ -1,317 +0,0 @@
-# Performance Benchmarks
-
-This directory contains comprehensive performance benchmarks for `koa-classic-server`.
-
-## Purpose
-
-These benchmarks measure:
-- **Response times** for different file sizes
-- **Directory listing performance** for various sizes
-- **Concurrent request handling**
-- **Memory usage**
-- **Throughput** (requests/second, MB/second)
-
-## Quick Start
-
-### 1. Setup Benchmark Data
-
-First, create the test files and directories:
-
-```bash
-npm run benchmark:setup
-```
-
-This creates:
-- `benchmark-data/small-files/` - 100 files × 1KB
-- `benchmark-data/medium-files/` - 50 files × 100KB
-- `benchmark-data/large-files/` - 10 files × 1MB
-- `benchmark-data/large-directory/` - 1,000 files for listing test
-- `benchmark-data/very-large-directory/` - 10,000 files for stress test
-- `benchmark-data/nested/` - 5 levels deep directory structure
-
-Total: ~15 MB of test data
-
-### 2. Run Jest Performance Tests
-
-```bash
-npm run test:performance
-```
-
-This runs comprehensive tests measuring:
-- Individual file serving times
-- Directory listing times
-- Concurrent request handling
-- 404 error handling
-- Memory usage
-
-**Save results:**
-```bash
-npm run test:performance > results-baseline-v1.2.0.txt
-```
-
-### 3. Run HTTP Load Tests (autocannon)
-
-```bash
-npm run benchmark
-```
-
-This performs realistic load testing with:
-- 10 seconds per scenario
-- 5-10 concurrent connections
-- Measures requests/sec, latency, throughput
-
-**Save results for comparison:**
-```bash
-npm run benchmark:save baseline-v1.2.0.json
-```
-
-## Workflow: Before/After Optimization
-
-### Step 1: Baseline (BEFORE optimization)
-
-```bash
-# Setup test data
-npm run benchmark:setup
-
-# Run tests and save results
-npm run test:performance > results-before.txt
-npm run benchmark:save baseline-before.json
-```
-
-### Step 2: Apply Optimizations
-
-Make code changes to improve performance...
-
-### Step 3: Compare (AFTER optimization)
-
-```bash
-# Run tests again
-npm run test:performance > results-after.txt
-npm run benchmark:save baseline-after.json --compare baseline-before.json
-```
-
-### Step 4: Analyze Differences
-
-```bash
-# Compare test results
-diff results-before.txt results-after.txt
-
-# Benchmark comparison is shown automatically
-```
-
-## Expected Improvements
-
-After implementing the optimizations from `PERFORMANCE_ANALYSIS.md`:
-
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Small file (1KB) | ~2.5ms | ~0.5ms | **80% faster** |
-| Directory (1,000 files) | ~120ms | ~40ms | **67% faster** |
-| Directory (10,000 files) | ~1,800ms | ~450ms | **75% faster** |
-| Concurrent requests | Sequential | Parallel | **5-10x faster** |
-| Memory (10k directory) | ~25MB | ~15MB | **40% less** |
-
-With HTTP caching enabled:
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Cached file | 2.5ms | 0.1ms | **96% faster** |
-| Bandwidth | 100% | 5% | **95% reduction** |
-
-## Understanding the Results
-
-### Jest Performance Tests
-
-Output includes:
-- **Average time**: Mean across all iterations
-- **Median time**: 50th percentile (less affected by outliers)
-- **Min/Max time**: Range of values
-- **Warnings**: Areas where optimizations will have big impact
-
-Example output:
-```
-📊 Large Directory (1,000 files) Benchmark:
-   Average: 123.45ms
-   Median:  120.30ms
-   Min:     110.20ms
-   Max:     145.80ms
-   ⚠️  WARNING: This will be MUCH faster after async optimization
-```
-
-### Autocannon Load Tests
-
-Output includes:
-- **Requests/sec**: How many requests the server can handle per second
-- **Latency**: Response time (avg, p50, p99)
-- **Throughput**: Data transferred per second (MB/sec)
-
-Example output:
-```
-Scenario                          | Req/sec | Latency (avg) | Throughput
-----------------------------------|---------|---------------|-------------
-Small file (1KB)                  |    2500 |       4.00ms  |    2.44 MB/s
-Directory listing (1,000 files)   |      80 |     125.00ms  |   15.60 MB/s
-```
-
-Higher **Requests/sec** = Better ✅
-Lower **Latency** = Better ✅
-Higher **Throughput** = Better ✅
-
-## Interpreting Latency Percentiles
-
-- **p50 (median)**: 50% of requests complete in this time
-- **p75**: 75% of requests complete in this time
-- **p90**: 90% of requests complete in this time
-- **p99**: 99% of requests complete in this time
-- **p999**: 99.9% of requests complete in this time
-
-**Why p99 matters:**
-- p50 might be 10ms, but p99 could be 100ms
-- This means 1% of users experience 10× slower responses
-- Optimizations should improve both average AND p99
-
-## Memory Usage Tests
-
-Memory tests show:
-- **Heap used**: JavaScript objects, strings, arrays
-- **External**: Buffers, native objects
-- **Response size**: Size of HTML/data generated
-
-**What to look for:**
-- Large heap increase = memory leaks or inefficient allocation
-- After optimization: should see 30-40% reduction
-
-## Directory Structure
-
-```
-koa-classic-server/
-├── benchmark-data/           # Test data (git-ignored, ~15MB)
-│   ├── small-files/
-│   ├── medium-files/
-│   ├── large-files/
-│   ├── large-directory/
-│   └── very-large-directory/
-├── scripts/
-│   └── setup-benchmark.js    # Creates test data
-├── __tests__/
-│   └── performance.test.js   # Jest performance tests
-├── benchmark.js              # Autocannon load tests
-└── BENCHMARKS.md            # This file
-```
-
-## Troubleshooting
-
-### "Benchmark data not found"
-
-Run: `npm run benchmark:setup`
-
-### Tests timeout
-
-Increase Jest timeout in `performance.test.js`:
-```javascript
-test('...', async () => { ... }, 60000); // 60 seconds
-```
-
-### Out of memory
-
-Reduce iterations or skip very-large-directory tests:
-```javascript
-test.skip('Very large directory...', async () => { ... });
-```
-
-### Inconsistent results
-
-- Close other applications
-- Run multiple times and average results
-- Check system load: `top` or `htop`
-- Disable CPU throttling
-
-## Best Practices
-
-1. **Run on idle system**: Close browsers, apps
-2. **Run multiple times**: Results vary, average 3+ runs
-3. **Same environment**: Use same machine for before/after
-4. **Document environment**: Note CPU, RAM, Node version
-5. **Save results**: Use `> file.txt` to save for comparison
-
-## Example: Complete Before/After Test
-
-```bash
-# === BEFORE OPTIMIZATION ===
-
-# Setup
-npm run benchmark:setup
-
-# Jest tests
-npm run test:performance > results-v1.2.0-before.txt
-
-# Load tests
-npm run benchmark:save baseline-v1.2.0.json
-
-# === APPLY OPTIMIZATIONS ===
-# Edit index.cjs...
-
-# === AFTER OPTIMIZATION ===
-
-# Jest tests
-npm run test:performance > results-v1.3.0-after.txt
-
-# Load tests with comparison
-node benchmark.js --save baseline-v1.3.0.json --compare baseline-v1.2.0.json
-
-# Review differences
-diff results-v1.2.0-before.txt results-v1.3.0-after.txt
-```
-
-## Environment Information
-
-When reporting results, include:
-
-```bash
-node --version
-npm --version
-cat /proc/cpuinfo | grep "model name" | head -n 1
-free -h
-```
-
-Example:
-```
-Node.js: v20.10.0
-npm: 10.2.3
-CPU: Intel(R) Core(TM) i7-9750H @ 2.60GHz
-RAM: 16GB
-OS: Ubuntu 22.04 LTS
-```
-
-## Next Steps
-
-After running baseline benchmarks:
-
-1. Review `PERFORMANCE_ANALYSIS.md` for optimization recommendations
-2. Review `OPTIMIZATION_HTTP_CACHING.md` for HTTP caching details
-3. Implement Priority 1 optimizations:
-   - Convert sync operations to async
-   - Fix string concatenation in `show_dir()`
-   - Add HTTP caching headers
-4. Re-run benchmarks to measure improvements
-5. Update to v1.3.0 "Performance Edition"
-
-## Contributing
-
-When submitting performance improvements:
-
-1. Run baseline benchmarks BEFORE changes
-2. Apply your optimization
-3. Run benchmarks AFTER changes
-4. Include both results in PR
-5. Document the optimization approach
-
-## Resources
-
-- [autocannon documentation](https://github.com/mcollina/autocannon)
-- [Jest performance testing](https://jestjs.io/docs/timer-mocks)
-- [Node.js performance best practices](https://nodejs.org/en/docs/guides/simple-profiling/)
-
----
-
-**Last updated**: 2025-11-18
-**Version**: 1.2.0 (baseline)