koa-classic-server 2.6.1 → 3.0.0

package/__tests__/compression.test.js

@@ -0,0 +1,284 @@
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+const Koa = require('koa');
+const path = require('path');
+
+const root = path.join(__dirname, 'compression-fixtures');
+
+// Fixtures:
+//   large.txt  — 2000 bytes of 'A' (text/plain, exceeds 1KB threshold)
+//   small.txt  — 4 bytes of 'tiny' (text/plain, below 1KB threshold)
+//   data.json  — 16 bytes '{"key":"value"}\n' (application/json, below threshold)
+
+function createApp(opts = {}) {
+    const app = new Koa();
+    app.use(koaClassicServer(root, { dirListing: { enabled: false }, ...opts }));
+    return app.listen();
+}
+
+// ─── Default behaviour (compression enabled, serverCache enabled) ─────────────
+
+describe('Compression — default: br preferred', () => {
+    let server;
+    beforeAll(() => { server = createApp(); });
+    afterAll(() => server.close());
+
+    test('large.txt with Accept-Encoding: br → brotli compressed', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br');
+        expect(res.status).toBe(200);
+        expect(res.headers['content-encoding']).toBe('br');
+        expect(res.headers['vary']).toBe('Accept-Encoding');
+    });
+
+    test('large.txt with Accept-Encoding: gzip → gzip compressed, body decompressed by supertest', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.status).toBe(200);
+        expect(res.headers['content-encoding']).toBe('gzip');
+        expect(res.headers['vary']).toBe('Accept-Encoding');
+        // supertest auto-decompresses gzip — res.text is the original content
+        expect(res.text).toBe('A'.repeat(2000));
+    });
+
+    test('large.txt with Accept-Encoding: br,gzip → br preferred (higher priority)', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br, gzip');
+        expect(res.headers['content-encoding']).toBe('br');
+    });
+
+    // Use 'identity' to prevent supertest's default Accept-Encoding from triggering compression
+    test('large.txt with Accept-Encoding: identity → uncompressed', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.headers['content-encoding']).toBeUndefined();
+        expect(res.headers['vary']).toBeUndefined();
+        expect(res.text).toBe('A'.repeat(2000));
+    });
+
+    test('Content-Length present on compressed response (serverCache)', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.headers['content-length']).toBeDefined();
+        expect(Number(res.headers['content-length'])).toBeGreaterThan(0);
+    });
+
+    test('Compressed Content-Length is smaller than original file size', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(Number(res.headers['content-length'])).toBeLessThan(2000);
+    });
+});
+
+// ─── Threshold: files below threshold are served uncompressed ────────────────
+
+describe('Compression — threshold (default 1024 bytes)', () => {
+    let server;
+    beforeAll(() => { server = createApp(); });
+    afterAll(() => server.close());
+
+    test('small.txt (4 bytes) below threshold → no compression', async () => {
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'br, gzip');
+        expect(res.status).toBe(200);
+        expect(res.headers['content-encoding']).toBeUndefined();
+        expect(res.text).toBe('tiny');
+    });
+
+    test('large.txt (2000 bytes) above threshold → compressed', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.headers['content-encoding']).toBe('gzip');
+    });
+
+    test('minFileSize: false → compress regardless of size', async () => {
+        const s = createApp({ compression: { minFileSize: false } });
+        const res = await supertest(s)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'gzip');
+        s.close();
+        expect(res.headers['content-encoding']).toBe('gzip');
+        // supertest auto-decompresses gzip
+        expect(res.text).toBe('tiny');
+    });
+});
+
+// ─── compression: false shorthand ────────────────────────────────────────────
+
+describe('Compression — disabled', () => {
+    let server;
+    beforeAll(() => { server = createApp({ compression: false }); });
+    afterAll(() => server.close());
+
+    test('compression: false → no compression on any file', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br, gzip');
+        expect(res.status).toBe(200);
+        expect(res.headers['content-encoding']).toBeUndefined();
+        expect(res.text).toBe('A'.repeat(2000));
+    });
+});
+
+// ─── encodings configuration ──────────────────────────────────────────────────
+
+describe('Compression — encodings configuration', () => {
+    test('encodings: [gzip] → no brotli even if client prefers br', async () => {
+        const s = createApp({ compression: { encodings: ['gzip'] } });
+        const res = await supertest(s)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br, gzip');
+        s.close();
+        expect(res.headers['content-encoding']).toBe('gzip');
+    });
+
+    test('encodings: [] → no compression', async () => {
+        const s = createApp({ compression: { encodings: [] } });
+        const res = await supertest(s)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br, gzip');
+        s.close();
+        expect(res.headers['content-encoding']).toBeUndefined();
+    });
+});
+
+// ─── mimeTypes configuration ──────────────────────────────────────────────────
+
+describe('Compression — mimeTypes configuration', () => {
+    test('custom mimeTypes replaces default list', async () => {
+        // Only compress application/json; text/plain should not be compressed
+        const s = createApp({ compression: { mimeTypes: ['application/json'], threshold: false } });
+
+        const resTxt = await supertest(s)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(resTxt.headers['content-encoding']).toBeUndefined();
+
+        s.close();
+    });
+});
+
+// ─── ETag encoding-specific ───────────────────────────────────────────────────
+
+describe('Compression — encoding-specific ETag', () => {
+    let server;
+    beforeAll(() => { server = createApp({ browserCacheEnabled: true }); });
+    afterAll(() => server.close());
+
+    test('ETag for br response has -br suffix', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br');
+        expect(res.headers['etag']).toMatch(/-br"$/);
+    });
+
+    test('ETag for gzip response has -gz suffix', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.headers['etag']).toMatch(/-gz"$/);
+    });
+
+    test('ETag for uncompressed response has no suffix', async () => {
+        // Use 'identity' to prevent supertest's default Accept-Encoding from triggering compression
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.headers['etag']).not.toMatch(/-(br|gz)"$/);
+    });
+
+    test('304 returned when If-None-Match matches encoding-specific ETag', async () => {
+        const first = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        const etag = first.headers['etag'];
+
+        const second = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip')
+            .set('If-None-Match', etag);
+        expect(second.status).toBe(304);
+    });
+
+    test('304 NOT returned when ETag suffix differs (br ETag sent with gzip request)', async () => {
+        const brRes = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'br');
+        const brEtag = brRes.headers['etag'];
+
+        // Send the br ETag but request gzip → ETag mismatch → 200
+        const gzipRes = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip')
+            .set('If-None-Match', brEtag);
+        expect(gzipRes.status).toBe(200);
+    });
+});
+
+// ─── serverCache.compressedFile disabled (streaming mode) ────────────────────
+
+describe('Compression — serverCache.compressedFile disabled (streaming)', () => {
+    let server;
+    beforeAll(() => {
+        server = createApp({ serverCache: { compressedFile: { enabled: false } } });
+    });
+    afterAll(() => server.close());
+
+    test('streaming: Content-Encoding set but no Content-Length', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.headers['content-encoding']).toBe('gzip');
+        // Streaming compressed responses use Transfer-Encoding: chunked → no Content-Length
+        expect(res.headers['content-length']).toBeUndefined();
+    });
+
+    test('streaming: response body is correctly decompressed', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        // supertest auto-decompresses gzip — res.text is the original content
+        expect(res.text).toBe('A'.repeat(2000));
+    });
+});
+
+// ─── Compression does not apply to Range requests ────────────────────────────
+
+describe('Compression — no compression on Range requests (HTTP 206)', () => {
+    let server;
+    beforeAll(() => { server = createApp(); });
+    afterAll(() => server.close());
+
+    test('Range request is served uncompressed even with Accept-Encoding', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Range', 'bytes=0-9')
+            .set('Accept-Encoding', 'br, gzip');
+        expect(res.status).toBe(206);
+        expect(res.headers['content-encoding']).toBeUndefined();
+        expect(res.text).toBe('A'.repeat(10));
+    });
+});
+
+// ─── V3 migration guard ───────────────────────────────────────────────────────
+
+describe('Compression — V3 migration guard (old name throws helpful error)', () => {
+    test('compression.minSize throws with hint pointing to minFileSize', () => {
+        expect(() => koaClassicServer(root, { compression: { minSize: 2048 } }))
+            .toThrow(/options\.compression\.minSize was renamed[\s\S]*compression: \{ minFileSize: 2048 \}/);
+    });
+
+    test('compression.minSize === false also throws (legacy "no minimum" sentinel)', () => {
+        expect(() => koaClassicServer(root, { compression: { minSize: false } }))
+            .toThrow(/options\.compression\.minSize was renamed/);
+    });
+});

package/__tests__/customTest/serversToLoad.util.js

@@ -20,7 +20,7 @@ const configurations = [
     options: {
       //urlPrefix: '/',
       method: ['GET'],
-      showDirContents: true,
+      dirListing: { enabled: true },
     },
   },
   {
@@ -31,8 +31,8 @@ const configurations = [
     options: {
       urlPrefix: '/public',
       method: ['GET'],
-      showDirContents: true,
-      index: 'index.html',
+      dirListing: { enabled: true },
+      index: ['index.html'],
     },
   },
   {
@@ -43,7 +43,7 @@ const configurations = [
     options: {
       urlPrefix: '/public',
       method: ['GET'],
-      showDirContents: true,
+      dirListing: { enabled: true },
     },
   },
   {
@@ -54,7 +54,7 @@ const configurations = [
     options: {
       urlPrefix: '',
       method: ['GET'],
-      showDirContents: true,
+      dirListing: { enabled: true },
       urlsReserved : Array('/percorso_riservato', '/percorso riservato con spazi')
     },
   },

package/__tests__/demo-regex-index.js

@@ -48,7 +48,7 @@ console.log('  Aspettativa: Matcha INDEX.HTML o Index.Html');
 const app1 = new Koa();
 app1.use(koaClassicServer(testDir, {
     index: [/index\.html/i],
-    showDirContents: true
+    dirListing: { enabled: true }
 }));
 const server1 = app1.listen(3001);
 console.log('  ✓ Server avviato su http://localhost:3001\n');
@@ -63,7 +63,7 @@ console.log('  Aspettativa: Matcha INDEX.HTML, Index.Html, index.htm');
 const app2 = new Koa();
 app2.use(koaClassicServer(testDir, {
     index: [/index\.(html|htm)/i],
-    showDirContents: true
+    dirListing: { enabled: true }
 }));
 const server2 = app2.listen(3002);
 console.log('  ✓ Server avviato su http://localhost:3002\n');
@@ -81,7 +81,7 @@ app3.use(koaClassicServer(testDir, {
         /index\.(html|htm)/i,
         /default\.html/i
     ],
-    showDirContents: true
+    dirListing: { enabled: true }
 }));
 const server3 = app3.listen(3003);
 console.log('  ✓ Server avviato su http://localhost:3003\n');
@@ -100,7 +100,7 @@ app4.use(koaClassicServer(testDir, {
         /INDEX\.HTML/i,     // Case-insensitive fallback
         /default\.html/i    // Default fallback
     ],
-    showDirContents: true
+    dirListing: { enabled: true }
 }));
 const server4 = app4.listen(3004);
 console.log('  ✓ Server avviato su http://localhost:3004\n');

package/__tests__/deprecation-warnings.test.js

@@ -1,217 +1,105 @@
 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //
-//  TEST FOR DEPRECATED OPTION NAMES (enableCaching, cacheMaxAge)
-//  This test verifies backward compatibility and deprecation warnings
+//  TEST FOR REMOVED OPTION NAMES (enableCaching, cacheMaxAge)
+//  These options were removed in v3.0.0 — passing them must throw an Error.
 //
 //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
-const supertest = require('supertest');
 const koaClassicServer = require('../index.cjs');
 const Koa = require('koa');
 const path = require('path');
 
 const rootDir = path.join(__dirname, 'publicWwwTest');
 
-describe('Deprecated option names (backward compatibility)', () => {
+describe('Removed option names (v3.0.0 breaking changes)', () => {
 
-    describe('Using deprecated enableCaching option', () => {
-        let app;
-        let server;
-        let consoleWarnSpy;
-
-        beforeAll(() => {
-            // Spy on console.warn to capture deprecation warnings
-            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-
-            app = new Koa();
-
-            // Use deprecated option name
-            app.use(koaClassicServer(rootDir, {
-                enableCaching: true  // DEPRECATED: should use browserCacheEnabled
-            }));
-
-            server = app.listen();
-        });
-
-        afterAll(() => {
-            server.close();
-            consoleWarnSpy.mockRestore();
-        });
-
-        test('should display deprecation warning for enableCaching', () => {
-            expect(consoleWarnSpy).toHaveBeenCalled();
-            const warningMessage = consoleWarnSpy.mock.calls[0][1];
-            expect(warningMessage).toContain('DEPRECATION WARNING');
-            expect(warningMessage).toContain('enableCaching');
-            expect(warningMessage).toContain('browserCacheEnabled');
-        });
-
-        test('should still work with deprecated option', async () => {
-            const response = await supertest(server).get('/test-page.html');
-
-            // Should return the file
-            expect(response.status).toBe(200);
-
-            // Should have caching headers (because enableCaching: true was set)
-            expect(response.headers['etag']).toBeDefined();
-            expect(response.headers['last-modified']).toBeDefined();
-            expect(response.headers['cache-control']).toContain('public');
-        });
+    test('should throw when "enableCaching" is passed', () => {
+        expect(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(rootDir, { enableCaching: true }));
+        }).toThrow('"enableCaching" option was removed in v3.0.0');
     });
 
-    describe('Using deprecated cacheMaxAge option', () => {
-        let app;
-        let server;
-        let consoleWarnSpy;
-
-        beforeAll(() => {
-            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-
-            app = new Koa();
-
-            // Use deprecated option name
-            app.use(koaClassicServer(rootDir, {
-                enableCaching: true,  // Also deprecated
-                cacheMaxAge: 7200     // DEPRECATED: should use browserCacheMaxAge
-            }));
-
-            server = app.listen();
-        });
-
-        afterAll(() => {
-            server.close();
-            consoleWarnSpy.mockRestore();
-        });
-
-        test('should display deprecation warning for cacheMaxAge', () => {
-            const warningCalls = consoleWarnSpy.mock.calls;
-            const cacheMaxAgeWarning = warningCalls.find(call =>
-                call[1] && call[1].includes('cacheMaxAge')
-            );
-
-            expect(cacheMaxAgeWarning).toBeDefined();
-            expect(cacheMaxAgeWarning[1]).toContain('DEPRECATION WARNING');
-            expect(cacheMaxAgeWarning[1]).toContain('browserCacheMaxAge');
-        });
-
-        test('should use the deprecated cacheMaxAge value', async () => {
-            const response = await supertest(server).get('/test-page.html');
-
-            expect(response.status).toBe(200);
-            expect(response.headers['cache-control']).toContain('max-age=7200');
-        });
+    test('should throw when "cacheMaxAge" is passed', () => {
+        expect(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(rootDir, { cacheMaxAge: 3600 }));
+        }).toThrow('"cacheMaxAge" option was removed in v3.0.0');
     });
 
-    describe('Using new option names (no warnings)', () => {
-        let app;
-        let server;
-        let consoleWarnSpy;
-
-        beforeAll(() => {
-            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-
-            app = new Koa();
-
-            // Use NEW option names
-            app.use(koaClassicServer(rootDir, {
-                browserCacheEnabled: true,
-                browserCacheMaxAge: 3600
-            }));
-
-            server = app.listen();
-        });
-
-        afterAll(() => {
-            server.close();
-            consoleWarnSpy.mockRestore();
-        });
-
-        test('should NOT display deprecation warnings', () => {
-            // Filter out warnings from other tests (like index option deprecation)
-            const cachingWarnings = consoleWarnSpy.mock.calls.filter(call =>
-                call[1] && (call[1].includes('enableCaching') || call[1].includes('cacheMaxAge'))
-            );
-
-            expect(cachingWarnings.length).toBe(0);
-        });
-
-        test('should work correctly with new option names', async () => {
-            const response = await supertest(server).get('/test-page.html');
-
-            expect(response.status).toBe(200);
-            expect(response.headers['etag']).toBeDefined();
-            expect(response.headers['cache-control']).toContain('max-age=3600');
-        });
+    test('should throw even when new option is also provided alongside "cacheMaxAge"', () => {
+        expect(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(rootDir, { cacheMaxAge: 3600, browserCacheMaxAge: 3600 }));
+        }).toThrow('"cacheMaxAge" option was removed in v3.0.0');
     });
 
-    describe('Using both old and new names (new takes precedence)', () => {
-        let app;
-        let server;
-        let consoleWarnSpy;
-
-        beforeAll(() => {
-            consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-
-            app = new Koa();
+    test('should throw even when new option is also provided alongside "enableCaching"', () => {
+        expect(() => {
+            const app = new Koa();
+            app.use(koaClassicServer(rootDir, { enableCaching: false, browserCacheEnabled: false }));
+        }).toThrow('"enableCaching" option was removed in v3.0.0');
+    });
+});
 
-            // Use BOTH old and new names - new should take precedence
-            app.use(koaClassicServer(rootDir, {
-                enableCaching: true,           // OLD (deprecated)
-                browserCacheEnabled: false,    // NEW (should take precedence)
-                cacheMaxAge: 7200,             // OLD (deprecated)
-                browserCacheMaxAge: 9999       // NEW (should take precedence)
-            }));
+describe('New option names (browserCacheEnabled / browserCacheMaxAge)', () => {
+    const supertest = require('supertest');
+    let app;
+    let server;
+    let consoleWarnSpy;
 
-            server = app.listen();
-        });
+    beforeAll(() => {
+        consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
 
-        afterAll(() => {
-            server.close();
-            consoleWarnSpy.mockRestore();
-        });
+        app = new Koa();
+        app.use(koaClassicServer(rootDir, {
+            browserCacheEnabled: true,
+            browserCacheMaxAge: 3600
+        }));
 
-        test('should NOT display warnings when new names are also provided', () => {
-            // When both old and new names are provided, no warning should be shown
-            const cachingWarnings = consoleWarnSpy.mock.calls.filter(call =>
-                call[1] && (call[1].includes('enableCaching') || call[1].includes('cacheMaxAge'))
-            );
+        server = app.listen();
+    });
 
-            expect(cachingWarnings.length).toBe(0);
-        });
+    afterAll(() => {
+        server.close();
+        consoleWarnSpy.mockRestore();
+    });
 
-        test('new option values should take precedence over old ones', async () => {
-            const response = await supertest(server).get('/test-page.html');
+    test('should not warn about removed options', () => {
+        const removedWarnings = consoleWarnSpy.mock.calls.filter(call =>
+            call[1] && (call[1].includes('enableCaching') || call[1].includes('cacheMaxAge'))
+        );
+        expect(removedWarnings.length).toBe(0);
+    });
 
-            expect(response.status).toBe(200);
+    test('should work correctly with new option names', async () => {
+        const response = await supertest(server).get('/test-page.html');
 
-            // browserCacheEnabled: false should take precedence over enableCaching: true
-            // So there should be NO caching headers
-            expect(response.headers['etag']).toBeUndefined();
-            expect(response.headers['cache-control']).toContain('no-cache');
-        });
+        expect(response.status).toBe(200);
+        expect(response.headers['etag']).toBeDefined();
+        expect(response.headers['cache-control']).toContain('max-age=3600');
     });
+});
 
-    describe('Default behavior (no caching options specified)', () => {
-        let app;
-        let server;
-
-        beforeAll(() => {
-            app = new Koa();
-            app.use(koaClassicServer(rootDir));
-            server = app.listen();
-        });
+describe('Default behavior (no caching options specified)', () => {
+    const supertest = require('supertest');
+    let app;
+    let server;
 
-        afterAll(() => {
-            server.close();
-        });
+    beforeAll(() => {
+        app = new Koa();
+        app.use(koaClassicServer(rootDir));
+        server = app.listen();
+    });
 
-        test('should default to browserCacheEnabled: false', async () => {
-            const response = await supertest(server).get('/test-page.html');
+    afterAll(() => {
+        server.close();
+    });
 
-            expect(response.status).toBe(200);
+    test('should default to browserCacheEnabled: false', async () => {
+        const response = await supertest(server).get('/test-page.html');
 
-            // Default is caching disabled
-            expect(response.headers['cache-control']).toContain('no-cache');
-        });
+        expect(response.status).toBe(200);
+        expect(response.headers['cache-control']).toContain('no-cache');
     });
 });

package/__tests__/directory-sorting-links.test.js

@@ -13,7 +13,7 @@ describe('Directory Sorting Links Bug Tests', () => {
 
         app.use(koaClassicServer(publicDir, {
             method: ['GET'],
-            showDirContents: true
+            dirListing: { enabled: true }
         }));
 
         server = app.listen();