@ecopages/core 0.2.0-alpha.8 → 0.2.1-beta.0

package/src/adapters/shared/server-adapter.ts

@@ -1,489 +0,0 @@
-import path from 'node:path';
-import { AbstractServerAdapter } from '../abstract/server-adapter.ts';
-import type { ServerAdapterOptions, ServerAdapterResult } from '../abstract/server-adapter.ts';
-import { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
-import { FSRouter } from '../../router/server/fs-router.ts';
-import { FSRouterScanner } from '../../router/server/fs-router-scanner.ts';
-import { MemoryCacheStore } from '../../services/cache/memory-cache-store.ts';
-import { PageCacheService } from '../../services/cache/page-cache-service.ts';
-import { SchemaValidationService } from '../../services/validation/schema-validation-service.ts';
-import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.ts';
-import { ServerStaticBuilder } from './server-static-builder.ts';
-import { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.ts';
-import { FileSystemServerResponseFactory } from './fs-server-response-factory.ts';
-import { FileSystemResponseMatcher } from './fs-server-response-matcher.ts';
-import { ServerRouteHandler } from './server-route-handler.ts';
-import { createRenderContext } from './render-context.ts';
-import { createRequire } from '../../utils/locals-utils.ts';
-import { HttpError } from '../../errors/http-error.ts';
-import { ApiResponseBuilder } from './api-response.ts';
-import { appLogger } from '../../global/app-logger.ts';
-import { fileSystem } from '@ecopages/file-system';
-import type {
-	ApiHandler,
-	ApiHandlerContext,
-	CacheInvalidator,
-	ErrorHandler,
-	RenderContext,
-	StaticRoute,
-} from '../../public-types.ts';
-
-export abstract class SharedServerAdapter<
-	TOptions extends ServerAdapterOptions,
-	TResult extends ServerAdapterResult,
-> extends AbstractServerAdapter<TOptions, TResult> {
-	protected router!: FSRouter;
-	protected fileSystemResponseMatcher!: FileSystemResponseMatcher;
-	protected routeRendererFactory!: RouteRendererFactory;
-	protected routeHandler!: ServerRouteHandler;
-	protected staticSiteGenerator!: StaticSiteGenerator;
-	protected staticBuilder!: ServerStaticBuilder;
-	protected readonly schemaValidator = new SchemaValidationService();
-
-	protected async initializeSharedRouteHandling(options: {
-		staticRoutes: StaticRoute[];
-		hmrManager?: any;
-	}): Promise<void> {
-		await this.initSharedRouter();
-		this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
-	}
-
-	protected createSharedWatchRefreshCallback(options: {
-		staticRoutes: StaticRoute[];
-		hmrManager?: any;
-		onRoutesReady?: () => Promise<void> | void;
-		onError?: (error: Error) => Promise<void> | void;
-	}): () => Promise<void> {
-		return async () => {
-			try {
-				await this.initializeSharedRouteHandling({
-					staticRoutes: options.staticRoutes,
-					hmrManager: options.hmrManager,
-				});
-
-				if (options.onRoutesReady) {
-					await options.onRoutesReady();
-				}
-			} catch (error) {
-				if (options.onError) {
-					await options.onError(error instanceof Error ? error : new Error(String(error)));
-					return;
-				}
-
-				throw error;
-			}
-		};
-	}
-
-	/**
-	 * Scans the filesystem and dynamically constructs the universal router map.
-	 *
-	 * This process runs identically across both Bun and Node wrappers. It analyzes the configured pages
-	 * directory, building a map of all available UI routes and API endpoints.
-	 * The resulting `FSRouter` instance becomes the central nervous system for mapping WinterCG incoming
-	 * Web Requests (`Request`) to their corresponding internal execution paths.
-	 */
-	protected async initSharedRouter(): Promise<void> {
-		const scanner = new FSRouterScanner({
-			dir: path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.pagesDir),
-			appConfig: this.appConfig,
-			origin: this.runtimeOrigin,
-			templatesExt: this.appConfig.templatesExt,
-			options: {
-				buildMode: !this.options?.watch,
-			},
-		});
-
-		this.router = new FSRouter({
-			origin: this.runtimeOrigin,
-			assetPrefix: path.join(this.appConfig.rootDir, this.appConfig.distDir),
-			scanner,
-		});
-
-		await this.router.init();
-	}
-
-	/**
-	 * Sets up the unified rendering pipeline and response matching chain.
-	 *
-	 * It bridges several sub-systems together so that when an incoming request is received, the adapter knows:
-	 * 1. How to render React/Lit pages via `RouteRendererFactory`
-	 * 2. How to match logical routes to physical filesystem artifacts via `FileSystemResponseMatcher`
-	 * 3. Whether to serve the response from the embedded `PageCacheService` or generate it fresh on the fly.
-	 *
-	 * Because `HmrManager` implementations rely heavily on runtime-specific WebSocket APIs (e.g. Bun.serve Websockets vs Node WS),
-	 * we leave it untyped (`any`) here at the common denominator core.
-	 *
-	 * @param staticRoutes - A map of explicitly served static assets.
-	 * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
-	 */
-	protected configureSharedResponseHandlers(staticRoutes: StaticRoute[], hmrManager?: any): void {
-		this.routeRendererFactory = new RouteRendererFactory({
-			appConfig: this.appConfig,
-			runtimeOrigin: this.runtimeOrigin,
-		});
-
-		const fileSystemResponseFactory = new FileSystemServerResponseFactory({
-			appConfig: this.appConfig,
-			routeRendererFactory: this.routeRendererFactory,
-			options: {
-				watchMode: !!this.options?.watch,
-			},
-		});
-
-		const cacheConfig = this.appConfig.cache;
-		const isCacheEnabled = cacheConfig?.enabled ?? !this.options?.watch;
-		let cacheService: PageCacheService | null = null;
-
-		if (isCacheEnabled) {
-			const store =
-				cacheConfig?.store === 'memory' || !cacheConfig?.store
-					? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries })
-					: cacheConfig.store;
-			cacheService = new PageCacheService({ store, enabled: true });
-		}
-
-		this.fileSystemResponseMatcher = new FileSystemResponseMatcher({
-			appConfig: this.appConfig,
-			router: this.router,
-			routeRendererFactory: this.routeRendererFactory,
-			fileSystemResponseFactory,
-			cacheService,
-			defaultCacheStrategy: cacheConfig?.defaultStrategy ?? 'static',
-		});
-
-		const explicitStaticRouteMatcher =
-			staticRoutes.length > 0
-				? new ExplicitStaticRouteMatcher({
-						appConfig: this.appConfig,
-						routeRendererFactory: this.routeRendererFactory,
-						staticRoutes,
-					})
-				: undefined;
-
-		this.routeHandler = new ServerRouteHandler({
-			router: this.router,
-			fileSystemResponseMatcher: this.fileSystemResponseMatcher,
-			explicitStaticRouteMatcher,
-			watch: !!this.options?.watch,
-			hmrManager,
-		});
-	}
-
-	protected getCacheService(): CacheInvalidator | null {
-		return this.fileSystemResponseMatcher?.getCacheService() ?? null;
-	}
-
-	protected getRenderContext(): RenderContext {
-		return createRenderContext({ integrations: this.appConfig.integrations });
-	}
-
-	/**
-	 * Executes an Application Programming Interface (API) handler in an environment-agnostic manner.
-	 *
-	 * API routes in Ecopages are universally written using standard WinterCG `Request` and `Response` objects.
-	 * This execution pipeline takes the raw `Request`, extracts its dynamic segments, runs our high-speed JSON schema
-	 * validator against the body/query/headers, and triggers the developer's middleware chain sequentially.
-	 *
-	 * If the execution throws an error, it is gracefully caught, logged, and mutated into a standardized Http error payload,
-	 * ensuring the consuming client receives a parsable response even upon internal catastrophic failure.
-	 *
-	 * @param request - The incoming Web standard `Request`.
-	 * @param params - The extracted dynamic URL parameters (e.g., `{ id: '123' }`).
-	 * @param routeConfig - The user-defined API handler object containing their business logic (`handler`) and `middleware`.
-	 * @param serverInstance - Untyped reference to the underlying native server instance (BunServer/NodeServer) for potential escape hatches.
-	 * @param errorHandler - Optional global error trap defined in project configuration.
-	 * @returns The resulting Web standard `Response` constructed by the user's handler.
-	 */
-	protected async executeApiHandler(
-		request: Request,
-		params: Record<string, string | string[]>,
-		routeConfig: ApiHandler,
-		serverInstance: any,
-		errorHandler?: ErrorHandler,
-	): Promise<Response> {
-		let context: ApiHandlerContext<Request, any> | undefined;
-
-		try {
-			const middleware = routeConfig.middleware || [];
-			const schema = routeConfig.schema;
-			const locals: Record<string, unknown> = {};
-
-			const normalizedParams = Object.fromEntries(
-				Object.entries(params).map(([key, value]) => [key, Array.isArray(value) ? value.join('/') : value]),
-			);
-
-			context = {
-				request,
-				params: normalizedParams,
-				response: new ApiResponseBuilder(),
-				server: serverInstance,
-				locals,
-				require: createRequire((): Record<string, unknown> => locals),
-				services: {
-					cache: this.getCacheService(),
-				},
-				...this.getRenderContext(),
-			};
-
-			if (schema) {
-				const url = new URL(request.url);
-				const queryParams = Object.fromEntries(url.searchParams);
-				const headers = Object.fromEntries(request.headers);
-
-				let body: unknown;
-				if (schema.body) {
-					try {
-						const contentType = request.headers.get('Content-Type') || '';
-						if (contentType.includes('application/json')) body = await request.clone().json();
-						else if (contentType.includes('text/plain')) body = await request.clone().text();
-					} catch {
-						return context.response.status(400).json({ error: 'Invalid request body' });
-					}
-				}
-
-				const validationResult = await this.schemaValidator.validateRequest(
-					{ body, query: queryParams, headers, params: normalizedParams },
-					schema,
-				);
-
-				if (!validationResult.success) {
-					return context.response.status(400).json({
-						error: 'Validation failed',
-						issues: validationResult.errors,
-					});
-				}
-
-				const validated = validationResult.data!;
-				if (validated.body !== undefined) context.body = validated.body;
-				if (validated.query !== undefined) context.query = validated.query;
-				if (validated.headers !== undefined) context.headers = validated.headers;
-				if (validated.params !== undefined) context.params = validated.params as Record<string, string>;
-			}
-
-			if (middleware.length === 0) {
-				return await routeConfig.handler(context);
-			}
-
-			let index = 0;
-			const executeNext = async (): Promise<Response> => {
-				if (index < middleware.length) {
-					const currentMiddleware = middleware[index++];
-					return await currentMiddleware(context!, executeNext);
-				}
-				return await routeConfig.handler(context!);
-			};
-
-			return await executeNext();
-		} catch (error) {
-			if (error instanceof Response) return error;
-
-			if (errorHandler) {
-				try {
-					if (!context) {
-						const locals: Record<string, unknown> = {};
-						context = {
-							request,
-							params: Object.fromEntries(
-								Object.entries(params).map(([key, value]) => [
-									key,
-									Array.isArray(value) ? value.join('/') : value,
-								]),
-							),
-							response: new ApiResponseBuilder(),
-							server: serverInstance,
-							locals,
-							require: createRequire((): Record<string, unknown> => locals),
-							services: { cache: this.getCacheService() },
-							...this.getRenderContext(),
-						};
-					}
-					return await errorHandler(error, context);
-				} catch (handlerError) {
-					appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
-				}
-			}
-
-			if (error instanceof HttpError) return error.toResponse();
-			appLogger.error(`[ecopages] Error handling API request: ${error}`);
-			return new Response('Internal Server Error', { status: 500 });
-		}
-	}
-
-	private normalizePath(pathname: string): string {
-		if (pathname.length > 1 && pathname.endsWith('/')) {
-			return pathname.slice(0, -1);
-		}
-
-		return pathname;
-	}
-
-	private matchApiPath(pattern: string, pathname: string): Record<string, string | string[]> | null {
-		const normalizedPattern = this.normalizePath(pattern);
-		const normalizedPathname = this.normalizePath(pathname);
-
-		const patternSegments = normalizedPattern.split('/').filter(Boolean);
-		const pathSegments = normalizedPathname.split('/').filter(Boolean);
-		const params: Record<string, string | string[]> = {};
-
-		let patternIndex = 0;
-		let pathIndex = 0;
-
-		while (patternIndex < patternSegments.length && pathIndex < pathSegments.length) {
-			const patternSegment = patternSegments[patternIndex];
-			const pathSegment = pathSegments[pathIndex];
-
-			if (patternSegment === '*') {
-				return params;
-			}
-
-			if (patternSegment.startsWith('[...') && patternSegment.endsWith(']')) {
-				const paramName = patternSegment.slice(4, -1);
-				params[paramName] = pathSegments.slice(pathIndex);
-				return params;
-			}
-
-			if (patternSegment.startsWith(':')) {
-				params[patternSegment.slice(1)] = pathSegment;
-				patternIndex++;
-				pathIndex++;
-				continue;
-			}
-
-			if (patternSegment.startsWith('[') && patternSegment.endsWith(']')) {
-				params[patternSegment.slice(1, -1)] = pathSegment;
-				patternIndex++;
-				pathIndex++;
-				continue;
-			}
-
-			if (patternSegment !== pathSegment) {
-				return null;
-			}
-
-			patternIndex++;
-			pathIndex++;
-		}
-
-		if (patternIndex < patternSegments.length) {
-			const remaining = patternSegments.slice(patternIndex);
-			const catchAll = remaining[0];
-
-			if (
-				remaining.length === 1 &&
-				(catchAll === '*' || (catchAll.startsWith('[...') && catchAll.endsWith(']')))
-			) {
-				if (catchAll.startsWith('[...')) {
-					const paramName = catchAll.slice(4, -1);
-					params[paramName] = [];
-				}
-				return params;
-			}
-
-			return null;
-		}
-
-		if (pathIndex < pathSegments.length) {
-			return null;
-		}
-
-		return params;
-	}
-
-	private getApiPathScore(pattern: string): number {
-		const segments = this.normalizePath(pattern).split('/').filter(Boolean);
-		let score = 0;
-		for (const segment of segments) {
-			if (segment === '*' || (segment.startsWith('[...') && segment.endsWith(']'))) {
-				score += 10;
-			} else if (segment.startsWith(':') || (segment.startsWith('[') && segment.endsWith(']'))) {
-				score += 50;
-			} else {
-				score += 100;
-			}
-		}
-		return score;
-	}
-
-	protected matchApiHandler(
-		request: Request,
-		apiHandlers: ApiHandler[],
-	): { routeConfig: ApiHandler; params: Record<string, string | string[]> } | null {
-		const pathname = new URL(request.url).pathname;
-		const method = request.method.toUpperCase();
-
-		const sortedHandlers = [...apiHandlers].sort((a, b) => {
-			return this.getApiPathScore(b.path) - this.getApiPathScore(a.path);
-		});
-
-		for (const routeConfig of sortedHandlers) {
-			const routeMethod = (routeConfig.method || 'GET').toUpperCase();
-			if (routeMethod !== method) {
-				continue;
-			}
-
-			const params = this.matchApiPath(routeConfig.path, pathname);
-			if (params) {
-				return { routeConfig, params };
-			}
-		}
-
-		return null;
-	}
-
-	/**
-	 * Universally processes an incoming WinterCG Web standard Request.
-	 *
-	 * 1. Resolves static Hot Module Replacement runtime blobs if development.
-	 * 2. Checks if the incoming request matches any parsed API route schemas.
-	 *   - Routes through `executeApiHandler` which performs strict validation.
-	 * 3. Falls through to standard `ServerRouteHandler` for React/Lit filesystem pages.
-	 *
-	 * Both Bun and Node bindings fall back to this exact function once they have mapped their
-	 * native HTTP objects into Web Standard Requests.
-	 */
-	public async handleSharedRequest(
-		request: Request,
-		context: {
-			apiHandlers: ApiHandler[];
-			errorHandler?: ErrorHandler;
-			serverInstance?: any;
-			hmrManager?: any;
-		},
-	): Promise<Response> {
-		const url = new URL(request.url);
-
-		if (url.pathname === '/_hmr_runtime.js' && context.hmrManager) {
-			const runtimePath = context.hmrManager.getRuntimePath();
-			if (fileSystem.exists(runtimePath)) {
-				return new Response(fileSystem.readFileAsBuffer(runtimePath) as BodyInit, {
-					headers: { 'Content-Type': 'application/javascript' },
-				});
-			}
-		}
-
-		if (url.pathname.startsWith('/assets/_hmr/') && context.hmrManager) {
-			const relativePath = url.pathname.slice('/assets/_hmr/'.length);
-			const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
-
-			if (fileSystem.exists(assetPath)) {
-				return new Response(fileSystem.readFileAsBuffer(assetPath) as BodyInit, {
-					headers: { 'Content-Type': 'application/javascript' },
-				});
-			}
-		}
-
-		const apiMatch = this.matchApiHandler(request, context.apiHandlers);
-		if (apiMatch) {
-			return this.executeApiHandler(
-				request,
-				apiMatch.params,
-				apiMatch.routeConfig,
-				context.serverInstance,
-				context.errorHandler,
-			);
-		}
-
-		return this.routeHandler.handleResponse(request);
-	}
-}

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

@@ -1,153 +0,0 @@
-import type { IHmrManager } from '../../public-types';
-import type { FSRouter } from '../../router/server/fs-router';
-import type { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher';
-import type { FileSystemResponseMatcher } from './fs-server-response-matcher';
-import { appLogger } from '../../global/app-logger';
-import { HttpError } from '../../errors/http-error';
-import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from './hmr-html-response';
-
-/**
- * Configuration parameters for ServerRouteHandler.
- */
-export interface ServerRouteHandlerParams {
-	/** File system router for matching request URLs to route handlers. */
-	router: FSRouter;
-	/** 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: FSRouter;
-	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.match(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 });
-		}
-	}
-}