koa-classic-server 3.1.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 } = require('stream');
+const { Readable, Transform, pipeline } = require('stream');
 
 const _brotliCompressAsync = util.promisify(zlib.brotliCompress);
 const _gzipAsync           = util.promisify(zlib.gzip);
@@ -151,6 +151,7 @@ function buildErrorHtml(title, heading, message) {
 const _NOT_FOUND_HTML       = buildErrorHtml('URL not found',         'Not Found',             'The requested URL was not found on this server.');
 const _GATEWAY_TIMEOUT_HTML = buildErrorHtml('Gateway Timeout',       'Gateway Timeout',       'The template took too long to render.');
 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);
@@ -192,6 +193,23 @@ function warnPayload(logger, message) {
         : [message];
 }
 
+// Config-deprecation warnings, deduplicated once-per-process (per distinct
+// message) so creating many middleware instances doesn't repeat the same nag —
+// same intent as the _showDirContentsDeprecationWarned flag, generalized to
+// multiple messages. These options (urlPrefix, urlsReserved, ...) are v2-stable,
+// so a malformed value is TOLERATED with a warning for now rather than thrown:
+// throwing on a stable option would be a breaking change on a minor upgrade.
+// The next major will flip `warnConfigDeprecation` into a hard throw (the call
+// sites already carry the final message) — see docs/revisione_codice_v3.1.md #11.
+const _configDeprecationsWarned = new Set();
+function warnConfigDeprecation(logger, message) {
+    if (_configDeprecationsWarned.has(message)) return;
+    _configDeprecationsWarned.add(message);
+    logger.warn(...warnPayload(logger,
+        '[koa-classic-server] DEPRECATION: ' + message +
+        '\n  This is tolerated for now and WILL throw in a future major version.'));
+}
+
 // 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).
@@ -387,6 +405,24 @@ function parseRangeHeader(rangeHeader, fileSize) {
     return { start, end };
 }
 
+// Evaluate an If-None-Match header against our (strong) ETag, per RFC 9110 §13.1.2.
+// The header is either "*" (matches any existing representation) or a comma-separated
+// list of entity-tags. The comparison is the WEAK function: a leading "W/" is ignored
+// on both sides (a proxy/CDN may have weakened the validator). Returns true when the
+// precondition is satisfied, i.e. the client's cached representation is still current
+// and the server should answer 304 (Not Modified) for a GET/HEAD.
+function ifNoneMatchSatisfied(headerValue, etag) {
+    if (!headerValue) return false;
+    const trimmed = headerValue.trim();
+    if (trimmed === '*') return true; // "*" matches any existing representation
+    const target = etag.replace(/^W\//, ''); // our ETag is strong, but strip defensively
+    for (const part of trimmed.split(',')) {
+        const tag = part.trim().replace(/^W\//, '');
+        if (tag && tag === target) return true;
+    }
+    return false;
+}
+
 // LFU cache with O(1) eviction using frequency buckets.
 // peek(key)  — read without touching frequency (for staleness checks)
 // get(key)   — read and increment frequency
@@ -420,10 +456,17 @@ class LFUCache {
     }
 
     set(key, entry) {
+        // An entry larger than the whole cache can never fit: bail out BEFORE the
+        // eviction loop, otherwise it would flush every other entry for nothing.
+        // Warn (throttled) so the operator learns the cache is undersized for
+        // this file instead of it silently never being cached.
+        if (entry.buffer.length > this.maxSize) {
+            this._warnThrottled(`[koa-classic-server] serverCache.${this.cacheLabel}: entry of ${entry.buffer.length} bytes exceeds maxSize (${this.maxSize} bytes) and will never be cached. Consider increasing maxSize.`);
+            return;
+        }
         while (this.currentSize + entry.buffer.length > this.maxSize && this._keyMap.size > 0) {
             this._evictOne();
         }
-        if (this.currentSize + entry.buffer.length > this.maxSize) return; // entry too large for cache
 
         this._keyMap.set(key, { ...entry, freq: 1 });
         this._addToFreqBucket(key, 1);
@@ -499,20 +542,60 @@ class LFUCache {
         bucket.delete(evictKey);
         if (bucket.size === 0) this._freqMap.delete(this._minFreq);
 
-        if (this.warnInterval !== false) {
-            const now = Date.now();
-            if (now - this._lastWarnAt >= this.warnInterval) {
-                this.logger.warn(`[koa-classic-server] serverCache.${this.cacheLabel}: maxSize reached, evicting LFU entries. Consider increasing maxSize.`);
-                this._lastWarnAt = now;
-            }
+        this._warnThrottled(`[koa-classic-server] serverCache.${this.cacheLabel}: maxSize reached, evicting LFU entries. Consider increasing maxSize.`);
+    }
+
+    // Emits a warning at most once per warnInterval ms (0 = always, false = never).
+    _warnThrottled(message) {
+        if (this.warnInterval === false) return;
+        const now = Date.now();
+        if (now - this._lastWarnAt >= this.warnInterval) {
+            this.logger.warn(message);
+            this._lastWarnAt = now;
         }
     }
 }
 
+// Single-flight job map helper: joins the in-flight job for `key`, or starts
+// `work()` as the leader. Concurrent callers share the same Promise — including
+// a rejection, so on failure every waiter falls back together instead of
+// re-running the work. The entry is removed as soon as the job settles
+// (success or failure), so the next request after a failure retries from
+// scratch and the map only ever holds jobs actually in progress.
+function singleFlight(map, key, work) {
+    let job = map.get(key);
+    if (!job) {
+        job = work();
+        map.set(key, job);
+        const clean = () => map.delete(key);
+        job.then(clean, clean);
+    }
+    return job;
+}
+
 // Upserts a fresh entry into an LFUCache. When the previous entry was only
 // 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
@@ -560,16 +643,36 @@ module.exports = function koaClassicServer(
                                         //   when visible entries > entriesPerPage. Page index via
                                         //   ?page=N (0-based); out-of-range values are clamped silently.
                                         //   Must be a finite integer >= 0; 0 = disabled (no pagination).
+            trailingSlash: true,        // Canonical trailing-slash enforcement (V4). Default true:
+                                        //   GET /dir  (directory, no slash) → 301 redirect to /dir/
+                                        //   GET /file/ (file, trailing slash) → 404
+                                        //   so relative links in an index page resolve against the
+                                        //   directory. Set false for the v3 behavior (serve directories
+                                        //   and files regardless of the trailing slash).
         },
-        index: ["index.html"], // Index file name(s) - must be an ARRAY:
-                               //   - Array of strings: ["index.html", "index.htm", "default.html"]
-                               //   - Array of RegExp:  [/index\.html/i, /default\.(html|htm)/i]
-                               //   - Mixed array:      ["index.html", /index\.[eE][jJ][sS]/]
-                               // Priority is determined by array order (first match wins)
-        urlPrefix: "", // URL path prefix
-        urlsReserved: [], // Reserved paths (first level only)
+        index: [], // Index file name(s) - must be an ARRAY.
+                   // Default: [] — no index file is looked up; directories always
+                   // show the listing (when dirListing.enabled). Configure explicitly
+                   // for the classic index-file behavior, e.g. ["index.html"].
+                   //   - Array of strings: ["index.html", "index.htm", "default.html"]
+                   //   - Array of RegExp:  [/index\.html/i, /default\.(html|htm)/i]
+                   //   - Mixed array:      ["index.html", /index\.[eE][jJ][sS]/]
+                   // Priority is determined by array order (first match wins)
+        urlPrefix: "", // URL path prefix. Should start with "/" and NOT end with "/"
+                       //   (e.g. "/static"); "" disables the prefix. A malformed value
+                       //   is tolerated with a deprecation warning for now (behavior
+                       //   unchanged) and WILL throw in the next major version.
+        urlsReserved: [], // Reserved first-level paths passed through to next().
+                          //   Each entry should be a single first-level path: a leading
+                          //   "/" plus one segment, no further "/" (e.g. "/admin").
+                          //   Malformed entries are tolerated with a deprecation warning
+                          //   for now and WILL throw in the next major version (a
+                          //   non-string entry is dropped to avoid a per-request 500).
         template: {
             render: undefined, // Template rendering function: async (ctx, next, filePath, rawBuffer, signal) => {}
+                               // rawBuffer (4th arg, may be null) is READ-ONLY: the same Buffer
+                               // instance is shared with the server cache and with concurrent
+                               // requests — mutating it corrupts other responses.
             ext: [], // File extensions to process with template.render
             renderTimeout: 30000, // Max ms allowed for template.render (number ≥ 0; 0 = disabled).
                                   // On timeout responds 504 Gateway Timeout. The render receives an
@@ -628,6 +731,19 @@ module.exports = function koaClassicServer(
             enabled: true,                // master switch (false = disable all compression)
             encodings: ['br', 'gzip'],    // algorithms in priority order; [] = disable
             minFileSize: 1024,            // min file size in bytes to compress; false = no minimum
+            maxFileSize: 10485760,        // max file size (bytes) for the buffered high-quality
+                                          //   compression path (whole file in RAM → brotli Q11 →
+                                          //   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 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
@@ -656,8 +772,31 @@ module.exports = function koaClassicServer(
 
     const normalizedRootDir = path.resolve(rootDir);
 
-    const options = opts || {};
-    options.template = opts.template || {};
+    // Options must be a plain object, or omitted entirely (the `opts = {}`
+    // default covers undefined). An explicit null — or any other non-object —
+    // is a configuration bug: surface it with a helpful error instead of a raw
+    // TypeError further down (or, worse, a silent fall-through to defaults).
+    if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+        throw new Error(
+            '[koa-classic-server] options must be a plain object (or omitted entirely). Got: ' +
+            (opts === null ? 'null' : Array.isArray(opts) ? 'an array' : typeof opts)
+        );
+    }
+
+    // Work on a copy: the factory normalizes options in place and must never
+    // mutate the caller's configuration object (reusing one config for two
+    // instances, or inspecting it after startup, would otherwise observe the
+    // rewritten values). Only the two nested objects the normalization writes
+    // into need their own copy — template (render/ext/renderTimeout) and
+    // hideExtension (ext/redirect); every other namespace is only read and
+    // normalized into new internal structures.
+    const options = { ...opts };
+    options.template = (opts.template && typeof opts.template === 'object' && !Array.isArray(opts.template))
+        ? { ...opts.template }
+        : {};
+    if (options.hideExtension && typeof options.hideExtension === 'object' && !Array.isArray(options.hideExtension)) {
+        options.hideExtension = { ...options.hideExtension };
+    }
 
     const _logger = normalizeLogger(options.logger);
 
@@ -732,6 +871,15 @@ module.exports = function koaClassicServer(
             'dirListing.entriesPerPage',
             100
         ),
+        // Canonical trailing-slash enforcement (V4). Default ON:
+        //   - GET /dir  (directory, no slash) → 301 redirect to /dir/
+        //   - GET /file/ (file, trailing slash) → 404
+        // so relative links in an index page resolve against the directory and
+        // a file is only reachable at its slash-less URL. Set false to keep the
+        // v3 behavior (serve directories and files regardless of trailing slash).
+        trailingSlash: userDirListing && userDirListing.trailingSlash !== undefined
+            ? !!userDirListing.trailingSlash
+            : true,
     };
 
     // Normalize index option to array format
@@ -755,9 +903,68 @@ module.exports = function koaClassicServer(
         options.index = [];
     }
 
-    options.urlPrefix = typeof options.urlPrefix === 'string' ? options.urlPrefix : "";
+    // ── urlPrefix / urlsReserved validation (V3.1, deprecation-warn) ──
+    // The request-time matcher depends on an implicit format for both options,
+    // and a malformed value fails SILENTLY: a urlPrefix with a stray
+    // leading/trailing slash makes the middleware serve nothing (it always falls
+    // through to next()), and a urlsReserved entry without a leading slash makes
+    // the reservation never match (the path is served instead of passed on).
+    // Both are v2-stable options, so instead of throwing (a breaking change on a
+    // minor upgrade — a mis-slashed value that "worked" only by falling through
+    // to a downstream handler would suddenly change behavior), we WARN and leave
+    // the runtime behavior exactly as it is today. The next major turns these
+    // warnings into throws. The one exception is a non-string urlsReserved entry:
+    // it would 500 on every request (value.substring is not a function), which is
+    // not working behavior, so it is dropped defensively (still warned).
+    if (options.urlPrefix === undefined) {
+        options.urlPrefix = "";
+    } else if (typeof options.urlPrefix !== 'string') {
+        // Unchanged behavior: pre-existing code already coerced non-string → "".
+        warnConfigDeprecation(_logger,
+            'urlPrefix should be a string like "/static" (or "" for no prefix); got ' +
+            (options.urlPrefix === null ? 'null' : typeof options.urlPrefix) + ' — treating it as "".');
+        options.urlPrefix = "";
+    } else if (options.urlPrefix !== "" && (!options.urlPrefix.startsWith('/') || options.urlPrefix.endsWith('/'))) {
+        // Left as-is: the matcher behaves exactly as today (falls through to
+        // next() under this prefix). Warn only — no behavior change.
+        warnConfigDeprecation(_logger,
+            'urlPrefix should start with "/" and not end with "/" (use "" to disable); got ' +
+            JSON.stringify(options.urlPrefix) + ' — it will not route correctly until corrected.');
+    }
     const _urlPrefixParts = options.urlPrefix.split("/");
-    options.urlsReserved = Array.isArray(options.urlsReserved) ? options.urlsReserved : [];
+
+    if (options.urlsReserved === undefined) {
+        options.urlsReserved = [];
+    } else if (!Array.isArray(options.urlsReserved)) {
+        // Unchanged behavior: pre-existing code already coerced non-array → [].
+        warnConfigDeprecation(_logger,
+            'urlsReserved should be an array of first-level paths like ["/admin"]; got ' +
+            (options.urlsReserved === null ? 'null' : typeof options.urlsReserved) + ' — treating it as [].');
+        options.urlsReserved = [];
+    } else {
+        const cleaned = [];
+        for (const value of options.urlsReserved) {
+            if (typeof value !== 'string') {
+                // Dropped defensively: a non-string entry would throw at match
+                // time (value.substring is not a function) → a 500 on every
+                // request. Dropping it can't break working code.
+                warnConfigDeprecation(_logger,
+                    'urlsReserved entries must be strings like "/admin"; dropping a non-string (' +
+                    (value === null ? 'null' : typeof value) + ') entry.');
+                continue;
+            }
+            // Malformed but non-crashing (missing leading slash, extra segment,
+            // trailing slash, empty): kept as-is so the matcher behaves exactly
+            // as today (it simply won't match). Warn only.
+            if (value === '' || !value.startsWith('/') || value.indexOf('/', 1) !== -1) {
+                warnConfigDeprecation(_logger,
+                    'each urlsReserved entry should be a single first-level path — a leading "/" plus one ' +
+                    'segment, e.g. "/admin"; got ' + JSON.stringify(value) + ' — it will not match until corrected.');
+            }
+            cleaned.push(value);
+        }
+        options.urlsReserved = cleaned;
+    }
     options.template.render = (options.template.render === undefined || typeof options.template.render === 'function') ? options.template.render : undefined;
     options.template.ext = Array.isArray(options.template.ext) ? options.template.ext : [];
 
@@ -788,7 +995,21 @@ module.exports = function koaClassicServer(
         );
     }
 
-    options.browserCacheMaxAge = typeof options.browserCacheMaxAge === 'number' && options.browserCacheMaxAge >= 0 ? options.browserCacheMaxAge : 3600;
+    // browserCacheMaxAge: non-negative integer seconds. An invalid value (negative, NaN,
+    // non-integer, Infinity, or a string) previously fell back to 3600 SILENTLY (#12).
+    // Consistent with #11: warn now and keep the fallback; a future major will throw
+    // (validateNonNegativeInt semantics) — so what warns here is exactly what will throw then.
+    if (options.browserCacheMaxAge === undefined) {
+        options.browserCacheMaxAge = 3600;
+    } else if (!(typeof options.browserCacheMaxAge === 'number'
+        && Number.isInteger(options.browserCacheMaxAge)
+        && options.browserCacheMaxAge >= 0)) {
+        warnConfigDeprecation(_logger,
+            'browserCacheMaxAge must be a non-negative integer (seconds). Got: ' +
+            String(options.browserCacheMaxAge) + '. Falling back to the default 3600 for now.');
+        options.browserCacheMaxAge = 3600;
+    }
+    // else: valid — keep as-is
     options.browserCacheEnabled = typeof options.browserCacheEnabled === 'boolean' ? options.browserCacheEnabled : false;
     options.useOriginalUrl = typeof options.useOriginalUrl === 'boolean' ? options.useOriginalUrl : true;
 
@@ -1012,6 +1233,7 @@ module.exports = function koaClassicServer(
                 enabled: true,
                 encodings: ['br', 'gzip'],              // priority order: brotli first, gzip as fallback
                 minFileSize: 1024,                      // bytes; skip compression for files smaller than this
+                maxFileSize: 10485760,                  // bytes; above this the buffered+cached path is skipped (streaming instead)
                 mimeTypes: new Set(DEFAULT_COMPRESSIBLE_MIME_TYPES),
             };
         }
@@ -1034,11 +1256,17 @@ module.exports = function koaClassicServer(
         const minFileSize = compression.minFileSize === false ? false
             : (typeof compression.minFileSize === 'number' && compression.minFileSize >= 0 ? compression.minFileSize : 1024);
 
+        // Cap for the buffered (whole-file-in-RAM, max-quality, cached) compression
+        // path. false = no cap. Files above the cap still get compressed via the
+        // bounded-RAM streaming mode — safety net, not a serving restriction.
+        const maxFileSize = compression.maxFileSize === false ? false
+            : (typeof compression.maxFileSize === 'number' && compression.maxFileSize > 0 ? compression.maxFileSize : 10485760);
+
         const mimeTypes = Array.isArray(compression.mimeTypes) && compression.mimeTypes.length > 0
             ? compression.mimeTypes
             : DEFAULT_COMPRESSIBLE_MIME_TYPES;
 
-        return { enabled, encodings, minFileSize, mimeTypes: new Set(mimeTypes) };
+        return { enabled, encodings, minFileSize, maxFileSize, mimeTypes: new Set(mimeTypes) };
     }
 
     // Normalize and validate the serverCache option into a clean internal structure.
@@ -1207,12 +1435,71 @@ module.exports = function koaClassicServer(
         _logger
     );
 
-    // Returns the client's preferred encoding based on Accept-Encoding header,
-    // filtered against the enabled encodings list. Returns null if no match.
+    // Single-flight maps for cache population (thundering-herd protection):
+    // N concurrent misses on the same key share ONE read (+ compression) instead
+    // of N duplicated jobs. Entries live only while a job is in flight. Keys
+    // include the stat'd mtime+size so requests that observed different versions
+    // of the file never share a job (each response stays coherent with its own
+    // 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
+    // Accept-Encoding q-values are used only to EXCLUDE encodings the client refuses
+    // (q=0), per RFC 9110 §12.5.3. Token match is exact, not substring ("x-gzip" is
+    // NOT "gzip"). A "*" supplies the q-value for any encoding not explicitly listed.
     function getClientEncoding(acceptEncoding) {
         if (!acceptEncoding) return null;
+        const qValues = new Map(); // token → q-value
+        for (const part of acceptEncoding.split(',')) {
+            const [tokenRaw, ...params] = part.split(';');
+            const token = tokenRaw.trim().toLowerCase();
+            if (!token) continue;
+            let q = 1;
+            for (const p of params) {
+                const m = /^\s*q=(\d+(?:\.\d+)?)\s*$/i.exec(p);
+                if (m) q = parseFloat(m[1]);
+            }
+            qValues.set(token, q);
+        }
+        const star = qValues.get('*');
         for (const enc of compressionConfig.encodings) {
-            if (acceptEncoding.includes(enc)) return enc;
+            let q = qValues.get(enc);
+            if (q === undefined) q = star;   // not listed → fall back to "*" if present
+            if (q === undefined) continue;   // not listed and no "*" → not offered
+            if (q > 0) return enc;           // acceptable → pick it (server preference order)
         }
         return null;
     }
@@ -1308,6 +1595,14 @@ module.exports = function koaClassicServer(
         const urlToUse = options.useOriginalUrl ? ctx.originalUrl : ctx.url;
         const _origin  = ctx.protocol + '://' + ctx.host;
         const fullUrl  = _origin + urlToUse;
+
+        // Whether the client's request path ends with "/" — captured from the
+        // raw originalUrl BEFORE the trailing slash is stripped for URL parsing
+        // below. Drives the canonical trailing-slash redirect / 404 in the
+        // directory / file branch. "/" (root) counts as ending with a slash, so
+        // it is already canonical and never redirects.
+        const _rawOriginalPath = ctx.originalUrl.split('?')[0];
+        const _pathEndsWithSlash = _rawOriginalPath.endsWith('/');
         // Parse the request URL. `new URL()` throws on an invalid Host header
         // (e.g. "Host: bad host") — reject as 400 rather than letting it surface as 500.
         let pageHref = '';
@@ -1357,194 +1652,291 @@ module.exports = function koaClassicServer(
             }
         }
 
-        // Path traversal protection: build and validate safe file path
-        let requestedPath = "";
-        if (pageHrefOutPrefix.pathname === "/") {
-            requestedPath = "";
-        } else {
-            // decodeURIComponent() throws URIError on malformed percent-encoding
-            // (e.g. "/%", "/%zz", a truncated UTF-8 sequence) — reject as 400
-            // rather than letting it surface as an unhandled 500.
-            try {
-                requestedPath = decodeURIComponent(pageHrefOutPrefix.pathname);
-            } catch {
+        // From this point on the middleware OWNS the request: every early
+        // pass-through above has already returned, and no next() is called below
+        // (the template render's next goes through tryRenderTemplate's own catch).
+        // Last-resort net: an unexpected failure on any unguarded path must not
+        // leak to Koa's default handler (a plain-text 500 without the middleware's
+        // security headers, logged outside the operator's `logger`). Errors from
+        // downstream middleware are NOT masked — they never reach this try.
+        try {
+            // Path traversal protection: build and validate safe file path
+            let requestedPath = "";
+            if (pageHrefOutPrefix.pathname === "/") {
+                requestedPath = "";
+            } else {
+                // decodeURIComponent() throws URIError on malformed percent-encoding
+                // (e.g. "/%", "/%zz", a truncated UTF-8 sequence) — reject as 400
+                // rather than letting it surface as an unhandled 500.
+                try {
+                    requestedPath = decodeURIComponent(pageHrefOutPrefix.pathname);
+                } catch {
+                    sendBadRequest(ctx);
+                    return;
+                }
+            }
+
+            // Null byte guard: path.normalize() throws ERR_INVALID_ARG_VALUE for paths
+            // containing \0. Reject early with 400 Bad Request before it reaches fs calls.
+            if (requestedPath.includes('\0')) {
                 sendBadRequest(ctx);
                 return;
             }
-        }
 
-        // Null byte guard: path.normalize() throws ERR_INVALID_ARG_VALUE for paths
-        // containing \0. Reject early with 400 Bad Request before it reaches fs calls.
-        if (requestedPath.includes('\0')) {
-            sendBadRequest(ctx);
-            return;
-        }
-
-        const normalizedPath = path.normalize(requestedPath);
-        const fullPath = path.join(normalizedRootDir, normalizedPath);
-
-        // Security check: ensure resolved path is within rootDir. Uses the shared
-        // _isWithinRoot() helper, which is boundary-aware: it matches rootDir exactly
-        // or rootDir + path.sep, never a sibling (e.g. /srv/wwwsecret for root /srv/www) —
-        // hardened defense in depth against a future change to how fullPath is built.
-        // Covers: ../ traversal, URL-encoded variants (%2e%2e%2f), and on Windows
-        // backslash sequences (path.normalize converts \ to / before the check).
-        // 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);
-            return;
-        }
+            const normalizedPath = path.normalize(requestedPath);
+            const fullPath = path.join(normalizedRootDir, normalizedPath);
+
+            // Security check: ensure resolved path is within rootDir. Uses the shared
+            // _isWithinRoot() helper, which is boundary-aware: it matches rootDir exactly
+            // or rootDir + path.sep, never a sibling (e.g. /srv/wwwsecret for root /srv/www) —
+            // hardened defense in depth against a future change to how fullPath is built.
+            // Covers: ../ traversal, URL-encoded variants (%2e%2e%2f), and on Windows
+            // backslash sequences (path.normalize converts \ to / before the check).
+            // 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);
+                return;
+            }
 
-        // Hidden check: block requests that traverse a hidden directory.
-        // Stops at length-1 because the leaf (the file or dir being served) is
-        // checked separately by the file/listing path with its real stat.isDirectory().
-        if (requestedPath !== '') {
-            const segments = normalizedPath.split(path.sep).filter(Boolean);
-            for (let i = 0; i < segments.length - 1; i++) {
-                const segName = segments[i];
-                const segRelPath = segments.slice(0, i + 1).join('/');
-                if (isHiddenEntry(segName, segRelPath, true)) {
-                    sendNotFound(ctx);
-                    return;
+            // Hidden check: block requests that traverse a hidden directory.
+            // Stops at length-1 because the leaf (the file or dir being served) is
+            // checked separately by the file/listing path with its real stat.isDirectory().
+            if (requestedPath !== '') {
+                const segments = normalizedPath.split(path.sep).filter(Boolean);
+                for (let i = 0; i < segments.length - 1; i++) {
+                    const segName = segments[i];
+                    const segRelPath = segments.slice(0, i + 1).join('/');
+                    if (isHiddenEntry(segName, segRelPath, true)) {
+                        sendNotFound(ctx);
+                        return;
+                    }
                 }
             }
-        }
 
-        let toOpen = fullPath;
-
-        // hideExtension logic: redirect URLs with extension and resolve clean URLs
-        if (options.hideExtension) {
-            const hideExt = options.hideExtension.ext;
-            const hideRedirect = options.hideExtension.redirect;
-
-            // Trailing slash check via string — avoids a full new URL() construction
-            const rawPath = urlToUse.split('?')[0];
-            const hadTrailingSlash = rawPath.length > 1 && rawPath.endsWith('/');
-
-            // Strip a trailing slash before the extension check so URLs like /foo.html/
-            // still match (the slash is URL formality, not part of the filename) — without
-            // this, /foo.html/ would skip the redirect and 404 trying to open it as a dir.
-            const pathForExtCheck = hadTrailingSlash ? rawPath.slice(0, -1) : requestedPath;
-            if (pathForExtCheck.endsWith(hideExt)) {
-                // Build redirect target using ctx.originalUrl (always, regardless of useOriginalUrl)
-                const originalUrlObj = new URL(_origin + ctx.originalUrl);
-                let redirectPath = originalUrlObj.pathname;
-
-                // Collapse leading slashes: a Location header starting with "//" (or "/\")
-                // is a protocol-relative URL and would let "GET //evil.com/foo.ejs" redirect
-                // off-origin. path.normalize() upstream already collapses these for the
-                // filesystem check, so the source-of-truth URL has a single leading slash.
-                if (redirectPath.length > 1 && (redirectPath.charCodeAt(1) === 0x2F || redirectPath.charCodeAt(1) === 0x5C)) {
-                    redirectPath = '/' + redirectPath.replace(/^[/\\]+/, '');
-                }
+            let toOpen = fullPath;
+
+            // hideExtension logic: redirect URLs with extension and resolve clean URLs
+            if (options.hideExtension) {
+                const hideExt = options.hideExtension.ext;
+                const hideRedirect = options.hideExtension.redirect;
+
+                // Trailing slash check via string — avoids a full new URL() construction
+                const rawPath = urlToUse.split('?')[0];
+                const hadTrailingSlash = rawPath.length > 1 && rawPath.endsWith('/');
+
+                // Model B (V4): an extension URL is canonicalized to its clean form only when it
+                // has NO trailing slash. A trailing slash means directory intent, so /foo.ejs/
+                // falls through to the file/dir dispatch, where a file requested with a trailing
+                // slash is a 404 (finding #3). We gate on _pathEndsWithSlash — the very flag that
+                // #3's file-branch 404 uses — so "skip the redirect" and "404 downstream" are the
+                // same condition. requestedPath is decoded (and already slash-stripped by the URL
+                // parse), so a percent-encoded dot (/foo%2Eejs → /foo.ejs) matches consistently (#14),
+                // while /foo%2Eejs/ is excluded here by _pathEndsWithSlash and 404s downstream.
+                if (!_pathEndsWithSlash && requestedPath.endsWith(hideExt)) {
+                    // Build redirect target using ctx.originalUrl (always, regardless of
+                    // useOriginalUrl). With useOriginalUrl: false the URL-parsing prologue
+                    // validated ctx.url (the rewritten one), NOT originalUrl — a malformed
+                    // originalUrl (e.g. an absolute-form request target, legal in HTTP/1.1)
+                    // makes this constructor throw. Same treatment as the other malformed
+                    // client input: 400 Bad Request, not an unhandled error.
+                    let originalUrlObj;
+                    try {
+                        originalUrlObj = new URL(_origin + ctx.originalUrl);
+                    } catch {
+                        sendBadRequest(ctx);
+                        return;
+                    }
 
-                redirectPath = redirectPath.slice(0, redirectPath.length - hideExt.length);
-
-                // Special case: /index.ejs → /, /sezione/index.ejs → /sezione/
-                const baseName = path.basename(redirectPath);
-                // Check if the remaining path points to an index file
-                if (options.index && options.index.length > 0) {
-                    for (const pattern of options.index) {
-                        if (typeof pattern === 'string' && (baseName + hideExt) === pattern) {
-                            // Redirect to the directory (with trailing slash)
-                            redirectPath = redirectPath.slice(0, redirectPath.length - baseName.length);
-                            break;
+                    // Build the clean target in DECODED space: the extension may be percent-encoded
+                    // in the raw URL (e.g. "%2Eejs"), so decoding first makes it literal and
+                    // sliceable, then we re-encode per segment (#14, #20). The URL constructor
+                    // already validated the encoding, so decodeURIComponent cannot throw — but
+                    // guard for symmetry with the other malformed-client-input guards.
+                    let decodedPath;
+                    try {
+                        decodedPath = decodeURIComponent(originalUrlObj.pathname);
+                    } catch {
+                        sendBadRequest(ctx);
+                        return;
+                    }
+
+                    let cleanPath = decodedPath.slice(0, decodedPath.length - hideExt.length);
+
+                    // Special case: /index.ejs → /, /sezione/index.ejs → /sezione/
+                    const baseName = path.basename(cleanPath);
+                    if (options.index && options.index.length > 0) {
+                        for (const pattern of options.index) {
+                            if (typeof pattern === 'string' && (baseName + hideExt) === pattern) {
+                                // Redirect to the directory (with trailing slash)
+                                cleanPath = cleanPath.slice(0, cleanPath.length - baseName.length);
+                                break;
+                            }
                         }
                     }
-                }
 
-                // Preserve query string
-                const redirectUrl = redirectPath + (originalUrlObj.search || '');
+                    // Re-encode per path segment: round-trips spaces, "%", etc. back into a valid
+                    // URL. encodeURIComponent may over-encode sub-delims in exotic filenames, but
+                    // the result always resolves to the same path.
+                    let redirectPath = cleanPath.split('/').map(encodeURIComponent).join('/');
+
+                    // Open-redirect guard LAST: a Location starting with "//" (or "/\") is a
+                    // protocol-relative URL that would navigate off-origin ("GET //evil.com/foo.ejs").
+                    // Placed after re-encoding because a decoded "%2F" can reintroduce a leading
+                    // "//"; collapse any run of leading slashes/backslashes to a single slash.
+                    if (redirectPath.length > 1 && (redirectPath.charCodeAt(1) === 0x2F || redirectPath.charCodeAt(1) === 0x5C)) {
+                        redirectPath = '/' + redirectPath.replace(/^[/\\]+/, '');
+                    }
 
-                ctx.status = hideRedirect;
-                ctx.redirect(redirectUrl);
-                return;
-            }
+                    // Preserve query string
+                    const redirectUrl = redirectPath + (originalUrlObj.search || '');
 
-            // Check if URL has no extension → try adding the configured extension
-            // Skip if original URL had trailing slash (trailing slash = directory intent)
-            const extOfRequested = path.extname(requestedPath);
-            if (!extOfRequested && requestedPath !== '' && !requestedPath.endsWith('/') && !hadTrailingSlash) {
-                const pathWithExt = fullPath + hideExt;
+                    ctx.status = hideRedirect;
+                    ctx.redirect(redirectUrl);
+                    return;
+                }
 
-                // Security check: ensure resolved path is still within rootDir (boundary-aware)
-                if (_isWithinRoot(pathWithExt, normalizedRootDir)) {
-                    try {
-                        const statWithExt = await fs.promises.stat(pathWithExt);
-                        if (statWithExt.isFile()) {
-                            // File with extension exists, serve it
-                            toOpen = pathWithExt;
+                // Check if URL has no extension → try adding the configured extension
+                // Skip if original URL had trailing slash (trailing slash = directory intent)
+                const extOfRequested = path.extname(requestedPath);
+                if (!extOfRequested && requestedPath !== '' && !requestedPath.endsWith('/') && !hadTrailingSlash) {
+                    const pathWithExt = fullPath + hideExt;
+
+                    // Security check: ensure resolved path is still within rootDir (boundary-aware)
+                    if (_isWithinRoot(pathWithExt, normalizedRootDir)) {
+                        try {
+                            const statWithExt = await fs.promises.stat(pathWithExt);
+                            if (statWithExt.isFile()) {
+                                // File with extension exists, serve it
+                                toOpen = pathWithExt;
+                            }
+                        } catch {
+                            // File with extension doesn't exist, continue normal flow
                         }
-                    } catch {
-                        // File with extension doesn't exist, continue normal flow
                     }
                 }
             }
-        }
 
-        // Check if path exists
-        let stat;
-        try {
-            stat = await fs.promises.stat(toOpen);
-        } catch {
-            // File/directory doesn't exist or can't be accessed
-            sendNotFound(ctx);
-            return;
-        }
+            // Check if path exists
+            let stat;
+            try {
+                stat = await fs.promises.stat(toOpen);
+            } catch {
+                // File/directory doesn't exist or can't be accessed
+                sendNotFound(ctx);
+                return;
+            }
+
+            // Hidden check: block access to the requested file or directory itself
+            if (requestedPath !== '') {
+                const entryName = path.basename(toOpen);
+                const entryRelPath = path.relative(normalizedRootDir, toOpen).split(path.sep).join('/');
+                if (isHiddenEntry(entryName, entryRelPath, stat.isDirectory())) {
+                    sendNotFound(ctx);
+                    return;
+                }
+            }
 
-        // Hidden check: block access to the requested file or directory itself
-        if (requestedPath !== '') {
-            const entryName = path.basename(toOpen);
-            const entryRelPath = path.relative(normalizedRootDir, toOpen).split(path.sep).join('/');
-            if (isHiddenEntry(entryName, entryRelPath, stat.isDirectory())) {
+            // Symlink boundary check (V-1): in protected modes reject any requested file
+            // or directory whose realpath escapes rootDir (or, in 'deny' mode, any symlink
+            // 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);
                 return;
             }
-        }
 
-        // Symlink boundary check (V-1): in protected modes reject any requested file
-        // or directory whose realpath escapes rootDir (or, in 'deny' mode, any symlink
-        // 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);
-            return;
-        }
+            if (stat.isDirectory()) {
+                // Handle directory
+                if (options.dirListing.enabled) {
+                    // Canonical trailing-slash redirect (V4): a directory URL
+                    // without a trailing slash serves an index/listing whose
+                    // relative links would resolve against the parent. Redirect
+                    // /dir → /dir/ (301) BEFORE serving so the browser's base is
+                    // the directory itself.
+                    if (options.dirListing.trailingSlash && !_pathEndsWithSlash) {
+                        // Build the Location from the parsed originalUrl (same
+                        // defense as the hideExtension redirect): re-parsing forces
+                        // the target to be origin-relative — an absolute-form
+                        // request target (`GET http://evil/x`, legal in HTTP/1.1
+                        // and reachable under useOriginalUrl:false + rewriting)
+                        // would otherwise become an off-origin `Location` (open
+                        // redirect). .pathname keeps urlPrefix and percent-encoding.
+                        let originalUrlObj;
+                        try {
+                            originalUrlObj = new URL(_origin + ctx.originalUrl);
+                        } catch {
+                            sendBadRequest(ctx);
+                            return;
+                        }
+                        // Collapse a leading "//" / "/\" (protocol-relative) to a
+                        // single slash before appending the canonical trailing one.
+                        let redirectPath = originalUrlObj.pathname;
+                        if (redirectPath.length > 1 && (redirectPath.charCodeAt(1) === 0x2F || redirectPath.charCodeAt(1) === 0x5C)) {
+                            redirectPath = '/' + redirectPath.replace(/^[/\\]+/, '');
+                        }
+                        ctx.status = 301;
+                        ctx.redirect(redirectPath + '/' + originalUrlObj.search);
+                        return;
+                    }
 
-        if (stat.isDirectory()) {
-            // Handle directory
-            if (options.dirListing.enabled) {
-                // Search for index file matching configured patterns
-                if (options.index && options.index.length > 0) {
-                    const indexFile = await findIndexFile(toOpen, options.index);
-                    if (indexFile) {
-                        const indexRelPath = path.relative(normalizedRootDir, path.join(toOpen, indexFile.name)).split(path.sep).join('/');
-                        if (!isHiddenEntry(indexFile.name, indexRelPath, false)) {
-                            const indexPath = path.join(toOpen, indexFile.name);
-                            // Symlink boundary check (V-1): an index file may itself be a
-                            // 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);
+                    // Search for index file matching configured patterns
+                    if (options.index && options.index.length > 0) {
+                        const indexFile = await findIndexFile(toOpen, options.index);
+                        if (indexFile) {
+                            const indexRelPath = path.relative(normalizedRootDir, path.join(toOpen, indexFile.name)).split(path.sep).join('/');
+                            if (!isHiddenEntry(indexFile.name, indexRelPath, false)) {
+                                const indexPath = path.join(toOpen, indexFile.name);
+                                // Symlink boundary check (V-1): an index file may itself be a
+                                // 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);
+                                    return;
+                                }
+                                await loadFile(indexPath, indexFile.stat);
                                 return;
                             }
-                            await loadFile(indexPath, indexFile.stat);
-                            return;
                         }
                     }
-                }
 
-                // No index file found, show directory listing
-                ctx.body = await show_dir(toOpen, ctx);
+                    // No index file found, show directory listing
+                    ctx.body = await show_dir(toOpen, ctx);
+                } else {
+                    // Directory listing disabled
+                    sendNotFound(ctx);
+                }
+                return;
             } else {
-                // Directory listing disabled
-                sendNotFound(ctx);
+                // Canonical trailing-slash 404 (V4): a trailing slash means
+                // "directory", but this path resolved to a FILE — a file is only
+                // reachable at its slash-less URL. Return 404 (indistinguishable
+                // 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);
+                    return;
+                }
+                await loadFile(toOpen, stat);
+                return;
             }
-            return;
-        } else {
-            await loadFile(toOpen, stat);
-            return;
+        } catch (err) {
+            _logger.error('[koa-classic-server] Unexpected error while serving the request:', err);
+            if (ctx.headerSent || ctx.res.writableEnded) {
+                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;
         }
 
         // Internal functions
@@ -1578,13 +1970,23 @@ module.exports = function koaClassicServer(
                     rawBuffer = cached.buffer;
                 } else {
                     try {
-                        rawBuffer = await fs.promises.readFile(toOpen);
-                        refreshOrInsert(_rawFileCache, toOpen, {
-                            buffer: rawBuffer,
-                            mtime: fileStat.mtime.getTime(),
-                            size: fileStat.size,
-                            insertedAt: Date.now(),
-                        }, cached, staleByAge);
+                        // Single-flight: concurrent misses on the same path share one
+                        // readFile + cache insert; only the leader (the closure below)
+                        // runs, waiters await the same Promise. The key includes the
+                        // stat'd mtime+size so a request that observed a DIFFERENT
+                        // version of the file starts its own job instead of adopting
+                        // bytes that don't match the validators it will emit.
+                        const inflightKey = `${toOpen}:${fileStat.mtime.getTime()}:${fileStat.size}`;
+                        rawBuffer = await singleFlight(_inflightRawReads, inflightKey, async () => {
+                            const buf = await fs.promises.readFile(toOpen);
+                            refreshOrInsert(_rawFileCache, toOpen, {
+                                buffer: buf,
+                                mtime: fileStat.mtime.getTime(),
+                                size: fileStat.size,
+                                insertedAt: Date.now(),
+                            }, cached, staleByAge);
+                            return buf;
+                        });
                     } catch {
                         rawBuffer = null; // Fall through to disk reads later
                     }
@@ -1632,6 +2034,67 @@ module.exports = function koaClassicServer(
                 }
             }
 
+            // Determine MIME type and compression encoding for the full-file response
+            const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
+            const filename = path.basename(toOpen);
+
+            // Resolve compression: enabled + compressible MIME + meets minFileSize + client supports it
+            let encoding = null; // 'br' | 'gzip' | null
+            let potentiallyCompressible = false; // response content-negotiates on Accept-Encoding
+            if (compressionConfig.enabled && compressionConfig.encodings.length > 0) {
+                const isCompressibleMime = compressionConfig.mimeTypes.has(mimeType);
+                const meetsMinSize = compressionConfig.minFileSize === false
+                    || fileStat.size >= compressionConfig.minFileSize;
+                if (isCompressibleMime && meetsMinSize) {
+                    potentiallyCompressible = true; // even if this client gets identity
+                    encoding = getClientEncoding(ctx.get('Accept-Encoding'));
+                }
+            }
+
+            // fullEtag is encoding-specific to avoid false 304 hits across representations.
+            // Proxies use Vary: Accept-Encoding to cache separate versions per encoding.
+            const etagSuffix = encoding === 'br' ? '-br' : encoding === 'gzip' ? '-gz' : '';
+            const fullEtag = `"${fileStat.mtime.getTime()}-${fileStat.size}${etagSuffix}"`;
+
+            // Vary: Accept-Encoding as soon as the resource is *potentially* compressible —
+            // regardless of whether THIS client gets a compressed variant, and regardless
+            // of browserCacheEnabled. RFC 9110 §15.4.5: the 304 below must carry the same
+            // Vary the 200 would; and a shared proxy must not serve the identity variant to
+            // a client that would have received the compressed one (#7).
+            if (potentiallyCompressible) {
+                ctx.set('Vary', 'Accept-Encoding');
+            }
+
+            // Preconditions are evaluated BEFORE the Range branch: RFC 9110 §13.2.2 gives the
+            // validators precedence over Range (steps 3/4 before step 5), so a conditional
+            // request that matches returns 304 (Not Modified), not 206 (Partial Content).
+            // Comparison uses fullEtag (the encoding-specific representation a full GET would
+            // return); a 206 below re-tags itself with baseEtag (the identity partial it serves).
+            if (options.browserCacheEnabled) {
+                ctx.set('ETag', fullEtag);
+                ctx.set('Last-Modified', fileStat.mtime.toUTCString());
+
+                // If-None-Match: "*" | comma-list, weak comparison (RFC 9110 §13.1.2).
+                if (ifNoneMatchSatisfied(ctx.get('If-None-Match'), fullEtag)) {
+                    ctx.status = 304;
+                    return;
+                }
+
+                // If-Modified-Since (date validation). The mtime is truncated to whole seconds
+                // before comparing: Last-Modified is emitted via toUTCString() (second precision
+                // — HTTP dates have no milliseconds), so a client echoing that header back would
+                // otherwise never match a sub-second mtime (e.g. 22:13:20.500 <= 22:13:20.000).
+                const clientModifiedSince = ctx.get('If-Modified-Since');
+                if (clientModifiedSince) {
+                    const clientDate = new Date(clientModifiedSince);
+                    const mtimeSeconds = Math.floor(fileStat.mtime.getTime() / 1000) * 1000;
+                    if (mtimeSeconds <= clientDate.getTime()) {
+                        ctx.status = 304;
+                        return;
+                    }
+                }
+            }
+
             // Range request handling (HTTP 206 Partial Content — compression skipped for ranges)
             const rangeHeader = ctx.get('Range');
             if (rangeHeader) {
@@ -1651,10 +2114,11 @@ module.exports = function koaClassicServer(
                     if (!ifRange || ifRange === baseEtag) {
                         const { start, end } = parsed;
                         const rangeLength = end - start + 1;
-                        const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
-                        const filename = path.basename(toOpen);
 
                         ctx.status = 206;
+                        // 206 returns identity bytes → tag with baseEtag, not the encoding-specific
+                        // fullEtag set above. Last-Modified is already set (browserCacheEnabled).
+                        if (options.browserCacheEnabled) ctx.set('ETag', baseEtag);
                         ctx.set('Content-Range', `bytes ${start}-${end}/${fileSize}`);
                         ctx.set('Content-Type', mimeType);
                         ctx.set('Content-Length', String(rangeLength));
@@ -1662,8 +2126,9 @@ module.exports = function koaClassicServer(
 
                         if (ctx.method !== 'HEAD') {
                             if (rawBuffer) {
-                                // Serve range slice from in-memory buffer — zero disk I/O
-                                ctx.body = rawBuffer.slice(start, end + 1);
+                                // Serve range slice from in-memory buffer — zero disk I/O.
+                                // subarray(): zero-copy view; Buffer.slice is deprecated (DEP0158).
+                                ctx.body = rawBuffer.subarray(start, end + 1);
                             } else {
                                 const src = fs.createReadStream(toOpen, { start, end });
                                 src.on('error', (err) => {
@@ -1688,57 +2153,25 @@ module.exports = function koaClassicServer(
                 // Invalid Range → fall through to full 200 response
             }
 
-            // Determine MIME type and compression encoding for the full-file response
-            const mimeType = mime.lookup(toOpen) || 'application/octet-stream';
-            const filename = path.basename(toOpen);
-
-            // Resolve compression: enabled + compressible MIME + meets minFileSize + client supports it
-            let encoding = null; // 'br' | 'gzip' | null
-            if (compressionConfig.enabled && compressionConfig.encodings.length > 0) {
-                const isCompressibleMime = compressionConfig.mimeTypes.has(mimeType);
-                const meetsMinSize = compressionConfig.minFileSize === false
-                    || fileStat.size >= compressionConfig.minFileSize;
-                if (isCompressibleMime && meetsMinSize) {
-                    encoding = getClientEncoding(ctx.get('Accept-Encoding'));
-                }
-            }
-
-            // fullEtag is encoding-specific to avoid false 304 hits across representations.
-            // Proxies use Vary: Accept-Encoding to cache separate versions per encoding.
-            const etagSuffix = encoding === 'br' ? '-br' : encoding === 'gzip' ? '-gz' : '';
-            const fullEtag = `"${fileStat.mtime.getTime()}-${fileStat.size}${etagSuffix}"`;
-
-            // ETag, Last-Modified, and 304 check — deferred until encoding is known
-            if (options.browserCacheEnabled) {
-                ctx.set('ETag', fullEtag);
-                ctx.set('Last-Modified', fileStat.mtime.toUTCString());
-
-                // Check If-None-Match (ETag validation)
-                const clientEtag = ctx.get('If-None-Match');
-                if (clientEtag && clientEtag === fullEtag) {
-                    ctx.status = 304;
-                    return;
-                }
-
-                // Check If-Modified-Since (date validation)
-                const clientModifiedSince = ctx.get('If-Modified-Since');
-                if (clientModifiedSince) {
-                    const clientDate = new Date(clientModifiedSince);
-                    if (fileStat.mtime.getTime() <= clientDate.getTime()) {
-                        ctx.status = 304;
-                        return;
-                    }
-                }
-            }
-
             // Common response headers
             ctx.set('Content-Type', mimeType);
             ctx.set('Content-Disposition', buildContentDisposition(filename));
 
             if (encoding) {
                 // ── Compressed response ───────────────────────────────────────────────
+                // Vary: Accept-Encoding is already set above (potentiallyCompressible).
                 ctx.set('Content-Encoding', encoding);
-                ctx.set('Vary', 'Accept-Encoding'); // Required so proxies cache per-encoding
+
+                // 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. 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) {
                     // compressedFile cache mode: compress once → buffer in RAM → Content-Length known
@@ -1755,23 +2188,123 @@ 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 {
-                            // Use rawFile buffer if available — avoids redundant disk read
-                            const rawData = rawBuffer || await fs.promises.readFile(toOpen);
-                            buf = await compressBuffer(rawData, encoding);
-
-                            refreshOrInsert(_compressedFileCache, cacheKey, {
-                                buffer: buf,
-                                mtime: fileStat.mtime.getTime(),
-                                size: fileStat.size,
-                                insertedAt: Date.now(),
-                            }, cached, staleByAge);
+                            // Single-flight: concurrent misses on the same path+encoding
+                            // share one read+compress+insert instead of N parallel brotli
+                            // jobs for identical content. A rejection is shared too: all
+                            // waiters land in this catch and use the uncompressed fallback.
+                            // The key includes the stat'd mtime+size so a request that
+                            // observed a DIFFERENT version of the file starts its own job
+                            // (its ETag/Last-Modified must describe the bytes it serves).
+                            const inflightKey = `${cacheKey}:${fileStat.mtime.getTime()}:${fileStat.size}`;
+                            buf = await singleFlight(_inflightCompressions, inflightKey, async () => {
+                                // Use rawFile buffer if available — avoids redundant disk read
+                                const rawData = rawBuffer || await fs.promises.readFile(toOpen);
+                                const compressed = await compressBuffer(rawData, encoding);
+                                refreshOrInsert(_compressedFileCache, cacheKey, {
+                                    buffer: compressed,
+                                    mtime: fileStat.mtime.getTime(),
+                                    size: fileStat.size,
+                                    insertedAt: Date.now(),
+                                }, cached, staleByAge);
+                                return compressed;
+                            });
                         } catch (err) {
                             _logger.error('Compression error:', err);
-                            // Fall back to uncompressed on any compression failure
+                            // Fall back to uncompressed on any compression failure. Vary STAYS
+                            // (the resource is still compressible), but the ETag must be reset to
+                            // the un-suffixed form: this identity body must not be cached by a
+                            // shared proxy under the -br/-gz validator (#7).
                             ctx.remove('Content-Encoding');
-                            ctx.remove('Vary');
+                            if (options.browserCacheEnabled) ctx.set('ETag', baseEtag);
                             if (rawBuffer) {
                                 ctx.set('Content-Length', String(rawBuffer.length));
                                 if (ctx.method !== 'HEAD') {
@@ -1808,25 +2341,17 @@ 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 });
-                        if (rawBuffer) {
-                            // Compress from in-memory buffer — no disk I/O
-                            const src = Readable.from(rawBuffer);
-                            ctx.body = src.pipe(compress);
-                        } else {
-                            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'; }
-                            });
-                            ctx.body = src.pipe(compress);
-                        }
+                        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
+                        // running the compression. The explicit status is required: with
+                        // no body ever assigned, Koa would otherwise respond its default 404.
+                        ctx.status = 200;
                     }
-                    // HEAD + streaming: no Content-Length available; Koa sends headers only via res.end()
                 }
 
             } else {
@@ -1945,9 +2470,12 @@ module.exports = function koaClassicServer(
             parts.push("</thead>");
             parts.push("<tbody>");
 
-            // Parent directory link
+            // Parent directory link — omitted at the middleware's LOGICAL root
+            // (pageHrefOutPrefix.pathname === '/'), not only at the absolute root: with
+            // urlPrefix '/static', the listing of /static/ must not link to '/', which is
+            // outside the served tree (#13).
             const currentPath = pageHref.origin + pageHref.pathname;
-            if (currentPath !== pageHrefOutPrefix.origin + "/") {
+            if (pageHrefOutPrefix.pathname !== "/") {
                 // Build parent directory URL without query parameters
                 const a_pD = currentPath.split("/");
                 a_pD.pop();
@@ -1956,8 +2484,9 @@ module.exports = function koaClassicServer(
                 parts.push(`<tr><td><a href="${escapeHtml(parentDirectory)}"><b>.. Parent Directory</b></a></td><td>DIR</td><td>-</td></tr>`);
             }
 
+            const emptyFolderRow = `<tr><td>empty folder</td><td></td><td></td></tr>`;
             if (dir.length === 0) {
-                parts.push(`<tr><td>empty folder</td><td></td><td></td></tr>`);
+                parts.push(emptyFolderRow);
             } else {
                 const _listingBaseUrl = pageHref.origin + pageHref.pathname;
                 const _listingOriginPrefix = pageHref.origin + options.urlPrefix;
@@ -2051,6 +2580,13 @@ module.exports = function koaClassicServer(
                 }
                 const items = rawItems.filter(Boolean);
 
+                // Every entry was filtered out as hidden (dotfiles / alwaysHide / blacklist):
+                // show the same "empty folder" row as a physically empty directory (#16), not a
+                // header-only empty table (which would also hint that hidden files exist).
+                if (items.length === 0) {
+                    parts.push(emptyFolderRow);
+                }
+
                 // Places directories before non-directories; falls back to `tieBreaker`
                 // when both items are in the same bucket. `effectiveType === 2` covers plain
                 // dirs and dir-resolved symlinks, matching the rest of the listing logic.
@@ -2186,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,
+};