koa-classic-server 4.2.1 → 5.0.0

package/index.cjs

@@ -14,6 +14,26 @@ const _gzipAsync           = util.promisify(zlib.gzip);
 // Pre-computed module-level constants
 const _LOG_1024 = Math.log(1024);
 
+// Redirect statuses accepted for hideExtension.redirect (V5 — anything else
+// throws at factory time; see the validation block for the rationale). The
+// set is exactly what Koa's ctx.redirect() emits AS-IS (statuses.redirect):
+// 300 and 305 are exotic/deprecated but valid and honored; 304 is NOT here
+// because Koa does not treat it as a redirect (it would be rewritten to 302).
+const _VALID_REDIRECT_CODES = new Set([300, 301, 302, 303, 305, 307, 308]);
+
+// Shared extension-suffix normalizer (V5 — v4.3 register #10), used by BOTH
+// hideExtension.ext and template.ext entries: the leading dot is optional
+// decoration ('.ejs' and 'ejs' are equivalent; '.ejs' is the preferred,
+// documented form) and compound suffixes ('.tar.gz', '.html.ejs') are
+// first-class — both options match by SUFFIX. Returns the canonical dotted
+// form, or null when the value cannot name a suffix (non-string, empty, '.').
+function normalizeExtSuffix(value) {
+    if (typeof value !== 'string') return null;
+    const stripped = value.startsWith('.') ? value.slice(1) : value;
+    if (stripped === '') return null;
+    return '.' + stripped;
+}
+
 // Emitted at most once per process lifetime when the caller passes the v2-era
 // `showDirContents` option instead of the v3 `dirListing.enabled`. The old
 // name is accepted as a backward-compatibility alias and may be removed in a
@@ -183,7 +203,15 @@ const ERROR_PAGE_SCRUB_HEADERS = [
 // 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');
+    // Every generated error page is non-cacheable: no-store on ALL handled
+    // statuses (404 included), not just >= 500 (v5.0 register #1). A 404 is
+    // heuristically cacheable by default (RFC 9110 §15.1 / RFC 7231 §6.1), so
+    // without an explicit directive a shared cache could keep serving a stale
+    // "not found" after the file is created — the same heuristic-caching hazard
+    // the file branch (browserCacheEnabled:false) and the listing (v4.3 #5)
+    // already defeat explicitly. no-store rather than the listing's no-cache
+    // trio: an error page has nothing worth storing to revalidate later.
+    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;
@@ -230,8 +258,9 @@ function warnPayload(logger, message) {
 // 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.
+// A FUTURE major (maintainer decision 2026-07-18: target 6.0.0, not 5.0.0)
+// 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;
@@ -290,8 +319,12 @@ function stripBodyForHead(ctx) {
 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);
-    if (!fileExt || !templateOpts.ext.includes(fileExt)) return false;
+    // Suffix match (V5 — v4.3 register #10): ext entries are canonical dotted
+    // suffixes ('.ejs'; compound forms like '.html.ejs' match too). The length
+    // guard preserves the historical dotfile behavior: a file named exactly
+    // '.ejs' has no extension and never matches.
+    const baseName = path.basename(filePath);
+    if (!templateOpts.ext.some((ext) => baseName.length > ext.length && baseName.endsWith(ext))) return false;
 
     // RFC 9110 §9.3.2: HEAD must mirror GET (same status + headers, no body). The
     // user's render is run exactly as for GET — by presenting ctx.method as GET for
@@ -362,14 +395,74 @@ function escapeHtml(unsafe) {
     return unsafe.replace(_HTML_ESCAPE_RE, c => _HTML_ESCAPE_MAP[c]);
 }
 
+// Lone (unpaired) surrogates cannot be percent-encoded: encodeURIComponent
+// throws URIError on them. They cannot arrive from URL-decoded client input
+// (the decode guards already reject invalid encodings with a 400), but Windows
+// filenames are WTF-16 and readdir() can return them — one such name must not
+// turn the whole directory listing (or the file's Content-Disposition) into a
+// 500. String.prototype.toWellFormed() (Node >= 20, the engines minimum since
+// v5.0.0) replaces every lone surrogate with U+FFFD. Well-formed strings —
+// including astral pairs like emoji — pass through unchanged.
+function toWellFormedName(name) {
+    return name.toWellFormed();
+}
+
+// Explicit bidi control characters (embedding/override/isolate,
+// U+202A-U+202E and U+2066-U+2069) can make a listing entry DISPLAY as a
+// different name — "evil‮txt.exe" renders roughly as "evilexe.txt"
+// (extension spoofing). In the DISPLAYED name only they are replaced with a
+// visible U+FFFD (the href and the served file are untouched); the caller
+// additionally wraps the name in <bdi> so the directional run of one name
+// (legit RTL included) cannot bleed into the rest of its row. Direction MARKS
+// (U+200E/U+200F) are legitimate in RTL text and are left alone.
+const _BIDI_CONTROLS_RE = /[\u202A-\u202E\u2066-\u2069]/g;
+function listingDisplayName(name) {
+    return escapeHtml(name.replace(_BIDI_CONTROLS_RE, '\uFFFD'));
+}
+
+/**
+ * Build a Content-Disposition header value for inline serving.
+ *
+ * Uses both the legacy quoted-string form (ASCII fallback) and the RFC 5987
+ * extended form (UTF-8 percent-encoded) for maximum browser compatibility:
+ *   inline; filename="ascii-safe"; filename*=UTF-8''percent-encoded
+ *
+ * The quoted-string form must stay within what Node accepts in a header
+ * value (latin1 minus control chars): anything outside — CJK, emoji, \n —
+ * would make ctx.set() throw ERR_INVALID_CHAR and turn the response into a
+ * 500. Those characters are replaced with '?' (same policy as express's
+ * content-disposition package); the real name still round-trips via the
+ * RFC 5987 form, which browsers prefer over filename (RFC 6266 §4.1).
+ * The name is normalized to well-formed UTF-16 first: a lone surrogate (WTF-16
+ * filename on Windows) would otherwise make encodeURIComponent throw.
+ */
+function buildContentDisposition(filename) {
+    filename = toWellFormedName(filename);
+
+    // quoted-string fallback: printable latin1 only (controls and >0xFF → '?'), then escape \ and "
+    const asciiSafe = filename
+        .replace(/[^\x20-\x7e\xa0-\xff]/g, '?')
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"');
+
+    // RFC 5987 extended value: UTF-8 percent-encode everything except
+    // unreserved chars (ALPHA / DIGIT / "-" / "." / "_" / "~")
+    const rfc5987 = encodeURIComponent(filename)
+        .replace(/['()]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+
+    return `inline; filename="${asciiSafe}"; filename*=UTF-8''${rfc5987}`;
+}
+
 // Pure helper — depends only on _LOG_1024 (module scope), safe to hoist.
 function formatSize(bytes) {
     if (bytes === 0) return '0 B';
     if (bytes === undefined || bytes === null) return '-';
 
     const k = 1024;
-    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
-    const i = Math.floor(Math.log(bytes) / _LOG_1024);
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+    // Clamped to the last unit: an off-scale size must degrade to "huge number
+    // of EB", never to "N undefined" (#8).
+    const i = Math.min(Math.floor(Math.log(bytes) / _LOG_1024), sizes.length - 1);
 
     return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
 }
@@ -383,6 +476,10 @@ function getDirentType(dirent) {
     return 0;
 }
 
+// Range start/end/suffix must be pure digit runs: parseInt alone would accept
+// "1x" as 1 (see the strict-validation note inside parseRangeHeader).
+const _RANGE_DIGITS_RE = /^\d+$/;
+
 /**
  * Parse a "Range: bytes=..." header against a known file size.
  * Only single ranges are supported; multi-range requests are treated as invalid.
@@ -408,25 +505,29 @@ function parseRangeHeader(rangeHeader, fileSize) {
 
     let start, end;
 
+    // Strict digit validation (#11): parseInt() would accept garbage prefixes
+    // ("bytes=1x-5y" as 1-5) and serve a 206 for a spec that RFC 9110 §14.2
+    // says must be ignored (→ full 200 via 'invalid'). Bounds were never at
+    // risk — this is pure conformance on malformed input.
     if (startStr === '') {
         // Suffix range: bytes=-N (last N bytes)
-        if (endStr === '') return 'invalid';
+        if (!_RANGE_DIGITS_RE.test(endStr)) return 'invalid'; // also rejects ''
         const suffix = parseInt(endStr, 10);
-        if (isNaN(suffix) || suffix <= 0) return 'invalid';
+        if (suffix <= 0) return 'invalid';
         if (fileSize === 0) return 'unsatisfiable';
         start = suffix >= fileSize ? 0 : fileSize - suffix;
         end   = fileSize - 1;
     } else {
+        if (!_RANGE_DIGITS_RE.test(startStr)) return 'invalid';
         start = parseInt(startStr, 10);
-        if (isNaN(start) || start < 0) return 'invalid';
         if (fileSize === 0 || start >= fileSize) return 'unsatisfiable';
 
         if (endStr === '') {
             // Open range: bytes=N-
             end = fileSize - 1;
         } else {
+            if (!_RANGE_DIGITS_RE.test(endStr)) return 'invalid';
             end = parseInt(endStr, 10);
-            if (isNaN(end) || end < 0) return 'invalid';
             if (start > end) return 'invalid';
             // Clamp end to file size - 1
             if (end >= fileSize) end = fileSize - 1;
@@ -460,8 +561,12 @@ function ifNoneMatchSatisfied(headerValue, etag) {
 // set(key, entry) — insert, evicting LFU entries if needed
 // delete(key) — remove explicitly (e.g. stale entry before re-insert)
 class LFUCache {
-    constructor(maxSize, warnInterval, cacheLabel, logger) {
+    constructor(maxSize, warnInterval, cacheLabel, logger, maxEntrySize) {
         this.maxSize     = maxSize;
+        // Per-entry admission cap (bytes). Entries larger than this are never
+        // cached (they are still served). Infinity = no per-entry cap: only the
+        // physical maxSize bound applies.
+        this.maxEntrySize = typeof maxEntrySize === 'number' ? maxEntrySize : Infinity;
         this.warnInterval = warnInterval;
         this.cacheLabel  = cacheLabel;
         this.logger      = logger || console;
@@ -487,6 +592,15 @@ class LFUCache {
     }
 
     set(key, entry) {
+        // Invariant: set() must never run against a LIVE key — it would add the
+        // new buffer to currentSize without subtracting the overwritten one
+        // (accounting inflated forever → chronic premature evictions) and leave
+        // the key in two frequency buckets (a ghost that later makes
+        // _evictOne() destructure undefined — a throw inside a stream callback,
+        // outside any request try). Callers are expected to delete first
+        // (refreshOrInsert does, unconditionally); this guard makes the
+        // invariant hold by construction for any future caller too.
+        if (this._keyMap.has(key)) this.delete(key);
         // 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
@@ -495,6 +609,12 @@ class LFUCache {
             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;
         }
+        // Per-entry admission cap: refuse (and keep serving uncached) instead of
+        // letting one oversized entry evict most of the working set on insert.
+        if (entry.buffer.length > this.maxEntrySize) {
+            this._warnThrottled(`[koa-classic-server] serverCache.${this.cacheLabel}: entry of ${entry.buffer.length} bytes exceeds maxEntrySize (${this.maxEntrySize} bytes) and will not be cached. Increase serverCache.${this.cacheLabel}.maxEntrySize or set it to false.`);
+            return;
+        }
         while (this.currentSize + entry.buffer.length > this.maxSize && this._keyMap.size > 0) {
             this._evictOne();
         }
@@ -514,6 +634,7 @@ class LFUCache {
         const entry = this._keyMap.get(key);
         if (!entry) return false;
 
+        if (fields.buffer.length > this.maxEntrySize) return false;
         const sizeDelta = fields.buffer.length - entry.buffer.length;
         if (this.currentSize + sizeDelta > this.maxSize) return false;
 
@@ -609,22 +730,25 @@ function singleFlight(map, key, work) {
 // 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.
+// than the buffered path (which can afford max quality because it runs once and
+// is cached). Used by every streamed-compression pipeline. `quality` carries the
+// normalized compression.streaming settings (brotliQuality default 4, gzipLevel
+// default 6).
 // 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) {
+// window is 32 KB by design — nothing to bound there. LGWIN is deliberately
+// NOT configurable: it is what bounds the per-stream RAM.
+function createStreamCompressor(encoding, quality) {
     return encoding === 'br'
         ? zlib.createBrotliCompress({ params: {
-            [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
+            [zlib.constants.BROTLI_PARAM_QUALITY]: quality.brotliQuality,
             [zlib.constants.BROTLI_PARAM_LGWIN]: 19,
         } })
-        : zlib.createGzip({ level: 6 });
+        : zlib.createGzip({ level: quality.gzipLevel });
 }
 
 function refreshOrInsert(cache, key, newEntry, cached, staleByAge) {
@@ -633,7 +757,13 @@ function refreshOrInsert(cache, key, newEntry, cached, staleByAge) {
         && cached.mtime === newEntry.mtime
         && cached.size === newEntry.size;
     if (!canRefreshInPlace || !cache.refresh(key, newEntry)) {
-        if (cached) cache.delete(key);
+        // Unconditional delete: `cached` is the caller's snapshot from request
+        // start and may be STALE — on the streamed-tee path by minutes. Another
+        // request can have inserted this key meanwhile (a new file version via
+        // a second tee leader, or the buffered path after the file shrank), so
+        // gating the delete on the snapshot would set() over a live key and
+        // corrupt the LFU accounting. delete() is a safe no-op when absent.
+        cache.delete(key);
         cache.set(key, newEntry);
     }
 }
@@ -692,19 +822,23 @@ module.exports = function koaClassicServer(
         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.
+                       //   unchanged) and WILL throw in a future major (target: 6.0.0).
         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
+                          //   for now and WILL throw in a future major, target 6.0.0 (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
+            ext: [], // Extension suffixes handled by template.render, e.g. ['.ejs'].
+                     // Preferred form WITH the leading dot; 'ejs' is equivalent (V5).
+                     // Matched as a SUFFIX of the file name (case-sensitive), so
+                     // compound extensions work too: ['.html.ejs'] targets only
+                     // page.html.ejs-style files.
             renderTimeout: 30000, // Max ms allowed for template.render (number ≥ 0; 0 = disabled).
                                   // On timeout responds 504 Gateway Timeout. The render receives an
                                   // AbortSignal as 5th argument; propagate it to fetch/db/fs to free
@@ -719,8 +853,15 @@ module.exports = function koaClassicServer(
         useOriginalUrl: true, // Use ctx.originalUrl (default) or ctx.url
                               // Set false for URL rewriting middleware (i18n, routing)
         hideExtension: {     // Hide file extension from URLs (clean URLs like mod_rewrite)
-            ext: '.ejs',     // Extension to hide (required, string, case-sensitive, must start with '.')
-            redirect: 301    // HTTP redirect code for URLs with extension (optional, default: 301)
+            ext: '.ejs',     // Suffix to hide (required, case-sensitive). Preferred form
+                             //   WITH the leading dot; 'ejs' is equivalent (V5). Compound
+                             //   suffixes ('.tar.gz') are supported.
+            redirect: 301    // HTTP redirect code for URLs with extension (optional, default: 301).
+                             //   Must be one of 300 | 301 | 302 | 303 | 305 | 307 | 308 (the codes
+                             //   Koa emits as-is; 300/305 are exotic/deprecated but valid) — anything
+                             //   else throws at factory time (V5; previously other numbers were
+                             //   tolerated and either became 302 silently or failed every redirect
+                             //   with a 500).
         },
         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.
@@ -773,6 +914,14 @@ module.exports = function koaClassicServer(
             compressedFile: {                 // cache for HTTP br/gzip responses — not for .zip/.tar files on disk
                 enabled: true,               // enable in-memory cache of compressed response buffers
                 maxSize: 104857600,          // max total RAM used by this cache (bytes; default: 100 MB)
+                maxEntrySize: undefined,     // max bytes of a SINGLE cached entry, measured on the compressed
+                                             //   OUTPUT (V4.3+). Applies to every insertion: buffered path and
+                                             //   streamed-tee path alike. Oversized entries are still served,
+                                             //   just not cached (throttled warning via logger).
+                                             //   undefined (default) → maxSize / 4, so one huge file cannot
+                                             //   evict most of the working set on insert; false → no per-entry
+                                             //   cap (maxSize still bounds); explicit bytes must be <= maxSize
+                                             //   (larger throws at factory time — use false instead).
                 maxAge: 0,                   // ms after insertion to consider an entry stale; 0 = disabled. See rawFile.maxAge.
                 warnInterval: 60000,         // ms between "maxSize reached" warnings; 0 = always; false = never
             },
@@ -795,6 +944,15 @@ module.exports = function koaClassicServer(
                                           //   so subsequent requests are served from RAM with
                                           //   Content-Length.
             mimeTypes: [],                // compressible MIME types (replaces default list if provided)
+            buffered: {                   // quality for the BUFFERED path (V4.3+): file <= maxFileSize,
+                brotliQuality: 11,        //   compressed once, output cached — the cost is paid once per
+                gzipLevel: 9,             //   file, so max quality by default. brotliQuality: integer 0-11;
+            },                            //   gzipLevel: integer 0-9. Out-of-range throws at factory time.
+            streaming: {                  // quality for the STREAMING path (V4.3+): file > maxFileSize, or
+                brotliQuality: 4,         //   compressed cache disabled — the cost is paid on EVERY
+                gzipLevel: 6,             //   non-cached request, so deliberately light by default.
+            },                            //   The brotli window stays fixed at 512 KB (bounds per-stream
+                                          //   RAM; not configurable). Same ranges as `buffered`.
         },
         // compression: false            // shorthand to disable all compression
         staticSecurityHeaders: {   // Opt-in security headers on STATIC file responses (V3.1+).
@@ -962,7 +1120,7 @@ module.exports = function koaClassicServer(
     // 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
+    // the runtime behavior exactly as it is today. A future major (6.0.0) 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).
@@ -1015,8 +1173,36 @@ module.exports = function koaClassicServer(
         }
         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 : [];
+    if (options.template.render !== undefined && typeof options.template.render !== 'function') {
+        // Dropped SILENTLY before V5 (#10): a non-function render means templates
+        // never run and template SOURCES are served as plain static files.
+        warnConfigDeprecation(_logger,
+            'template.render must be a function; got ' +
+            (options.template.render === null ? 'null' : typeof options.template.render) +
+            ' — template rendering is DISABLED (template sources are served as static files).');
+        options.template.render = undefined;
+    }
+    // template.ext entries go through the shared suffix normalizer: leading
+    // dot optional ('.ejs' preferred), compound suffixes supported. Entries
+    // that cannot name a suffix are dropped with a warning — they could never
+    // match a file, so dropping them cannot break working behavior.
+    if (Array.isArray(options.template.ext)) {
+        const normalizedExts = [];
+        for (const value of options.template.ext) {
+            const suffix = normalizeExtSuffix(value);
+            if (suffix === null) {
+                warnConfigDeprecation(_logger,
+                    'template.ext entries must be non-empty extension suffixes like ".ejs" (leading dot optional); dropping ' +
+                    (typeof value === 'string' ? JSON.stringify(value) : 'a non-string (' + (value === null ? 'null' : typeof value) + ')') +
+                    ' — it can never match a file.');
+                continue;
+            }
+            normalizedExts.push(suffix);
+        }
+        options.template.ext = normalizedExts;
+    } else {
+        options.template.ext = [];
+    }
 
     if (options.template.renderTimeout === undefined) {
         options.template.renderTimeout = 30000;
@@ -1068,23 +1254,34 @@ module.exports = function koaClassicServer(
         if (typeof options.hideExtension !== 'object' || Array.isArray(options.hideExtension)) {
             throw new Error('[koa-classic-server] hideExtension must be an object with an "ext" property. Example: { ext: ".ejs" }');
         }
-        if (!options.hideExtension.ext || typeof options.hideExtension.ext !== 'string') {
-            throw new Error('[koa-classic-server] hideExtension.ext is required and must be a non-empty string. Example: { ext: ".ejs" }');
-        }
-        // Normalize ext: add leading dot if missing
-        if (!options.hideExtension.ext.startsWith('.')) {
-            _logger.warn(...warnPayload(_logger,
-                '[koa-classic-server] WARNING: hideExtension.ext should start with a dot.\n' +
-                `  Current usage: ext: "${options.hideExtension.ext}"\n` +
-                `  Corrected to:  ext: ".${options.hideExtension.ext}"\n` +
-                '  Please update your configuration.'
-            ));
-            options.hideExtension.ext = '.' + options.hideExtension.ext;
+        // Shared suffix normalizer (V5, #10): '.ejs' and 'ejs' are EQUIVALENT
+        // (the old missing-dot warning is gone — both forms are legal; '.ejs'
+        // is the preferred, documented one). Compound suffixes ('.tar.gz')
+        // keep working as before. Values that cannot name a suffix ('', '.',
+        // non-string) throw, as the empty/non-string forms always did.
+        const normalizedHideExt = normalizeExtSuffix(options.hideExtension.ext);
+        if (normalizedHideExt === null) {
+            throw new Error(
+                '[koa-classic-server] hideExtension.ext is required and must be a non-empty extension suffix. ' +
+                'Example: { ext: ".ejs" } (the leading dot is optional: "ejs" is equivalent).'
+            );
         }
-        // Validate redirect code
+        options.hideExtension.ext = normalizedHideExt;
+        // Validate redirect code (V5 breaking change — v4.3 register #9).
+        // Only real redirect statuses are accepted. Anything else was a
+        // configuration bug with two silent failure modes: a non-integer (or
+        // out-of-range) value made Koa's status setter throw at request time —
+        // a 500 on EVERY hideExtension redirect — while an integer that is not
+        // a redirect status (200, 404, 999, ...) was silently replaced with
+        // 302 by ctx.redirect(). Both now surface at startup instead.
         if (options.hideExtension.redirect !== undefined) {
-            if (typeof options.hideExtension.redirect !== 'number') {
-                throw new Error('[koa-classic-server] hideExtension.redirect must be a number (e.g. 301, 302). Got: ' + typeof options.hideExtension.redirect);
+            if (!_VALID_REDIRECT_CODES.has(options.hideExtension.redirect)) {
+                throw new Error(
+                    '[koa-classic-server] hideExtension.redirect must be one of: 300, 301, 302, 303, 305, 307, 308. ' +
+                    'Got: ' + String(options.hideExtension.redirect) + '\n' +
+                    '  Before v5.0.0 other values were tolerated: non-redirect codes were silently sent\n' +
+                    '  as 302, and non-integer values failed every redirect with a 500.'
+                );
             }
         } else {
             options.hideExtension.redirect = 301;
@@ -1276,6 +1473,54 @@ module.exports = function koaClassicServer(
     // Normalize and validate the compression option into a clean internal structure.
     // compression: false is a valid shorthand for { enabled: false }.
     function normalizeCompressionConfig(compression) {
+        // Per-path quality defaults (V4.3+). Two groups because the two execution
+        // modes have opposite cost models: the buffered path compresses once and
+        // caches the result (can afford max quality), the streaming path pays the
+        // CPU on every non-cached request (must stay light).
+        const defaultBuffered  = { brotliQuality: 11, gzipLevel: 9 };
+        const defaultStreaming = { brotliQuality: 4,  gzipLevel: 6 };
+
+        // Strict validation: these namespaces are new in 4.3.0, so unknown keys
+        // are caught as typos instead of being silently ignored (an operator who
+        // misspells brotliQuality must not believe they lowered the quality).
+        function validateQualityGroup(group, groupName, defaults) {
+            if (group === undefined) return { ...defaults };
+            if (!group || typeof group !== 'object' || Array.isArray(group)) {
+                throw new Error(
+                    `[koa-classic-server] compression.${groupName} must be an object, e.g. ` +
+                    `{ brotliQuality: ${defaults.brotliQuality}, gzipLevel: ${defaults.gzipLevel} }. Got: ` + String(group)
+                );
+            }
+            for (const key of Object.keys(group)) {
+                if (key !== 'brotliQuality' && key !== 'gzipLevel') {
+                    throw new Error(
+                        `[koa-classic-server] compression.${groupName}.${key} is not a valid option. ` +
+                        'Valid keys: brotliQuality, gzipLevel.'
+                    );
+                }
+            }
+            const out = { ...defaults };
+            if (group.brotliQuality !== undefined) {
+                if (!Number.isInteger(group.brotliQuality) || group.brotliQuality < 0 || group.brotliQuality > 11) {
+                    throw new Error(
+                        `[koa-classic-server] compression.${groupName}.brotliQuality must be an integer between 0 and 11. ` +
+                        'Got: ' + String(group.brotliQuality)
+                    );
+                }
+                out.brotliQuality = group.brotliQuality;
+            }
+            if (group.gzipLevel !== undefined) {
+                if (!Number.isInteger(group.gzipLevel) || group.gzipLevel < 0 || group.gzipLevel > 9) {
+                    throw new Error(
+                        `[koa-classic-server] compression.${groupName}.gzipLevel must be an integer between 0 and 9. ` +
+                        'Got: ' + String(group.gzipLevel)
+                    );
+                }
+                out.gzipLevel = group.gzipLevel;
+            }
+            return out;
+        }
+
         if (compression === false) return { enabled: false };
 
         if (!compression || typeof compression !== 'object' || Array.isArray(compression)) {
@@ -1285,6 +1530,8 @@ module.exports = function koaClassicServer(
                 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),
+                buffered: { ...defaultBuffered },
+                streaming: { ...defaultStreaming },
             };
         }
 
@@ -1303,20 +1550,47 @@ module.exports = function koaClassicServer(
             ? compression.encodings.filter(e => e === 'br' || e === 'gzip')
             : ['br', 'gzip'];
 
-        const minFileSize = compression.minFileSize === false ? false
-            : (typeof compression.minFileSize === 'number' && compression.minFileSize >= 0 ? compression.minFileSize : 1024);
+        // minFileSize / maxFileSize: an invalid value used to fall back to the
+        // default SILENTLY (#13) — inconsistent with maxAge / maxEntrySize /
+        // quality, which throw. These are v2-stable options, so the fallback
+        // stays (behavior unchanged) but now warns; a future major (6.0.0) will throw.
+        let minFileSize;
+        if (compression.minFileSize === undefined) {
+            minFileSize = 1024;
+        } else if (compression.minFileSize === false
+            || (typeof compression.minFileSize === 'number' && compression.minFileSize >= 0)) {
+            minFileSize = compression.minFileSize;
+        } else {
+            warnConfigDeprecation(_logger,
+                'compression.minFileSize must be a number >= 0 (bytes) or false; got ' +
+                String(compression.minFileSize) + ' — falling back to the default 1024 for now.');
+            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);
+        let maxFileSize;
+        if (compression.maxFileSize === undefined) {
+            maxFileSize = 10485760;
+        } else if (compression.maxFileSize === false
+            || (typeof compression.maxFileSize === 'number' && compression.maxFileSize > 0)) {
+            maxFileSize = compression.maxFileSize;
+        } else {
+            warnConfigDeprecation(_logger,
+                'compression.maxFileSize must be a positive number (bytes) or false; got ' +
+                String(compression.maxFileSize) + ' — falling back to the default 10485760 for now.');
+            maxFileSize = 10485760;
+        }
 
         const mimeTypes = Array.isArray(compression.mimeTypes) && compression.mimeTypes.length > 0
             ? compression.mimeTypes
             : DEFAULT_COMPRESSIBLE_MIME_TYPES;
 
-        return { enabled, encodings, minFileSize, maxFileSize, mimeTypes: new Set(mimeTypes) };
+        const buffered  = validateQualityGroup(compression.buffered,  'buffered',  defaultBuffered);
+        const streaming = validateQualityGroup(compression.streaming, 'streaming', defaultStreaming);
+
+        return { enabled, encodings, minFileSize, maxFileSize, mimeTypes: new Set(mimeTypes), buffered, streaming };
     }
 
     // Normalize and validate the serverCache option into a clean internal structure.
@@ -1331,6 +1605,7 @@ module.exports = function koaClassicServer(
         const defaultCompressedFile = {
             enabled: true,
             maxSize: 104857600,     // 100 MB
+            maxEntrySize: 26214400, // maxSize / 4
             maxAge: 0,
             warnInterval: 60000,
         };
@@ -1346,26 +1621,70 @@ module.exports = function koaClassicServer(
             return value;
         }
 
+        // maxEntrySize (V4.3+): per-entry admission cap for the compressed cache,
+        // measured on the compressed OUTPUT. Applies to every insertion (buffered
+        // path and streamed-tee path alike). undefined → a quarter of maxSize
+        // (the historical tee-path bound, and it keeps scaling with maxSize);
+        // false → no per-entry cap (normalized to Infinity; maxSize still bounds).
+        function validateMaxEntrySize(value, maxSize) {
+            if (value === undefined) return Math.floor(maxSize / 4);
+            if (value === false) return Infinity;
+            if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+                throw new Error(
+                    '[koa-classic-server] serverCache.compressedFile.maxEntrySize must be a positive integer (bytes) or false. ' +
+                    'Got: ' + String(value)
+                );
+            }
+            if (value > maxSize) {
+                throw new Error(
+                    `[koa-classic-server] serverCache.compressedFile.maxEntrySize (${value}) exceeds maxSize (${maxSize}) — ` +
+                    'a per-entry cap larger than the whole cache is a configuration contradiction. ' +
+                    'Use false to disable the per-entry cap.'
+                );
+            }
+            return value;
+        }
+
         if (!serverCache || typeof serverCache !== 'object' || Array.isArray(serverCache)) {
             return { rawFile: defaultRawFile, compressedFile: defaultCompressedFile };
         }
 
+        // Positive-bytes fields whose invalid values used to fall back to the
+        // default SILENTLY (#13): warn now, behavior unchanged (the fallback is
+        // identical); the next major will throw — same deprecation path as the
+        // other config warnings.
+        function sizeOrWarn(value, fieldName, defaultValue) {
+            if (value === undefined) return defaultValue;
+            if (typeof value === 'number' && value > 0) return value;
+            warnConfigDeprecation(_logger,
+                `serverCache.${fieldName} must be a positive number (bytes); got ` +
+                String(value) + ` — falling back to the default ${defaultValue} for now.`);
+            return defaultValue;
+        }
+
         const rf = serverCache.rawFile;
         const rawFile = (!rf || typeof rf !== 'object' || Array.isArray(rf)) ? defaultRawFile : {
             enabled: typeof rf.enabled === 'boolean' ? rf.enabled : false,
-            maxSize: typeof rf.maxSize === 'number' && rf.maxSize > 0 ? rf.maxSize : 52428800,
-            maxFileSize: typeof rf.maxFileSize === 'number' && rf.maxFileSize > 0 ? rf.maxFileSize : 1048576,
+            maxSize: sizeOrWarn(rf.maxSize, 'rawFile.maxSize', 52428800),
+            maxFileSize: sizeOrWarn(rf.maxFileSize, 'rawFile.maxFileSize', 1048576),
             maxAge: validateMaxAge(rf.maxAge, 'rawFile'),
             warnInterval: rf.warnInterval === false ? false : (typeof rf.warnInterval === 'number' ? rf.warnInterval : 60000),
         };
 
         const cf = serverCache.compressedFile;
-        const compressedFile = (!cf || typeof cf !== 'object' || Array.isArray(cf)) ? defaultCompressedFile : {
-            enabled: typeof cf.enabled === 'boolean' ? cf.enabled : true,
-            maxSize: typeof cf.maxSize === 'number' && cf.maxSize > 0 ? cf.maxSize : 104857600,
-            maxAge: validateMaxAge(cf.maxAge, 'compressedFile'),
-            warnInterval: cf.warnInterval === false ? false : (typeof cf.warnInterval === 'number' ? cf.warnInterval : 60000),
-        };
+        let compressedFile;
+        if (!cf || typeof cf !== 'object' || Array.isArray(cf)) {
+            compressedFile = defaultCompressedFile;
+        } else {
+            const cfMaxSize = sizeOrWarn(cf.maxSize, 'compressedFile.maxSize', 104857600);
+            compressedFile = {
+                enabled: typeof cf.enabled === 'boolean' ? cf.enabled : true,
+                maxSize: cfMaxSize,
+                maxEntrySize: validateMaxEntrySize(cf.maxEntrySize, cfMaxSize),
+                maxAge: validateMaxAge(cf.maxAge, 'compressedFile'),
+                warnInterval: cf.warnInterval === false ? false : (typeof cf.warnInterval === 'number' ? cf.warnInterval : 60000),
+            };
+        }
 
         return { rawFile, compressedFile };
     }
@@ -1548,12 +1867,35 @@ module.exports = function koaClassicServer(
         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]);
+    // Pre-opens `filePath` and returns a ReadStream reading from the already-open
+    // descriptor, or null after writing the 404 error page when the open fails.
+    // Rationale (v5.0 register #5): assigning a lazily-opening
+    // fs.createReadStream(path) to ctx.body means an open-time failure (file
+    // vanished after the stat, EACCES, EIO at open) fires only AFTER Koa's
+    // respond() has taken ownership of the body — the error page written by a
+    // stream-error handler can never be sent, Stream.pipeline tears the socket
+    // down, and the client sees a bare ECONNRESET. Opening HERE, while the
+    // response is still fully ours, turns that race into a clean 404 (matching
+    // the access-check contract: "unreadable" is indistinguishable from "not
+    // found"). The path is still passed to fs.createReadStream — Node ignores it
+    // when `fd` is set — so path-based instrumentation keeps working.
+    async function openBodyStream(ctx, filePath, streamOpts) {
+        let handle;
+        try {
+            handle = await fs.promises.open(filePath, 'r');
+        } catch (err) {
+            _logger.error('File open error:', err);
+            await sendErrorPage(ctx, 404);
+            return null;
+        }
+        try {
+            // autoClose (default true) closes the FileHandle when the stream ends
+            // or is destroyed — including Koa's teardown on client disconnect.
+            return fs.createReadStream(filePath, { fd: handle, ...streamOpts });
+        } catch (err) {
+            handle.close().catch(() => {}); // nothing consumed the fd — release it
+            throw err; // unexpected: surfaces through the last-resort catch
+        }
     }
 
     const compressionConfig = normalizeCompressionConfig(options.compression);
@@ -1574,7 +1916,8 @@ module.exports = function koaClassicServer(
         serverCacheConfig.compressedFile.maxSize,
         serverCacheConfig.compressedFile.warnInterval,
         'compressedFile',
-        _logger
+        _logger,
+        serverCacheConfig.compressedFile.maxEntrySize
     );
 
     // Single-flight maps for cache population (thundering-herd protection):
@@ -1599,21 +1942,26 @@ module.exports = function koaClassicServer(
     // `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.
+    // The disk source is pre-opened (openBodyStream, register #5): an open-time
+    // failure becomes a clean 404 here, so the pipeline callback below only ever
+    // sees mid-flight errors — where the response is already on the wire and
+    // Koa 3 tears the socket down; logging on the operator's logger is all
+    // that is left to do.
     // 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);
+    async function streamCompressedBody(ctx, toOpen, rawBuffer, encoding) {
         const src = rawBuffer
             ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
-            : fs.createReadStream(toOpen);
+            : await openBodyStream(ctx, toOpen);
+        if (!src) return; // open failed — the 404 page is already written
+        const compress = createStreamCompressor(encoding, compressionConfig.streaming);
         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);
         });
     }
 
@@ -1646,38 +1994,16 @@ module.exports = function koaClassicServer(
         return null;
     }
 
-    // Compress a Buffer using the given encoding ('br' or 'gzip').
-    // Quality is maxed out: serverCache pays this cost once per file, not per request.
+    // Compress a Buffer using the given encoding ('br' or 'gzip') at the
+    // buffered-path quality (compression.buffered). Defaults are maxed out:
+    // serverCache pays this cost once per file, not per request.
     function compressBuffer(data, encoding) {
         if (encoding === 'br') {
             return _brotliCompressAsync(data, {
-                params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 }
+                params: { [zlib.constants.BROTLI_PARAM_QUALITY]: compressionConfig.buffered.brotliQuality }
             });
         }
-        return _gzipAsync(data, { level: zlib.constants.Z_BEST_COMPRESSION });
-    }
-
-    /**
-     * Build a Content-Disposition header value for inline serving.
-     *
-     * Uses both the legacy quoted-string form (ASCII fallback) and the RFC 5987
-     * extended form (UTF-8 percent-encoded) for maximum browser compatibility:
-     *   inline; filename="ascii-safe"; filename*=UTF-8''percent-encoded
-     *
-     * The quoted-string form escapes only double-quotes; the RFC 5987 form
-     * percent-encodes every byte that is not an unreserved URI character.
-     * Browsers that support filename* prefer it over filename (RFC 6266 §4.1).
-     */
-    function buildContentDisposition(filename) {
-        // quoted-string fallback: escape " and \ so the value is always valid ASCII
-        const asciiSafe = filename.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-
-        // RFC 5987 extended value: UTF-8 percent-encode everything except
-        // unreserved chars (ALPHA / DIGIT / "-" / "." / "_" / "~")
-        const rfc5987 = encodeURIComponent(filename)
-            .replace(/['()]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
-
-        return `inline; filename="${asciiSafe}"; filename*=UTF-8''${rfc5987}`;
+        return _gzipAsync(data, { level: compressionConfig.buffered.gzipLevel });
     }
 
     // Find the first matching index file in a directory.
@@ -2162,6 +2488,12 @@ module.exports = function koaClassicServer(
 
             // Verify file is still readable (race condition protection).
             // Skip if rawBuffer already loaded — the successful readFile() is equivalent proof.
+            // The disk-streaming branches additionally PRE-OPEN the file
+            // (openBodyStream, register #5), which closes the residual
+            // access→open TOCTOU there; this probe is kept for the outcomes
+            // that never open the file (compressed-cache hits, 304s, HEAD):
+            // dropping it would let a file made unreadable after caching keep
+            // being served from RAM.
             if (!rawBuffer) {
                 try {
                     await fs.promises.access(toOpen, fs.constants.R_OK);
@@ -2200,7 +2532,10 @@ module.exports = function koaClassicServer(
             // 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');
+                // ctx.vary() appends (deduplicating) instead of overwriting: a
+                // Vary set by upstream middleware (e.g. "Origin" from a CORS
+                // layer) must survive (#7).
+                ctx.vary('Accept-Encoding');
             }
 
             // Preconditions are evaluated BEFORE the Range branch: RFC 9110 §13.2.2 gives the
@@ -2213,23 +2548,33 @@ module.exports = function koaClassicServer(
                 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()) {
+                // When the header is present it is the ONLY precondition evaluated:
+                // RFC 9110 §13.1.3 — "A recipient MUST ignore If-Modified-Since if
+                // the request contains an If-None-Match header field". The ETag is
+                // the strong validator; the date has 1-second resolution and would
+                // otherwise 304 a client whose ETag just said it is stale (e.g. two
+                // same-second edits with a size change, or an encoding-suffix change).
+                const ifNoneMatch = ctx.get('If-None-Match');
+                if (ifNoneMatch) {
+                    if (ifNoneMatchSatisfied(ifNoneMatch, fullEtag)) {
                         ctx.status = 304;
                         return;
                     }
+                    // present but not satisfied → full response, date NOT consulted
+                } else {
+                    // 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;
+                        }
+                    }
                 }
             }
 
@@ -2268,10 +2613,14 @@ module.exports = function koaClassicServer(
                                 // subarray(): zero-copy view; Buffer.slice is deprecated (DEP0158).
                                 ctx.body = rawBuffer.subarray(start, end + 1);
                             } else {
-                                const src = fs.createReadStream(toOpen, { start, end });
+                                // Pre-open (register #5): an open failure is a clean 404
+                                // (writeErrorPage scrubs the 206 headers set above).
+                                const src = await openBodyStream(ctx, toOpen, { start, end });
+                                if (!src) return;
+                                // Mid-flight errors only from here on: the socket is torn
+                                // down by Koa 3 — log on the operator's logger.
                                 src.on('error', (err) => {
                                     _logger.error('Stream error:', err);
-                                    if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                                 });
                                 ctx.body = src;
                             }
@@ -2341,19 +2690,27 @@ module.exports = function koaClassicServer(
                             // 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);
+                            await streamCompressedBody(ctx, toOpen, rawBuffer, encoding);
                             return;
                         }
-                        // Leader: stream AND accumulate a copy for the cache.
+                        // Leader: stream AND accumulate a copy for the cache. The disk
+                        // source is pre-opened BEFORE the tee bookkeeping starts, so an
+                        // open failure is a clean 404 with nothing to unwind (register #5).
+                        const src = rawBuffer
+                            ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
+                            : await openBodyStream(ctx, toOpen);
+                        if (!src) return;
                         _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;
+                        //  - per entry: maxEntrySize (default: a quarter of the cache), so
+                        //    one huge file cannot evict most of the working set on insert.
+                        //    Checked here — not just in LFUCache.set() — to stop ACCUMULATING
+                        //    RAM as soon as the budget is blown, not merely refuse the 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);
+                        const entryCap = serverCacheConfig.compressedFile.maxEntrySize;
                         // Stops accumulating and releases this tee's share of the aggregate
                         // budget. Safe to call more than once.
                         const abandonAccumulation = () => {
@@ -2363,10 +2720,7 @@ module.exports = function koaClassicServer(
                             }
                         };
                         try {
-                            const compress = createStreamCompressor(encoding);
-                            const src = rawBuffer
-                                ? Readable.from(rawBuffer) // compress from in-memory buffer — no disk I/O
-                                : fs.createReadStream(toOpen);
+                            const compress = createStreamCompressor(encoding, compressionConfig.streaming);
                             const tee = new Transform({
                                 transform(chunk, _enc, done) {
                                     if (acc) {
@@ -2398,8 +2752,9 @@ module.exports = function koaClassicServer(
                                 }
                                 abandonAccumulation();
                                 if (!err || err.code === 'ERR_STREAM_PREMATURE_CLOSE') return;
+                                // Mid-flight error: the response is already on the wire and
+                                // Koa 3 tears the socket down — log and nothing else.
                                 _logger.error('Stream error:', err);
-                                if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                             });
                         } catch (err) {
                             // Defensive: nothing between add() and pipeline() is expected to
@@ -2407,6 +2762,7 @@ module.exports = function koaClassicServer(
                             // the tee for this file version forever.
                             _inflightStreamTees.delete(teeKey);
                             abandonAccumulation();
+                            src.destroy(); // release the pre-opened fd — nothing consumed it
                             throw err;
                         }
                         return;
@@ -2451,10 +2807,14 @@ module.exports = function koaClassicServer(
                             } else {
                                 ctx.set('Content-Length', String(fileStat.size));
                                 if (ctx.method !== 'HEAD') {
-                                    const src = fs.createReadStream(toOpen);
+                                    // Pre-open (register #5): if the disk is failing hard
+                                    // enough that the identity fallback cannot even open the
+                                    // file, the client gets a clean 404 instead of a torn
+                                    // socket.
+                                    const src = await openBodyStream(ctx, toOpen);
+                                    if (!src) return;
                                     src.on('error', (streamErr) => {
                                         _logger.error('Stream error:', streamErr);
-                                        if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                                     });
                                     ctx.body = src;
                                 } else {
@@ -2479,7 +2839,7 @@ module.exports = function koaClassicServer(
                     // Streaming mode (compressed cache disabled): pipe through the zlib
                     // transform — Content-Length not known in advance, nothing cached.
                     if (ctx.method !== 'HEAD') {
-                        streamCompressedBody(ctx, toOpen, rawBuffer, encoding);
+                        await 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
@@ -2503,10 +2863,15 @@ module.exports = function koaClassicServer(
                 } else {
                     ctx.set('Content-Length', String(fileStat.size));
                     if (ctx.method !== 'HEAD') {
-                        const src = fs.createReadStream(toOpen);
+                        // Pre-open (register #5): an open-time failure (file vanished
+                        // after the stat, EACCES, EIO) becomes a clean 404 instead of
+                        // an ECONNRESET after respond() owns the body.
+                        const src = await openBodyStream(ctx, toOpen);
+                        if (!src) return;
+                        // Mid-flight errors only from here on (Koa 3 tears the socket
+                        // down): log on the operator's logger.
                         src.on('error', (err) => {
                             _logger.error('Stream error:', err);
-                            if (!ctx.headerSent) sendErrorPageSync(ctx, 500);
                         });
                         ctx.body = src;
                     } else {
@@ -2550,17 +2915,32 @@ module.exports = function koaClassicServer(
             const rawDirRel = path.relative(normalizedRootDir, toOpen);
             const dirRelPath = (rawDirRel === '' || rawDirRel === '.') ? '' : rawDirRel.split(path.sep).join('/');
 
-            // Get sorting parameters from query string
-            const sortBy = ctx.query.sort || 'name';
-            const sortOrder = ctx.query.order || 'asc';
-
-            const baseUrl = pageHrefOutPrefix.pathname;
+            // Get sorting parameters from query string. Repeated parameters
+            // (?sort=a&sort=b) arrive as arrays from the query parser: take the
+            // first occurrence so sorting stays deterministic and regenerated
+            // links never embed "a,b" (#12).
+            const firstQueryValue = (v) => Array.isArray(v) ? v[0] : v;
+            const sortParam  = firstQueryValue(ctx.query.sort);
+            const orderParam = firstQueryValue(ctx.query.order);
+            const sortBy = sortParam || 'name';
+            const sortOrder = orderParam || 'asc';
+
+            // Base for the listing's self-referencing links (sort headers,
+            // paginator). Built from the WITH-prefix pathname — the out-prefix
+            // one would make these links escape urlPrefix (#2), unlike the
+            // parent/entry links which already use pageHref — and normalized
+            // to exactly one trailing slash: the pathname was slash-stripped
+            // for URL parsing, and linking the canonical /dir/ form spares a
+            // 301 redirect hop on every sort/pagination click.
+            const baseUrl = pageHref.pathname.endsWith('/')
+                ? pageHref.pathname
+                : pageHref.pathname + '/';
 
             // Preserves sort/order while overriding `page`; omits page when 0.
             function buildQueryUrl(targetPage) {
                 const params = [];
-                if (ctx.query.sort)  params.push(`sort=${encodeURIComponent(ctx.query.sort)}`);
-                if (ctx.query.order) params.push(`order=${encodeURIComponent(ctx.query.order)}`);
+                if (sortParam)  params.push(`sort=${encodeURIComponent(sortParam)}`);
+                if (orderParam) params.push(`order=${encodeURIComponent(orderParam)}`);
                 if (targetPage > 0)  params.push(`page=${targetPage}`);
                 return params.length ? `${baseUrl}?${params.join('&')}` : baseUrl;
             }
@@ -2601,12 +2981,18 @@ module.exports = function koaClassicServer(
             // (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;
+            // PATH-ABSOLUTE (#6): no origin — an absolute URL would embed the
+            // client-controlled Host header (cache-poisoning surface) and pin
+            // http:// behind a TLS-terminating proxy without app.proxy. And
+            // CANONICAL SLASH (#16): the parent is a directory, so link the
+            // /dir/ form directly instead of paying the 301 hop per click
+            // (previously the parent of /sub/ was even the bare origin).
             if (pageHrefOutPrefix.pathname !== "/") {
                 // Build parent directory URL without query parameters
-                const a_pD = currentPath.split("/");
+                const a_pD = pageHref.pathname.split("/");
                 a_pD.pop();
-                const parentDirectory = a_pD.join("/");
+                const joined = a_pD.join("/");
+                const parentDirectory = joined === "" ? "/" : joined + "/";
                 // Escape HTML to prevent XSS
                 parts.push(`<tr><td><a href="${escapeHtml(parentDirectory)}"><b>.. Parent Directory</b></a></td><td>DIR</td><td>-</td></tr>`);
             }
@@ -2615,8 +3001,10 @@ module.exports = function koaClassicServer(
             if (dir.length === 0) {
                 parts.push(emptyFolderRow);
             } else {
-                const _listingBaseUrl = pageHref.origin + pageHref.pathname;
-                const _listingOriginPrefix = pageHref.origin + options.urlPrefix;
+                // PATH-ABSOLUTE (#6): entry hrefs carry no origin either — the
+                // browser resolves them against the page's real origin/scheme.
+                const _listingBasePath = pageHref.pathname;
+                const _listingPrefixPath = options.urlPrefix; // "" without a prefix
 
                 // Collect item data with stat I/O in parallel (batched to avoid
                 // overwhelming the filesystem on very large directories).
@@ -2629,12 +3017,12 @@ module.exports = function koaClassicServer(
                             const type = getDirentType(item);
                             const itemPath = path.join(toOpen, s_name);
 
-                            // Build item URI without query parameters
+                            // Build item URI (path-absolute, no query parameters)
                             let itemUri;
-                            if (_listingBaseUrl === _listingOriginPrefix + "/" || _listingBaseUrl === _listingOriginPrefix) {
-                                itemUri = `${_listingOriginPrefix}/${encodeURIComponent(s_name)}`;
+                            if (_listingBasePath === _listingPrefixPath + "/" || _listingBasePath === _listingPrefixPath) {
+                                itemUri = `${_listingPrefixPath}/${encodeURIComponent(toWellFormedName(s_name))}`;
                             } else {
-                                itemUri = `${_listingBaseUrl}/${encodeURIComponent(s_name)}`;
+                                itemUri = `${_listingBasePath}/${encodeURIComponent(toWellFormedName(s_name))}`;
                             }
 
                             // Resolve symlinks and DT_UNKNOWN entries to their effective type.
@@ -2657,6 +3045,14 @@ module.exports = function koaClassicServer(
                                 }
                             }
 
+                            // Canonical trailing slash for directories (#16): link
+                            // the /dir/ form the trailing-slash redirect would
+                            // enforce anyway, so navigating the listing costs no
+                            // 301 hop per click. effectiveType 2 covers plain
+                            // directories and dir-resolved symlinks, consistent
+                            // with the rest of the listing logic.
+                            if (effectiveType === 2) itemUri += '/';
+
                             // Hidden check: skip entries that should not appear in directory listing
                             const itemIsDir = effectiveType === 2;
                             const itemRelPath = dirRelPath ? dirRelPath + '/' + s_name : s_name;
@@ -2741,7 +3137,7 @@ module.exports = function koaClassicServer(
                 // Pagination — slice the sorted items into the requested page (0-based).
                 const pageSize = options.dirListing.entriesPerPage; // 0 disables pagination
                 totalPages = pageSize > 0 ? Math.max(1, Math.ceil(items.length / pageSize)) : 1;
-                const rawPage = parseInt(ctx.query.page, 10);
+                const rawPage = parseInt(firstQueryValue(ctx.query.page), 10);
                 const requestedPage = Number.isFinite(rawPage) && rawPage >= 0 ? rawPage : 0;
                 currentPage = Math.min(requestedPage, totalPages - 1); // silent clamp
                 const visibleItems = (pageSize > 0 && items.length > pageSize)
@@ -2770,12 +3166,12 @@ module.exports = function koaClassicServer(
                                 : '';
 
                     if (item.isReserved) {
-                        parts.push(`${rowStart} ${escapeHtml(item.name)}${symlinkLabel}</td> <td> DIR BUT RESERVED</td><td>${item.sizeStr}</td></tr>`);
+                        parts.push(`${rowStart} <bdi>${listingDisplayName(item.name)}</bdi>${symlinkLabel}</td> <td> DIR BUT RESERVED</td><td>${item.sizeStr}</td></tr>`);
                     } else if (item.isBrokenSymlink || item.isBlockedSymlink) {
                         // Broken or policy-blocked symlink: name visible but not clickable
-                        parts.push(`${rowStart} ${escapeHtml(item.name)}${symlinkLabel}</td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
+                        parts.push(`${rowStart} <bdi>${listingDisplayName(item.name)}</bdi>${symlinkLabel}</td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
                     } else {
-                        parts.push(`${rowStart} <a href="${escapeHtml(item.itemUri)}">${escapeHtml(item.name)}</a>${symlinkLabel} </td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
+                        parts.push(`${rowStart} <bdi><a href="${escapeHtml(item.itemUri)}">${listingDisplayName(item.name)}</a></bdi>${symlinkLabel} </td> <td> ${escapeHtml(item.mimeType)} </td><td>${item.sizeStr}</td></tr>`);
                     }
                 }
             }
@@ -2843,6 +3239,14 @@ module.exports = function koaClassicServer(
                     </html>
                 `;
 
+            // Listings are dynamic pages — they change with directory content,
+            // sort and page — so an EXPLICIT no-cache policy is sent regardless
+            // of browserCacheEnabled: without it, browsers and shared proxies
+            // may heuristically cache a stale listing (#5). Same header trio the
+            // file path uses when browser caching is disabled.
+            ctx.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+            ctx.set('Pragma', 'no-cache');
+            ctx.set('Expires', '0');
             setGeneratedPageHeaders(ctx, LISTING_CSP);
             return html;
         }
@@ -2863,11 +3267,21 @@ module.exports._internals = {
     singleFlight,
     refreshOrInsert,
     escapeHtml,
+    // toWellFormedName / buildContentDisposition / listingDisplayName: the
+    // lone-surrogate class (#14) cannot be exercised through fixtures on
+    // POSIX (invalid UTF-8 names become U+FFFD at write time, and only
+    // Windows readdir can return WTF-16 names), so their totality is
+    // asserted at unit level here.
+    toWellFormedName,
+    buildContentDisposition,
+    listingDisplayName,
     // writeErrorPage is the shared output path for every middleware-generated error
-    // response (sendErrorPage / sendErrorPageSync delegate to it). Exposed so its
-    // contract — header scrub, no-store on >=500, Content-Type, custom-vs-built-in
-    // body, CSP only for the built-in page — can be asserted deterministically: the
-    // stream-failure branches that also use it can't be, because Koa 3 tears the
-    // socket down on a mid-stream body error before the client sees the response.
+    // response (sendErrorPage delegates to it). Exposed so its contract — header
+    // scrub, no-store, Content-Type, custom-vs-built-in body, CSP only for the
+    // built-in page — can be asserted deterministically. Mid-flight stream
+    // failures no longer route here at all (v5.0 register #5): the response is
+    // already on the wire and Koa 3 tears the socket down, so those branches
+    // only log; open-time failures are caught BEFORE the body is assigned
+    // (openBodyStream) and go through the regular async sendErrorPage.
     writeErrorPage,
 };