@nifrajs/web 5.5.0 → 5.6.0

package/src/internal/dev-websocket.ts

@@ -0,0 +1,230 @@
+/**
+ * The app's WebSocket routes under the dev servers. Neither dev server is the app's own listener, so
+ * neither gets the upgrades `app.listen()` and the adapters wire: each hands the handshake to the
+ * app's `resolveWebSocketUpgrade` seam - the route's `upgrade()` guard and Origin check included - and
+ * wires an accepted socket with the runtime's own `attach`, so a dev socket behaves as a served one.
+ */
+import type { WebSocketUpgradeOutcome } from "@nifrajs/core"
+
+type Upgrade = Extract<WebSocketUpgradeOutcome, { readonly kind: "upgrade" }>
+
+/** A nifra app's handshake seam; a plain `{ fetch }` handler has none and takes no upgrades. */
+export interface UpgradableApp {
+  resolveWebSocketUpgrade?(
+    request: Request,
+  ): WebSocketUpgradeOutcome | Promise<WebSocketUpgradeOutcome>
+}
+
+export function isWebSocketUpgrade(request: Request): boolean {
+  return request.headers.get("upgrade")?.toLowerCase() === "websocket"
+}
+
+type Listener = (event: never) => void
+
+/** A standard-socket view `attach` wires its listeners to; the dev server feeds it events. */
+function socketView(native: {
+  send(data: string | ArrayBufferView | ArrayBuffer): unknown
+  close(code?: number, reason?: string): void
+  readonly readyState: number
+}) {
+  const listeners = new Map<string, Listener[]>()
+  return {
+    view: {
+      send: (data: string | ArrayBufferView | ArrayBuffer): void => {
+        native.send(data)
+      },
+      close: (code?: number, reason?: string) => native.close(code, reason),
+      get readyState() {
+        return native.readyState
+      },
+      addEventListener(type: string, listener: Listener): void {
+        listeners.set(type, [...(listeners.get(type) ?? []), listener])
+      },
+    },
+    emit(type: string, event: unknown): void {
+      for (const listener of listeners.get(type) ?? []) Reflect.apply(listener, undefined, [event])
+    },
+  }
+}
+
+function attachView(view: ReturnType<typeof socketView>["view"], outcome: Upgrade): void {
+  outcome.attach(view, outcome.handler, outcome.data, {
+    openNow: true,
+    pubsub: outcome.pubsub,
+    maxPayloadBytes: outcome.maxPayloadBytes,
+  })
+}
+
+// --- Bun ----------------------------------------------------------------------------------------
+
+/** What a dev socket carries from its handshake to `open`, and the view its events go to after. */
+export interface BunDevSocketData {
+  readonly outcome: Upgrade
+  emit?: (type: string, event: unknown) => void
+}
+
+/** The part of Bun's `ServerWebSocket` used here. */
+interface BunDevSocket {
+  send(data: string | ArrayBufferView | ArrayBuffer): unknown
+  close(code?: number, reason?: string): void
+  readonly readyState: number
+  readonly data: BunDevSocketData
+}
+
+export interface BunUpgradeServer {
+  upgrade(request: Request, options: { data: BunDevSocketData }): boolean
+}
+
+/** `Bun.serve`'s `websocket` option for a dev server whose upgrades go through {@link upgradeOnBun}. */
+export const bunDevWebSocket = {
+  open(socket: BunDevSocket): void {
+    const { view, emit } = socketView(socket)
+    socket.data.emit = emit
+    attachView(view, socket.data.outcome)
+  },
+  message(socket: BunDevSocket, message: string | Uint8Array): void {
+    socket.data.emit?.("message", { data: message })
+  },
+  close(socket: BunDevSocket, code: number, reason: string): void {
+    socket.data.emit?.("close", { code, reason })
+  },
+}
+
+/**
+ * Run the handshake through the app. `undefined` when the socket was upgraded; a `Response` for a
+ * refusal; `"pass"` when no WebSocket route takes the path, for the dev server to answer as HTTP.
+ */
+export async function upgradeOnBun(
+  app: UpgradableApp,
+  request: Request,
+  server: BunUpgradeServer,
+): Promise<Response | "pass" | undefined> {
+  if (app.resolveWebSocketUpgrade === undefined) return "pass"
+  const outcome = await app.resolveWebSocketUpgrade(request)
+  if (outcome.kind === "pass") return "pass"
+  if (outcome.kind === "reject") return outcome.response
+  return server.upgrade(request, { data: { outcome } })
+    ? undefined
+    : new Response("upgrade_required", { status: 426 })
+}
+
+// --- Node (the Vite dev server) -------------------------------------------------------------------
+
+/** The part of a Node socket an upgrade writes to. */
+export interface UpgradeSocket {
+  write(chunk: string): unknown
+  destroy(): void
+  on(event: "error", listener: () => void): unknown
+}
+
+/** The part of the `ws` package's `WebSocketServer` used here (no `@types/ws` dependency). */
+export interface WsServer {
+  handleUpgrade(
+    request: unknown,
+    socket: UpgradeSocket,
+    head: unknown,
+    done: (ws: WsSocket) => void,
+  ): void
+}
+
+/** The part of a `ws` socket used here. Its own events, not its `addEventListener`: Bun's `ws`
+ * shim hands text frames to that as bytes. The shim also gives a close reason as a string where
+ * `ws` gives bytes. */
+interface WsSocket {
+  send(data: string | ArrayBufferView | ArrayBuffer): void
+  close(code?: number, reason?: string): void
+  readonly readyState: number
+  on(event: "message", listener: (data: string | Uint8Array, isBinary: boolean) => void): void
+  on(event: "close", listener: (code: number, reason: string | Uint8Array) => void): void
+  on(event: "error", listener: (error: Error) => void): void
+}
+
+const TEXT = new TextDecoder()
+const textOf = (data: string | Uint8Array): string =>
+  typeof data === "string" ? data : TEXT.decode(data)
+
+/** A non-literal specifier: `ws` is an optional peer, typed structurally above. */
+const WS_MODULE = "ws"
+
+/** A noServer `ws` server from `specifier`; undefined when it cannot be loaded or has none. */
+export async function wsServerFrom(specifier: string): Promise<WsServer | undefined> {
+  try {
+    const mod: {
+      WebSocketServer?: new (options: { noServer: true }) => WsServer
+      default?: { WebSocketServer?: new (options: { noServer: true }) => WsServer }
+    } = await import(specifier)
+    const Server = mod.WebSocketServer ?? mod.default?.WebSocketServer
+    return Server === undefined ? undefined : new Server({ noServer: true })
+  } catch {
+    return undefined
+  }
+}
+
+let wsServer: Promise<WsServer | undefined> | undefined
+
+/** One server for every dev upgrade. */
+const loadWsServer = (): Promise<WsServer | undefined> => {
+  wsServer ??= wsServerFrom(WS_MODULE)
+  return wsServer
+}
+
+/**
+ * Answer a Node `upgrade` event through the app. Resolves `false` when no WebSocket route takes the
+ * path, leaving the socket to the other listeners (Vite's HMR among them).
+ */
+export async function upgradeOnNode(
+  app: UpgradableApp,
+  request: Request,
+  nodeRequest: unknown,
+  socket: UpgradeSocket,
+  head: unknown,
+  wsServerOf: () => Promise<WsServer | undefined> = loadWsServer,
+): Promise<boolean> {
+  if (app.resolveWebSocketUpgrade === undefined) return false
+  // A peer can reset the socket while the guard is awaited; with no listener that error ends the process.
+  socket.on("error", () => {})
+  let outcome: WebSocketUpgradeOutcome
+  try {
+    outcome = await app.resolveWebSocketUpgrade(request)
+  } catch {
+    await writeRefusal(socket, new Response("internal_error", { status: 500 }))
+    return true
+  }
+  if (outcome.kind === "pass") return false
+  if (outcome.kind === "reject") {
+    await writeRefusal(socket, outcome.response)
+    return true
+  }
+  const wss = await wsServerOf()
+  if (wss === undefined) {
+    await writeRefusal(
+      socket,
+      new Response("[nifra] install `ws` to serve app.ws() routes under the Vite dev server\n", {
+        status: 501,
+      }),
+    )
+    return true
+  }
+  const upgrade = outcome
+  wss.handleUpgrade(nodeRequest, socket, head, (ws) => {
+    const { view, emit } = socketView(ws)
+    ws.on("message", (data, isBinary) => emit("message", { data: isBinary ? data : textOf(data) }))
+    // Bun's `node:http` stops listening when a socket's close listener throws.
+    ws.on("close", (code, reason) => emit("close", { code, reason: textOf(reason) }))
+    ws.on("error", (error) => emit("error", error))
+    attachView(view, upgrade)
+  })
+  return true
+}
+
+/** A refusal written to the raw socket, then closed. */
+async function writeRefusal(socket: UpgradeSocket, response: Response): Promise<void> {
+  const body = await response.text()
+  let head = `HTTP/1.1 ${response.status} ${response.statusText || "Refused"}\r\n`
+  response.headers.forEach((value, key) => {
+    if (key !== "content-length" && key !== "connection") head += `${key}: ${value}\r\n`
+  })
+  head += `content-length: ${new TextEncoder().encode(body).byteLength}\r\nconnection: close\r\n\r\n`
+  socket.write(head + body)
+  socket.destroy()
+}

package/src/internal/hole-runtime.ts

@@ -0,0 +1,286 @@
+/**
+ * The browser side of a partially prerendered page's holes, shared by every adapter's `Hole`: the
+ * host's first fill from the document, and each refill a data request brings when the page on screen
+ * reloads. An adapter supplies only how an interactive hole's own root hydrates, updates and goes. A
+ * hole that shows a server component mounts the client islands inside it through the component
+ * client the app registered with `holeComponents` (`@nifrajs/web/server-components/client`).
+ */
+import type { ComponentClientAdapter, ComponentClientRoot } from "../server-components/client.ts"
+import type { ComponentRecord } from "../server-components/types.ts"
+import { onPageRelease, PAGE_HIDE_EVENT, PAGE_SHOW_EVENT } from "./page-events.ts"
+
+/** One hole's fill, as the PPR runtime keeps it. */
+export interface HoleFill {
+  readonly props?: unknown
+  readonly error: boolean
+  /** The record of the server component the hole shows, without its HTML. */
+  readonly component?: unknown
+  /** That component's HTML. */
+  readonly html?: string
+}
+
+/** The shell's inline runtime (internal/ppr/runtime.ts). */
+interface PprRuntime {
+  get(name: string): HoleFill | undefined
+  subscribe(name: string, callback: (fill: HoleFill) => void): () => void
+  put(name: string, frame: unknown, host: Element): void
+  /** Stop filling holes from the document, and cancel the ones still loading on the server. */
+  leave?(): void
+}
+
+/** The error slot a failed, timed-out or refused hole shows. Constant: no thrown message reaches it. */
+export const HOLE_ERROR_HTML = '<p data-nifra-hole-error="">This section is unavailable.</p>'
+
+const ERROR_FRAME = { v: 1, error: true, html: HOLE_ERROR_HTML } as const
+
+/** The runtime the shell's inline script defines, when this document has one. */
+const pprRuntime = (): PprRuntime | undefined => {
+  const runtime: unknown = Reflect.get(globalThis, "__nifraPpr")
+  return typeof runtime === "function" &&
+    "get" in runtime &&
+    "subscribe" in runtime &&
+    "put" in runtime
+    ? // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the shell's constant inline runtime defines exactly this shape.
+      (runtime as PprRuntime)
+    : undefined
+}
+
+/** How the islands inside a hole that shows a server component mount: the app's component client,
+ * and the protocol check the component's record passes first. */
+export interface HoleComponents {
+  readonly client: ComponentClientAdapter
+  record(value: unknown): ComponentRecord
+}
+
+let components: HoleComponents | undefined
+
+/** What `holeComponents` registers; `undefined` forgets it. */
+export function setHoleComponents(next: HoleComponents | undefined): void {
+  components = next
+}
+
+/** An interactive hole's own root, as its adapter made it. */
+export interface HoleRoot {
+  /** Render new props into the root, keeping its state; `false` when it has to be made again. */
+  update(props: unknown): boolean
+  /** `leaving`: the page is unmounting the host, so the adapter may defer the work. A promise means
+   * the host is not free until it settles. */
+  dispose(leaving: boolean): void | Promise<void>
+  /** The kept page holding the host is hidden (`true`) or shown again: a root whose framework can
+   * pause what it runs keeps its state either way. */
+  hide?(hidden: boolean): void
+}
+
+export interface HoleHost {
+  /** Apply a data request's fill once it arrives, unless a newer one is given first. Without the
+   * shell's runtime, only a server component's fill or the error slot can be put. A first fill the
+   * host was rendered with (`initialHtml`) hydrates its islands over that HTML. */
+  refill(fill: unknown): void
+  dispose(): void
+  /**
+   * For an adapter whose hidden page cleans its effects up (React's `Activity`): while a kept page
+   * hides the host, keep it, root and all, for the page's return, and dispose it only if the page is
+   * dropped. `false` when nothing hides the host, and disposing is the adapter's.
+   */
+  park(): boolean
+  /** The parked host is the adapter's again. */
+  unpark(): void
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+/** A fill the server deferred: the NDJSON stream settles its promise. */
+const settledFill = (fill: unknown): Promise<unknown> =>
+  isRecord(fill) && fill.__nifra_deferred === true && fill.promise instanceof Promise
+    ? fill.promise
+    : Promise.resolve(fill)
+
+/**
+ * What a host renders with: a blocking render's settled fill puts the server's HTML in it, which a
+ * crawler reads with no script; any other state leaves it empty. A host reads it once, so no later
+ * render changes what the runtime put there.
+ */
+export const initialHtml = (fill: unknown): string =>
+  isRecord(fill) && fill.__nifra_deferred !== true && typeof fill.html === "string" ? fill.html : ""
+
+/** The record of the server component a fill shows, its HTML put back, not yet checked. */
+const recordOf = (fill: Record<string, unknown>): Record<string, unknown> | undefined =>
+  isRecord(fill.component) && typeof fill.html === "string"
+    ? { ...fill.component, html: fill.html }
+    : undefined
+
+/** The error slot, built without HTML parsing, for a document with no runtime to put it. */
+const errorSlot = (host: Element): void => {
+  const slot = host.ownerDocument.createElement("p")
+  slot.setAttribute("data-nifra-hole-error", "")
+  slot.textContent = "This section is unavailable."
+  host.replaceChildren(slot)
+  host.setAttribute("data-nifra-hole-error", "")
+}
+
+/**
+ * The islands of the server component in `host`: hydrated over the server's HTML, or with `fresh`,
+ * put into the host from the record. `failed` runs when they cannot mount, as when the record fails
+ * the protocol check.
+ */
+function componentRoot(
+  host: Element,
+  unchecked: Record<string, unknown>,
+  fresh: boolean,
+  failed: () => void,
+): HoleRoot {
+  const registered = components
+  let current = true
+  const valid = (): boolean => current
+  const mounted: Promise<ComponentClientRoot | undefined> = (async () => {
+    if (registered === undefined) {
+      throw new Error(
+        "[nifra/web] ppr: a hole shows a server component, but no holeComponents client",
+      )
+    }
+    const { client } = registered
+    const record = registered.record(unchecked)
+    const mount = fresh ? client.create : client.hydrate
+    if (mount === undefined) throw new Error("[nifra/web] ppr: the component client cannot create")
+    const prepared = await client.prepare(record, valid, host, { records: [record] })
+    if (!current) return undefined
+    const root = await mount.call(client, host, record, prepared, valid)
+    if (!current) {
+      await root.dispose()
+      return undefined
+    }
+    host.setAttribute("aria-busy", "false")
+    return root
+  })().catch((error: unknown) => {
+    if (current) {
+      console.error("[nifra/web] ppr: a server component hole's islands did not mount", error)
+      failed()
+    }
+    return undefined
+  })
+  return {
+    update: () => false,
+    dispose() {
+      current = false
+      return mounted.then((root) => root?.dispose())
+    },
+  }
+}
+
+/**
+ * Drive the host of hole `name`. `hydrate` makes an interactive hole's root over the server HTML in
+ * `host`; a hole without one only ever shows server HTML, or a server component's.
+ */
+export function holeHost(
+  name: string,
+  host: Element,
+  hydrate: ((host: Element, props: unknown) => HoleRoot) | undefined,
+): HoleHost {
+  const runtime = pprRuntime()
+  let root: HoleRoot | undefined
+  let disposed = false
+  let latest = 0
+  // The kept page hiding the host, and what disposes the host if that page is dropped.
+  let hiddenBy: Element | undefined
+  let release: (() => void) | undefined
+  const put = (frame: Record<string, unknown>): void => {
+    if (runtime !== undefined) runtime.put(name, frame, host)
+    else errorSlot(host)
+    host.setAttribute("aria-busy", "false")
+  }
+  const showError = (): void => {
+    root = undefined
+    put(ERROR_FRAME)
+  }
+  const start = (fill: HoleFill): void => {
+    if (disposed || root !== undefined || fill.error) return
+    const record = recordOf({ component: fill.component, html: fill.html })
+    if (record !== undefined) root = componentRoot(host, record, false, showError)
+    else if (hydrate !== undefined) root = hydrate(host, fill.props)
+  }
+  const now = runtime?.get(name)
+  const unsubscribe =
+    now === undefined && (hydrate !== undefined || components !== undefined)
+      ? runtime?.subscribe(name, start)
+      : undefined
+  if (now !== undefined) start(now)
+  // A `keepAlive` page hidden behind another has been left: the document's holes stop filling and
+  // the ones still loading are cancelled, and a refill already on its way is dropped. The page's
+  // reload when it is shown again refills the host.
+  const hidden = (event: Event): void => {
+    if (!(event.target instanceof Element) || !event.target.contains(host)) return
+    hiddenBy = event.target
+    latest++
+    runtime?.leave?.()
+    root?.hide?.(true)
+  }
+  const shown = (event: Event): void => {
+    if (event.target !== hiddenBy) return
+    hiddenBy = undefined
+    root?.hide?.(false)
+  }
+  host.ownerDocument.addEventListener(PAGE_HIDE_EVENT, hidden)
+  host.ownerDocument.addEventListener(PAGE_SHOW_EVENT, shown)
+  const apply = (frame: unknown, mine: number, inPlace: boolean): void => {
+    if (!isRecord(frame)) return
+    const failed = frame.error === true
+    const record = failed ? undefined : recordOf(frame)
+    if (!failed && record === undefined && root?.update(frame.props) === true) {
+      host.setAttribute("aria-busy", "false")
+      return
+    }
+    // An error shows the error slot, never content the action that reloaded it may have changed.
+    const gone = root?.dispose(false)
+    root = undefined
+    const fill = (): void => {
+      if (disposed || mine !== latest) return
+      host.removeAttribute("data-nifra-hole-error")
+      if (record !== undefined) {
+        host.setAttribute("data-nifra-filled", "")
+        root = componentRoot(host, record, !inPlace, showError)
+        return
+      }
+      put(frame)
+      if (!failed && hydrate !== undefined) root = hydrate(host, frame.props)
+    }
+    if (gone instanceof Promise) gone.then(fill, fill)
+    else fill()
+  }
+  const dispose = (): void => {
+    disposed = true
+    release?.()
+    release = undefined
+    host.ownerDocument.removeEventListener(PAGE_HIDE_EVENT, hidden)
+    host.ownerDocument.removeEventListener(PAGE_SHOW_EVENT, shown)
+    unsubscribe?.()
+    Promise.resolve(root?.dispose(true)).catch(() => {})
+    root = undefined
+  }
+  return {
+    refill(fill) {
+      // A blocking render's settled fill is the server HTML the host already shows.
+      const inPlace = latest === 0 && root === undefined && initialHtml(fill) !== ""
+      const mine = ++latest
+      host.setAttribute("aria-busy", "true")
+      settledFill(fill).then(
+        (frame) => {
+          if (!disposed && mine === latest) apply(frame, mine, inPlace)
+        },
+        () => {
+          if (!disposed && mine === latest) apply(ERROR_FRAME, mine, false)
+        },
+      )
+    },
+    dispose,
+    park() {
+      if (disposed || hiddenBy === undefined) return false
+      release ??= onPageRelease(hiddenBy, dispose)
+      return true
+    },
+    unpark() {
+      release?.()
+      release = undefined
+    },
+  }
+}