@nifrajs/web 3.3.0 → 4.0.0

package/src/internal/cdn/core.ts

@@ -0,0 +1,316 @@
+/**
+ * The provider-neutral half of `@nifrajs/web/cdn`: the path tag every cached page carries, and the
+ * purge queue each provider runs its API calls through (coalescing, chunking, `Retry-After`).
+ */
+import type { CdnPurgeOutcome, CdnPurgeTarget, ISRPlatform } from "../../isr.ts"
+
+/** What a cacheable page tells the CDN: its tags and how long the CDN may serve it. */
+export interface CdnCacheInput {
+  readonly tags: readonly string[]
+  /** Seconds the CDN may serve the page as fresh. */
+  readonly maxAge: number
+  /** Seconds past `maxAge` the CDN may serve it while it refetches. */
+  readonly staleWhileRevalidate: number
+  /** Seconds past `maxAge` the CDN may serve it while the origin errors. */
+  readonly staleIfError?: number | undefined
+}
+
+/** A CDN nifra can tag pages for and purge. Build one with {@link defineCdnProvider}. */
+export interface CdnProvider extends CdnPurgeTarget {
+  readonly name: string
+  /** Most tags one response may carry on this CDN. */
+  readonly maxResponseTags: number
+  /** Headers that let the CDN store a page under `input.tags` (consumed by the CDN, not the browser). */
+  cacheHeaders(input: CdnCacheInput): Readonly<Record<string, string>>
+  /** Headers that keep the CDN from storing a page, whatever its rules say. */
+  noStoreHeaders(): Readonly<Record<string, string>>
+}
+
+/** One purge API call's result. A refusal is `retryable` when sending it again may succeed. */
+export type PurgeAttempt =
+  | { readonly ok: true }
+  | {
+      readonly ok: false
+      readonly retryable: boolean
+      readonly reason: string
+      readonly retryAfterMs?: number | undefined
+      readonly rateLimited?: boolean | undefined
+    }
+
+/** What a provider file supplies; {@link defineCdnProvider} adds the queue. */
+export interface CdnProviderDefinition {
+  readonly name: string
+  /** Most tags one purge API call may name. */
+  readonly tagsPerCall: number
+  readonly maxResponseTags: number
+  cacheHeaders(input: CdnCacheInput): Readonly<Record<string, string>>
+  noStoreHeaders(): Readonly<Record<string, string>>
+  purgeTags(tags: readonly string[]): Promise<PurgeAttempt>
+}
+
+/** A purge that did not go through, as reported to {@link PurgeQueueOptions.onError}. */
+export interface CdnPurgeError {
+  readonly code: "NIFRA_CDN_PURGE_FAILED" | "NIFRA_CDN_RATE_LIMITED"
+  readonly provider: string
+  readonly reason: string
+  /** How many tags the refused call named (never the tags or the credentials). */
+  readonly tags: number
+  /** Whether the queue gave up on them. */
+  readonly final: boolean
+}
+
+export interface PurgeQueueOptions {
+  /** Tags arriving within this window go out in one call (ms). Default 250. */
+  readonly debounceMs?: number
+  /** Attempts per call before a retryable refusal is given up on. Default 5. */
+  readonly maxAttempts?: number
+  /** Longest wait between attempts, `Retry-After` included (ms). Default 60000. */
+  readonly maxBackoffMs?: number
+  /** Most tags waiting or retrying at once; a purge past it is refused as retryable. Default 5000. */
+  readonly maxQueuedTags?: number
+  /** Where a refused purge is reported. Default: one `console.error` line per refusal. */
+  readonly onError?: (error: CdnPurgeError) => void
+  /** Timer for the debounce and the backoff; tests pass their own. */
+  readonly sleep?: (ms: number) => Promise<void>
+}
+
+const BASE32 = "abcdefghijklmnopqrstuvwxyz234567"
+
+function base32(bytes: Uint8Array): string {
+  let out = ""
+  let bits = 0
+  let value = 0
+  for (const byte of bytes) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      out += BASE32[(value >>> (bits - 5)) & 31]
+      bits -= 5
+    }
+  }
+  if (bits > 0) out += BASE32[(value << (5 - bits)) & 31]
+  return out
+}
+
+/**
+ * The tag every page a CDN stores carries for its own path, so a path purge works on CDNs that only
+ * purge by tag. It hashes the normalized pathname alone: the query and the host stay out, so one purge
+ * reaches every query variant and needs no knowledge of the public origin. Two hosts serving the same
+ * path share the tag, which can only make a purge reach more than asked, never serve a wrong page.
+ */
+export async function pathTag(path: string): Promise<string> {
+  const cut = path.search(/[?#]/)
+  // Joined as text, never resolved: `//host/x` stays a path, as the revalidation endpoint keys it.
+  const pathname = new URL(`http://n${cut === -1 ? path : path.slice(0, cut)}`).pathname
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(pathname))
+  return `nifra.p:${base32(new Uint8Array(digest)).slice(0, 26)}`
+}
+
+/** `Retry-After` as milliseconds: delta seconds or an HTTP date; undefined when absent or unreadable. */
+export function retryAfterMs(value: string | null, now = Date.now()): number | undefined {
+  if (value === null) return undefined
+  const trimmed = value.trim()
+  if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1000
+  const at = Date.parse(trimmed)
+  return Number.isNaN(at) ? undefined : Math.max(0, at - now)
+}
+
+/** A purge API reply read the same way for every HTTP provider. */
+export function attemptFromStatus(res: Response, reason: string): PurgeAttempt {
+  if (res.ok) return { ok: true }
+  const retryAfter = retryAfterMs(res.headers.get("retry-after"))
+  if (res.status === 429) {
+    return {
+      ok: false,
+      retryable: true,
+      rateLimited: true,
+      reason: "rate_limited",
+      retryAfterMs: retryAfter,
+    }
+  }
+  if (res.status >= 500) {
+    return {
+      ok: false,
+      retryable: true,
+      reason: `${reason}_${res.status}`,
+      retryAfterMs: retryAfter,
+    }
+  }
+  return { ok: false, retryable: false, reason: `${reason}_${res.status}` }
+}
+
+/** `max-age=..., stale-while-revalidate=...[, stale-if-error=...]` for a CDN TTL header. */
+export function cdnDirectives(input: CdnCacheInput): string {
+  const parts = [`max-age=${input.maxAge}`, `stale-while-revalidate=${input.staleWhileRevalidate}`]
+  if (input.staleIfError !== undefined) parts.push(`stale-if-error=${input.staleIfError}`)
+  return parts.join(", ")
+}
+
+function positive(value: number | undefined, fallback: number, name: string): number {
+  if (value === undefined) return fallback
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`[nifra/web/cdn] ${name} must be a finite non-negative number`)
+  }
+  return value
+}
+
+interface Waiter {
+  readonly tags: ReadonlySet<string>
+  readonly platform: ISRPlatform | undefined
+  readonly resolve: (outcome: CdnPurgeOutcome) => void
+}
+
+type TagState =
+  | { state: "accepted" }
+  | { state: "queued" }
+  | { state: "failed"; retryable: boolean; reason: string }
+
+/**
+ * A {@link CdnProvider} from a provider's API calls, with the purge queue in front: tags arriving
+ * within `debounceMs` go out together, chunked to the provider's per-call limit and sent one call at
+ * a time; a 429 or 5xx is retried with capped exponential backoff that honors `Retry-After`. A
+ * `purge` resolves once its tags' first attempt is answered: `accepted`, `queued` (a retry is
+ * pending, kept alive with `platform.waitUntil` on edge runtimes), or `failed`.
+ */
+export function defineCdnProvider(
+  definition: CdnProviderDefinition,
+  options: PurgeQueueOptions = {},
+): CdnProvider {
+  const debounceMs = positive(options.debounceMs, 250, "debounceMs")
+  const maxAttempts = Math.max(1, Math.floor(positive(options.maxAttempts, 5, "maxAttempts")))
+  const maxBackoffMs = positive(options.maxBackoffMs, 60_000, "maxBackoffMs")
+  const maxQueuedTags = positive(options.maxQueuedTags, 5000, "maxQueuedTags")
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+  const report =
+    options.onError ??
+    ((error: CdnPurgeError) =>
+      console.error(
+        `[nifra/web/cdn] ${error.code}: ${error.provider} refused a purge of ${error.tags} tag(s) (${error.reason})${error.final ? "" : "; retrying"}`,
+      ))
+
+  let pending = new Set<string>()
+  let waiters: Waiter[] = []
+  let scheduled = false
+  let retrying = 0
+  // Flushes run one after another, so the provider sees one purge call at a time from this queue.
+  let tail: Promise<void> = Promise.resolve()
+
+  const attempt = async (chunk: readonly string[]): Promise<PurgeAttempt> => {
+    try {
+      return await definition.purgeTags(chunk)
+    } catch {
+      // The provider's own error text can quote the request; only the kind leaves this function.
+      return { ok: false, retryable: true, reason: "network_error" }
+    }
+  }
+
+  const refusal = (
+    chunk: readonly string[],
+    result: PurgeAttempt & { ok: false },
+    final: boolean,
+  ) => {
+    try {
+      report({
+        code: result.rateLimited === true ? "NIFRA_CDN_RATE_LIMITED" : "NIFRA_CDN_PURGE_FAILED",
+        provider: definition.name,
+        reason: result.reason,
+        tags: chunk.length,
+        final,
+      })
+    } catch {
+      // A reporter that throws must not strand the purge or the callers waiting on it.
+    }
+  }
+
+  const retry = async (
+    chunk: readonly string[],
+    first: PurgeAttempt & { ok: false },
+  ): Promise<void> => {
+    retrying += chunk.length
+    try {
+      let last = first
+      for (let n = 2; n <= maxAttempts; n++) {
+        const backoff = Math.min(maxBackoffMs, 1000 * 2 ** (n - 2))
+        await sleep(Math.min(maxBackoffMs, Math.max(backoff, last.retryAfterMs ?? 0)))
+        const result = await attempt(chunk)
+        if (result.ok) return
+        last = result
+        if (!result.retryable || n === maxAttempts) {
+          refusal(chunk, result, true)
+          return
+        }
+        refusal(chunk, result, false)
+      }
+    } finally {
+      retrying -= chunk.length
+    }
+  }
+
+  const flush = async (): Promise<void> => {
+    const batch = [...pending]
+    const settled = waiters
+    pending = new Set()
+    waiters = []
+    scheduled = false
+    const states = new Map<string, TagState>()
+    const background: Promise<void>[] = []
+    for (let i = 0; i < batch.length; i += definition.tagsPerCall) {
+      const chunk = batch.slice(i, i + definition.tagsPerCall)
+      const result = await attempt(chunk)
+      let state: TagState
+      if (result.ok) state = { state: "accepted" }
+      else if (result.retryable && maxAttempts > 1) {
+        refusal(chunk, result, false)
+        background.push(retry(chunk, result))
+        state = { state: "queued" }
+      } else {
+        refusal(chunk, result, true)
+        state = { state: "failed", retryable: result.retryable, reason: result.reason }
+      }
+      for (const tag of chunk) states.set(tag, state)
+    }
+    const retries = background.length === 0 ? undefined : Promise.all(background)
+    for (const waiter of settled) {
+      if (retries !== undefined) waiter.platform?.waitUntil?.(retries)
+      let failed: (TagState & { state: "failed" }) | undefined
+      let queued = false
+      for (const tag of waiter.tags) {
+        const state = states.get(tag)
+        if (state?.state === "failed") failed = failed?.retryable === false ? failed : state
+        else if (state?.state === "queued") queued = true
+      }
+      waiter.resolve(
+        failed !== undefined
+          ? { cdn: "failed", retryable: failed.retryable, error: failed.reason }
+          : queued
+            ? { cdn: "queued", retryable: true }
+            : { cdn: "accepted", retryable: false },
+      )
+    }
+  }
+
+  return {
+    name: definition.name,
+    maxResponseTags: definition.maxResponseTags,
+    cacheHeaders: (input) => definition.cacheHeaders(input),
+    noStoreHeaders: () => definition.noStoreHeaders(),
+    async purge(target, platform) {
+      const tags = new Set(target.tags ?? [])
+      for (const path of target.paths ?? []) tags.add(await pathTag(path))
+      if (tags.size === 0) return { cdn: "accepted", retryable: false }
+      if (pending.size + retrying + tags.size > maxQueuedTags) {
+        return { cdn: "failed", retryable: true, error: "queue_full" }
+      }
+      const outcome = new Promise<CdnPurgeOutcome>((resolve) => {
+        for (const tag of tags) pending.add(tag)
+        waiters.push({ tags, platform, resolve })
+      })
+      if (!scheduled) {
+        scheduled = true
+        tail = tail.then(() => sleep(debounceMs)).then(flush)
+        platform?.waitUntil?.(tail)
+      }
+      return outcome
+    },
+  }
+}

package/src/internal/cdn/fastly.ts

@@ -0,0 +1,62 @@
+/**
+ * Fastly: `Surrogate-Key` (space-separated) and `Surrogate-Control`, purged in batches of up to 256
+ * keys. Soft purge by default, so a purged page is served stale while Fastly refetches it.
+ */
+import {
+  attemptFromStatus,
+  type CdnProvider,
+  cdnDirectives,
+  defineCdnProvider,
+  type PurgeQueueOptions,
+} from "./core.ts"
+
+export interface FastlyOptions {
+  readonly serviceId: string
+  /** A Fastly API token with the `purge_select` scope. Keep it in an env var. */
+  readonly apiToken: string
+  /** Mark purged pages stale instead of dropping them. Default `true`. */
+  readonly soft?: boolean
+  readonly queue?: PurgeQueueOptions
+  /** The fetch purge calls go through; tests pass their own. */
+  readonly fetch?: typeof fetch
+}
+
+export function fastly(options: FastlyOptions): CdnProvider {
+  if (!/^[A-Za-z0-9]+$/.test(options.serviceId)) {
+    throw new TypeError("[nifra/web/cdn] fastly: serviceId must be the service's alphanumeric id")
+  }
+  if (typeof options.apiToken !== "string" || options.apiToken === "") {
+    throw new TypeError("[nifra/web/cdn] fastly: apiToken is empty (is the env var set?)")
+  }
+  const send = options.fetch ?? fetch
+  const endpoint = `https://api.fastly.com/service/${options.serviceId}/purge`
+  const soft = options.soft !== false
+  return defineCdnProvider(
+    {
+      name: "fastly",
+      tagsPerCall: 256,
+      maxResponseTags: 1000,
+      cacheHeaders: (input) => ({
+        "surrogate-key": input.tags.join(" "),
+        "surrogate-control": cdnDirectives(input),
+      }),
+      noStoreHeaders: () => ({ "surrogate-control": "no-store" }),
+      async purgeTags(tags) {
+        const headers: Record<string, string> = {
+          "fastly-key": options.apiToken,
+          "content-type": "application/json",
+          accept: "application/json",
+        }
+        if (soft) headers["fastly-soft-purge"] = "1"
+        const res = await send(endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ surrogate_keys: tags }),
+        })
+        await res.body?.cancel()
+        return attemptFromStatus(res, "fastly")
+      },
+    },
+    options.queue,
+  )
+}

package/src/internal/cdn/vercel.ts

@@ -0,0 +1,95 @@
+/**
+ * Vercel's CDN: `Vercel-Cache-Tag` and `Vercel-CDN-Cache-Control`, both consumed by Vercel and kept
+ * from the browser. Tags are case-sensitive; at most 16 a purge call and 128 a response.
+ */
+import {
+  attemptFromStatus,
+  type CdnProvider,
+  cdnDirectives,
+  defineCdnProvider,
+  type PurgeQueueOptions,
+} from "./core.ts"
+
+type TagPurge = (tags: string | string[]) => Promise<unknown>
+
+export type VercelOptions = (
+  | {
+      /** `invalidateByTag` from `@vercel/functions`: inside a Vercel Function, no token needed. */
+      readonly invalidateByTag: TagPurge
+      /** `dangerouslyDeleteByTag` from `@vercel/functions`, for `mode: "delete"`. */
+      readonly dangerouslyDeleteByTag?: TagPurge
+    }
+  | {
+      /** A Vercel access token for the REST API. Keep it in an env var. */
+      readonly token: string
+      readonly projectId: string
+      readonly teamId?: string
+      /** Purge one environment only; default both. */
+      readonly target?: "production" | "preview"
+      /** The fetch purge calls go through; tests pass their own. */
+      readonly fetch?: typeof fetch
+    }
+) & {
+  /**
+   * `invalidate` (default) marks tagged pages stale: the next visitor gets the old page while Vercel
+   * refetches. `delete` drops them, so the next visitors wait on the origin together.
+   */
+  readonly mode?: "invalidate" | "delete"
+  readonly queue?: PurgeQueueOptions
+}
+
+export function vercel(options: VercelOptions): CdnProvider {
+  const mode = options.mode ?? "invalidate"
+  let purgeTags: (
+    tags: readonly string[],
+  ) => ReturnType<Parameters<typeof defineCdnProvider>[0]["purgeTags"]>
+  if ("invalidateByTag" in options) {
+    const fn = mode === "delete" ? options.dangerouslyDeleteByTag : options.invalidateByTag
+    if (typeof fn !== "function") {
+      throw new TypeError(
+        `[nifra/web/cdn] vercel: pass ${mode === "delete" ? "dangerouslyDeleteByTag" : "invalidateByTag"} from @vercel/functions`,
+      )
+    }
+    purgeTags = async (tags) => {
+      await fn([...tags])
+      return { ok: true }
+    }
+  } else {
+    if (typeof options.token !== "string" || options.token === "") {
+      throw new TypeError("[nifra/web/cdn] vercel: token is empty (is the env var set?)")
+    }
+    if (typeof options.projectId !== "string" || options.projectId === "") {
+      throw new TypeError("[nifra/web/cdn] vercel: projectId is required")
+    }
+    const send = options.fetch ?? fetch
+    const query = new URLSearchParams({ projectIdOrName: options.projectId })
+    if (options.teamId !== undefined) query.set("teamId", options.teamId)
+    const path = mode === "delete" ? "dangerously-delete-by-tags" : "invalidate-by-tags"
+    const endpoint = `https://api.vercel.com/v1/edge-cache/${path}?${query}`
+    const token = options.token
+    const target = options.target
+    purgeTags = async (tags) => {
+      const res = await send(endpoint, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify(target === undefined ? { tags } : { tags, target }),
+      })
+      await res.body?.cancel()
+      return attemptFromStatus(res, "vercel")
+    }
+  }
+  return defineCdnProvider(
+    {
+      name: "vercel",
+      tagsPerCall: 16,
+      maxResponseTags: 128,
+      cacheHeaders: (input) => ({
+        "vercel-cache-tag": input.tags.join(","),
+        "vercel-cdn-cache-control": cdnDirectives(input),
+      }),
+      noStoreHeaders: () => ({ "vercel-cdn-cache-control": "no-store" }),
+      purgeTags,
+    },
+    options.queue,
+  )
+}

package/src/internal/code-unit-order.ts

@@ -0,0 +1,5 @@
+/** Code-unit order, the same on every runtime and in every locale. A build artifact or a report sorts
+ * with this, so its bytes and its order do not depend on the machine that produced it. */
+export function codeUnitOrder(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}