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

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

@@ -0,0 +1,118 @@
+import { createRequire } from '../../utils/locals-utils.ts';
+import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../types/public-types.ts';
+import type { PageCacheService } from '../../services/cache/page-cache-service.ts';
+import { ApiResponseBuilder } from './api-response.ts';
+import { LocalsAccessError } from '../../errors/locals-access-error.ts';
+
+export const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
+	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: FileRouteMiddleware[];
+		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 omits `render()` and `renderPartial()` 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;
+	}): FileRouteMiddlewareContext {
+		const context: FileRouteMiddlewareContext = {
+			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>),
+			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: FileRouteMiddleware[];
+		context: FileRouteMiddlewareContext;
+		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.test.ts

@@ -0,0 +1,176 @@
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { fileSystem } from '@ecopages/file-system';
+import {
+	FIXTURE_APP_PROJECT_DIR,
+	FIXTURE_EXISTING_CSS_FILE_IN_DIST,
+	FIXTURE_EXISTING_SVG_FILE_IN_DIST_PATH,
+} from '../../../__fixtures__/constants.js';
+import { appLogger } from '../../global/app-logger.ts';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { STATUS_MESSAGE } from '../../config/constants.ts';
+import { FileSystemServerResponseFactory } from './fs-server-response-factory.ts';
+
+let appConfig: Awaited<ReturnType<ConfigBuilder['build']>>;
+let responseFactory: FileSystemServerResponseFactory;
+
+describe('FileSystemServerResponseFactory', () => {
+	beforeAll(async () => {
+		appConfig = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+		for (const integration of appConfig.integrations) {
+			integration.setConfig(appConfig);
+			integration.setRuntimeOrigin(appConfig.baseUrl);
+		}
+
+		responseFactory = new FileSystemServerResponseFactory({
+			options: {
+				watchMode: false,
+			},
+		});
+	});
+
+	describe('isHtml', () => {
+		it('should return true for text/html content type', () => {
+			const result = responseFactory.isHtml('text/html');
+			expect(result).toBe(true);
+		});
+
+		it('should return false for text/plain content type', () => {
+			const result = responseFactory.isHtml('text/plain');
+			expect(result).toBe(false);
+		});
+
+		it('should return false for other content types', () => {
+			const result = responseFactory.isHtml('application/json');
+			expect(result).toBe(false);
+		});
+	});
+
+	describe('shouldEnableGzip', () => {
+		it('should return false in watch mode', () => {
+			const responseFactoryWatch = new FileSystemServerResponseFactory({
+				options: {
+					watchMode: true,
+				},
+			});
+
+			const result = responseFactoryWatch.shouldEnableGzip('text/javascript');
+			expect(result).toBe(false);
+		});
+
+		it('should return true for text/javascript content type', () => {
+			const result = responseFactory.shouldEnableGzip('text/javascript');
+			expect(result).toBe(true);
+		});
+
+		it('should return true for text/css content type', () => {
+			const result = responseFactory.shouldEnableGzip('text/css');
+			expect(result).toBe(true);
+		});
+
+		it('should return false for other content types', () => {
+			const result = responseFactory.shouldEnableGzip('application/json');
+			expect(result).toBe(false);
+		});
+	});
+
+	describe('createResponseWithBody', () => {
+		it('should create a response with the given route renderer body', async () => {
+			const routeRendererBody = '<html><body>Test</body></html>';
+			const response = await responseFactory.createResponseWithBody(routeRendererBody);
+			const body = await response.text();
+			expect(body).toBe(routeRendererBody);
+			expect(response.headers.get('Content-Type')).toBe('text/html');
+		});
+	});
+
+	describe('createDefaultNotFoundResponse', () => {
+		it('should create a response with status 404 and body "file not found"', async () => {
+			const response = await responseFactory.createDefaultNotFoundResponse();
+			expect(response.status).toBe(404);
+			expect(await response.text()).toBe(STATUS_MESSAGE[404]);
+		});
+	});
+
+	describe('createHtmlNotFoundResponse', () => {
+		it('should create an html 404 response from a rendered body', async () => {
+			const response = await responseFactory.createHtmlNotFoundResponse('<h1>404 - Page Not Found</h1>');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+			expect(response.headers.get('Content-Type')).toBe('text/html');
+			expect(response.status).toBe(404);
+		});
+	});
+
+	describe('createFileResponse', () => {
+		it('should create a response with the file content and content type', async () => {
+			const readFileAsBufferSpy = vi
+				.spyOn(fileSystem, 'readFileAsBuffer')
+				.mockReturnValue(Buffer.from('<svg></svg>'));
+
+			const response = await responseFactory.createFileResponse(
+				FIXTURE_EXISTING_SVG_FILE_IN_DIST_PATH,
+				'image/svg+xml',
+			);
+			readFileAsBufferSpy.mockRestore();
+			if (!response) {
+				throw new Error('Expected static file response');
+			}
+			expect(response.headers.get('Content-Type')).toBe('image/svg+xml');
+		});
+
+		it('should return null if the file does not exist', async () => {
+			const response = await responseFactory.createFileResponse('/path/to/nonexistent.txt', 'text/plain');
+			expect(response).toBeNull();
+		});
+
+		it('should log debug for ENOENT errors', async () => {
+			const debugSpy = vi.spyOn(appLogger, 'debug');
+			const errorSpy = vi.spyOn(appLogger, 'error');
+
+			await responseFactory.createFileResponse('/path/to/nonexistent-debug.txt', 'text/plain');
+
+			expect(debugSpy).toHaveBeenCalled();
+			expect(errorSpy).not.toHaveBeenCalled();
+
+			debugSpy.mockRestore();
+			errorSpy.mockRestore();
+		});
+
+		it('should serve gzip file with Content-Encoding header when gzip is enabled', async () => {
+			const cssFilePath = `${appConfig.absolutePaths.distDir}/${FIXTURE_EXISTING_CSS_FILE_IN_DIST}`;
+			const existsSpy = vi
+				.spyOn(fileSystem, 'exists')
+				.mockImplementation((filePath) => filePath === `${cssFilePath}.gz`);
+			const readFileAsBufferSpy = vi
+				.spyOn(fileSystem, 'readFileAsBuffer')
+				.mockReturnValue(Buffer.from('body{color:red}'));
+			const response = await responseFactory.createFileResponse(cssFilePath, 'text/css');
+			existsSpy.mockRestore();
+			readFileAsBufferSpy.mockRestore();
+
+			if (!response) {
+				throw new Error('Expected gzip file response');
+			}
+			expect(response.headers.get('Content-Type')).toBe('text/css');
+			expect(response.headers.get('Content-Encoding')).toBe('gzip');
+		});
+
+		it('should not set Content-Encoding header for non-gzip content types', async () => {
+			const readFileAsBufferSpy = vi
+				.spyOn(fileSystem, 'readFileAsBuffer')
+				.mockReturnValue(Buffer.from('<svg></svg>'));
+			const response = await responseFactory.createFileResponse(
+				FIXTURE_EXISTING_SVG_FILE_IN_DIST_PATH,
+				'image/svg+xml',
+			);
+			readFileAsBufferSpy.mockRestore();
+
+			if (!response) {
+				throw new Error('Expected non-gzip file response');
+			}
+			expect(response.headers.get('Content-Type')).toBe('image/svg+xml');
+			expect(response.headers.get('Content-Encoding')).toBeNull();
+		});
+	});
+});

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

@@ -0,0 +1,96 @@
+import { STATUS_MESSAGE } from '../../config/constants.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { FileSystemServerOptions } from '../../types/internal-types.ts';
+import type { RouteRendererBody } from '../../types/public-types.ts';
+import { fileSystem } from '@ecopages/file-system';
+
+/**
+ * Builds HTTP responses for static files and shared file-system fallbacks.
+ */
+export class FileSystemServerResponseFactory {
+	private options: FileSystemServerOptions;
+
+	constructor({ options }: { options: FileSystemServerOptions }) {
+		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,
+		});
+	}
+
+	/**
+	 * Wraps already-rendered HTML in a 404 response envelope.
+	 */
+	async createHtmlNotFoundResponse(body: RouteRendererBody) {
+		return await this.createResponseWithBody(body, {
+			status: 404,
+			statusText: STATUS_MESSAGE[404],
+			headers: {
+				'Content-Type': 'text/html',
+			},
+		});
+	}
+
+	/**
+	 * Reads a static file response, returning `null` when the file is missing.
+	 */
+	async createFileResponse(filePath: string, contentType: string): Promise<Response | null> {
+		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 null;
+		}
+	}
+}

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

@@ -0,0 +1,311 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fileSystem } from '@ecopages/file-system';
+import path from 'node:path';
+import { APP_TEST_ROUTES, FIXTURE_APP_PROJECT_DIR, INDEX_TEMPLATE_FILE } from '../../../__fixtures__/constants.ts';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import type { MatchResult } from '../../types/internal-types.ts';
+import { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
+import { RouteRegistry } from '../../router/server/route-registry.ts';
+import { MemoryCacheStore } from '../../services/cache/memory-cache-store.ts';
+import { PageCacheService } from '../../services/cache/page-cache-service.ts';
+import { FileSystemServerResponseFactory } from './fs-server-response-factory.ts';
+import { FileSystemResponseMatcher } from './fs-server-response-matcher.ts';
+
+const appConfig = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+for (const integration of appConfig.integrations) {
+	integration.setConfig(appConfig);
+	integration.setRuntimeOrigin(appConfig.baseUrl);
+}
+
+const router = new RouteRegistry({
+	pagesDir: path.join(appConfig.rootDir, appConfig.srcDir, appConfig.pagesDir),
+	appConfig,
+	origin: appConfig.baseUrl,
+	templatesExt: appConfig.templatesExt,
+	buildMode: false,
+	pageModuleAdapter: {
+		loadPageModule: vi.fn(async () => ({})),
+	},
+});
+
+await router.init();
+
+const routeRendererFactory = new RouteRendererFactory({
+	appConfig,
+	runtimeOrigin: appConfig.baseUrl,
+});
+
+const fileSystemResponseFactory = new FileSystemServerResponseFactory({
+	options: {
+		watchMode: false,
+	},
+});
+
+describe('FileSystemResponseMatcher', () => {
+	describe('without cache service', () => {
+		const matcherWithoutCache = new FileSystemResponseMatcher({
+			appConfig,
+			assetPrefix: path.join(appConfig.rootDir, appConfig.distDir),
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+		});
+
+		it('should return custom 404 page for unmatched request URL', async () => {
+			const requestUrl = APP_TEST_ROUTES.nonExistentFile;
+			const response = await matcherWithoutCache.handleNoMatch(requestUrl);
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should handle match with disabled cache headers', async () => {
+			const match: MatchResult = {
+				requestedPathname: APP_TEST_ROUTES.index,
+				templateRoute: {
+					kind: 'exact',
+					pathname: APP_TEST_ROUTES.index,
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: {},
+			};
+			const response = await matcherWithoutCache.handleMatch(match);
+			expect(response.headers.get('Content-Type')).toBe('text/html');
+			expect(response.headers.get('X-Cache')).toBe('DISABLED');
+			expect(response.headers.get('Cache-Control')).toBe('no-store, must-revalidate');
+		});
+
+		it('should return null for getCacheService when not configured', () => {
+			expect(matcherWithoutCache.getCacheService()).toBeNull();
+		});
+	});
+
+	describe('with cache service', () => {
+		const cacheService = new PageCacheService({
+			store: new MemoryCacheStore(),
+			enabled: true,
+		});
+
+		const matcherWithCache = new FileSystemResponseMatcher({
+			appConfig,
+			assetPrefix: path.join(appConfig.rootDir, appConfig.distDir),
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+			cacheService,
+			defaultCacheStrategy: 'static',
+		});
+
+		it('should return cache service via getCacheService', () => {
+			expect(matcherWithCache.getCacheService()).toBe(cacheService);
+		});
+
+		it('should return X-Cache header on first request (MISS)', async () => {
+			const match: MatchResult = {
+				requestedPathname: '/cache-test-miss',
+				templateRoute: {
+					kind: 'exact',
+					pathname: '/cache-test-miss',
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: {},
+			};
+			const response = await matcherWithCache.handleMatch(match);
+			expect(response.headers.get('X-Cache')).toBe('MISS');
+			expect(response.headers.get('Cache-Control')).toBe('public, max-age=31536000, immutable');
+		});
+
+		it('should return X-Cache HIT on second request to same path', async () => {
+			const uniquePath = `/cache-test-hit-${Date.now()}`;
+			const match: MatchResult = {
+				requestedPathname: uniquePath,
+				templateRoute: {
+					kind: 'exact',
+					pathname: uniquePath,
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: {},
+			};
+
+			const response1 = await matcherWithCache.handleMatch(match);
+			const response2 = await matcherWithCache.handleMatch(match);
+
+			expect(response1.headers.get('X-Cache')).toBe('MISS');
+			expect(response2.headers.get('X-Cache')).toBe('HIT');
+		});
+
+		it('should cache different paths separately', async () => {
+			const match1: MatchResult = {
+				requestedPathname: '/path-a',
+				templateRoute: {
+					kind: 'exact',
+					pathname: '/path-a',
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: {},
+			};
+			const match2: MatchResult = {
+				requestedPathname: '/path-b',
+				templateRoute: {
+					kind: 'exact',
+					pathname: '/path-b',
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: {},
+			};
+
+			const response1 = await matcherWithCache.handleMatch(match1);
+			const response2 = await matcherWithCache.handleMatch(match2);
+
+			expect(response1.headers.get('X-Cache')).toBe('MISS');
+			expect(response2.headers.get('X-Cache')).toBe('MISS');
+		});
+
+		it('should include query params in cache key', async () => {
+			const basePath = `/search-${Date.now()}`;
+			const matchWithQuery: MatchResult = {
+				requestedPathname: basePath,
+				templateRoute: {
+					kind: 'exact',
+					pathname: basePath,
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: { q: 'test' },
+			};
+			const matchWithDifferentQuery: MatchResult = {
+				requestedPathname: basePath,
+				templateRoute: {
+					kind: 'exact',
+					pathname: basePath,
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: { q: 'other' },
+			};
+
+			const firstCall = await matcherWithCache.handleMatch(matchWithQuery);
+			const response1 = await matcherWithCache.handleMatch(matchWithQuery);
+			const response2 = await matcherWithCache.handleMatch(matchWithDifferentQuery);
+
+			expect(firstCall.headers.get('X-Cache')).toBe('MISS');
+			expect(response1.headers.get('X-Cache')).toBe('HIT');
+			expect(response2.headers.get('X-Cache')).toBe('MISS');
+		});
+	});
+
+	describe('with dynamic cache strategy', () => {
+		const cacheService = new PageCacheService({
+			store: new MemoryCacheStore(),
+			enabled: true,
+		});
+
+		const dynamicMatcher = new FileSystemResponseMatcher({
+			appConfig,
+			assetPrefix: path.join(appConfig.rootDir, appConfig.distDir),
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+			cacheService,
+			defaultCacheStrategy: 'dynamic',
+		});
+
+		it('should bypass cache entirely for dynamic strategy', async () => {
+			const match: MatchResult = {
+				requestedPathname: '/dynamic-page',
+				templateRoute: {
+					kind: 'exact',
+					pathname: '/dynamic-page',
+					filePath: INDEX_TEMPLATE_FILE,
+				},
+				params: {},
+				query: {},
+			};
+
+			const response1 = await dynamicMatcher.handleMatch(match);
+			const response2 = await dynamicMatcher.handleMatch(match);
+
+			expect(response1.headers.get('X-Cache')).toBe('DISABLED');
+			expect(response2.headers.get('X-Cache')).toBe('DISABLED');
+			expect(response1.headers.get('Cache-Control')).toBe('no-store, must-revalidate');
+		});
+	});
+
+	describe('handleNoMatch content type behavior', () => {
+		const matcher = new FileSystemResponseMatcher({
+			appConfig,
+			assetPrefix: path.join(appConfig.rootDir, appConfig.distDir),
+			router,
+			routeRendererFactory,
+			fileSystemResponseFactory,
+		});
+
+		it('should return custom 404 page for known extension like .html', async () => {
+			const response = await matcher.handleNoMatch('/non-existent-page.html');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should return custom 404 page for page requests without extension', async () => {
+			const response = await matcher.handleNoMatch('/non-existent-page');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should return custom 404 page for unknown extensions', async () => {
+			const response = await matcher.handleNoMatch('/page.xyz');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should return custom 404 page for trailing dot', async () => {
+			const response = await matcher.handleNoMatch('/page.');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+
+		it('should serve text/plain files from disk', async () => {
+			const readFileAsBuffer = vi.spyOn(fileSystem, 'readFileAsBuffer').mockReturnValue(Buffer.from('robots'));
+			const response = await matcher.handleNoMatch('/robots.txt');
+			readFileAsBuffer.mockRestore();
+			expect(response.headers.get('Content-Type')).toBe('text/plain');
+		});
+
+		it('should return custom 404 page for non-existent static files', async () => {
+			const response = await matcher.handleNoMatch('/non-existent.txt');
+			const body = await response.text();
+			expect(body).toContain('<h1>404 - Page Not Found</h1>');
+		});
+	});
+
+	describe('internal transpile output', () => {
+		it('should inspect page modules through the owning route renderer', async () => {
+			const matcher = new FileSystemResponseMatcher({
+				appConfig,
+				assetPrefix: path.join(appConfig.rootDir, appConfig.distDir),
+				router,
+				routeRendererFactory,
+				fileSystemResponseFactory,
+			});
+
+			const loadPageModule = vi.fn(async () => ({}));
+			(matcher as any).routeRendererFactory = {
+				getPageRenderer: vi.fn(() => ({
+					loadPageModule,
+				})),
+			};
+
+			await (matcher as any).importPageModule(INDEX_TEMPLATE_FILE);
+
+			expect((matcher as any).routeRendererFactory.getPageRenderer).toHaveBeenCalledWith(INDEX_TEMPLATE_FILE);
+			expect(loadPageModule).toHaveBeenCalledWith(INDEX_TEMPLATE_FILE, {
+				cacheScope: 'request-metadata',
+			});
+		});
+	});
+});