@orkestrel/middleware 0.0.19 → 0.0.20

package/dist/src/server/index.cjs

@@ -10,7 +10,10 @@ let node_crypto = require("node:crypto");
 let node_os = require("node:os");
 let _src_core = require("../core/index.cjs");
 //#region src/server/constants.ts
-/** Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}. */
+/**
+* Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}:
+* `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415.
+*/
 var MULTIPART_STATUS = Object.freeze({
 	limit: 413,
 	malformed: 400,
@@ -23,33 +26,33 @@ var MULTIPART_STATUS = Object.freeze({
 * which would mint an unequal symbol per copy.
 */
 var MULTIPART_ERROR_BRAND = Symbol.for("@orkestrel/middleware.MultipartError");
-/** Names `createStatic`'s default directory-index filename. */
+/** Names `'index.html'`, `createStatic`'s default directory-index filename. */
 var DEFAULT_STATIC_INDEX = "index.html";
-/** Names `createStatic`'s `fallback: true` default excluded path prefix. */
+/** Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. */
 var DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
-/** Names `createStatic`'s default policy for a path carrying a dotfile segment. */
+/** Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. */
 var DEFAULT_STATIC_DOTFILES = "ignore";
 /**
-* Lists the content-codings the node face's `createCompression` offers — the two
-* `node:zlib` guarantees on every Node runtime, so this face never
+* Lists `['gzip', 'deflate']`, the content-codings the node face's `createCompression`
+* offers — what `node:zlib` guarantees on every Node runtime, so this face never
 * feature-detects.
 */
 var NODE_COMPRESSION_ENCODINGS = Object.freeze(["gzip", "deflate"]);
-/** Names the MIME type served when a file extension has no known mapping. */
+/** Names `'application/octet-stream'`, the MIME type served when a file extension has no known mapping. */
 var DEFAULT_CONTENT_TYPE = "application/octet-stream";
-/** Holds `createMultipart`'s default per-file byte-size cap. */
+/** Holds `10_485_760`, `createMultipart`'s default per-file byte-size cap. */
 var DEFAULT_MULTIPART_FILE_SIZE = 10485760;
-/** Holds `createMultipart`'s default maximum file-part count. */
+/** Holds `10`, `createMultipart`'s default maximum file-part count. */
 var DEFAULT_MULTIPART_FILE_COUNT = 10;
-/** Holds `createMultipart`'s default per-field byte-size cap. */
+/** Holds `65_536`, `createMultipart`'s default per-field byte-size cap. */
 var DEFAULT_MULTIPART_FIELD_SIZE = 65536;
-/** Holds `createMultipart`'s default maximum field-part count. */
+/** Holds `100`, `createMultipart`'s default maximum field-part count. */
 var DEFAULT_MULTIPART_FIELD_COUNT = 100;
-/** Holds `createMultipart`'s default combined request-body byte-size cap. */
+/** Holds `52_428_800`, `createMultipart`'s default combined request-body byte-size cap. */
 var DEFAULT_MULTIPART_TOTAL = 52428800;
-/** Holds the maximum bytes a single multipart part's header block may occupy before it is malformed. */
+/** Holds `16_384`, the maximum bytes a single multipart part's header block may occupy before it is malformed. */
 var MULTIPART_MAX_HEADER_BLOCK = 16384;
-/** Holds the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+/** Holds `65_536`, the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
 var MULTIPART_MAX_PREAMBLE = 65536;
 /**
 * Lists the Windows reserved device-name stems (CVE-2025-27210) — matched
@@ -168,7 +171,7 @@ function isMultipartError(value) {
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Checks whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+* Checks whether `pathname` is `prefix` itself or lies under it on a segment
 * boundary — the shared under-path test `resolveStaticPath`'s prefix strip
 * and `createStatic`'s SPA-fallback `exclude` both apply, so `exclude:
 * '/api'` matches `/api` and `/api/x` but never `/apifoo`.
@@ -193,7 +196,7 @@ function isUnderPath(pathname, prefix) {
 * fallback.
 *
 * @remarks
-* `GET` and `HEAD` are both eligible, and resolve the SAME shell: `HEAD` is
+* `GET` and `HEAD` are both eligible, and resolve the same shell: `HEAD` is
 * defined as `GET` without a body (RFC 9110 §9.3.2), so a navigation probe
 * that answered `404` while its `GET` answered `200` would report a resource
 * the very next request serves.
@@ -221,11 +224,11 @@ function resolveStaticFallbackPath(root, index, exclude, method, pathname, accep
 }
 /**
 * Checks whether `child` is `parent` itself or lies inside it on-disk — the
-* FILESYSTEM containment predicate `createStatic` applies to `fs.realpath`
+* filesystem containment predicate `createStatic` applies to `fs.realpath`
 * output (never to a URL pathname — that is {@link isUnderPath}'s job).
 *
 * @remarks
-* Argument order is `(child, parent)` — deliberately the OPPOSITE conceptual
+* Argument order is `(child, parent)` — deliberately the opposite conceptual
 * order from {@link isUnderPath}`(pathname, prefix)`, so a call site cannot
 * casually swap one predicate in for the other. Built on `path.relative`,
 * this is separator-correct on both POSIX (`/`) and win32 (`\`) — unlike a
@@ -248,14 +251,14 @@ function isContainedPath(child, parent) {
 	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${node_path.sep}`) && !(0, node_path.isAbsolute)(rel);
 }
 /**
-* Resolves a request pathname to an on-disk path UNDER `root`, or `undefined`
+* Resolves a request pathname to an on-disk path under `root`, or `undefined`
 * when it cannot — the traversal guard, whose algorithm and order are exact:
 * strip `prefix` on a segment boundary → `decodeURIComponent` (a
 * malformed escape refuses, never throws) → reject a NUL byte → strip the
-* leading path separator FIRST (so a leading `..` survives `normalize` as a
-* genuine climbing segment) → `normalize` → refuse any Windows reserved-
-* device-name segment ({@link isReservedDeviceName}) → `resolve` and require
-* the result under `root`.
+* leading path separator first (so a leading `..` survives `normalize` as a
+* genuine climbing segment) → `normalize` → refuse any Windows
+* reserved-device-name segment ({@link isReservedDeviceName}) → `resolve` and
+* require the result under `root`.
 *
 * @param root - The absolute root directory every result must resolve under
 * @param prefix - An optional URL path prefix stripped on a segment boundary
@@ -324,7 +327,7 @@ async function resolveContainedRealPath(candidate, rootReal) {
 *
 * @remarks
 * Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
-* and spaces (Windows drops them), takes the STEM before the first `.`,
+* and spaces (Windows drops them), takes the stem before the first `.`,
 * upper-cases it, and tests it against {@link RESERVED_DEVICE_NAMES}
 * (`CON PRN AUX NUL COM1-9 LPT1-9`) — an exact-stem match only, so
 * `console.js` and `nullable.css` are never flagged.
@@ -643,7 +646,7 @@ async function unlinkStagedFiles(body) {
 * response body routes through.
 *
 * @remarks
-* PULL-driven, not push-driven: the underlying node stream's async iterator
+* Pull-driven, not push-driven: the underlying node stream's async iterator
 * is only advanced (`iterator.next()`) from inside `pull(controller)`, which
 * the web `ReadableStream` invokes exactly when its internal queue has room
 * for more data. Exactly one disk chunk is read and enqueued per `pull` —
@@ -980,30 +983,30 @@ var MultipartParser = class MultipartParser {
 *
 * @remarks
 * Reads `request.body` chunk by chunk through its `ReadableStream` reader —
-* NEVER buffers the whole body — enforcing every {@link MultipartLimits} cap
+* never buffers the whole body — enforcing every {@link MultipartLimits} cap
 * the instant it is exceeded (reading stops, every already-staged temp file
 * is deleted, throws {@link MultipartError} with code `'limit'`). Each file
 * part streams to `join(directory, randomUUID())` — the client's declared
-* filename is METADATA ONLY, never a path component. A field OR file part
+* filename is metadata only, never a path component. A field or file part
 * named `__proto__` / `constructor` / `prototype` is silently skipped and
 * never keyed onto the returned {@link MultipartBody} (a skipped file's
 * staged temp file is unlinked immediately, since it can never be
 * referenced). A file part with an empty declared filename (`filename=""`)
-* AND a zero-byte body — the browser convention for an unselected optional
+* and a zero-byte body — the browser convention for an unselected optional
 * `<input type="file">` — is a silent no-op: its temp file is unlinked, it is
 * never counted against the `file.count` limit, and it never runs the
 * `allowed` check. A malformed
 * structure (missing/unterminated boundary, nameless part, an oversized
 * header block, or a preamble exceeding {@link MULTIPART_MAX_PREAMBLE} before
 * the first boundary) throws with code `'malformed'`. A file is accepted
-* against the configured `allowed` MIME list iff its SNIFFED bytes detect a
+* against the configured `allowed` MIME list exactly when its sniffed bytes detect a
 * type present in the list — sniff-authoritative, independent of whether the
 * declared `Content-Type` matches (that agreement is exposed separately as
 * `validated`); otherwise throws with code `'rejected'`. A
 * request abort mid-upload triggers the same fail-closed cleanup as a limit
 * breach. Returns `undefined` for a non-multipart request (untouched).
 *
-* Staging defaults to a process-owned directory created ONCE (lazily,
+* Staging defaults to a process-owned directory created once (lazily,
 * memoized across calls) with `mkdtemp` under `os.tmpdir()` and locked to
 * mode `0o700`; `options.directory` overrides it.
 *
@@ -1124,16 +1127,16 @@ function createAssets(options) {
 	};
 }
 /**
-* Serves static files from `options.root` over `node:fs` — the node-bound
-* static-file battery.
+* Serves static files from `options.root` over `node:fs` — the node-bound static-file
+* battery, answering conditional, ranged, and SPA-fallback requests.
 *
 * @remarks
-* Containment is enforced on CANONICAL paths, not merely the lexically
+* Containment is enforced on canonical paths, not merely the lexically
 * resolved one: `options.root` is canonicalized once (memoized) and every
 * request's candidate path is re-canonicalized (`fs.realpath`) before it is
 * served, so a symlink whose target escapes `root` is refused (falls through
 * to `next()`) even though the lexical path resolved inside `root`. A
-* symlink that resolves to a target still INSIDE `root` is unaffected and
+* symlink that resolves to a target still inside `root` is unaffected and
 * still serves normally. A dangling symlink (`realpath` throws `ENOENT`) or
 * any other `realpath` failure is treated as a miss — this battery never
 * throws or 500s on a symlink surprise. On a streamed response (a 200 or 206
@@ -1329,7 +1332,7 @@ function createStatic(options) {
 * {@link MultipartError} this battery's parser throws is re-thrown as an
 * {@link HTTPError} carrying the same status/message, so `createBoundary`
 * (or any HTTPError-aware renderer) maps it correctly without depending on
-* this node face's error type. Fail-closed on the DOWNSTREAM handler too: if
+* this node face's error type. Fail-closed on the downstream handler too: if
 * `next()` throws, every still-`'staged'` uploaded file is unlinked
 * (best-effort) before the error is re-thrown, so an unhandled downstream
 * failure never leaks temp files. A normal return leaves staged files
@@ -1368,12 +1371,11 @@ function createMultipart(options = {}) {
 	};
 }
 /**
-* Compresses response bodies through `node:zlib` — the node-bound sibling of
-* the core face's `CompressionStream`-feature-detected `createCompression`,
-* guaranteed available on any Node runtime rather than dependent on the
-* WHATWG `CompressionStream` global. Ships as a SEPARATE package entry point
-* (`@orkestrel/middleware/server`) from the core face's `createCompression`,
-* so the shared name is unambiguous per consumer import path.
+* Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather
+* than dependent on the WHATWG `CompressionStream` global. This battery is the
+* node-bound sibling of the core face's feature-detected `createCompression`, and it
+* ships from a separate package entry point (`@orkestrel/middleware/server`) so the
+* shared name is unambiguous per consumer import path.
 *
 * @remarks
 * Peer-type limitation, the same one the core face carries: the shipped