koa-classic-server 2.1.2 → 2.1.4

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,98 @@
+# This workflow will run tests using node and then publish a package to npm when a release is published
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+# Prevent multiple concurrent publish workflows
+concurrency:
+  group: npm-publish-${{ github.ref }}
+  cancel-in-progress: false
+
+# Set permissions for the workflow
+permissions:
+  contents: read
+  id-token: write  # Required for npm provenance
+
+jobs:
+  build:
+    name: Build and Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build package
+        run: npm run build --if-present
+
+      - name: Cache build artifacts
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            node_modules
+            dist
+            build
+          key: build-${{ github.sha }}
+
+  publish-npm:
+    name: Publish to npm Registry
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+          cache: 'npm'
+
+      - name: Restore build artifacts
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            node_modules
+            dist
+            build
+          key: build-${{ github.sha }}
+
+      - name: Verify package version matches release tag
+        run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          RELEASE_TAG=${GITHUB_REF#refs/tags/}
+          # Remove 'v' prefix if present in tag
+          RELEASE_VERSION=${RELEASE_TAG#v}
+
+          echo "Package version: $PACKAGE_VERSION"
+          echo "Release version: $RELEASE_VERSION"
+
+          if [ "$PACKAGE_VERSION" != "$RELEASE_VERSION" ]; then
+            echo "Error: Package version ($PACKAGE_VERSION) does not match release tag ($RELEASE_VERSION)"
+            exit 1
+          fi
+
+      - name: Publish to npm with provenance
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -8,9 +8,15 @@
 
 ---
 
-## 🎉 Version 2.1.2 - Production Release
+## 🎉 Version 2.1.3 - Configuration Update
 
-Version 2.1.2 is a **major production release** featuring performance optimizations, enhanced directory listing, and critical bug fixes.
+Version 2.1.3 updates the default caching behavior for better development experience while maintaining production-ready performance.
+
+### What's New in 2.1.3
+
+✅ **Development-Friendly Defaults** - `enableCaching` now defaults to `false` for easier development
+✅ **Production Guidance** - Clear documentation on enabling caching for production environments
+✅ **Enhanced Documentation** - Comprehensive notes on caching configuration and recommendations
 
 ### What's New in 2.1.2
 
@@ -228,10 +234,14 @@ app.use(koaClassicServer(__dirname + '/public', {
 }));
 ```
 
-**Benefits:**
+**⚠️ Important: Production Recommendation**
+
+The default value for `enableCaching` is `false` to facilitate development (where you want changes to be immediately visible). **For production environments, it is strongly recommended to set `enableCaching: true`** to benefit from:
+
 - 80-95% bandwidth reduction
 - 304 Not Modified responses for unchanged files
 - Faster page loads for returning visitors
+- Reduced server load
 
 **See details:** [HTTP Caching Optimization →](./docs/OPTIMIZATION_HTTP_CACHING.md)
 
@@ -357,7 +367,8 @@ Creates a Koa middleware for serving static files.
   },
 
   // HTTP caching configuration
-  enableCaching: true,      // Enable ETag & Last-Modified (default: true)
+  // NOTE: Default is false for development. Set to true in production for better performance!
+  enableCaching: false,     // Enable ETag & Last-Modified (default: false)
   cacheMaxAge: 3600,        // Cache-Control max-age in seconds (default: 3600 = 1 hour)
 }
 ```
@@ -373,7 +384,7 @@ Creates a Koa middleware for serving static files.
 | `urlsReserved` | Array | `[]` | Reserved directory paths (first-level only) |
 | `template.render` | Function | `undefined` | Template rendering function |
 | `template.ext` | Array | `[]` | Extensions for template rendering |
-| `enableCaching` | Boolean | `true` | Enable HTTP caching headers |
+| `enableCaching` | Boolean | `false` | Enable HTTP caching headers (recommended: `true` in production) |
 | `cacheMaxAge` | Number | `3600` | Cache duration in seconds |
 
 ---

package/__tests__/caching-headers.test.js

@@ -0,0 +1,556 @@
+/**
+ * HTTP Caching Headers Test
+ *
+ * Tests to verify correct caching behavior:
+ * - When enableCaching: true -> proper cache headers
+ * - When enableCaching: false -> anti-cache headers
+ */
+
+const Koa = require('koa');
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const path = require('path');
+const fs = require('fs');
+
+const TEST_DIR = path.join(__dirname, 'test-caching-headers');
+
+describe('HTTP Caching Headers', () => {
+    beforeAll(() => {
+        // Create test directory and file
+        if (!fs.existsSync(TEST_DIR)) {
+            fs.mkdirSync(TEST_DIR, { recursive: true });
+        }
+        fs.writeFileSync(path.join(TEST_DIR, 'test.txt'), 'Test content for caching');
+    });
+
+    afterAll(() => {
+        // Cleanup
+        if (fs.existsSync(TEST_DIR)) {
+            fs.rmSync(TEST_DIR, { recursive: true, force: true });
+        }
+    });
+
+    describe('When caching is DISABLED (enableCaching: false)', () => {
+        let app;
+        let server;
+        let request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: false
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('Should return anti-cache headers', async () => {
+            const res = await request.get('/test.txt');
+
+            expect(res.status).toBe(200);
+
+            // Verify anti-cache headers are present
+            expect(res.headers['cache-control']).toBe('no-cache, no-store, must-revalidate');
+            expect(res.headers['pragma']).toBe('no-cache');
+            expect(res.headers['expires']).toBe('0');
+
+            // Verify caching headers are NOT present
+            expect(res.headers['etag']).toBeUndefined();
+            expect(res.headers['last-modified']).toBeUndefined();
+        });
+
+        test('Should NOT return 304 even with If-None-Match header', async () => {
+            // First request to get potential ETag (should not exist)
+            const res1 = await request.get('/test.txt');
+            expect(res1.status).toBe(200);
+
+            // Second request with If-None-Match (should still return 200)
+            const res2 = await request
+                .get('/test.txt')
+                .set('If-None-Match', '"fake-etag"');
+
+            expect(res2.status).toBe(200);
+            expect(res2.text).toBe('Test content for caching');
+        });
+
+        test('Should NOT return 304 even with If-Modified-Since header', async () => {
+            const futureDate = new Date(Date.now() + 86400000).toUTCString();
+
+            const res = await request
+                .get('/test.txt')
+                .set('If-Modified-Since', futureDate);
+
+            expect(res.status).toBe(200);
+            expect(res.text).toBe('Test content for caching');
+        });
+    });
+
+    describe('When caching is ENABLED (enableCaching: true)', () => {
+        let app;
+        let server;
+        let request;
+
+        beforeAll(() => {
+            app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true,
+                cacheMaxAge: 3600
+            }));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('Should return proper cache headers', async () => {
+            const res = await request.get('/test.txt');
+
+            expect(res.status).toBe(200);
+
+            // Verify cache headers are present
+            expect(res.headers['cache-control']).toBe('public, max-age=3600, must-revalidate');
+            expect(res.headers['etag']).toBeDefined();
+            expect(res.headers['last-modified']).toBeDefined();
+
+            // Verify anti-cache headers are NOT present
+            expect(res.headers['pragma']).toBeUndefined();
+            expect(res.headers['expires']).not.toBe('0');
+        });
+
+        test('Should return 304 with matching ETag', async () => {
+            // First request to get ETag
+            const res1 = await request.get('/test.txt');
+            expect(res1.status).toBe(200);
+            const etag = res1.headers['etag'];
+            expect(etag).toBeDefined();
+
+            // Second request with If-None-Match
+            const res2 = await request
+                .get('/test.txt')
+                .set('If-None-Match', etag);
+
+            expect(res2.status).toBe(304);
+            expect(res2.text).toBe('');
+        });
+
+        test('Should return 304 with If-Modified-Since (not modified)', async () => {
+            // Get file stats and add 1 second to ensure it's after file mtime
+            const stats = fs.statSync(path.join(TEST_DIR, 'test.txt'));
+            const futureDate = new Date(stats.mtime.getTime() + 1000).toUTCString();
+
+            // Request with If-Modified-Since header (1 second in future)
+            const res = await request
+                .get('/test.txt')
+                .set('If-Modified-Since', futureDate);
+
+            expect(res.status).toBe(304);
+            expect(res.text).toBe('');
+        });
+
+        test('Should return 200 with If-Modified-Since (file modified)', async () => {
+            // Use a date in the past
+            const pastDate = new Date(Date.now() - 86400000).toUTCString();
+
+            const res = await request
+                .get('/test.txt')
+                .set('If-Modified-Since', pastDate);
+
+            expect(res.status).toBe(200);
+            expect(res.text).toBe('Test content for caching');
+        });
+    });
+
+    describe('Default behavior (caching disabled by default)', () => {
+        let app;
+        let server;
+        let request;
+
+        beforeAll(() => {
+            app = new Koa();
+            // No options provided - should default to enableCaching: false
+            app.use(koaClassicServer(TEST_DIR));
+            server = app.listen();
+            request = supertest(server);
+        });
+
+        afterAll(() => {
+            server.close();
+        });
+
+        test('Should have anti-cache headers by default', async () => {
+            const res = await request.get('/test.txt');
+
+            expect(res.status).toBe(200);
+            expect(res.headers['cache-control']).toBe('no-cache, no-store, must-revalidate');
+            expect(res.headers['pragma']).toBe('no-cache');
+            expect(res.headers['expires']).toBe('0');
+        });
+    });
+
+    describe('Custom cacheMaxAge values', () => {
+        test('Should respect custom cacheMaxAge: 7200', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true,
+                cacheMaxAge: 7200
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.txt');
+
+            expect(res.status).toBe(200);
+            expect(res.headers['cache-control']).toBe('public, max-age=7200, must-revalidate');
+
+            server.close();
+        });
+
+        test('Should respect custom cacheMaxAge: 0 (no browser cache)', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true,
+                cacheMaxAge: 0
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.txt');
+
+            expect(res.status).toBe(200);
+            expect(res.headers['cache-control']).toBe('public, max-age=0, must-revalidate');
+            // Should still have ETag for validation
+            expect(res.headers['etag']).toBeDefined();
+
+            server.close();
+        });
+
+        test('Should respect custom cacheMaxAge: 86400 (1 day)', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true,
+                cacheMaxAge: 86400
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.txt');
+
+            expect(res.status).toBe(200);
+            expect(res.headers['cache-control']).toBe('public, max-age=86400, must-revalidate');
+
+            server.close();
+        });
+    });
+
+    describe('ETag generation and validation', () => {
+        test('ETag should change when file is modified', async () => {
+            const testFile = path.join(TEST_DIR, 'dynamic-test.txt');
+            fs.writeFileSync(testFile, 'Original content');
+
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            // First request
+            const res1 = await request.get('/dynamic-test.txt');
+            expect(res1.status).toBe(200);
+            const etag1 = res1.headers['etag'];
+            expect(etag1).toBeDefined();
+
+            // Wait 10ms to ensure different mtime
+            await new Promise(resolve => setTimeout(resolve, 10));
+
+            // Modify file
+            fs.writeFileSync(testFile, 'Modified content - different');
+
+            // Second request - ETag should be different
+            const res2 = await request.get('/dynamic-test.txt');
+            expect(res2.status).toBe(200);
+            const etag2 = res2.headers['etag'];
+            expect(etag2).toBeDefined();
+            expect(etag2).not.toBe(etag1);
+
+            // Cleanup
+            fs.unlinkSync(testFile);
+            server.close();
+        });
+
+        test('ETag should change when file size changes', async () => {
+            const testFile = path.join(TEST_DIR, 'size-test.txt');
+            fs.writeFileSync(testFile, 'Short');
+
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            // First request
+            const res1 = await request.get('/size-test.txt');
+            const etag1 = res1.headers['etag'];
+
+            // Wait and change file size
+            await new Promise(resolve => setTimeout(resolve, 10));
+            fs.writeFileSync(testFile, 'Much longer content here');
+
+            // Second request
+            const res2 = await request.get('/size-test.txt');
+            const etag2 = res2.headers['etag'];
+
+            expect(etag2).not.toBe(etag1);
+
+            fs.unlinkSync(testFile);
+            server.close();
+        });
+    });
+
+    describe('Bandwidth savings with 304 responses', () => {
+        test('304 response should have no body', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            // First request
+            const res1 = await request.get('/test.txt');
+            expect(res1.status).toBe(200);
+            expect(res1.text).toBe('Test content for caching');
+            const bodySize1 = res1.text.length;
+
+            // Second request with ETag
+            const res2 = await request
+                .get('/test.txt')
+                .set('If-None-Match', res1.headers['etag']);
+
+            expect(res2.status).toBe(304);
+            expect(res2.text).toBe('');
+            expect(res2.text.length).toBe(0);
+
+            // Verify bandwidth saving
+            expect(bodySize1).toBeGreaterThan(0);
+            expect(res2.text.length).toBe(0);
+
+            server.close();
+        });
+
+        test('Should save bandwidth on multiple 304 responses', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            // First request
+            const res1 = await request.get('/test.txt');
+            const etag = res1.headers['etag'];
+            const originalSize = res1.text.length;
+
+            // Make 10 cached requests
+            let totalBytesSaved = 0;
+            for (let i = 0; i < 10; i++) {
+                const res = await request
+                    .get('/test.txt')
+                    .set('If-None-Match', etag);
+
+                expect(res.status).toBe(304);
+                totalBytesSaved += originalSize;
+            }
+
+            expect(totalBytesSaved).toBeGreaterThan(0);
+
+            server.close();
+        });
+    });
+
+    describe('Caching with different MIME types', () => {
+        beforeAll(() => {
+            // Create files with different types
+            fs.writeFileSync(path.join(TEST_DIR, 'test.html'), '<html><body>Test</body></html>');
+            fs.writeFileSync(path.join(TEST_DIR, 'test.json'), '{"test": "data"}');
+            fs.writeFileSync(path.join(TEST_DIR, 'test.css'), 'body { color: red; }');
+            fs.writeFileSync(path.join(TEST_DIR, 'test.js'), 'console.log("test");');
+        });
+
+        afterAll(() => {
+            fs.unlinkSync(path.join(TEST_DIR, 'test.html'));
+            fs.unlinkSync(path.join(TEST_DIR, 'test.json'));
+            fs.unlinkSync(path.join(TEST_DIR, 'test.css'));
+            fs.unlinkSync(path.join(TEST_DIR, 'test.js'));
+        });
+
+        test('HTML files should have cache headers', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.html');
+            expect(res.status).toBe(200);
+            expect(res.headers['etag']).toBeDefined();
+            expect(res.headers['cache-control']).toContain('public');
+            expect(res.headers['content-type']).toContain('text/html');
+
+            server.close();
+        });
+
+        test('JSON files should have cache headers', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.json');
+            expect(res.status).toBe(200);
+            expect(res.headers['etag']).toBeDefined();
+            expect(res.headers['content-type']).toContain('application/json');
+
+            server.close();
+        });
+
+        test('CSS files should have cache headers', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.css');
+            expect(res.status).toBe(200);
+            expect(res.headers['etag']).toBeDefined();
+            expect(res.headers['content-type']).toContain('text/css');
+
+            server.close();
+        });
+
+        test('JavaScript files should have cache headers', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test.js');
+            expect(res.status).toBe(200);
+            expect(res.headers['etag']).toBeDefined();
+            expect(res.headers['content-type']).toContain('javascript');
+
+            server.close();
+        });
+    });
+
+    describe('Caching does not interfere with template rendering', () => {
+        test('Template files should not get cache headers during rendering', async () => {
+            const testFile = path.join(TEST_DIR, 'test-template.ejs');
+            fs.writeFileSync(testFile, '<html><body><%= name %></body></html>');
+
+            let renderCalled = false;
+
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true,
+                cacheMaxAge: 3600,
+                template: {
+                    ext: ['ejs'],
+                    render: async (ctx, next, filePath) => {
+                        renderCalled = true;
+                        ctx.body = '<html><body>Rendered</body></html>';
+                        ctx.type = 'text/html';
+                    }
+                }
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            const res = await request.get('/test-template.ejs');
+
+            expect(res.status).toBe(200);
+            expect(renderCalled).toBe(true);
+            expect(res.text).toBe('<html><body>Rendered</body></html>');
+
+            // Template rendering happens before caching logic,
+            // so cache headers should not be added by koaClassicServer
+            // (the template renderer controls caching)
+
+            fs.unlinkSync(testFile);
+            server.close();
+        });
+    });
+
+    describe('Concurrent requests with caching', () => {
+        test('Multiple concurrent requests should handle caching correctly', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            // Make 5 concurrent requests
+            const promises = Array.from({ length: 5 }, () =>
+                request.get('/test.txt')
+            );
+
+            const results = await Promise.all(promises);
+
+            // All should succeed
+            results.forEach(res => {
+                expect(res.status).toBe(200);
+                expect(res.headers['etag']).toBeDefined();
+            });
+
+            // All ETags should be identical (same file)
+            const etags = results.map(r => r.headers['etag']);
+            const uniqueEtags = new Set(etags);
+            expect(uniqueEtags.size).toBe(1);
+
+            server.close();
+        });
+
+        test('Concurrent 304 responses should work correctly', async () => {
+            const app = new Koa();
+            app.use(koaClassicServer(TEST_DIR, {
+                enableCaching: true
+            }));
+            const server = app.listen();
+            const request = supertest(server);
+
+            // First request to get ETag
+            const initial = await request.get('/test.txt');
+            const etag = initial.headers['etag'];
+
+            // Make 5 concurrent cached requests
+            const promises = Array.from({ length: 5 }, () =>
+                request.get('/test.txt').set('If-None-Match', etag)
+            );
+
+            const results = await Promise.all(promises);
+
+            // All should return 304
+            results.forEach(res => {
+                expect(res.status).toBe(304);
+                expect(res.text).toBe('');
+            });
+
+            server.close();
+        });
+    });
+});

package/docs/CHANGELOG.md

@@ -5,6 +5,84 @@ 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.1.3] - 2025-11-25
+
+### 🔧 Configuration Changes
+
+#### Changed Default Caching Behavior
+- **Change**: `enableCaching` default value changed from `true` to `false`
+- **Rationale**: Better development experience - changes are immediately visible without cache invalidation
+- **Production Impact**: **Users should explicitly set `enableCaching: true` in production environments**
+- **Benefits in Production**:
+  - 80-95% bandwidth reduction
+  - Faster page loads with 304 Not Modified responses
+  - Reduced server load
+- **Code**: `index.cjs:107`
+
+### 📝 Documentation Improvements
+
+#### Enhanced Caching Documentation
+- Added comprehensive production recommendations in README.md
+- Added inline code comments explaining the default behavior
+- Clear guidance on when to enable caching (development vs production)
+- **Files**: `README.md`, `index.cjs`
+
+### ⚠️ Migration Notice
+
+**IMPORTANT**: If you are upgrading from 2.1.2 or earlier and rely on HTTP caching:
+
+```javascript
+// You must now explicitly enable caching in production
+app.use(koaClassicServer(__dirname + '/public', {
+  enableCaching: true  // ← Add this for production environments
+}));
+```
+
+**Development**: No changes needed - the new default (`false`) is better for development.
+
+**Production**: Explicitly set `enableCaching: true` to maintain previous behavior and performance benefits.
+
+### 📦 Package Changes
+
+- **Version**: `2.1.2` → `2.1.3`
+
+---
+
+## [2.1.2] - 2025-11-24
+
+### 🎨 Features
+
+#### Sortable Directory Columns
+- Apache2-like directory listing with clickable column headers
+- Sort by Name, Type, or Size (ascending/descending)
+- Fixed navigation bug after sorting
+
+#### File Size Display
+- Human-readable file sizes (B, KB, MB, GB, TB)
+- Proper formatting and precision
+
+#### HTTP Caching
+- ETag and Last-Modified headers
+- 304 Not Modified responses
+- 80-95% bandwidth reduction
+
+### 🧪 Testing
+- 153 tests passing
+- Comprehensive test coverage
+
+---
+
+## [2.1.1] - 2025-11-23
+
+### 🚀 Production Release
+
+- Async/await implementation
+- Non-blocking I/O
+- Performance optimizations
+- Flow documentation
+
+---
+
 ## [1.2.0] - 2025-11-17
 
 ### 🎉 SECURITY & BUG FIX RELEASE

package/index.cjs

@@ -45,7 +45,10 @@ module.exports = function koaClassicServer(
             ext: [], // File extensions to process with template.render
         },
         cacheMaxAge: 3600, // Cache-Control max-age in seconds (default: 1 hour)
-        enableCaching: true, // Enable HTTP caching headers (ETag, Last-Modified)
+        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.
     }
     */
 ) {
@@ -97,8 +100,11 @@ 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.
+    // 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 : true;
+    options.enableCaching = typeof options.enableCaching === 'boolean' ? options.enableCaching : false;
 
     return async (ctx, next) => {
         // Check if method is allowed
@@ -347,6 +353,12 @@ module.exports = function koaClassicServer(
                         return;
                     }
                 }
+            } else {
+                // BUGFIX: When caching is disabled, explicitly prevent browser caching
+                // Without these headers, browsers may use heuristic caching and serve stale content
+                ctx.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+                ctx.set('Pragma', 'no-cache'); // HTTP 1.0 compatibility
+                ctx.set('Expires', '0'); // Proxies
             }
 
             // Verify file is still readable (race condition protection)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "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": {
@@ -29,6 +29,10 @@
   ],
   "author": "Italo Paesano",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/italopaesano/koa-classic-server"
+  },
   "dependencies": {
     "mime-types": "^2.1.35"
   },