koa-classic-server 2.6.1 → 3.0.0-alpha.0

package/README.md

@@ -554,9 +554,23 @@ Creates a Koa middleware for serving static files.
     redirect: 301           // HTTP redirect code (optional, default: 301)
   },
 
-  // DEPRECATED (use new names above):
-  // enableCaching: use browserCacheEnabled instead
-  // cacheMaxAge: use browserCacheMaxAge instead
+  // Block files/dirs from listing and serving (HTTP 404)
+  // Dot-files (names starting with '.') are hidden by default.
+  // Dot-directories are visible by default.
+  hidden: {
+    dotFiles: {
+      default: 'hidden',        // 'hidden' | 'visible' — system default: 'hidden'
+      whitelist: ['.well-known'], // Always visible — string (exact/glob) or RegExp
+      blacklist: [],              // Always hidden — overrides whitelist
+    },
+    dotDirs: {
+      default: 'visible',       // 'hidden' | 'visible' — system default: 'visible'
+      whitelist: [],
+      blacklist: ['.git'],
+    },
+    alwaysHide: ['*.key', /secret/i], // Path-aware patterns (string glob or RegExp)
+  },
+
 }
 ```
 
@@ -566,7 +580,7 @@ Creates a Koa middleware for serving static files.
 |--------|------|---------|-------------|
 | `method` | Array | `['GET']` | Allowed HTTP methods |
 | `showDirContents` | Boolean | `true` | Show directory listing |
-| `index` | Array/String | `[]` | Index file patterns (array format recommended) |
+| `index` | Array | `[]` | Index file patterns (strings, RegExp, or mixed) |
 | `urlPrefix` | String | `''` | URL path prefix |
 | `urlsReserved` | Array | `[]` | Reserved directory paths (first-level only) |
 | `template.render` | Function | `undefined` | Template rendering function |
@@ -576,8 +590,13 @@ Creates a Koa middleware for serving static files.
 | `useOriginalUrl` | Boolean | `true` | Use `ctx.originalUrl` (default) or `ctx.url` for URL resolution |
 | `hideExtension.ext` | String | - | Extension to hide (e.g. `'.ejs'`). Enables clean URL feature |
 | `hideExtension.redirect` | Number | `301` | HTTP redirect code for URLs with extension |
-| ~~`enableCaching`~~ | Boolean | `false` | **DEPRECATED**: Use `browserCacheEnabled` instead |
-| ~~`cacheMaxAge`~~ | Number | `3600` | **DEPRECATED**: Use `browserCacheMaxAge` instead |
+| `hidden.dotFiles.default` | String | `'hidden'` | Default visibility for dot-files: `'hidden'` or `'visible'` |
+| `hidden.dotFiles.whitelist` | Array | `[]` | Dot-file names always visible (string exact/glob or RegExp) |
+| `hidden.dotFiles.blacklist` | Array | `[]` | Dot-file names always hidden — overrides whitelist |
+| `hidden.dotDirs.default` | String | `'visible'` | Default visibility for dot-dirs: `'hidden'` or `'visible'` |
+| `hidden.dotDirs.whitelist` | Array | `[]` | Dot-dir names always visible |
+| `hidden.dotDirs.blacklist` | Array | `[]` | Dot-dir names always hidden — overrides whitelist |
+| `hidden.alwaysHide` | Array | `[]` | Path-aware patterns (string glob or RegExp) for any file/dir. Secondary to whitelist/blacklist. |
 
 #### useOriginalUrl (Boolean, default: true)
 
@@ -774,7 +793,7 @@ npm run test:performance
 - ✅ 309 tests passing
 - ✅ Security tests (path traversal, XSS, race conditions)
 - ✅ EJS template integration tests
-- ✅ Index option tests (strings, arrays, RegExp)
+- ✅ Index option tests (arrays, RegExp)
 - ✅ hideExtension tests (clean URLs, redirects, conflicts, validation)
 - ✅ Symlink tests (file, directory, broken, circular, indicators)
 - ✅ Performance benchmarks
@@ -844,20 +863,59 @@ npm run test:performance
 
 ## Migration Guide
 
+### From v2.x to v3.x
+
+**Breaking Changes:**
+- `index` option: String format removed — passing a non-empty string now throws an Error
+- `cacheMaxAge` option: removed — use `browserCacheMaxAge`
+- `enableCaching` option: removed — use `browserCacheEnabled`
+- **Dot-files hidden by default** — `hidden.dotFiles.default` is `'hidden'` out of the box.
+  In v2.x, dot-files like `.env` were served normally. In v3.x they return 404 unless explicitly allowed.
+
+**Migration:**
+
+```javascript
+// v2.x (now throws in v3)
+{ index: 'index.html' }
+
+// v3.x
+{ index: ['index.html'] }
+```
+
+```javascript
+// v2.x — dot-files were served (no protection)
+// v3.x — dot-files hidden by default (recommended)
+
+// To restore v2.x behavior for dot-files:
+{
+  hidden: { dotFiles: { default: 'visible' } }
+}
+
+// Recommended v3.x — hide dot-files but expose .well-known for ACME/Let's Encrypt:
+{
+  hidden: {
+    dotFiles: { default: 'hidden', whitelist: ['.well-known'] },
+    dotDirs:  { default: 'hidden', whitelist: ['.well-known'] }
+  }
+}
+```
+
+---
+
 ### From v1.x to v2.x
 
 **Breaking Changes:**
-- `index` option: String format deprecated (still works), use array format
+- `index` option: String format deprecated (use array format)
 
 **Migration:**
 
 ```javascript
-// v1.x (deprecated)
+// v1.x
 {
   index: 'index.html'
 }
 
-// v2.x (recommended)
+// v2.x+
 {
   index: ['index.html']
 }

package/__tests__/caching-headers.test.js

@@ -2,8 +2,8 @@
  * HTTP Caching Headers Test
  *
  * Tests to verify correct caching behavior:
- * - When enableCaching: true -> proper cache headers
- * - When enableCaching: false -> anti-cache headers
+ * - When browserCacheEnabled: true -> proper cache headers
+ * - When browserCacheEnabled: false -> anti-cache headers
  */
 
 const Koa = require('koa');
@@ -30,7 +30,7 @@ describe('HTTP Caching Headers', () => {
         }
     });
 
-    describe('When caching is DISABLED (enableCaching: false)', () => {
+    describe('When caching is DISABLED (browserCacheEnabled: false)', () => {
         let app;
         let server;
         let request;
@@ -38,7 +38,7 @@ describe('HTTP Caching Headers', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: false
+                browserCacheEnabled: false
             }));
             server = app.listen();
             request = supertest(server);
@@ -89,7 +89,7 @@ describe('HTTP Caching Headers', () => {
         });
     });
 
-    describe('When caching is ENABLED (enableCaching: true)', () => {
+    describe('When caching is ENABLED (browserCacheEnabled: true)', () => {
         let app;
         let server;
         let request;
@@ -97,8 +97,8 @@ describe('HTTP Caching Headers', () => {
         beforeAll(() => {
             app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true,
-                cacheMaxAge: 3600
+                browserCacheEnabled: true,
+                browserCacheMaxAge: 3600
             }));
             server = app.listen();
             request = supertest(server);
@@ -173,7 +173,7 @@ describe('HTTP Caching Headers', () => {
 
         beforeAll(() => {
             app = new Koa();
-            // No options provided - should default to enableCaching: false
+            // No options provided - should default to browserCacheEnabled: false
             app.use(koaClassicServer(TEST_DIR));
             server = app.listen();
             request = supertest(server);
@@ -193,12 +193,12 @@ describe('HTTP Caching Headers', () => {
         });
     });
 
-    describe('Custom cacheMaxAge values', () => {
-        test('Should respect custom cacheMaxAge: 7200', async () => {
+    describe('Custom browserCacheMaxAge values', () => {
+        test('Should respect custom browserCacheMaxAge: 7200', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true,
-                cacheMaxAge: 7200
+                browserCacheEnabled: true,
+                browserCacheMaxAge: 7200
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -211,11 +211,11 @@ describe('HTTP Caching Headers', () => {
             server.close();
         });
 
-        test('Should respect custom cacheMaxAge: 0 (no browser cache)', async () => {
+        test('Should respect custom browserCacheMaxAge: 0 (no browser cache)', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true,
-                cacheMaxAge: 0
+                browserCacheEnabled: true,
+                browserCacheMaxAge: 0
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -230,11 +230,11 @@ describe('HTTP Caching Headers', () => {
             server.close();
         });
 
-        test('Should respect custom cacheMaxAge: 86400 (1 day)', async () => {
+        test('Should respect custom browserCacheMaxAge: 86400 (1 day)', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true,
-                cacheMaxAge: 86400
+                browserCacheEnabled: true,
+                browserCacheMaxAge: 86400
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -255,7 +255,7 @@ describe('HTTP Caching Headers', () => {
 
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -290,7 +290,7 @@ describe('HTTP Caching Headers', () => {
 
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -318,7 +318,7 @@ describe('HTTP Caching Headers', () => {
         test('304 response should have no body', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -348,7 +348,7 @@ describe('HTTP Caching Headers', () => {
         test('Should save bandwidth on multiple 304 responses', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -394,7 +394,7 @@ describe('HTTP Caching Headers', () => {
         test('HTML files should have cache headers', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -411,7 +411,7 @@ describe('HTTP Caching Headers', () => {
         test('JSON files should have cache headers', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -427,7 +427,7 @@ describe('HTTP Caching Headers', () => {
         test('CSS files should have cache headers', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -443,7 +443,7 @@ describe('HTTP Caching Headers', () => {
         test('JavaScript files should have cache headers', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -466,8 +466,8 @@ describe('HTTP Caching Headers', () => {
 
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true,
-                cacheMaxAge: 3600,
+                browserCacheEnabled: true,
+                browserCacheMaxAge: 3600,
                 template: {
                     ext: ['ejs'],
                     render: async (ctx, next, filePath) => {
@@ -499,7 +499,7 @@ describe('HTTP Caching Headers', () => {
         test('Multiple concurrent requests should handle caching correctly', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);
@@ -528,7 +528,7 @@ describe('HTTP Caching Headers', () => {
         test('Concurrent 304 responses should work correctly', async () => {
             const app = new Koa();
             app.use(koaClassicServer(TEST_DIR, {
-                enableCaching: true
+                browserCacheEnabled: true
             }));
             const server = app.listen();
             const request = supertest(server);

package/__tests__/compression-fixtures/data.json

@@ -0,0 +1 @@
+{"key":"value"}

package/__tests__/compression-fixtures/large.txt

@@ -0,0 +1 @@
+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

package/__tests__/compression-fixtures/small.txt

@@ -0,0 +1 @@
+tiny

package/__tests__/compression.test.js

@@ -0,0 +1,270 @@
+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, { showDirContents: 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('minSize: false → compress regardless of size', async () => {
+        const s = createApp({ compression: { minSize: 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));
+    });
+});

package/__tests__/customTest/serversToLoad.util.js

@@ -32,7 +32,7 @@ const configurations = [
       urlPrefix: '/public',
       method: ['GET'],
       showDirContents: true,
-      index: 'index.html',
+      index: ['index.html'],
     },
   },
   {