@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/codegen.ts

@@ -10,12 +10,14 @@ import {
   DATA_GLOBAL,
   HANDOVER_ID,
   LAYOUT_DATA_GLOBAL,
+  LIVE_GLOBAL,
   LOCALES_GLOBAL,
   ROOT_ATTRIBUTE,
   ROUTE_GLOBAL,
 } from "../render-seam.ts"
 import { PRERENDERED_GLOBAL } from "../router.ts"
 import { jsStringLiteral, jsValueLiteral } from "./js-string.ts"
+import { keepAliveTable } from "./keep-alive-table.ts"
 
 /** The refusal for a server build given no client entry, shared by the codegen and `buildServer`. */
 export function missingClientEntry(clientEntry: unknown): TypeError {
@@ -53,6 +55,22 @@ export interface GenerateClientEntryOptions {
   /** The build moved copy tables into per-locale chunks: the handover carries the chunk URLs, and a
    * navigation loads the copy of the URL it goes to beside the route's code. */
   readonly copyChunks?: boolean
+  /**
+   * The server runs `createWebApp({ live })`: route loads go through its live load endpoint and the
+   * entry keeps what is on screen fresh (`@nifrajs/web/live-client`). Absent, the entry is exactly the
+   * non-live one.
+   */
+  readonly live?: LiveClientEntry | undefined
+}
+
+// The router as the entry names it: in a keep-alive app, the keep-alive layer over `router`.
+const keepAround = (keep: unknown, router: string): string =>
+  keep === undefined ? `const router = ${router}` : `const router = __keep.attach(${router})`
+
+/** A client entry for a live server: `{}`, or the endpoints when the runtime moves them. */
+export interface LiveClientEntry {
+  readonly path?: string
+  readonly loadPath?: string
 }
 
 /**
@@ -65,11 +83,31 @@ export interface GenerateClientEntryOptions {
  * Bun has no `import.meta.glob`, so file-based routing needs this. Write the result to a file and
  * bundle it with `buildClient` / `Bun.build` (+ the adapter's transform).
  */
+/** The client modules whose package has a keep-alive mount beside them, at `<package>/keep-alive`. */
+const KEEP_ALIVE_ADAPTERS: readonly string[] = [
+  "@nifrajs/web-react/client",
+  "@nifrajs/web-svelte/client",
+  "@nifrajs/web-preact/client",
+  "@nifrajs/web-solid/client",
+  "@nifrajs/web-vue/client",
+]
+
 export function generateClientEntry(
   manifest: Manifest,
   options: GenerateClientEntryOptions,
 ): string {
-  const { clientModule, resolve } = options
+  const { resolve } = options
+  const keep = keepAliveTable(manifest)
+  if (keep !== undefined && !KEEP_ALIVE_ADAPTERS.includes(options.clientModule)) {
+    throw new Error(
+      `[nifra/web] ${keep.routes.map((id) => `"${id}"`).join(", ")} export keepAlive, which needs the React, Preact, Solid, Svelte or Vue adapter; this app's client module is ${jsStringLiteral(options.clientModule)}. Remove the keepAlive export or switch the adapter.`,
+    )
+  }
+  // A keep-alive app mounts through the adapter's keep-alive module, which re-exports its client.
+  const clientModule =
+    keep === undefined
+      ? options.clientModule
+      : options.clientModule.replace(/\/client$/, "/keep-alive")
 
   const loaderRows: string[] = []
   const patternRows: string[] = []
@@ -165,6 +203,13 @@ export function generateClientEntry(
     )
   }
 
+  const live = options.live
+  const liveFetch =
+    keep !== undefined
+      ? ", fetchData: __keep.fetchData"
+      : live === undefined
+        ? ""
+        : ", fetchData: __live.fetchData"
   return `${[
     // `/client`, never the root: the root's graph carries the server (renderPage, the static-file
     // server), and Vite's dev server evaluates what it is given instead of tree-shaking it.
@@ -173,6 +218,8 @@ export function generateClientEntry(
     ...(options.serverComponents
       ? ['import { bindComponentRouter } from "@nifrajs/web/server-components/client"']
       : []),
+    ...(live === undefined ? [] : ['import { liveClient } from "@nifrajs/web/live-client"']),
+    ...(keep === undefined ? [] : ['import { keepAliveClient } from "@nifrajs/web/keep-alive"']),
     // Namespace import: `errorBoundary` is optional (an adapter may not export it). A namespace member
     // access yields `undefined` if absent - unlike a named import, which would be a link error.
     ...(loadings.length > 0
@@ -235,7 +282,22 @@ export function generateClientEntry(
     "const holds = {}",
     // routeId → the ids and `handle` exports `useMatches` reports (layouts, then the page).
     `const layoutIdsOf = ${jsValueLiteral(layoutIdsOf)}`,
+    ...(live === undefined
+      ? []
+      : [
+          `const __live = liveClient({ ${[
+            "layoutIdsOf",
+            ...(live.path === undefined ? [] : [`path: ${jsStringLiteral(live.path)}`]),
+            ...(live.loadPath === undefined ? [] : [`loadPath: ${jsStringLiteral(live.loadPath)}`]),
+          ].join(", ")} })`,
+        ]),
     "const matchChains = {}",
+    ...(keep === undefined
+      ? []
+      : [
+          `const keepAliveTable = ${jsValueLiteral(keep)}`,
+          `const __keep = keepAliveClient({ table: keepAliveTable, routeHooks, matchChains${live === undefined ? "" : ", fetchData: __live.fetchData"} })`,
+        ]),
     `const ${options.copyChunks === true ? "loadRoute" : "loadModule"} = async (id) => {`,
     "  if (chains[id]) return",
     "  const mods = await loaders[id]()",
@@ -271,7 +333,7 @@ export function generateClientEntry(
     // backend half, which no browser bundle contains.
     "  const boundaryMods = errorRouteIds.has(id) ? mods.slice(0, -1) : mods",
     "  const boundaries = boundaryMods.flatMap((m) => (m.boundaries ?? []).map((b) => ({ name: b.name, mode: b.mode, ...(b.errorId === undefined ? {} : { errorId: b.errorId }) })))",
-    "  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, boundaries }",
+    `  routeHooks[id] = { clientLoader: page.clientLoader, clientAction: page.clientAction, shareData: page.shareData, ${keep === undefined ? "" : "keepAlive: page.keepAlive, "}boundaries }`,
     "  if (page.ssr === false) holds[id] = [...chains[id].slice(0, -1), page.HydrateFallback ?? (() => null)]",
     "}",
     ...(options.copyChunks === true
@@ -293,7 +355,11 @@ export function generateClientEntry(
     "const handover = handovers[handovers.length - 1]",
     "if (handover !== undefined) {",
     '  const state = JSON.parse(handover.textContent || "{}")',
-    `  for (const key of ${jsValueLiteral(options.copyChunks === true ? [...HANDOVER_GLOBALS, COPY_CHUNKS_GLOBAL] : HANDOVER_GLOBALS)}) {`,
+    `  for (const key of ${jsValueLiteral([
+      ...HANDOVER_GLOBALS,
+      ...(options.copyChunks === true ? [COPY_CHUNKS_GLOBAL] : []),
+      ...(live === undefined ? [] : [LIVE_GLOBAL]),
+    ])}) {`,
     "    if (Object.prototype.hasOwnProperty.call(state, key)) Reflect.set(window, key, state[key])",
     "  }",
     "}",
@@ -325,6 +391,8 @@ export function generateClientEntry(
     `  layoutData: window.${LAYOUT_DATA_GLOBAL} && window.${LAYOUT_DATA_GLOBAL}.map(mapDeferred),`,
     `  boundaries: mapDeferred(window.${BOUNDARY_GLOBAL}),`,
     `  serverComponents: window.${COMPONENT_GLOBAL},`,
+    // The seed the server rendered the page with: the live client exchanges it for its first grant.
+    ...(live === undefined ? [] : [`  live: window.${LIVE_GLOBAL},`]),
     // actionData (only set after a form POST) is in the initial state so the binding hydrates
     // consistently with the server-rendered markup; mapped through `mapDeferred` too so a deferred
     // action's placeholders become registry markers (a no-op when the action didn't defer).
@@ -334,9 +402,18 @@ export function generateClientEntry(
     ...loadingLines,
     // With `_loading` pages the store is wrapped: a slow navigation then names a loading chain (the
     // shared layouts + the `_loading` component) for the mounted view to render in the meantime.
-    loadings.length > 0
-      ? `const router = withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })`
-      : `const router = createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks })`,
+    keepAround(
+      keep,
+      loadings.length > 0
+        ? `withLoading(createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks${liveFetch} }), { routes: loadingRoutes, modules: loadingModules, chains, searchSchemas, matchChains })`
+        : `createClientRouter({ patterns, initial, loadModule, statusRoutes${routerStatusOption}, searchClientKeys, routeHooks${liveFetch} })`,
+    ),
+    // Kept pages hold the code they were rendered with: a hot update drops them.
+    ...(keep === undefined
+      ? []
+      : [
+          'if (import.meta.hot) for (const event of ["bun:afterUpdate", "vite:afterUpdate"]) import.meta.hot.on(event, () => router.dropKept("hot-update"))',
+        ]),
     ...(options.serverComponents ? ["bindComponentRouter(router)"] : []),
     "installHistory(router)",
     "installForms(router)",
@@ -392,11 +469,13 @@ export function generateClientEntry(
     "      for (const listener of [...listeners]) listener()",
     "    }, 0)",
     "  }",
-    "  mountRouter({ router: view, routes: chains, searchSchemas, matchChains, container: root })",
+    `  mountRouter({ router: view, routes: chains, searchSchemas, matchChains, container: root${keep === undefined ? "" : ", keepAlive: keepAliveTable"} })`,
     // Run the optional client loader only after the adapter has mounted the SSR tree. The initial
     // server data is already in `window.__NIFRA_DATA__`, so `serverLoader()` reuses it and cannot
     // duplicate the first request.
     "  router.hydrate().catch((error) => console.error('[nifra/web] clientLoader failed:', error))",
+    // Once mounted: the first live load and the socket must not race the hydration.
+    ...(live === undefined ? [] : ["  __live.attach(router)"]),
     // Next frame: the adapter has committed its initial hydration, so handlers are attached. Flip the
     // document to interactive (`data-nifra-hydrated` + `nifra:hydrated`) for apps to gate pre-hydration UI.
     "  requestAnimationFrame(signalHydrated)",
@@ -521,6 +600,13 @@ function moduleSpecifier(resolved: string): string {
 // A route's namespace is not assignable to `RouteModule` under a strict `tsc` (a backend half has no
 // `default`, a typed `meta` narrows its data), so the table holds plain objects and the cast happens at
 // `buildManifest`'s boundary - the same cast `discoverRoutes` applies to its dynamic import.
+// The routes the scan found exporting `keepAlive`, which a disk-less server cannot scan again.
+const keepAliveArg = (manifest: Manifest): string => {
+  const files = [
+    ...new Set(manifest.routes.filter((route) => route.keepAlive).map((route) => route.file)),
+  ]
+  return files.length === 0 ? "" : `, { keepAlive: ${jsValueLiteral(files)} }`
+}
 const LAZY_IMPORTER = "(file) => loaders[file] as () => Promise<RouteModule>"
 const EAGER_IMPORTER = "(file) => () => Promise.resolve(modules[file] as RouteModule)"
 
@@ -604,7 +690,7 @@ export function generateServerManifest(
       cssLoadingLine,
       ...copyChunksLines,
       ...buildAssetsLines,
-      `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER})`,
+      `export const manifest = buildManifest(Object.keys(loaders), ${LAZY_IMPORTER}${keepAliveArg(manifest)})`,
     ].join("\n")}\n`
   }
   // Eager: `import * as` per route (all bundled into the entry, parsed at boot). Index-based
@@ -625,6 +711,6 @@ export function generateServerManifest(
     cssLoadingLine,
     ...copyChunksLines,
     ...buildAssetsLines,
-    `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER})`,
+    `export const manifest = buildManifest(Object.keys(modules), ${EAGER_IMPORTER}${keepAliveArg(manifest)})`,
   ].join("\n")}\n`
 }

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()
+}