@ecopages/core 0.2.0-alpha.54 → 0.2.0-alpha.55

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

@@ -1,131 +0,0 @@
-import { appLogger } from '../../global/app-logger.ts';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import type { StaticRoute } from '../../types/public-types.ts';
-import type { ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.ts';
-import { prepareExplicitStaticRender } from './explicit-static-render-preparation.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;
-
-export interface ExplicitStaticRouteMatcherOptions {
-	appConfig: EcoPagesAppConfig;
-	routeRendererFactory: ExplicitViewRendererResolver;
-	staticRoutes: StaticRoute[];
-}
-
-export interface ExplicitRouteMatch {
-	route: StaticRoute;
-	params: Record<string, string>;
-}
-
-/**
- * Matches and renders explicit static routes declared through `app.static()`.
- */
-export class ExplicitStaticRouteMatcher {
-	private readonly appConfig: EcoPagesAppConfig;
-	private readonly routeRendererFactory: ExplicitViewRendererResolver;
-	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 {
-				renderer,
-				props,
-				view: renderableView,
-			} = await prepareExplicitStaticRender({
-				routePath: route.path,
-				view,
-				params,
-				appConfig: this.appConfig,
-				runtimeOrigin: this.appConfig.baseUrl,
-				routeRendererFactory: this.routeRendererFactory,
-				errors: EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS,
-			});
-
-			return renderer.renderToResponse(renderableView, 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.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type { FileRouteMiddleware } from '../../types/public-types.ts';
-import { LocalsAccessError } from '../../errors/locals-access-error.ts';
-import {
-	FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS,
-	FileRouteMiddlewarePipeline,
-} from './file-route-middleware-pipeline.ts';
-
-declare module '../../types/public-types.ts' {
-	interface RequestLocals {
-		user?: string;
-		first?: boolean;
-	}
-}
-
-describe('FileRouteMiddlewarePipeline', () => {
-	it('should reject middleware on non-dynamic pages', () => {
-		const service = new FileRouteMiddlewarePipeline(null);
-
-		expect(() =>
-			service.assertValidConfiguration({
-				middleware: [async (_ctx, next) => next()],
-				pageCacheStrategy: 'static',
-				filePath: '/app/pages/index.tsx',
-			}),
-		).toThrowError(
-			new LocalsAccessError(
-				FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.middlewareRequiresDynamic('/app/pages/index.tsx'),
-			),
-		);
-	});
-
-	it('should create middleware context without handler render methods', async () => {
-		const service = new FileRouteMiddlewarePipeline(null);
-		const context = service.createContext({
-			request: new Request('http://localhost:3000/hello'),
-			params: { slug: 'hello' },
-			locals: { user: 'andee' },
-		});
-
-		expect('render' in context).toBe(false);
-		expect('renderPartial' in context).toBe(false);
-
-		expect(context.require('user', () => new Response('missing', { status: 500 }))).toBe('andee');
-		expect(await context.html('<p>ok</p>').text()).toContain('<p>ok</p>');
-		expect(await context.json({ ok: true }).text()).toContain('{"ok":true}');
-	});
-
-	it('should execute middleware in order and eventually render the response', async () => {
-		const service = new FileRouteMiddlewarePipeline(null);
-		const context = service.createContext({
-			request: new Request('http://localhost:3000/hello'),
-			params: {},
-			locals: {},
-		});
-		const events: string[] = [];
-
-		const middleware: FileRouteMiddleware[] = [
-			async (ctx, next) => {
-				events.push('first:before');
-				ctx.locals.first = true;
-				const response = await next();
-				events.push('first:after');
-				return response;
-			},
-			async (ctx, next) => {
-				events.push('second');
-				expect(ctx.locals.first).toBe(true);
-				return next();
-			},
-		];
-
-		const response = await service.run({
-			middleware,
-			context,
-			renderResponse: async () => {
-				events.push('render');
-				return new Response('done');
-			},
-		});
-
-		expect(await response.text()).toBe('done');
-		expect(events).toEqual(['first:before', 'second', 'render', 'first:after']);
-	});
-});

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

@@ -1,118 +0,0 @@
-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

@@ -1,176 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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;
-		}
-	}
-}