@nifrajs/web 3.5.0 → 4.0.0

package/src/diagnostic.ts

@@ -14,6 +14,22 @@
 import { readFileSync, realpathSync } from "node:fs"
 import { isAbsolute, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
+import { classify, type FixOption } from "./diagnostic-catalog.ts"
+
+export {
+  classify,
+  DIAGNOSTIC_CATALOG,
+  type FixOption,
+  isHydrationMismatch,
+} from "./diagnostic-catalog.ts"
+export {
+  buildFixPrompt,
+  type FixPrompt,
+  type FixPromptContext,
+  type FixPromptSurface,
+  fixPrompts,
+  promptPath,
+} from "./diagnostic-prompt.ts"
 
 /** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */
 export const LAST_ERROR_PATH = "/__nifra/last-error"
@@ -40,7 +56,7 @@ export interface Codeframe {
 
 /** The structured failure. Serialisable as-is to JSON for the agent surfaces. */
 export interface Diagnostic {
-  /** Stable, greppable identifier, e.g. `NIFRA_SERVER_ONLY_IN_CLIENT`. `NIFRA_UNHANDLED` when unrecognised. */
+  /** Stable, greppable identifier, e.g. `NIFRA_BACKEND_IN_CLIENT`. `NIFRA_UNHANDLED` when unrecognised. */
   readonly code: string
   readonly name: string
   readonly message: string
@@ -51,8 +67,10 @@ export interface Diagnostic {
   readonly cause?: string | undefined
   /** Plain-language "do this", when the failure is recognised. */
   readonly fix?: string | undefined
-  /** Docs section anchor for the code, e.g. `errors#server-only-in-client`. */
+  /** Docs section anchor for the code, e.g. `errors#backend-in-client`. */
   readonly docsAnchor?: string | undefined
+  /** The distinct ways to fix it, when more than one is right; `fix` covers them all in one line. */
+  readonly fixOptions?: readonly FixOption[] | undefined
 }
 
 /** Reads a source file's text, or returns undefined if it cannot (missing, binary, permission). */
@@ -178,61 +196,6 @@ export function buildCodeframe(
   return { file, line, column, lines }
 }
 
-/** A recognised failure shape: a stable code plus the plain-language cause/fix/anchor to attach. */
-interface CatalogEntry {
-  readonly code: string
-  readonly match: (name: string, message: string) => boolean
-  readonly cause: string
-  readonly fix: string
-  readonly docsAnchor: string
-}
-
-/**
- * The recognised-failure catalog. Seeded with the highest-signal nifra failures; extend it as new
- * classes of error earn a stable code. Order matters only in that the first match wins.
- */
-export const DIAGNOSTIC_CATALOG: readonly CatalogEntry[] = [
-  {
-    code: "NIFRA_SERVER_ONLY_IN_CLIENT",
-    match: (_n, m) => m.includes("server-only module(s) in the client bundle"),
-    cause:
-      "A module marked server-only was reachable from a client entry, so it would ship to the browser.",
-    fix: "Follow the import chain in the message and move the server-only use behind a loader/action or a `*.server.ts` boundary, so it never enters a client component.",
-    docsAnchor: "errors#server-only-in-client",
-  },
-  {
-    code: "NIFRA_NODE_BUILTIN_IN_CLIENT",
-    match: (_n, m) => m.includes("Node built-in(s) in the client bundle"),
-    cause: "A `node:` built-in was reached from a client entry; it has no browser implementation.",
-    fix: "Move the code using the built-in to the server (loader/action or `*.server.ts`); the message lists the import chain that pulled it in.",
-    docsAnchor: "errors#node-builtin-in-client",
-  },
-  {
-    code: "NIFRA_SCHEMA_PARSE",
-    match: (n, m) =>
-      n === "SchemaError" ||
-      /failed to (parse|validate)|invalid_type|expected .* received/i.test(m),
-    cause: "Data crossing a boundary did not match its declared schema.",
-    fix: "Check the value against the schema at the failing boundary (loader input, search params, or request body); parse-don't-cast means the shape must match exactly.",
-    docsAnchor: "errors#schema-parse",
-  },
-]
-
-/** Classify an error name+message against the catalog; falls back to the generic unhandled code. */
-export function classify(
-  name: string,
-  message: string,
-): {
-  code: string
-  cause?: string
-  fix?: string
-  docsAnchor?: string
-} {
-  const hit = DIAGNOSTIC_CATALOG.find((e) => e.match(name, message))
-  if (hit === undefined) return { code: "NIFRA_UNHANDLED" }
-  return { code: hit.code, cause: hit.cause, fix: hit.fix, docsAnchor: hit.docsAnchor }
-}
-
 /** Split an Error's `stack` into its leading message block and its frame lines. */
 function messageAndStack(err: Error): { message: string; stack: string } {
   const stack = err.stack ?? `${err.name}: ${err.message}`
@@ -251,6 +214,37 @@ export interface BuildDiagnosticOptions {
   readonly root?: string
   /** Injectable source reader (tests pass a fake; production reads the filesystem). */
   readonly read?: SourceReader
+  /** Whether a file's source may appear in the codeframe, given the path the codeframe would read. The
+   * overlay is served to a browser, so a dev server passes the zone check here and backend source never
+   * renders in it. */
+  readonly showSource?: (file: string) => boolean
+  /** A frame's authored position when its file was compiled by a plugin whose map the runtime did not
+   * apply (Bun ignores a plugin's inline map), so a compiled line never lands in the codeframe. */
+  readonly remap?: (
+    file: string,
+    line: number,
+    column: number,
+  ) => { readonly line: number; readonly column: number } | undefined
+}
+
+function remapFrames(
+  frames: DiagnosticFrame[],
+  remap: BuildDiagnosticOptions["remap"],
+): DiagnosticFrame[] {
+  if (remap === undefined) return frames
+  return frames.map((frame) => {
+    if (frame.file === undefined || frame.line === undefined || frame.column === undefined) {
+      return frame
+    }
+    const authored = remap(frame.file, frame.line, frame.column)
+    if (authored === undefined) return frame
+    const at = frame.raw.lastIndexOf(`:${frame.line}:${frame.column}`)
+    const raw =
+      at === -1
+        ? frame.raw
+        : `${frame.raw.slice(0, at)}:${authored.line}:${authored.column}${frame.raw.slice(at + `:${frame.line}:${frame.column}`.length)}`
+    return { raw, file: frame.file, line: authored.line, column: authored.column }
+  })
 }
 
 /**
@@ -262,18 +256,20 @@ export function buildDiagnostic(err: unknown, options: BuildDiagnosticOptions =
   const error = err instanceof Error ? err : new Error(String(err))
   const root = options.root ?? safeCwd()
   const { message } = messageAndStack(error)
-  const frames = parseFrames(error.stack ?? "")
+  const frames = remapFrames(parseFrames(error.stack ?? ""), options.remap)
   const top = topUserFrame(frames, root)
+  // The gate sees the path that will be read: a frame's text can come from a browser.
+  const source =
+    top?.file === undefined
+      ? undefined
+      : options.read === undefined
+        ? canonicalPath(top.file)
+        : top.file
   const codeframe =
-    top?.file !== undefined && top.line !== undefined
-      ? buildCodeframe(
-          options.read === undefined ? canonicalPath(top.file) : top.file,
-          top.line,
-          top.column,
-          options.read,
-        )
+    source !== undefined && top?.line !== undefined && (options.showSource?.(source) ?? true)
+      ? buildCodeframe(source, top.line, top.column, options.read)
       : undefined
-  const { code, cause, fix, docsAnchor } = classify(error.name || "Error", message)
+  const { code, cause, fix, docsAnchor, fixOptions } = classify(error.name || "Error", message)
   return {
     code,
     name: error.name || "Error",
@@ -284,6 +280,7 @@ export function buildDiagnostic(err: unknown, options: BuildDiagnosticOptions =
     cause,
     fix,
     docsAnchor,
+    fixOptions,
   }
 }
 

package/src/draft.ts

@@ -21,7 +21,7 @@ import {
   signValue,
   unsignValue,
 } from "@nifrajs/core/server"
-import { timingSafeEqual } from "./internal/timing-safe-equal.ts"
+import { assertTokenSecret, timingSafeEqual } from "./internal/timing-safe-equal.ts"
 
 /** The cookie name nifra uses for draft/preview mode. */
 export const DRAFT_COOKIE = "__nifra_draft"
@@ -160,6 +160,9 @@ export interface PreviewEndpointOptions {
 export function previewEndpoint(
   options: PreviewEndpointOptions,
 ): (request: Request) => Promise<Response> {
+  // An empty token matches a link with no `?token=` at all, which would hand draft mode (and every
+  // unpublished page) to anyone. Refuse it at construction, where an unset env var surfaces at boot.
+  assertTokenSecret(options.secret, "previewEndpoint")
   const tokenParam = options.tokenParam ?? "token"
   const redirectParam = options.redirectParam ?? "to"
   const fallbackPath = options.fallbackPath ?? "/"

package/src/fn.ts

@@ -53,6 +53,7 @@ import {
   type RouteSchema,
   type StandardSchemaV1,
 } from "@nifrajs/core/server"
+import { guardChannel, outputGuard } from "./internal/output-guard.ts"
 
 /** The URL prefix every mounted function lives under. Namespaced per mount, then by export name. */
 export const SERVER_FN_PREFIX = "/_nifra/fn"
@@ -66,6 +67,11 @@ export interface ServerFnConfig<Input> {
    * the caller controls this value completely, so an unvalidated one is an open door.
    */
   readonly input?: StandardSchemaV1<unknown, Input>
+  /**
+   * Describes what the function returns to the browser. Required whenever it returns data: keys the
+   * schema does not declare are dropped, and a declared field of the wrong shape fails the call.
+   */
+  readonly output?: StandardSchemaV1
   /** Effect tokens, forwarded to the route so `nifra assure` and the effect ledger see them. */
   readonly capabilities?: readonly string[]
 }
@@ -172,6 +178,13 @@ export function serverFunctions(namespace: string, module: ServerFnModule): Iden
         )
       }
       const config = fn[SERVER_FN]
+      const label = `server function "${namespace}.${name}"`
+      const guarded = guardChannel(fn, {
+        label,
+        guard:
+          config.output === undefined ? undefined : outputGuard(config.output, label, "output"),
+        missing: "an output schema in its serverFn({ output }) config",
+      })
       const schema: RouteSchema = {
         ...(config.input !== undefined ? { body: config.input } : {}),
         ...(config.capabilities !== undefined ? { capabilities: config.capabilities } : {}),
@@ -182,17 +195,20 @@ export function serverFunctions(namespace: string, module: ServerFnModule): Iden
         // has happened yet, so rejecting here is a complete refusal.
         const request = c.req
         const contentType = request.headers.get("content-type") ?? ""
-        if (!contentType.includes("application/json")) {
+        const semi = contentType.indexOf(";")
+        const mediaType = (semi === -1 ? contentType : contentType.slice(0, semi)).trim()
+        if (mediaType.toLowerCase() !== "application/json") {
           // A form cannot send this content type cross-origin without a preflight. Rejecting anything
           // else is what makes form-driven CSRF against a server function impossible rather than
-          // merely unlikely.
+          // merely unlikely. Compare the media type, never search the header: `text/plain;
+          // x=application/json` contains the string but is a no-preflight `text/plain` request.
           return c.json({ ok: false, error: "unsupported_media_type" }, 415)
         }
         const origin = request.headers.get("origin")
         if (origin !== null && !sameOrigin(origin, request)) {
           return c.json({ ok: false, error: "forbidden_origin" }, 403)
         }
-        return fn(config.input === undefined ? (undefined as never) : (c.body as never), c)
+        return guarded(config.input === undefined ? undefined : c.body, c)
       }) as (context: never) => unknown)
     }
     return app

package/src/fs.ts

@@ -5,7 +5,13 @@
  */
 import { readdirSync } from "node:fs"
 import { join } from "node:path"
-import { buildManifest, type Manifest, type RouteModule } from "./manifest.ts"
+import {
+  buildManifest,
+  isMiddlewareFile,
+  isRouteBackendFile,
+  type Manifest,
+  type RouteModule,
+} from "./manifest.ts"
 
 /** Options for {@link discoverRoutes}. */
 export interface DiscoverRoutesOptions {
@@ -31,7 +37,12 @@ export interface DiscoverRoutesOptions {
 export function discoverRoutes(dir: string, options: DiscoverRoutesOptions = {}): Manifest {
   const files = (readdirSync(dir, { recursive: true }) as string[])
     .map((file) => file.replaceAll("\\", "/")) // normalize Windows separators
-    .filter((file) => /\.(tsx|jsx|svelte|vue|mdx)$/.test(file))
+    .filter(
+      (file) =>
+        /\.(tsx|jsx|svelte|vue|mdx)$/.test(file) ||
+        isRouteBackendFile(file) ||
+        isMiddlewareFile(file),
+    )
   const query = options.importQuery ? `?${options.importQuery}` : ""
   const load = options.load
   return buildManifest(files, (file) =>

package/src/index.ts

@@ -41,6 +41,14 @@ export {
   RenderAdapterConformanceError,
   type RenderAdapterConformanceFixture,
 } from "./conformance.ts"
+// Hash-based CSP: a document carries a nonce only when it needs one, so a CSP page stays cacheable.
+export {
+  type CreateCspPolicyOptions,
+  type CspHeaderContext,
+  type CspPolicy,
+  createCspPolicy,
+  nifraScriptHashes,
+} from "./csp.ts"
 export {
   assertCssLoadingCompatible,
   type CssLoadingMode,
@@ -102,43 +110,46 @@ export {
   unsafeInlineScript,
 } from "./internal/render-document.ts"
 export {
+  type BackendOnly,
   DEFAULT_DEV_PORT,
   PRE_HYDRATION_GUARD,
-  type ServerOnly,
 } from "./internal/runtime-contract.ts"
 /**
- * The two file-name conventions that decide what never reaches a browser: a `*.server` module is
- * EMPTIED in the client build, a `*.fn` module is REPLACED with client stubs.
- *
- * Exported because more than the bundlers need them. `nifra dev --bun` cannot transform (Bun's dev
- * bundler takes no plugins) so it must REFUSE instead, and a refusal driven by its own hand-written
- * glob drifts from the transform - which is how `.fn.mts` came to be stubbed by both build pipelines
- * and waved through by the guard that exists to stop it leaking. Anything deciding "is this module
- * server-only" should import the matcher rather than re-encode it.
+ * The `*.fn` server-function convention: the browser build REPLACES such a module with client stubs.
+ * Exported so anything deciding "is this a server-function module" imports the matcher instead of
+ * re-encoding it - a hand-written glob drifts from the transform, which is how `.fn.mts` was once
+ * stubbed by both build pipelines and waved through by the guard meant to stop it leaking.
  */
-export { SERVER_FN_MODULE, SERVER_ONLY_MODULE } from "./internal/server-boundary.ts"
+export { SERVER_FN_MODULE } from "./internal/server-boundary.ts"
 export {
   type CreateWebAppOptions,
   createWebApp,
   type NonceResolver,
+  webProjectEvidence,
 } from "./internal/web-app.ts"
 // ISR (incremental static regeneration): a pluggable cache store + the `withISR` stale-while-revalidate
 // wrapper for rendered SSR responses.
 export {
   type CachedResponse,
   type CacheStore,
+  type CdnPurgeOutcome,
+  type CdnPurgeTarget,
   ISR_REVALIDATE_HEADER,
   ISR_REVALIDATE_TAGS_HEADER,
   ISR_STATUS_HEADER,
   type ISRApp,
   type ISROptions,
   type ISRPlatform,
+  type ISRQuery,
+  isCacheablePage,
   KVCacheStore,
   type KVCacheStoreOptions,
   type KVNamespaceLike,
   MemoryCacheStore,
   type MemoryCacheStoreOptions,
   type RevalidateEndpointOptions,
+  type RevalidateTags,
+  type RevalidateTagsInput,
   revalidateEndpoint,
   withISR,
 } from "./isr.ts"
@@ -162,14 +173,22 @@ export {
   type LinkDescriptor,
   type Loader,
   type LoaderContext,
+  type LoaderResponseControls,
+  type LoadingEntry,
   type Manifest,
   type Meta,
   type MetaArgs,
   type MetaDescriptor,
   type MetaInput,
+  type MiddlewareOutcome,
+  type NotFoundEntry,
+  type NotFoundScope,
   type RouteEntry,
+  type RouteMiddleware,
   type RouteModule,
   type ScriptDescriptor,
+  type ShouldRevalidate,
+  type ShouldRevalidateArgs,
   type StaticPath,
   type StaticPaths,
   type StaticRoutes,
@@ -190,12 +209,21 @@ export {
   type NavigateOptions,
   type NavigateSearchOf,
   type NavigateTargetInput,
+  type PrefetchMode,
   type RouteSearch,
   registerBlocker,
   resolveNavigate,
   setBlockerController,
   setBrowserNavigate,
 } from "./navigation.ts"
+export {
+  type CreateNonceResolverOptions,
+  createNonceResolver,
+  type NonceContext,
+  type NonceGenerator,
+  type NonceHeader,
+  type NonceHeaderContext,
+} from "./nonce.ts"
 // public/ - user-authored static files, served identically in dev and production by one handler.
 export {
   type PublicDirCache,
@@ -228,14 +256,18 @@ export {
   ACTION_GLOBAL,
   BOUNDARY_GLOBAL,
   DATA_GLOBAL,
+  HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  type MatchChain,
   type RenderAdapter,
   type RenderProps,
+  type RenderStreamOptions,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
   type SsrModuleLoader,
   setSsrModuleLoader,
   ssrModuleLoader,
+  type UIMatch,
 } from "./render-seam.ts"
 // Agnostic client-side router core (pure + DOM-free) - consumed by per-adapter Router bindings.
 // `DATA_HEADER` marks a navigation's data-only GET; `createWebApp` answers it with loader JSON.

package/src/internal/cdn/cloudflare.ts

@@ -0,0 +1,146 @@
+/**
+ * Cloudflare: a proxied zone in front of the origin, and Workers Cache in front of a Worker. Both read
+ * `Cache-Tag` and `Cloudflare-CDN-Cache-Control` and strip them before the browser; the zone purges
+ * through the API (at most 100 tags a call; the Free plan allows 5 calls a minute), Workers Cache
+ * through the Worker's own `cache.purge` (always Free-plan limits).
+ */
+import {
+  attemptFromStatus,
+  type CdnCacheInput,
+  type CdnProvider,
+  cdnDirectives,
+  defineCdnProvider,
+  type PurgeQueueOptions,
+} from "./core.ts"
+
+const headersFor = (input: CdnCacheInput): Record<string, string> => ({
+  "cache-tag": input.tags.join(","),
+  "cloudflare-cdn-cache-control": cdnDirectives(input),
+})
+const NO_STORE = { "cloudflare-cdn-cache-control": "no-store" }
+
+export interface CloudflareZoneOptions {
+  /** The zone id (32 hex characters, on the zone's Overview page). */
+  readonly zoneId: string
+  /** An API token scoped to Zone > Cache Purge for this zone. Keep it in an env binding. */
+  readonly apiToken: string
+  readonly queue?: PurgeQueueOptions
+  /** The fetch purge calls go through; tests pass their own. */
+  readonly fetch?: typeof fetch
+}
+
+/**
+ * A Cloudflare zone proxying the origin. HTML is only cached by a Cache Rule that makes it eligible,
+ * and the zone's cache ignores `Vary`: the rule must also bypass the cache when the request carries
+ * `x-nifra-data` (soft navigations fetch the page URL with that header). `nifra cdn-check` tests both.
+ */
+export function cloudflareZone(options: CloudflareZoneOptions): CdnProvider {
+  if (!/^[a-f0-9]{32}$/.test(options.zoneId)) {
+    throw new TypeError(
+      "[nifra/web/cdn] cloudflareZone: zoneId must be the 32-character hex zone id",
+    )
+  }
+  if (typeof options.apiToken !== "string" || options.apiToken === "") {
+    throw new TypeError(
+      "[nifra/web/cdn] cloudflareZone: apiToken is empty (is the env binding set?)",
+    )
+  }
+  const send = options.fetch ?? fetch
+  const endpoint = `https://api.cloudflare.com/client/v4/zones/${options.zoneId}/purge_cache`
+  return defineCdnProvider(
+    {
+      name: "cloudflare",
+      tagsPerCall: 100,
+      maxResponseTags: 1000,
+      cacheHeaders: headersFor,
+      noStoreHeaders: () => NO_STORE,
+      async purgeTags(tags) {
+        const res = await send(endpoint, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${options.apiToken}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ tags }),
+        })
+        const attempt = attemptFromStatus(res, "cloudflare")
+        if (!res.ok) {
+          await res.body?.cancel()
+          return attempt
+        }
+        // A 200 can still carry `success: false`; only `true` means the purge was received.
+        const body: unknown = await res.json().catch(() => null)
+        const field = (from: unknown, name: string): unknown =>
+          typeof from === "object" && from !== null ? Reflect.get(from, name) : undefined
+        if (field(body, "success") === true) return attempt
+        const errors = field(body, "errors")
+        const code = field(Array.isArray(errors) ? errors[0] : undefined, "code")
+        return {
+          ok: false,
+          retryable: false,
+          reason: typeof code === "number" ? `cloudflare_error_${code}` : "cloudflare_unsuccessful",
+        }
+      },
+    },
+    options.queue,
+  )
+}
+
+/** The Worker's cache binding: `import { cache } from "cloudflare:workers"`, or `ctx.cache`. */
+export interface WorkersCacheLike {
+  purge(options: { tags?: string[]; pathPrefixes?: string[] }): Promise<{
+    success: boolean
+    errors?: readonly { code?: number; message?: string }[]
+  }>
+}
+
+export interface CloudflareWorkersCacheOptions {
+  /** `import { cache } from "cloudflare:workers"` (needs `[cache] enabled = true` in wrangler). */
+  readonly cache: WorkersCacheLike
+  /**
+   * Whether the Worker serves different content per hostname. Workers Cache keys entries by path, not
+   * host, so such an app would serve one host's page to another: `true` is refused.
+   */
+  readonly hostRouted?: boolean
+  readonly queue?: PurgeQueueOptions
+}
+
+/** Workers Cache in front of the Worker serving the app. Purges are scoped to the calling entrypoint. */
+export function cloudflareWorkersCache(options: CloudflareWorkersCacheOptions): CdnProvider {
+  if (options.hostRouted === true) {
+    throw new Error(
+      "[nifra/web/cdn] NIFRA_CDN_HOST_ROUTED: Workers Cache keys pages by path, not host, so a Worker that serves different content per hostname would serve one host's page to another. Put a Cloudflare zone (cloudflareZone) in front instead, or serve each host from its own Worker.",
+    )
+  }
+  if (typeof options.cache?.purge !== "function") {
+    throw new TypeError(
+      '[nifra/web/cdn] cloudflareWorkersCache: pass `cache` from `import { cache } from "cloudflare:workers"`',
+    )
+  }
+  return defineCdnProvider(
+    {
+      name: "cloudflare-workers-cache",
+      tagsPerCall: 100,
+      maxResponseTags: 1000,
+      cacheHeaders: headersFor,
+      noStoreHeaders: () => NO_STORE,
+      async purgeTags(tags) {
+        const result = await options.cache.purge({ tags: [...tags] })
+        if (result.success) return { ok: true }
+        const first = result.errors?.[0]
+        // A rate-limit refusal is the one worth retrying; anything else is configuration.
+        const limited = /rate/i.test(first?.message ?? "")
+        return {
+          ok: false,
+          retryable: limited,
+          rateLimited: limited,
+          reason:
+            typeof first?.code === "number"
+              ? `workers_cache_${first.code}`
+              : "workers_cache_refused",
+        }
+      },
+    },
+    options.queue,
+  )
+}