koa-classic-server 4.0.0 → 4.2.0

package/README.md

@@ -150,6 +150,25 @@ app.use(koaClassicServer(path.join(__dirname, 'www'), {
 // .env, .git/config, *.key → 404
 ```
 
+### Custom error pages
+
+Branded 404/500/504 pages from self-contained `.html` files (v4.2+). Keep them **outside**
+`rootDir` so they are not themselves reachable via URL; edit them anytime — changes are
+picked up without a restart, and an unreadable file falls back to the built-in page:
+
+```javascript
+app.use(koaClassicServer(path.join(__dirname, 'www'), {
+  errorPages: {
+    404: path.join(__dirname, 'errors', '404.html'),
+    500: path.join(__dirname, 'errors', '500.html'),
+  },
+}));
+```
+
+One rule: each page must be a single self-contained file (inline CSS, no external
+css/js/img references). Custom pages are served without the built-in pages'
+`Content-Security-Policy`, so an external reference would really load.
+
 ### Mount under a prefix, pass through some routes
 
 ```javascript
@@ -299,6 +318,12 @@ koaClassicServer(rootDir, {
   symlinks: 'follow',                    // 'follow' | 'follow-within-root' | 'deny'
   staticSecurityHeaders: { nosniff: false }, // set nosniff on static responses
 
+  errorPages: {                          // custom error pages (v4.2+); omitted → built-ins
+    // 404: './errors/404.html',         // supported statuses: 404, 500, 504
+    // 500: './errors/500.html',         // self-contained .html (inline CSS, no external refs)
+    // 504: './errors/504.html',         // editable without a restart; unreadable → built-in
+  },
+
   template: {
     ext: [],                             // e.g. ['ejs']
     renderTimeout: 30000,                // ms; on timeout the request fails closed (0 = off)

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);
@@ -121,9 +121,12 @@ const LISTING_CSP = `default-src 'none'; style-src '${_listingCssHash}'; frame-a
 const NOT_FOUND_CSP = "default-src 'none'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
 
 // Sets security headers on all middleware-generated HTML pages (listing + error).
-// Must NOT be called for user files served from disk.
+// Must NOT be called for user files served from disk. `csp` may be null for
+// operator-authored custom error pages (options.errorPages): the built-in pages'
+// `default-src 'none'` would block their inline styles, so they get the non-CSP
+// headers only — the self-contained requirement is documented, not enforced.
 function setGeneratedPageHeaders(ctx, csp) {
-    ctx.set('Content-Security-Policy', csp);
+    if (csp) ctx.set('Content-Security-Policy', csp);
     ctx.set('X-Content-Type-Options', 'nosniff');
     ctx.set('X-Frame-Options', 'DENY');
     ctx.set('Referrer-Policy', 'no-referrer');
@@ -153,10 +156,38 @@ const _GATEWAY_TIMEOUT_HTML = buildErrorHtml('Gateway Timeout',       'Gateway T
 const _TEMPLATE_ERROR_HTML  = buildErrorHtml('Internal Server Error', 'Internal Server Error', 'Template rendering failed for the requested resource.');
 const _INTERNAL_ERROR_HTML  = buildErrorHtml('Internal Server Error', 'Internal Server Error', 'The server encountered an unexpected condition.');
 
-function sendNotFound(ctx) {
-    setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
-    ctx.status = 404;
-    ctx.body = _NOT_FOUND_HTML;
+// Statuses an operator can override via options.errorPages, each with its
+// built-in fallback page. 400 is deliberately absent: it answers malformed /
+// hostile requests and stays minimal by design. _TEMPLATE_ERROR_HTML is a
+// call-site-specific 500 body (template failures), not a separate status.
+const _BUILTIN_ERROR_HTML = {
+    404: _NOT_FOUND_HTML,
+    500: _INTERNAL_ERROR_HTML,
+    504: _GATEWAY_TIMEOUT_HTML,
+};
+
+// Representation / caching headers a partially-built response may have left
+// behind by the time an error is detected: a stale Content-Encoding would
+// corrupt the error page (its body is never compressed), a public
+// Cache-Control could get the 404/500 cached by proxies under the resource's
+// URL. Scrubbed on every error page write.
+const ERROR_PAGE_SCRUB_HEADERS = [
+    'Content-Encoding', 'Content-Disposition', 'Content-Range', 'Vary',
+    'ETag', 'Last-Modified', 'Accept-Ranges',
+    'Cache-Control', 'Pragma', 'Expires',
+];
+
+// Single writer for every middleware-generated error response (404 / 500 / 504).
+// `customBuffer` is the operator's page from options.errorPages (or null →
+// `builtinHtml` is served). Assumes the response is still writable — callers
+// keep their own headerSent / writableEnded guards.
+function writeErrorPage(ctx, status, customBuffer, builtinHtml) {
+    for (const h of ERROR_PAGE_SCRUB_HEADERS) ctx.remove(h);
+    if (status >= 500) ctx.set('Cache-Control', 'no-store');
+    setGeneratedPageHeaders(ctx, customBuffer ? null : NOT_FOUND_CSP);
+    ctx.set('Content-Type', 'text/html; charset=utf-8');
+    ctx.status = status;
+    ctx.body = customBuffer || builtinHtml;
 }
 
 // Plain-text 400 for malformed requests (bad percent-encoding, invalid Host,
@@ -212,16 +243,16 @@ function warnConfigDeprecation(logger, message) {
 
 // Sends an error response for a failed template render. If headers were already
 // flushed by the render itself, destroys the underlying socket instead (the
-// status/body can no longer be changed at that point).
-function sendTemplateError(ctx, status, html, logMsg, err, logger) {
+// status/body can no longer be changed at that point). Page selection (custom
+// vs built-in) goes through the instance's sendErrorPage; `builtinHtml` keeps
+// the call-site-specific fallback body (timeout vs render failure).
+async function sendTemplateError(ctx, status, builtinHtml, logMsg, err, logger, sendErrorPage) {
     logger.error(logMsg, err);
     if (ctx.headerSent || ctx.res.writableEnded) {
         ctx.res.destroy();
         return;
     }
-    setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
-    ctx.status = status;
-    ctx.body = html;
+    await sendErrorPage(ctx, status, builtinHtml);
 }
 
 // Rewrites an already-rendered response into an RFC 9110 §9.3.2 compliant HEAD
@@ -256,7 +287,7 @@ function stripBodyForHead(ctx) {
 // client disconnect. Cooperative renders that propagate the signal to fetch/db
 // release backend resources promptly; non-cooperative renders still get a 504
 // response, but their work continues in the background.
-async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, logger) {
+async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, logger, sendErrorPage) {
     if (templateOpts.ext.length === 0 || !templateOpts.render) return false;
 
     const fileExt = path.extname(filePath).slice(1);
@@ -304,11 +335,11 @@ async function tryRenderTemplate(ctx, next, filePath, rawBuffer, templateOpts, l
         }
     } catch (error) {
         if (timedOut || error.code === 'ETEMPLATETIMEOUT') {
-            sendTemplateError(ctx, 504, _GATEWAY_TIMEOUT_HTML,
-                'Template render timeout after ' + timeoutMs + 'ms:', filePath, logger);
+            await sendTemplateError(ctx, 504, _GATEWAY_TIMEOUT_HTML,
+                'Template render timeout after ' + timeoutMs + 'ms:', filePath, logger, sendErrorPage);
         } else {
-            sendTemplateError(ctx, 500, _TEMPLATE_ERROR_HTML,
-                'Template rendering error:', error, logger);
+            await sendTemplateError(ctx, 500, _TEMPLATE_ERROR_HTML,
+                'Template rendering error:', error, logger, sendErrorPage);
         }
     } finally {
         if (timer) clearTimeout(timer);
@@ -577,6 +608,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
@@ -672,6 +722,25 @@ module.exports = function koaClassicServer(
             ext: '.ejs',     // Extension to hide (required, string, case-sensitive, must start with '.')
             redirect: 301    // HTTP redirect code for URLs with extension (optional, default: 301)
         },
+        errorPages: {        // Custom error pages (V4.2+). Opt-in — omitted statuses keep the built-in pages.
+            // Keys: the statuses the middleware generates error pages for: 404, 500, 504.
+            //   Any other key throws at factory time. (400 replies to malformed/hostile
+            //   requests are deliberately NOT customizable — they stay minimal.)
+            // Values: filesystem path (absolute, or relative to process.cwd()) to a
+            //   SELF-CONTAINED .html file: one single file, inline CSS only, no external
+            //   css/js/img references. Documented requirement, not enforced — custom
+            //   pages are served WITHOUT the built-in pages' Content-Security-Policy
+            //   (which would block their inline styles); the other generated-page
+            //   security headers (nosniff, X-Frame-Options, ...) are still sent.
+            //   The file may live outside rootDir (recommended: keeps it unreachable via URL).
+            //   Read and validated at factory time (missing/unreadable → throw), cached in
+            //   RAM, and re-read automatically when its mtime/size changes — editable
+            //   without a restart. If it becomes unreadable at request time, the built-in
+            //   page is served instead (fallback; throttled warning via logger).
+            // 404: './errors/404.html',
+            // 500: './errors/500.html',
+            // 504: './errors/504.html',
+        },
         hidden: {            // Block files/dirs from listing and serving (HTTP 404)
             dotFiles: {      // Dot-files (names starting with '.'): visible by default — design philosophy
                 default: 'visible',  // 'hidden' | 'visible' — system default: 'visible'
@@ -717,9 +786,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
@@ -1390,6 +1464,98 @@ module.exports = function koaClassicServer(
         nosniff: !!(_ssh && _ssh.nosniff),
     };
 
+    // ── errorPages (V4.2+) — operator-supplied custom error pages ──
+    // Validated and read once at factory time (a typo must fail at startup, not
+    // on the first 404), then kept in RAM and refreshed when mtime/size changes.
+    const _errorPages = new Map(); // status → { path, buffer, mtimeMs, size }
+    const userErrorPages = opts.errorPages;
+    if (userErrorPages !== undefined) {
+        if (typeof userErrorPages !== 'object' || userErrorPages === null || Array.isArray(userErrorPages)) {
+            throw new Error(
+                '[koa-classic-server] options.errorPages must be an object mapping a supported HTTP status ' +
+                "to an .html file path. Example: errorPages: { 404: './errors/404.html' }"
+            );
+        }
+        for (const key of Object.keys(userErrorPages)) {
+            const status = Number(key);
+            if (_BUILTIN_ERROR_HTML[status] === undefined) {
+                throw new Error(
+                    `[koa-classic-server] errorPages: unsupported status "${key}". ` +
+                    'Supported statuses: ' + Object.keys(_BUILTIN_ERROR_HTML).join(', ') + '. ' +
+                    '(400 is deliberately not customizable: replies to malformed requests stay minimal.)'
+                );
+            }
+            const value = userErrorPages[key];
+            if (typeof value !== 'string' || value === '') {
+                throw new Error(
+                    `[koa-classic-server] errorPages[${key}] must be a non-empty string path to an .html file. ` +
+                    'Got: ' + (value === '' ? 'an empty string' : value === null ? 'null' : typeof value)
+                );
+            }
+            const resolved = path.resolve(value);
+            let pageStat, pageBuffer;
+            try {
+                pageStat = fs.statSync(resolved);
+                if (!pageStat.isFile()) throw new Error('not a regular file');
+                pageBuffer = fs.readFileSync(resolved);
+            } catch (err) {
+                throw new Error(
+                    `[koa-classic-server] errorPages[${key}]: cannot read "${resolved}" (${err.message}). ` +
+                    'The file must exist and be readable at startup.'
+                );
+            }
+            _errorPages.set(status, { path: resolved, buffer: pageBuffer, mtimeMs: pageStat.mtimeMs, size: pageStat.size });
+        }
+    }
+
+    // Runtime read-failure warnings, throttled per status: a 404 flood against a
+    // deleted custom page must not flood the log.
+    const _errorPageWarnAt = new Map(); // status → last warn timestamp (ms)
+    function warnErrorPageUnreadable(status, entry, err) {
+        const now = Date.now();
+        if (now - (_errorPageWarnAt.get(status) || 0) < 60000) return;
+        _errorPageWarnAt.set(status, now);
+        _logger.warn(...warnPayload(_logger,
+            `[koa-classic-server] errorPages[${status}]: cannot read "${entry.path}" — ` +
+            `serving the built-in page instead. (${err.message})`));
+    }
+
+    // Returns the custom page buffer for `status`, re-read from disk when the
+    // file changed (mtime+size — pages are editable without a restart). Returns
+    // null when no custom page is configured for the status, or when the file is
+    // no longer readable (the caller falls back to the built-in page).
+    async function getCustomErrorPage(status) {
+        const entry = _errorPages.get(status);
+        if (!entry) return null;
+        try {
+            const st = await fs.promises.stat(entry.path);
+            if (st.mtimeMs !== entry.mtimeMs || st.size !== entry.size) {
+                entry.buffer = await fs.promises.readFile(entry.path);
+                entry.mtimeMs = st.mtimeMs;
+                entry.size = st.size;
+            }
+            return entry.buffer;
+        } catch (err) {
+            warnErrorPageUnreadable(status, entry, err);
+            return null;
+        }
+    }
+
+    // Single sender for every middleware-generated error response. `builtinHtml`
+    // lets a call site keep its specific fallback body (e.g. the template-failure
+    // 500) while still honoring the operator's custom page when configured.
+    async function sendErrorPage(ctx, status, builtinHtml = _BUILTIN_ERROR_HTML[status]) {
+        writeErrorPage(ctx, status, await getCustomErrorPage(status), builtinHtml);
+    }
+
+    // Sync variant for stream-error callbacks, where no await is possible: serves
+    // the last-loaded custom buffer without the freshness stat — an acceptable
+    // trade for a branch that only fires when the disk fails mid-response.
+    function sendErrorPageSync(ctx, status) {
+        const entry = _errorPages.get(status);
+        writeErrorPage(ctx, status, entry ? entry.buffer : null, _BUILTIN_ERROR_HTML[status]);
+    }
+
     const compressionConfig = normalizeCompressionConfig(options.compression);
     const serverCacheConfig = normalizeServerCacheConfig(options.serverCache);
 
@@ -1419,6 +1585,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) sendErrorPageSync(ctx, 500);
+        });
+    }
 
     // Returns the server-preferred enabled encoding the client is willing to accept.
     // Server preference order (compressionConfig.encodings) still wins; the
@@ -1640,7 +1837,7 @@ module.exports = function koaClassicServer(
             // Returns 404 (not 403) so "outside root" is indistinguishable from "not found",
             // matching the symlink-escape and hidden-entry outcomes.
             if (!_isWithinRoot(fullPath, normalizedRootDir)) {
-                sendNotFound(ctx);
+                await sendErrorPage(ctx, 404);
                 return;
             }
 
@@ -1653,7 +1850,7 @@ module.exports = function koaClassicServer(
                     const segName = segments[i];
                     const segRelPath = segments.slice(0, i + 1).join('/');
                     if (isHiddenEntry(segName, segRelPath, true)) {
-                        sendNotFound(ctx);
+                        await sendErrorPage(ctx, 404);
                         return;
                     }
                 }
@@ -1768,7 +1965,7 @@ module.exports = function koaClassicServer(
                 stat = await fs.promises.stat(toOpen);
             } catch {
                 // File/directory doesn't exist or can't be accessed
-                sendNotFound(ctx);
+                await sendErrorPage(ctx, 404);
                 return;
             }
 
@@ -1777,7 +1974,7 @@ module.exports = function koaClassicServer(
                 const entryName = path.basename(toOpen);
                 const entryRelPath = path.relative(normalizedRootDir, toOpen).split(path.sep).join('/');
                 if (isHiddenEntry(entryName, entryRelPath, stat.isDirectory())) {
-                    sendNotFound(ctx);
+                    await sendErrorPage(ctx, 404);
                     return;
                 }
             }
@@ -1787,7 +1984,7 @@ module.exports = function koaClassicServer(
             // resolved below rootDir). The `_symlinkMode !== 'follow'` guard short-circuits
             // before any await so the default 'follow' mode stays truly zero-overhead.
             if (_symlinkMode !== 'follow' && !(await symlinkAllowed(toOpen))) {
-                sendNotFound(ctx);
+                await sendErrorPage(ctx, 404);
                 return;
             }
 
@@ -1836,7 +2033,7 @@ module.exports = function koaClassicServer(
                                 // symlink escaping rootDir — validate before serving it.
                                 // Guarded so the default 'follow' mode skips the await entirely.
                                 if (_symlinkMode !== 'follow' && !(await symlinkAllowed(indexPath))) {
-                                    sendNotFound(ctx);
+                                    await sendErrorPage(ctx, 404);
                                     return;
                                 }
                                 await loadFile(indexPath, indexFile.stat);
@@ -1849,7 +2046,7 @@ module.exports = function koaClassicServer(
                     ctx.body = await show_dir(toOpen, ctx);
                 } else {
                     // Directory listing disabled
-                    sendNotFound(ctx);
+                    await sendErrorPage(ctx, 404);
                 }
                 return;
             } else {
@@ -1859,7 +2056,7 @@ module.exports = function koaClassicServer(
                 // from not-found) rather than serving the file at a non-canonical
                 // URL. Disabled by dirListing.trailingSlash: false (v3 behavior).
                 if (options.dirListing.trailingSlash && _pathEndsWithSlash) {
-                    sendNotFound(ctx);
+                    await sendErrorPage(ctx, 404);
                     return;
                 }
                 await loadFile(toOpen, stat);
@@ -1871,17 +2068,10 @@ module.exports = function koaClassicServer(
                 ctx.res.destroy(); // response already in flight — nothing sane left to send
                 return;
             }
-            // Scrub representation/caching headers a partially-built response may
-            // have left behind: a stale Content-Encoding would corrupt the error
-            // page, a public Cache-Control could get the 500 cached by proxies.
-            for (const h of ['Content-Encoding', 'Content-Disposition', 'Content-Range', 'Vary', 'ETag', 'Last-Modified', 'Accept-Ranges']) {
-                ctx.remove(h);
-            }
-            ctx.set('Cache-Control', 'no-store');
-            ctx.set('Content-Type', 'text/html; charset=utf-8');
-            setGeneratedPageHeaders(ctx, NOT_FOUND_CSP);
-            ctx.status = 500;
-            ctx.body = _INTERNAL_ERROR_HTML;
+            // writeErrorPage scrubs the representation/caching headers a
+            // partially-built response may have left behind (stale
+            // Content-Encoding, public Cache-Control, ...) and sets no-store.
+            await sendErrorPage(ctx, 500);
         }
 
         // Internal functions
@@ -1894,7 +2084,7 @@ module.exports = function koaClassicServer(
                     fileStat = await fs.promises.stat(toOpen);
                 } catch (error) {
                     _logger.error('File stat error:', error);
-                    sendNotFound(ctx);
+                    await sendErrorPage(ctx, 404);
                     return;
                 }
             }
@@ -1938,7 +2128,7 @@ module.exports = function koaClassicServer(
                 }
             }
 
-            if (await tryRenderTemplate(ctx, next, toOpen, rawBuffer, options.template, _logger)) {
+            if (await tryRenderTemplate(ctx, next, toOpen, rawBuffer, options.template, _logger, sendErrorPage)) {
                 return;
             }
 
@@ -1974,7 +2164,7 @@ module.exports = function koaClassicServer(
                     await fs.promises.access(toOpen, fs.constants.R_OK);
                 } catch (error) {
                     _logger.error('File access error:', error);
-                    sendNotFound(ctx);
+                    await sendErrorPage(ctx, 404);
                     return;
                 }
             }
@@ -2078,10 +2268,7 @@ module.exports = function koaClassicServer(
                                 const src = fs.createReadStream(toOpen, { start, end });
                                 src.on('error', (err) => {
                                     _logger.error('Stream error:', err);
-                                    if (!ctx.headerSent) {
-                                        ctx.status = 500;
-                                        ctx.body = 'Error reading file';
-                                    }
+                                    if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                                 });
                                 ctx.body = src;
                             }
@@ -2110,11 +2297,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 +2320,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) sendErrorPageSync(ctx, 500);
+                            });
+                        } 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
@@ -2173,7 +2451,7 @@ module.exports = function koaClassicServer(
                                     const src = fs.createReadStream(toOpen);
                                     src.on('error', (streamErr) => {
                                         _logger.error('Stream error:', streamErr);
-                                        if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
+                                        if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                                     });
                                     ctx.body = src;
                                 } else {
@@ -2195,26 +2473,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
@@ -2241,7 +2503,7 @@ module.exports = function koaClassicServer(
                         const src = fs.createReadStream(toOpen);
                         src.on('error', (err) => {
                             _logger.error('Stream error:', err);
-                            if (!ctx.headerSent) { ctx.status = 500; ctx.body = 'Error reading file'; }
+                            if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                         });
                         ctx.body = src;
                     } else {
@@ -2592,3 +2854,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.2.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",