koa-classic-server 2.6.1 → 3.0.0

package/__tests__/server-cache.test.js

@@ -0,0 +1,594 @@
+/**
+ * serverCache tests for koa-classic-server
+ *
+ * Covers serverCache.rawFile and serverCache.compressedFile behaviour:
+ *   - rawFile disabled by default; opt-in via { serverCache: { rawFile: { enabled: true } } }
+ *   - compressedFile enabled by default
+ *   - LFU eviction when maxSize is exceeded
+ *   - warnInterval throttling of "maxSize reached" warnings
+ *   - rawFile buffer fed to template render as 4th parameter
+ *   - rawFile buffer used for Range (206) responses — zero additional disk I/O
+ *   - rawFile buffer used as input to compression — avoids redundant readFile
+ *   - Files exceeding maxFileSize are never cached (served via stream)
+ *   - Cache invalidation when mtime or size changes
+ *
+ * Fixtures (server-cache-fixtures/):
+ *   small.txt   — 64 bytes of 'A'
+ *   large.txt   — 2048 bytes of 'B' (used for maxFileSize threshold tests)
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const Koa = require('koa');
+const supertest = require('supertest');
+const koaClassicServer = require('../index.cjs');
+
+const fixturesDir = path.join(__dirname, 'server-cache-fixtures');
+
+function createApp(opts = {}) {
+    const app = new Koa();
+    app.use(koaClassicServer(fixturesDir, { dirListing: { enabled: false }, ...opts }));
+    return app.listen();
+}
+
+// ─── Default behaviour ────────────────────────────────────────────────────────
+
+describe('serverCache.rawFile — disabled by default', () => {
+    let server;
+    beforeAll(() => { server = createApp(); });
+    afterAll(() => server.close());
+
+    test('GET /small.txt returns 200 without rawFile cache', async () => {
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('A'.repeat(64));
+    });
+});
+
+// ─── rawFile cache enabled ────────────────────────────────────────────────────
+
+describe('serverCache.rawFile — enabled', () => {
+    let server;
+    beforeAll(() => {
+        server = createApp({ serverCache: { rawFile: { enabled: true } } });
+    });
+    afterAll(() => server.close());
+
+    test('first request populates cache and returns correct body', async () => {
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('A'.repeat(64));
+    });
+
+    test('second request also returns correct body (served from cache)', async () => {
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('A'.repeat(64));
+    });
+
+    test('Content-Length matches file size', async () => {
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(Number(res.headers['content-length'])).toBe(64);
+    });
+});
+
+// ─── maxFileSize threshold ────────────────────────────────────────────────────
+
+describe('serverCache.rawFile — maxFileSize', () => {
+    test('file exceeding maxFileSize is served via stream (not cached)', async () => {
+        // maxFileSize: 32 bytes — small.txt (64 bytes) exceeds this
+        const server = createApp({
+            serverCache: { rawFile: { enabled: true, maxFileSize: 32 } }
+        });
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'identity');
+        server.close();
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('A'.repeat(64));
+    });
+
+    test('file within maxFileSize is served correctly', async () => {
+        // maxFileSize: 128 bytes — small.txt (64 bytes) fits
+        const server = createApp({
+            serverCache: { rawFile: { enabled: true, maxFileSize: 128 } }
+        });
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'identity');
+        server.close();
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('A'.repeat(64));
+        expect(Number(res.headers['content-length'])).toBe(64);
+    });
+});
+
+// ─── Cache invalidation ───────────────────────────────────────────────────────
+
+describe('serverCache.rawFile — cache invalidation on file change', () => {
+    let tmpDir;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-cache-inval-'));
+        fs.writeFileSync(path.join(tmpDir, 'dynamic.txt'), 'version-1');
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { rawFile: { enabled: true } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('initial content is served correctly', async () => {
+        const res = await supertest(server)
+            .get('/dynamic.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('version-1');
+    });
+
+    test('updated file content is served after cache invalidation', async () => {
+        // Wait 10ms to ensure mtime changes on filesystems with 1ms resolution
+        await new Promise(r => setTimeout(r, 10));
+        fs.writeFileSync(path.join(tmpDir, 'dynamic.txt'), 'version-2');
+
+        const res = await supertest(server)
+            .get('/dynamic.txt')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('version-2');
+    });
+});
+
+// ─── maxAge: factory validation ───────────────────────────────────────────────
+
+describe('serverCache.*.maxAge — factory validation', () => {
+    test('rejects negative rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: -1 } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects NaN rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: NaN } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects Infinity rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: Infinity } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects string rawFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: '5000' } }
+        })).toThrow(/rawFile\.maxAge must be a finite number/);
+    });
+
+    test('rejects negative compressedFile.maxAge', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { compressedFile: { maxAge: -1 } }
+        })).toThrow(/compressedFile\.maxAge must be a finite number/);
+    });
+
+    test('accepts 0 (disabled) and positive integers', () => {
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: 0 } }
+        })).not.toThrow();
+        expect(() => koaClassicServer(fixturesDir, {
+            serverCache: { rawFile: { enabled: true, maxAge: 1000 } }
+        })).not.toThrow();
+    });
+});
+
+// ─── maxAge: rawFile staleness ────────────────────────────────────────────────
+
+describe('serverCache.rawFile.maxAge — time-based staleness', () => {
+    // Verify maxAge triggers a fresh disk read even when mtime+size are unchanged.
+    // Simulates the NFS attribute-cache scenario by manually restoring mtime after
+    // editing the file, so the mtime-based invariant alone cannot detect the change.
+    let tmpDir;
+    let filePath;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-maxage-raw-'));
+        filePath = path.join(tmpDir, 'data.txt');
+        fs.writeFileSync(filePath, 'version-A');
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { rawFile: { enabled: true, maxAge: 100 } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('within maxAge: cache is served (no disk re-read)', async () => {
+        const first = await supertest(server).get('/data.txt').set('Accept-Encoding', 'identity');
+        expect(first.text).toBe('version-A');
+
+        // Replace content but freeze mtime to its original value (simulates NFS lying about mtime).
+        // Length must stay identical so the size check doesn't invalidate independently of maxAge.
+        const originalStat = fs.statSync(filePath);
+        fs.writeFileSync(filePath, 'version-B'); // same 9 bytes as 'version-A'
+        fs.utimesSync(filePath, originalStat.atime, originalStat.mtime);
+
+        // Within maxAge → stale check passes → still serves cached A
+        const second = await supertest(server).get('/data.txt').set('Accept-Encoding', 'identity');
+        expect(second.text).toBe('version-A');
+    });
+
+    test('after maxAge: cache is refreshed (disk re-read) even when mtime+size unchanged', async () => {
+        await new Promise(r => setTimeout(r, 120)); // exceeds 100 ms maxAge
+
+        const third = await supertest(server).get('/data.txt').set('Accept-Encoding', 'identity');
+        expect(third.text).toBe('version-B');
+    });
+});
+
+describe('serverCache.rawFile.maxAge — disabled (0) preserves previous behaviour', () => {
+    let tmpDir;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-maxage-off-'));
+        fs.writeFileSync(path.join(tmpDir, 'stable.txt'), 'unchanged');
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { rawFile: { enabled: true, maxAge: 0 } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('cache served indefinitely while mtime+size unchanged', async () => {
+        await supertest(server).get('/stable.txt').set('Accept-Encoding', 'identity');
+        await new Promise(r => setTimeout(r, 150));
+        const res = await supertest(server).get('/stable.txt').set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('unchanged');
+    });
+});
+
+// ─── maxAge: compressedFile staleness ─────────────────────────────────────────
+
+describe('serverCache.compressedFile.maxAge — time-based staleness', () => {
+    let tmpDir;
+    let filePath;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-maxage-cmp-'));
+        filePath = path.join(tmpDir, 'data.css');
+        fs.writeFileSync(filePath, 'a'.repeat(2048)); // above minFileSize=1024 to ensure compression
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { compressedFile: { maxAge: 100 } }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('after maxAge, compressed cache is rebuilt from updated content', async () => {
+        const first = await supertest(server).get('/data.css').set('Accept-Encoding', 'gzip');
+        expect(first.status).toBe(200);
+        expect(first.headers['content-encoding']).toBe('gzip');
+        expect(first.text).toBe('a'.repeat(2048));
+
+        // Replace content with same length, freeze mtime to simulate NFS staleness.
+        const originalStat = fs.statSync(filePath);
+        fs.writeFileSync(filePath, 'b'.repeat(2048));
+        fs.utimesSync(filePath, originalStat.atime, originalStat.mtime);
+
+        // Within maxAge → cached gzip of A still served.
+        const second = await supertest(server).get('/data.css').set('Accept-Encoding', 'gzip');
+        expect(second.text).toBe('a'.repeat(2048));
+
+        // After maxAge → cache refreshed → gzip of B served.
+        await new Promise(r => setTimeout(r, 120));
+        const third = await supertest(server).get('/data.css').set('Accept-Encoding', 'gzip');
+        expect(third.text).toBe('b'.repeat(2048));
+    });
+});
+
+// ─── rawFile + Range requests ─────────────────────────────────────────────────
+
+describe('serverCache.rawFile — Range request served from buffer', () => {
+    let server;
+    beforeAll(() => {
+        server = createApp({ serverCache: { rawFile: { enabled: true } } });
+    });
+    afterAll(() => server.close());
+
+    test('Range request returns 206 with correct slice', async () => {
+        // Warm cache first
+        await supertest(server).get('/small.txt').set('Accept-Encoding', 'identity');
+
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Range', 'bytes=0-9')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(206);
+        expect(res.text).toBe('A'.repeat(10));
+        expect(res.headers['content-length']).toBe('10');
+    });
+
+    test('Range request returns correct Content-Range header', async () => {
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Range', 'bytes=10-19')
+            .set('Accept-Encoding', 'identity');
+        expect(res.status).toBe(206);
+        expect(res.headers['content-range']).toBe('bytes 10-19/64');
+    });
+});
+
+// ─── rawFile + compression ────────────────────────────────────────────────────
+
+describe('serverCache.rawFile + compression — rawFile feeds compressedFile', () => {
+    let server;
+    beforeAll(() => {
+        server = createApp({
+            compression: { minFileSize: false }, // compress small.txt too
+            serverCache: { rawFile: { enabled: true } }
+        });
+    });
+    afterAll(() => server.close());
+
+    test('compressed response is served correctly when rawFile cache is warm', async () => {
+        // Warm rawFile cache
+        await supertest(server).get('/small.txt').set('Accept-Encoding', 'identity');
+
+        // Request compressed version — rawFile buffer used as compression input
+        const res = await supertest(server)
+            .get('/small.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.status).toBe(200);
+        expect(res.headers['content-encoding']).toBe('gzip');
+        // supertest auto-decompresses gzip
+        expect(res.text).toBe('A'.repeat(64));
+    });
+});
+
+// ─── compressedFile cache — default enabled ───────────────────────────────────
+
+describe('serverCache.compressedFile — enabled by default', () => {
+    let server;
+    beforeAll(() => { server = createApp(); });
+    afterAll(() => server.close());
+
+    test('large.txt compressed response has Content-Length (buffered, not streamed)', 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['content-length']).toBeDefined();
+        expect(Number(res.headers['content-length'])).toBeGreaterThan(0);
+    });
+});
+
+// ─── compressedFile cache — disabled (streaming) ──────────────────────────────
+
+describe('serverCache.compressedFile — disabled (streaming mode)', () => {
+    let server;
+    beforeAll(() => {
+        server = createApp({ serverCache: { compressedFile: { enabled: false } } });
+    });
+    afterAll(() => server.close());
+
+    test('compressed response has no Content-Length in streaming mode', 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['content-length']).toBeUndefined();
+    });
+
+    test('streaming body is correctly decompressed', async () => {
+        const res = await supertest(server)
+            .get('/large.txt')
+            .set('Accept-Encoding', 'gzip');
+        expect(res.text).toBe('B'.repeat(2048));
+    });
+});
+
+// ─── LFU eviction ────────────────────────────────────────────────────────────
+
+describe('serverCache.rawFile — LFU eviction when maxSize exceeded', () => {
+    let tmpDir;
+    let server;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-lfu-test-'));
+        // fileA: 100 bytes, fileB: 100 bytes — cache maxSize: 150 bytes
+        // After caching A (100 bytes) and B (100 bytes), total = 200 > 150.
+        // LFU should evict A (hits=1) when B is added if A has fewer hits than B.
+        fs.writeFileSync(path.join(tmpDir, 'fileA.txt'), 'A'.repeat(100));
+        fs.writeFileSync(path.join(tmpDir, 'fileB.txt'), 'B'.repeat(100));
+        fs.writeFileSync(path.join(tmpDir, 'fileC.txt'), 'C'.repeat(100));
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: {
+                rawFile: {
+                    enabled: true,
+                    maxSize: 150,    // fits 1 file (100 bytes) + half of another
+                    maxFileSize: 200,
+                    warnInterval: false, // suppress warnings during test
+                }
+            }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('all files return correct content even when eviction occurs', async () => {
+        // Access A twice (hits=2), then B once (hits=1), then C once
+        // When C is added, LFU should evict B (lowest hits among cached entries)
+        const resA1 = await supertest(server).get('/fileA.txt').set('Accept-Encoding', 'identity');
+        const resA2 = await supertest(server).get('/fileA.txt').set('Accept-Encoding', 'identity');
+        const resB  = await supertest(server).get('/fileB.txt').set('Accept-Encoding', 'identity');
+        const resC  = await supertest(server).get('/fileC.txt').set('Accept-Encoding', 'identity');
+
+        expect(resA1.text).toBe('A'.repeat(100));
+        expect(resA2.text).toBe('A'.repeat(100));
+        expect(resB.text).toBe('B'.repeat(100));
+        expect(resC.text).toBe('C'.repeat(100));
+    });
+});
+
+// ─── warnInterval ────────────────────────────────────────────────────────────
+
+describe('serverCache.rawFile — warnInterval throttles warnings', () => {
+    test('warnInterval: false suppresses all warnings', async () => {
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-warn-test-'));
+        fs.writeFileSync(path.join(tmpDir, 'a.txt'), 'A'.repeat(100));
+        fs.writeFileSync(path.join(tmpDir, 'b.txt'), 'B'.repeat(100));
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: {
+                rawFile: {
+                    enabled: true,
+                    maxSize: 50,        // too small to fit either file → eviction on every request
+                    maxFileSize: 200,
+                    warnInterval: false, // no warnings
+                }
+            }
+        }));
+        const server = app.listen();
+
+        await supertest(server).get('/a.txt').set('Accept-Encoding', 'identity');
+        await supertest(server).get('/b.txt').set('Accept-Encoding', 'identity');
+
+        const cacheWarnings = warnSpy.mock.calls.filter(c =>
+            c[0] && c[0].toString().includes('serverCache.rawFile')
+        );
+        expect(cacheWarnings.length).toBe(0);
+
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+        warnSpy.mockRestore();
+    });
+});
+
+// ─── rawFile buffer passed to template render ─────────────────────────────────
+
+describe('serverCache.rawFile — buffer passed as 4th param to render function', () => {
+    let tmpDir;
+    let server;
+    let capturedBuffer;
+
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kcs-render-buf-'));
+        fs.writeFileSync(path.join(tmpDir, 'page.tmpl'), 'hello from template');
+
+        const app = new Koa();
+        app.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            serverCache: { rawFile: { enabled: true } },
+            template: {
+                ext: ['tmpl'],
+                render: async (ctx, next, filePath, buffer) => {
+                    capturedBuffer = buffer;
+                    const content = buffer
+                        ? buffer.toString('utf-8')
+                        : await fs.promises.readFile(filePath, 'utf-8');
+                    ctx.type = 'text/plain';
+                    ctx.body = content;
+                }
+            }
+        }));
+        server = app.listen();
+    });
+
+    afterAll(() => {
+        server.close();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    test('render receives buffer on first request (cache miss populates buffer)', async () => {
+        capturedBuffer = undefined;
+        const res = await supertest(server).get('/page.tmpl');
+        expect(res.status).toBe(200);
+        expect(res.text).toBe('hello from template');
+        // Buffer should be populated (cache miss still reads file and caches it)
+        expect(Buffer.isBuffer(capturedBuffer)).toBe(true);
+        expect(capturedBuffer.toString('utf-8')).toBe('hello from template');
+    });
+
+    test('render receives buffer on subsequent request (cache hit)', async () => {
+        capturedBuffer = undefined;
+        const res = await supertest(server).get('/page.tmpl');
+        expect(res.status).toBe(200);
+        expect(Buffer.isBuffer(capturedBuffer)).toBe(true);
+        expect(capturedBuffer.toString('utf-8')).toBe('hello from template');
+    });
+
+    test('render receives null when rawFile cache is disabled', async () => {
+        let bufferWhenDisabled;
+        const appNoCache = new Koa();
+        appNoCache.use(koaClassicServer(tmpDir, {
+            dirListing: { enabled: false },
+            // rawFile.enabled: false by default
+            template: {
+                ext: ['tmpl'],
+                render: async (ctx, next, filePath, buffer) => {
+                    bufferWhenDisabled = buffer;
+                    ctx.type = 'text/plain';
+                    ctx.body = 'ok';
+                }
+            }
+        }));
+        const s = appNoCache.listen();
+        await supertest(s).get('/page.tmpl');
+        s.close();
+        expect(bufferWhenDisabled).toBeNull();
+    });
+});