@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,198 @@
+import path from 'node:path';
+import { appLogger } from '../../global/app-logger.ts';
+import type { MatchResult } from '../../internal-types.ts';
+import type { RouteRendererFactory } from '../../route-renderer/route-renderer.ts';
+import type { FSRouter } from '../../router/fs-router.ts';
+import type { PageCacheService } from '../../services/cache/page-cache-service.ts';
+import type { CacheStrategy, RenderResult } from '../../services/cache/cache.types.ts';
+import { PageModuleImportService } from '../../services/page-module-import.service.ts';
+import { PageRequestCacheCoordinator } from '../../services/page-request-cache-coordinator.service.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 {
+	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 router: FSRouter;
+	private routeRendererFactory: RouteRendererFactory;
+	private fileSystemResponseFactory: FileSystemServerResponseFactory;
+	private pageModuleImportService: PageModuleImportService;
+	private pageRequestCacheCoordinator: PageRequestCacheCoordinator;
+	private fileRouteMiddlewarePipeline: FileRouteMiddlewarePipeline;
+
+	constructor({
+		router,
+		routeRendererFactory,
+		fileSystemResponseFactory,
+		cacheService = null,
+		defaultCacheStrategy = 'static',
+	}: FileSystemResponseMatcherOptions) {
+		this.router = router;
+		this.routeRendererFactory = routeRendererFactory;
+		this.fileSystemResponseFactory = fileSystemResponseFactory;
+		this.pageModuleImportService = new PageModuleImportService();
+		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.
+	 *
+	 * @param filePath Absolute page module path.
+	 * @returns Imported page module.
+	 */
+	private async importPageModule(filePath: string): Promise<unknown> {
+		return this.pageModuleImportService.importModule({
+			filePath,
+			rootDir: path.dirname(this.router.assetPrefix),
+			outdir: path.join(this.router.assetPrefix, '.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();
+	}
+}

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

@@ -0,0 +1,14 @@
+import type { RenderContext } from '../../public-types.js';
+import type { IntegrationPlugin } from '../../plugins/integration-plugin.js';
+export interface CreateRenderContextOptions {
+    integrations: IntegrationPlugin[];
+}
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export declare function createRenderContext(options: CreateRenderContextOptions): RenderContext;

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

@@ -0,0 +1,69 @@
+import { invariant } from "../../utils/invariant.js";
+function mergePropsWithLocals(props, locals) {
+  if (!locals || typeof props !== "object" || props === null) {
+    return props;
+  }
+  return { ...props, locals };
+}
+function createRenderContext(options) {
+  const { integrations } = options;
+  const getRendererForView = (view) => {
+    const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
+    invariant(
+      !!integrationName,
+      "Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension."
+    );
+    const integration = integrations.find((i) => i.name === integrationName);
+    invariant(!!integration, `No integration found for: ${integrationName}`);
+    return integration.initializeRenderer();
+  };
+  return {
+    async render(view, props, renderOptions) {
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: false,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return renderer.renderToResponse(view, mergedProps, ctx);
+    },
+    async renderPartial(view, props, renderOptions) {
+      const locals = this?.locals;
+      const mergedProps = mergePropsWithLocals(props, locals);
+      const renderer = getRendererForView(view);
+      const ctx = {
+        partial: true,
+        status: renderOptions?.status,
+        headers: renderOptions?.headers
+      };
+      return renderer.renderToResponse(view, mergedProps, ctx);
+    },
+    json(data, responseOptions) {
+      const headers = new Headers({ "Content-Type": "application/json; charset=utf-8" });
+      if (responseOptions?.headers) {
+        const incomingHeaders = new Headers(responseOptions.headers);
+        incomingHeaders.forEach((value, key) => headers.set(key, value));
+      }
+      return new Response(JSON.stringify(data), {
+        status: responseOptions?.status ?? 200,
+        headers
+      });
+    },
+    html(content, responseOptions) {
+      const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+      if (responseOptions?.headers) {
+        const incomingHeaders = new Headers(responseOptions.headers);
+        incomingHeaders.forEach((value, key) => headers.set(key, value));
+      }
+      return new Response(content, {
+        status: responseOptions?.status ?? 200,
+        headers
+      });
+    }
+  };
+}
+export {
+  createRenderContext
+};

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

@@ -0,0 +1,105 @@
+import type { EcoComponent, RenderContext, RenderOptions, ResponseOptions } from '../../public-types.ts';
+import type { IntegrationRenderer, RenderToResponseContext } from '../../route-renderer/integration-renderer.ts';
+import type { IntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import { invariant } from '../../utils/invariant.ts';
+
+export interface CreateRenderContextOptions {
+	integrations: IntegrationPlugin[];
+}
+
+/**
+ * Merges request locals into component props as a dedicated 'locals' property.
+ * This prevents naming conflicts and maintains type safety by keeping locals
+ * separate from other props.
+ *
+ * @param props - The original component props
+ * @param locals - Optional request-scoped locals from middleware
+ * @returns Props with locals merged in, or original props if no locals provided
+ */
+function mergePropsWithLocals<P>(props: P, locals: Record<string, unknown> | undefined): P {
+	if (!locals || typeof props !== 'object' || props === null) {
+		return props;
+	}
+	return { ...(props as Record<string, unknown>), locals } as P;
+}
+
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export function createRenderContext(options: CreateRenderContextOptions): RenderContext {
+	const { integrations } = options;
+
+	/**
+	 * Resolves the appropriate renderer for a given view component based on its integration.
+	 * Throws an error if the integration cannot be determined or is not found.
+	 */
+	const getRendererForView = <P>(view: EcoComponent<P>): IntegrationRenderer => {
+		const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
+		invariant(
+			!!integrationName,
+			'Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension.',
+		);
+
+		const integration = integrations.find((i) => i.name === integrationName);
+		invariant(!!integration, `No integration found for: ${integrationName}`);
+
+		return integration.initializeRenderer();
+	};
+
+	return {
+		async render<P>(view: EcoComponent<P>, props: P, renderOptions?: RenderOptions): Promise<Response> {
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals(props, locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: false,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+			return renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		async renderPartial<P>(view: EcoComponent<P>, props: P, renderOptions?: RenderOptions): Promise<Response> {
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals(props, locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: true,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+			return renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		json(data: unknown, responseOptions?: ResponseOptions): Response {
+			const headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' });
+			if (responseOptions?.headers) {
+				const incomingHeaders = new Headers(responseOptions.headers);
+				incomingHeaders.forEach((value, key) => headers.set(key, value));
+			}
+			return new Response(JSON.stringify(data), {
+				status: responseOptions?.status ?? 200,
+				headers,
+			});
+		},
+
+		html(content: string, responseOptions?: ResponseOptions): Response {
+			const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8' });
+			if (responseOptions?.headers) {
+				const incomingHeaders = new Headers(responseOptions.headers);
+				incomingHeaders.forEach((value, key) => headers.set(key, value));
+			}
+			return new Response(content, {
+				status: responseOptions?.status ?? 200,
+				headers,
+			});
+		},
+	};
+}

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

@@ -0,0 +1,87 @@
+import { AbstractServerAdapter } from '../abstract/server-adapter.js';
+import type { ServerAdapterOptions, ServerAdapterResult } from '../abstract/server-adapter.js';
+import { RouteRendererFactory } from '../../route-renderer/route-renderer.js';
+import { FSRouter } from '../../router/fs-router.js';
+import { SchemaValidationService } from '../../services/schema-validation-service.js';
+import { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
+import { ServerStaticBuilder } from './server-static-builder.js';
+import { FileSystemResponseMatcher } from './fs-server-response-matcher.js';
+import { ServerRouteHandler } from './server-route-handler.js';
+import type { ApiHandler, CacheInvalidator, ErrorHandler, RenderContext, StaticRoute } from '../../public-types.js';
+export declare 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: SchemaValidationService;
+    /**
+     * 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 initSharedRouter(): Promise<void>;
+    /**
+     * 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;
+    protected getCacheService(): CacheInvalidator | null;
+    protected getRenderContext(): RenderContext;
+    /**
+     * 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 executeApiHandler(request: Request, params: Record<string, string | string[]>, routeConfig: ApiHandler, serverInstance: any, errorHandler?: ErrorHandler): Promise<Response>;
+    private normalizePath;
+    private matchApiPath;
+    private getApiPathScore;
+    protected matchApiHandler(request: Request, apiHandlers: ApiHandler[]): {
+        routeConfig: ApiHandler;
+        params: Record<string, string | string[]>;
+    } | 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.
+     */
+    handleSharedRequest(request: Request, context: {
+        apiHandlers: ApiHandler[];
+        errorHandler?: ErrorHandler;
+        serverInstance?: any;
+        hmrManager?: any;
+    }): Promise<Response>;
+}