@nifrajs/web 5.5.1 → 5.7.0

package/src/server-components/runtime.ts

@@ -1,5 +1,6 @@
 import type { CapabilityDefinition } from "@nifrajs/core/capabilities"
-import { isResponseResult, isStatusSignal, STATUS_SIGNAL } from "../internal/render-document.ts"
+import { isResponseResult } from "../internal/render-document.ts"
+import { isStatusSignal, STATUS_SIGNAL } from "../internal/status-page.ts"
 import {
   authorizeServerComponent,
   isServerComponent,
@@ -20,9 +21,11 @@ import {
 import { BoundedComponentTasks, componentAbort } from "./scheduler.ts"
 import { componentValue } from "./schema.ts"
 import type {
+  ComponentHoles,
   ComponentInstance,
   ComponentOwner,
   ComponentRecord,
+  ComponentRender,
   ServerComponent,
   ServerComponentContext,
   ServerComponentHandle,
@@ -42,6 +45,11 @@ export interface ServerComponentsOptions {
   readonly build: string
   readonly adapter: ServerComponentRenderAdapter
   readonly owners: Readonly<Record<string, ComponentOwner>>
+  /**
+   * Experimental: route id to the server components its partially prerendered holes may show, each
+   * through `serverHole`. A route is an owner or hosts holes, never both.
+   */
+  readonly holes?: Readonly<Record<string, ComponentHoles>>
   readonly capabilities?: readonly CapabilityDefinition[]
   readonly assets?: readonly string[]
 }
@@ -103,20 +111,19 @@ export function createServerComponents(options: ServerComponentsOptions): Server
   )
   if (capabilities.size !== (options.capabilities?.length ?? 0))
     throw new ServerComponentError("component_contract")
-  for (const [routeId, owner] of Object.entries(options.owners)) {
-    if (
-      typeof owner.instances !== "function" ||
-      (owner.scope !== "anonymous" && typeof owner.scope !== "function")
-    )
-      throw new ServerComponentError("component_contract")
+  /** A route's component allowlist, by reference, each within the capabilities the route grants. */
+  const allowlist = (
+    list: readonly ServerComponentHandle[],
+    granted: readonly string[] = [],
+  ): ReadonlyMap<string, ServerComponentHandle> => {
     const components = new Map<string, ServerComponentHandle>()
-    const allowed = new Set(owner.capabilities ?? [])
+    const allowed = new Set(granted)
     for (const capability of allowed) {
       const declared = capabilities.get(capability)
       if (declared === undefined || (declared.zone === "domain" && declared.access !== "read"))
         throw new ServerComponentError("component_contract")
     }
-    for (const component of owner.components) {
+    for (const component of list) {
       if (
         !isServerComponent(component) ||
         component.reference === undefined ||
@@ -128,11 +135,106 @@ export function createServerComponents(options: ServerComponentsOptions): Server
       if (serverComponentCapabilities(component).some((capability) => !allowed.has(capability)))
         throw new ServerComponentError("component_contract")
     }
-    owners.set(routeId, { owner, components })
+    return components
+  }
+  for (const [routeId, owner] of Object.entries(options.owners)) {
+    if (
+      typeof owner.instances !== "function" ||
+      (owner.scope !== "anonymous" && typeof owner.scope !== "function")
+    )
+      throw new ServerComponentError("component_contract")
+    owners.set(routeId, { owner, components: allowlist(owner.components, owner.capabilities) })
+  }
+  const holes = new Map<
+    string,
+    { capabilities: readonly string[]; components: ReadonlyMap<string, ServerComponentHandle> }
+  >()
+  for (const [routeId, entry] of Object.entries(options.holes ?? {})) {
+    // An owner route renders whole, so its holes never run.
+    if (owners.has(routeId) || !Array.isArray(entry.components))
+      throw new ServerComponentError("component_contract")
+    holes.set(routeId, {
+      capabilities: entry.capabilities ?? [],
+      components: allowlist(entry.components, entry.capabilities),
+    })
+  }
+  /** A rendered instance as a record: its range HTML checked, its payload and island props public. */
+  const recordOf = (
+    instance: {
+      readonly id: string
+      readonly reference: string
+      readonly key: ComponentRecord["key"]
+      readonly parent?: string | undefined
+      readonly input: ComponentRecord["input"]
+    },
+    rendered: ComponentRender,
+  ): ComponentRecord => {
+    const record: ComponentRecord = {
+      instance: instance.id,
+      reference: instance.reference,
+      key: instance.key,
+      parent: instance.parent ?? null,
+      input: instance.input,
+      html: componentRangeHTML(rendered.html, assets),
+    }
+    if (rendered.payload !== undefined)
+      Object.assign(record, {
+        payload: componentValue(rendered.payload, COMPONENT_LIMITS.outputBytes),
+      })
+    if (rendered.islands !== undefined)
+      Object.assign(record, {
+        islands: rendered.islands.map((island) => ({
+          ...island,
+          props: componentValue(island.props),
+        })),
+      })
+    return record
   }
   return {
     owns: (routeId) => owners.has(routeId),
-    capabilities: (routeId) => owners.get(routeId)?.owner.capabilities ?? [],
+    capabilities: (routeId) =>
+      owners.get(routeId)?.owner.capabilities ?? holes.get(routeId)?.capabilities ?? [],
+    hosts: (routeId) => holes.has(routeId),
+    async hole(routeId, component, key, input, context) {
+      const reference = isServerComponent(component) ? component.reference : undefined
+      const handle =
+        reference === undefined ? undefined : holes.get(routeId)?.components.get(reference)
+      if (
+        reference === undefined ||
+        handle === undefined ||
+        handle !== component ||
+        !componentKey(key)
+      )
+        throw new ServerComponentError("component_contract")
+      const signal = AbortSignal.any([
+        context.signal,
+        AbortSignal.timeout(COMPONENT_LIMITS.executionMs),
+      ])
+      const ctx: ServerComponentContext = Object.create(context, {
+        signal: { value: signal, enumerable: true },
+      })
+      const value = componentValue(input, COMPONENT_LIMITS.inputBytes)
+      const id = await serverComponentIdentity(routeId, handle, key, null)
+      return admission.run(signal, async () => {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The route's hole allowlist identifies this handle; authorization validates the input before any callback runs.
+        const authorized = await authorizeServerComponent(handle as ServerComponent, value, ctx)
+        const prepared = await prepareAuthorizedServerComponent(authorized)
+        const rendered = await options.adapter.render(prepared.view, prepared.props, {
+          reference,
+          instance: id,
+          signal,
+          children: [],
+        })
+        if (signal.aborted) throw componentAbort(signal)
+        if (typeof rendered.html !== "string") throw new ServerComponentError("component_contract")
+        if ((rendered.islands?.length ?? 0) > COMPONENT_LIMITS.instances)
+          throw new ServerComponentError("component_limit", 413)
+        const record = recordOf({ id, reference, key, input: value }, rendered)
+        if (encoder.encode(JSON.stringify(record)).length > COMPONENT_LIMITS.outputBytes)
+          throw new ServerComponentError("component_limit", 413)
+        return record
+      })
+    },
     classify(request, routeId) {
       const selection = readComponentRequest(request)
       if (selection === undefined) return undefined
@@ -275,29 +377,10 @@ export function createServerComponents(options: ServerComponentsOptions): Server
               if (signal.aborted) throw componentAbort(signal)
               if (typeof rendered.html !== "string")
                 throw new ServerComponentError("component_contract")
-              const html = componentRangeHTML(rendered.html, assets)
+              const record = recordOf({ ...instance, id }, rendered)
               count += rendered.islands?.length ?? 0
               if (count > COMPONENT_LIMITS.instances)
                 throw new ServerComponentError("component_limit", 413)
-              const record: ComponentRecord = {
-                instance: id,
-                reference: instance.reference,
-                key: instance.key,
-                parent: instance.parent ?? null,
-                input: instance.input,
-                html,
-              }
-              if (rendered.payload !== undefined)
-                Object.assign(record, {
-                  payload: componentValue(rendered.payload, COMPONENT_LIMITS.outputBytes),
-                })
-              if (rendered.islands !== undefined)
-                Object.assign(record, {
-                  islands: rendered.islands.map((island) => ({
-                    ...island,
-                    props: componentValue(island.props),
-                  })),
-                })
               const size = encoder.encode(JSON.stringify(record)).length
               bytes += size
               if (

package/src/server-components/state.ts

@@ -50,6 +50,69 @@ function island(value: unknown): ComponentIsland {
   if (item.slots !== undefined) Object.assign(result, { slots: item.slots })
   return result
 }
+/** One record, checked as each of a state's is; `ids` and `islandIds` collect what must be unique. */
+function componentRecord(
+  value: unknown,
+  ids: Set<string>,
+  islandIds: Set<string>,
+): ComponentRecord {
+  const record = object(
+    value,
+    ["instance", "reference", "key", "parent", "input", "html"],
+    ["payload", "islands"],
+  )
+  if (
+    !componentToken(record.instance) ||
+    ids.has(record.instance) ||
+    !componentToken(record.reference) ||
+    !componentKey(record.key) ||
+    (record.parent !== null && !componentToken(record.parent)) ||
+    typeof record.html !== "string"
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  ids.add(record.instance)
+  validateComponentHTML(record.html)
+  if (
+    record.islands !== undefined &&
+    (!Array.isArray(record.islands) || record.islands.length > COMPONENT_LIMITS.instances)
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  const islands =
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    record.islands === undefined ? undefined : (record.islands as unknown[]).map(island)
+  for (const island of islands ?? []) {
+    if (islandIds.has(island.renderId)) throw new ServerComponentError("component_protocol", 400)
+    islandIds.add(island.renderId)
+  }
+  const result: ComponentRecord = {
+    instance: record.instance,
+    reference: record.reference,
+    key: record.key,
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    parent: record.parent as string | null,
+    html: record.html,
+    input: componentValue(record.input, COMPONENT_LIMITS.inputBytes),
+  }
+  if (record.payload !== undefined)
+    Object.assign(result, {
+      payload: componentValue(record.payload, COMPONENT_LIMITS.outputBytes),
+    })
+  if (islands !== undefined) Object.assign(result, { islands })
+  return result
+}
+
+/** A record that arrives alone, as a partially prerendered hole's does, checked as a state's are. */
+export function parseComponentRecord(value: unknown): ComponentRecord {
+  const record = componentRecord(
+    componentValue(value, COMPONENT_LIMITS.documentBytes),
+    new Set(),
+    new Set(),
+  )
+  if ((record.islands?.length ?? 0) >= COMPONENT_LIMITS.instances)
+    throw new ServerComponentError("component_limit", 413)
+  return record
+}
+
 export function parseComponentState(
   value: unknown,
   maxBytes: number = COMPONENT_LIMITS.documentBytes,
@@ -72,52 +135,11 @@ export function parseComponentState(
   const islandIds = new Set<string>()
   let instances = state.records.length
   const records: ComponentRecord[] = state.records.map((value: unknown) => {
-    const record = object(
-      value,
-      ["instance", "reference", "key", "parent", "input", "html"],
-      ["payload", "islands"],
-    )
-    if (
-      !componentToken(record.instance) ||
-      ids.has(record.instance) ||
-      !componentToken(record.reference) ||
-      !componentKey(record.key) ||
-      (record.parent !== null && !componentToken(record.parent)) ||
-      typeof record.html !== "string"
-    )
-      throw new ServerComponentError("component_protocol", 400)
-    ids.add(record.instance)
-    validateComponentHTML(record.html)
-    if (
-      record.islands !== undefined &&
-      (!Array.isArray(record.islands) || record.islands.length > COMPONENT_LIMITS.instances)
-    )
-      throw new ServerComponentError("component_protocol", 400)
-    const islands =
-      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
-      record.islands === undefined ? undefined : (record.islands as unknown[]).map(island)
-    for (const island of islands ?? []) {
-      if (islandIds.has(island.renderId)) throw new ServerComponentError("component_protocol", 400)
-      islandIds.add(island.renderId)
-    }
-    instances += islands?.length ?? 0
+    const record = componentRecord(value, ids, islandIds)
+    instances += record.islands?.length ?? 0
     if (instances > COMPONENT_LIMITS.instances)
       throw new ServerComponentError("component_limit", 413)
-    const result: ComponentRecord = {
-      instance: record.instance,
-      reference: record.reference,
-      key: record.key,
-      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
-      parent: record.parent as string | null,
-      html: record.html,
-      input: componentValue(record.input, COMPONENT_LIMITS.inputBytes),
-    }
-    if (record.payload !== undefined)
-      Object.assign(result, {
-        payload: componentValue(record.payload, COMPONENT_LIMITS.outputBytes),
-      })
-    if (islands !== undefined) Object.assign(result, { islands })
-    return result
+    return record
   })
   // Refreshes contain a single child and may name its already mounted parent. Documents carry the full forest.
   for (const record of records) {

package/src/server-components/types.ts

@@ -98,6 +98,12 @@ export interface ComponentOwner {
   readonly scope: "anonymous" | ((ctx: ServerComponentContext) => string | Promise<string>)
 }
 
+/** Experimental: the server components a partially prerendered route's holes may show. */
+export interface ComponentHoles {
+  readonly components: readonly ServerComponentHandle[]
+  readonly capabilities?: readonly string[]
+}
+
 export interface ServerComponentHandle {
   readonly reference?: string
   readonly input: StandardSchemaV1
@@ -135,4 +141,14 @@ export interface ServerComponentRuntime {
   ): Promise<ComponentState>
   response(state: ComponentState, selection: import("./protocol.ts").ComponentRequest): Response
   failure(error: unknown): Response
+  /** Whether the route's partially prerendered holes may show server components. */
+  hosts?(routeId: string): boolean
+  /** Render `component` as the route's hole `key`, with the hole loader's output as its input. */
+  hole?(
+    routeId: string,
+    component: object,
+    key: string,
+    input: unknown,
+    context: ServerComponentContext,
+  ): Promise<ComponentRecord>
 }

package/src/server-components/vite.ts

@@ -25,6 +25,17 @@ const reactRuntime = "\0nifra-component-react-runtime"
 // Vite uses forward slashes for module IDs even when the filesystem uses backslashes.
 const bare = (id: string): string => (id.split("?")[0] ?? id).replaceAll("\\", "/")
 
+// Blanked with spaces rather than cut, so later offsets still point at the source.
+function withoutUseClient(source: string, path: string): string {
+  for (const statement of sourceFile(source, path).statements) {
+    if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression)) break
+    if (statement.expression.text !== "use client") continue
+    const start = statement.getStart()
+    return `${source.slice(0, start)}${" ".repeat(statement.end - start)}${source.slice(statement.end)}`
+  }
+  return source
+}
+
 export interface ServerComponentsPluginOptions {
   readonly root: string
   readonly adapter: "react" | "vue" | "svelte" | "solid" | "preact"
@@ -224,23 +235,31 @@ export function serverComponentsPlugin(
       return null
     },
     transform(source, id) {
-      if (id.includes(nativeQuery) || internal.has(bare(id))) return null
       const path = bare(id)
       let code = source
-      if (componentFile.test(path)) {
-        code = compileComponentModule(source, path, options.root, this.environment.name).code
-        componentModules.add(path)
+      if (!id.includes(nativeQuery) && !internal.has(path)) {
+        if (componentFile.test(path)) {
+          code = compileComponentModule(source, path, options.root, this.environment.name).code
+          componentModules.add(path)
+        }
+        if (islandFile.test(path))
+          code = compileComponentModule(
+            source,
+            path,
+            options.root,
+            this.environment.name,
+            "island",
+          ).code
+        if (this.environment.name === "rsc" && options.adapter === "react")
+          code = guardCreateElementCalls(code, path)
       }
-      if (islandFile.test(path))
-        code = compileComponentModule(
-          source,
-          path,
-          options.root,
-          this.environment.name,
-          "island",
-        ).code
-      if (this.environment.name === "rsc" && options.adapter === "react")
-        code = guardCreateElementCalls(code, path)
+      // Only the rsc build acts on "use client"; the client and ssr bundles would warn about it.
+      if (
+        this.environment.name !== "rsc" &&
+        options.adapter === "react" &&
+        code.includes("use client")
+      )
+        code = withoutUseClient(code, path)
       return code === source ? null : { code, map: null }
     },
   }

package/src/vite.ts

@@ -23,10 +23,21 @@ import { isHiddenPath } from "@nifrajs/core/static-file"
 import { CLIENT_BATCH_MAX_BYTES } from "./dev-client.ts"
 import { DEV_REQUEST_ID_HEADER, DEV_SERVER_FILES } from "./dev-feed.ts"
 import { listenOrExplain } from "./dev-port.ts"
-import { createDevSession, type DevAppHooks, isDevAgentPath } from "./dev-session.ts"
+import {
+  createDevSession,
+  type DevAppHooks,
+  isDevAgentPath,
+  isLoopbackHost,
+} from "./dev-session.ts"
 import { discoverRoutes } from "./fs.ts"
-import { DEFAULT_DEV_PORT, generateClientEntry, setSsrModuleLoader } from "./index.ts"
+import {
+  DEFAULT_DEV_PORT,
+  generateClientEntry,
+  type LiveClientEntry,
+  setSsrModuleLoader,
+} from "./index.ts"
 import { admitViteTags } from "./internal/dev-csp.ts"
+import { type UpgradableApp, upgradeOnNode } from "./internal/dev-websocket.ts"
 import { viteDedupePackages } from "./internal/identity-policy.ts"
 import {
   assertIdentityParity,
@@ -49,7 +60,7 @@ import { viteServerFnStub } from "./plugins/vite-server-fn.ts"
 import { viteZoneGuard } from "./plugins/vite-zone-guard.ts"
 
 /** Minimal app surface - `createWebApp(...)` satisfies it. */
-interface FetchApp {
+interface FetchApp extends UpgradableApp {
   fetch(request: Request): Response | Promise<Response>
 }
 
@@ -79,7 +90,10 @@ interface ViteLike {
   /** The module graph, used to invalidate a changed file AND its transitive importers before reload. */
   readonly moduleGraph?: ViteModuleGraph
   /** The resolved config: `publicDir` is absolute, or `""` when the public directory is off. */
-  readonly config?: { readonly publicDir?: string }
+  readonly config?: {
+    readonly publicDir?: string
+    readonly server?: { readonly allowedHosts?: true | readonly string[] }
+  }
   readonly watcher: {
     on(event: "change" | "add" | "unlink", cb: (path: string) => void): void
     on(event: "ready", cb: () => void): void
@@ -163,6 +177,8 @@ export interface ViteDevServerOptions {
    * fix (default `true`). Off, the errors still reach the feed.
    */
   readonly indicator?: boolean
+  /** The app runs `createWebApp({ live })`: the same option as the build's (`BuildClientOptions.live`). */
+  readonly live?: LiveClientEntry | undefined
 }
 
 export interface ViteDevServer {
@@ -236,7 +252,7 @@ const readAgentBody = async (req: IncomingMessage, max: number): Promise<Buffer
 function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
   const headers = new Headers()
   for (const [key, value] of Object.entries(req.headers)) {
-    if (typeof value === "string") headers.set(key, value)
+    if (typeof value === "string") appendJoined(headers, key, value)
     else if (Array.isArray(value)) for (const v of value) headers.append(key, v)
   }
   const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`
@@ -252,6 +268,23 @@ function toWebRequest(req: IncomingMessage, body: Buffer | undefined): Request {
   return new Request(url, init as unknown as ConstructorParameters<typeof Request>[1])
 }
 
+/**
+ * Node joins a repeated field into one string, and a trailing space there means the last member was
+ * empty (each field line is trimmed). `Headers` strips the whitespace around each value it is given,
+ * so the empty members are appended one by one to keep the "a, " production shows.
+ */
+function appendJoined(headers: Headers, name: string, joined: string): void {
+  const delimiter = name === "cookie" ? "; " : ", "
+  let base = joined
+  let empty = 0
+  while (base.endsWith(delimiter)) {
+    base = base.slice(0, -delimiter.length)
+    empty++
+  }
+  headers.append(name, base)
+  for (; empty > 0; empty--) headers.append(name, "")
+}
+
 /** The bits of a Node ServerResponse `pipeWebBodyToNode` touches - structural, to avoid a node:http dep here. */
 interface NodeResLike {
   /** Set once the socket is gone: `close` has fired, and a write returns `false` for good. */
@@ -395,7 +428,11 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     const manifest = discoverRoutes(routesDir)
     writeFileSync(
       resolvePath(root, DEV_ENTRY),
-      generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }),
+      generateClientEntry(manifest, {
+        clientModule: options.clientModule,
+        resolve: toUrl,
+        live: options.live,
+      }),
     )
   }
   const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1"
@@ -457,6 +494,38 @@ export async function createViteDevServer(options: ViteDevServerOptions): Promis
     handleWithVite(req, res)
   })
 
+  // The app's own WebSocket routes. Vite's HMR socket rides this server with a listener of its own,
+  // so its handshakes, and any no app route takes, are left to the other listeners.
+  server.on("upgrade", (req, socket, head) => {
+    const protocol = req.headers["sec-websocket-protocol"] ?? ""
+    if (protocol.includes("vite-hmr") || protocol.includes("vite-ping")) return
+    if (!allowsHost(req.headers.host)) {
+      socket.on("error", () => {})
+      socket.end("HTTP/1.1 403 Forbidden\r\ncontent-length: 0\r\nconnection: close\r\n\r\n")
+      return
+    }
+    void upgradeOnNode(app, toWebRequest(req, undefined), req, socket, head)
+  })
+
+  /** Vite's own rule for a handshake's Host: a loopback name, or one `server.allowedHosts` lists. */
+  function allowsHost(host: string | undefined): boolean {
+    if (isLoopbackHost(host)) return true
+    const allowed = vite.config?.server?.allowedHosts
+    if (allowed === true) return true
+    if (allowed === undefined || host === undefined) return false
+    let name: string
+    try {
+      name = new URL(`http://${host}`).hostname
+    } catch {
+      return false
+    }
+    return allowed.some(
+      (entry) =>
+        entry === name ||
+        (entry.startsWith(".") && (name === entry.slice(1) || name.endsWith(entry))),
+    )
+  }
+
   // Vite's public middleware serves every file under the public directory, dotfiles included. A
   // build ships no hidden file and the Bun pipeline's `servePublicDir` refuses one, so a request for
   // `/.env` or `/.git/config` goes to the app here too, as it does in production.