vue-ssr-lite 0.0.3

package/server/SsrServer.js

@@ -0,0 +1,600 @@
+// SsrServer — the optional standalone Node server (default host of the engine).
+//
+// Ready-to-use production and development server: static assets, health and
+// readiness endpoints, host classification across SSR and SPA entries,
+// startup preflight, error shells, and graceful shutdown. The SSR rendering
+// itself goes through the separable engine (../engine), so deployments with
+// their own servers can bypass this file entirely.
+//
+// Development and production run one request pipeline; only module loading
+// and HTML transformation differ (Vite middleware vs built assets).
+
+import { createServer } from 'node:http'
+import { readFile, stat } from 'node:fs/promises'
+import { extname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import {
+	createSsrRequestHandler,
+	SSR_HTML_SECURITY_HEADERS,
+} from '../engine/SsrEngine.js'
+import {
+	SSR_MARKERS,
+	renderErrorMarkup,
+	escapeHtml,
+} from '../engine/SsrEngineHtml.js'
+import {
+	matchesSsrHostPatterns,
+	resolveSsrForwardedHost,
+	resolveSsrForwardedProtocol,
+	stripSsrHostPort,
+} from '../engine/SsrEngineHostPolicy.js'
+
+const LOCAL_HOSTS = ['localhost', '127.0.0.1', '0.0.0.0', '::1']
+
+const MIME_TYPES = {
+	'.css': 'text/css; charset=utf-8',
+	'.gif': 'image/gif',
+	'.html': 'text/html; charset=utf-8',
+	'.ico': 'image/x-icon',
+	'.jpeg': 'image/jpeg',
+	'.jpg': 'image/jpeg',
+	'.js': 'text/javascript; charset=utf-8',
+	'.json': 'application/json; charset=utf-8',
+	'.png': 'image/png',
+	'.svg': 'image/svg+xml',
+	'.txt': 'text/plain; charset=utf-8',
+	'.webp': 'image/webp',
+	'.woff': 'font/woff',
+	'.woff2': 'font/woff2',
+	'.xml': 'application/xml; charset=utf-8',
+}
+
+const parseBoolean = (value) =>
+	['1', 'true', 'yes', 'on'].includes(
+		String(value || '')
+			.trim()
+			.toLowerCase(),
+	)
+
+const parsePort = (value, fallback) => {
+	const parsed = Number(value)
+	if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) return fallback
+	return parsed
+}
+
+const resolveRootCause = (error) => {
+	let cause = error
+	while (cause instanceof Error && cause.cause) cause = cause.cause
+	return cause
+}
+
+export const SSR_RUNTIME_MANIFEST = '.vue-ssr-lite.json'
+
+/** Load serialized server options emitted by the Vite integration at build time. */
+export const loadSsrRuntimeManifest = async (clientDir) => {
+	try {
+		const raw = await readFile(resolve(clientDir, SSR_RUNTIME_MANIFEST), 'utf8')
+		return JSON.parse(raw)
+	} catch {
+		return null
+	}
+}
+
+export const createSsrServer = async (userOptions = {}) => {
+	const root = resolve(userOptions.root || process.cwd())
+	const production =
+		userOptions.mode != null
+			? userOptions.mode === 'production'
+			: process.env.NODE_ENV === 'production'
+	const clientDir = resolve(root, userOptions.clientDir || 'dist/client')
+	const logger = userOptions.logger || console
+
+	// ---- Development: Vite in middleware mode -----------------------------
+	let vite = null
+	if (!production) {
+		const { createServer: createViteServer } = await import('vite')
+		vite = await createViteServer({
+			root,
+			server: { middlewareMode: true },
+			appType: 'custom',
+			...(userOptions.vite || {}),
+		})
+	}
+
+	// ---- Options: programmatic > plugin/manifest > defaults ----------------
+	let integrationOptions = null
+	if (!production && vite) {
+		const plugin = vite.config.plugins.find((p) => p.name === 'vue-ssr-lite')
+		integrationOptions = plugin?.api?.getServerOptions?.() ?? null
+	} else if (production) {
+		integrationOptions = await loadSsrRuntimeManifest(clientDir)
+	}
+
+	const options = { ...(integrationOptions || {}), ...userOptions }
+
+	const port = parsePort(process.env.PORT ?? options.port, 4173)
+	const host = process.env.HOST || options.host || '0.0.0.0'
+	const trustProxy =
+		options.trustProxy ?? parseBoolean(process.env.SSR_TRUST_PROXY)
+	const globals = options.globals || {}
+	const headAttribute = options.headAttribute || 'data-ssr-head'
+	const cookieAllowlist = options.cookieAllowlist || []
+	const cookieDenylist = options.cookieDenylist || []
+	const serveRole = options.serveRole || 'unified'
+	const consumerRoutes = options.routes || []
+	const readinessProbes = options.readiness || []
+	const serviceName = options.serviceName || 'vue-ssr-lite'
+
+	const apps = (options.apps || []).map((app) => ({
+		type: 'ssr',
+		hosts: [],
+		...app,
+	}))
+	if (apps.length === 0) {
+		apps.push({ name: 'ssr', type: 'ssr', template: 'index.html', hosts: [] })
+	}
+	const defaultApp =
+		apps.find((app) => app.default) || apps.find((app) => app.type === 'ssr') || apps[0]
+	const ssrApp = apps.find((app) => app.type === 'ssr')
+
+	const serverEntry = options.serverEntry || 'virtual:vue-ssr-lite/server'
+	const bundlePath = resolve(root, options.bundlePath || 'dist/server/entry.mjs')
+	const renderExport = options.renderExport || 'render'
+	const readyExport = options.readyExport || 'assertReady'
+
+	let productionModule = null
+	const loadRenderModule = async () => {
+		if (production) {
+			productionModule ??= await import(pathToFileURL(bundlePath).href)
+			return productionModule
+		}
+		return vite.ssrLoadModule(serverEntry)
+	}
+
+	const loadHtmlTemplate = async (templateName, requestUrl) => {
+		let template = await readFile(
+			resolve(production ? clientDir : root, templateName),
+			'utf8',
+		)
+		if (!production) {
+			template = await vite.transformIndexHtml(requestUrl || '/', template)
+		}
+		return template
+	}
+
+	// ---- The separable engine ---------------------------------------------
+	const engine = ssrApp
+		? createSsrRequestHandler({
+				loadTemplate: (requestUrl) => loadHtmlTemplate(ssrApp.template, requestUrl),
+				loadRenderModule,
+				renderExport,
+				config: options.config,
+				globals,
+				headAttribute,
+				defaultHead: options.defaultHead || '',
+				cookieAllowlist,
+				cookieDenylist,
+				renderTimeoutMs: options.renderTimeoutMs,
+				nonce: options.security?.nonce,
+			})
+		: null
+
+	// ---- Classification ----------------------------------------------------
+	const classify = (hostname, pathname, headers) => {
+		if (typeof options.classifyRequest === 'function') {
+			const result = options.classifyRequest({ hostname, pathname, headers })
+			if (result) return result
+		}
+		const bare = stripSsrHostPort(hostname)
+		if (!bare) return 'invalid'
+		for (const app of apps) {
+			if (app.hosts?.length && matchesSsrHostPatterns(bare, app.hosts)) {
+				return app.name
+			}
+		}
+		if (LOCAL_HOSTS.includes(bare)) {
+			const localApp = apps.find((app) => app.localhost) || defaultApp
+			return localApp.name
+		}
+		return defaultApp.name
+	}
+
+	const isAppAllowed = (appName) => serveRole === 'unified' || serveRole === appName
+
+	// ---- Helpers -----------------------------------------------------------
+	const endResponse = (request, response, body = '') => {
+		response.end(request.method === 'HEAD' ? '' : body)
+	}
+
+	const sendJson = (request, response, statusCode, payload) => {
+		response.writeHead(statusCode, {
+			'content-type': 'application/json; charset=utf-8',
+			'cache-control': 'no-store',
+		})
+		endResponse(request, response, JSON.stringify(payload))
+	}
+
+	const sendText = (
+		request,
+		response,
+		statusCode,
+		body,
+		contentType = 'text/plain; charset=utf-8',
+		headers = {},
+	) => {
+		response.writeHead(statusCode, {
+			'content-type': contentType,
+			'cache-control': 'no-store',
+			...headers,
+		})
+		endResponse(request, response, body)
+	}
+
+	const isHtmlNavigation = (request, pathname) => {
+		if (request.method !== 'GET' && request.method !== 'HEAD') return false
+		if (request.headers['sec-fetch-mode'] === 'navigate') return true
+		const accept = String(request.headers.accept || '')
+		if (accept.includes('text/html')) return true
+		return (!accept || accept === '*/*') && !extname(pathname)
+	}
+
+	const serveProductionAsset = async (pathname, request, response) => {
+		try {
+			const relativePath = decodeURIComponent(pathname).replace(/^\/+/, '')
+			if (
+				relativePath === SSR_RUNTIME_MANIFEST ||
+				apps.some((app) => relativePath === app.template)
+			) {
+				return false
+			}
+			const filePath = resolve(clientDir, relativePath)
+			if (!filePath.startsWith(`${clientDir}/`)) return false
+			const info = await stat(filePath)
+			if (!info.isFile()) return false
+			const body = await readFile(filePath)
+			response.writeHead(200, {
+				'content-type': MIME_TYPES[extname(filePath)] || 'application/octet-stream',
+				'cache-control': pathname.startsWith('/assets/')
+					? 'public, max-age=31536000, immutable'
+					: 'public, max-age=3600',
+			})
+			endResponse(request, response, body)
+			return true
+		} catch {
+			return false
+		}
+	}
+
+	const runViteMiddleware = (request, response) =>
+		new Promise((resolveMiddleware, reject) => {
+			vite.middlewares(request, response, (error) => {
+				if (error) reject(error)
+				else resolveMiddleware()
+			})
+		})
+
+	const sendNavigationError = async (request, response, statusCode, appName, error) => {
+		const title = 'Application unavailable'
+		const message =
+			!production && error instanceof Error
+				? error.message
+				: 'The application could not render this page. Please try again.'
+		const custom = options.errorPage?.({
+			statusCode,
+			error,
+			appName,
+			mode: production ? 'production' : 'development',
+		})
+		if (custom) {
+			return sendText(
+				request,
+				response,
+				statusCode,
+				custom,
+				'text/html; charset=utf-8',
+				SSR_HTML_SECURITY_HEADERS,
+			)
+		}
+		const markup = renderErrorMarkup(title, message)
+		try {
+			const app = apps.find((candidate) => candidate.name === appName) || defaultApp
+			let template = await loadHtmlTemplate(app.template, request.url)
+			template = template
+				.replace(
+					SSR_MARKERS.head,
+					`<title ${headAttribute}>${escapeHtml(title)}</title><meta ${headAttribute} name="robots" content="noindex, nofollow">`,
+				)
+				.replace(SSR_MARKERS.state, '')
+				.replace(SSR_MARKERS.teleports, '')
+				// A broken bundle must not half-hydrate an error page.
+				.replace(/<script\b[^>]*type=["']module["'][^>]*>[\s\S]*?<\/script>/gi, '')
+				.replace(SSR_MARKERS.html, markup)
+			sendText(
+				request,
+				response,
+				statusCode,
+				template,
+				'text/html; charset=utf-8',
+				SSR_HTML_SECURITY_HEADERS,
+			)
+		} catch {
+			sendText(
+				request,
+				response,
+				statusCode,
+				`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="robots" content="noindex, nofollow"><title>${escapeHtml(title)}</title></head><body>${markup}</body></html>`,
+				'text/html; charset=utf-8',
+				SSR_HTML_SECURITY_HEADERS,
+			)
+		}
+	}
+
+	// ---- Preflight ---------------------------------------------------------
+	const assertTemplatesReady = async () => {
+		await Promise.all(
+			apps
+				.filter((app) => isAppAllowed(app.name))
+				.map(async (app) => {
+					const templatePath = resolve(production ? clientDir : root, app.template)
+					const info = await stat(templatePath)
+					if (!info.isFile()) {
+						throw new Error(`Required client template is missing: ${app.template}`)
+					}
+				}),
+		)
+	}
+
+	const assertRuntimeReady = async () => {
+		await assertTemplatesReady()
+		if (ssrApp && isAppAllowed(ssrApp.name)) {
+			const module = await loadRenderModule()
+			if (typeof module[renderExport] !== 'function') {
+				throw new Error('The SSR render module could not be loaded.')
+			}
+			await module[readyExport]?.()
+		}
+		for (const probe of readinessProbes) await probe()
+	}
+
+	try {
+		await assertTemplatesReady()
+		if (ssrApp && isAppAllowed(ssrApp.name)) {
+			const module = await loadRenderModule()
+			if (typeof module[renderExport] !== 'function') {
+				throw new Error('The SSR render module could not be loaded.')
+			}
+			await module[readyExport]?.()
+		}
+	} catch (error) {
+		try {
+			await vite?.close()
+		} catch {
+			// Closing a half-started Vite server must not mask the preflight error.
+		}
+		logger.error(`\n[${serviceName}] runtime preflight failed; not starting.`)
+		logger.error(resolveRootCause(error))
+		process.exit(1)
+	}
+
+	// ---- Request pipeline --------------------------------------------------
+	let shuttingDown = false
+
+	const server = createServer(async (request, response) => {
+		const startedAt = new Date().toISOString()
+		let pathname = '/'
+		let appName = defaultApp.name
+
+		try {
+			pathname = new URL(request.url || '/', 'http://internal').pathname
+
+			if (pathname === '/healthz') {
+				return sendJson(request, response, 200, {
+					status: 'ok',
+					service: serviceName,
+					runtime: serveRole,
+					timestamp: startedAt,
+				})
+			}
+			if (pathname === '/readyz') {
+				if (shuttingDown) {
+					return sendJson(request, response, 503, {
+						status: 'error',
+						service: serviceName,
+						runtime: serveRole,
+						message: 'Server is shutting down.',
+						timestamp: startedAt,
+					})
+				}
+				try {
+					await assertRuntimeReady()
+					return sendJson(request, response, 200, {
+						status: 'ok',
+						service: serviceName,
+						runtime: serveRole,
+						timestamp: startedAt,
+					})
+				} catch {
+					return sendJson(request, response, 503, {
+						status: 'error',
+						service: serviceName,
+						runtime: serveRole,
+						timestamp: startedAt,
+					})
+				}
+			}
+
+			const incomingHost = resolveSsrForwardedHost(
+				request.headers['x-forwarded-host'],
+				request.headers.host,
+				trustProxy,
+			)
+			appName = classify(incomingHost, pathname, request.headers)
+			if (appName === 'invalid' || !incomingHost) {
+				if (isHtmlNavigation(request, pathname)) {
+					return sendNavigationError(
+						request,
+						response,
+						400,
+						defaultApp.name,
+						new Error('The request Host header is invalid.'),
+					)
+				}
+				return sendJson(request, response, 400, {
+					status: 'error',
+					service: serviceName,
+					message: 'Invalid Host header.',
+					timestamp: startedAt,
+				})
+			}
+			if (!isAppAllowed(appName)) {
+				const message = `This ${serveRole} runtime does not serve ${appName} hosts.`
+				if (isHtmlNavigation(request, pathname)) {
+					return sendText(
+						request,
+						response,
+						421,
+						`<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="robots" content="noindex, nofollow"><title>Misdirected request</title></head><body>${renderErrorMarkup('Misdirected request', message)}</body></html>`,
+						'text/html; charset=utf-8',
+						SSR_HTML_SECURITY_HEADERS,
+					)
+				}
+				return sendJson(request, response, 421, {
+					status: 'error',
+					service: serviceName,
+					runtime: serveRole,
+					message,
+					timestamp: startedAt,
+				})
+			}
+
+			const protocol = resolveSsrForwardedProtocol(
+				request.headers['x-forwarded-proto'],
+				request.socket.encrypted ? 'https' : 'http',
+				trustProxy,
+			)
+
+			// Consumer endpoints (SEO resources, proxies, …) run after host
+			// classification and before asset handling, mirroring the audited
+			// ERP pipeline.
+			for (const route of consumerRoutes) {
+				if (!route.match(pathname, { appName, host: incomingHost, protocol })) {
+					continue
+				}
+				await route.handle(request, response, {
+					appName,
+					host: incomingHost,
+					protocol,
+					pathname,
+					config: options.config,
+					loadRenderModule,
+					sendJson: (statusCode, payload) =>
+						sendJson(request, response, statusCode, payload),
+					sendText: (statusCode, body, contentType, headers) =>
+						sendText(request, response, statusCode, body, contentType, headers),
+				})
+				if (response.writableEnded) return
+			}
+
+			if (production && (await serveProductionAsset(pathname, request, response))) {
+				return
+			}
+			if (
+				!production &&
+				(pathname.startsWith('/src/') ||
+					pathname.startsWith('/@') ||
+					pathname.includes('.') ||
+					pathname === '/__vite_ping')
+			) {
+				await runViteMiddleware(request, response)
+				if (response.writableEnded) return
+			}
+
+			if (!isHtmlNavigation(request, pathname)) {
+				return sendJson(request, response, 404, {
+					status: 'error',
+					service: serviceName,
+					message: 'Resource not found.',
+					timestamp: startedAt,
+				})
+			}
+
+			const app = apps.find((candidate) => candidate.name === appName) || defaultApp
+
+			if (app.type === 'spa') {
+				const template = await loadHtmlTemplate(app.template, request.url)
+				response.writeHead(200, {
+					'content-type': 'text/html; charset=utf-8',
+					'cache-control': 'private, no-store',
+					vary: 'Host, X-Forwarded-Host',
+					...SSR_HTML_SECURITY_HEADERS,
+				})
+				return endResponse(
+					request,
+					response,
+					template.replace(SSR_MARKERS.html, ''),
+				)
+			}
+
+			const result = await engine.handle({
+				url: request.url || '/',
+				host: incomingHost,
+				protocol,
+				cookieHeader: request.headers.cookie,
+			})
+			response.writeHead(result.statusCode, result.headers)
+			endResponse(request, response, result.html)
+		} catch (error) {
+			vite?.ssrFixStacktrace(error)
+			logger.error(error)
+			if (response.writableEnded) return
+			if (response.headersSent) {
+				response.destroy()
+				return
+			}
+			if (isHtmlNavigation(request, pathname)) {
+				return sendNavigationError(request, response, 500, appName, error)
+			}
+			sendJson(request, response, 500, {
+				status: 'error',
+				service: serviceName,
+				timestamp: startedAt,
+			})
+		}
+	})
+
+	// ---- Lifecycle ---------------------------------------------------------
+	const shutdown = async () => {
+		if (shuttingDown) return
+		shuttingDown = true
+		const forcedExit = setTimeout(() => process.exit(1), 10_000)
+		forcedExit.unref()
+		try {
+			await Promise.all([
+				new Promise((resolveClose, rejectClose) => {
+					server.close((error) => {
+						if (error) rejectClose(error)
+						else resolveClose()
+					})
+				}),
+				vite?.close(),
+			])
+			clearTimeout(forcedExit)
+			process.exit(0)
+		} catch (error) {
+			logger.error(`[${serviceName}] Graceful shutdown failed.`, error)
+			process.exit(1)
+		}
+	}
+	process.once('SIGINT', () => void shutdown())
+	process.once('SIGTERM', () => void shutdown())
+
+	const listen = () =>
+		new Promise((resolveListen) => {
+			server.listen(port, host, () => {
+				logger.log(`${serviceName} (${serveRole}) listening on ${host}:${port}`)
+				resolveListen({ server, port, host })
+			})
+		})
+
+	return { server, vite, listen, shutdown, options }
+}

package/server/index.d.ts

@@ -0,0 +1,91 @@
+import type { Server } from 'node:http'
+import type { SsrEngineRequest } from '../engine/index'
+
+export * from '../engine/index'
+
+export interface SsrServerApp {
+	name: string
+	type?: 'ssr' | 'spa'
+	template: string
+	hosts?: string[]
+	default?: boolean
+	localhost?: boolean
+}
+
+export interface SsrServerRoute {
+	match: (
+		pathname: string,
+		info: { appName: string; host: string; protocol: string },
+	) => boolean
+	handle: (
+		request: import('node:http').IncomingMessage,
+		response: import('node:http').ServerResponse,
+		tools: {
+			appName: string
+			host: string
+			protocol: string
+			pathname: string
+			config?: Record<string, unknown>
+			loadRenderModule: () => Promise<Record<string, unknown>>
+			sendJson: (statusCode: number, payload: unknown) => void
+			sendText: (
+				statusCode: number,
+				body: string,
+				contentType?: string,
+				headers?: Record<string, string>,
+			) => void
+		},
+	) => Promise<void> | void
+}
+
+export interface SsrServerOptions {
+	root?: string
+	mode?: 'development' | 'production'
+	port?: number
+	host?: string
+	trustProxy?: boolean
+	apps?: SsrServerApp[]
+	serverEntry?: string
+	bundlePath?: string
+	clientDir?: string
+	renderExport?: string
+	readyExport?: string
+	config?: Record<string, unknown>
+	globals?: { configKey?: string; stateKey?: string }
+	headAttribute?: string
+	defaultHead?: string
+	cookieAllowlist?: string[]
+	cookieDenylist?: string[]
+	classifyRequest?: (info: {
+		hostname: string
+		pathname: string
+		headers: Record<string, string | string[] | undefined>
+	}) => string | undefined
+	serveRole?: string
+	routes?: SsrServerRoute[]
+	readiness?: Array<() => Promise<void> | void>
+	errorPage?: (info: {
+		statusCode: number
+		error: unknown
+		appName: string
+		mode: 'development' | 'production'
+	}) => string | null | undefined
+	renderTimeoutMs?: number
+	security?: { nonce?: (request: SsrEngineRequest) => string | undefined }
+	serviceName?: string
+	logger?: Pick<Console, 'log' | 'warn' | 'error'>
+	vite?: Record<string, unknown>
+}
+
+export declare const SSR_RUNTIME_MANIFEST: string
+export declare const loadSsrRuntimeManifest: (
+	clientDir: string,
+) => Promise<Record<string, unknown> | null>
+
+export declare const createSsrServer: (options?: SsrServerOptions) => Promise<{
+	server: Server
+	vite: unknown
+	listen: () => Promise<{ server: Server; port: number; host: string }>
+	shutdown: () => Promise<void>
+	options: SsrServerOptions
+}>

package/server/index.js

@@ -0,0 +1,14 @@
+export {
+	createSsrServer,
+	loadSsrRuntimeManifest,
+	SSR_RUNTIME_MANIFEST,
+} from './SsrServer.js'
+// The engine is separable from the standalone server: custom Node servers,
+// Express-style frameworks, tests, and serverless deployments consume it
+// directly (also available from 'vue-ssr-lite/engine').
+export {
+	createSsrRequestHandler,
+	SSR_HTML_SECURITY_HEADERS,
+} from '../engine/SsrEngine.js'
+export * from '../engine/SsrEngineHtml.js'
+export * from '../engine/SsrEngineHostPolicy.js'