koa-classic-server 4.0.0 → 4.1.0

package/index.cjs

@@ -6,7 +6,7 @@ const crypto = require("crypto");
 const zlib = require("zlib");
 const util = require("util");
 const mime = require("mime-types");
-const { Readable, pipeline } = require('stream');
+const { Readable, Transform, pipeline } = require('stream');
 
 const _brotliCompressAsync = util.promisify(zlib.brotliCompress);
 const _gzipAsync           = util.promisify(zlib.gzip);
@@ -577,6 +577,25 @@ function singleFlight(map, key, work) {
 // stale-by-age (mtime + size unchanged), updates in place so the existing
 // frequency counter survives — important for popular files refreshed by maxAge.
 // Otherwise falls back to delete + set (frequency resets to 1).
+// Bounded-RAM streaming compressor: constant-memory transform, lower quality
+// than the buffered path (which can afford brotli Q11 because it runs once and
+// is cached). Used by every streamed-compression pipeline.
+// LGWIN 19 (512 KB window instead of brotli's default 4 MB): the encoder state
+// is the dominant per-request RAM on this path (~10 MB/stream at the default,
+// ~1.3 GB peak measured under 100 concurrent cold requests), and at Q4 the big
+// window buys nothing on typical text (measured: same output size, ~40% faster).
+// The trade-off: content with identical blocks repeated at >512 KB distance
+// (rare, pathological) compresses worse than with the 4 MB window. gzip's
+// window is 32 KB by design — nothing to bound there.
+function createStreamCompressor(encoding) {
+    return encoding === 'br'
+        ? zlib.createBrotliCompress({ params: {
+            [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+            [zlib.constants.BROTLI_PARAM_LGWIN]: 19,
+        } })
+        : zlib.createGzip({ level: 6 });
+}
+
 function refreshOrInsert(cache, key, newEntry, cached, staleByAge) {
     const canRefreshInPlace = cached
         && staleByAge
@@ -717,9 +736,14 @@ module.exports = function koaClassicServer(
                                           //   result cached). Default: 10 MB; false = no cap.
                                           //   Larger files are STILL compressed, but via the
                                           //   bounded-RAM streaming mode (brotli Q4 / gzip 6, no
-                                          //   Content-Length, not cached). This is a SAFETY NET
-                                          //   against unbounded RAM/CPU on huge compressible files
-                                          //   (multi-GB logs/JSON/CSV), not a serving restriction.
+                                          //   Content-Length on the first response). This is a
+                                          //   SAFETY NET against unbounded RAM/CPU on huge
+                                          //   compressible files (multi-GB logs/JSON/CSV), not a
+                                          //   serving restriction. When serverCache.compressedFile
+                                          //   is enabled, the streamed OUTPUT is also cached
+                                          //   (when it fits in a quarter of that cache's maxSize),
+                                          //   so subsequent requests are served from RAM with
+                                          //   Content-Length.
             mimeTypes: [],                // compressible MIME types (replaces default list if provided)
         },
         // compression: false            // shorthand to disable all compression
@@ -1419,6 +1443,37 @@ module.exports = function koaClassicServer(
     // ETag/Last-Modified).
     const _inflightRawReads     = new Map(); // `${path}:${mtime}:${size}` → Promise<Buffer>
     const _inflightCompressions = new Map(); // `${path}:${encoding}:${mtime}:${size}` → Promise<Buffer>
+    // Streamed-compression tee leaders in flight (`${path}:${encoding}:${mtime}:${size}`).
+    // Only ONE request per key accumulates the compressed output for the cache,
+    // so tee RAM never scales with the number of concurrent clients.
+    const _inflightStreamTees = new Set();
+    // Aggregate bytes currently accumulated by ALL in-flight tees. Bounds the
+    // transient RAM across DISTINCT large files too: accumulation stops (the
+    // entry is skipped, streaming continues) rather than let the tees hold more
+    // RAM in aggregate than the compressed cache they feed (its maxSize).
+    let _inflightTeeBytes = 0;
+
+    // Streams `toOpen` (or `rawBuffer`) through the bounded-RAM compressor for
+    // `encoding` and sets it as the response body. Shared by the cache-disabled
+    // streaming branch and by tee followers; the tee leader builds its own
+    // pipeline with the extra accumulator stage.
+    // pipeline (NOT pipe): teardown propagates in BOTH directions. When the
+    // client disconnects mid-transfer, Koa destroys the body (the zlib
+    // transform) and pipeline destroys `src` too, closing its file descriptor.
+    // A bare src.pipe(compress) leaves the ReadStream paused with the fd open
+    // forever — fd leak under aborted downloads. Client disconnects are a
+    // normal event and are not logged (avoids client-driven log spam).
+    function streamCompressedBody(ctx, toOpen, rawBuffer, encoding) {
+        const compress = createStreamCompressor(encoding);
+        const src = rawBuffer
+            ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
+            : fs.createReadStream(toOpen);
+        ctx.body = pipeline(src, compress, (err) => {
+            if (!err || err.code === 'ERR_STREAM_PREMATURE_CLOSE') return;
+            _logger.error('Stream error:', err);
+            if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
+        });
+    }
 
     // Returns the server-preferred enabled encoding the client is willing to accept.
     // Server preference order (compressionConfig.encodings) still wins; the
@@ -2110,11 +2165,15 @@ module.exports = function koaClassicServer(
                 // Safety net (#4): the buffered path reads the WHOLE file into RAM and
                 // compresses at max quality — fine for web assets, catastrophic for a
                 // multi-GB log/CSV. Above compression.maxFileSize the bounded-RAM
-                // streaming mode below is used instead (still compressed, not cached).
+                // streaming mode below is used instead. The cap gates only HOW the
+                // compression runs (buffered Q11 vs streamed Q4) — the compressed
+                // cache stays in play on both sides: above the cap the streamed
+                // OUTPUT is teed into the cache when it fits (see the tee branch),
+                // so later requests are RAM hits either way.
                 const withinCompressCap = compressionConfig.maxFileSize === false
                     || fileStat.size <= compressionConfig.maxFileSize;
 
-                if (serverCacheConfig.compressedFile.enabled && withinCompressCap) {
+                if (serverCacheConfig.compressedFile.enabled) {
                     // compressedFile cache mode: compress once → buffer in RAM → Content-Length known
                     const cacheKey = `${toOpen}:${encoding}`;
                     const cached = _compressedFileCache.peek(cacheKey);
@@ -2129,6 +2188,93 @@ module.exports = function koaClassicServer(
                     if (!stale) {
                         _compressedFileCache.get(cacheKey); // increment frequency
                         buf = cached.buffer; // Serve from cache
+                    } else if (!withinCompressCap) {
+                        // Above the buffered-compression cap: stream at the bounded-RAM
+                        // quality (never buffer the input), and tee the compressed OUTPUT
+                        // into the cache so later requests are RAM hits with Content-Length.
+                        // The cap protects against a large INPUT; the cache admission below
+                        // is decided on the actual OUTPUT size, which is only known here.
+                        if (ctx.method === 'HEAD') {
+                            // Mirror the GET status/headers (RFC 9110 §9.3.2) without running
+                            // the compression: no Content-Length (unknown), no cache insert.
+                            ctx.status = 200;
+                            return;
+                        }
+                        const mtimeMs = fileStat.mtime.getTime();
+                        const teeKey = `${cacheKey}:${mtimeMs}:${fileStat.size}`;
+                        if (_inflightStreamTees.has(teeKey)) {
+                            // Follower: another request is already accumulating this exact
+                            // file version. Stream independently (no added latency, no tee
+                            // stage) — the cache will be warm for the NEXT request.
+                            streamCompressedBody(ctx, toOpen, rawBuffer, encoding);
+                            return;
+                        }
+                        // Leader: stream AND accumulate a copy for the cache.
+                        _inflightStreamTees.add(teeKey);
+                        let acc = [];
+                        let accBytes = 0;
+                        // Two admission bounds, both on the real OUTPUT size:
+                        //  - per entry: a quarter of the cache, so one huge file cannot
+                        //    evict most of the working set on insert;
+                        //  - aggregate (_inflightTeeBytes): all in-flight tees together may
+                        //    never hold more RAM than the cache's own maxSize.
+                        const entryCap = Math.floor(serverCacheConfig.compressedFile.maxSize / 4);
+                        // Stops accumulating and releases this tee's share of the aggregate
+                        // budget. Safe to call more than once.
+                        const abandonAccumulation = () => {
+                            if (acc) {
+                                _inflightTeeBytes -= accBytes;
+                                acc = null;
+                            }
+                        };
+                        try {
+                            const compress = createStreamCompressor(encoding);
+                            const src = rawBuffer
+                                ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
+                                : fs.createReadStream(toOpen);
+                            const tee = new Transform({
+                                transform(chunk, _enc, done) {
+                                    if (acc) {
+                                        accBytes += chunk.length;
+                                        _inflightTeeBytes += chunk.length;
+                                        if (accBytes > entryCap
+                                            || _inflightTeeBytes > serverCacheConfig.compressedFile.maxSize) {
+                                            abandonAccumulation(); // over budget: keep streaming, skip the cache
+                                        } else {
+                                            acc.push(chunk);
+                                        }
+                                    }
+                                    done(null, chunk);
+                                },
+                            });
+                            // pipeline (NOT pipe): teardown propagates in BOTH directions —
+                            // same fd-leak rationale as streamCompressedBody.
+                            ctx.body = pipeline(src, compress, tee, (err) => {
+                                _inflightStreamTees.delete(teeKey);
+                                if (!err && acc) {
+                                    // Clean completion only: an aborted or failed stream never
+                                    // inserts a (truncated) entry.
+                                    refreshOrInsert(_compressedFileCache, cacheKey, {
+                                        buffer: Buffer.concat(acc, accBytes),
+                                        mtime: mtimeMs,
+                                        size: fileStat.size,
+                                        insertedAt: Date.now(),
+                                    }, cached, staleByAge);
+                                }
+                                abandonAccumulation();
+                                if (!err || err.code === 'ERR_STREAM_PREMATURE_CLOSE') return;
+                                _logger.error('Stream error:', err);
+                                if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
+                            });
+                        } catch (err) {
+                            // Defensive: nothing between add() and pipeline() is expected to
+                            // throw synchronously, but a leaked teeKey would silently disable
+                            // the tee for this file version forever.
+                            _inflightStreamTees.delete(teeKey);
+                            abandonAccumulation();
+                            throw err;
+                        }
+                        return;
                     } else {
                         try {
                             // Single-flight: concurrent misses on the same path+encoding
@@ -2195,26 +2341,10 @@ module.exports = function koaClassicServer(
                     }
 
                 } else {
-                    // Streaming mode: pipe through zlib transform — Content-Length not known in advance
+                    // Streaming mode (compressed cache disabled): pipe through the zlib
+                    // transform — Content-Length not known in advance, nothing cached.
                     if (ctx.method !== 'HEAD') {
-                        const compress = encoding === 'br'
-                            ? zlib.createBrotliCompress({ params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 4 } })
-                            : zlib.createGzip({ level: 6 });
-                        const src = rawBuffer
-                            ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
-                            : fs.createReadStream(toOpen);
-                        // pipeline (NOT pipe): teardown propagates in BOTH directions.
-                        // When the client disconnects mid-transfer, Koa destroys the body
-                        // (`compress`) and pipeline destroys `src` too, closing its file
-                        // descriptor. A bare src.pipe(compress) leaves the ReadStream
-                        // paused with the fd open forever — fd leak under aborted
-                        // downloads. Client disconnects are a normal event and are not
-                        // logged (avoids client-driven log spam).
-                        ctx.body = pipeline(src, compress, (err) => {
-                            if (!err || err.code === 'ERR_STREAM_PREMATURE_CLOSE') return;
-                            _logger.error('Stream error:', err);
-                            if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
-                        });
+                        streamCompressedBody(ctx, toOpen, rawBuffer, encoding);
                     } else {
                         // HEAD: mirror the GET status and headers (RFC 9110 §9.3.2) — no
                         // Content-Length, since the compressed size is unknown without
@@ -2592,3 +2722,18 @@ module.exports = function koaClassicServer(
 
     };
 };
+
+// ── Test-only internals ──────────────────────────────────────────────────────
+// NOT part of the public API: exposed so the unit tests can exercise the pure
+// helpers and the LFU cache directly (eviction order, frequency preservation,
+// range parsing, validator matching) without a full HTTP round-trip. No
+// stability guarantee — do not import from application code.
+module.exports._internals = {
+    LFUCache,
+    parseRangeHeader,
+    ifNoneMatchSatisfied,
+    formatSize,
+    singleFlight,
+    refreshOrInsert,
+    escapeHtml,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-classic-server",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "High-performance Koa middleware for serving static files with classic directory listing (similar, but not identical, to Apache 2), HTTP caching, template engine support, and comprehensive security fixes",
   "main": "index.cjs",
   "exports": {
@@ -17,6 +17,7 @@
     "pretest": "npm run lint",
     "test": "jest",
     "test:ci": "jest --testPathIgnorePatterns=performance",
+    "test:coverage": "jest --coverage --testPathIgnorePatterns=performance",
     "test:security": "jest __tests__/security.test.js",
     "test:performance": "jest __tests__/performance.test.js --runInBand",
     "benchmark": "node __tests__/benchmark.js",