@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

package/src/adapters/shared/server-route-handler.ts

@@ -0,0 +1,153 @@
+import type { IHmrManager } from '../../types/public-types.ts';
+import type { RouteRegistry } from '../../router/server/route-registry.ts';
+import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.ts';
+import type { FileSystemResponseMatcher } from './fs-server-response-matcher.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import { HttpError } from '../../errors/http-error.ts';
+import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from './hmr-html-response.ts';
+
+/**
+ * Configuration parameters for ServerRouteHandler.
+ */
+export interface ServerRouteHandlerParams {
+	/** File system router for matching request URLs to route handlers. */
+	router: RouteRegistry;
+	/** Matcher for handling file system route responses. */
+	fileSystemResponseMatcher: FileSystemResponseMatcher;
+	/** Optional matcher for explicit static routes like processed images or sitemaps. */
+	explicitStaticRouteMatcher?: ExplicitStaticRouteMatcher;
+	/** Enable watch mode for development. */
+	watch?: boolean;
+	/** HMR manager for broadcasting hot module reload events in development. */
+	hmrManager?: IHmrManager;
+}
+
+/**
+ * Handles HTTP requests and routing for the server.
+ *
+ * This class manages the request routing flow with a priority-based approach:
+ * 1. Explicit static routes (highest priority - intentional mappings like /sitemap.xml)
+ * 2. File-based routes without extensions (application routes)
+ * 3. Static file fallback (lowest priority - disk serving)
+ *
+ * In development mode, it also injects HMR scripts into HTML responses.
+ */
+export class ServerRouteHandler {
+	private readonly router: RouteRegistry;
+	private readonly fileSystemResponseMatcher: FileSystemResponseMatcher;
+	private readonly explicitStaticRouteMatcher?: ExplicitStaticRouteMatcher;
+	private readonly watch: boolean;
+	private readonly hmrManager?: IHmrManager;
+
+	/**
+	 * Creates a new ServerRouteHandler instance.
+	 *
+	 * @param params - Configuration parameters
+	 */
+	constructor({
+		router,
+		fileSystemResponseMatcher,
+		explicitStaticRouteMatcher,
+		watch = false,
+		hmrManager,
+	}: ServerRouteHandlerParams) {
+		this.router = router;
+		this.fileSystemResponseMatcher = fileSystemResponseMatcher;
+		this.explicitStaticRouteMatcher = explicitStaticRouteMatcher;
+		this.watch = watch;
+		this.hmrManager = hmrManager;
+	}
+
+	/**
+	 * Determines if HMR script should be injected.
+	 *
+	 * @returns true if in watch mode and HMR manager is enabled
+	 */
+	shouldInjectHmrScript(): boolean {
+		return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager);
+	}
+
+	/**
+	 * Checks if a response contains HTML content.
+	 *
+	 * @param response - The HTTP response to check
+	 * @returns true if Content-Type header starts with 'text/html'
+	 */
+	isHtmlResponse(response: Response): boolean {
+		return isHtmlResponse(response);
+	}
+
+	/**
+	 * Handles HTTP requests from the router adapter.
+	 *
+	 * Priority-based routing flow:
+	 * 1. Check explicit static routes first (e.g., /sitemap.xml, /image.webp from plugins)
+	 * 2. Match file-based routes without extensions (application routes)
+	 * 3. Fall back to static file serving from disk
+	 *
+	 * @param request - The incoming HTTP request
+	 * @returns HTTP response, potentially with injected HMR script in dev mode
+	 */
+	async handleResponse(request: Request): Promise<Response> {
+		const pathname = new URL(request.url).pathname;
+
+		const explicitMatch = this.explicitStaticRouteMatcher?.match(request.url);
+
+		if (explicitMatch) {
+			const response = await this.explicitStaticRouteMatcher!.handleMatch(explicitMatch);
+			return this.maybeInjectHmrScript(response);
+		}
+
+		const fsMatch = !pathname.includes('.') && this.router.matchRequest(request.url);
+
+		const response = await (fsMatch
+			? this.fileSystemResponseMatcher.handleMatch(fsMatch, request)
+			: this.handleNoMatch(request));
+
+		return this.maybeInjectHmrScript(response);
+	}
+
+	/**
+	 * Injects HMR script into HTML responses in development mode.
+	 *
+	 * The script is inserted before the closing </html> tag to enable
+	 * hot module reloading without full page refreshes.
+	 *
+	 * @param response - The HTTP response to potentially modify
+	 * @returns Original response or modified response with HMR script
+	 */
+	private async maybeInjectHmrScript(response: Response): Promise<Response> {
+		if (this.shouldInjectHmrScript() && this.isHtmlResponse(response)) {
+			return injectHmrRuntimeIntoHtmlResponse(response);
+		}
+
+		return response;
+	}
+
+	/**
+	 * Handles requests that do not match any routes.
+	 *
+	 * This is the final fallback that attempts to serve static files from disk.
+	 * If the requested path corresponds to an HTML file or no file is found,
+	 * a custom 404 response is returned.
+	 *
+	 * @param request - The HTTP request to handle
+	 * @returns Response from file system or error response
+	 * @throws HttpError for standard HTTP errors
+	 */
+	async handleNoMatch(request: Request): Promise<Response> {
+		try {
+			const pathname = new URL(request.url).pathname;
+			return await this.fileSystemResponseMatcher.handleNoMatch(pathname);
+		} catch (error) {
+			if (error instanceof HttpError) {
+				return error.toResponse();
+			}
+			if (error instanceof Error) {
+				this.hmrManager?.broadcast({ type: 'error', message: error.message });
+				appLogger.error('Error handling no match:', error);
+			}
+			return new Response('Internal Server Error', { status: 500 });
+		}
+	}
+}

package/src/adapters/shared/server-static-builder.test.ts

@@ -0,0 +1,338 @@
+import assert from 'node:assert/strict';
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import {
+	ServerStaticBuilder,
+	type ServeOptions,
+	type ServerStaticBuilderLogger,
+	type ServerStaticPreviewServerFactory,
+} from './server-static-builder';
+import type { EcoPagesAppConfig } from '../../types/internal-types';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator';
+import type { RouteRegistry } from '../../router/server/route-registry';
+import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const TMP_DIR = path.join(os.tmpdir(), 'server-static-builder-test');
+
+function createMockDependencies() {
+	const calls = {
+		staticSiteGeneratorRun: [] as Array<unknown>,
+		integrationSetup: 0,
+		processorSetup: 0,
+		warn: [] as Array<[string, string | undefined]>,
+		info: [] as string[],
+		error: [] as string[],
+		createServer: [] as Array<{
+			appConfig: EcoPagesAppConfig;
+			options: { port: number };
+		}>,
+	};
+
+	const StaticSiteGenerator = {
+		run: async (options: unknown) => {
+			calls.staticSiteGeneratorRun.push(options);
+		},
+	} as unknown as StaticSiteGenerator;
+
+	const mockIntegration = {
+		setup: async () => {
+			calls.integrationSetup += 1;
+		},
+	} as any;
+
+	const mockProcessor = {
+		setup: async () => {
+			calls.processorSetup += 1;
+			fs.mkdirSync(path.join(TMP_DIR, 'dist', 'images'), { recursive: true });
+			fs.writeFileSync(path.join(TMP_DIR, 'dist', 'images', 'processor.webp'), 'processor-output');
+		},
+	} as any;
+
+	const AppConfig = {
+		rootDir: TMP_DIR,
+		srcDir: 'src',
+		publicDir: 'public',
+		distDir: 'dist',
+		integrations: [mockIntegration],
+		processors: new Map([['image-processor', mockProcessor]]),
+		absolutePaths: {
+			distDir: path.join(TMP_DIR, 'dist'),
+			workDir: path.join(TMP_DIR, '.eco'),
+		} as EcoPagesAppConfig['absolutePaths'],
+	} as unknown as EcoPagesAppConfig;
+
+	const ServeOptions: ServeOptions = {
+		hostname: 'localhost',
+		port: 3000,
+	};
+
+	const Router = {} as RouteRegistry;
+	const RouteRendererFactory = {} as StaticGenerationRendererResolver;
+	const logger: ServerStaticBuilderLogger = {
+		warn: (message: string, detail?: string) => {
+			calls.warn.push([message, detail]);
+		},
+		info: (message: string) => {
+			calls.info.push(message);
+		},
+		error: (message: string) => {
+			calls.error.push(message);
+		},
+	};
+	const previewServerFactory: ServerStaticPreviewServerFactory = {
+		createServer: ({ appConfig, options }) => {
+			calls.createServer.push({ appConfig, options });
+			return {
+				server: { port: 3000 },
+			};
+		},
+	};
+
+	return {
+		calls,
+		StaticSiteGenerator,
+		AppConfig,
+		mockIntegration,
+		mockProcessor,
+		logger,
+		previewServerFactory,
+		ServeOptions,
+		Router,
+		RouteRendererFactory,
+		ApiHandlers: [],
+	};
+}
+
+describe('ServerStaticBuilder', () => {
+	beforeAll(() => {
+		fs.mkdirSync(TMP_DIR, { recursive: true });
+	});
+
+	afterAll(() => {
+		fs.rmSync(TMP_DIR, { recursive: true, force: true });
+	});
+
+	it('should warn when API handlers are registered for static build modes', async () => {
+		const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+			createMockDependencies();
+
+		const builder = new ServerStaticBuilder({
+			appConfig: AppConfig,
+			staticSiteGenerator: StaticSiteGenerator,
+			serveOptions: ServeOptions,
+			logger,
+			apiHandlers: [
+				{ method: 'GET', path: '/api/auth/*', handler: () => undefined } as any,
+				{ method: 'POST', path: '/api/auth/*', handler: () => undefined } as any,
+			],
+		});
+
+		await builder.build(undefined, {
+			router: Router,
+			routeRendererFactory: RouteRendererFactory,
+		});
+
+		assert.deepEqual(calls.warn, [
+			[
+				'Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n',
+				'➤ GET /api/auth/*, POST /api/auth/*',
+			],
+		]);
+	});
+
+	describe('constructor', () => {
+		it('should create instance with provided options', () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, logger, previewServerFactory } =
+				createMockDependencies();
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+				previewServerFactory,
+			});
+			expect(builder).toBeDefined();
+		});
+	});
+
+	describe('build', () => {
+		it('should run static site generator with correct options', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.deepEqual(calls.staticSiteGeneratorRun, [
+				{
+					router: Router,
+					baseUrl: 'http://localhost:3000',
+					routeRendererFactory: RouteRendererFactory,
+					staticRoutes: undefined,
+				},
+			]);
+		});
+
+		it('should handle custom serve options for base URL', async () => {
+			const { AppConfig, StaticSiteGenerator, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const customServeOptions: ServeOptions = {
+				hostname: '0.0.0.0',
+				port: 8080,
+			};
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: customServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.equal((calls.staticSiteGeneratorRun[0] as { baseUrl: string }).baseUrl, 'http://0.0.0.0:8080');
+		});
+
+		it('should allow build-time base URL overrides', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(
+				{ baseUrl: 'http://localhost:41731' },
+				{
+					router: Router,
+					routeRendererFactory: RouteRendererFactory,
+				},
+			);
+
+			assert.equal((calls.staticSiteGeneratorRun[0] as { baseUrl: string }).baseUrl, 'http://localhost:41731');
+		});
+
+		it('should start preview server when preview option is true', async () => {
+			const {
+				AppConfig,
+				StaticSiteGenerator,
+				ServeOptions,
+				Router,
+				RouteRendererFactory,
+				logger,
+				previewServerFactory,
+				calls,
+			} = createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+				previewServerFactory,
+			});
+
+			await builder.build(
+				{ preview: true },
+				{
+					router: Router,
+					routeRendererFactory: RouteRendererFactory,
+				},
+			);
+
+			assert.deepEqual(calls.createServer, [
+				{
+					appConfig: AppConfig,
+					options: { port: 3000 },
+				},
+			]);
+		});
+
+		it('should rebuild integration runtime assets after resetting the export directory', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.equal(calls.integrationSetup, 1);
+		});
+
+		it('should rebuild processor-owned assets after resetting the export directory', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger, calls } =
+				createMockDependencies();
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			assert.equal(calls.processorSetup, 1);
+			assert.equal(
+				fs.readFileSync(path.join(TMP_DIR, 'dist', 'images', 'processor.webp'), 'utf8'),
+				'processor-output',
+			);
+		});
+
+		it('should reset stale export contents before regenerating the public output', async () => {
+			const { AppConfig, StaticSiteGenerator, ServeOptions, Router, RouteRendererFactory, logger } =
+				createMockDependencies();
+
+			const publicDir = path.join(TMP_DIR, 'src', 'public');
+			const distDir = AppConfig.absolutePaths.distDir;
+			fs.mkdirSync(publicDir, { recursive: true });
+			fs.mkdirSync(path.join(distDir, '.server-modules-meta'), { recursive: true });
+			fs.writeFileSync(path.join(publicDir, 'site.css'), 'body { color: red; }');
+			fs.writeFileSync(path.join(distDir, '.server-modules-meta', 'stale.js'), 'stale');
+
+			const builder = new ServerStaticBuilder({
+				appConfig: AppConfig,
+				staticSiteGenerator: StaticSiteGenerator,
+				serveOptions: ServeOptions,
+				logger,
+			});
+
+			await builder.build(undefined, {
+				router: Router,
+				routeRendererFactory: RouteRendererFactory,
+			});
+
+			expect(fs.existsSync(path.join(distDir, '.server-modules-meta'))).toBe(false);
+			expect(fs.readFileSync(path.join(distDir, 'site.css'), 'utf8')).toBe('body { color: red; }');
+		});
+	});
+});

package/src/adapters/shared/server-static-builder.ts

@@ -0,0 +1,170 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.ts';
+import { StaticContentServer } from '../../dev/sc-server.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { ApiHandler, StaticRoute } from '../../types/public-types.ts';
+import type { RouteRegistry } from '../../router/server/route-registry.ts';
+import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.ts';
+import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.ts';
+
+export interface StaticBuildOptions {
+	preview?: boolean;
+	baseUrl?: string;
+}
+
+export interface ServeOptions {
+	hostname?: string;
+	port?: number | string;
+}
+
+export interface ServerStaticBuilderParams {
+	appConfig: EcoPagesAppConfig;
+	staticSiteGenerator: StaticSiteGenerator;
+	serveOptions: ServeOptions;
+	apiHandlers?: ApiHandler[];
+	logger?: ServerStaticBuilderLogger;
+	previewServerFactory?: ServerStaticPreviewServerFactory;
+}
+
+/**
+ * Minimal logger dependency used by the static builder.
+ */
+export interface ServerStaticBuilderLogger {
+	warn(message: string, detail?: string): unknown;
+	info(message: string): unknown;
+	error(message: string): unknown;
+}
+
+/**
+ * Preview server factory dependency used when static preview mode is enabled.
+ */
+export interface ServerStaticPreviewServerFactory {
+	createServer(args: { appConfig: EcoPagesAppConfig; options: { port: number } }): {
+		server?: {
+			port?: number;
+		} | null;
+	};
+}
+
+/**
+ * Handles static site generation and previews.
+ */
+export class ServerStaticBuilder {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly staticSiteGenerator: StaticSiteGenerator;
+	private readonly serveOptions: ServeOptions;
+	private readonly apiHandlers: ApiHandler[];
+	private readonly logger: ServerStaticBuilderLogger;
+	private readonly previewServerFactory: ServerStaticPreviewServerFactory;
+
+	constructor({
+		appConfig,
+		staticSiteGenerator,
+		serveOptions,
+		apiHandlers,
+		logger,
+		previewServerFactory,
+	}: ServerStaticBuilderParams) {
+		this.appConfig = appConfig;
+		this.staticSiteGenerator = staticSiteGenerator;
+		this.serveOptions = serveOptions;
+		this.apiHandlers = apiHandlers ?? [];
+		this.logger = logger ?? appLogger;
+		this.previewServerFactory = previewServerFactory ?? StaticContentServer;
+	}
+
+	private warnApiHandlersUnavailableInStaticMode(): void {
+		if (this.apiHandlers.length === 0) {
+			return;
+		}
+
+		const uniqueHandlers = Array.from(
+			new Set(this.apiHandlers.map((handler) => `${handler.method} ${handler.path}`)),
+		);
+		const visibleHandlers = uniqueHandlers.slice(0, 5).join(', ');
+		const remainingCount = uniqueHandlers.length - Math.min(uniqueHandlers.length, 5);
+		const summary = remainingCount > 0 ? `${visibleHandlers}, +${remainingCount} more` : visibleHandlers;
+
+		this.logger.warn(
+			'Registered API endpoints are not available in static build or preview modes because no server runtime is started. They are excluded from the generated output.\n',
+			`➤ ${summary}`,
+		);
+	}
+
+	private prepareExportDirectory(): void {
+		const exportDir =
+			this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
+		fileSystem.ensureDir(exportDir, true);
+
+		const srcPublicDir = path.join(
+			this.appConfig.rootDir,
+			this.appConfig.srcDir ?? 'src',
+			this.appConfig.publicDir ?? 'public',
+		);
+		if (fileSystem.exists(srcPublicDir)) {
+			fileSystem.copyDir(srcPublicDir, exportDir);
+		}
+	}
+
+	private async refreshRuntimeAssets(): Promise<void> {
+		for (const processor of this.appConfig.processors.values()) {
+			await processor.setup();
+		}
+
+		for (const integration of this.appConfig.integrations) {
+			await integration.setup();
+		}
+	}
+
+	/**
+	 * Generates a static build of the site for deployment.
+	 * @param options.preview - If true, starts a preview server after build
+	 * @param dependencies.router - The initialized router
+	 * @param dependencies.routeRendererFactory - The route renderer factory
+	 * @param dependencies.staticRoutes - Explicit static routes registered via app.static()
+	 */
+	async build(
+		options: StaticBuildOptions | undefined,
+		dependencies: {
+			router: RouteRegistry;
+			routeRendererFactory: StaticGenerationRendererResolver;
+			staticRoutes?: StaticRoute[];
+		},
+	): Promise<void> {
+		const { preview = false, baseUrl: explicitBaseUrl } = options ?? {};
+
+		const baseUrl =
+			explicitBaseUrl ??
+			`http://${this.serveOptions.hostname || DEFAULT_ECOPAGES_HOSTNAME}:${this.serveOptions.port || DEFAULT_ECOPAGES_PORT}`;
+		this.warnApiHandlersUnavailableInStaticMode();
+		this.prepareExportDirectory();
+		await this.refreshRuntimeAssets();
+
+		await this.staticSiteGenerator.run({
+			router: dependencies.router,
+			baseUrl,
+			routeRendererFactory: dependencies.routeRendererFactory,
+			staticRoutes: dependencies.staticRoutes,
+		});
+
+		if (!preview) {
+			this.logger.info('Build completed');
+			return;
+		}
+
+		const previewPort = this.serveOptions.port || DEFAULT_ECOPAGES_PORT;
+
+		const { server } = this.previewServerFactory.createServer({
+			appConfig: this.appConfig,
+			options: { port: Number(previewPort) },
+		});
+
+		if (server?.port) {
+			this.logger.info(`Preview running at http://localhost:${server.port}`);
+		} else {
+			this.logger.error('Failed to start preview server');
+		}
+	}
+}