@nifrajs/core 5.3.0 → 5.5.0

package/src/server/transport-lane.ts

@@ -1,5 +1,9 @@
 /** Opt-in versioned transport integration. Kept outside the server kernel's bare dependency graph. */
-import type { TransportCodec, TransportCodecRegistry } from "../transport-codec.ts"
+import {
+  encodeTransportResponse,
+  type TransportCodec,
+  type TransportCodecRegistry,
+} from "../transport-codec.ts"
 import { readBoundedBytes } from "./body.ts"
 import { jsonError } from "./http.ts"
 import { guardDecodedValue, type ProtoPoisoning } from "./proto-guard.ts"
@@ -14,7 +18,7 @@ interface TransportBodySource {
 
 export type TransportDecodeResult =
   | { readonly matched: false }
-  | { readonly matched: true; readonly value: unknown; readonly byteLength: number }
+  | { readonly matched: true; readonly value: unknown; readonly bytes: Uint8Array }
   | { readonly matched: true; readonly response: Response }
 
 export interface TransportRuntime {
@@ -99,7 +103,7 @@ export function transportCodecs(
         return {
           matched: true,
           value: guardDecodedValue(codec.decode(text), protoPoisoning, acceptRegExp),
-          byteLength: read.bytes.byteLength,
+          bytes: read.bytes,
         }
       } catch {
         return {
@@ -129,36 +133,38 @@ export function transportCodecs(
       if (!decoded.matched) 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: Record<string, string> = {}
-      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 as Uint8Array<ArrayBuffer>,
         signal: request.signal as never,
       })
-      const stash: PreDecodedBody = { value: decoded.value, byteLength: decoded.byteLength }
+      const stash: PreDecodedBody = {
+        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/src/static-file.ts

@@ -0,0 +1,362 @@
+/**
+ * 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: Readonly<Record<string, string>> = 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: string): string {
+  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: string): boolean {
+  for (const segment of rel.split(/[\\/]/)) {
+    if (segment.charCodeAt(0) === 46 /* '.' */ && segment !== ".well-known") return true
+  }
+  return false
+}
+
+/**
+ * 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
+}
+
+// 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: FileVersion): number | undefined {
+  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: FileVersion,
+  now: number = Date.now(),
+): number | undefined {
+  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: number): number {
+  return Math.floor(time / 1000)
+}
+
+function opaqueTag(tag: string): string {
+  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: string | null,
+  ifModifiedSince: string | null,
+  etag: string | undefined,
+  lastModified: number | undefined,
+): boolean {
+  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: string | null,
+  etag: string | undefined,
+  lastModified: number | undefined,
+): boolean {
+  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)
+}
+
+/** 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 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: FileVersion, b: FileVersion): boolean {
+  return (
+    a.ctimeMs === b.ctimeMs &&
+    a.mtimeMs === b.mtimeMs &&
+    a.size === b.size &&
+    a.ino === b.ino &&
+    a.dev === b.dev
+  )
+}
+
+function quoted(hash: ContentHash): string {
+  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: (algorithm: "sha256") => ContentHash,
+  options: ContentTagOptions = {},
+): ContentTags {
+  const limit = options.limit ?? 8192
+  const now = options.now ?? Date.now
+  const rehashMax = options.rehashMax ?? SNAPSHOT_REHASH_MAX
+  let instance: Uint8Array | undefined
+  const known = new Map<string, FileVersion & { readonly tag: string }>()
+  const reading = new Map<
+    string,
+    { readonly version: FileVersion; readonly tag: Promise<string> }
+  >()
+
+  const remember = (path: string, version: FileVersion, tag: string): void => {
+    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: string, version: FileVersion, read: ReadAt): Promise<string> => {
+    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: string, version: FileVersion): string | undefined => {
+    const entry = known.get(path)
+    return entry !== undefined && sameVersion(entry, version) ? entry.tag : undefined
+  }
+
+  const ofBytes = (path: string, version: FileVersion, bytes: Uint8Array): string => {
+    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)
+      }
+    },
+  }
+}