@asenajs/ergenecore 4.0.0 → 5.0.1

package/dist/lib/Ergenecore.js

@@ -1,4 +1,4 @@
-import { AsenaAdapter, isHttpException, VALIDATOR_METHODS, } from '@asenajs/asena/adapter';
+import { AsenaAdapter, isHttpException, VALIDATOR_METHODS, ASENA_CONTEXT_CONTRACT, assertContextAdapter, assertRouteContract, prepareContextValidation, } from '@asenajs/asena/adapter';
 import { blue, green, red, yellow } from '@asenajs/asena/logger';
 import { ErgenecoreWebsocketAdapter } from './ErgenecoreWebsocketAdapter';
 import { ErgenecoreContextWrapper } from './ErgenecoreContextWrapper';
@@ -6,6 +6,7 @@ import * as Bun from 'bun';
 import * as path from 'path';
 import { HttpException, MiddlewareResponseError, ValidationError } from './errors';
 import { shouldApplyMiddleware } from '@asenajs/asena/utils';
+import { regularFileStats, StaticFileReader, staticFileHeaders } from './utils/staticFileReader';
 /**
  * Static response headers for performance
  *
@@ -18,6 +19,62 @@ const STATIC_JSON_HEADERS = Object.freeze({ 'Content-Type': 'application/json' }
  */
 const INTERNAL_SERVER_ERROR = JSON.stringify({ error: 'Internal Server Error' });
 const NOT_FOUND = JSON.stringify({ error: 'Not Found' });
+const JSON_HEADERS = new Headers(STATIC_JSON_HEADERS);
+function isThenable(value) {
+    return (value instanceof Promise ||
+        (value !== null &&
+            (typeof value === 'object' || typeof value === 'function') &&
+            typeof value.then === 'function'));
+}
+const JSON_INIT = { headers: JSON_HEADERS };
+function toHandlerResponse(response) {
+    if (response instanceof Response) {
+        return response;
+    }
+    return new Response(JSON.stringify(response), JSON_INIT);
+}
+function resolveStaticPath(root, rewrittenPath) {
+    // 3. Build absolute file path
+    const filePath = path.join(root, rewrittenPath);
+    // 4. Security: Resolve and validate path to prevent traversal attacks
+    return path.sep !== '/' || filePath.charCodeAt(0) !== 47
+        ? path.resolve(filePath)
+        : filePath.length > 1 && filePath.endsWith('/')
+            ? filePath.slice(0, -1)
+            : filePath;
+}
+function isNormalizedRelativePath(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return false;
+    }
+    let segmentStart = value.charCodeAt(0) === 47 ? 1 : 0;
+    for (let i = segmentStart; i <= value.length; i++) {
+        if (i < value.length && value.charCodeAt(i) !== 47) {
+            continue;
+        }
+        const length = i - segmentStart;
+        if (length === 0 ||
+            (value.charCodeAt(segmentStart) === 46 && (length === 1 || (length === 2 && value.charCodeAt(i - 1) === 46)))) {
+            return false;
+        }
+        segmentStart = i + 1;
+    }
+    return true;
+}
+function requestPathname(url) {
+    const authority = url.indexOf('//');
+    const start = authority === -1 ? -1 : url.indexOf('/', authority + 2);
+    if (start === -1) {
+        return new URL(url).pathname;
+    }
+    for (let i = start; i < url.length; i++) {
+        const code = url.charCodeAt(i);
+        if (code === 63 || code === 35) {
+            return url.slice(start, i);
+        }
+    }
+    return start === 0 ? url : url.slice(start);
+}
 /**
  * CoreAdapter - Native Bun adapter for Asenajs
  *
@@ -66,6 +123,7 @@ export class Ergenecore extends AsenaAdapter {
      * Handler for requests that matched no route
      */
     notFoundHandler;
+    staticFileReader = new StaticFileReader();
     /**
      * Whether the adapter logs errors before handing them to the application.
      * Set false when your own handler already logs with a correlation id.
@@ -194,6 +252,20 @@ export class Ergenecore extends AsenaAdapter {
      * ```
      */
     registerRoute(params) {
+        const label = `${params.method} ${params.path}`;
+        if (params.contextContract && !params.contextClass) {
+            throw new Error(`${label}: contextContract requires contextClass`);
+        }
+        if (params.contextClass &&
+            params.contextContract !== undefined &&
+            params.contextContract !== params.contextClass[ASENA_CONTEXT_CONTRACT]) {
+            throw new Error(`${label}: contextContract does not match contextClass`);
+        }
+        if (params.validatorCache !== undefined && typeof params.validatorCache !== 'boolean') {
+            throw new Error(`${label}: validatorCache must be a boolean`);
+        }
+        assertRouteContract(params, params.contextClass, label);
+        assertContextAdapter(params.contextClass, 'ergenecore');
         this.routeQueue.push(params);
     }
     /**
@@ -220,7 +292,7 @@ export class Ergenecore extends AsenaAdapter {
         const serverHostname = this._hostname;
         if (!this.routesBuilt) {
             // 1. Build HTTP routes
-            const httpRoutes = this.buildBunRoutes();
+            const httpRoutes = await this.buildBunRoutes();
             // 2. Build WebSocket routes
             const wsRoutes = this.buildWebSocketRoutes();
             // 3. Check for path collisions
@@ -291,6 +363,7 @@ export class Ergenecore extends AsenaAdapter {
             }
         }
         finally {
+            this.staticFileReader.close();
             // In a `finally`, and swallowed: `AsenaServer.runStop()` awaits this call unguarded, so an
             // error escaping here would strand everything queued behind it - the components' @OnStop
             // hooks, the microservice transports, ulak. A WebSocket layer that cannot let go of a
@@ -354,7 +427,7 @@ export class Ergenecore extends AsenaAdapter {
      *
      * @returns Bun router object
      */
-    buildBunRoutes() {
+    async buildBunRoutes() {
         const routes = {};
         // Group routes by exact path. There used to be an outer grouping by *base* path too, but
         // its only product was a `commonMiddlewares` array that createRouteHandler ignored - and
@@ -380,6 +453,11 @@ export class Ergenecore extends AsenaAdapter {
             }
             for (const route of pathRoutes) {
                 const method = route.method.toUpperCase();
+                const contextClass = route.contextClass;
+                const validateContract = contextClass
+                    ? prepareContextValidation(route.contextContract ?? contextClass[ASENA_CONTEXT_CONTRACT])
+                    : undefined;
+                const validationSteps = route.validator ? await this.prepareValidationSteps(route) : [];
                 // Fast Path Optimization with Pattern Matching
                 // ✅ Check if this route has any applicable global middlewares
                 const applicableGlobalMiddlewares = this.getGlobalMiddlewaresForPath(route.path);
@@ -387,9 +465,12 @@ export class Ergenecore extends AsenaAdapter {
                 const isSimpleRoute = applicableGlobalMiddlewares.length === 0 &&
                     (!route.middlewares || route.middlewares.length === 0) &&
                     !route.validator &&
+                    !validateContract &&
                     !route.staticServe;
                 // Create handler based on route complexity
-                const handler = isSimpleRoute ? this.createFastPathHandler(route) : this.createRouteHandler(route);
+                const handler = isSimpleRoute
+                    ? this.createFastPathHandler(route)
+                    : this.createRouteHandler(route, validateContract, validationSteps);
                 // Register handler to both path variants for trailing slash support
                 if (method === 'ALL') {
                     // Bun native: direct handler function matches all HTTP methods
@@ -872,33 +953,32 @@ export class Ergenecore extends AsenaAdapter {
         // - and once both were routed through `respondToError` the two bodies were identical. It was
         // also the only place the adapter read `errorHandler` at *build* time rather than per request,
         // so a handler registered after start() would have selected the wrong closure.
-        return async (req) => {
-            const context = new ErgenecoreContextWrapper(req, this.server);
-            context.routePattern = route.path;
+        const settle = (pending, context) => Promise.resolve(pending).then(toHandlerResponse, (error) => this.respondToError(error, context));
+        const hasParams = route.path.includes(':');
+        const ContextClass = (route.contextClass ?? ErgenecoreContextWrapper);
+        // Not `async`: a synchronous handler's Response goes back to Bun without a promise.
+        return (req) => {
+            let context;
+            try {
+                context = new ContextClass(req, this.server, route.path);
+            }
+            catch (error) {
+                return this.respondToError(error, new ErgenecoreContextWrapper(req, this.server, route.path));
+            }
             try {
-                // Inject Bun's native route params if present
                 // @ts-expect-error - Bun adds params to Request
-                if (req.params) {
+                if (hasParams && req.params) {
                     // @ts-expect-error - Bun adds params to Request
-                    const params = req.params;
-                    for (const key in params) {
-                        context.setValue(`param:${key}`, params[key]);
-                    }
+                    context.setRouteParams(req.params);
                 }
-                // Execute handler directly
-                const response = await route.handler(context);
-                // Return response (check if already a Response object)
-                if (response instanceof Response) {
-                    return response;
+                const result = route.handler(context);
+                if (isThenable(result)) {
+                    return settle(result, context);
                 }
-                // Wrap in Response with static headers
-                return new Response(JSON.stringify(response), {
-                    status: 200,
-                    headers: STATIC_JSON_HEADERS,
-                });
+                return toHandlerResponse(result);
             }
             catch (error) {
-                return await this.respondToError(error, context);
+                return this.respondToError(error, context);
             }
         };
     }
@@ -914,12 +994,13 @@ export class Ergenecore extends AsenaAdapter {
      * @param route - Route parameters
      * @returns Bun-compatible route handler
      */
-    createRouteHandler(route) {
+    createRouteHandler(route, validateContract, validationSteps = []) {
         // ✅ Filter global middlewares by path pattern (ONCE during route building)
         // This happens at server startup, NOT on every request → zero runtime overhead
         const applicableGlobalMiddlewares = this.getGlobalMiddlewaresForPath(route.path);
         // Combine global + route middlewares into a single chain
         const middlewares = [...applicableGlobalMiddlewares, ...(route.middlewares || [])];
+        const hasMiddlewares = middlewares.length > 0;
         // Resolved root for static file serving, computed once at startup instead of per request
         const resolvedStaticRoot = route.staticServe ? path.resolve(route.staticServe.root) : '';
         // The containment test below is a prefix comparison, so it needs the separator baked in.
@@ -928,65 +1009,91 @@ export class Ergenecore extends AsenaAdapter {
         const resolvedStaticRootPrefix = resolvedStaticRoot.endsWith(path.sep)
             ? resolvedStaticRoot
             : `${resolvedStaticRoot}${path.sep}`;
-        return async (req) => {
-            // Create context wrapper outside try block so it's accessible in catch
-            const context = new ErgenecoreContextWrapper(req, this.server);
-            context.routePattern = route.path;
+        const joinsVerbatim = path.sep === '/' && typeof route.staticServe?.root === 'string' && path.isAbsolute(route.staticServe.root);
+        const hasParams = route.path.includes(':');
+        const ContextClass = (route.contextClass ?? ErgenecoreContextWrapper);
+        const serveRoute = (req, context) => {
+            if (route.staticServe) {
+                const staticResponse = this.serveStaticFile(req, context, route.staticServe, resolvedStaticRoot, resolvedStaticRootPrefix, joinsVerbatim);
+                if (isThenable(staticResponse)) {
+                    return staticResponse.then((response) => response ?? this.runRouteHandler(route, context));
+                }
+                return staticResponse;
+            }
+            return this.runRouteHandler(route, context);
+        };
+        const runRoute = validateContract || validationSteps.length > 0
+            ? async (req, context) => {
+                if (validateContract)
+                    await validateContract(context);
+                if (validationSteps.length > 0) {
+                    const validationResult = await this.validateRequest(context, validationSteps);
+                    if (validationResult)
+                        return validationResult;
+                }
+                return serveRoute(req, context);
+            }
+            : serveRoute;
+        return (req) => {
+            let context;
+            try {
+                context = new ContextClass(req, this.server, route.path);
+            }
+            catch (error) {
+                return this.respondToError(error, new ErgenecoreContextWrapper(req, this.server, route.path));
+            }
             // Inject Bun's native route params
             // @ts-expect-error - Bun adds params to Request
-            if (req.params) {
+            if (hasParams && req.params) {
                 // @ts-expect-error - Bun adds params to Request
-                const params = req.params;
-                for (const key in params) {
-                    context.setValue(`param:${key}`, params[key]);
-                }
+                context.setRouteParams(req.params);
             }
             try {
-                // Execute middleware chain with handler as onComplete callback
-                // This ensures the handler runs INSIDE the middleware async context
-                const result = await this.executeMiddlewares(context, middlewares, 0, async () => {
-                    // Execute validation
-                    if (route.validator) {
-                        const validationResult = await this.validateRequest(context, route.validator);
-                        if (validationResult)
-                            return validationResult;
-                    }
-                    // Handle static file serving
-                    if (route.staticServe) {
-                        const staticResponse = await this.serveStaticFile(req, context, route.staticServe, resolvedStaticRoot, resolvedStaticRootPrefix);
-                        if (staticResponse)
-                            return staticResponse;
-                    }
-                    // Execute route handler
-                    const response = await route.handler(context);
-                    // If handler returns Response, return it directly
-                    if (response instanceof Response) {
-                        return response;
-                    }
-                    // Otherwise, wrap in Response
-                    return new Response(JSON.stringify(response), {
-                        status: 200,
-                        headers: STATIC_JSON_HEADERS,
-                    });
-                });
-                // Single choke point so middleware headers reach handlers that answer without the
-                // wrapper. Idempotent for `ctx.send()`, which merged them already.
-                if (result instanceof Response) {
-                    return context.applyMiddlewareHeaders(result);
+                const result = hasMiddlewares
+                    ? this.executeMiddlewares(context, middlewares, 0, () => runRoute(req, context))
+                    : runRoute(req, context);
+                if (isThenable(result)) {
+                    return this.settleRoute(context, result);
                 }
-                // If middleware chain returned false (stopped), return 403
-                if (result === false) {
-                    return context.applyMiddlewareHeaders(new Response('Forbidden', { status: 403 }));
-                }
-                // Default: result is true (should not happen with onComplete, but just in case)
-                return context.applyMiddlewareHeaders(new Response(null, { status: 204 }));
+                return this.finishRoute(context, result);
             }
             catch (error) {
-                // The context here already has params injected, so pass it through unchanged.
-                return context.applyMiddlewareHeaders(await this.respondToError(error, context));
+                return this.failRoute(context, error);
             }
         };
     }
+    runRouteHandler(route, context) {
+        const response = route.handler(context);
+        if (isThenable(response)) {
+            return Promise.resolve(response).then(toHandlerResponse);
+        }
+        return toHandlerResponse(response);
+    }
+    async settleRoute(context, pending) {
+        try {
+            return this.finishRoute(context, await pending);
+        }
+        catch (error) {
+            return await this.failRoute(context, error);
+        }
+    }
+    finishRoute(context, result) {
+        // Single choke point so middleware headers reach handlers that answer without the
+        // wrapper. Idempotent for `ctx.send()`, which merged them already.
+        if (result instanceof Response) {
+            return context.applyMiddlewareHeaders(result);
+        }
+        // If middleware chain returned false (stopped), return 403
+        if (result === false) {
+            return context.applyMiddlewareHeaders(new Response('Forbidden', { status: 403 }));
+        }
+        // Default: result is true (should not happen with onComplete, but just in case)
+        return context.applyMiddlewareHeaders(new Response(null, { status: 204 }));
+    }
+    async failRoute(context, error) {
+        // The context here already has params injected, so pass it through unchanged.
+        return context.applyMiddlewareHeaders(await this.respondToError(error, context));
+    }
     /**
      * Type guard to check if validation schema has hook format
      *
@@ -1008,6 +1115,46 @@ export class Ergenecore extends AsenaAdapter {
     isValidationSchemaWithHook(schema) {
         return typeof schema === 'object' && schema !== null && 'schema' in schema;
     }
+    /** Prepare each legacy validator target once for this route, preserving method order. */
+    async prepareValidationSteps(route) {
+        const steps = [];
+        for (const target of VALIDATOR_METHODS) {
+            const handler = route.validator[target];
+            if (!handler || typeof handler.handle !== 'function')
+                continue;
+            const step = {
+                target,
+                handle: () => handler.handle(),
+                extract: this.createValidationExtractor(target),
+                cachedResolved: route.validatorCache !== false,
+            };
+            if (route.validatorCache !== false) {
+                try {
+                    const value = await step.handle();
+                    if (value)
+                        step.prepared = this.unwrapValidationSchema(value);
+                }
+                catch (error) {
+                    throw new Error(`Failed to prepare validator for ${route.method.toUpperCase()} ${route.path} (${target})`, {
+                        cause: error,
+                    });
+                }
+            }
+            steps.push(step);
+        }
+        return steps;
+    }
+    unwrapValidationSchema(value) {
+        const schema = this.isValidationSchemaWithHook(value) ? value.schema : value;
+        const hook = this.isValidationSchemaWithHook(value) ? (value.hook ?? null) : null;
+        if (!schema || typeof schema.safeParseAsync !== 'function') {
+            throw new TypeError('Validator factory must return a Zod schema with safeParseAsync()');
+        }
+        if (hook !== null && typeof hook !== 'function') {
+            throw new TypeError('Validator hook must be a function');
+        }
+        return { schema, hook };
+    }
     /**
      * Validates request data using Zod schemas
      *
@@ -1023,28 +1170,20 @@ export class Ergenecore extends AsenaAdapter {
      * @param validator - Validator instance with schema definitions
      * @returns Response if validation fails, null if passes
      */
-    async validateRequest(context, validator) {
-        // Iterate through all validator methods (body, query, param, header)
-        for (const key of VALIDATOR_METHODS) {
-            const validatorHandler = validator[key];
-            // Skip if validator not defined for this target
-            if (!validatorHandler || typeof validatorHandler.handle !== 'function') {
-                continue;
-            }
-            // Get validation schema
-            const validationSchema = await validatorHandler.handle();
+    async validateRequest(context, steps) {
+        for (const { target: key, handle, extract, prepared, cachedResolved } of steps) {
+            const handled = cachedResolved ? undefined : handle();
+            const validationSchema = isThenable(handled) ? await handled : handled;
             // Skip if no validation schema provided
-            if (!validationSchema) {
+            if ((!cachedResolved && !validationSchema) || (cachedResolved && !prepared)) {
                 continue;
             }
             // Use type guard to discriminate between formats
-            const schema = this.isValidationSchemaWithHook(validationSchema)
-                ? validationSchema.schema
-                : validationSchema;
-            const hook = this.isValidationSchemaWithHook(validationSchema) ? (validationSchema.hook ?? null) : null;
+            const { schema, hook } = prepared ?? this.unwrapValidationSchema(validationSchema);
             // Extract data to validate
-            const data = await this.extractValidationData(context, key);
-            const result = schema.safeParse(data);
+            const extracted = extract(context);
+            const data = isThenable(extracted) ? await extracted : extracted;
+            const result = await schema.safeParseAsync(data);
             if (result.success) {
                 // Body targets only: z.object() strips unknown keys and the raw form parse is
                 // last-value-wins, so without the write-back the handler reads a shape the schema
@@ -1075,69 +1214,64 @@ export class Ergenecore extends AsenaAdapter {
      * @param target - Validation target (body, query, param, header, form)
      * @returns Data to be validated
      */
-    async extractValidationData(context, target) {
+    createValidationExtractor(target) {
         switch (target) {
             case 'json':
-                return await context.getBody();
-            case 'body': {
-                // 'json' is the correct Asena validator method name
-                // 'body' is kept for backwards compatibility
-                return await context.getBody();
-            }
+            case 'body':
+                return (context) => context.getBody();
             case 'query': {
-                const url = new URL(context.req.url);
-                const queryObj = {};
-                url.searchParams.forEach((value, key) => {
-                    queryObj[key] = value;
-                });
-                return queryObj;
+                return (context) => {
+                    const url = new URL(context.req.url);
+                    const queryObj = {};
+                    url.searchParams.forEach((value, key) => {
+                        queryObj[key] = value;
+                    });
+                    return queryObj;
+                };
             }
             case 'param': {
-                // Extract all params from context
-                const params = {};
-                // We stored params with 'param:' prefix in context
-                for (const [key, value] of context.values.entries()) {
-                    if (key.startsWith('param:')) {
-                        params[key.replace('param:', '')] = value;
+                return (context) => {
+                    const params = {};
+                    for (const [key, value] of context.values.entries()) {
+                        if (key.startsWith('param:'))
+                            params[key.replace('param:', '')] = value;
                     }
-                }
-                return params;
+                    return params;
+                };
             }
             case 'header': {
-                const headers = {};
-                context.req.headers.forEach((value, key) => {
-                    headers[key.toLowerCase()] = value;
-                });
-                return headers;
+                return (context) => {
+                    const headers = {};
+                    context.req.headers.forEach((value, key) => {
+                        headers[key.toLowerCase()] = value;
+                    });
+                    return headers;
+                };
             }
             case 'form': {
-                const contentType = context.req.headers.get('content-type') ?? '';
-                // hono parity: non-form content-type validates {} (a required field then fails),
-                // instead of feeding JSON into a form schema
-                if (!contentType.includes('multipart/form-data') &&
-                    !contentType.includes('application/x-www-form-urlencoded')) {
-                    return {};
-                }
-                const formData = await context.getFormData();
-                const form = Object.create(null);
-                formData.forEach((value, key) => {
-                    if (key.endsWith('[]')) {
-                        (form[key] ??= []).push(value);
-                    }
-                    else if (Array.isArray(form[key])) {
-                        form[key].push(value);
+                return async (context) => {
+                    const contentType = context.req.headers.get('content-type') ?? '';
+                    if (!contentType.includes('multipart/form-data') &&
+                        !contentType.includes('application/x-www-form-urlencoded')) {
+                        return {};
                     }
-                    else if (Object.hasOwn(form, key)) {
-                        form[key] = [form[key], value];
-                    }
-                    else {
-                        form[key] = value;
-                    }
-                });
-                return form;
+                    const formData = await context.getFormData();
+                    const form = Object.create(null);
+                    formData.forEach((value, key) => {
+                        if (key.endsWith('[]'))
+                            (form[key] ??= []).push(value);
+                        else if (Array.isArray(form[key]))
+                            form[key].push(value);
+                        else if (Object.hasOwn(form, key))
+                            form[key] = [form[key], value];
+                        else
+                            form[key] = value;
+                    });
+                    return form;
+                };
             }
             default:
-                return {};
+                return () => ({});
         }
     }
     /**
@@ -1165,30 +1299,29 @@ export class Ergenecore extends AsenaAdapter {
      * });
      * ```
      */
-    async serveStaticFile(req, context, staticServe, resolvedRoot, resolvedRootPrefix) {
+    serveStaticFile(req, context, staticServe, resolvedRoot, resolvedRootPrefix, joinsVerbatim) {
         // Deliberately no try/catch. Anything thrown here - a rewriteRequestPath that raises, a
         // path.resolve or Bun.file failure - travels up to createRouteHandler's catch and through
         // `respondToError`, like every other failure. Answering it here meant the body was
         // `{"error": error.message}`, and a message thrown out of the filesystem layer is
         // specifically a deployment path; and the application's `onError` never saw it at all.
         // 1. Extract request path from URL
-        const url = new URL(req.url);
+        const pathname = requestPathname(req.url);
         // A malformed escape - `%zz`, a lone `%` - makes decodeURIComponent throw a URIError, which
         // reached respondToError as an unbranded error: a 500, an error-level log with a stack, and
         // the application's onError handed a request the client had simply written wrong.
         let requestPath;
         try {
-            requestPath = decodeURIComponent(url.pathname);
+            requestPath = pathname.includes('%') ? decodeURIComponent(pathname) : pathname;
         }
         catch {
             throw new HttpException(400, { error: 'Bad Request' });
         }
         // 2. Apply path rewriting if provided
         const rewrittenPath = staticServe.rewriteRequestPath ? staticServe.rewriteRequestPath(requestPath) : requestPath;
-        // 3. Build absolute file path
-        const filePath = path.join(staticServe.root, rewrittenPath);
-        // 4. Security: Resolve and validate path to prevent traversal attacks
-        const resolvedFilePath = path.resolve(filePath);
+        const resolvedFilePath = joinsVerbatim && isNormalizedRelativePath(rewrittenPath)
+            ? resolvedRootPrefix + (rewrittenPath.charCodeAt(0) === 47 ? rewrittenPath.slice(1) : rewrittenPath)
+            : resolveStaticPath(staticServe.root, rewrittenPath);
         // Check if resolved file path is within root directory. The separator is what makes this a
         // containment test rather than a string-prefix one: without it a root of `/srv/assets`
         // accepted `/srv/assets-private/…`, reachable through `..%2F` in the request path. The
@@ -1198,6 +1331,29 @@ export class Ergenecore extends AsenaAdapter {
             this.logger.warn(`Path traversal attempt detected: ${requestPath} -> ${resolvedFilePath}`);
             return new Response('Forbidden', { status: 403 });
         }
+        const stats = regularFileStats(resolvedFilePath);
+        if (stats !== undefined && !staticServe.onFound) {
+            return this.statFileResponse(resolvedFilePath, stats, staticServe.extra, req);
+        }
+        return this.serveResolvedStaticFile(req, context, staticServe, pathname, rewrittenPath, resolvedFilePath, stats);
+    }
+    statFileResponse(filePath, stats, extra, req) {
+        if (!extra) {
+            return this.staticFileReader.respond(filePath, stats, !req.headers.has('range'));
+        }
+        const read = this.staticFileReader.read(filePath, stats, !req.headers.has('range'));
+        const headers = this.withStaticExtras(staticFileHeaders(read.type, read.etag, read.lastModified), filePath, extra);
+        return new Response(read.bytes ?? Bun.file(filePath), { status: 200, headers });
+    }
+    async serveResolvedStaticFile(req, context, staticServe, pathname, rewrittenPath, resolvedFilePath, stats) {
+        if (stats !== undefined) {
+            await staticServe.onFound.handler(rewrittenPath, context);
+            if (staticServe.onFound.override) {
+                return null;
+            }
+            return this.statFileResponse(resolvedFilePath, stats, staticServe.extra, req);
+        }
+        this.staticFileReader.release(resolvedFilePath);
         // 5. Create Bun.file() instance
         const file = Bun.file(resolvedFilePath);
         // 5. Check if file exists
@@ -1216,7 +1372,7 @@ export class Ergenecore extends AsenaAdapter {
             // `text/plain` 404 and never consult the config hook - so the same app produced a
             // different 404 body here than on the hono adapter, where serveStatic calls next()
             // and the request lands in app.notFound.
-            return await this.respondToUnmatched(context, url.pathname, req.method);
+            return await this.respondToUnmatched(context, pathname, req.method);
         }
         // 7. File found → trigger onFound hook
         if (staticServe.onFound) {
@@ -1226,33 +1382,24 @@ export class Ergenecore extends AsenaAdapter {
                 return null;
             }
         }
-        // 8. Create Bun file response with automatic Content-Type detection
-        const fileResponse = new Response(file);
-        // 9. Build response headers starting with Bun's Content-Type
-        const finalHeaders = new Headers(fileResponse.headers);
-        // 10. Add cache validation headers (ETag and Last-Modified)
-        // ETag format: W/"<size>-<lastModified>" (weak validator)
-        const etag = `W/"${file.size}-${file.lastModified}"`;
-        finalHeaders.set('ETag', etag);
-        // Last-Modified: HTTP date format (RFC 7231)
-        const lastModified = new Date(file.lastModified).toUTCString();
-        finalHeaders.set('Last-Modified', lastModified);
-        // 11. Add custom headers (can override defaults)
-        const customHeaders = this.buildStaticFileHeaders(resolvedFilePath, staticServe.extra);
-        for (const [key, value] of Object.entries(customHeaders)) {
-            finalHeaders.set(key, value);
+        const lastModifiedMs = file.lastModified;
+        const finalHeaders = staticFileHeaders(file.type, `W/"${file.size}-${lastModifiedMs}"`, new Date(lastModifiedMs).toUTCString());
+        return new Response(file, {
+            status: 200,
+            headers: this.withStaticExtras(finalHeaders, resolvedFilePath, staticServe.extra),
+        });
+    }
+    withStaticExtras(headers, filePath, extras) {
+        if (extras) {
+            const customHeaders = this.buildStaticFileHeaders(filePath, extras);
+            for (const key in customHeaders) {
+                headers.set(key, customHeaders[key]);
+            }
         }
-        // 12. Add default Cache-Control if not provided
-        // Using 'public, max-age=0' allows caching but requires revalidation
-        if (!finalHeaders.has('Cache-Control')) {
-            finalHeaders.set('Cache-Control', 'public, max-age=0');
+        if (!headers.has('Cache-Control')) {
+            headers.set('Cache-Control', 'public, max-age=0');
         }
-        // 13. Return response with all headers
-        // This preserves Bun's zero-copy file serving while adding cache headers
-        return new Response(fileResponse.body, {
-            status: fileResponse.status,
-            headers: finalHeaders,
-        });
+        return headers;
     }
     /**
      * Builds response headers for static file serving