@ecopages/core 0.2.0-alpha.9 → 0.2.0-beta.1

package/src/adapters/shared/explicit-static-route-matcher.ts

@@ -1,140 +0,0 @@
-import { appLogger } from '../../global/app-logger.ts';
-import type { EcoPagesAppConfig } from '../../internal-types.ts';
-import type { StaticRoute } from '../../public-types.ts';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
-
-export const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
-	missingIntegration: (routePath: string) =>
-		`View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
-	noRendererForIntegration: (integrationName: string) => `No renderer found for integration: ${integrationName}`,
-} as const;
-
-function getViewIntegrationName(view: {
-	config?: { integration?: string; __eco?: { integration?: string } };
-}): string | undefined {
-	return view.config?.integration ?? view.config?.__eco?.integration;
-}
-
-export interface ExplicitStaticRouteMatcherOptions {
-	appConfig: EcoPagesAppConfig;
-	routeRendererFactory: RouteRendererFactory;
-	staticRoutes: StaticRoute[];
-}
-
-export interface ExplicitRouteMatch {
-	route: StaticRoute;
-	params: Record<string, string>;
-}
-
-export class ExplicitStaticRouteMatcher {
-	private readonly appConfig: EcoPagesAppConfig;
-	private readonly routeRendererFactory: RouteRendererFactory;
-	private readonly staticRoutes: StaticRoute[];
-
-	constructor({ appConfig, routeRendererFactory, staticRoutes }: ExplicitStaticRouteMatcherOptions) {
-		this.appConfig = appConfig;
-		this.routeRendererFactory = routeRendererFactory;
-		this.staticRoutes = staticRoutes;
-	}
-
-	/**
-	 * Match a request URL against explicit static routes.
-	 * Returns the matched route and extracted params, or null if no match.
-	 */
-	match(url: string): ExplicitRouteMatch | null {
-		const pathname = new URL(url).pathname;
-
-		for (const route of this.staticRoutes) {
-			const params = this.matchRoute(route.path, pathname);
-			if (params !== null) {
-				return { route, params };
-			}
-		}
-
-		return null;
-	}
-
-	/**
-	 * Match a route pattern against a pathname.
-	 * Supports :param and [param] syntax.
-	 * Returns extracted params or null if no match.
-	 */
-	private matchRoute(pattern: string, pathname: string): Record<string, string> | null {
-		const patternSegments = pattern.split('/').filter(Boolean);
-		const pathSegments = pathname.split('/').filter(Boolean);
-
-		if (patternSegments.length !== pathSegments.length) {
-			const lastPattern = patternSegments[patternSegments.length - 1];
-			const isCatchAll = lastPattern?.startsWith('[...') || lastPattern?.startsWith(':...');
-			if (!isCatchAll) {
-				return null;
-			}
-		}
-
-		const params: Record<string, string> = {};
-
-		for (let i = 0; i < patternSegments.length; i++) {
-			const patternPart = patternSegments[i];
-			const pathPart = pathSegments[i];
-
-			if (patternPart.startsWith(':...') || patternPart.startsWith('[...')) {
-				const paramName = patternPart.replace(/^(:\.\.\.|\[\.\.\.)/, '').replace(/\]$/, '');
-				params[paramName] = pathSegments.slice(i).join('/');
-				return params;
-			}
-
-			if (patternPart.startsWith(':')) {
-				const paramName = patternPart.slice(1);
-				params[paramName] = pathPart;
-			} else if (patternPart.startsWith('[') && patternPart.endsWith(']')) {
-				const paramName = patternPart.slice(1, -1);
-				params[paramName] = pathPart;
-			} else if (patternPart !== pathPart) {
-				return null;
-			}
-		}
-
-		return params;
-	}
-
-	/**
-	 * Handle a matched explicit static route.
-	 * Resolves the loader and renders the view using the appropriate integration renderer.
-	 */
-	async handleMatch(match: ExplicitRouteMatch): Promise<Response> {
-		const { route, params } = match;
-
-		try {
-			const mod = await route.loader();
-			const view = mod.default;
-
-			const integrationName = getViewIntegrationName(view);
-			if (!integrationName) {
-				throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.missingIntegration(route.path));
-			}
-
-			const renderer = this.routeRendererFactory.getRendererByIntegration(integrationName);
-			if (!renderer) {
-				throw new Error(EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS.noRendererForIntegration(integrationName));
-			}
-
-			const props = view.staticProps
-				? (
-						await view.staticProps({
-							pathname: { params },
-							appConfig: this.appConfig,
-							runtimeOrigin: this.appConfig.baseUrl,
-						})
-					).props
-				: {};
-
-			return renderer.renderToResponse(view, props, {});
-		} catch (error) {
-			appLogger.error(
-				`Error rendering explicit static route ${route.path}:`,
-				error instanceof Error ? error : String(error),
-			);
-			throw error;
-		}
-	}
-}

package/src/adapters/shared/file-route-middleware-pipeline.ts

@@ -1,127 +0,0 @@
-import { createRequire } from '../../utils/locals-utils.ts';
-import type { Middleware, ApiHandlerContext, RequestLocals } from '../../public-types.ts';
-import type { PageCacheService } from '../../services/cache/page-cache-service.js';
-import { ApiResponseBuilder } from './api-response.js';
-import { LocalsAccessError } from '../../errors/locals-access-error.ts';
-
-export const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
-	CTX_RENDER_UNAVAILABLE: '[ecopages] ctx.render is not available in file-route middleware',
-	CTX_RENDER_PARTIAL_UNAVAILABLE: '[ecopages] ctx.renderPartial is not available in file-route middleware',
-	middlewareRequiresDynamic: (filePath: string) =>
-		`[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`,
-} as const;
-
-/**
- * Executes middleware for file-based page routes.
- *
- * This pipeline owns the middleware-specific rules that are distinct from route
- * matching and rendering, including request-local storage, the middleware
- * execution context, and the invariant that page middleware only runs for
- * request-time dynamic rendering.
- */
-export class FileRouteMiddlewarePipeline {
-	private cacheService: PageCacheService | null;
-
-	constructor(cacheService: PageCacheService | null) {
-		this.cacheService = cacheService;
-	}
-
-	/**
-	 * Enforces the current middleware contract for file-routed pages.
-	 *
-	 * Middleware depends on request-scoped locals and therefore must not run when
-	 * the page is treated as statically cacheable.
-	 *
-	 * @param input Middleware list, effective cache strategy, and page path.
-	 * @throws LocalsAccessError When middleware is configured for a non-dynamic page.
-	 */
-	assertValidConfiguration(input: {
-		middleware: Middleware[];
-		pageCacheStrategy: 'static' | 'dynamic' | { revalidate: number; tags?: string[] };
-		filePath: string;
-	}): void {
-		if (input.middleware.length > 0 && input.pageCacheStrategy !== 'dynamic') {
-			throw new LocalsAccessError(
-				FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.middlewareRequiresDynamic(input.filePath),
-			);
-		}
-	}
-
-	/**
-	 * Creates the request-scoped middleware context used by page middleware.
-	 *
-	 * The context intentionally disables `render()` and `renderPartial()` inside
-	 * file-route middleware because rendering is owned by the page route pipeline,
-	 * not by middleware stages.
-	 *
-	 * @param input Request details and the mutable locals store.
-	 * @returns Middleware execution context.
-	 */
-	createContext(input: {
-		request: Request;
-		params: Record<string, string>;
-		locals: RequestLocals;
-	}): ApiHandlerContext {
-		const context: ApiHandlerContext = {
-			request: input.request,
-			params: input.params,
-			response: new ApiResponseBuilder(),
-			server: null,
-			services: {
-				cache: this.cacheService,
-			},
-			locals: input.locals,
-			require: createRequire(() => context.locals as unknown as Record<string, unknown>),
-			render: async () => {
-				throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_UNAVAILABLE);
-			},
-			renderPartial: async () => {
-				throw new Error(FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.CTX_RENDER_PARTIAL_UNAVAILABLE);
-			},
-			json: (data, options) => {
-				const builder = new ApiResponseBuilder();
-				if (options?.status) builder.status(options.status);
-				if (options?.headers) builder.headers(options.headers);
-				return builder.json(data);
-			},
-			html: (content, options) => {
-				const builder = new ApiResponseBuilder();
-				if (options?.status) builder.status(options.status);
-				if (options?.headers) builder.headers(options.headers);
-				return builder.html(content);
-			},
-		};
-
-		return context;
-	}
-
-	/**
-	 * Runs the middleware chain and eventually delegates to the render callback.
-	 *
-	 * Middleware may short-circuit by returning a response directly. If the chain
-	 * completes, the supplied `renderResponse` callback is executed exactly once.
-	 *
-	 * @param input Middleware context, chain, and terminal render callback.
-	 * @returns Response from middleware or final render stage.
-	 */
-	async run(input: {
-		middleware: Middleware[];
-		context: ApiHandlerContext;
-		renderResponse: () => Promise<Response>;
-	}): Promise<Response> {
-		if (input.middleware.length === 0) {
-			return input.renderResponse();
-		}
-
-		let index = 0;
-		const executeNext = async (): Promise<Response> => {
-			if (index < input.middleware.length) {
-				const current = input.middleware[index++];
-				return current(input.context, executeNext);
-			}
-			return input.renderResponse();
-		};
-
-		return executeNext();
-	}
-}

package/src/adapters/shared/fs-server-response-factory.ts

@@ -1,118 +0,0 @@
-import { STATUS_MESSAGE } from '../../constants.ts';
-import { appLogger } from '../../global/app-logger.ts';
-import type { EcoPagesAppConfig, FileSystemServerOptions } from '../../internal-types.ts';
-import type { RouteRendererBody } from '../../public-types.ts';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
-import { fileSystem } from '@ecopages/file-system';
-
-export class FileSystemServerResponseFactory {
-	private appConfig: EcoPagesAppConfig;
-	private routeRendererFactory: RouteRendererFactory;
-	private options: FileSystemServerOptions;
-
-	constructor({
-		appConfig,
-		routeRendererFactory,
-		options,
-	}: {
-		appConfig: EcoPagesAppConfig;
-		routeRendererFactory: RouteRendererFactory;
-		options: FileSystemServerOptions;
-	}) {
-		this.appConfig = appConfig;
-		this.routeRendererFactory = routeRendererFactory;
-		this.options = options;
-	}
-
-	isHtml(contentType: string) {
-		return contentType === 'text/html';
-	}
-
-	shouldEnableGzip(contentType: string) {
-		if (this.options.watchMode) return false;
-		const gzipEnabledExtensions = ['text/javascript', 'text/css'];
-		return gzipEnabledExtensions.includes(contentType);
-	}
-
-	async createResponseWithBody(
-		body: RouteRendererBody,
-		init: ResponseInit = {
-			headers: {
-				'Content-Type': 'text/html',
-			},
-		},
-	) {
-		return new Response(body as BodyInit, init);
-	}
-
-	async createDefaultNotFoundResponse() {
-		return new Response(STATUS_MESSAGE[404], {
-			status: 404,
-		});
-	}
-
-	async createCustomNotFoundResponse() {
-		const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
-
-		try {
-			fileSystem.verifyFileExists(error404TemplatePath);
-		} catch {
-			appLogger.debug(
-				'Custom 404 template not found, falling back to default 404 response',
-				error404TemplatePath,
-			);
-			return this.createDefaultNotFoundResponse();
-		}
-
-		const routeRenderer = this.routeRendererFactory.createRenderer(error404TemplatePath);
-
-		const result = await routeRenderer.createRoute({
-			file: error404TemplatePath,
-		});
-
-		return await this.createResponseWithBody(result.body, {
-			status: 404,
-			statusText: STATUS_MESSAGE[404],
-			headers: {
-				'Content-Type': 'text/html',
-			},
-		});
-	}
-
-	async createFileResponse(filePath: string, contentType: string) {
-		try {
-			let file: Buffer;
-			const contentEncodingHeader: HeadersInit = {};
-
-			if (this.shouldEnableGzip(contentType)) {
-				const gzipPath = `${filePath}.gz`;
-				if (fileSystem.exists(gzipPath)) {
-					file = fileSystem.readFileAsBuffer(gzipPath);
-					contentEncodingHeader['Content-Encoding'] = 'gzip';
-					contentEncodingHeader['Vary'] = 'Accept-Encoding';
-				} else {
-					appLogger.debug('Gzip file not found, serving uncompressed', gzipPath);
-					file = fileSystem.readFileAsBuffer(filePath);
-				}
-			} else {
-				file = fileSystem.readFileAsBuffer(filePath);
-			}
-
-			return await this.createResponseWithBody(file as unknown as BodyInit, {
-				headers: {
-					'Content-Type': contentType,
-					...contentEncodingHeader,
-				},
-			});
-		} catch (error) {
-			const err = error as Error & { code?: string; cause?: { code?: string } };
-			const code = err.code || err.cause?.code;
-			if (code === 'ENOENT') {
-				appLogger.debug('File not found', filePath);
-			} else {
-				appLogger.error('Error reading file', filePath, err);
-			}
-			return this.createCustomNotFoundResponse();
-		}
-	}
-}

package/src/adapters/shared/fs-server-response-matcher.ts

@@ -1,205 +0,0 @@
-import path from 'node:path';
-import { appLogger } from '../../global/app-logger.ts';
-import type { EcoPagesAppConfig, MatchResult } from '../../internal-types.ts';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
-import type { FSRouter } from '../../router/server/fs-router.ts';
-import type { PageCacheService } from '../../services/cache/page-cache-service.ts';
-import type { CacheStrategy, RenderResult } from '../../services/cache/cache.types.ts';
-import { PageRequestCacheCoordinator } from '../../services/cache/page-request-cache-coordinator.service.ts';
-import { getAppServerModuleTranspiler } from '../../services/module-loading/app-server-module-transpiler.service.ts';
-import type { ServerModuleTranspiler } from '../../services/module-loading/server-module-transpiler.service.ts';
-import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.ts';
-import { ServerUtils } from '../../utils/server-utils.module.ts';
-import type { Middleware, RequestLocals } from '../../public-types.ts';
-import { FileRouteMiddlewarePipeline } from './file-route-middleware-pipeline.ts';
-import { LocalsAccessError } from '../../errors/locals-access-error.ts';
-import { isDevelopmentRuntime } from '../../utils/runtime.ts';
-import type { FileSystemServerResponseFactory } from './fs-server-response-factory.ts';
-
-export const FILE_SYSTEM_RESPONSE_MATCHER_ERRORS = {
-	transpilePageModuleFailed: (details: string) => `Error transpiling page module: ${details}`,
-	noTranspiledOutputForPageModule: (filePath: string) =>
-		`No transpiled output generated for page module: ${filePath}`,
-} as const;
-
-export interface FileSystemResponseMatcherOptions {
-	appConfig: EcoPagesAppConfig;
-	router: FSRouter;
-	routeRendererFactory: RouteRendererFactory;
-	fileSystemResponseFactory: FileSystemServerResponseFactory;
-	/** Optional cache service. When null, caching is disabled. */
-	cacheService?: PageCacheService | null;
-	/** Default cache strategy when caching is enabled. @default 'static' */
-	defaultCacheStrategy?: CacheStrategy;
-}
-
-/**
- * Matches file-system routes to rendered HTML responses.
- *
- * This class sits at the request-time boundary between router matches and the
- * render pipeline. It coordinates page module inspection, request-local policy,
- * renderer invocation, middleware execution, cache integration, and fallback
- * error translation.
- */
-export class FileSystemResponseMatcher {
-	private appConfig: EcoPagesAppConfig;
-	private router: FSRouter;
-	private routeRendererFactory: RouteRendererFactory;
-	private fileSystemResponseFactory: FileSystemServerResponseFactory;
-	private serverModuleTranspiler: ServerModuleTranspiler;
-	private pageRequestCacheCoordinator: PageRequestCacheCoordinator;
-	private fileRouteMiddlewarePipeline: FileRouteMiddlewarePipeline;
-
-	constructor({
-		appConfig,
-		router,
-		routeRendererFactory,
-		fileSystemResponseFactory,
-		cacheService = null,
-		defaultCacheStrategy = 'static',
-	}: FileSystemResponseMatcherOptions) {
-		this.appConfig = appConfig;
-		this.router = router;
-		this.routeRendererFactory = routeRendererFactory;
-		this.fileSystemResponseFactory = fileSystemResponseFactory;
-		this.serverModuleTranspiler = getAppServerModuleTranspiler(appConfig);
-		this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
-		this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
-	}
-
-	/**
-	 * Resolves unmatched paths either as static asset requests or as the custom
-	 * not-found page.
-	 *
-	 * @param requestUrl Incoming pathname.
-	 * @returns Static file response or rendered 404 response.
-	 */
-	async handleNoMatch(requestUrl: string): Promise<Response> {
-		const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
-
-		if (!isStaticFileRequest) {
-			return this.fileSystemResponseFactory.createCustomNotFoundResponse();
-		}
-
-		const relativeUrl = requestUrl.startsWith('/') ? requestUrl.slice(1) : requestUrl;
-		const filePath = path.join(this.router.assetPrefix, relativeUrl);
-		const contentType = ServerUtils.getContentType(filePath);
-
-		return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
-	}
-
-	/**
-	 * Handles a matched file-system page route.
-	 *
-	 * The method inspects page metadata needed for request-time execution,
-	 * prepares the renderer invocation, validates middleware/cache constraints,
-	 * and delegates caching plus middleware execution to dedicated collaborators.
-	 *
-	 * @param match Router match result.
-	 * @param request Optional incoming request. A synthetic GET request is created when omitted.
-	 * @returns Final response for the matched route.
-	 */
-	async handleMatch(match: MatchResult, request?: Request): Promise<Response> {
-		const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey(match);
-
-		try {
-			const resolvedRequest =
-				request ??
-				new Request(new URL(cacheKey, this.router.origin).toString(), {
-					method: 'GET',
-				});
-
-			const localsStore: RequestLocals = {};
-			const pageModule = await this.importPageModule(match.filePath);
-			const Page = (pageModule as any)?.default;
-			const pageMiddleware = (Page?.middleware ?? []) as Middleware[];
-			const pageCacheStrategy =
-				(Page?.cache as CacheStrategy | undefined) ??
-				this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-			const localsForRender: RequestLocals | undefined =
-				pageCacheStrategy === 'dynamic' ? localsStore : undefined;
-
-			this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-				middleware: pageMiddleware,
-				pageCacheStrategy,
-				filePath: match.filePath,
-			});
-
-			const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
-			const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-				request: resolvedRequest,
-				params: match.params as Record<string, string>,
-				locals: localsStore,
-			});
-
-			const renderFn = async (): Promise<RenderResult> => {
-				const result = await routeRenderer.createRoute({
-					file: match.filePath,
-					params: match.params,
-					query: match.query,
-					locals: localsForRender,
-				});
-				const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
-				const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-				return { html, strategy };
-			};
-			const renderResponse = async (): Promise<Response> => {
-				return this.pageRequestCacheCoordinator.render({
-					cacheKey,
-					pageCacheStrategy,
-					renderFn,
-				});
-			};
-
-			return await this.fileRouteMiddlewarePipeline.run({
-				middleware: pageMiddleware,
-				context: middlewareContext,
-				renderResponse,
-			});
-		} catch (error) {
-			if (error instanceof Response) {
-				return error;
-			}
-			if (error instanceof LocalsAccessError) {
-				return new Response(error.message, {
-					status: 500,
-					headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-				});
-			}
-			if (error instanceof Error) {
-				if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-					appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
-				}
-			}
-			return this.fileSystemResponseFactory.createCustomNotFoundResponse();
-		}
-	}
-
-	/**
-	 * Loads the matched page module for request-time inspection.
-	 *
-	 * The matcher needs access to page-level metadata such as `cache` and
-	 * `middleware` before full rendering starts, so it uses the shared module
-	 * import service directly rather than going through route rendering. The
-	 * app config is injected explicitly so build ownership stays at the adapter
-	 * boundary instead of leaking through nested router collaborators.
-	 *
-	 * @param filePath Absolute page module path.
-	 * @returns Imported page module.
-	 */
-	private async importPageModule(filePath: string): Promise<unknown> {
-		return this.serverModuleTranspiler.importModule({
-			filePath,
-			outdir: path.join(resolveInternalExecutionDir(this.appConfig), '.server-modules-meta'),
-			transpileErrorMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.transpilePageModuleFailed,
-			noOutputMessage: FILE_SYSTEM_RESPONSE_MATCHER_ERRORS.noTranspiledOutputForPageModule,
-		});
-	}
-
-	/**
-	 * Get the underlying cache service for external invalidation.
-	 */
-	getCacheService(): PageCacheService | null {
-		return this.pageRequestCacheCoordinator.getCacheService();
-	}
-}