@nifrajs/web 5.5.0 → 5.6.0

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
+}