@ripple-ts/vite-plugin 0.2.210 → 0.2.212

package/src/server/middleware.js

@@ -0,0 +1,126 @@
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Context} Context
+ * @typedef {import('@ripple-ts/vite-plugin').Middleware} Middleware
+ * @typedef {import('@ripple-ts/vite-plugin').NextFunction} NextFunction
+ */
+
+/**
+ * Compose multiple middlewares into a single middleware
+ * Follows Koa-style execution: request flows down, response flows back up
+ *
+ * @param {Middleware[]} middlewares
+ * @returns {(context: Context, finalHandler: () => Promise<Response>) => Promise<Response>}
+ */
+export function compose(middlewares) {
+	return function composed(context, finalHandler) {
+		let index = -1;
+
+		/**
+		 * @param {number} i
+		 * @returns {Promise<Response>}
+		 */
+		function dispatch(i) {
+			if (i <= index) {
+				return Promise.reject(new Error('next() called multiple times'));
+			}
+			index = i;
+
+			/** @type {Middleware | (() => Promise<Response>) | undefined} */
+			let fn;
+
+			if (i < middlewares.length) {
+				fn = middlewares[i];
+			} else if (i === middlewares.length) {
+				fn = finalHandler;
+			}
+
+			if (!fn) {
+				return Promise.reject(new Error('No handler provided'));
+			}
+
+			try {
+				// For the final handler, we don't pass next
+				if (i === middlewares.length) {
+					return Promise.resolve(/** @type {() => Promise<Response>} */ (fn)());
+				}
+				// For middlewares, pass context and next
+				return Promise.resolve(/** @type {Middleware} */ (fn)(context, () => dispatch(i + 1)));
+			} catch (err) {
+				return Promise.reject(err);
+			}
+		}
+
+		return dispatch(0);
+	};
+}
+
+/**
+ * Create a context object for the request
+ * @param {Request} request
+ * @param {Record<string, string>} params
+ * @returns {Context}
+ */
+export function createContext(request, params) {
+	return {
+		request,
+		params,
+		url: new URL(request.url),
+		state: new Map(),
+	};
+}
+
+/**
+ * Run middlewares with a final handler
+ * Combines global middlewares, route-level before/after, and the handler
+ *
+ * @param {Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @param {Middleware[]} beforeMiddlewares
+ * @param {() => Promise<Response>} handler
+ * @param {Middleware[]} afterMiddlewares
+ * @returns {Promise<Response>}
+ */
+export async function runMiddlewareChain(
+	context,
+	globalMiddlewares,
+	beforeMiddlewares,
+	handler,
+	afterMiddlewares = [],
+) {
+	// Combine global + before middlewares
+	const allMiddlewares = [...globalMiddlewares, ...beforeMiddlewares];
+
+	// If there are after middlewares, wrap the handler to run them
+	const wrappedHandler =
+		afterMiddlewares.length > 0
+			? async () => {
+					const response = await handler();
+					// After middlewares can inspect/modify the response
+					// but have limited ability to change it in our model
+					// We run them for side-effects (logging, etc.)
+					return runAfterMiddlewares(context, afterMiddlewares, response);
+				}
+			: handler;
+
+	const composed = compose(allMiddlewares);
+	return composed(context, wrappedHandler);
+}
+
+/**
+ * Run after middlewares with the response
+ * After middlewares run in order and can intercept/modify the response
+ *
+ * @param {Context} context
+ * @param {Middleware[]} middlewares
+ * @param {Response} response
+ * @returns {Promise<Response>}
+ */
+async function runAfterMiddlewares(context, middlewares, response) {
+	let currentResponse = response;
+
+	for (const middleware of middlewares) {
+		currentResponse = await middleware(context, async () => currentResponse);
+	}
+
+	return currentResponse;
+}

package/src/server/production.js

@@ -0,0 +1,266 @@
+/**
+ * Production server runtime for Ripple metaframework
+ * This module is used in production builds to handle SSR + API routes
+ */
+
+import { createRouter } from './router.js';
+import { createContext, runMiddlewareChain } from './middleware.js';
+
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Route} Route
+ * @typedef {import('@ripple-ts/vite-plugin').Middleware} Middleware
+ * @typedef {import('@ripple-ts/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('@ripple-ts/vite-plugin').ServerRoute} ServerRoute
+ */
+
+/**
+ * @typedef {Object} ServerManifest
+ * @property {Route[]} routes - Array of route definitions
+ * @property {Record<string, Function>} components - Map of entry path to component function
+ * @property {Record<string, Function>} layouts - Map of layout path to layout function
+ * @property {Middleware[]} middlewares - Global middlewares
+ */
+
+/**
+ * @typedef {Object} RenderResult
+ * @property {string} head
+ * @property {string} body
+ * @property {Set<string>} css
+ */
+
+/**
+ * Create a production request handler from a manifest
+ *
+ * @param {ServerManifest} manifest
+ * @param {Object} options
+ * @param {(component: Function) => Promise<RenderResult>} options.render - SSR render function
+ * @param {(css: Set<string>) => string} options.getCss - Get CSS for hashes
+ * @param {string} options.clientBase - Base path for client assets
+ * @returns {(request: Request) => Promise<Response>}
+ */
+export function createHandler(manifest, options) {
+	const { render, getCss, clientBase = '/' } = options;
+	const router = createRouter(manifest.routes);
+	const globalMiddlewares = manifest.middlewares || [];
+
+	return async function handler(request) {
+		const url = new URL(request.url);
+		const method = request.method;
+
+		// Match route
+		const match = router.match(method, url.pathname);
+
+		if (!match) {
+			return new Response('Not Found', { status: 404 });
+		}
+
+		// Create context
+		const context = createContext(request, match.params);
+
+		try {
+			if (match.route.type === 'render') {
+				return await handleRenderRoute(
+					match.route,
+					context,
+					manifest,
+					globalMiddlewares,
+					render,
+					getCss,
+					clientBase,
+				);
+			} else {
+				return await handleServerRoute(match.route, context, globalMiddlewares);
+			}
+		} catch (error) {
+			console.error('[ripple] Request error:', error);
+			return new Response('Internal Server Error', { status: 500 });
+		}
+	};
+}
+
+/**
+ * Handle a RenderRoute in production
+ *
+ * @param {RenderRoute} route
+ * @param {import('@ripple-ts/vite-plugin').Context} context
+ * @param {ServerManifest} manifest
+ * @param {Middleware[]} globalMiddlewares
+ * @param {(component: Function) => Promise<RenderResult>} render
+ * @param {(css: Set<string>) => string} getCss
+ * @param {string} clientBase
+ * @returns {Promise<Response>}
+ */
+async function handleRenderRoute(
+	route,
+	context,
+	manifest,
+	globalMiddlewares,
+	render,
+	getCss,
+	clientBase,
+) {
+	const renderHandler = async () => {
+		// Get the page component
+		const PageComponent = manifest.components[route.entry];
+		if (!PageComponent) {
+			throw new Error(`Component not found: ${route.entry}`);
+		}
+
+		// Get layout if specified
+		let RootComponent;
+		const pageProps = { params: context.params };
+
+		if (route.layout && manifest.layouts[route.layout]) {
+			const LayoutComponent = manifest.layouts[route.layout];
+			RootComponent = createLayoutWrapper(LayoutComponent, PageComponent, pageProps);
+		} else {
+			RootComponent = createPropsWrapper(PageComponent, pageProps);
+		}
+
+		// Render to HTML
+		const { head, body, css } = await render(RootComponent);
+
+		// Generate CSS tags
+		let cssContent = '';
+		if (css.size > 0) {
+			const cssString = getCss(css);
+			if (cssString) {
+				cssContent = `<style data-ripple-ssr>${cssString}</style>`;
+			}
+		}
+
+		// Generate the full HTML document
+		const html = generateHtml({
+			head: head + cssContent,
+			body,
+			route,
+			context,
+			clientBase,
+		});
+
+		return new Response(html, {
+			status: 200,
+			headers: { 'Content-Type': 'text/html; charset=utf-8' },
+		});
+	};
+
+	return runMiddlewareChain(context, globalMiddlewares, route.before || [], renderHandler, []);
+}
+
+/**
+ * Handle a ServerRoute in production
+ *
+ * @param {ServerRoute} route
+ * @param {import('@ripple-ts/vite-plugin').Context} context
+ * @param {Middleware[]} globalMiddlewares
+ * @returns {Promise<Response>}
+ */
+async function handleServerRoute(route, context, globalMiddlewares) {
+	const handler = async () => route.handler(context);
+	return runMiddlewareChain(
+		context,
+		globalMiddlewares,
+		route.before || [],
+		handler,
+		route.after || [],
+	);
+}
+
+/**
+ * Create a wrapper component that injects props
+ * @param {Function} Component
+ * @param {Record<string, unknown>} props
+ * @returns {Function}
+ */
+function createPropsWrapper(Component, props) {
+	return function WrappedComponent(/** @type {unknown} */ output, additionalProps = {}) {
+		return Component(output, { ...additionalProps, ...props });
+	};
+}
+
+/**
+ * Create a wrapper that composes a layout with a page component
+ * @param {Function} Layout
+ * @param {Function} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {Function}
+ */
+function createLayoutWrapper(Layout, Page, pageProps) {
+	return function LayoutWrapper(/** @type {unknown} */ output, additionalProps = {}) {
+		const children = (/** @type {unknown} */ childOutput) => {
+			return Page(childOutput, { ...additionalProps, ...pageProps });
+		};
+		return Layout(output, { ...additionalProps, children });
+	};
+}
+
+/**
+ * Generate the full HTML document for production
+ * @param {Object} options
+ * @param {string} options.head
+ * @param {string} options.body
+ * @param {RenderRoute} options.route
+ * @param {import('@ripple-ts/vite-plugin').Context} options.context
+ * @param {string} options.clientBase
+ * @returns {string}
+ */
+function generateHtml({ head, body, route, context, clientBase }) {
+	const routeData = JSON.stringify({
+		entry: route.entry,
+		params: context.params,
+	});
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+${head}
+</head>
+<body>
+<div id="app">${body}</div>
+<script id="__ripple_data" type="application/json">${escapeScript(routeData)}</script>
+<script type="module">
+import { hydrate, mount } from '${clientBase}ripple.js';
+
+const data = JSON.parse(document.getElementById('__ripple_data').textContent);
+const target = document.getElementById('app');
+
+try {
+  const module = await import('${clientBase}' + data.entry.replace(/^\\//, '').replace(/\\.ripple$/, '.js'));
+  const Component =
+    module.default ||
+    Object.entries(module).find(([key, value]) => typeof value === 'function' && /^[A-Z]/.test(key))?.[1];
+
+  if (!Component || !target) {
+    console.error('[ripple] Unable to hydrate route: missing component export or #app target.');
+  } else {
+    try {
+      hydrate(Component, {
+        target,
+        props: { params: data.params }
+      });
+    } catch (error) {
+      console.warn('[ripple] Hydration failed, falling back to mount.', error);
+      mount(Component, {
+        target,
+        props: { params: data.params }
+      });
+    }
+  }
+} catch (error) {
+  console.error('[ripple] Failed to bootstrap client hydration.', error);
+}
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Escape script content to prevent XSS
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeScript(str) {
+	return str.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+}

package/src/server/render-route.js

@@ -0,0 +1,239 @@
+/// <reference types="ripple/compiler/internal/rpc" />
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @typedef {import('@ripple-ts/vite-plugin').Context} Context
+ * @typedef {import('@ripple-ts/vite-plugin').RenderRoute} RenderRoute
+ * @typedef {import('vite').ViteDevServer} ViteDevServer
+ */
+
+/**
+ * @typedef {Object} RenderResult
+ * @property {string} head
+ * @property {string} body
+ * @property {Set<string>} css
+ */
+
+/**
+ * Handle SSR rendering for a RenderRoute
+ *
+ * @param {RenderRoute} route
+ * @param {Context} context
+ * @param {ViteDevServer} vite
+ * @returns {Promise<Response>}
+ */
+export async function handleRenderRoute(route, context, vite) {
+	try {
+		// Initialize so the server can register
+		// RPC functions from #server blocks during SSR module loading
+		if (!globalThis.rpc_modules) {
+			globalThis.rpc_modules = new Map();
+		}
+
+		// Load ripple server utilities
+		const { render, get_css_for_hashes } = await vite.ssrLoadModule('ripple/server');
+
+		// Load the page component
+		const pageModule = await vite.ssrLoadModule(route.entry);
+		const PageComponent = getDefaultExport(pageModule);
+
+		if (!PageComponent) {
+			throw new Error(`No default export found in ${route.entry}`);
+		}
+
+		// Build the component tree (with optional layout)
+		let RootComponent;
+		const pageProps = { params: context.params };
+
+		if (route.layout) {
+			// Load layout component
+			const layoutModule = await vite.ssrLoadModule(route.layout);
+			const LayoutComponent = getDefaultExport(layoutModule);
+
+			if (!LayoutComponent) {
+				throw new Error(`No default export found in ${route.layout}`);
+			}
+
+			// Create a wrapper that composes layout + page
+			// Layout receives children as a component prop
+			RootComponent = createLayoutWrapper(LayoutComponent, PageComponent, pageProps);
+		} else {
+			// No layout - render page directly with props
+			RootComponent = createPropsWrapper(PageComponent, pageProps);
+		}
+
+		// Render to HTML
+		/** @type {RenderResult} */
+		const { head, body, css } = await render(RootComponent);
+
+		// Generate CSS tags
+		let cssContent = '';
+		if (css.size > 0) {
+			const cssString = get_css_for_hashes(css);
+			if (cssString) {
+				cssContent = `<style data-ripple-ssr>${cssString}</style>`;
+			}
+		}
+
+		// Build head content with hydration data
+		const routeData = JSON.stringify({
+			entry: route.entry,
+			params: context.params,
+		});
+		const headContent = [
+			head,
+			cssContent,
+			`<script id="__ripple_data" type="application/json">${escapeScript(routeData)}</script>`,
+		]
+			.filter(Boolean)
+			.join('\n');
+
+		// Load and process index.html template
+		const templatePath = join(vite.config.root, 'public', 'index.html');
+		let template = await readFile(templatePath, 'utf-8');
+
+		// 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);
+
+		// Inject hydration script before </body>
+		const hydrationScript = `<script type="module" src="/@id/virtual:ripple-hydrate"></script>`;
+		html = html.replace('</body>', `${hydrationScript}\n</body>`);
+
+		return new Response(html, {
+			status: 200,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		});
+	} catch (error) {
+		console.error('[ripple] SSR render error:', error);
+
+		const errorHtml = generateErrorHtml(error, route);
+		return new Response(errorHtml, {
+			status: 500,
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+			},
+		});
+	}
+}
+
+/**
+ * Get the default export from a module
+ * Handles both `export default` and `export { X as default }`
+ *
+ * @param {Record<string, unknown>} module
+ * @returns {Function | null}
+ */
+function getDefaultExport(module) {
+	if (typeof module.default === 'function') {
+		return module.default;
+	}
+	// Look for a component-like export (capitalized function)
+	for (const [key, value] of Object.entries(module)) {
+		if (typeof value === 'function' && /^[A-Z]/.test(key)) {
+			return value;
+		}
+	}
+	return null;
+}
+
+/**
+ * Create a wrapper component that injects props
+ *
+ * @param {Function} Component
+ * @param {Record<string, unknown>} props
+ * @returns {Function}
+ */
+function createPropsWrapper(Component, props) {
+	/**
+	 * @param {unknown} output
+	 * @param {Record<string, unknown>} additionalProps
+	 */
+	return function WrappedComponent(output, additionalProps = {}) {
+		return Component(output, { ...additionalProps, ...props });
+	};
+}
+
+/**
+ * Create a wrapper that composes a layout with a page component
+ * The layout receives the page as its children prop
+ *
+ * @param {Function} Layout
+ * @param {Function} Page
+ * @param {Record<string, unknown>} pageProps
+ * @returns {Function}
+ */
+function createLayoutWrapper(Layout, Page, pageProps) {
+	/**
+	 * @param {unknown} output
+	 * @param {Record<string, unknown>} additionalProps
+	 */
+	return function LayoutWrapper(output, additionalProps = {}) {
+		// Children is a component function that renders the page
+		const children = (/** @type {unknown} */ childOutput) => {
+			return Page(childOutput, { ...additionalProps, ...pageProps });
+		};
+
+		return Layout(output, { ...additionalProps, children });
+	};
+}
+
+/**
+ * Escape script content to prevent XSS
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeScript(str) {
+	return str.replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+}
+
+/**
+ * Generate an error HTML page for development
+ *
+ * @param {unknown} error
+ * @param {RenderRoute} route
+ * @returns {string}
+ */
+function generateErrorHtml(error, route) {
+	const message = error instanceof Error ? error.message : String(error);
+	const stack = error instanceof Error ? error.stack : '';
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SSR Error</title>
+<style>
+body { font-family: system-ui, sans-serif; padding: 2rem; background: #1a1a1a; color: #fff; }
+h1 { color: #ff6b6b; }
+pre { background: #2d2d2d; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+.route { color: #888; }
+</style>
+</head>
+<body>
+<h1>SSR Render Error</h1>
+<p class="route">Route: ${route.path} → ${route.entry}</p>
+<pre>${escapeHtml(message)}</pre>
+${stack ? `<pre>${escapeHtml(stack)}</pre>` : ''}
+</body>
+</html>`;
+}
+
+/**
+ * Escape HTML entities
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+	return str
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;');
+}