@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/adapters/shared/http/api-request-pipeline.js

@@ -0,0 +1,132 @@
+import { createRequire } from '../../../utils/locals-utils.js';
+import { HttpError } from '../../../errors/http-error.js';
+import { ApiResponseBuilder } from './api-response.js';
+import { runMiddlewareChain } from './run-middleware-chain.js';
+import { matchApiPathPattern, scoreApiPathPattern } from '../../abstract/segment-path-matcher.js';
+import { appLogger } from '../../../global/app-logger.js';
+export class ApiRequestPipeline {
+    schemaValidator;
+    getRenderContext;
+    getCacheService;
+    constructor(options) {
+        this.schemaValidator = options.schemaValidator;
+        this.getRenderContext = options.getRenderContext;
+        this.getCacheService = options.getCacheService;
+    }
+    match(request, apiHandlers) {
+        const pathname = new URL(request.url).pathname;
+        const method = request.method.toUpperCase();
+        const sortedHandlers = [...apiHandlers].sort((a, b) => {
+            return scoreApiPathPattern(b.path) - scoreApiPathPattern(a.path);
+        });
+        for (const routeConfig of sortedHandlers) {
+            const routeMethod = (routeConfig.method || 'GET').toUpperCase();
+            if (routeMethod !== method) {
+                continue;
+            }
+            const params = matchApiPathPattern(routeConfig.path, pathname);
+            if (params) {
+                return { routeConfig, params };
+            }
+        }
+        return null;
+    }
+    async tryHandle(request, apiHandlers, serverInstance, errorHandler) {
+        const apiMatch = this.match(request, apiHandlers);
+        if (!apiMatch) {
+            return null;
+        }
+        return await this.execute(request, apiMatch.params, apiMatch.routeConfig, serverInstance, errorHandler);
+    }
+    async execute(request, params, routeConfig, serverInstance, errorHandler) {
+        let context;
+        try {
+            context = this.createContext(request, params, serverInstance);
+            const schemaResponse = await this.applyRequestSchema(context, routeConfig.schema);
+            if (schemaResponse) {
+                return schemaResponse;
+            }
+            return await this.runMiddlewareChain(context, routeConfig);
+        }
+        catch (error) {
+            if (error instanceof Response)
+                return error;
+            if (errorHandler) {
+                try {
+                    if (!context) {
+                        context = this.createContext(request, params, serverInstance);
+                    }
+                    return await errorHandler(error, context);
+                }
+                catch (handlerError) {
+                    appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
+                }
+            }
+            if (error instanceof HttpError)
+                return error.toResponse();
+            appLogger.error(`[ecopages] Error handling API request: ${error}`);
+            return new Response('Internal Server Error', { status: 500 });
+        }
+    }
+    createContext(request, params, serverInstance) {
+        const locals = {};
+        const normalizedParams = this.normalizeParams(params);
+        return {
+            request,
+            params: normalizedParams,
+            response: new ApiResponseBuilder(),
+            server: serverInstance,
+            locals,
+            require: createRequire(() => locals),
+            services: {
+                cache: this.getCacheService(),
+            },
+            ...this.getRenderContext(),
+        };
+    }
+    normalizeParams(params) {
+        return Object.fromEntries(Object.entries(params).map(([key, value]) => [key, Array.isArray(value) ? value.join('/') : value]));
+    }
+    async applyRequestSchema(context, schema) {
+        if (!schema) {
+            return undefined;
+        }
+        const url = new URL(context.request.url);
+        const queryParams = Object.fromEntries(url.searchParams);
+        const headers = Object.fromEntries(context.request.headers);
+        let body;
+        if (schema.body) {
+            try {
+                const contentType = context.request.headers.get('Content-Type') || '';
+                if (contentType.includes('application/json'))
+                    body = await context.request.clone().json();
+                else if (contentType.includes('text/plain'))
+                    body = await context.request.clone().text();
+            }
+            catch {
+                return context.response.status(400).json({ error: 'Invalid request body' });
+            }
+        }
+        const validationResult = await this.schemaValidator.validateRequest({ body, query: queryParams, headers, params: context.params }, schema);
+        if (!validationResult.success) {
+            return context.response.status(400).json({
+                error: 'Validation failed',
+                issues: validationResult.errors,
+            });
+        }
+        const validated = validationResult.data;
+        if (validated.body !== undefined)
+            context.body = validated.body;
+        if (validated.query !== undefined)
+            context.query = validated.query;
+        if (validated.headers !== undefined)
+            context.headers = validated.headers;
+        if (validated.params !== undefined)
+            context.params = validated.params;
+        return undefined;
+    }
+    async runMiddlewareChain(context, routeConfig) {
+        const middleware = routeConfig.middleware ?? [];
+        return runMiddlewareChain(middleware, context, async () => await routeConfig.handler(context));
+    }
+}

package/src/adapters/shared/{api-response.d.ts → http/api-response.d.ts}

@@ -21,7 +21,7 @@ export declare class ApiResponseBuilder {
      * @param data - The data to serialize.
      * @returns A Response object.
      */
-    json(data: any): Response;
+    json(data: unknown): Response;
     /**
      * Creates a plain text response using the configured status and headers.
      * @param data - The text content.

package/src/adapters/shared/http/api-response.js

@@ -0,0 +1,79 @@
+import { createBodyResponse } from './create-body-response.js';
+/**
+ * A builder class for creating Response objects fluently.
+ */
+export class ApiResponseBuilder {
+    _status = 200;
+    _headers = new Headers();
+    /**
+     * Sets the HTTP status code for the response.
+     * @param code - The HTTP status code.
+     * @returns The builder instance for chaining.
+     */
+    status(code) {
+        this._status = code;
+        return this;
+    }
+    /**
+     * Adds or merges headers for the response.
+     * @param headersInit - Headers to add or merge.
+     * @returns The builder instance for chaining.
+     */
+    headers(headersInit) {
+        const inputHeaders = new Headers(headersInit);
+        inputHeaders.forEach((value, key) => {
+            this._headers.set(key, value);
+        });
+        return this;
+    }
+    /**
+     * Creates a JSON response using the configured status and headers.
+     * @param data - The data to serialize.
+     * @returns A Response object.
+     */
+    json(data) {
+        return createBodyResponse('json', data, { status: this._status, headers: this._headers });
+    }
+    /**
+     * Creates a plain text response using the configured status and headers.
+     * @param data - The text content.
+     * @returns A Response object.
+     */
+    text(data) {
+        return createBodyResponse('text', data, { status: this._status, headers: this._headers });
+    }
+    /**
+     * Creates an HTML response using the configured status and headers.
+     * @param data - The HTML content.
+     * @returns A Response object.
+     */
+    html(data) {
+        return createBodyResponse('html', data, { status: this._status, headers: this._headers });
+    }
+    /**
+     * Creates a redirect response.
+     * @param url - The URL to redirect to.
+     * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 302 if not set via status().
+     * @returns A Response object.
+     */
+    redirect(url, explicitStatus) {
+        const redirectStatus = explicitStatus ?? (this._status === 200 ? 302 : this._status); // Default to 302 if status wasn't explicitly set
+        this._headers.set('Location', url);
+        return new Response(null, { status: redirectStatus, headers: this._headers });
+    }
+    /**
+     * Creates an error response using the configured status and headers.
+     * If data is an object, it's treated as JSON, otherwise as text.
+     * @param data - The error data (string or object).
+     * @param explicitStatus - Optional explicit status code (overrides status() if provided). Defaults to 500 if not set via status().
+     * @returns A Response object.
+     */
+    error(data, explicitStatus) {
+        const errorStatus = explicitStatus ?? (this._status === 200 ? 500 : this._status); // Default to 500 if status wasn't explicitly set
+        this.status(errorStatus);
+        if (typeof data === 'object' && data !== null) {
+            return createBodyResponse('json', { error: data }, { status: this._status, headers: this._headers });
+        }
+        return createBodyResponse('text', String(data), { status: this._status, headers: this._headers });
+    }
+}

package/src/adapters/shared/http/create-body-response.d.ts

@@ -0,0 +1,12 @@
+export type BodyResponseKind = 'json' | 'html' | 'text';
+export type CreateBodyResponseInit = {
+    status?: Response['status'];
+    headers?: HeadersInit;
+};
+/**
+ * Builds a typed HTTP response body for JSON, HTML, or plain text.
+ *
+ * @remarks
+ * Sole internal emission path for adapter response helpers. Not exported from `@ecopages/core`.
+ */
+export declare function createBodyResponse(kind: BodyResponseKind, data: unknown, init?: CreateBodyResponseInit): Response;

package/src/adapters/shared/http/create-body-response.js

@@ -0,0 +1,26 @@
+/**
+ * Builds a typed HTTP response body for JSON, HTML, or plain text.
+ *
+ * @remarks
+ * Sole internal emission path for adapter response helpers. Not exported from `@ecopages/core`.
+ */
+export function createBodyResponse(kind, data, init) {
+    const headers = new Headers(init?.headers);
+    const status = init?.status ?? 200;
+    if (kind === 'json') {
+        if (!headers.has('Content-Type')) {
+            headers.set('Content-Type', 'application/json; charset=utf-8');
+        }
+        return new Response(JSON.stringify(data), { status, headers });
+    }
+    if (kind === 'html') {
+        if (!headers.has('Content-Type')) {
+            headers.set('Content-Type', 'text/html; charset=utf-8');
+        }
+        return new Response(String(data), { status, headers });
+    }
+    if (!headers.has('Content-Type')) {
+        headers.set('Content-Type', 'text/plain; charset=utf-8');
+    }
+    return new Response(String(data), { status, headers });
+}

package/src/adapters/shared/http/define-api-handler.d.ts

@@ -0,0 +1,90 @@
+import type { ApiHandler, ApiHandlerContext, Middleware, ResponseOptions, RouteSchema, TypedGroupHandlerContext } from '../../../types/public-types.js';
+type UniversalContext = ApiHandlerContext<Request, unknown>;
+type SchemaHandlerContext<TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
+type DefineApiHandlerInput<TPath extends string, TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema' | 'method'> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[];
+    schema?: TSchema;
+};
+export declare function defineApiHandler<TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: DefineApiHandlerInput<TPath, TSchema, TContext> & {
+    method: ApiHandler<TPath, Request, unknown>['method'];
+}): ApiHandler<TPath, Request, unknown>;
+declare const defineApiMethod: <M extends ApiHandler["method"]>(method: M) => <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: DefineApiHandlerInput<TPath, TSchema, TContext> & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineGet: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const definePost: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const definePut: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineDelete: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const definePatch: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineOptions: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare const defineHead: <const TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, "middleware" | "method" | "schema" | "handler"> & {
+    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, unknown, TContext>[] | undefined;
+    schema?: TSchema | undefined;
+} & {
+    path: TPath;
+}) => ApiHandler<TPath, Request, unknown>;
+export declare function json(data: unknown, options?: ResponseOptions): Response;
+export declare function html(content: string, options?: ResponseOptions): Response;
+export declare function redirect(url: string, status?: number): Response;
+export interface GroupHandler<TPrefix extends string = string> {
+    prefix: TPrefix;
+    middleware?: readonly Middleware<Request, unknown, any>[];
+    routes: readonly ApiHandler<string, Request, unknown>[];
+}
+type GroupDefineHandler<TContext extends UniversalContext> = {
+    <const TPath extends string, TSchema extends RouteSchema | undefined = undefined>(handler: DefineApiHandlerInput<TPath, TSchema, TContext> & {
+        path: TPath;
+        method: ApiHandler<TPath, Request, unknown>['method'];
+    }): ApiHandler<TPath, Request, unknown>;
+    get: ReturnType<typeof defineApiMethod<'GET'>>;
+    post: ReturnType<typeof defineApiMethod<'POST'>>;
+    put: ReturnType<typeof defineApiMethod<'PUT'>>;
+    delete: ReturnType<typeof defineApiMethod<'DELETE'>>;
+    patch: ReturnType<typeof defineApiMethod<'PATCH'>>;
+    options: ReturnType<typeof defineApiMethod<'OPTIONS'>>;
+    head: ReturnType<typeof defineApiMethod<'HEAD'>>;
+};
+export declare function defineGroupHandler<TPrefix extends string, TMiddleware extends readonly Middleware<Request, unknown, any>[] = [], TContext extends UniversalContext = TMiddleware extends readonly Middleware<Request, unknown, infer TGroupContext>[] ? TGroupContext : UniversalContext>(config: {
+    prefix: TPrefix;
+    middleware?: TMiddleware;
+    routes: (api: GroupDefineHandler<TContext>) => readonly ApiHandler<string, Request, unknown>[];
+}): GroupHandler<TPrefix>;
+export {};

package/src/adapters/shared/http/define-api-handler.js

@@ -0,0 +1,49 @@
+import { createBodyResponse } from './create-body-response.js';
+export function defineApiHandler(handler) {
+    return handler;
+}
+const defineApiMethod = (method) => (handler) => defineApiHandler({ ...handler, method });
+export const defineGet = defineApiMethod('GET');
+export const definePost = defineApiMethod('POST');
+export const definePut = defineApiMethod('PUT');
+export const defineDelete = defineApiMethod('DELETE');
+export const definePatch = defineApiMethod('PATCH');
+export const defineOptions = defineApiMethod('OPTIONS');
+export const defineHead = defineApiMethod('HEAD');
+export function json(data, options) {
+    return createBodyResponse('json', data, {
+        status: options?.status,
+        headers: options?.headers,
+    });
+}
+export function html(content, options) {
+    return createBodyResponse('html', content, {
+        status: options?.status,
+        headers: options?.headers,
+    });
+}
+export function redirect(url, status = 302) {
+    return new Response(null, {
+        status,
+        headers: { Location: url },
+    });
+}
+function createGroupApi() {
+    const define = ((handler) => handler);
+    return Object.assign(define, {
+        get: defineApiMethod('GET'),
+        post: defineApiMethod('POST'),
+        put: defineApiMethod('PUT'),
+        delete: defineApiMethod('DELETE'),
+        patch: defineApiMethod('PATCH'),
+        options: defineApiMethod('OPTIONS'),
+        head: defineApiMethod('HEAD'),
+    });
+}
+export function defineGroupHandler(config) {
+    return {
+        prefix: config.prefix,
+        middleware: config.middleware,
+        routes: config.routes(createGroupApi()),
+    };
+}

package/src/adapters/shared/{explicit-static-render-preparation.d.ts → http/explicit-static-render-preparation.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { EcoFunctionComponent, EcoPageComponent } from '../../types/public-types.js';
-import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { EcoFunctionComponent, EcoPageComponent } from '../../../types/public-types.js';
+import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../../route-renderer/route-renderer.js';
 type ExplicitStaticRenderPreparationResult = {
     renderer: ExplicitViewRenderer;
     props: Record<string, unknown>;

package/src/adapters/shared/http/explicit-static-render-preparation.js

@@ -0,0 +1,29 @@
+function getViewIntegrationName(view) {
+    return view.config?.integration ?? view.config?.identity?.integration;
+}
+/**
+ * Resolves the renderer and static props needed to render one explicit static
+ * view at runtime or during static generation.
+ */
+export async function prepareExplicitStaticRender(input) {
+    const integrationName = getViewIntegrationName(input.view);
+    if (!integrationName) {
+        throw new Error(input.errors.missingIntegration(input.routePath));
+    }
+    const renderer = input.routeRendererFactory.getExplicitViewRenderer(integrationName);
+    if (!renderer) {
+        throw new Error(input.errors.noRendererForIntegration(integrationName));
+    }
+    const props = input.view.staticProps
+        ? (await input.view.staticProps({
+            pathname: { params: input.params },
+            appConfig: input.appConfig,
+            runtimeOrigin: input.runtimeOrigin,
+        })).props
+        : {};
+    return {
+        renderer,
+        props,
+        view: input.view,
+    };
+}

package/src/adapters/shared/{explicit-static-route-matcher.d.ts → http/explicit-static-route-matcher.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { StaticRoute } from '../../types/public-types.js';
-import type { ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { StaticRoute } from '../../../types/public-types.js';
+import type { ExplicitViewRendererResolver } from '../../../route-renderer/route-renderer.js';
 export declare const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS: {
     readonly missingIntegration: (routePath: string) => string;
     readonly noRendererForIntegration: (integrationName: string) => string;
@@ -27,12 +27,6 @@ export declare class ExplicitStaticRouteMatcher {
      * Returns the matched route and extracted params, or null if no match.
      */
     match(url: string): ExplicitRouteMatch | null;
-    /**
-     * Match a route pattern against a pathname.
-     * Supports :param and [param] syntax.
-     * Returns extracted params or null if no match.
-     */
-    private matchRoute;
     /**
      * Handle a matched explicit static route.
      * Resolves the loader and renders the view using the appropriate integration renderer.

package/src/adapters/shared/http/explicit-static-route-matcher.js

@@ -0,0 +1,59 @@
+import { appLogger } from '../../../global/app-logger.js';
+import { prepareExplicitStaticRender } from './explicit-static-render-preparation.js';
+import { matchExplicitStaticPathPattern } from '../../abstract/segment-path-matcher.js';
+export const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
+    missingIntegration: (routePath) => `View at ${routePath} is missing component identity integration. Ensure it's defined with eco.page() and exported as default.`,
+    noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
+};
+/**
+ * Matches and renders explicit static routes declared through `app.static()`.
+ */
+export class ExplicitStaticRouteMatcher {
+    appConfig;
+    routeRendererFactory;
+    staticRoutes;
+    constructor({ appConfig, routeRendererFactory, staticRoutes }) {
+        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) {
+        const pathname = new URL(url).pathname;
+        for (const route of this.staticRoutes) {
+            const params = matchExplicitStaticPathPattern(route.path, pathname);
+            if (params !== null) {
+                return { route, params };
+            }
+        }
+        return null;
+    }
+    /**
+     * Handle a matched explicit static route.
+     * Resolves the loader and renders the view using the appropriate integration renderer.
+     */
+    async handleMatch(match) {
+        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.d.ts → http/file-route-middleware-pipeline.d.ts}

@@ -1,5 +1,5 @@
-import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../types/public-types.js';
-import type { PageCacheService } from '../../services/cache/page-cache-service.js';
+import type { FileRouteMiddleware, FileRouteMiddlewareContext, RequestLocals } from '../../../types/public-types.js';
+import type { PageCacheService } from '../../../services/cache/page-cache-service.js';
 export declare const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS: {
     readonly middlewareRequiresDynamic: (filePath: string) => string;
 };

package/src/adapters/shared/http/file-route-middleware-pipeline.js

@@ -0,0 +1,84 @@
+import { createRequire } from '../../../utils/locals-utils.js';
+import { ApiResponseBuilder } from './api-response.js';
+import { runMiddlewareChain } from './run-middleware-chain.js';
+import { LocalsAccessError } from '../../../errors/locals-access-error.js';
+export const FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS = {
+    middlewareRequiresDynamic: (filePath) => `[ecopages] Page middleware requires cache: 'dynamic'. Page: ${filePath}`,
+};
+/**
+ * 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 {
+    cacheService;
+    constructor(cacheService) {
+        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) {
+        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) {
+        const context = {
+            request: input.request,
+            params: input.params,
+            response: new ApiResponseBuilder(),
+            server: null,
+            services: {
+                cache: this.cacheService,
+            },
+            locals: input.locals,
+            require: createRequire(() => context.locals),
+            json: (data, options) => {
+                if (options?.status)
+                    context.response.status(options.status);
+                if (options?.headers)
+                    context.response.headers(options.headers);
+                return context.response.json(data);
+            },
+            html: (content, options) => {
+                if (options?.status)
+                    context.response.status(options.status);
+                if (options?.headers)
+                    context.response.headers(options.headers);
+                return context.response.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) {
+        return runMiddlewareChain(input.middleware, input.context, input.renderResponse);
+    }
+}

package/src/adapters/shared/{fs-server-response-factory.d.ts → http/fs-server-response-factory.d.ts}

@@ -1,5 +1,5 @@
-import type { FileSystemServerOptions } from '../../types/internal-types.js';
-import type { RouteRendererBody } from '../../types/public-types.js';
+import type { FileSystemServerOptions } from '../../../types/internal-types.js';
+import type { RouteRendererBody } from '../../../types/public-types.js';
 /**
  * Builds HTTP responses for static files and shared file-system fallbacks.
  */
@@ -16,6 +16,11 @@ export declare class FileSystemServerResponseFactory {
      * Wraps already-rendered HTML in a 404 response envelope.
      */
     createHtmlNotFoundResponse(body: RouteRendererBody): Promise<Response>;
+    createDefaultServerErrorResponse(): Promise<Response>;
+    /**
+     * Wraps already-rendered HTML in a 500 response envelope.
+     */
+    createHtmlServerErrorResponse(body: RouteRendererBody): Promise<Response>;
     /**
      * Reads a static file response, returning `null` when the file is missing.
      */