@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.32

package/src/adapters/shared/http/fs-server-response-matcher.js

@@ -1,268 +1,250 @@
-import path from "node:path";
-import { appLogger } from "../../../global/app-logger.js";
-import { PageRequestCacheCoordinator } from "../../../services/cache/page-request-cache-coordinator.service.js";
-import { ServerUtils } from "../../../utils/server-utils.module.js";
-import { FileRouteMiddlewarePipeline } from "./file-route-middleware-pipeline.js";
-import { LocalsAccessError } from "../../../errors/locals-access-error.js";
-import { isDevelopmentRuntime } from "../../../utils/runtime.js";
-class FileSystemResponseMatcher {
-  appConfig;
-  assetPrefix;
-  router;
-  routeRendererFactory;
-  fileSystemResponseFactory;
-  pageRequestCacheCoordinator;
-  fileRouteMiddlewarePipeline;
-  constructor({
-    appConfig,
-    assetPrefix,
-    router,
-    routeRendererFactory,
-    fileSystemResponseFactory,
-    cacheService = null,
-    defaultCacheStrategy = "static"
-  }) {
-    this.appConfig = appConfig;
-    this.assetPrefix = assetPrefix;
-    this.router = router;
-    this.routeRendererFactory = routeRendererFactory;
-    this.fileSystemResponseFactory = fileSystemResponseFactory;
-    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) {
-    const isStaticFileRequest = ServerUtils.hasKnownStaticExtension(requestUrl);
-    if (!isStaticFileRequest) {
-      return this.renderCustomNotFoundResponseOrServerError(requestUrl);
+import path from 'node:path';
+import { appLogger } from '../../../global/app-logger.js';
+import { PageRequestCacheCoordinator } from '../../../services/cache/page-request-cache-coordinator.service.js';
+import { ServerUtils } from '../../../utils/server-utils.module.js';
+import { FileRouteMiddlewarePipeline } from './file-route-middleware-pipeline.js';
+import { LocalsAccessError } from '../../../errors/locals-access-error.js';
+import { isDevelopmentRuntime } from '../../../utils/runtime.js';
+/**
+ * Matches file-system routes to rendered HTML responses.
+ *
+ * This render pipeline coordinates page module inspection, request-local policy,
+ * renderer invocation, middleware execution, cache integration, and fallback
+ * error translation.
+ */
+export class FileSystemResponseMatcher {
+    appConfig;
+    assetPrefix;
+    router;
+    routeRendererFactory;
+    fileSystemResponseFactory;
+    pageRequestCacheCoordinator;
+    fileRouteMiddlewarePipeline;
+    constructor({ appConfig, assetPrefix, router, routeRendererFactory, fileSystemResponseFactory, cacheService = null, defaultCacheStrategy = 'static', }) {
+        this.appConfig = appConfig;
+        this.assetPrefix = assetPrefix;
+        this.router = router;
+        this.routeRendererFactory = routeRendererFactory;
+        this.fileSystemResponseFactory = fileSystemResponseFactory;
+        this.pageRequestCacheCoordinator = new PageRequestCacheCoordinator(cacheService, defaultCacheStrategy);
+        this.fileRouteMiddlewarePipeline = new FileRouteMiddlewarePipeline(cacheService);
     }
-    const relativeUrl = requestUrl.startsWith("/") ? requestUrl.slice(1) : requestUrl;
-    const filePath = path.join(this.assetPrefix, relativeUrl);
-    const contentType = ServerUtils.getContentType(filePath);
-    const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
-    return response ?? this.renderCustomNotFoundResponseOrServerError(requestUrl);
-  }
-  /**
-   * 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, request) {
-    try {
-      const executionPlan = await this.createExecutionPlan(match, request);
-      this.fileRouteMiddlewarePipeline.assertValidConfiguration({
-        middleware: executionPlan.pageMiddleware,
-        pageCacheStrategy: executionPlan.pageCacheStrategy,
-        filePath: executionPlan.pageFilePath
-      });
-      const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
-      const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
-        request: executionPlan.request,
-        params: match.params,
-        locals: executionPlan.localsStore
-      });
-      const renderFn = async () => {
-        const result = await routeRenderer.execute({
-          file: executionPlan.pageFilePath,
-          params: match.params,
-          query: match.query,
-          locals: executionPlan.localsForRender
+    /**
+     * 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) {
+        const isStaticFileRequest = ServerUtils.hasKnownStaticExtension(requestUrl);
+        if (!isStaticFileRequest) {
+            return this.renderCustomNotFoundResponseOrServerError(requestUrl);
+        }
+        const relativeUrl = requestUrl.startsWith('/') ? requestUrl.slice(1) : requestUrl;
+        const filePath = path.join(this.assetPrefix, relativeUrl);
+        const contentType = ServerUtils.getContentType(filePath);
+        const response = await this.fileSystemResponseFactory.createFileResponse(filePath, contentType);
+        return response ?? this.renderCustomNotFoundResponseOrServerError(requestUrl);
+    }
+    /**
+     * 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, request) {
+        try {
+            const executionPlan = await this.createExecutionPlan(match, request);
+            this.fileRouteMiddlewarePipeline.assertValidConfiguration({
+                middleware: executionPlan.pageMiddleware,
+                pageCacheStrategy: executionPlan.pageCacheStrategy,
+                filePath: executionPlan.pageFilePath,
+            });
+            const routeRenderer = this.routeRendererFactory.getPageRenderer(executionPlan.pageFilePath);
+            const middlewareContext = this.fileRouteMiddlewarePipeline.createContext({
+                request: executionPlan.request,
+                params: match.params,
+                locals: executionPlan.localsStore,
+            });
+            const renderFn = async () => {
+                const result = await routeRenderer.execute({
+                    file: executionPlan.pageFilePath,
+                    params: match.params,
+                    query: match.query,
+                    locals: executionPlan.localsForRender,
+                });
+                const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
+                const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+                return { html, strategy };
+            };
+            const renderResponse = async () => {
+                return this.pageRequestCacheCoordinator.render({
+                    cacheKey: executionPlan.cacheKey,
+                    pageCacheStrategy: executionPlan.pageCacheStrategy,
+                    renderFn,
+                });
+            };
+            return await this.fileRouteMiddlewarePipeline.run({
+                middleware: executionPlan.pageMiddleware,
+                context: middlewareContext,
+                renderResponse,
+            });
+        }
+        catch (error) {
+            if (error instanceof Response) {
+                return error;
+            }
+            if (error instanceof LocalsAccessError) {
+                return await this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
+            }
+            return await this.createInternalServerErrorResponse(error instanceof Error ? error.message : 'Internal Server Error', match.requestedPathname, error);
+        }
+    }
+    /**
+     * Renders the app-owned custom 404 page, falling back to the default text 404
+     * when the page template cannot be resolved.
+     */
+    async renderCustomNotFoundResponse() {
+        return this.renderCustomErrorPageResponse({
+            templatePath: this.appConfig.absolutePaths.error404TemplatePath,
+            label: '404',
+            createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultNotFoundResponse(),
+            createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlNotFoundResponse(body),
         });
-        const html = await this.pageRequestCacheCoordinator.bodyToString(result.body);
-        const strategy = result.cacheStrategy ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-        return { html, strategy };
-      };
-      const renderResponse = async () => {
-        return this.pageRequestCacheCoordinator.render({
-          cacheKey: executionPlan.cacheKey,
-          pageCacheStrategy: executionPlan.pageCacheStrategy,
-          renderFn
+    }
+    /**
+     * Renders the app-owned custom 500 page, falling back to the default text 500
+     * when the page template cannot be resolved.
+     */
+    async renderCustomServerErrorResponse(error) {
+        return this.renderCustomErrorPageResponse({
+            templatePath: this.appConfig.absolutePaths.error500TemplatePath,
+            label: '500',
+            props: this.buildServerErrorPageProps(error),
+            createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultServerErrorResponse(),
+            createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlServerErrorResponse(body),
         });
-      };
-      return await this.fileRouteMiddlewarePipeline.run({
-        middleware: executionPlan.pageMiddleware,
-        context: middlewareContext,
-        renderResponse
-      });
-    } catch (error) {
-      if (error instanceof Response) {
-        return error;
-      }
-      if (error instanceof LocalsAccessError) {
-        return await this.createInternalServerErrorResponse(error.message, match.requestedPathname, error);
-      }
-      return await this.createInternalServerErrorResponse(
-        error instanceof Error ? error.message : "Internal Server Error",
-        match.requestedPathname,
-        error
-      );
     }
-  }
-  /**
-   * Renders the app-owned custom 404 page, falling back to the default text 404
-   * when the page template cannot be resolved.
-   */
-  async renderCustomNotFoundResponse() {
-    return this.renderCustomErrorPageResponse({
-      templatePath: this.appConfig.absolutePaths.error404TemplatePath,
-      label: "404",
-      createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultNotFoundResponse(),
-      createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlNotFoundResponse(body)
-    });
-  }
-  /**
-   * Renders the app-owned custom 500 page, falling back to the default text 500
-   * when the page template cannot be resolved.
-   */
-  async renderCustomServerErrorResponse(error) {
-    return this.renderCustomErrorPageResponse({
-      templatePath: this.appConfig.absolutePaths.error500TemplatePath,
-      label: "500",
-      props: this.buildServerErrorPageProps(error),
-      createDefaultResponse: () => this.fileSystemResponseFactory.createDefaultServerErrorResponse(),
-      createHtmlResponse: (body) => this.fileSystemResponseFactory.createHtmlServerErrorResponse(body)
-    });
-  }
-  /**
-   * Builds development-only error details for the custom 500 page.
-   * @remarks Production omits these fields so stacks are not serialized into HTML.
-   */
-  buildServerErrorPageProps(error) {
-    if (!isDevelopmentRuntime()) {
-      return void 0;
+    /**
+     * Builds development-only error details for the custom 500 page.
+     * @remarks Production omits these fields so stacks are not serialized into HTML.
+     */
+    buildServerErrorPageProps(error) {
+        if (!isDevelopmentRuntime()) {
+            return undefined;
+        }
+        if (error instanceof Error) {
+            return {
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        return {
+            message: String(error),
+        };
     }
-    if (error instanceof Error) {
-      return {
-        message: error.message,
-        stack: error.stack
-      };
+    async renderCustomErrorPageResponse({ templatePath, label, props, createDefaultResponse, createHtmlResponse, }) {
+        let routeRenderer;
+        try {
+            routeRenderer = this.routeRendererFactory.getPageRenderer(templatePath);
+        }
+        catch {
+            appLogger.debug(`Custom ${label} template not found, falling back to default ${label} response`, templatePath);
+            return createDefaultResponse();
+        }
+        const result = await routeRenderer.execute({
+            file: templatePath,
+            props,
+        });
+        return createHtmlResponse(result.body);
+    }
+    async renderCustomNotFoundResponseOrServerError(pathname) {
+        try {
+            return await this.renderCustomNotFoundResponse();
+        }
+        catch (error) {
+            if (error instanceof Response) {
+                return error;
+            }
+            return await this.createInternalServerErrorResponse(error instanceof Error ? error.message : 'Internal Server Error', pathname, error);
+        }
     }
-    return {
-      message: String(error)
-    };
-  }
-  async renderCustomErrorPageResponse({
-    templatePath,
-    label,
-    props,
-    createDefaultResponse,
-    createHtmlResponse
-  }) {
-    let routeRenderer;
-    try {
-      routeRenderer = this.routeRendererFactory.getPageRenderer(templatePath);
-    } catch {
-      appLogger.debug(
-        `Custom ${label} template not found, falling back to default ${label} response`,
-        templatePath
-      );
-      return createDefaultResponse();
+    /**
+     * Logs the original render failure, then tries the custom 500 page once.
+     * @remarks Any failure while rendering the custom 500 page falls back to the
+     * default plain-text response and never re-enters the custom page path.
+     * In development the thrown error's `message` and `stack` are passed into the
+     * custom 500 page props.
+     */
+    async createInternalServerErrorResponse(message, pathname, error) {
+        if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
+            appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
+        }
+        else {
+            appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
+        }
+        try {
+            return await this.renderCustomServerErrorResponse(error);
+        }
+        catch (serverErrorPageError) {
+            if (serverErrorPageError instanceof Response) {
+                return serverErrorPageError;
+            }
+            appLogger.error(`[FileSystemResponseMatcher] Custom 500 template failed at ${pathname}`, serverErrorPageError);
+            return this.fileSystemResponseFactory.createDefaultServerErrorResponse();
+        }
     }
-    const result = await routeRenderer.execute({
-      file: templatePath,
-      props
-    });
-    return createHtmlResponse(result.body);
-  }
-  async renderCustomNotFoundResponseOrServerError(pathname) {
-    try {
-      return await this.renderCustomNotFoundResponse();
-    } catch (error) {
-      if (error instanceof Response) {
-        return error;
-      }
-      return await this.createInternalServerErrorResponse(
-        error instanceof Error ? error.message : "Internal Server Error",
-        pathname,
-        error
-      );
+    async createExecutionPlan(match, request) {
+        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 = {};
+        const pageFilePath = match.templateRoute.filePath;
+        const pageModule = await this.importPageModule(pageFilePath);
+        const Page = pageModule?.default;
+        const pageMiddleware = (Page?.middleware ?? []);
+        const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
+        return {
+            cacheKey,
+            request: resolvedRequest,
+            pageFilePath,
+            pageMiddleware,
+            pageCacheStrategy,
+            localsStore,
+            localsForRender: pageCacheStrategy === 'dynamic' ? localsStore : undefined,
+        };
     }
-  }
-  /**
-   * Logs the original render failure, then tries the custom 500 page once.
-   * @remarks Any failure while rendering the custom 500 page falls back to the
-   * default plain-text response and never re-enters the custom page path.
-   * In development the thrown error's `message` and `stack` are passed into the
-   * custom 500 page props.
-   */
-  async createInternalServerErrorResponse(message, pathname, error) {
-    if (isDevelopmentRuntime() || appLogger.isDebugEnabled()) {
-      appLogger.error(`[FileSystemResponseMatcher] ${message} at ${pathname}`, error);
-    } else {
-      appLogger.error(`[FileSystemResponseMatcher] Render error at ${pathname}`, error);
+    /**
+     * 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 asks the owning route
+     * renderer to load the page module. That preserves integration-specific page
+     * import setup for request-time inspection as well as for full rendering.
+     *
+     * @param filePath Absolute page module path.
+     * @returns Imported page module.
+     */
+    async importPageModule(filePath) {
+        const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
+        return routeRenderer.loadPageModule(filePath, {
+            cacheScope: 'request-metadata',
+        });
     }
-    try {
-      return await this.renderCustomServerErrorResponse(error);
-    } catch (serverErrorPageError) {
-      if (serverErrorPageError instanceof Response) {
-        return serverErrorPageError;
-      }
-      appLogger.error(
-        `[FileSystemResponseMatcher] Custom 500 template failed at ${pathname}`,
-        serverErrorPageError
-      );
-      return this.fileSystemResponseFactory.createDefaultServerErrorResponse();
+    /**
+     * Get the underlying cache service for external invalidation.
+     */
+    getCacheService() {
+        return this.pageRequestCacheCoordinator.getCacheService();
     }
-  }
-  async createExecutionPlan(match, request) {
-    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 = {};
-    const pageFilePath = match.templateRoute.filePath;
-    const pageModule = await this.importPageModule(pageFilePath);
-    const Page = pageModule?.default;
-    const pageMiddleware = Page?.middleware ?? [];
-    const pageCacheStrategy = Page?.cache ?? this.pageRequestCacheCoordinator.getDefaultCacheStrategy();
-    return {
-      cacheKey,
-      request: resolvedRequest,
-      pageFilePath,
-      pageMiddleware,
-      pageCacheStrategy,
-      localsStore,
-      localsForRender: pageCacheStrategy === "dynamic" ? localsStore : void 0
-    };
-  }
-  /**
-   * 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 asks the owning route
-   * renderer to load the page module. That preserves integration-specific page
-   * import setup for request-time inspection as well as for full rendering.
-   *
-   * @param filePath Absolute page module path.
-   * @returns Imported page module.
-   */
-  async importPageModule(filePath) {
-    const routeRenderer = this.routeRendererFactory.getPageRenderer(filePath);
-    return routeRenderer.loadPageModule(filePath, {
-      cacheScope: "request-metadata"
-    });
-  }
-  /**
-   * Get the underlying cache service for external invalidation.
-   */
-  getCacheService() {
-    return this.pageRequestCacheCoordinator.getCacheService();
-  }
 }
-export {
-  FileSystemResponseMatcher
-};

package/src/adapters/shared/http/run-middleware-chain.js

@@ -1,17 +1,17 @@
-async function runMiddlewareChain(middleware, context, terminal) {
-  if (middleware.length === 0) {
-    return terminal();
-  }
-  let index = 0;
-  const executeNext = async () => {
-    if (index < middleware.length) {
-      const current = middleware[index++];
-      return await current(context, executeNext);
+/**
+ * Runs an onion middleware chain and invokes the terminal handler when the chain completes.
+ */
+export async function runMiddlewareChain(middleware, context, terminal) {
+    if (middleware.length === 0) {
+        return terminal();
     }
-    return terminal();
-  };
-  return executeNext();
+    let index = 0;
+    const executeNext = async () => {
+        if (index < middleware.length) {
+            const current = middleware[index++];
+            return await current(context, executeNext);
+        }
+        return terminal();
+    };
+    return executeNext();
 }
-export {
-  runMiddlewareChain
-};