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

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

@@ -1,22 +1,33 @@
 import path from 'node:path';
 import { appLogger } from '../../global/app-logger.ts';
 import type { EcoPagesAppConfig, MatchResult } from '../../types/internal-types.ts';
-import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
-import type { FSRouter } from '../../router/server/fs-router.ts';
+import type { PageRendererResolver } from '../../route-renderer/route-renderer.ts';
+import type { RouteRegistry } from '../../router/server/route-registry.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 { ServerUtils } from '../../utils/server-utils.module.ts';
-import type { Middleware, RequestLocals } from '../../types/public-types.ts';
+import type { FileRouteMiddleware, RequestLocals } from '../../types/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';
 
+type FileRouteExecutionPlan = {
+	cacheKey: string;
+	request: Request;
+	pageFilePath: string;
+	pageMiddleware: FileRouteMiddleware[];
+	pageCacheStrategy: CacheStrategy;
+	localsStore: RequestLocals;
+	localsForRender: RequestLocals | undefined;
+};
+
 export interface FileSystemResponseMatcherOptions {
 	appConfig: EcoPagesAppConfig;
-	router: FSRouter;
-	routeRendererFactory: RouteRendererFactory;
+	assetPrefix: string;
+	router: RouteRegistry;
+	routeRendererFactory: PageRendererResolver;
 	fileSystemResponseFactory: FileSystemServerResponseFactory;
 	/** Optional cache service. When null, caching is disabled. */
 	cacheService?: PageCacheService | null;
@@ -27,20 +38,22 @@ export interface FileSystemResponseMatcherOptions {
 /**
  * Matches file-system routes to rendered HTML responses.
  *
- * render pipeline. It coordinates page module inspection, request-local policy,
+ * This render pipeline 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 assetPrefix: string;
+	private router: RouteRegistry;
+	private routeRendererFactory: PageRendererResolver;
 	private fileSystemResponseFactory: FileSystemServerResponseFactory;
 	private pageRequestCacheCoordinator: PageRequestCacheCoordinator;
 	private fileRouteMiddlewarePipeline: FileRouteMiddlewarePipeline;
 
 	constructor({
 		appConfig,
+		assetPrefix,
 		router,
 		routeRendererFactory,
 		fileSystemResponseFactory,
@@ -48,6 +61,7 @@ export class FileSystemResponseMatcher {
 		defaultCacheStrategy = 'static',
 	}: FileSystemResponseMatcherOptions) {
 		this.appConfig = appConfig;
+		this.assetPrefix = assetPrefix;
 		this.router = router;
 		this.routeRendererFactory = routeRendererFactory;
 		this.fileSystemResponseFactory = fileSystemResponseFactory;
@@ -65,14 +79,15 @@ export class FileSystemResponseMatcher {
 		const isStaticFileRequest = ServerUtils.hasKnownExtension(requestUrl);
 
 		if (!isStaticFileRequest) {
-			return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+			return this.renderCustomNotFoundResponse();
 		}
 
 		const relativeUrl = requestUrl.startsWith('/') ? requestUrl.slice(1) : requestUrl;
-		const filePath = path.join(this.router.assetPrefix, relativeUrl);
+		const filePath = path.join(this.assetPrefix, relativeUrl);
 		const contentType = ServerUtils.getContentType(filePath);
 
-		return this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+		const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+		return response ?? this.renderCustomNotFoundResponse();
 	}
 
 	/**
@@ -87,44 +102,28 @@ export class FileSystemResponseMatcher {
 	 * @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;
+			const executionPlan = await this.createExecutionPlan(match, request);
 
 			this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-				middleware: pageMiddleware,
-				pageCacheStrategy,
-				filePath: match.filePath,
+				middleware: executionPlan.pageMiddleware,
+				pageCacheStrategy: executionPlan.pageCacheStrategy,
+				filePath: executionPlan.pageFilePath,
 			});
 
-			const routeRenderer = this.routeRendererFactory.createRenderer(match.filePath);
+			const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
 			const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-				request: resolvedRequest,
+				request: executionPlan.request,
 				params: match.params as Record<string, string>,
-				locals: localsStore,
+				locals: executionPlan.localsStore,
 			});
 
 			const renderFn = async (): Promise<RenderResult> => {
-				const result = await routeRenderer.createRoute({
-					file: match.filePath,
+				const result = await routeRenderer.execute({
+					file: executionPlan.pageFilePath,
 					params: match.params,
 					query: match.query,
-					locals: localsForRender,
+					locals: executionPlan.localsForRender,
 				});
 				const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
 				const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
@@ -132,14 +131,14 @@ export class FileSystemResponseMatcher {
 			};
 			const renderResponse = async (): Promise<Response> => {
 				return this.pageRequestCacheCoordinator.render({
-					cacheKey,
-					pageCacheStrategy,
+					cacheKey: executionPlan.cacheKey,
+					pageCacheStrategy: executionPlan.pageCacheStrategy,
 					renderFn,
 				});
 			};
 
 			return await this.fileRouteMiddlewarePipeline.run({
-				middleware: pageMiddleware,
+				middleware: executionPlan.pageMiddleware,
 				context: middlewareContext,
 				renderResponse,
 			});
@@ -155,13 +154,65 @@ export class FileSystemResponseMatcher {
 			}
 			if (error instanceof Error) {
 				if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-					appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.pathname}`);
+					appLogger.error(`[FileSystemResponseMatcher] ${error.message} at ${match.requestedPathname}`);
 				}
 			}
-			return this.fileSystemResponseFactory.createCustomNotFoundResponse();
+			return this.renderCustomNotFoundResponse();
 		}
 	}
 
+	/**
+	 * Renders the app-owned custom 404 page, falling back to the default text 404
+	 * when the page template cannot be resolved.
+	 */
+	private async renderCustomNotFoundResponse(): Promise<Response> {
+		const error404TemplatePath = this.appConfig.absolutePaths.error404TemplatePath;
+
+		try {
+			const routeRenderer = this.routeRendererFactory.getPageRenderer(error404TemplatePath);
+			const result = await routeRenderer.execute({
+				file: error404TemplatePath,
+			});
+
+			return this.fileSystemResponseFactory.createHtmlNotFoundResponse(result.body);
+		} catch {
+			appLogger.debug(
+				'Custom 404 template not found, falling back to default 404 response',
+				error404TemplatePath,
+			);
+			return this.fileSystemResponseFactory.createDefaultNotFoundResponse();
+		}
+	}
+
+	private async createExecutionPlan(match: MatchResult, request?: Request): Promise<FileRouteExecutionPlan> {
+		const cacheKey = this.pageRequestCacheCoordinator.buildCacheKey({
+			pathname: match.requestedPathname,
+			query: match.query,
+		});
+		const resolvedRequest =
+			request ??
+			new Request(new URL(cacheKey, this.router.origin).toString(), {
+				method: 'GET',
+			});
+		const localsStore: RequestLocals = {};
+		const pageFilePath = match.templateRoute.filePath;
+		const pageModule = await this.importPageModule(pageFilePath);
+		const Page = (pageModule as any)?.default;
+		const pageMiddleware = (Page?.middleware ?? []) as FileRouteMiddleware[];
+		const pageCacheStrategy =
+			(Page?.cache as CacheStrategy | undefined) ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+
+		return {
+			cacheKey,
+			request: resolvedRequest,
+			pageFilePath,
+			pageMiddleware,
+			pageCacheStrategy,
+			localsStore,
+			localsForRender: pageCacheStrategy === 'dynamic' ? localsStore : undefined,
+		};
+	}
+
 	/**
 	 * Loads the matched page module for request-time inspection.
 	 *
@@ -174,7 +225,7 @@ export class FileSystemResponseMatcher {
 	 * @returns Imported page module.
 	 */
 	private async importPageModule(filePath: string): Promise<unknown> {
-		const routeRenderer = this.routeRendererFactory.createRenderer(filePath);
+		const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
 		return routeRenderer.loadPageModule(filePath, {
 			cacheScope: 'request-metadata',
 		});

package/src/adapters/shared/hmr-manager.contract.test.ts

@@ -12,9 +12,7 @@ type SharedHmrManager = {
 	handleFileChange(filePath: string, options?: { broadcast?: boolean }): Promise<void>;
 	registerEntrypoint(entrypointPath: string): Promise<string>;
 	registerScriptEntrypoint(entrypointPath: string): Promise<string>;
-	registerSpecifierMap(map: Record<string, string>): void;
 	getWatchedFiles(): Map<string, string>;
-	getSpecifierMap(): Map<string, string>;
 	stop(): void;
 	appConfig: Awaited<ReturnType<ConfigBuilder['build']>>;
 };
@@ -221,12 +219,10 @@ describe.each(runtimes)('shared HMR manager contract: $name', ({ create }) => {
 			fs.writeFileSync(outputPath, 'export default 1;', 'utf8');
 		});
 
-		manager.registerSpecifierMap({ react: '/assets/vendors/react.js' });
 		await manager.registerEntrypoint(entrypointPath);
 
 		manager.stop();
 
 		assert.equal(manager.getWatchedFiles().size, 0);
-		assert.equal(manager.getSpecifierMap().size, 0);
 	});
 });

package/src/adapters/shared/render-context.ts

@@ -3,11 +3,11 @@ import type {
 	IntegrationRenderer,
 	RenderToResponseContext,
 } from '../../route-renderer/orchestration/integration-renderer.ts';
-import type { IntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.ts';
 import { invariant } from '../../utils/invariant.ts';
 
 export interface CreateRenderContextOptions {
-	integrations: IntegrationPlugin[];
+	integrations: AnyIntegrationPlugin[];
 	rendererModules?: unknown;
 }
 
@@ -54,7 +54,7 @@ export function createRenderContext(options: CreateRenderContextOptions): Render
 
 		return integration.initializeRenderer({
 			rendererModules: options.rendererModules,
-		});
+		}) as IntegrationRenderer;
 	};
 
 	const renderContext: RenderContext = {

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { afterEach, test } from 'vitest';
 import { ConfigBuilder } from '../../config/config-builder.ts';
 import type { ServerAdapterResult } from '../abstract/server-adapter.ts';
+import type { ApiHandler } from '../../types/public-types.ts';
 import { SharedServerAdapter } from './server-adapter.ts';
 
 const tempRoots: string[] = [];
@@ -43,6 +44,18 @@ class TestSharedServerAdapter extends SharedServerAdapter<any, ServerAdapterResu
 		});
 	}
 
+	public async handleSharedRequestForTest(request: Request, apiHandlers: ApiHandler[]): Promise<Response> {
+		return await this.handleSharedRequest(request, {
+			apiHandlers,
+		});
+	}
+
+	public setRouteHandlerForTest(handleResponse: (request: Request) => Promise<Response>): void {
+		this.routeHandler = {
+			handleResponse,
+		} as any;
+	}
+
 	constructor(
 		private readonly hmrDir: string,
 		rootDir: string,
@@ -75,3 +88,43 @@ test('SharedServerAdapter serves /assets/_hmr files from the HMR manager directo
 		false,
 	);
 });
+
+test('SharedServerAdapter dispatches matching API handlers before filesystem routes', async () => {
+	const rootDir = createTempRoot('ecopages-shared-server-api-dispatch');
+	const adapter = new TestSharedServerAdapter('', rootDir);
+	adapter.setRouteHandlerForTest(async () => new Response('filesystem'));
+
+	const response = await adapter.handleSharedRequestForTest(
+		new Request('http://localhost/api/posts/123', { method: 'GET' }),
+		[
+			{
+				path: '/api/posts/[id]',
+				method: 'GET',
+				handler: ({ params }) => new Response(`api:${params.id}`),
+			},
+		],
+	);
+
+	assert.equal(response.status, 200);
+	assert.equal(await response.text(), 'api:123');
+});
+
+test('SharedServerAdapter falls back to the route handler when no API handler matches', async () => {
+	const rootDir = createTempRoot('ecopages-shared-server-route-fallback');
+	const adapter = new TestSharedServerAdapter('', rootDir);
+	adapter.setRouteHandlerForTest(async () => new Response('filesystem'));
+
+	const response = await adapter.handleSharedRequestForTest(
+		new Request('http://localhost/blog/post-1', { method: 'GET' }),
+		[
+			{
+				path: '/api/posts/[id]',
+				method: 'GET',
+				handler: () => new Response('api'),
+			},
+		],
+	);
+
+	assert.equal(response.status, 200);
+	assert.equal(await response.text(), 'filesystem');
+});