@nifrajs/web 4.0.2 → 5.1.0

package/src/server-components/islands.ts

@@ -0,0 +1,111 @@
+import type { StandardSchemaV1 } from "@nifrajs/core/server"
+import type { ComponentKey, ComponentRecord, ServerComponentHandle } from "./types.ts"
+
+const contractBrand = Symbol.for("nifra.components.island")
+const viewBrand = Symbol.for("nifra.components.view")
+export interface ClientIsland<Props = unknown, Component = unknown> {
+  readonly reference?: string
+  readonly props: StandardSchemaV1<unknown, Props>
+  readonly component: Component
+  readonly slots: readonly string[]
+  readonly [contractBrand]: true
+}
+type NativeComponentProps<Component> = Component extends abstract new (
+  ...args: never[]
+) => { $props: infer Props }
+  ? Props
+  : Component extends abstract new (
+        ...args: never[]
+      ) => { props: infer Props }
+    ? Props
+    : Component extends (...args: infer Args) => unknown
+      ? Args extends []
+        ? object
+        : // Optional legacy context is not a public props alternative (Preact types it as any).
+          Args extends [unknown, infer Props, ...unknown[]]
+          ? Args[0] | Props
+          : Args[0]
+      : never
+type CompatibleComponent<Props, Component> =
+  Props extends NativeComponentProps<Component>
+    ? unknown
+    : { readonly __nifraIslandPropsMustMatchComponent: never }
+
+export function defineClientIsland<Props, Component>(
+  definition: {
+    readonly props: StandardSchemaV1<unknown, Props>
+    readonly component: Component
+    readonly slots?: readonly string[]
+  } & CompatibleComponent<NoInfer<Props>, NoInfer<Component>>,
+  reference?: string,
+): ClientIsland<Props, Component> {
+  const slots = definition.slots ?? []
+  if (
+    slots.length > 16 ||
+    new Set(slots).size !== slots.length ||
+    slots.some(
+      (name) =>
+        !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name) || ["ref", "key", "constructor"].includes(name),
+    )
+  )
+    throw new Error("component_contract")
+  const contract: ClientIsland<Props, Component> = {
+    props: definition.props,
+    component: definition.component,
+    slots: Object.freeze([...slots]),
+    [contractBrand]: true,
+  }
+  if (reference !== undefined) Object.assign(contract, { reference })
+  return Object.freeze(contract)
+}
+export interface IslandInstance {
+  readonly contract: ClientIsland
+  readonly key: ComponentKey
+  readonly props: unknown
+  readonly slots: Readonly<Record<string, string>>
+}
+export function clientIsland<Props>(
+  contract: ClientIsland<Props>,
+  key: ComponentKey,
+  props: NoInfer<Props>,
+  slots: Readonly<Record<string, string>> = {},
+): IslandInstance {
+  return { contract, key, props, slots }
+}
+export interface NativeServerView {
+  readonly component: unknown
+  readonly islands: Readonly<Record<string, IslandInstance>>
+  readonly ranges: Readonly<Record<string, ComponentRecord>>
+  readonly [viewBrand]: true
+}
+/** Server-only native view rendered by the selected framework's own renderer. */
+export function nativeServerView(
+  component: unknown,
+  islands: Readonly<Record<string, IslandInstance>> = {},
+  ranges: Readonly<Record<string, ComponentRecord>> = {},
+): NativeServerView {
+  return { component, islands, ranges, [viewBrand]: true }
+}
+export function serverComponentChild(
+  children: readonly ComponentRecord[],
+  component: Pick<ServerComponentHandle, "reference">,
+  key: ComponentKey,
+): ComponentRecord {
+  const matches = children.filter(
+    (record) => record.reference === component.reference && record.key === key,
+  )
+  if (matches.length !== 1) throw new Error("component_contract")
+  return matches[0]!
+}
+export function isNativeServerView(value: unknown): value is NativeServerView {
+  return (
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before inspecting the private symbol brand created by this module.
+    typeof value === "object" && value !== null && (value as NativeServerView)[viewBrand] === true
+  )
+}
+export function isClientIsland(value: unknown): value is ClientIsland {
+  return (
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before inspecting the private symbol brand created by this module.
+    typeof value === "object" && value !== null && (value as ClientIsland)[contractBrand] === true
+  )
+}

package/src/server-components/native.ts

@@ -0,0 +1,101 @@
+import { isClientIsland, isNativeServerView } from "./islands.ts"
+import { guardComponentProps } from "./props.ts"
+import { COMPONENT_LIMITS, componentKey } from "./protocol.ts"
+import { componentToken } from "./state.ts"
+import type { ComponentIsland, ServerComponentRenderAdapter } from "./types.ts"
+
+export type NativeRender = (
+  component: unknown,
+  props: Record<string, unknown>,
+  renderId: string,
+) => string | Promise<string>
+export function nativeServerComponents(
+  name: "vue" | "svelte" | "solid" | "preact",
+  render: NativeRender,
+): ServerComponentRenderAdapter {
+  return {
+    name,
+    version: 1,
+    async render(view, props, context) {
+      if (typeof view !== "function") throw new Error("component_contract")
+      const value: unknown = await view({ props, children: context.children ?? [] })
+      if (!isNativeServerView(value)) throw new Error("component_contract")
+      const entries = Object.entries(value.islands)
+      if (entries.length > COMPONENT_LIMITS.instances) throw new Error("component_limit")
+      const seen = new Set<string>()
+      const islands: ComponentIsland[] = []
+      const markup: Record<string, { readonly html: string; readonly renderId: string }> =
+        Object.create(null)
+      for (const [slot, instance] of entries) {
+        if (
+          !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(slot) ||
+          !isClientIsland(instance.contract) ||
+          !componentToken(instance.contract.reference) ||
+          !componentKey(instance.key) ||
+          Object.keys(instance.slots).some((name) => !instance.contract.slots.includes(name))
+        )
+          throw new Error("component_contract")
+        const digest = await crypto.subtle.digest(
+          "SHA-256",
+          new TextEncoder().encode(
+            JSON.stringify([context.instance, instance.contract.reference, instance.key]),
+          ),
+        )
+        const renderId = `i_${[...new Uint8Array(digest)].map((n) => n.toString(16).padStart(2, "0")).join("")}`
+        if (seen.has(renderId)) throw new Error("component_contract")
+        seen.add(renderId)
+        const projected = await guardComponentProps(instance.contract.props, instance.props)
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The closed schema guard and bounded JSON validator produced this public props object before native rendering.
+        const guarded = projected as Record<string, unknown> // Closed schema guard and JSON check own this boundary.
+        const slots = Object.fromEntries(
+          instance.contract.slots.map((name) => {
+            const html = instance.slots[name] ?? ""
+            if (typeof html !== "string") throw new Error("component_contract")
+            return [name, `<nifra-slot data-nifra-slot="${name}">${html}</nifra-slot>`]
+          }),
+        )
+        const html = await render(instance.contract.component, { ...guarded, slots }, renderId)
+        if (context.signal.aborted) throw new Error("component_cancelled")
+        markup[slot] = {
+          html: `<nifra-island data-nifra-island="${renderId}">${html}</nifra-island>`,
+          renderId,
+        }
+        islands.push({
+          reference: instance.contract.reference,
+          key: instance.key,
+          // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The closed schema guard and bounded JSON validator produced this public props object before native rendering.
+          props: projected as ComponentIsland["props"],
+          renderId,
+          slots: instance.slots,
+        })
+      }
+      const ranges: Record<string, { html: string; instance: string }> = Object.create(null)
+      const rangeIds = new Set<string>()
+      for (const [name, child] of Object.entries(value.ranges)) {
+        if (
+          !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name) ||
+          child.parent !== context.instance ||
+          !(context.children ?? []).includes(child) ||
+          rangeIds.has(child.instance)
+        )
+          throw new Error("component_contract")
+        rangeIds.add(child.instance)
+        ranges[name] = {
+          instance: child.instance,
+          html:
+            '<nifra-component data-nifra-component="' +
+            child.instance +
+            '">' +
+            child.html +
+            "</nifra-component>",
+        }
+      }
+      const html = await render(
+        value.component,
+        { props, islands: markup, ranges },
+        `${context.instance}-view`,
+      )
+      return { html, islands }
+    },
+  }
+}

package/src/server-components/portal.ts

@@ -0,0 +1,42 @@
+/** Resolve only a declared target inside the island or component that owns the calling node. */
+export function componentPortalTarget(source: Element, target: Element): Element {
+  const owner = source.closest("[data-nifra-island], [data-nifra-component]")
+  const name = target.getAttribute("data-nifra-portal")
+  if (
+    owner === null ||
+    name === null ||
+    !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name) ||
+    !owner.contains(target) ||
+    target.closest("[data-nifra-island], [data-nifra-component]") !== owner
+  )
+    throw new Error("component_contract")
+  return target
+}
+
+const cleanups = new WeakMap<Element, Set<() => Promise<void>>>()
+
+/** Native portal actions register cleanup with the island that owns their target. */
+export function ownComponentPortal(
+  source: Element,
+  target: Element,
+  cleanup: () => void | Promise<void>,
+): () => Promise<void> {
+  componentPortalTarget(source, target)
+  const owner = source.closest("[data-nifra-island], [data-nifra-component]")!
+  const entries = cleanups.get(owner) ?? new Set<() => Promise<void>>()
+  let pending: Promise<void> | undefined
+  const dispose = () => {
+    entries.delete(dispose)
+    pending ??= Promise.resolve().then(cleanup)
+    return pending
+  }
+  entries.add(dispose)
+  cleanups.set(owner, entries)
+  return dispose
+}
+
+export async function disposeComponentPortals(owner: Element): Promise<void> {
+  const entries = cleanups.get(owner)
+  cleanups.delete(owner)
+  if (entries !== undefined) await Promise.all([...entries].map((cleanup) => cleanup()))
+}

package/src/server-components/props.ts

@@ -0,0 +1,19 @@
+import type { StandardSchemaV1 } from "@nifrajs/core/schema"
+import { outputGuard, runGuard } from "../internal/output-guard.ts"
+import { assertComponentSchema } from "./schema.ts"
+import { componentValue } from "./value.ts"
+
+const guards = new WeakMap<object, ReturnType<typeof outputGuard>>()
+
+export async function guardComponentProps(
+  schema: StandardSchemaV1,
+  value: unknown,
+): Promise<unknown> {
+  let guard = guards.get(schema)
+  if (guard === undefined) {
+    assertComponentSchema(schema)
+    guard = outputGuard(schema, "client component", "props")
+    guards.set(schema, guard)
+  }
+  return componentValue(await runGuard(guard, value, "client component props"))
+}

package/src/server-components/protocol.ts

@@ -0,0 +1,167 @@
+import { ServerComponentError } from "./error.ts"
+import type { ComponentKey, ComponentValue } from "./types.ts"
+import { componentValue } from "./value.ts"
+
+export const COMPONENT_HEADER = "x-nifra-component"
+export const COMPONENT_MEDIA_TYPE = "application/vnd.nifra.component-v1"
+export const COMPONENT_PROTOCOL = 1
+export const COMPONENT_LIMITS = Object.freeze({
+  headerBytes: 2048,
+  encodedHeaderBytes: 2732,
+  inputBytes: 1024,
+  propsBytes: 65536,
+  outputBytes: 1048576,
+  documentBytes: 4194304,
+  frameBytes: 262144,
+  depth: 16,
+  instances: 128,
+  requestLoads: 8,
+  activeLoads: 64,
+  queuedLoads: 128,
+  executionMs: 10000,
+  idleMs: 5000,
+  operationMs: 15000,
+})
+
+export interface ComponentRequest {
+  readonly v: 1
+  readonly build: string
+  readonly reference: string
+  readonly key: ComponentKey
+  readonly parent: string | null
+  readonly generation: number
+  readonly routeEpoch: number
+  readonly authEpoch: number
+  readonly input: ComponentValue
+}
+
+const fields = [
+  "v",
+  "build",
+  "reference",
+  "key",
+  "parent",
+  "generation",
+  "routeEpoch",
+  "authEpoch",
+  "input",
+]
+const token = /^[A-Za-z0-9_-]{1,128}$/
+const encoder = new TextEncoder()
+const decoder = new TextDecoder("utf-8", { fatal: true })
+
+export function componentKey(value: unknown): value is ComponentKey {
+  return (
+    (typeof value === "string" &&
+      encoder.encode(value).length > 0 &&
+      encoder.encode(value).length <= 128) ||
+    (typeof value === "number" && Number.isSafeInteger(value))
+  )
+}
+
+export function parseComponentRequest(value: unknown): ComponentRequest {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new ServerComponentError("component_protocol", 400)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; every field is validated before a request is returned.
+  const object = value as Record<string, unknown>
+  if (
+    Object.keys(object).length !== fields.length ||
+    fields.some((name) => !Object.hasOwn(object, name)) ||
+    object.v !== 1 ||
+    typeof object.build !== "string" ||
+    !token.test(object.build) ||
+    typeof object.reference !== "string" ||
+    !token.test(object.reference) ||
+    !componentKey(object.key) ||
+    (object.parent !== null && (typeof object.parent !== "string" || !token.test(object.parent)))
+  ) {
+    throw new ServerComponentError("component_protocol", 400)
+  }
+  const counter = (value: unknown): number => {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+      throw new ServerComponentError("component_protocol", 400)
+    return value
+  }
+  const input = componentValue(object.input, COMPONENT_LIMITS.inputBytes)
+  return {
+    v: 1,
+    build: object.build,
+    reference: object.reference,
+    key: object.key,
+    parent: object.parent,
+    generation: counter(object.generation),
+    routeEpoch: counter(object.routeEpoch),
+    authEpoch: counter(object.authEpoch),
+    input,
+  }
+}
+
+function base64url(bytes: Uint8Array): string {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "")
+}
+
+export function componentRequestHeader(value: ComponentRequest): string {
+  const request = parseComponentRequest(value)
+  const bytes = encoder.encode(JSON.stringify(request))
+  if (bytes.length > COMPONENT_LIMITS.headerBytes)
+    throw new ServerComponentError("component_limit", 431)
+  return base64url(bytes)
+}
+
+export function readComponentRequest(request: Request): ComponentRequest | undefined {
+  const encoded = request.headers.get(COMPONENT_HEADER)
+  if (encoded === null) return undefined
+  if (
+    request.method !== "GET" ||
+    request.headers.has("x-nifra-data") ||
+    request.headers.has("x-nifra-retain") ||
+    request.headers.has("x-nifra-revalidate") ||
+    request.headers.has("x-nifra-from")
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  if (encoded.length > COMPONENT_LIMITS.encodedHeaderBytes)
+    throw new ServerComponentError("component_limit", 431)
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded) || encoded.length % 4 === 1)
+    throw new ServerComponentError("component_protocol", 400)
+  const origin = new URL(request.url).origin
+  if (
+    request.headers.get("sec-fetch-site") !== "same-origin" ||
+    (request.headers.has("origin") && request.headers.get("origin") !== origin)
+  ) {
+    throw new ServerComponentError("component_denied", 403)
+  }
+  let decoded: unknown
+  try {
+    const binary = atob(encoded.replaceAll("-", "+").replaceAll("_", "/"))
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0))
+    if (bytes.length > COMPONENT_LIMITS.headerBytes)
+      throw new ServerComponentError("component_limit", 431)
+    if (base64url(bytes) !== encoded) throw new ServerComponentError("component_protocol", 400)
+    decoded = JSON.parse(decoder.decode(bytes))
+  } catch (error) {
+    if (error instanceof ServerComponentError) throw error
+    throw new ServerComponentError("component_protocol", 400)
+  }
+  return parseComponentRequest(decoded)
+}
+
+export const COMPONENT_RESPONSE_HEADERS = Object.freeze({
+  "content-type": COMPONENT_MEDIA_TYPE,
+  "cache-control": "private, no-store",
+  "x-content-type-options": "nosniff",
+  vary: "x-nifra-component, x-nifra-data",
+})
+
+export function componentFailure(error: unknown): Response {
+  const failure =
+    error instanceof ServerComponentError ? error : new ServerComponentError("component_failed")
+  return Response.json(
+    { v: 1, error: failure.code },
+    {
+      status: failure.status === 499 ? 409 : failure.status,
+      headers: { ...COMPONENT_RESPONSE_HEADERS, "content-type": "application/json" },
+    },
+  )
+}