@nifrajs/core 5.3.0 → 5.5.0

package/dist/server/transport-lane.d.ts

@@ -1,5 +1,5 @@
 /** Opt-in versioned transport integration. Kept outside the server kernel's bare dependency graph. */
-import type { TransportCodec, TransportCodecRegistry } from "../transport-codec.js";
+import { type TransportCodec, type TransportCodecRegistry } from "../transport-codec.js";
 import { type ProtoPoisoning } from "./proto-guard.js";
 import type { IdentityPlugin } from "./server.js";
 interface TransportBodySource {
@@ -12,7 +12,7 @@ export type TransportDecodeResult = {
 } | {
     readonly matched: true;
     readonly value: unknown;
-    readonly byteLength: number;
+    readonly bytes: Uint8Array;
 } | {
     readonly matched: true;
     readonly response: Response;

package/dist/server/transport-lane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-lane.d.ts","sourceRoot":"","sources":["../../src/server/transport-lane.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,OAAO,KAAK,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnF,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEzE,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5D,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAA;IAChD,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACpC;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAA;IACpD,aAAa,CACX,MAAM,EAAE,mBAAmB,EAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,sBAAsB,EAChC,OAAO,GAAE,sBAA2B,GACnC,cAAc,CA6GhB"}
+{"version":3,"file":"transport-lane.d.ts","sourceRoot":"","sources":["../../src/server/transport-lane.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEzE,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5D,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAA;IAChD,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACpC;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAAA;IACpD,aAAa,CACX,MAAM,EAAE,mBAAmB,EAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,sBAAsB,EAChC,OAAO,GAAE,sBAA2B,GACnC,cAAc,CA+GhB"}

package/dist/server/transport-lane.js

@@ -1,3 +1,5 @@
+/** Opt-in versioned transport integration. Kept outside the server kernel's bare dependency graph. */
+import { encodeTransportResponse, } from "../transport-codec.js";
 import { readBoundedBytes } from "./body.js";
 import { jsonError } from "./http.js";
 import { guardDecodedValue } from "./proto-guard.js";
@@ -42,7 +44,7 @@ export function transportCodecs(registry, options = {}) {
                 return {
                     matched: true,
                     value: guardDecodedValue(codec.decode(text), protoPoisoning, acceptRegExp),
-                    byteLength: read.bytes.byteLength,
+                    bytes: read.bytes,
                 };
             }
             catch {
@@ -73,36 +75,34 @@ export function transportCodecs(registry, options = {}) {
                 return undefined;
             if ("response" in decoded)
                 return decoded.response;
-            // Re-frame as a plain JSON request whose already-decoded value rides the pre-decoded stash;
-            // the body lane takes the stash verbatim (this lane owns the cap and poisoning policy), so
-            // the placeholder body is never parsed and codec machinery stays out of the kernel.
-            const headers = {};
-            request.headers.forEach((value, name) => {
-                headers[name] = value;
-            });
-            headers["content-type"] = "application/json";
-            headers["content-length"] = "2";
-            delete headers["transfer-encoding"];
+            // The decoded value rides the pre-decoded stash, which the body lane takes verbatim (this lane
+            // owns the cap and poisoning policy), so codec machinery stays out of the kernel. The request
+            // keeps the bytes and media type it was sent with: a route without a body schema, or a
+            // signature check, reads the payload itself, not a stand-in.
+            const headers = new Headers(request.headers);
+            headers.set("content-length", String(decoded.bytes.byteLength));
+            headers.delete("transfer-encoding");
             const normalized = new Request(request.url, {
                 method: request.method,
                 headers,
-                body: "{}",
+                // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: every reader behind readBoundedBytes yields an unshared buffer, which a Request body accepts.
+                body: decoded.bytes,
                 signal: request.signal,
             });
-            const stash = { value: decoded.value, byteLength: decoded.byteLength };
+            const stash = {
+                value: decoded.value,
+                byteLength: decoded.bytes.byteLength,
+                encoded: decoded.bytes,
+                contentType,
+            };
             Object.defineProperty(normalized, PRE_DECODED_BODY, { value: stash });
             return normalized;
         });
         app.afterHandle((result, context) => {
             if (result === undefined || result instanceof Response || isResponseResult(result))
                 return result;
-            const codec = runtime.responseCodec(context.req.headers.get("accept"));
-            const headers = new Headers(context.set.headers);
-            headers.set("content-type", codec.mediaType);
-            return new Response(codec.encode(result), {
-                status: context.set.status ?? 200,
-                headers,
-            });
+            // The representation depends on `Accept`, so the response says so to every shared cache.
+            return encodeTransportResponse(result, runtime.responseCodec(context.req.headers.get("accept")), { status: context.set.status ?? 200, headers: context.set.headers });
         });
         return app;
     };

package/dist/server/transport-lane.js.map

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

package/dist/static-file.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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;
+/**
+ * {@link lastModifiedOf} for a body streamed after its stat, where a write can still reach the bytes
+ * sent. Dated only once its change is older than the racy window, so such a write falls in a later
+ * HTTP-date second and the next `If-Modified-Since` fetches it. A weak validator: never pass it to
+ * {@link ifRangeAllowsPartial}, which would resume a range across two versions.
+ */
+export declare function streamedLastModifiedOf(version: FileVersion, now?: number): 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>;
+/**
+ * Entity tags from file bytes, consistent across instances and runtimes. Files beyond the content
+ * hash limit instead use a per-instance identity tag. Callers must serve the same immutable bytes
+ * they hash; static HTTP readers use bounded snapshots for that guarantee. A tag is remembered per
+ * real path for the version it was computed from.
+ */
+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 `bytes`, the whole file at `path` read after a stat that gave `version`. A small
+     * snapshot is hashed; a larger one takes the tag remembered for `version` when `restat`, called
+     * after the read, still reports that version, since no write reached the file in between.
+     */
+    ofSnapshot(path: string, version: FileVersion, bytes: Uint8Array, restat: () => Promise<FileVersion>): Promise<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 within this tagger instance instead, or is `undefined` without a stable identity.
+     * Reading a mutable inode and later streaming it does not preserve this tag's byte identity.
+     */
+    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 snapshot {@link ContentTags.ofSnapshot} hashes on every request (default 4 KiB). A larger
+     * one takes the tag remembered for its version once a restat shows that version. Raise it where a
+     * stat costs more than hashing, as on Deno.
+     */
+    readonly rehashMax?: 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 plus a random instance salt. Identity tags require immutable file versions and intentionally
+ * differ between tagger instances so local stat identities cannot collide across hosts.
+ */
+export declare const CONTENT_TAG_MAX: number;
+/** Static HTTP readers tag only a whole, bounded snapshot; streamed inodes can change after hashing. */
+export declare const CONTENT_SNAPSHOT_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":"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"}

package/dist/static-file.js

@@ -0,0 +1,269 @@
+/**
+ * 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;
+}
+/**
+ * {@link lastModifiedOf} for a body streamed after its stat, where a write can still reach the bytes
+ * sent. Dated only once its change is older than the racy window, so such a write falls in a later
+ * HTTP-date second and the next `If-Modified-Since` fetches it. A weak validator: never pass it to
+ * {@link ifRangeAllowsPartial}, which would resume a range across two versions.
+ */
+export function streamedLastModifiedOf(version, now = Date.now()) {
+    return now - version.ctimeMs >= RACY_MS ? lastModifiedOf(version) : 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 plus a random instance salt. Identity tags require immutable file versions and intentionally
+ * differ between tagger instances so local stat identities cannot collide across hosts.
+ */
+export const CONTENT_TAG_MAX = 256 * 1024 * 1024;
+/** Static HTTP readers tag only a whole, bounded snapshot; streamed inodes can change after hashing. */
+export const CONTENT_SNAPSHOT_MAX = 256 * 1024;
+// Past this, a restat proves a remembered version unchanged faster than hashing it again: served over
+// HTTP on Node and Bun, an 8 KiB file is 1.02-1.05x faster that way, a 4 KiB one no faster.
+const SNAPSHOT_REHASH_MAX = 4 * 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 rehashMax = options.rehashMax ?? SNAPSHOT_REHASH_MAX;
+    let instance;
+    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;
+    };
+    const cached = (path, version) => {
+        const entry = known.get(path);
+        return entry !== undefined && sameVersion(entry, version) ? entry.tag : undefined;
+    };
+    const 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;
+    };
+    return {
+        cached,
+        ofBytes,
+        async ofSnapshot(path, version, bytes, restat) {
+            if (bytes.byteLength > rehashMax) {
+                const tag = cached(path, version);
+                // A remembered version is settled, so any write since its stat would show in the restat.
+                if (tag !== undefined && cached(path, await restat()) === tag)
+                    return tag;
+            }
+            return ofBytes(path, version, bytes);
+        },
+        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");
+                // Filesystem identities are local: another host may reuse every one of these stat fields.
+                instance ??= crypto.getRandomValues(new Uint8Array(16));
+                hash.update(instance);
+                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.5.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.5.0" as const
 
 export type Version = typeof VERSION
 

package/src/internal/route-lanes.ts

@@ -119,22 +119,24 @@ export function selectRouteLanes(options: {
     !hasLedger &&
     around === 0
 
-  const lane: RouteExecutionLane = authBeforeValidation
-    ? "lifecycle"
-    : bare
-      ? "bare"
-      : bodyOnly
-        ? "body"
-        : !hasResponseContract &&
-            schema?.body === undefined &&
-            schema?.query !== undefined &&
-            plain &&
-            derives === 0 &&
-            beforeHandle === 0 &&
-            afterHandle === 0 &&
-            onError === 0
-          ? "query"
-          : "lifecycle"
+  // The idempotency gate lives in the general program, so an idempotent route always runs it.
+  const lane: RouteExecutionLane =
+    authBeforeValidation || hasIdempotency
+      ? "lifecycle"
+      : bare
+        ? "bare"
+        : bodyOnly
+          ? "body"
+          : !hasResponseContract &&
+              schema?.body === undefined &&
+              schema?.query !== undefined &&
+              plain &&
+              derives === 0 &&
+              beforeHandle === 0 &&
+              afterHandle === 0 &&
+              onError === 0
+            ? "query"
+            : "lifecycle"
 
   // Lifecycle routes with no params schema are the common middleware shape: derive/before plus an
   // optional query or body schema. Select their complete validation stage at registration so the