@nifrajs/core 5.2.0 → 5.4.0

package/src/server/server.ts

@@ -113,7 +113,7 @@ import {
   readBodyFramed,
 } from "./request-context.ts"
 import { recordRequestReplacement } from "./request-lineage.ts"
-import { hasDotSegment, resolveDotSegments } from "./request-target.ts"
+import { needsResolving, resolveDotSegments } from "./request-target.ts"
 import {
   applyStaticResponseHeaders,
   buildStaticResponseHeaders,
@@ -583,14 +583,21 @@ export { plainValidationError } from "./validation.ts"
 // importers keep resolving `searchOf`/`queryObjectOf`/`QueryValue` from here.
 export { type QueryValue, queryObjectOf, searchOf }
 
+// Outside the printable ASCII a parsed path keeps as written: a control, space, `"`, `#`, `<`, `>`,
+// `\`, `^`, `` ` ``, `{`, `}`, or past ASCII (U+FFFD, an invalid escape, included). Bun's table reads
+// a raw `#` and what follows as path, where the parsed URL ends the path there.
+const UNROUTED_CHAR = /[^!$%&'()*+,\-./0-9:;=?@A-Z[\]_a-z|~]/
+
 /**
  * A param value Bun's native route table matched but the portable router must decide: an invalid
  * escape, or a piece of path Bun matched raw while its own parsed URL says otherwise - a `.` / `..`
- * segment (Bun hands `%2e` over decoded), or a backslash, which the parsed URL reads as `/`.
+ * segment (Bun hands `%2e` over decoded), a backslash, which the parsed URL reads as `/`, a `#`,
+ * where the parsed URL's path ends (`/a/..#/b` is `/`), or a character the parsed URL
+ * percent-encodes (`/t/<b>` is `/t/%3Cb%3E`, which a static route for that text matches). The value
+ * is decoded, so a raw `<` and a sent `%3C` look alike; both are re-routed.
  */
 const unroutedParam = (value: string | undefined): boolean =>
-  value !== undefined &&
-  (value.includes("\uFFFD") || value.includes("\\") || value === "." || value === "..")
+  value !== undefined && (value === "." || value === ".." || UNROUTED_CHAR.test(value))
 
 function hasUnroutedParam(params: Record<string, string>): boolean {
   for (const key in params) {
@@ -605,9 +612,19 @@ function hasUnroutedParam(params: Record<string, string>): boolean {
  */
 const rawRequestTargets = typeof (globalThis as { Deno?: unknown }).Deno !== "undefined"
 
-/** `req` as Bun or workerd would have delivered it: the same request, its URL's dot segments resolved. */
+/** `req` as Bun or workerd would have delivered it: the same request, its URL resolved as they parse it. */
 const withResolvedTarget = (req: Request): Request => new Request(resolveDotSegments(req.url), req)
 
+// A Host as RFC 9110 allows it: a reg-name or an IP literal, then an optional port. Deno builds
+// `Request.url` by appending the target to the Host as received, so `Host: x/admin#` turned a
+// request for `/public` into one for `/admin`. Node refuses such a Host before routing; so does this.
+const HOST_AUTHORITY = /^(?:\[[0-9a-f:.%]+\]|[\w.-]+)(?::\d{1,5})?$/i
+
+const invalidHost = (req: Request): boolean => {
+  const host = req.headers.get("host")
+  return host !== null && !HOST_AUTHORITY.test(host)
+}
+
 function normalizeMountPrefix(path: string): string {
   if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
     throw new TypeError("mountFetch path must be an absolute pathname without a query or hash")
@@ -844,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. */
@@ -875,6 +895,7 @@ const beginHookAudit = (
   policy: "warn" | "error" | "off",
   hasCustomLogger: boolean,
 ): void => {
+  unsealedHookAudits++
   hookAudit.set(key, {
     policy,
     hasCustomLogger,
@@ -990,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(
@@ -3159,7 +3181,10 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
   fetch(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<Response> {
     // Deno's `Request.url` is the target as sent; Bun, workerd and every `new Request()` parse it.
     // Route what the parsed URL says, so `/users/../admin` is `/admin` on every runtime.
-    if (rawRequestTargets && hasDotSegment(req.url)) req = withResolvedTarget(req)
+    if (rawRequestTargets) {
+      if (invalidHost(req)) return jsonError(400, "invalid_host")
+      if (needsResolving(req.url)) req = withResolvedTarget(req)
+    }
     // An edge deployment whose only ingress is this method declares its requests runtime-framed at
     // construction; everything else stays on the delivered-byte check (see `trustBodyFraming`).
     if (this.trustBodyFraming) markTrustedBodyFraming(req)
@@ -3173,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)
@@ -3358,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
@@ -3654,8 +3679,13 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext, Hook
     if (req.method !== "GET") return WS_PASS
     // The adapter answers a pass by handing this same object to `fetch`.
     const received = req
-    // The handshake routes the path `fetch` would: dot segments resolved (see `fetch`).
-    if (rawRequestTargets && hasDotSegment(req.url)) req = withResolvedTarget(req)
+    // The handshake routes the path `fetch` would: Host checked, dot segments resolved (see `fetch`).
+    if (rawRequestTargets) {
+      if (invalidHost(req)) {
+        return { kind: "reject", response: this.wrapWebResponse(jsonError(400, "invalid_host")) }
+      }
+      if (needsResolving(req.url)) req = withResolvedTarget(req)
+    }
     // The handshake's caller is the one `fetch` derives: hooks and `upgrade()` see the trusted IP.
     platform = this.trustedPlatform(req, platform)
 

package/src/server/websocket.ts

@@ -60,6 +60,9 @@ export class TopicRegistry {
   private readonly memberships = new WeakMap<NifraWebSocket, Set<string>>()
 
   subscribe(topic: string, ws: NifraWebSocket): void {
+    // CLOSING or CLOSED: close has run, or is about to run, `unsubscribeAll`, so an async handler's
+    // late subscribe would hold the dead socket for good.
+    if (ws.readyState >= 2) return
     let subs = this.topics.get(topic)
     if (subs === undefined) {
       subs = new Set()

package/src/static-file.ts

@@ -0,0 +1,306 @@
+/**
+ * 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
+}
+
+/** 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>
+
+/**
+ * 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 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: 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 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
+  }
+
+  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)
+      }
+    },
+  }
+}

package/src/tool-contract.ts

@@ -469,8 +469,9 @@ export async function executeTool<Input, Output>(
       await options.idempotency?.abandon(reservationInput(reservation))
     } catch {}
   }
-  // Once the executor has run, the reservation is never released: a retry would repeat a side effect
-  // that may have committed. A store that throws on completion counts as one that refused it.
+  // Once the executor has started, the reservation is never released, even when it throws: a retry
+  // would repeat a side effect that may have committed. A store that throws on completion counts as
+  // one that refused it.
   let executed = false
   const complete = async (): Promise<boolean> => {
     if (reservation === undefined) return true
@@ -660,6 +661,7 @@ export async function executeTool<Input, Output>(
       record("execution", "dry-run")
       return finish({ ok: true, dryRun })
     }
+    executed = true
     const output = await tool.execute(validatedInput.value, {
       effectId,
       signal,
@@ -667,7 +669,6 @@ export async function executeTool<Input, Output>(
       dryRun,
       ...(tool.policy === undefined ? {} : { policy: tool.policy }),
     })
-    executed = true
     record("execution", "committed")
     const validatedOutput = await validateStandard(tool.output, output)
     if (!validatedOutput.ok) {
@@ -699,7 +700,9 @@ export async function executeTool<Input, Output>(
     }
     return finish({ ok: true, dryRun, output: validatedOutput.value })
   } catch (error) {
-    if (!executed) await abandon()
+    // A completion the store refuses still leaves the key pending until its lease lapses.
+    if (executed) await complete()
+    else await abandon()
     const code = signal.aborted || isAbortError(error) ? "cancelled" : "execution_failed"
     record("execution", "failed", code)
     return finish({ ok: false, dryRun, error: { code, stage: "execution" } })

package/src/transport-codec.ts

@@ -228,8 +228,11 @@ export async function readBoundedBytes(
 ): Promise<Uint8Array> {
   const maxBytes = maxBytesOf(options)
   const declared = response.headers.get("content-length")
-  if (declared !== null && /^\d+$/u.test(declared) && Number(declared) > maxBytes)
+  if (declared !== null && /^\d+$/u.test(declared) && Number(declared) > maxBytes) {
+    // Refused unread, the body would otherwise hold its connection open until the sender gives up.
+    response.body?.cancel().catch(() => {})
     throw new TransportCodecError("transport payload exceeds maxBytes")
+  }
   if (response.body === null) return new Uint8Array(0)
   const reader = response.body.getReader()
   const chunks: Uint8Array[] = []