@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/parity.ts

@@ -99,6 +99,9 @@ export interface IdentityParityFinding {
    * before anything loads. Reported, never fatal - see `SingleCopyCoverage`.
    */
   readonly deduplicated: boolean
+  /** Unbundled commands that still load both copies of a deduplicated package, because bunfig.toml
+   * does not preload the registrar for them. Absent when both are covered. */
+  readonly unenforced?: readonly ("bun run" | "bun test")[]
 }
 
 /**
@@ -743,11 +746,34 @@ const describeProvenance = (copies: readonly IdentityParityCopy[]): string | und
   return `reached through ${one ? "a symlink" : "symlinks"} that ${one ? "points" : "point"} outside the importer's install: ${lines.join(", ")}. Unless the importer declares ${one ? "it" : "them"} as a \`link:\` dependency, ${one ? "the link was" : "the links were"} planted by hand, by another project, or by \`bun link\` - remove ${one ? "it" : "them"} and reinstall there, so the importer resolves its own install's copy.`
 }
 
-/** What is left to do about a duplicate the declaration already covers. */
-const deduplicatedRemediation = (registration: SingleCopyRegistration): string =>
-  registration.run || registration.test
-    ? "Declared single-copy and enforced: every duplicate is rewritten to this app's copy, so one module instance loads."
-    : `Declared single-copy, so bundled output is deduplicated by the build. Unbundled runs are NOT: Bun's runtime never offers a bare specifier to a resolver, so add preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"] to bunfig.toml (and under [test]) or \`bun test\` still loads both copies.`
+/**
+ * What is left to do about a duplicate the declaration already covers. Bun reads the top-level
+ * `preload` for `bun run` (and the nifra CLI, which runs under the app's bunfig) and `[test] preload`
+ * for `bun test`, never one for the other, so each half is reported on its own.
+ */
+const deduplicatedRemediation = (registration: SingleCopyRegistration): string => {
+  if (registration.run && registration.test)
+    return "Declared single-copy and enforced: every duplicate is rewritten to this app's copy, so one module instance loads."
+  const preload = `preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"]`
+  const ignored =
+    registration.ignored === undefined
+      ? ""
+      : ` The ${preload} under [${registration.ignored.join("], [")}] belongs to that table, so Bun never runs it.`
+  if (registration.test)
+    return `Declared single-copy and enforced under \`bun test\` only: \`bun run\`, \`nifra dev\` and the CLI's app imports still load both copies until bunfig.toml carries ${preload} at the top level, above the first [table].${ignored}`
+  if (registration.run)
+    return `Declared single-copy and enforced under \`bun run\` only: \`bun test\` still loads both copies until bunfig.toml carries ${preload} under [test].`
+  return `Declared single-copy, so bundled output is deduplicated by the build. Unbundled runs are NOT: Bun's runtime never offers a bare specifier to a resolver, so add ${preload} to bunfig.toml above the first [table], and again under [test], or \`bun run\` and \`bun test\` still load both copies.${ignored}`
+}
+
+const unenforcedCommands = (
+  registration: SingleCopyRegistration,
+): readonly ("bun run" | "bun test")[] => {
+  const commands: ("bun run" | "bun test")[] = []
+  if (!registration.run) commands.push("bun run")
+  if (!registration.test) commands.push("bun test")
+  return commands
+}
 
 /**
  * Read the declaration and its runtime proof, preferring the directory the caller is in.
@@ -861,6 +887,7 @@ export async function collectIdentityParity(
     // so the skew stays fatal and the ranges have to be fixed.
     const covered =
       cause === "duplicate-path" && matchesSingleCopyDeclaration(singleCopy.declared, name)
+    const unenforced = covered ? unenforcedCommands(singleCopy.registration) : []
     const finding: IdentityParityFinding = {
       package: name,
       copies: resolvedCopies,
@@ -880,7 +907,9 @@ export async function collectIdentityParity(
       ...(provenance === undefined ? {} : { provenance }),
       deduplicated: covered,
     }
-    ;(covered ? deduplicated : findings).push(finding)
+    ;(covered ? deduplicated : findings).push(
+      unenforced.length === 0 ? finding : { ...finding, unenforced },
+    )
   }
   return {
     workspaceRoot: scanRoot,

package/src/internal/ppr/admission.ts

@@ -0,0 +1,300 @@
+import type { ResolvedPprOptions } from "./options.ts"
+
+/** Which admission level denied an invocation, checked in this order. */
+export type DenialLevel = "stop" | "process" | "boundary"
+
+/** How one hole invocation ended, as its response sees it. */
+export type HoleRun<T> =
+  | { readonly ok: true; readonly value: T }
+  | {
+      readonly ok: false
+      readonly reason: "denied" | "failed" | "aborted"
+      readonly error?: unknown
+    }
+
+export interface PprAdmissionStats {
+  /** Responses holding a hole-work slot. */
+  readonly slotsInUse: number
+  /** Every invocation whose promise has not settled, abandoned ones included (`ppr.inflight_loaders`). */
+  readonly pending: number
+  /** The abandoned subset of {@link pending} (`ppr.abandoned_inflight`). */
+  readonly abandoned: number
+  readonly pendingBy: Readonly<Record<string, number>>
+  readonly abandonedBy: Readonly<Record<string, number>>
+  readonly denied: Readonly<Record<DenialLevel, number>>
+  /** Responses that found no free slot and invoked no hole (`ppr.shed`). */
+  readonly shed: number
+  /** True while the global admission stop holds (`ppr.admission_stopped`). */
+  readonly admissionStopped: boolean
+}
+
+type AdmissionOptions = Pick<
+  ResolvedPprOptions,
+  | "boundaryAbandonedTrip"
+  | "processAbandonedTrip"
+  | "admissionStop"
+  | "abandonGraceMs"
+  | "maxHoleWork"
+>
+
+/** The clock and timer admission reads; injected by tests so no test waits on the wall clock. */
+export interface AdmissionTimers {
+  now(): number
+  setTimeout(callback: () => void, ms: number): unknown
+  clearTimeout(handle: unknown): void
+}
+
+const SYSTEM_TIMERS: AdmissionTimers = {
+  now: () => performance.now(),
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the handle came from this object's own setTimeout.
+  clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+const watchers = new WeakMap<AbortSignal, Set<() => void>>()
+
+/**
+ * Calls `onAbort` when `signal` aborts, until the returned function is called. A signal gets one
+ * native listener that every watcher shares: adding and removing a native listener per hole
+ * invocation cost more under load than the invocation's own bookkeeping.
+ */
+export function watchAbort(signal: AbortSignal, onAbort: () => void): () => void {
+  let watching = watchers.get(signal)
+  if (watching === undefined) {
+    const created = new Set<() => void>()
+    watching = created
+    watchers.set(signal, created)
+    signal.addEventListener(
+      "abort",
+      () => {
+        for (const watcher of created) watcher()
+      },
+      { once: true },
+    )
+  }
+  const set = watching
+  set.add(onAbort)
+  return () => {
+    set.delete(onAbort)
+  }
+}
+
+/** A boundary's count, kept once made: an invocation changes its own count with no map lookup. */
+interface Count {
+  n: number
+}
+
+const countOf = (counts: Map<string, Count>, key: string): Count => {
+  let count = counts.get(key)
+  if (count === undefined) {
+    count = { n: 0 }
+    counts.set(key, count)
+  }
+  return count
+}
+
+const nonZero = (counts: Map<string, Count>): Record<string, number> => {
+  const out: Record<string, number> = {}
+  for (const [key, count] of counts) if (count.n !== 0) out[key] = count.n
+  return out
+}
+
+/**
+ * Bounds the hole work a process runs without letting one bad loader starve the rest.
+ *
+ * An invocation is abandoned once its signal aborted more than `abandonGraceMs` ago and its promise
+ * is still pending; it stays counted until the promise settles. Only abandoned invocations count
+ * toward a denial level, so a well-behaved boundary is denied only at the global stop. Each response
+ * holds one hole-work slot from before its first invocation until every invocation has settled,
+ * been denied or been abandoned, which bounds live invocations by `32 * maxHoleWork`.
+ */
+export class HoleAdmission {
+  readonly #options: AdmissionOptions
+  readonly #onLateSettle: ((key: string, msAfterAbort: number) => void) | undefined
+  readonly #timers: AdmissionTimers
+  readonly #pendingBy = new Map<string, Count>()
+  readonly #abandonedBy = new Map<string, Count>()
+  readonly #denied: Record<DenialLevel, number> = { stop: 0, process: 0, boundary: 0 }
+  #pending = 0
+  #abandoned = 0
+  #slotsInUse = 0
+  #shed = 0
+
+  constructor(
+    options: AdmissionOptions,
+    onLateSettle?: (key: string, msAfterAbort: number) => void,
+    timers: AdmissionTimers = SYSTEM_TIMERS,
+  ) {
+    this.#options = options
+    this.#onLateSettle = onLateSettle
+    this.#timers = timers
+  }
+
+  /** A hole-work slot for one response, or `undefined` when none is free (the response is shed). */
+  slot(): HoleSlot | undefined {
+    if (this.#slotsInUse >= this.#options.maxHoleWork) {
+      this.#shed++
+      return undefined
+    }
+    this.#slotsInUse++
+    return new HoleSlot(this, () => this.#slotsInUse--)
+  }
+
+  /** The level that denies boundary `key` now, or `undefined` when it is admitted. */
+  denial(key: string): DenialLevel | undefined {
+    if (this.#abandoned >= this.#options.admissionStop) return "stop"
+    const mine = this.#abandonedBy.get(key)?.n ?? 0
+    if (this.#abandoned >= this.#options.processAbandonedTrip && mine > 0) return "process"
+    if (mine >= this.#options.boundaryAbandonedTrip) return "boundary"
+    return undefined
+  }
+
+  /** @internal Counts one denial. */
+  countDenied(level: DenialLevel): void {
+    this.#denied[level]++
+  }
+
+  /**
+   * @internal Runs one admitted invocation, counted until its promise settles. Once its signal has
+   * been aborted for `abandonGraceMs` it is abandoned and `onDone` fires; `onDone` fires again when
+   * it settles. The result settles with the loader, or at once when the signal aborts first: a
+   * response never waits on a loader that ignores its signal. One promise and one abort watcher per
+   * invocation; a chain of them cost more than the loaders the bench page runs.
+   */
+  invoke<T>(
+    key: string,
+    signal: AbortSignal,
+    load: () => T | Promise<T>,
+    onDone: () => void,
+    watch: (onAbort: () => void) => () => void,
+  ): Promise<HoleRun<T>> {
+    this.#pending++
+    const pending = countOf(this.#pendingBy, key)
+    pending.n++
+    return new Promise<HoleRun<T>>((resolve) => {
+      let answered = false
+      const answer = (run: HoleRun<T>): void => {
+        if (answered) return
+        answered = true
+        resolve(run)
+      }
+      let abandoned: Count | undefined
+      let abortedAt: number | undefined
+      let timer: unknown
+      const onAbort = (): void => {
+        abortedAt = this.#timers.now()
+        timer = this.#timers.setTimeout(() => {
+          abandoned = countOf(this.#abandonedBy, key)
+          abandoned.n++
+          this.#abandoned++
+          onDone()
+        }, this.#options.abandonGraceMs)
+        answer({ ok: false, reason: "aborted", error: signal.reason })
+      }
+      let unwatch: (() => void) | undefined
+      if (signal.aborted) onAbort()
+      else unwatch = watch(onAbort)
+      const settle = (): void => {
+        unwatch?.()
+        if (timer !== undefined) this.#timers.clearTimeout(timer)
+        this.#pending--
+        pending.n--
+        if (abandoned !== undefined) {
+          this.#abandoned--
+          abandoned.n--
+        }
+        if (abortedAt !== undefined) {
+          const late = this.#timers.now() - abortedAt
+          if (late > this.#options.abandonGraceMs) this.#onLateSettle?.(key, late)
+        }
+        onDone()
+      }
+      // `then` turns a synchronous throw into this invocation's rejection.
+      Promise.resolve()
+        .then(load)
+        .then(
+          (value) => {
+            settle()
+            answer({ ok: true, value })
+          },
+          (error: unknown) => {
+            settle()
+            answer({ ok: false, reason: signal.aborted ? "aborted" : "failed", error })
+          },
+        )
+    })
+  }
+
+  stats(): PprAdmissionStats {
+    return {
+      slotsInUse: this.#slotsInUse,
+      pending: this.#pending,
+      abandoned: this.#abandoned,
+      pendingBy: nonZero(this.#pendingBy),
+      abandonedBy: nonZero(this.#abandonedBy),
+      denied: { ...this.#denied },
+      shed: this.#shed,
+      admissionStopped: this.#abandoned >= this.#options.admissionStop,
+    }
+  }
+}
+
+/** One response's hole-work slot. Released exactly once. */
+export class HoleSlot {
+  readonly #admission: HoleAdmission
+  readonly #release: () => void
+  #outstanding = 0
+  #sealed = false
+  #released = false
+
+  constructor(admission: HoleAdmission, release: () => void) {
+    this.#admission = admission
+    this.#release = release
+  }
+
+  /**
+   * Invoke one hole loader under admission. Denied, it is never invoked. Otherwise the result
+   * settles with the loader, or at once when `signal` aborts while the loader is still pending.
+   * `watch` reports that abort; the caller that aborts the signal itself passes its own.
+   */
+  run<T>(
+    key: string,
+    signal: AbortSignal,
+    load: () => T | Promise<T>,
+    watch: (onAbort: () => void) => () => void = (onAbort) => watchAbort(signal, onAbort),
+  ): Promise<HoleRun<T>> {
+    if (this.#sealed) throw new Error("[nifra/web] ppr: a sealed hole slot cannot start a hole")
+    if (signal.aborted) return Promise.resolve({ ok: false, reason: "aborted" })
+    const level = this.#admission.denial(key)
+    if (level !== undefined) {
+      this.#admission.countDenied(level)
+      return Promise.resolve({ ok: false, reason: "denied" })
+    }
+    this.#outstanding++
+    let done = false
+    return this.#admission.invoke(
+      key,
+      signal,
+      load,
+      () => {
+        if (done) return
+        done = true
+        this.#outstanding--
+        this.#maybeRelease()
+      },
+      watch,
+    )
+  }
+
+  /** No more holes will start for this response; the slot frees once the started ones are done. */
+  seal(): void {
+    this.#sealed = true
+    this.#maybeRelease()
+  }
+
+  #maybeRelease(): void {
+    if (this.#released || !this.#sealed || this.#outstanding > 0) return
+    this.#released = true
+    this.#release()
+  }
+}

package/src/internal/ppr/canary.ts

@@ -0,0 +1,122 @@
+import { MAX_SHELL_AFTER_REQUESTS } from "./options.ts"
+
+/** Where a canary value went into the request whose shell carried it. */
+export type CanaryCarrier = "cookie" | "authorization" | "header" | "query"
+
+export interface ShellCanaryFinding {
+  readonly path: string
+  readonly via: CanaryCarrier
+  /** The shared hole whose frame carried it; absent when the shell did. */
+  readonly hole?: string
+}
+
+export interface ShellCanaryOptions {
+  /** The origin the requests are made against. Default `http://canary.invalid`. */
+  readonly origin?: string
+}
+
+const CARRIERS: readonly CanaryCarrier[] = ["cookie", "authorization", "header", "query"]
+
+/** Where a streamed document's per-response part starts: everything before it is the shared shell. */
+const REQUEST_SCRIPT = '<script type="application/json" id="nifra-ppr-req">'
+const SCRIPT_END = "</script>"
+
+/** Requests per path: enough for a shell to be built, then for each shared hole's entry. */
+const MAX_ATTEMPTS = 2 * MAX_SHELL_AFTER_REQUESTS
+
+/** The JSON text of the inert script element opened by `opener`, or `undefined` without one. */
+const scriptText = (html: string, opener: string): string | undefined => {
+  const start = html.indexOf(opener)
+  if (start === -1) return undefined
+  const end = html.indexOf(SCRIPT_END, start + opener.length)
+  return end === -1 ? undefined : html.slice(start + opener.length, end)
+}
+
+const parsed = (text: string | undefined): unknown => {
+  if (text === undefined) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/** The shared holes' frames a response carries, by name, when every one carries its entry. */
+function sharedFrames(html: string): ReadonlyMap<string, string> | undefined {
+  const request = parsed(scriptText(html, REQUEST_SCRIPT))
+  const names =
+    typeof request === "object" && request !== null ? Reflect.get(request, "shared") : undefined
+  const frames = new Map<string, string>()
+  if (!Array.isArray(names)) return frames
+  for (const name of names) {
+    if (typeof name !== "string") return undefined
+    const text = scriptText(html, `<script type="application/json" id="nifra-ppr:${name}">`)
+    const frame = parsed(text)
+    // An error frame holds nothing built: the entry is not there yet.
+    if (text === undefined || typeof frame !== "object" || frame === null) return undefined
+    if (Reflect.get(frame, "error") === true) return undefined
+    frames.set(name, text)
+  }
+  return frames
+}
+
+const randomHex = (): string =>
+  Array.from(crypto.getRandomValues(new Uint8Array(12)), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("")
+
+/**
+ * The canary check. Each path is requested through the app's own middleware and gates with a
+ * unique value in a cookie, an `Authorization` header, a custom header and the query, until a
+ * response carries a shell (`shellAfterRequests` decides which request builds it) and a built frame
+ * for each shared hole, and those are scanned for every value the path's requests carried. It
+ * catches visitor data the app keeps in module state, which no import check sees. Run it against a
+ * fresh app before it serves traffic: a shell or frame already cached was built without the canaries.
+ */
+export async function checkShellCanaries(
+  app: { fetch(request: Request): Response | Promise<Response> },
+  paths: readonly string[],
+  options: ShellCanaryOptions = {},
+): Promise<readonly ShellCanaryFinding[]> {
+  const findings: ShellCanaryFinding[] = []
+  for (const path of paths) {
+    const sent: Array<Record<CanaryCarrier, string>> = []
+    // A route that renders whole every time reports nothing.
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const values: Record<CanaryCarrier, string> = {
+        cookie: `nifra-canary-${randomHex()}`,
+        authorization: `nifra-canary-${randomHex()}`,
+        header: `nifra-canary-${randomHex()}`,
+        query: `nifra-canary-${randomHex()}`,
+      }
+      sent.push(values)
+      const url = new URL(path, options.origin ?? "http://canary.invalid")
+      url.searchParams.set("nifra_canary", values.query)
+      const response = await app.fetch(
+        new Request(url.href, {
+          headers: {
+            cookie: `nifra_canary=${values.cookie}`,
+            authorization: `Bearer ${values.authorization}`,
+            "x-nifra-canary": values.header,
+          },
+        }),
+      )
+      const html = await response.text()
+      const end = html.indexOf(REQUEST_SCRIPT)
+      // No shared shell yet: this request rendered whole, so nothing it saw is shared.
+      if (end === -1) continue
+      const frames = sharedFrames(html)
+      // A shared hole whose entry is still being built: a later request gets it.
+      if (frames === undefined && attempt < MAX_ATTEMPTS - 1) continue
+      const shell = html.slice(0, end)
+      const carried = (text: string, via: CanaryCarrier): boolean =>
+        sent.some((earlier) => text.includes(earlier[via]))
+      for (const via of CARRIERS) if (carried(shell, via)) findings.push({ path, via })
+      for (const [hole, frame] of frames ?? []) {
+        for (const via of CARRIERS) if (carried(frame, via)) findings.push({ path, via, hole })
+      }
+      break
+    }
+  }
+  return findings
+}