koa-classic-server 1.1.0 → 2.0.0

package/BENCHMARKS.md

@@ -0,0 +1,317 @@
+# 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)

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+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).
+
+## [1.2.0] - 2025-11-17
+
+### 🎉 SECURITY & BUG FIX RELEASE
+
+This release contains **critical security fixes** and important bug fixes. All users should upgrade immediately.
+
+### 🔒 Security Fixes (CRITICAL)
+
+#### Fixed Path Traversal Vulnerability
+- **Issue**: Attackers could access files outside the served directory using `../` sequences
+- **Impact**: CRITICAL - Unauthorized file access
+- **Fix**: Added path normalization and validation to ensure all file access stays within `rootDir`
+- **Code**: `index.cjs:106-124`
+
+#### Fixed Template Rendering Crash
+- **Issue**: Unhandled errors in template rendering could crash the entire server
+- **Impact**: CRITICAL - Denial of Service
+- **Fix**: Added try-catch around template render calls with proper error handling
+- **Code**: `index.cjs:195-205`
+
+### ✅ Bug Fixes
+
+#### Fixed HTTP Status Code 404
+- **Issue**: Missing files returned HTML "Not Found" with HTTP 200 status instead of 404
+- **Impact**: HIGH - Violates HTTP standards, affects SEO, breaks caching
+- **Fix**: Properly set `ctx.status = 404` when resources are not found
+- **Locations**:
+  - `index.cjs:130` - File/directory not found
+  - `index.cjs:158` - Directory listing disabled
+
+#### Fixed Race Condition in File Access
+- **Issue**: Files could be deleted between existence check and reading, causing uncaught errors
+- **Impact**: HIGH - Server crashes on file access errors
+- **Fix**: Added `fs.promises.access()` check before streaming files with error handling
+- **Code**: `index.cjs:208-216`
+
+#### Fixed File Extension Extraction
+- **Issue**: Using `split(".")` failed for:
+  - Files without extension (`README`)
+  - Hidden files (`.gitignore`)
+  - Paths with dots (`/folder.backup/file`)
+- **Impact**: HIGH - Template rendering activated incorrectly
+- **Fix**: Use `path.extname()` for robust extension extraction
+- **Code**: `index.cjs:192`
+
+#### Fixed Directory Read Errors
+- **Issue**: `fs.readdirSync()` could throw unhandled errors (permissions, deleted directories)
+- **Impact**: MEDIUM - Server crashes on directory access errors
+- **Fix**: Added try-catch with user-friendly error message
+- **Code**: `index.cjs:245-264`
+
+#### Fixed Content-Disposition Header
+- **Issue**: Filename in Content-Disposition header was not quoted and included full path
+- **Impact**: MEDIUM - Download issues with special characters in filenames
+- **Fix**:
+  - Use only basename (not full path)
+  - Quote filename and escape quotes
+- **Code**: `index.cjs:234-239`
+
+### 🎨 Improvements
+
+#### Added Input Validation
+- Validate `rootDir` is a non-empty string
+- Validate `rootDir` is an absolute path
+- Throw meaningful errors for invalid input
+
+#### Added XSS Protection
+- HTML-escape all user-controlled content in directory listings
+- Escapes filenames, paths, and MIME types
+- Prevents XSS attacks through malicious filenames
+
+#### Improved Error Messages
+- More descriptive error messages
+- Console logging for debugging
+- Stream error handling
+
+#### Code Quality
+- Fixed usage of `Array()` constructor to literal syntax `[]`
+- Better code organization and comments
+- Improved HTML output formatting
+
+### 📝 Added Files
+
+- **`__tests__/security.test.js`**: Comprehensive security and bug tests
+- **`DEBUG_REPORT.md`**: Detailed analysis of all bugs and fixes
+- **`DOCUMENTATION.md`**: Complete documentation (1500+ lines)
+- **`CHANGELOG.md`**: This file
+
+### 🧪 Testing
+
+- All 71 tests passing
+- Added security test suite
+- Path traversal tests
+- Template error handling tests
+- Status code validation tests
+- Race condition tests
+- Content-Disposition tests
+
+### 📦 Package Changes
+
+- **Version**: `1.1.0` → `1.2.0`
+- **Description**: Enhanced with security fixes
+- **Keywords**: Added `secure`, `middleware`, `file-server`, `directory-listing`
+- **Scripts**: Added `test:security` command
+
+### ⚠️ Breaking Changes
+
+**None** - This is a backwards-compatible release. However, behavior changes for security:
+
+1. **404 Status Codes**: Now properly returns 404 instead of 200 for missing resources
+2. **Path Traversal**: Requests with `../` now return 403 Forbidden instead of allowing access
+3. **Error Handling**: Template errors return 500 instead of crashing the server
+
+These changes fix bugs and security issues. The new behavior is correct and standards-compliant.
+
+### 🔄 Migration Guide
+
+No code changes required! Simply update:
+
+```bash
+npm update koa-classic-server
+```
+
+**Recommended**: Verify that:
+1. `rootDir` is an absolute path (e.g., `__dirname + '/public'`)
+2. Your error handling expects proper 404/403/500 status codes
+3. Your tests pass with the new behavior
+
+### 📊 Statistics
+
+- **Lines of code fixed**: ~200
+- **Security vulnerabilities fixed**: 2 critical
+- **Bugs fixed**: 6
+- **Tests added**: 12 security tests
+- **Documentation added**: 2000+ lines
+- **Test coverage**: 71 tests passing
+
+### 🙏 Credits
+
+- **Author**: Italo Paesano
+- **Security Audit**: Comprehensive code analysis
+- **Testing**: Jest & Supertest
+
+---
+
+## [1.1.0] - Previous Release
+
+### Features
+- Basic static file serving
+- Directory listing
+- Template engine support
+- URL prefixes
+- Reserved URLs
+
+### Known Issues (Fixed in 1.2.0)
+- Path traversal vulnerability ⚠️ CRITICAL
+- Missing 404 status codes
+- Unhandled template errors ⚠️ CRITICAL
+- Race condition in file access
+- Fragile file extension extraction
+- Missing error handling
+
+---
+
+## Links
+
+- [Full Documentation](./DOCUMENTATION.md)
+- [Debug Report](./DEBUG_REPORT.md)
+- [Repository](https://github.com/italopaesano/koa-classic-server)
+- [npm Package](https://www.npmjs.com/package/koa-classic-server)
+
+---
+
+**⚠️ Security Notice**: Version 1.2.0 fixes critical vulnerabilities. Update immediately if using 1.1.0 or earlier.

package/CREATE_RELEASE.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Script per creare la release v1.2.0
+
+echo "🏷️  Creazione Release v1.2.0..."
+
+# Assicurati di essere sul branch principale
+echo "📥 Fetch delle ultime modifiche..."
+git fetch origin
+
+# Checkout al branch principale (prova main, poi master)
+if git show-ref --verify --quiet refs/remotes/origin/main; then
+    echo "✅ Checkout a main..."
+    git checkout main
+    git pull origin main
+elif git show-ref --verify --quiet refs/remotes/origin/master; then
+    echo "✅ Checkout a master..."
+    git checkout master
+    git pull origin master
+else
+    echo "❌ Branch principale non trovato. Usa l'interfaccia GitHub."
+    exit 1
+fi
+
+# Crea il tag
+echo "🏷️  Creazione tag v1.2.0..."
+git tag -a v1.2.0 -m "Release v1.2.0 - Critical Security Update
+
+⚠️ CRITICAL SECURITY FIXES
+
+Security Fixes:
+- Fixed Path Traversal Vulnerability (CRITICAL)
+- Fixed Template Rendering Crash (CRITICAL)
+
+Bug Fixes:
+- HTTP Status Code 404 (HIGH)
+- Race Condition File Access (HIGH)
+- File Extension Extraction (HIGH)
+- Directory Read Errors (MEDIUM)
+- Content-Disposition Header (MEDIUM)
+- Code Quality & XSS Protection
+
+Statistics:
+- Security vulnerabilities: 2 critical fixed
+- Bugs fixed: 6
+- Tests: 71 passing
+- Documentation: 2000+ lines added"
+
+# Push del tag
+echo "📤 Push del tag a GitHub..."
+git push origin v1.2.0
+
+echo "✅ Tag creato! Ora vai su GitHub per creare la release:"
+echo "   https://github.com/italopaesano/koa-classic-server/releases/new?tag=v1.2.0"