@nifrajs/core 5.3.0 → 5.4.0

package/dist/static-file.d.ts

@@ -0,0 +1,104 @@
+/**
+ * What a file served from disk is typed as, which files are never served, and when a client's copy of
+ * one is still current - the shared owner for every static-file surface.
+ *
+ * `@nifrajs/web`'s `servePublicDir` (dev, the Bun entry), the Deno entry's handler and
+ * `@nifrajs/node`'s `static` reader (the Node entry) answer the same deployed files. Copies that drift
+ * serve a `.pdf` as a download on one runtime and inline on the other, a `.well-known` file on one and
+ * a 404 on the other, or a resumed download spliced from two versions of a file on one, so all three
+ * read this module. The Node adapter runs a generated copy (scripts/gen-node-outcome.ts), so this
+ * module imports nothing.
+ */
+/**
+ * Media types by extension. A table rather than the runtime's own file typing, which Node and Deno
+ * lack. Unknown extensions, and extensionless files such as ACME tokens, are
+ * `application/octet-stream`, which together with `nosniff` keeps a browser from guessing a more
+ * dangerous type.
+ */
+export declare const CONTENT_TYPES: Readonly<Record<string, string>>;
+/** The media type for a file path or name by its extension, case-insensitively. */
+export declare function contentTypeOf(path: string): string;
+/**
+ * Whether a relative path crosses a dot-segment other than `.well-known` (RFC 8615, public by
+ * definition). Serving, the build's `public/` copy and the parity listing all apply it, so an editor
+ * or VCS artifact (`.env`, `.git/`, `.DS_Store`) is neither served nor shipped. Both separators split:
+ * a request path uses `/`, a relative file path the OS separator.
+ */
+export declare function isHiddenPath(rel: string): boolean;
+/**
+ * The stat fields that tell one version of a file from another on one host: node:fs `Stats` as it is,
+ * or Deno's `FileInfo` with its dates as epoch milliseconds and a field it lacks as `NaN`.
+ */
+export interface FileVersion {
+    readonly dev: number;
+    readonly ino: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+}
+/**
+ * The time a file can be dated by in Last-Modified, or `undefined`: its mtime, only while that is
+ * the time of its own last change. A copy or build that keeps or normalizes timestamps - `cp -p`,
+ * `rsync -a`, tar, a container image layer, SOURCE_DATE_EPOCH, the Nix store's 1 s - gives a
+ * same-size replacement the old file's date, so its files are left undated and their content tag
+ * validates them alone.
+ */
+export declare function lastModifiedOf(version: FileVersion): number | undefined;
+/**
+ * Whether the client's copy is current, so the answer is a bodyless 304. `If-None-Match` (the header,
+ * or `null`) decides whenever it is sent (RFC 9110 section 13.2.2), by weak comparison with `etag`, and
+ * `*` matches any file. Otherwise an `If-Modified-Since` at or after `lastModified` (epoch
+ * milliseconds), compared at the whole seconds an HTTP date carries; an unparseable date, or a file
+ * with no date, is never current.
+ */
+export declare function isNotModified(ifNoneMatch: string | null, ifModifiedSince: string | null, etag: string | undefined, lastModified: number | undefined): boolean;
+/**
+ * Whether `If-Range` (the header, or `null`) lets a range request be answered partially; otherwise the
+ * whole file is the conformant answer, not a fallback. An entity tag must equal the file's strong
+ * `etag` (RFC 9110 section 13.1.5). A date must equal `lastModified` to the second, and counts only
+ * for a file with no strong tag: a client holding the tag sends it, and a date cannot tell apart two
+ * versions dated in the same second - here or on another instance - so resuming by one could splice
+ * them.
+ */
+export declare function ifRangeAllowsPartial(ifRange: string | null, etag: string | undefined, lastModified: number | undefined): boolean;
+/** What node:crypto's `createHash` returns; Bun, Node and Deno all provide it. */
+export interface ContentHash {
+    update(bytes: Uint8Array): unknown;
+    digest(encoding: "base64url"): string;
+}
+/** Reads into `bytes` from byte `position` of a file, resolving to the count read (0 at its end). */
+export type ReadAt = (bytes: Uint8Array, position: number) => Promise<number>;
+/**
+ * Strong entity tags from what a file holds, the same for the same bytes on every instance and
+ * runtime, so a replacement that keeps a file's size and timestamps still changes its tag. A tag is
+ * remembered per real path for the version it was computed from, so serving a known file reads no
+ * more than before.
+ */
+export interface ContentTags {
+    /** The tag remembered for this version of the file at `path`, if any. */
+    cached(path: string, version: FileVersion): string | undefined;
+    /** The tag of `bytes`, read whole from this version of the file at `path`. */
+    ofBytes(path: string, version: FileVersion, bytes: Uint8Array): string;
+    /**
+     * The tag of this version of the file at `path`, read whole through `read`; requests for a version
+     * already being read wait for that read. A file over {@link CONTENT_TAG_MAX} is not read: its tag
+     * names its identity on this host instead, or is `undefined` where the runtime reports none.
+     */
+    ofFile(path: string, version: FileVersion, read: ReadAt): Promise<string | undefined>;
+}
+export interface ContentTagOptions {
+    /** Most tags remembered at once (default 8192); past it the earliest is forgotten. */
+    readonly limit?: number;
+    /** The clock compared with a file's ctime (default `Date.now`). */
+    readonly now?: () => number;
+}
+/**
+ * Largest file tagged by its content. Its first request waits for one read of the whole file, ~0.1 s
+ * per 256 MiB with hardware SHA-256 and several times that on a slow disk or CPU, so a larger file -
+ * a long video that is only ever fetched by ranges, say - is tagged by its device, inode, size and
+ * times. That tag is still strong and changes with any replacement, but differs between instances.
+ */
+export declare const CONTENT_TAG_MAX: number;
+/** Tags from `createHash` - node:crypto's, which every runtime nifra serves files on provides. */
+export declare function contentTags(createHash: (algorithm: "sha256") => ContentHash, options?: ContentTagOptions): ContentTags;
+//# sourceMappingURL=static-file.d.ts.map

package/dist/static-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-file.d.ts","sourceRoot":"","sources":["../src/static-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuCzD,CAAA;AAEF,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAKjD;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAOD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAGvE;AAWD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAcT;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAQT;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAA;IAClC,MAAM,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAAA;CACtC;AAED,qGAAqG;AACrG,MAAM,MAAM,MAAM,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;IAC9D,8EAA8E;IAC9E,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAAA;IACtE;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACtF;AAED,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAoB,CAAA;AAqBhD,kGAAkG;AAClG,wBAAgB,WAAW,CACzB,UAAU,EAAE,CAAC,SAAS,EAAE,QAAQ,KAAK,WAAW,EAChD,OAAO,GAAE,iBAAsB,GAC9B,WAAW,CAsEb"}

package/dist/static-file.js

@@ -0,0 +1,238 @@
+/**
+ * What a file served from disk is typed as, which files are never served, and when a client's copy of
+ * one is still current - the shared owner for every static-file surface.
+ *
+ * `@nifrajs/web`'s `servePublicDir` (dev, the Bun entry), the Deno entry's handler and
+ * `@nifrajs/node`'s `static` reader (the Node entry) answer the same deployed files. Copies that drift
+ * serve a `.pdf` as a download on one runtime and inline on the other, a `.well-known` file on one and
+ * a 404 on the other, or a resumed download spliced from two versions of a file on one, so all three
+ * read this module. The Node adapter runs a generated copy (scripts/gen-node-outcome.ts), so this
+ * module imports nothing.
+ */
+/**
+ * Media types by extension. A table rather than the runtime's own file typing, which Node and Deno
+ * lack. Unknown extensions, and extensionless files such as ACME tokens, are
+ * `application/octet-stream`, which together with `nosniff` keeps a browser from guessing a more
+ * dangerous type.
+ */
+export const CONTENT_TYPES = Object.freeze({
+    ".html": "text/html; charset=utf-8",
+    ".htm": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".cjs": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".webmanifest": "application/manifest+json",
+    ".txt": "text/plain; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
+    ".csv": "text/csv; charset=utf-8",
+    ".xml": "application/xml",
+    ".rss": "application/rss+xml",
+    ".atom": "application/atom+xml",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".ico": "image/x-icon",
+    ".bmp": "image/bmp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".otf": "font/otf",
+    ".wasm": "application/wasm",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+    ".ogg": "audio/ogg",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".m4a": "audio/mp4",
+    ".vtt": "text/vtt; charset=utf-8",
+});
+/** The media type for a file path or name by its extension, case-insensitively. */
+export function contentTypeOf(path) {
+    const dot = path.lastIndexOf(".");
+    // A dot before the last separator belongs to a directory; a leading dot names a dotfile, not a type.
+    const name = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\")) + 1;
+    if (dot <= name)
+        return "application/octet-stream";
+    return CONTENT_TYPES[path.slice(dot).toLowerCase()] ?? "application/octet-stream";
+}
+/**
+ * Whether a relative path crosses a dot-segment other than `.well-known` (RFC 8615, public by
+ * definition). Serving, the build's `public/` copy and the parity listing all apply it, so an editor
+ * or VCS artifact (`.env`, `.git/`, `.DS_Store`) is neither served nor shipped. Both separators split:
+ * a request path uses `/`, a relative file path the OS separator.
+ */
+export function isHiddenPath(rel) {
+    for (const segment of rel.split(/[\\/]/)) {
+        if (segment.charCodeAt(0) === 46 /* '.' */ && segment !== ".well-known")
+            return true;
+    }
+    return false;
+}
+// A write sets a file's mtime and ctime together (a chmod or rename right after adds well under a
+// millisecond), and Deno truncates the ctime it reports to the second. No tool can set a ctime, so a
+// larger gap means the mtime came from somewhere else.
+const MODIFIED_LAG_MS = 1000;
+/**
+ * The time a file can be dated by in Last-Modified, or `undefined`: its mtime, only while that is
+ * the time of its own last change. A copy or build that keeps or normalizes timestamps - `cp -p`,
+ * `rsync -a`, tar, a container image layer, SOURCE_DATE_EPOCH, the Nix store's 1 s - gives a
+ * same-size replacement the old file's date, so its files are left undated and their content tag
+ * validates them alone.
+ */
+export function lastModifiedOf(version) {
+    const lag = Math.abs(version.ctimeMs - version.mtimeMs);
+    return version.mtimeMs > 0 && lag < MODIFIED_LAG_MS ? version.mtimeMs : undefined;
+}
+/** HTTP dates carry whole seconds; comparing raw milliseconds makes every file look stale. */
+function seconds(time) {
+    return Math.floor(time / 1000);
+}
+function opaqueTag(tag) {
+    return tag.startsWith("W/") ? tag.slice(2) : tag;
+}
+/**
+ * Whether the client's copy is current, so the answer is a bodyless 304. `If-None-Match` (the header,
+ * or `null`) decides whenever it is sent (RFC 9110 section 13.2.2), by weak comparison with `etag`, and
+ * `*` matches any file. Otherwise an `If-Modified-Since` at or after `lastModified` (epoch
+ * milliseconds), compared at the whole seconds an HTTP date carries; an unparseable date, or a file
+ * with no date, is never current.
+ */
+export function isNotModified(ifNoneMatch, ifModifiedSince, etag, lastModified) {
+    if (ifNoneMatch !== null) {
+        const current = etag === undefined ? undefined : opaqueTag(etag);
+        for (const raw of ifNoneMatch.split(",")) {
+            const candidate = raw.trim();
+            if (candidate === "*" || (current !== undefined && opaqueTag(candidate) === current)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if (ifModifiedSince === null || lastModified === undefined)
+        return false;
+    const since = Date.parse(ifModifiedSince);
+    return Number.isFinite(since) && seconds(since) >= seconds(lastModified);
+}
+/**
+ * Whether `If-Range` (the header, or `null`) lets a range request be answered partially; otherwise the
+ * whole file is the conformant answer, not a fallback. An entity tag must equal the file's strong
+ * `etag` (RFC 9110 section 13.1.5). A date must equal `lastModified` to the second, and counts only
+ * for a file with no strong tag: a client holding the tag sends it, and a date cannot tell apart two
+ * versions dated in the same second - here or on another instance - so resuming by one could splice
+ * them.
+ */
+export function ifRangeAllowsPartial(ifRange, etag, lastModified) {
+    if (ifRange === null)
+        return true;
+    const item = ifRange.trim();
+    const strong = etag !== undefined && !etag.startsWith("W/");
+    if (item.startsWith('"') || item.startsWith("W/"))
+        return strong && item === etag;
+    if (strong || lastModified === undefined)
+        return false;
+    const date = Date.parse(item);
+    return Number.isFinite(date) && seconds(date) === seconds(lastModified);
+}
+/**
+ * Largest file tagged by its content. Its first request waits for one read of the whole file, ~0.1 s
+ * per 256 MiB with hardware SHA-256 and several times that on a slow disk or CPU, so a larger file -
+ * a long video that is only ever fetched by ranges, say - is tagged by its device, inode, size and
+ * times. That tag is still strong and changes with any replacement, but differs between instances.
+ */
+export const CONTENT_TAG_MAX = 256 * 1024 * 1024;
+const READ_CHUNK = 1024 * 1024;
+// A file changed this recently can change again within its ctime's granularity (a jiffy on ext4, a
+// second on HFS+ and as Deno reports it) without its stat showing it, so it is not tagged by version.
+const RACY_MS = 2000;
+function sameVersion(a, b) {
+    return (a.ctimeMs === b.ctimeMs &&
+        a.mtimeMs === b.mtimeMs &&
+        a.size === b.size &&
+        a.ino === b.ino &&
+        a.dev === b.dev);
+}
+function quoted(hash) {
+    return `"${hash.digest("base64url").slice(0, 22)}"`;
+}
+/** Tags from `createHash` - node:crypto's, which every runtime nifra serves files on provides. */
+export function contentTags(createHash, options = {}) {
+    const limit = options.limit ?? 8192;
+    const now = options.now ?? Date.now;
+    const known = new Map();
+    const reading = new Map();
+    const remember = (path, version, tag) => {
+        if (!(now() - version.ctimeMs >= RACY_MS))
+            return;
+        const { dev, ino, size, mtimeMs, ctimeMs } = version;
+        known.delete(path);
+        known.set(path, { dev, ino, size, mtimeMs, ctimeMs, tag });
+        for (const earliest of known.keys()) {
+            if (known.size <= limit)
+                break;
+            known.delete(earliest);
+        }
+    };
+    const readWhole = async (path, version, read) => {
+        const hash = createHash("sha256");
+        const chunk = new Uint8Array(Math.min(version.size, READ_CHUNK));
+        let position = 0;
+        while (position < version.size) {
+            const count = await read(chunk.subarray(0, Math.min(chunk.length, version.size - position)), position);
+            if (count === 0)
+                break;
+            hash.update(chunk.subarray(0, count));
+            position += count;
+        }
+        const tag = quoted(hash);
+        if (position === version.size)
+            remember(path, version, tag);
+        return tag;
+    };
+    return {
+        cached(path, version) {
+            const entry = known.get(path);
+            return entry !== undefined && sameVersion(entry, version) ? entry.tag : undefined;
+        },
+        ofBytes(path, version, bytes) {
+            const hash = createHash("sha256");
+            hash.update(bytes);
+            const tag = quoted(hash);
+            if (bytes.byteLength === version.size)
+                remember(path, version, tag);
+            return tag;
+        },
+        async ofFile(path, version, read) {
+            if (version.size > CONTENT_TAG_MAX) {
+                const { dev, ino, size, mtimeMs, ctimeMs } = version;
+                if (!Number.isFinite(ino) || !(now() - ctimeMs >= RACY_MS))
+                    return undefined;
+                const hash = createHash("sha256");
+                hash.update(new TextEncoder().encode(`${dev}:${ino}:${size}:${mtimeMs}:${ctimeMs}`));
+                return quoted(hash);
+            }
+            const pending = reading.get(path);
+            if (pending !== undefined && sameVersion(pending.version, version))
+                return pending.tag;
+            const entry = { version, tag: readWhole(path, version, read) };
+            reading.set(path, entry);
+            try {
+                return await entry.tag;
+            }
+            finally {
+                // A read of a newer version may have replaced this entry; leave that one in place.
+                if (reading.get(path) === entry)
+                    reading.delete(path);
+            }
+        },
+    };
+}
+//# sourceMappingURL=static-file.js.map

package/dist/static-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-file.js","sourceRoot":"","sources":["../src/static-file.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/core",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "Bun-native, contract-first HTTP framework - the router, server, and route descriptor.",
   "keywords": [
     "bun",
@@ -200,6 +200,11 @@
       "types": "./dist/range.d.ts",
       "default": "./dist/range.js"
     },
+    "./static-file": {
+      "bun": "./src/static-file.ts",
+      "types": "./dist/static-file.d.ts",
+      "default": "./dist/static-file.js"
+    },
     "./contract": {
       "bun": "./src/server/contract.ts",
       "types": "./dist/server/contract.d.ts",

package/src/index.ts

@@ -16,7 +16,7 @@
  * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and
  * `check:publish` asserts it equals `@nifrajs/core`'s package version.
  */
-export const VERSION = "5.3.0" as const
+export const VERSION = "5.4.0" as const
 
 export type Version = typeof VERSION
 

package/src/range.ts

@@ -32,6 +32,63 @@ function validSize(size: number): void {
   }
 }
 
+/**
+ * `bytes=<digits>-<digits>`, the one form clients send, answered with a single scan; `undefined`
+ * for anything else, which the general path below answers. The answers must stay the general path's:
+ * test/range.test.ts compares both against a frozen copy of it.
+ */
+function parseSingleRange(value: string, size: number): ByteRangeResult | undefined {
+  const length = value.length
+  // `| 0x20` folds only ASCII case, which is all the general path's /bytes/i matches.
+  if (
+    length < 7 ||
+    value.charCodeAt(5) !== 0x3d ||
+    (value.charCodeAt(0) | 0x20) !== 0x62 ||
+    (value.charCodeAt(1) | 0x20) !== 0x79 ||
+    (value.charCodeAt(2) | 0x20) !== 0x74 ||
+    (value.charCodeAt(3) | 0x20) !== 0x65 ||
+    (value.charCodeAt(4) | 0x20) !== 0x73
+  ) {
+    return undefined
+  }
+  let dash = -1
+  for (let index = 6; index < length; index++) {
+    const code = value.charCodeAt(index)
+    if (code === 0x2d) {
+      if (dash !== -1) return undefined
+      dash = index
+    } else if (code < 0x30 || code > 0x39) {
+      return undefined
+    }
+  }
+  if (dash === -1) return undefined
+  const leftDigits = dash - 6
+  const rightDigits = length - dash - 1
+  // INTEGER: no leading zero.
+  if (
+    (leftDigits > 1 && value.charCodeAt(6) === 0x30) ||
+    (rightDigits > 1 && value.charCodeAt(dash + 1) === 0x30)
+  ) {
+    return { kind: "none" }
+  }
+  let start: number
+  let end: number
+  if (leftDigits === 0) {
+    // A suffix with no length, or a zero one, is ignored.
+    if (rightDigits === 0 || (rightDigits === 1 && value.charCodeAt(dash + 1) === 0x30)) {
+      return { kind: "none" }
+    }
+    const suffix = Number(value.slice(dash + 1))
+    start = suffix >= size ? 0 : size - suffix
+    end = size - 1
+  } else {
+    start = Number(value.slice(6, dash))
+    end = rightDigits === 0 ? size - 1 : Math.min(Number(value.slice(dash + 1)), size - 1)
+  }
+  if (start > end || start >= size || size === 0) return { kind: "unsatisfiable" }
+  return { kind: "satisfiable", ranges: [{ start, end }] }
+}
+
 /**
  * Parse an HTTP `Range: bytes=...` header against a known representation size.
  *
@@ -45,12 +102,14 @@ export function parseByteRange(value: string | null, size: number): ByteRangeRes
   // Bound the input before the regex runs, not after: an oversized header must never reach the
   // matcher in the first place.
   if (value.length > MAX_RANGE_HEADER_LENGTH) return { kind: "none" }
+  const single = parseSingleRange(value, size)
+  if (single !== undefined) return single
   const match = /^bytes\s*=\s*(.+)$/i.exec(value)
   if (match === null) return { kind: "none" }
   const source = match[1]!
   let separators = 0
-  for (const character of source) {
-    if (character === "," && ++separators >= MAX_RANGE_SPECIFIERS) return { kind: "none" }
+  for (let comma = source.indexOf(","); comma !== -1; comma = source.indexOf(",", comma + 1)) {
+    if (++separators >= MAX_RANGE_SPECIFIERS) return { kind: "none" }
   }
 
   const ranges: ByteRange[] = []

package/src/server/core-copies.ts

@@ -23,7 +23,7 @@ if (!copies.includes(here) && copies.push(here) > 1) {
 
 /** This copy's version: a literal like the package root's `VERSION` (no fs on the edge), which
  * `scripts/version.ts` rewrites on every release and `check:publish` asserts. */
-const COPY_VERSION = "5.3.0"
+const COPY_VERSION = "5.4.0"
 
 /** Record this copy's version beside its URL. Called by each `server()` behind the development guard,
  * so a production bundle drops it with the version; a copy that built a server has recorded one. */

package/src/server/server.ts

@@ -861,6 +861,9 @@ interface HookAuditState {
   checked: boolean
 }
 const hookAudit = /* @__PURE__ */ new WeakMap<object, HookAuditState>()
+// Audits begun and not yet sealed. Zero outside development, so a request tests it before the
+// NODE_ENV literal and never reads `process.env` (a native call of ~130 ns on Node).
+let unsealedHookAudits = 0
 
 /** Whether `from` reaches `target` through mounts that keep the path and take a request under `path`.
  * Module-level, not a `Server` method, so a production bundle drops it with its dev-only caller. */
@@ -892,6 +895,7 @@ const beginHookAudit = (
   policy: "warn" | "error" | "off",
   hasCustomLogger: boolean,
 ): void => {
+  unsealedHookAudits++
   hookAudit.set(key, {
     policy,
     hasCustomLogger,
@@ -1007,6 +1011,7 @@ const sealHookAudit = (
   const state = hookAudit.get(key)
   if (state === undefined || state.checked) return
   state.checked = true
+  unsealedHookAudits--
   if (state.policy === "off" || total + sockets === 0) return
   const own = total - state.merged
   const dead = state.sites.filter(
@@ -3193,8 +3198,8 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<Response> {
     // Seal once on the first request so test servers (no `listen()`) still get the dead-hook check.
-    // After that it is a single boolean read - the per-request cost the option promises to keep at zero.
-    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+    // After that it is one integer compare; the literal stays so a production define drops the branch.
+    if (unsealedHookAudits !== 0 && process.env.NODE_ENV !== "production")
       sealHookAudit(this, this.catalog.size, this.wsRoutes.length, this.logger)
     // Off path (default): straight through - one property check, no closure, no promise.
     if (this.capacityGate === undefined) return this.fetchSourceInner(source, platform)
@@ -3378,7 +3383,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     suppliedRuntime?: NodeOutcomeRuntime,
   ): MaybePromise<NodeServeOutcome> {
     // Seal once on the Node-direct lane too - it can bypass `fetchSource` entirely (hookless outcome).
-    if (hookAuditRuntime && process.env.NODE_ENV !== "production")
+    if (unsealedHookAudits !== 0 && process.env.NODE_ENV !== "production")
       sealHookAudit(this, this.catalog.size, this.wsRoutes.length, this.logger)
     // A paired header-only native hook can preserve the Node-direct JSON/body outcome for successful
     // responses. Arbitrary onResponse transforms need a real Web Response, but a buffered outcome can