@octanejs/vite-plugin 0.1.3 → 0.1.4

package/src/server/production.js

@@ -1,26 +1,286 @@
+// @ts-check
 /**
  * Production fetch-handler factory + config re-exports.
  *
- * PHASE 1 STUB. `createHandler` is the runtime entry the generated server
- * bundle calls in production; it is wired in Phase 2 (async render, adapter
- * `serve`, asset preload, RPC). Until then it throws a clear error. The
- * `./production` export path stays resolvable, and `resolveOctaneConfig` is
- * re-exported here because the generated server entry imports it from this
- * module (mirrors @ripple-ts/vite-plugin).
+ * `createHandler(manifest, deps)` is the runtime entry the generated server
+ * bundle (dist/server/entry.js) calls in production. It is designed to be
+ * BUNDLED: platform-agnostic (no Node imports — platform capabilities come via
+ * `manifest.runtime`), and free of vite / octane-compiler imports (which is why
+ * `resolveOctaneConfig` is re-exported from resolve-config.js, not
+ * load-config.js).
+ *
+ * The render path mirrors the DEV middleware's `handleRenderRoute`
+ * (server/render-route.js) byte-for-byte in everything hydration can see —
+ * the same `renderToReadableStream` engine, the same `#__octane_data` payload
+ * (same keys, same order), and the same template-prefix → render-stream →
+ * template-suffix assembly — so `hydrateRoot()` adopts a production response
+ * exactly as it adopts a dev one. Deliberate differences: the template is the
+ * BUILT dist/client/index.html (hashed hydrate script already in place, so
+ * nothing is injected per-request), per-route `<link rel=stylesheet/modulepreload>`
+ * tags from the client manifest join the head, and render errors produce a
+ * plain 500 (no dev stack page). Keep the two files in sync when the shape
+ * changes.
  */
 
-export { resolveOctaneConfig } from '../load-config.js';
+import { createRouter } from './router.js';
+import { createContext, runMiddlewareChain } from './middleware.js';
+import { handleServerRoute } from './server-route.js';
+import { createLayoutWrapper, createPropsWrapper } from './component-wrappers.js';
+import {
+	get_component_export,
+	get_route_entry_export_name,
+	get_route_entry_path,
+} from '../routes.js';
+import {
+	patch_global_fetch,
+	build_rpc_lookup,
+	is_rpc_request,
+	handle_rpc_request,
+} from '@ripple-ts/adapter/rpc';
+
+export { resolveOctaneConfig } from '../resolve-config.js';
+
+/**
+ * @typedef {import('@octanejs/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@octanejs/vite-plugin').Middleware} Middleware
+ * @typedef {import('@octanejs/vite-plugin').Context} Context
+ */
+/**
+@import { ServerManifest, HandlerOptions, ClientAssetEntry } from '../../types/production.d.ts'
+ */
 
 /**
- * Create the production fetch handler (Phase 2).
+ * Create the production request handler from a manifest.
+ *
+ * The returned function is a standard Web `fetch`-style handler:
+ * `(request: Request) => Promise<Response>` — the generated server entry boots
+ * it behind the adapter's `serve()` (or the built-in Node server), and
+ * serverless wrappers import it directly.
  *
- * @param {unknown} _manifest
- * @param {unknown} _deps
- * @returns {never}
+ * @param {ServerManifest} manifest
+ * @param {HandlerOptions} deps
+ * @returns {(request: Request) => Promise<Response>}
+ */
+export function createHandler(manifest, deps) {
+	const { renderToReadableStream, prerender, htmlTemplate, executeServerFunction } = deps;
+	const router = createRouter(manifest.routes);
+	const globalMiddlewares = manifest.middlewares ?? [];
+	const trustProxy = manifest.trustProxy ?? false;
+	const runtime = manifest.runtime;
+
+	// RPC lookup for `module server` functions (hash → server function). Empty
+	// today — the octane compiler does not emit `module server` modules yet —
+	// but the wiring matches the dev middleware so it lights up when it does.
+	const rpcLookup =
+		manifest.rpcModules && runtime ? build_rpc_lookup(manifest.rpcModules, runtime.hash) : null;
+
+	// Request-scoped async context + same-origin fetch short-circuit: fetch()
+	// during SSR that resolves to this origin routes through the handler
+	// in-process instead of a network round-trip.
+	const asyncContext = runtime?.createAsyncContext();
+	const fetchHandle = asyncContext ? patch_global_fetch(asyncContext) : null;
+
+	const handler = async function handler(/** @type {Request} */ request) {
+		const url = new URL(request.url);
+		const method = request.method;
+
+		if (is_rpc_request(url.pathname)) {
+			if (!rpcLookup || !asyncContext) {
+				return new Response(JSON.stringify({ error: 'RPC is not configured' }), {
+					status: 404,
+					headers: { 'Content-Type': 'application/json' },
+				});
+			}
+			return handle_rpc_request(request, {
+				resolveFunction(/** @type {string} */ hash) {
+					const entry = rpcLookup.get(hash);
+					if (!entry) return null;
+					const fn = entry.serverObj[entry.funcName];
+					return typeof fn === 'function' ? fn : null;
+				},
+				executeServerFunction,
+				asyncContext,
+				trustProxy,
+			});
+		}
+
+		const match = router.match(method, url.pathname);
+		if (!match) {
+			// Static assets never reach here (the static layer — the built-in Node
+			// server, or the platform's file serving — runs first); an app with a
+			// catch-all RenderRoute matches everything else, so this is only hit
+			// when no catch-all exists.
+			return new Response('Not Found', { status: 404 });
+		}
+
+		const context = createContext(request, match.params);
+
+		try {
+			if (match.route.type === 'render') {
+				return await runMiddlewareChain(
+					context,
+					globalMiddlewares,
+					match.route.before || [],
+					async () => renderRoute(/** @type {RenderRoute} */ (match.route), context),
+					[],
+				);
+			}
+			return await handleServerRoute(match.route, context, globalMiddlewares);
+		} catch (error) {
+			console.error('[@octanejs/vite-plugin] Request error:', error);
+			return new Response('Internal Server Error', { status: 500 });
+		}
+	};
+
+	fetchHandle?.set_handler(handler);
+
+	/**
+	 * Render a RenderRoute — the production twin of dev's `handleRenderRoute`.
+	 *
+	 * @param {RenderRoute} route
+	 * @param {Context} context
+	 * @returns {Promise<Response>}
+	 */
+	async function renderRoute(route, context) {
+		const entryPath = get_route_entry_path(route.entry);
+		const exportName = get_route_entry_export_name(route.entry);
+		const PageComponent = entryPath
+			? get_component_export(manifest.components[entryPath] ?? {}, exportName)
+			: null;
+		if (!PageComponent) {
+			throw new Error(`Component not found for route ${route.path}`);
+		}
+
+		// Identical props to dev: `{ params, url }`, url origin-free so the client
+		// re-renders the exact string.
+		const requestUrl = context.url.pathname + context.url.search;
+		const pageProps = { params: context.params, url: requestUrl };
+
+		let RootComponent;
+		if (route.layout) {
+			const LayoutComponent = get_component_export(manifest.layouts[route.layout] ?? {}, undefined);
+			if (!LayoutComponent) {
+				throw new Error(`No layout component found for ${route.layout}`);
+			}
+			RootComponent = createLayoutWrapper(
+				/** @type {any} */ (LayoutComponent),
+				/** @type {any} */ (PageComponent),
+				pageProps,
+			);
+		} else {
+			RootComponent = createPropsWrapper(/** @type {any} */ (PageComponent), pageProps);
+		}
+
+		// The hydration payload — SAME keys, SAME order as dev render-route.js, so
+		// the data script is byte-identical between dev and production.
+		const routeData = JSON.stringify({
+			entry: entryPath,
+			exportName: exportName ?? null,
+			layout: route.layout ?? null,
+			routeIndex: getRenderRouteIndex(manifest.routes, route),
+			params: context.params,
+			url: requestUrl,
+			preHydrate: manifest.preHydrate ?? null,
+		});
+		const dataScript = `<script id="__octane_data" type="application/json">${escapeScript(routeData)}</script>`;
+
+		// Per-route asset hints from the client manifest: stylesheet links so
+		// page CSS applies before hydration, modulepreload so the page chunk
+		// downloads in parallel with the hydrate entry (which the template's own
+		// script tag already references).
+		/** @type {string[]} */
+		const preloadTags = [];
+		const entryAssets = entryPath ? manifest.clientAssets?.[entryPath] : undefined;
+		if (entryAssets) {
+			for (const cssFile of entryAssets.css) {
+				preloadTags.push(`<link rel="stylesheet" href="/${cssFile}">`);
+			}
+			if (entryAssets.js) {
+				preloadTags.push(`<link rel="modulepreload" href="/${entryAssets.js}">`);
+			}
+		}
+
+		const headContent = [...preloadTags, dataScript].join('\n');
+		const html = htmlTemplate.replace('<!--ssr-head-->', headContent);
+
+		const status = route.status ?? 200;
+		const headers = { 'Content-Type': 'text/html; charset=utf-8' };
+
+		const splitAt = html.indexOf('<!--ssr-body-->');
+		if (splitAt === -1) {
+			return new Response(html, { status, headers });
+		}
+		const prefix = html.slice(0, splitAt);
+		const suffix = html.slice(splitAt + '<!--ssr-body-->'.length);
+
+		if (manifest.render === 'buffered') {
+			// Await-everything fallback (`prerender` from octane/static): no
+			// streaming, one document. The deduped scoped-style tags lead the body
+			// markup inside #root — the same position they hold in the streamed
+			// shell — so hydrateRoot's leading-style skip applies unchanged.
+			const { html: body, css } = await prerender(RootComponent, undefined, {
+				onError(/** @type {unknown} */ error) {
+					console.error('[octane] SSR render error:', error);
+				},
+			});
+			return new Response(prefix + css + body + suffix, { status, headers });
+		}
+
+		// Streaming (default): shell flushes at first await, suspense segments
+		// stream out-of-order behind it — identical to dev.
+		/** @type {ReadableStream<Uint8Array>} */
+		const renderStream = await renderToReadableStream(RootComponent, undefined, {
+			onError(/** @type {unknown} */ error) {
+				console.error('[octane] SSR render error:', error);
+			},
+		});
+
+		const encoder = new TextEncoder();
+		const body = new ReadableStream({
+			async start(controller) {
+				controller.enqueue(encoder.encode(prefix));
+				const reader = renderStream.getReader();
+				try {
+					while (true) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						controller.enqueue(value);
+					}
+					controller.enqueue(encoder.encode(suffix));
+					controller.close();
+				} catch (error) {
+					controller.error(error);
+				} finally {
+					reader.releaseLock();
+				}
+			},
+			cancel(reason) {
+				return renderStream.cancel(reason);
+			},
+		});
+
+		return new Response(body, { status, headers });
+	}
+
+	return handler;
+}
+
+/**
+ * @param {import('@octanejs/vite-plugin').Route[]} routes
+ * @param {RenderRoute} route
+ * @returns {number | undefined}
+ */
+function getRenderRouteIndex(routes, route) {
+	const renderRoutes = routes.filter((r) => r.type === 'render');
+	const index = renderRoutes.indexOf(route);
+	return index === -1 ? undefined : index;
+}
+
+/**
+ * Escape script content to prevent XSS in the inline JSON data block.
+ * @param {string} str
+ * @returns {string}
  */
-export function createHandler(_manifest, _deps) {
-	throw new Error(
-		'[@octanejs/vite-plugin] Production build (createHandler) is Phase 2 — not yet implemented. ' +
-			'Dev SSR works via `vite dev`.',
-	);
+function escapeScript(str) {
+	return str.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
 }

package/src/server/render-route.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { createLayoutWrapper, createPropsWrapper } from './component-wrappers.js';
@@ -15,19 +16,27 @@ import {
  */
 
 /**
- * octane RenderResult — imported from 'octane/static' (the single source of
- * truth) rather than re-declared, so the shape can't silently drift. `prerender`
- * is ASYNC (awaits Suspense data) and returns `{ html, css }`: `html` has any
- * hoisted `<head>` metadata folded in, and `css` is ALREADY a deduped
- * `<style data-octane="hash">…</style>` string (NOT a Set<string> needing a
- * `get_css_for_hashes` lookup like Ripple), so CSS handling here is identity.
+ * Handle SSR rendering for a RenderRoute (dev) — STREAMING.
  *
- * @typedef {import('octane/static').RenderResult} RenderResult
+ * The render uses octane's `renderToReadableStream` (octane/server): the shell
+ * (with `@pending` fallbacks for anything still suspended) flushes as soon as
+ * it is ready, and each suspense boundary streams later as a hidden segment +
+ * an inline `$OCTRC` swap script, so a slow `use(thenable)` no longer blocks
+ * TTFB the way the old buffered `prerender` did. Consequences of streaming:
+ *
+ *   - Scoped CSS rides the STREAM (the shell emits its deduped
+ *     `<style data-octane>` tags ahead of the body markup, per-wave styles ride
+ *     their segment chunk), so nothing is spliced into `<!--ssr-head-->`
+ *     anymore — only the hydration data script goes there. `hydrateRoot()`
+ *     skips the shell's leading style tags when adopting.
+ *   - A render error BEFORE the shell completes still produces the dev 500
+ *     page (`renderToReadableStream` rejects on shell errors). An error AFTER
+ *     the shell (a rejected `use(thenable)` with no `@catch`) can't change the
+ *     status — the stream ends with `$OCTRX` markers and hydration
+ *     client-renders the affected boundaries.
  */
 
 /**
- * Handle SSR rendering for a RenderRoute (dev).
- *
  * @param {RenderRoute} route
  * @param {Context} context
  * @param {ViteDevServer} vite
@@ -43,10 +52,10 @@ export async function handleRenderRoute(route, context, vite, octaneConfig) {
 			/** @type {any} */ (globalThis).rpc_modules = new Map();
 		}
 
-		// Load the octane static renderer. The wrappers call components directly
-		// (no ssrComponent injection — the root must NOT be marker-wrapped), so
-		// only `prerender` is needed here (await-all, complete HTML).
-		const { prerender } = await vite.ssrLoadModule('octane/static');
+		// Load the octane streaming renderer. The wrappers call components
+		// directly (no ssrComponent injection — the root must NOT be
+		// marker-wrapped).
+		const { renderToReadableStream } = await vite.ssrLoadModule('octane/server');
 
 		// Load the page component (compiled in server mode by octane()).
 		const entryPath = get_route_entry_path(route.entry);
@@ -60,9 +69,14 @@ export async function handleRenderRoute(route, context, vite, octaneConfig) {
 			throw new Error(`No component found for route ${route.path}`);
 		}
 
-		// Build the component tree (with optional layout).
+		// Build the component tree (with optional layout). Every RenderRoute
+		// component receives the request `url` (pathname + search — origin-free so
+		// the identical string re-renders on the client) alongside its `params`,
+		// so an app-level router can match without baking the URL into per-route
+		// entry exports.
 		let RootComponent;
-		const pageProps = { params: context.params };
+		const requestUrl = context.url.pathname + context.url.search;
+		const pageProps = { params: context.params, url: requestUrl };
 
 		if (route.layout) {
 			const layoutModule = await vite.ssrLoadModule(route.layout);
@@ -81,34 +95,24 @@ export async function handleRenderRoute(route, context, vite, octaneConfig) {
 			RootComponent = createPropsWrapper(/** @type {any} */ (PageComponent), pageProps);
 		}
 
-		// Render to HTML. prerender() is async (awaits Suspense data) and returns
-		// { html, css }: `html` has any hoisted <head> metadata folded in and
-		// already contains any inline <script data-octane-suspense> seed.
-		/** @type {RenderResult} */
-		const { html: body, css } = await prerender(RootComponent);
-
-		// CSS is already a ready <style> string (or '') — identity, no re-wrapping.
-		const cssContent = css || '';
-
 		// Build head content with hydration data. The client entry is CONFIG-FREE
 		// (importing octane.config.ts into the browser would drag the plugin + the
 		// server adapter — and their `node:fs` imports — into the client graph and
 		// break at module-eval). So everything the client needs to pick + import
 		// the page/layout is serialized HERE: entry path, export name, layout path,
-		// and params. routeIndex stays for debugging / Phase-2 static maps.
+		// params, the request url, and the optional preHydrate module the client
+		// entry awaits before hydrateRoot. routeIndex stays for debugging /
+		// Phase-2 static maps.
 		const routeData = JSON.stringify({
 			entry: entryPath,
 			exportName: get_route_entry_export_name(route.entry) ?? null,
 			layout: route.layout ?? null,
 			routeIndex: getRenderRouteIndex(octaneConfig, route),
 			params: context.params,
+			url: requestUrl,
+			preHydrate: octaneConfig?.router.preHydrate ?? null,
 		});
-		const headContent = [
-			cssContent,
-			`<script id="__octane_data" type="application/json">${escapeScript(routeData)}</script>`,
-		]
-			.filter(Boolean)
-			.join('\n');
+		const headContent = `<script id="__octane_data" type="application/json">${escapeScript(routeData)}</script>`;
 
 		// Load and process index.html template.
 		const templatePath = join(vite.config.root, 'index.html');
@@ -117,19 +121,64 @@ export async function handleRenderRoute(route, context, vite, octaneConfig) {
 		// Apply Vite's HTML transforms (HMR client, module resolution, etc.).
 		template = await vite.transformIndexHtml(context.url.pathname, template);
 
-		// Replace placeholders.
-		let html = template.replace('<!--ssr-head-->', headContent).replace('<!--ssr-body-->', body);
+		let html = template.replace('<!--ssr-head-->', headContent);
 
 		// Inject the hydration entry before </body>.
 		const hydrationScript = `<script type="module" src="/@id/virtual:octane-hydrate"></script>`;
 		html = html.replace('</body>', `${hydrationScript}\n</body>`);
 
-		return new Response(html, {
-			status: 200,
-			headers: {
-				'Content-Type': 'text/html; charset=utf-8',
+		// Start the render. This await resolves at SHELL-ready (so a synchronous
+		// render error still falls into the catch below and produces the dev 500
+		// page); segments keep flushing through the returned stream afterwards.
+		/** @type {ReadableStream<Uint8Array>} */
+		const renderStream = await renderToReadableStream(RootComponent, undefined, {
+			onError(/** @type {unknown} */ error) {
+				if (error instanceof Error) vite.ssrFixStacktrace(error);
+				console.error('[octane] SSR render error:', error);
+			},
+		});
+
+		const status = route.status ?? 200;
+		const headers = { 'Content-Type': 'text/html; charset=utf-8' };
+
+		// No body placeholder → nothing to stream into; cancel the render and
+		// serve the transformed template (matches the old buffered behavior).
+		const splitAt = html.indexOf('<!--ssr-body-->');
+		if (splitAt === -1) {
+			await renderStream.cancel();
+			return new Response(html, { status, headers });
+		}
+		const prefix = html.slice(0, splitAt);
+		const suffix = html.slice(splitAt + '<!--ssr-body-->'.length);
+
+		// Template prefix → render stream (shell, then out-of-order segments) →
+		// template suffix. The hydration <script> is in the SUFFIX, so by the time
+		// the browser requests the entry every segment is already in the DOM.
+		const encoder = new TextEncoder();
+		const body = new ReadableStream({
+			async start(controller) {
+				controller.enqueue(encoder.encode(prefix));
+				const reader = renderStream.getReader();
+				try {
+					while (true) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						controller.enqueue(value);
+					}
+					controller.enqueue(encoder.encode(suffix));
+					controller.close();
+				} catch (error) {
+					controller.error(error);
+				} finally {
+					reader.releaseLock();
+				}
+			},
+			cancel(reason) {
+				return renderStream.cancel(reason);
 			},
 		});
+
+		return new Response(body, { status, headers });
 	} catch (error) {
 		console.error('[octane] SSR render error:', error);
 

package/src/server/router.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * @typedef {import('@octanejs/vite-plugin').Route} Route
  * @typedef {import('@octanejs/vite-plugin').RenderRoute} RenderRoute

package/src/server/server-route.js

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * @typedef {import('@octanejs/vite-plugin').Context} Context
  * @typedef {import('@octanejs/vite-plugin').ServerRoute} ServerRoute