@teyik0/furin 0.1.0-alpha.3

package/src/render/index.ts

@@ -0,0 +1,312 @@
+import { renderToReadableStream } from "react-dom/server";
+import type { RootLayout } from "../router.ts";
+import { assembleHTML, resolvePath, splitTemplate, streamToString } from "./assemble.ts";
+import { isrCache, ssgCache } from "./cache.ts";
+import { buildElement } from "./element.tsx";
+import { runLoaders } from "./loaders.ts";
+import { buildHeadInjection, safeJson } from "./shell.ts";
+import { getDevTemplate, getProductionTemplate } from "./template.ts";
+
+// ── Re-exports (public API) ──────────────────────────────────────────────────
+// biome-ignore lint/performance/noBarrelFile: acnowledged
+export { type LoaderContext, streamToString } from "./assemble.ts";
+export { buildElement } from "./element.tsx";
+export { type LoaderResult, runLoaders } from "./loaders.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+import type { Context } from "elysia";
+import type { ResolvedRoute } from "../router.ts";
+import { IS_DEV } from "../runtime-env.ts";
+import type { LoaderContext } from "./assemble.ts";
+import { generateIndexHtml } from "./shell.ts";
+
+interface RenderResult {
+  headers: Record<string, string>;
+  html: string;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function catchRedirect(err: unknown): Response {
+  if (err instanceof Response) {
+    return err;
+  }
+  throw err;
+}
+
+async function renderForPath(
+  route: ResolvedRoute,
+  params: Record<string, string>,
+  root: RootLayout,
+  origin: string
+): Promise<RenderResult> {
+  const resolvedPath = resolvePath(route.pattern, params);
+  return await renderToHTML(
+    route,
+    {
+      params,
+      query: {},
+      request: new Request(`${origin}${resolvedPath}`),
+      headers: {},
+      cookie: {},
+      redirect: (url, status = 302) => new Response(null, { status, headers: { Location: url } }),
+      set: { headers: {} },
+      path: resolvedPath,
+    } as Context,
+    root
+  );
+}
+
+// ── Core pipeline ────────────────────────────────────────────────────────────
+
+export async function renderToHTML(
+  route: ResolvedRoute,
+  ctx: Context,
+  root: RootLayout
+): Promise<RenderResult> {
+  const loaderResult = await runLoaders(route, ctx, root.route);
+
+  if (loaderResult.type === "redirect") {
+    throw loaderResult.response;
+  }
+
+  const { data, headers } = loaderResult;
+
+  const componentProps = {
+    ...data,
+    params: ctx.params,
+    query: ctx.query,
+    path: ctx.path,
+  };
+
+  const headData = buildHeadInjection(route.page?.head?.(componentProps));
+
+  const element = buildElement(route, componentProps, root.route);
+  const stream = await renderToReadableStream(element);
+  await stream.allReady;
+  const reactHtml = await streamToString(stream);
+
+  // Dev: self-fetch /_bun_hmr_entry (once, then cached) to get the Bun-processed
+  // HTML template with content-hashed chunk paths and HMR WebSocket client.
+  // Prod: read .furin/client/index.html from disk.
+  const template = IS_DEV
+    ? await getDevTemplate(new URL(ctx.request.url).origin)
+    : (getProductionTemplate() ?? generateIndexHtml());
+
+  return {
+    html: assembleHTML(template, headData, reactHtml, data),
+    headers,
+  };
+}
+
+// ── Public render functions ──────────────────────────────────────────────────
+
+export async function renderToStream(
+  route: ResolvedRoute,
+  ctx: Context,
+  root: RootLayout
+): Promise<ReadableStream | Response> {
+  const response = await renderSSR(route, ctx, root);
+  if (!response.ok) {
+    return response;
+  }
+  return response.body ?? new ReadableStream();
+}
+
+export async function prerenderSSG(
+  route: ResolvedRoute,
+  params: Record<string, string>,
+  root: RootLayout,
+  origin = "http://localhost:3000"
+): Promise<string> {
+  const resolvedPath = resolvePath(route.pattern, params);
+
+  const cached = ssgCache.get(resolvedPath);
+  if (cached && !IS_DEV) {
+    return cached;
+  }
+
+  const result = await renderForPath(route, params, root, origin);
+
+  if (!IS_DEV) {
+    ssgCache.set(resolvedPath, result.html);
+  }
+
+  return result.html;
+}
+
+export async function renderSSR(
+  route: ResolvedRoute,
+  ctx: Context,
+  root: RootLayout
+): Promise<Response> {
+  try {
+    const loaderResult = await runLoaders(route, ctx, root.route);
+    if (loaderResult.type === "redirect") {
+      return loaderResult.response;
+    }
+
+    const { data, headers } = loaderResult;
+    const componentProps = { ...data, params: ctx.params, query: ctx.query, path: ctx.path };
+
+    const headData = buildHeadInjection(route.page.head?.(componentProps));
+    const template = IS_DEV
+      ? await getDevTemplate(new URL(ctx.request.url).origin)
+      : (getProductionTemplate() ?? generateIndexHtml());
+
+    // Phase 2: split template around placeholders
+    const { headPre, bodyPre, bodyPost } = splitTemplate(template);
+    const dataScript = `<script id="__FURIN_DATA__" type="application/json">${safeJson(data)}</script>`;
+
+    // Phase 3: start React render without awaiting allReady
+    const element = buildElement(route, componentProps, root.route);
+    const reactStream = await renderToReadableStream(element);
+
+    // Phase 4: pipe head + React stream + tail into a single ReadableStream
+    const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
+    const writer = writable.getWriter();
+    const enc = new TextEncoder();
+
+    (async () => {
+      await writer.write(enc.encode(headPre + headData + bodyPre));
+      const reader = reactStream.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        await writer.write(value);
+      }
+      await writer.write(enc.encode(dataScript + bodyPost));
+      await writer.close();
+    })().catch((err) => writer.abort(err));
+
+    return new Response(readable, {
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-cache, no-store, must-revalidate",
+        ...headers,
+      },
+    });
+  } catch (err) {
+    return catchRedirect(err);
+  }
+}
+
+export async function handleISR(route: ResolvedRoute, ctx: Context, root: RootLayout) {
+  const revalidate = route.page._route.revalidate ?? 60;
+  const params = ctx.params ?? {};
+  const cacheKey = resolvePath(route.pattern, params);
+
+  const cached = isrCache.get(cacheKey);
+
+  if (cached && !IS_DEV) {
+    const age = Date.now() - cached.generatedAt;
+    const isFresh = age < revalidate * 1000;
+
+    if (!isFresh) {
+      revalidateInBackground(route, params, cacheKey, revalidate, root, ctx);
+    }
+
+    ctx.set.headers["content-type"] = "text/html; charset=utf-8";
+    ctx.set.headers["cache-control"] = isFresh
+      ? `public, s-maxage=${revalidate}, stale-while-revalidate=${revalidate}`
+      : "public, s-maxage=0, must-revalidate";
+
+    return cached.html;
+  }
+
+  try {
+    const result = await renderToHTML(route, ctx, root);
+
+    if (!IS_DEV) {
+      isrCache.set(cacheKey, { html: result.html, generatedAt: Date.now(), revalidate });
+    }
+
+    ctx.set.headers["content-type"] = "text/html; charset=utf-8";
+    ctx.set.headers["cache-control"] =
+      `public, s-maxage=${revalidate}, stale-while-revalidate=${revalidate}`;
+    return result.html;
+  } catch (err) {
+    return catchRedirect(err);
+  }
+}
+
+// ── SSG warm-up ──────────────────────────────────────────────────────────────
+
+/** Maximum number of concurrent `prerenderSSG` calls during SSG warm-up. */
+const SSG_WARM_CONCURRENCY = 4;
+
+/**
+ * Pre-renders all SSG routes that declare `staticParams` and populates the
+ * in-memory cache before the first real request arrives.
+ * Should be called from the Elysia `onStart` hook (production only).
+ *
+ * Uses a bounded worker pool (SSG_WARM_CONCURRENCY slots) so large sites
+ * with many routes × param sets cannot exhaust memory or CPU during startup.
+ * Failures are isolated per (route, params) pair and logged without aborting
+ * the rest of the warm-up.
+ */
+export async function warmSSGCache(
+  routes: ResolvedRoute[],
+  root: RootLayout,
+  origin: string
+): Promise<void> {
+  const targets = routes.filter((r) => r.mode === "ssg" && r.page.staticParams);
+
+  // Collect all (route, params) render tasks, handling per-route errors early.
+  const tasks: Array<() => Promise<void>> = [];
+  for (const route of targets) {
+    let paramSets: Record<string, string>[];
+    try {
+      paramSets = (await route.page.staticParams?.()) ?? [];
+    } catch (err) {
+      console.error(`[furin] SSG warm-up failed for ${route.pattern}:`, err);
+      continue;
+    }
+    for (const params of paramSets) {
+      tasks.push(async () => {
+        try {
+          await prerenderSSG(route, params, root, origin);
+        } catch (err) {
+          console.error(`[furin] SSG prerender failed for ${route.pattern}:`, err);
+        }
+      });
+    }
+  }
+
+  if (tasks.length === 0) {
+    return;
+  }
+
+  // Drain the task queue with a fixed-size worker pool.
+  const queue = [...tasks];
+  const workers = Array.from({ length: Math.min(SSG_WARM_CONCURRENCY, tasks.length) }, async () => {
+    while (queue.length > 0) {
+      await queue.shift()?.();
+    }
+  });
+  await Promise.all(workers);
+}
+
+function revalidateInBackground(
+  route: ResolvedRoute,
+  params: Record<string, string>,
+  cacheKey: string,
+  revalidate: number,
+  root: RootLayout,
+  originalCtx: LoaderContext
+) {
+  renderForPath(route, params, root, new URL(originalCtx.request.url).origin)
+    .then((result) => {
+      isrCache.set(cacheKey, {
+        html: result.html,
+        generatedAt: Date.now(),
+        revalidate,
+      });
+    })
+    .catch((err: unknown) => {
+      console.error("[furin] ISR background revalidation failed:", err);
+    });
+}

package/src/render/loaders.ts

@@ -0,0 +1,67 @@
+import type { Context } from "elysia";
+import type { LoaderDeps, RuntimeRoute } from "../client";
+import type { ResolvedRoute } from "../router";
+
+export type LoaderResult =
+  | { type: "data"; data: Record<string, unknown>; headers: Record<string, string> }
+  | { type: "redirect"; response: Response };
+
+export async function runLoaders(
+  route: ResolvedRoute,
+  ctx: Context,
+  rootLayout: RuntimeRoute
+): Promise<LoaderResult> {
+  try {
+    // Step 1: root loader runs first — provides global context (user, auth, etc.)
+    // Root data is merged into ctxWithRoot so all subsequent loaders receive it
+    // automatically (backward-compatible with the previous waterfall behaviour).
+    //
+    // deps is defined here so it can be passed to the root loader too.
+    // The root has no ancestors, so deps always returns an empty resolved promise.
+    const loaderMap = new Map<RuntimeRoute, Promise<Record<string, unknown>>>();
+
+    const deps: LoaderDeps = (routeRef) =>
+      loaderMap.get(routeRef as RuntimeRoute) ?? Promise.resolve({});
+
+    const rootData: Record<string, unknown> = rootLayout.loader
+      ? ((await rootLayout.loader({ ...ctx }, deps)) ?? {})
+      : {};
+    const ctxWithRoot = { ...ctx, ...rootData };
+
+    // Step 2: launch all ancestor + page loaders immediately in parallel.
+    // Each is stored in loaderMap keyed by object identity so that deps()
+    // can resolve a Promise for any route in the chain.
+    //
+    // Loaders are inserted in chain order (index 1, 2, 3 …) so when loader N
+    // calls `await deps(routeAtIndexM)` where M < N, the Promise is already
+    // present in the map — no deadlock is possible for backward dependencies.
+
+    for (let i = 1; i < route.routeChain.length; i++) {
+      const ancestor = route.routeChain[i];
+      if (ancestor?.loader) {
+        loaderMap.set(
+          ancestor,
+          Promise.resolve(ancestor.loader(ctxWithRoot, deps)).then((r) => r ?? {})
+        );
+      }
+    }
+
+    // Page loader — all ancestors are already in the map at this point.
+    const pagePromise: Promise<Record<string, unknown>> = route.page?.loader
+      ? Promise.resolve(route.page.loader(ctxWithRoot, deps)).then((r) => r ?? {})
+      : Promise.resolve({});
+
+    // Step 3: await all in parallel, then flat-merge results.
+    const results = await Promise.all([...loaderMap.values(), pagePromise]);
+    const data = Object.assign({}, rootData, ...results);
+    const headers: Record<string, string> = {};
+    Object.assign(headers, ctx.set.headers);
+
+    return { type: "data", data, headers };
+  } catch (err) {
+    if (err instanceof Response) {
+      return { type: "redirect", response: err };
+    }
+    throw err;
+  }
+}

package/src/render/shell.ts

@@ -0,0 +1,128 @@
+import type { HeadOptions, MetaDescriptor } from "../client.ts";
+
+export function extractTitle(meta?: MetaDescriptor[]): string | undefined {
+  if (!meta) {
+    return undefined;
+  }
+  for (const entry of meta) {
+    if ("title" in entry) {
+      return (entry as { title: string }).title;
+    }
+  }
+  return undefined;
+}
+
+export function isMetaTag(entry: MetaDescriptor): boolean {
+  return !(
+    "title" in entry ||
+    "charSet" in entry ||
+    "script:ld+json" in entry ||
+    "tagName" in entry
+  );
+}
+
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+export function safeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+export function renderAttrs(obj: Record<string, string | undefined>): string {
+  return Object.entries(obj)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}="${escapeHtml(String(v))}"`)
+    .join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Head injection helpers
+// ---------------------------------------------------------------------------
+
+export function buildMetaParts(meta: MetaDescriptor[]): string[] {
+  const parts: string[] = [];
+  const title = extractTitle(meta);
+  if (title) {
+    parts.push(`<title>${escapeHtml(title)}</title>`);
+  }
+  for (const m of meta) {
+    if (isMetaTag(m)) {
+      parts.push(`<meta ${renderAttrs(m as Record<string, string>)} />`);
+    }
+    if ("script:ld+json" in m) {
+      parts.push(`<script type="application/ld+json">${safeJson(m["script:ld+json"])}</script>`);
+    }
+  }
+  return parts;
+}
+
+export function buildLinkParts(links: NonNullable<HeadOptions["links"]>): string[] {
+  return links.map((link) => `<link ${renderAttrs(link)} />`);
+}
+
+export function buildScriptParts(scripts: NonNullable<HeadOptions["scripts"]>): string[] {
+  return scripts.map((script) => {
+    const { children, ...rest } = script;
+    const attrs = renderAttrs(rest as Record<string, string | undefined>);
+    if (children) {
+      return `<script ${attrs}>${children}</script>`;
+    }
+    return `<script ${attrs}></script>`;
+  });
+}
+
+export function buildStyleParts(styles: NonNullable<HeadOptions["styles"]>): string[] {
+  return styles.map((style) => {
+    const typeAttr = style.type ? ` type="${escapeHtml(style.type)}"` : "";
+    return `<style${typeAttr}>${style.children}</style>`;
+  });
+}
+
+/**
+ * Builds the string to inject into the <!--ssr-head--> placeholder.
+ * Handles title, meta tags, links, inline scripts, and inline styles from
+ * the page's `head()` function.  CSS is handled by Bun (imported in user files).
+ */
+export function buildHeadInjection(headData: HeadOptions | undefined): string {
+  const parts: string[] = [];
+
+  if (headData?.meta) {
+    parts.push(...buildMetaParts(headData.meta));
+  }
+
+  if (headData?.links) {
+    parts.push(...buildLinkParts(headData.links));
+  }
+
+  if (headData?.scripts) {
+    parts.push(...buildScriptParts(headData.scripts));
+  }
+
+  if (headData?.styles) {
+    parts.push(...buildStyleParts(headData.styles));
+  }
+
+  return parts.length > 0 ? `\n  ${parts.join("\n  ")}\n` : "";
+}
+
+export function generateIndexHtml(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <!--ssr-head-->
+  </head>
+  <body>
+    <div id="root"><!--ssr-outlet--></div>
+    <script type="module" src="./_hydrate.tsx"></script>
+  </body>
+</html>
+`;
+}

package/src/render/template.ts

@@ -0,0 +1,54 @@
+// ── Dev template ─────────────────────────────────────────────────────────────
+
+import { readFileSync } from "node:fs";
+
+const devTemplatePromises = new Map<string, Promise<string>>();
+let _prodTemplatePath: string | null = null;
+let _prodTemplateContent: string | null = null;
+
+export function getDevTemplate(origin: string): Promise<string> {
+  const cached = devTemplatePromises.get(origin);
+  if (cached) {
+    return cached;
+  }
+
+  const promise = fetch(`${origin}/_bun_hmr_entry`)
+    .then((r) => {
+      if (!r.ok) {
+        throw new Error(`/_bun_hmr_entry returned ${r.status}`);
+      }
+      return r.text();
+    })
+    .catch((err) => {
+      devTemplatePromises.delete(origin);
+      throw err;
+    });
+
+  devTemplatePromises.set(origin, promise);
+  return promise;
+}
+
+export function setProductionTemplatePath(path: string | null): void {
+  _prodTemplatePath = path;
+  _prodTemplateContent = null;
+}
+
+export function setProductionTemplateContent(content: string): void {
+  _prodTemplatePath = null;
+  _prodTemplateContent = content;
+}
+
+export function getProductionTemplate(): string | null {
+  if (_prodTemplateContent !== null) {
+    return _prodTemplateContent;
+  }
+  if (!_prodTemplatePath) {
+    return null;
+  }
+  try {
+    _prodTemplateContent = readFileSync(_prodTemplatePath, "utf8");
+    return _prodTemplateContent;
+  } catch {
+    return null;
+  }
+}