@fluojs/http 2.0.1 → 3.0.0

package/dist/dispatch/dispatcher.js

@@ -1,15 +1,22 @@
 import { getCompiledDtoBindingPlan } from '../adapters/dto-binding-plan.js';
 import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
-import { SseResponse, isSseMessage } from '../context/sse.js';
+import { resolveRequestId } from '../context/request-id.js';
+import { isSseMessage, SseResponse, waitForSseResponseCompletion } from '../context/sse.js';
 import { RequestAbortedError } from '../errors.js';
 import { runGuardChain } from '../guards.js';
 import { runInterceptorChain } from '../interceptors.js';
 import { isMiddlewareRouteConfig, matchRoutePattern, runMiddlewareChain } from '../middleware/middleware.js';
+import { initializeCorrelationMiddlewareRequestContext } from '../middleware/correlation.js';
+import { resolveConditionalRequest } from './conditional-request-policy.js';
+import { isContentNegotiationNotAcceptableException } from './dispatch-content-negotiation.js';
 import { invokeControllerHandler } from './dispatch-handler-policy.js';
-import { resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
+import { resolveResponsePolicy, resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
 import { matchHandlerOrThrow, updateRequestParams } from './dispatch-routing-policy.js';
+import { createDispatcherFastPathState } from './fast-path/dispatcher-state.js';
+import { addPathDebugHeader, createPathDebugInfo, executeFastPath, FAST_PATH_STATS_SYMBOL, shouldUseFastPathForRequest } from './fast-path/index.js';
 import { attachFrameworkRequestNativeRouteHandoff, readFrameworkRequestNativeRouteHandoff } from './native-route-handoff.js';
-import { compileFastPathEligibility, getHandlerFastPathEligibility, setHandlerFastPathEligibility, FAST_PATH_STATS_SYMBOL, addPathDebugHeader, createFastPathStats, createPathDebugInfo, executeFastPath, shouldUseFastPathForRequest } from './fast-path/index.js';
+import { isRequestAborted } from './request-abort.js';
+import { FRAMEWORK_RESPONSE_VALUE_FINALIZER } from './response-integration.js';
 export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL } from './fast-path/index.js';
 
 /** Type definition for a global HTTP error handler function. */
@@ -28,6 +35,16 @@ class ManagedSseCleanupError extends Error {
     this.cleanupError = cleanupError;
   }
 }
+class ManagedSseOperationError extends Error {
+  operationError;
+  constructor(operationError) {
+    super('Managed SSE operation failed.', {
+      cause: operationError
+    });
+    this.name = 'ManagedSseOperationError';
+    this.operationError = operationError;
+  }
+}
 function logDispatchFailure(logger, message, error) {
   if (logger) {
     logger.error(message, error, 'HttpDispatcher');
@@ -47,6 +64,7 @@ function createDispatchRequest(request) {
       return request.query;
     },
     body: request.body,
+    connection: request.connection,
     method: request.method,
     params: {
       ...request.params
@@ -70,41 +88,11 @@ function createDispatchRequest(request) {
   }
   return nativeRouteHandoff ? attachFrameworkRequestNativeRouteHandoff(dispatchRequest, nativeRouteHandoff) : dispatchRequest;
 }
-function cloneHandlerDescriptor(descriptor) {
-  const cloned = {
-    ...descriptor,
-    metadata: {
-      ...descriptor.metadata,
-      moduleMiddleware: [...descriptor.metadata.moduleMiddleware],
-      pathParams: [...descriptor.metadata.pathParams]
-    },
-    route: {
-      ...descriptor.route,
-      guards: descriptor.route.guards ? [...descriptor.route.guards] : undefined,
-      headers: descriptor.route.headers?.map(header => ({
-        ...header
-      })),
-      interceptors: descriptor.route.interceptors ? [...descriptor.route.interceptors] : undefined,
-      produces: descriptor.route.produces ? [...descriptor.route.produces] : undefined,
-      redirect: descriptor.route.redirect ? {
-        ...descriptor.route.redirect
-      } : undefined
-    }
-  };
-  const eligibility = getHandlerFastPathEligibility(descriptor);
-  if (eligibility) {
-    setHandlerFastPathEligibility(cloned, eligibility);
-  }
-  return cloned;
-}
 function readRequestId(request) {
   if (request.requestId) {
     return request.requestId;
   }
-  const raw = request.headers['x-request-id'] ?? request.headers['X-Request-Id'];
-  const value = Array.isArray(raw) ? raw[0] : raw;
-  const normalized = value?.trim();
-  return normalized ? normalized : undefined;
+  return resolveRequestId(request, false);
 }
 function createDispatchContext(request, response, container, promoteOnContainerAccess) {
   const context = createRequestContext({
@@ -132,7 +120,7 @@ function createDispatchContext(request, response, container, promoteOnContainerA
   };
   const getWrappedContainer = () => {
     if (!wrappedContainer) {
-      wrappedContainer = {
+      const wrapped = {
         async resolve(token) {
           const targetContainer = ensurePromoted();
           return targetContainer.resolve(token);
@@ -147,6 +135,16 @@ function createDispatchContext(request, response, container, promoteOnContainerA
           return activeContainer.dispose();
         }
       };
+      const presenceAwareContainer = activeContainer;
+      if (typeof presenceAwareContainer.has === 'function') {
+        Object.assign(wrapped, {
+          has(token) {
+            const targetContainer = activeContainer;
+            return targetContainer.has?.(token) ?? false;
+          }
+        });
+      }
+      wrappedContainer = wrapped;
     }
     return wrappedContainer;
   };
@@ -263,9 +261,6 @@ function ensureRequestNotAborted(request) {
     throw new RequestAbortedError();
   }
 }
-function isRequestAborted(request) {
-  return request.isAborted?.() ?? request.signal?.aborted === true;
-}
 function isSseRoute(handler) {
   return handler.route.produces?.some(mediaType => mediaType.toLowerCase().startsWith('text/event-stream')) === true;
 }
@@ -358,13 +353,13 @@ function resolveManagedSseFrame(value) {
 async function closeAsyncIterator(iterator) {
   await iterator.return?.();
 }
-async function readManagedSseNext(request, stream, iterator) {
+async function waitForManagedSseOperation(request, stream, operation) {
   const abort = createManagedSseStopPromise(request, stream);
   if (!abort) {
-    return iterator.next();
+    return operation;
   }
   try {
-    return await Promise.race([iterator.next(), abort.promise]);
+    return await Promise.race([operation, abort.promise]);
   } finally {
     abort.cleanup();
   }
@@ -387,7 +382,7 @@ async function writeManagedSseIterable(handler, requestContext, source) {
         iteratorCleanup ??= closeAsyncIterator(iterator);
         break;
       }
-      const next = await readManagedSseNext(requestContext.request, stream, iterator);
+      const next = await waitForManagedSseOperation(requestContext.request, stream, iterator.next());
       if (next === 'aborted') {
         iteratorCleanup ??= closeAsyncIterator(iterator);
         break;
@@ -397,10 +392,16 @@ async function writeManagedSseIterable(handler, requestContext, source) {
       }
       const frame = resolveManagedSseFrame(next.value);
       const accepted = sse.send(frame.data, frame.options);
-      if (!accepted) {
-        await requestContext.response.stream?.waitForDrain?.();
+      if (!accepted && stream.waitForDrain) {
+        const drain = await waitForManagedSseOperation(requestContext.request, stream, stream.waitForDrain());
+        if (drain === 'aborted') {
+          iteratorCleanup ??= closeAsyncIterator(iterator);
+          break;
+        }
       }
     }
+  } catch (error) {
+    throw new ManagedSseOperationError(error);
   } finally {
     sse.close();
     if (iteratorCleanup) {
@@ -428,19 +429,6 @@ function resolveFastPathHandlerRuntimeCache(handler, cache) {
   cache.set(handler, compiled);
   return compiled;
 }
-function resolveFastPathController(handler, controllerContainer, runtimeCache) {
-  if (runtimeCache.controller) {
-    return runtimeCache.controller;
-  }
-  runtimeCache.controllerPromise ??= controllerContainer.resolve(handler.controllerToken).then(controller => {
-    runtimeCache.controller = controller;
-    return controller;
-  });
-  return runtimeCache.controllerPromise;
-}
-function isPromiseLike(value) {
-  return typeof value === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
-}
 function isRequestObserver(value) {
   return typeof value === 'object' && value !== null;
 }
@@ -450,24 +438,21 @@ async function resolveRequestObserver(definition, requestContext) {
   }
   return requestContext.container.resolve(definition);
 }
-async function notifyObservers(observers, requestContext, callback, handler) {
+async function notifyObserversSafely(observers, requestContext, callback, logger, handler) {
+  if (observers.length === 0) {
+    return;
+  }
   const context = {
     handler,
     requestContext
   };
   for (const definition of observers) {
-    const observer = await resolveRequestObserver(definition, requestContext);
-    await callback(observer, context);
-  }
-}
-async function notifyObserversSafely(observers, requestContext, callback, logger, handler) {
-  if (observers.length === 0) {
-    return;
-  }
-  try {
-    await notifyObservers(observers, requestContext, callback, handler);
-  } catch (error) {
-    logDispatchFailure(logger, 'Request observer threw an unhandled error.', error);
+    try {
+      const observer = await resolveRequestObserver(definition, requestContext);
+      await callback(observer, context);
+    } catch (error) {
+      logDispatchFailure(logger, 'Request observer threw an unhandled error.', error);
+    }
   }
 }
 function mergeInterceptors(globalInterceptors, routeInterceptors) {
@@ -479,7 +464,7 @@ function mergeInterceptors(globalInterceptors, routeInterceptors) {
   }
   return [...globalInterceptors, ...routeInterceptors];
 }
-async function dispatchMatchedHandler(handler, executionPlan, requestContext, controllerContainer, observers, contentNegotiation, binder, logger) {
+async function dispatchMatchedHandler(handler, executionPlan, requestContext, controllerContainer, contentNegotiation, binder, conditionalRequest) {
   const routeGuards = executionPlan.routeGuards;
   if (routeGuards.length > 0) {
     const guardContext = {
@@ -491,19 +476,47 @@ async function dispatchMatchedHandler(handler, executionPlan, requestContext, co
   if (requestContext.response.committed) {
     return;
   }
+  if (contentNegotiation && handler.route.produces?.length && handler.route.redirect === undefined && typeof requestContext.metadata[FRAMEWORK_RESPONSE_VALUE_FINALIZER] !== 'function') {
+    resolveResponsePolicy(handler, requestContext.request, contentNegotiation);
+  }
+  let conditionalOutcome;
+  let conditionalValidators;
+  if (conditionalRequest) {
+    const resolved = await resolveConditionalRequest(conditionalRequest, {
+      handler,
+      request: requestContext.request
+    });
+    conditionalValidators = resolved.validators;
+    if (resolved.outcome !== 'proceed') {
+      conditionalOutcome = resolved.outcome;
+    }
+  }
+  if (conditionalOutcome !== undefined && !requiresResultFirstConditionalClassification(handler, requestContext)) {
+    await writeSuccessResponse(handler, requestContext.request, requestContext.response, undefined, contentNegotiation, requestContext, conditionalValidators, conditionalOutcome);
+    return {
+      result: undefined
+    };
+  }
   const result = executionPlan.mergedInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder, controllerContainer) : await runInterceptorChain(executionPlan.mergedInterceptors, {
     handler,
     requestContext
   }, async () => invokeControllerHandler(handler, requestContext, binder, controllerContainer));
   ensureRequestNotAborted(requestContext.request);
-  if (isAsyncIterable(result) && (await writeManagedSseIterable(handler, requestContext, result))) {
+  if (conditionalOutcome === undefined && result instanceof SseResponse) {
+    await waitForSseResponseCompletion(result);
+    ensureRequestNotAborted(requestContext.request);
+  } else if (conditionalOutcome === undefined && isAsyncIterable(result) && (await writeManagedSseIterable(handler, requestContext, result))) {
     // Managed SSE streams are already committed and closed by writeManagedSseIterable.
-  } else if (!(result instanceof SseResponse) && !requestContext.response.committed) {
-    await writeSuccessResponse(handler, requestContext.request, requestContext.response, result, contentNegotiation, requestContext);
+  } else if (!requestContext.response.committed) {
+    await writeSuccessResponse(handler, requestContext.request, requestContext.response, result, contentNegotiation, requestContext, conditionalValidators, conditionalOutcome);
   }
-  await notifyObserversSafely(observers, requestContext, async (observer, context) => {
-    await observer.onRequestSuccess?.(context, result);
-  }, logger, handler);
+  return {
+    result
+  };
+}
+function requiresResultFirstConditionalClassification(handler, requestContext) {
+  const method = requestContext.request.method.toUpperCase();
+  return (method === 'GET' || method === 'HEAD') && (handler.route.redirect !== undefined || typeof requestContext.metadata[FRAMEWORK_RESPONSE_VALUE_FINALIZER] === 'function');
 }
 function resolveHandlerExecutionPlan(handler, executionPlans, options) {
   const cached = executionPlans.get(handler);
@@ -514,8 +527,11 @@ function resolveHandlerExecutionPlan(handler, executionPlans, options) {
   executionPlans.set(handler, compiled);
   return compiled;
 }
-async function dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathRuntimeCache) {
-  const eligibility = getHandlerFastPathEligibility(match.descriptor);
+async function dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathState, fastPathRuntimeCache) {
+  if (options.conditionalRequest || (options.observers?.length ?? 0) > 0) {
+    return false;
+  }
+  const eligibility = fastPathState.getEligibility(match.descriptor);
   if (!shouldUseFastPathForRequest(eligibility, request)) {
     return false;
   }
@@ -537,6 +553,7 @@ async function dispatchNativeFastRoute(match, request, response, options, conten
   phaseContext = {
     contentNegotiation,
     dispatchScope,
+    fastPathState,
     fastPathRuntimeCache,
     handlerExecutionPlans: EMPTY_NATIVE_FAST_PATH_HANDLER_EXECUTION_PLANS,
     observers: EMPTY_NATIVE_FAST_PATH_OBSERVERS,
@@ -581,6 +598,11 @@ async function notifyHandlerMatched(context, descriptor) {
     await observer.onHandlerMatched?.(observationContext);
   }, context.options.logger, descriptor);
 }
+async function notifyRequestSuccess(context, result) {
+  await notifyObserversSafely(context.observers, context.requestContext, async (observer, observationContext) => {
+    await observer.onRequestSuccess?.(observationContext, result);
+  }, context.options.logger, context.matchedHandler);
+}
 async function notifyRequestError(context, error) {
   await notifyObserversSafely(context.observers, context.requestContext, async (observer, observationContext) => {
     await observer.onRequestError?.(observationContext, error);
@@ -592,7 +614,7 @@ async function notifyRequestFinish(context) {
   }, context.options.logger, context.matchedHandler);
 }
 async function tryFastPathExecution(handler, context) {
-  const eligibility = getHandlerFastPathEligibility(handler);
+  const eligibility = context.fastPathState.getEligibility(handler);
   if (!eligibility || eligibility.executionPath !== 'fast') {
     return false;
   }
@@ -600,8 +622,7 @@ async function tryFastPathExecution(handler, context) {
     ensureRequestScope(context);
   }
   const runtimeCache = resolveFastPathHandlerRuntimeCache(handler, context.fastPathRuntimeCache);
-  const controllerOrPromise = resolveFastPathController(handler, context.dispatchScope.container, runtimeCache);
-  const controller = isPromiseLike(controllerOrPromise) ? await controllerOrPromise : controllerOrPromise;
+  const controller = await context.dispatchScope.container.resolve(handler.controllerToken);
   const fastPathResult = await executeFastPath({
     binder: context.options.binder,
     contentNegotiation: context.contentNegotiation,
@@ -623,6 +644,7 @@ async function tryFastPathExecution(handler, context) {
 }
 async function runDispatchPipeline(context) {
   ensureRequestNotAborted(context.requestContext.request);
+  let handlerResult;
   const appMiddlewareContext = {
     request: context.requestContext.request,
     requestContext: context.requestContext,
@@ -635,12 +657,12 @@ async function runDispatchPipeline(context) {
     const match = readFrameworkRequestNativeRouteHandoff(appMiddlewareContext.request) ?? matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
     context.matchedHandler = match.descriptor;
     updateRequestParams(context.requestContext, match.params);
-    const eligibility = getHandlerFastPathEligibility(match.descriptor);
+    const eligibility = context.fastPathState.getEligibility(match.descriptor);
     if (context.options.fastPathDebugHeaders === true && eligibility && !context.response.committed) {
       const debugInfo = createPathDebugInfo(eligibility);
       addPathDebugHeader(context.response.setHeader.bind(context.response), debugInfo);
     }
-    if (shouldUseFastPathForRequest(eligibility, appMiddlewareContext.request)) {
+    if (!context.options.conditionalRequest && shouldUseFastPathForRequest(eligibility, appMiddlewareContext.request)) {
       const fastPathSuccess = await tryFastPathExecution(match.descriptor, context);
       if (fastPathSuccess) {
         return;
@@ -657,20 +679,24 @@ async function runDispatchPipeline(context) {
       response: context.response
     };
     await runMiddlewareChain(match.descriptor.metadata.moduleMiddleware ?? [], moduleMiddlewareContext, async () => {
-      await dispatchMatchedHandler(match.descriptor, executionPlan, context.requestContext, context.dispatchScope.container, context.observers, context.contentNegotiation, context.options.binder, context.options.logger);
+      handlerResult = await dispatchMatchedHandler(match.descriptor, executionPlan, context.requestContext, context.dispatchScope.container, context.contentNegotiation, context.options.binder, context.options.conditionalRequest);
     });
   };
   const appMiddleware = context.options.appMiddleware ?? [];
   if (appMiddleware.length === 0) {
     await dispatchMatchedRoute();
-    return;
+  } else {
+    await runMiddlewareChain(appMiddleware, appMiddlewareContext, dispatchMatchedRoute);
+  }
+  if (handlerResult) {
+    await notifyRequestSuccess(context, handlerResult.result);
   }
-  await runMiddlewareChain(appMiddleware, appMiddlewareContext, dispatchMatchedRoute);
 }
 async function handleDispatchError(context, error) {
   const managedSseCleanupFailed = error instanceof ManagedSseCleanupError;
-  const dispatchError = managedSseCleanupFailed ? error.cleanupError : error;
-  if (!managedSseCleanupFailed && (error instanceof RequestAbortedError || isRequestAborted(context.requestContext.request))) {
+  const managedSseOperationFailed = error instanceof ManagedSseOperationError;
+  const dispatchError = managedSseCleanupFailed ? error.cleanupError : managedSseOperationFailed ? error.operationError : error;
+  if (!managedSseCleanupFailed && !managedSseOperationFailed && (error instanceof RequestAbortedError || isRequestAborted(context.requestContext.request))) {
     return;
   }
   await notifyRequestError(context, dispatchError);
@@ -681,7 +707,20 @@ async function handleDispatchError(context, error) {
   if (managedSseCleanupFailed) {
     logDispatchFailure(context.options.logger, 'Managed SSE iterator cleanup threw an error.', dispatchError);
   }
-  await writeErrorResponse(dispatchError, context.response, context.requestContext.requestId);
+  await writeErrorResponse(dispatchError, context.requestContext, {
+    ...(context.matchedHandler === undefined ? {} : {
+      handler: context.matchedHandler
+    }),
+    ...(context.options.logger === undefined ? {} : {
+      logger: context.options.logger
+    }),
+    ...(context.options.errorRepresentation === undefined ? {} : {
+      representation: context.options.errorRepresentation
+    }),
+    ...(isContentNegotiationNotAcceptableException(dispatchError) ? {
+      varyAccept: true
+    } : {})
+  });
 }
 
 /**
@@ -698,22 +737,16 @@ export function createDispatcher(options) {
   const fastPathRuntimeCache = new WeakMap();
   const handlerExecutionPlans = new WeakMap();
   const adapter = options.adapter ?? 'default';
-  const fastPathEligibilities = [];
+  const fastPathState = createDispatcherFastPathState(options.handlerMapping.descriptors, options, adapter);
   for (const descriptor of options.handlerMapping.descriptors) {
     handlerExecutionPlans.set(descriptor, compileHandlerExecutionPlan(descriptor, options));
-    const {
-      eligibility
-    } = compileFastPathEligibility(descriptor, options, adapter);
-    setHandlerFastPathEligibility(descriptor, eligibility);
-    fastPathEligibilities.push(eligibility);
   }
-  const fastPathStats = createFastPathStats(fastPathEligibilities);
   const dispatcher = {
     describeRoutes() {
-      return options.handlerMapping.descriptors.map(descriptor => cloneHandlerDescriptor(descriptor));
+      return fastPathState.describeRoutes();
     },
     async dispatchNativeRoute(match, request, response) {
-      return dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathRuntimeCache);
+      return dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathState, fastPathRuntimeCache);
     },
     async dispatch(request, response) {
       const dispatchRequest = createDispatchRequest(request);
@@ -730,6 +763,7 @@ export function createDispatcher(options) {
       phaseContext = {
         contentNegotiation,
         dispatchScope,
+        fastPathState,
         fastPathRuntimeCache,
         handlerExecutionPlans,
         observers,
@@ -737,6 +771,7 @@ export function createDispatcher(options) {
         requestContext,
         response
       };
+      initializeCorrelationMiddlewareRequestContext(options.appMiddleware ?? [], requestContext);
       await runWithRequestContext(phaseContext.requestContext, async () => {
         try {
           if (observers.length > 0) {
@@ -764,7 +799,12 @@ export function createDispatcher(options) {
       });
     }
   };
-  dispatcher[FAST_PATH_STATS_SYMBOL] = fastPathStats;
+  Object.defineProperty(dispatcher, FAST_PATH_STATS_SYMBOL, {
+    configurable: false,
+    enumerable: false,
+    value: fastPathState.stats,
+    writable: false
+  });
   return dispatcher;
 }
 

package/dist/dispatch/fast-path/debug-visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug-visibility.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/debug-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI3E,UAAU,aAAa;IACrB,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,mBAAmB,GAAG,aAAa,CAMnF;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,EAChD,IAAI,EAAE,aAAa,GAClB,IAAI,CAMN;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,GAAG,aAAa,CAShG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAuBhE"}
+{"version":3,"file":"debug-visibility.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/debug-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAI3E,UAAU,aAAa;IACrB,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,mBAAmB,GAAG,aAAa,CAMnF;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,EAChD,IAAI,EAAE,aAAa,GAClB,IAAI,CAMN;AAED,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,mBAAmB,EAAE,GAAG,aAAa,CAUhG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAuBhE"}

package/dist/dispatch/fast-path/debug-visibility.js

@@ -12,12 +12,15 @@ export function addPathDebugHeader(setHeader, info) {
 }
 export function createFastPathStats(eligibilities) {
   const fastPathRoutes = eligibilities.filter(e => e.executionPath === 'fast').length;
-  return {
+  const routes = Object.freeze(eligibilities.map(eligibility => Object.freeze({
+    ...eligibility
+  })));
+  return Object.freeze({
     fastPathRoutes,
     fullPathRoutes: eligibilities.length - fastPathRoutes,
-    routes: eligibilities,
+    routes,
     totalRoutes: eligibilities.length
-  };
+  });
 }
 
 /**

package/dist/dispatch/fast-path/dispatcher-state.d.ts

@@ -0,0 +1,10 @@
+import type { HandlerDescriptor } from '../../types.js';
+import type { CreateDispatcherOptions } from '../dispatcher.js';
+import type { FastPathEligibility, FastPathStats } from './eligibility.js';
+export interface DispatcherFastPathState {
+    readonly stats: FastPathStats;
+    describeRoutes(): readonly HandlerDescriptor[];
+    getEligibility(descriptor: HandlerDescriptor): FastPathEligibility | undefined;
+}
+export declare function createDispatcherFastPathState(descriptors: readonly HandlerDescriptor[], options: CreateDispatcherOptions, adapter: string): DispatcherFastPathState;
+//# sourceMappingURL=dispatcher-state.d.ts.map

package/dist/dispatch/fast-path/dispatcher-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher-state.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/dispatcher-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAGhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE3E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,cAAc,IAAI,SAAS,iBAAiB,EAAE,CAAC;IAC/C,cAAc,CAAC,UAAU,EAAE,iBAAiB,GAAG,mBAAmB,GAAG,SAAS,CAAC;CAChF;AAqBD,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,SAAS,iBAAiB,EAAE,EACzC,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,MAAM,GACd,uBAAuB,CA6BzB"}

package/dist/dispatch/fast-path/dispatcher-state.js

@@ -0,0 +1,52 @@
+import { createFastPathStats } from './debug-visibility.js';
+import { compileFastPathEligibility, setHandlerFastPathEligibility } from './eligibility-checker.js';
+function cloneHandlerDescriptor(descriptor) {
+  return {
+    ...descriptor,
+    metadata: {
+      ...descriptor.metadata,
+      moduleMiddleware: [...descriptor.metadata.moduleMiddleware],
+      pathParams: [...descriptor.metadata.pathParams]
+    },
+    route: {
+      ...descriptor.route,
+      guards: descriptor.route.guards ? [...descriptor.route.guards] : undefined,
+      headers: descriptor.route.headers?.map(header => ({
+        ...header
+      })),
+      interceptors: descriptor.route.interceptors ? [...descriptor.route.interceptors] : undefined,
+      produces: descriptor.route.produces ? [...descriptor.route.produces] : undefined,
+      redirect: descriptor.route.redirect ? {
+        ...descriptor.route.redirect
+      } : undefined
+    }
+  };
+}
+export function createDispatcherFastPathState(descriptors, options, adapter) {
+  const eligibilities = new WeakMap();
+  const compiledEligibilities = [];
+  for (const descriptor of descriptors) {
+    const {
+      eligibility
+    } = compileFastPathEligibility(descriptor, options, adapter);
+    eligibilities.set(descriptor, eligibility);
+    compiledEligibilities.push(eligibility);
+  }
+  return Object.freeze({
+    describeRoutes() {
+      return descriptors.map(descriptor => {
+        const cloned = cloneHandlerDescriptor(descriptor);
+        const eligibility = eligibilities.get(descriptor);
+        if (eligibility) {
+          setHandlerFastPathEligibility(cloned, eligibility);
+          eligibilities.set(cloned, eligibility);
+        }
+        return cloned;
+      });
+    },
+    getEligibility(descriptor) {
+      return eligibilities.get(descriptor);
+    },
+    stats: createFastPathStats(compiledEligibilities)
+  });
+}

package/dist/dispatch/fast-path/eligibility-checker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eligibility-checker.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/eligibility-checker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EACV,MAAM,EACN,iBAAiB,EAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,kBAAkB,CAAC;AAM1F,UAAU,uBAAuB;IAC/B,WAAW,EAAE,mBAAmB,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;CACrB;AA0DD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,MAAM,GACd,uBAAuB,CAiEzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,GACzB,mBAAmB,GAAG,SAAS,CAIjC;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,mBAAmB,GAC/B,IAAI,CAGN;AAED,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,SAAS,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}
+{"version":3,"file":"eligibility-checker.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/eligibility-checker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EACV,MAAM,EACN,iBAAiB,EAElB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,mBAAmB,EAAgC,MAAM,kBAAkB,CAAC;AAM1F,UAAU,uBAAuB;IAC/B,WAAW,EAAE,mBAAmB,CAAC;IACjC,UAAU,EAAE,OAAO,CAAC;CACrB;AA0DD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,MAAM,GACd,uBAAuB,CAsEzB;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,GACzB,mBAAmB,GAAG,SAAS,CAIjC;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,mBAAmB,GAC/B,IAAI,CAON;AAED,oDAAoD;AACpD,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,SAAS,CAAC;CAC1B;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/dispatch/fast-path/eligibility-checker.js

@@ -58,10 +58,10 @@ export function compileFastPathEligibility(handler, options, adapter) {
   const hasRequestScopedDI = determineRequestScopeRequirement(handler, options);
   const hasMiddleware = determineMiddlewareRequirement(handler, options.appMiddleware ?? []);
   const hasContentNegotiation = options.contentNegotiation?.formatters !== undefined && options.contentNegotiation.formatters.length > 0;
+  const hasConditionalRequest = options.conditionalRequest !== undefined;
   const isSseRoute = handler.route.produces?.some(mediaType => mediaType.toLowerCase().startsWith('text/event-stream')) === true;
-  const eligibility = {
+  const eligibilityBase = {
     adapter,
-    executionPath: 'full',
     hasAdapterPluginInfluence: false,
     hasCustomBodyParser: options.binder !== undefined,
     hasCustomErrorFilter: options.onError !== undefined,
@@ -74,39 +74,44 @@ export function compileFastPathEligibility(handler, options, adapter) {
     routeId
   };
   const blockingReasons = [];
-  if (eligibility.hasGuard) {
+  if (eligibilityBase.hasGuard) {
     blockingReasons.push('guards');
   }
-  if (eligibility.hasInterceptor) {
+  if (eligibilityBase.hasInterceptor) {
     blockingReasons.push('interceptors');
   }
-  if (eligibility.hasRequestScopedDI) {
+  if (eligibilityBase.hasRequestScopedDI) {
     blockingReasons.push('request-scoped DI');
   }
-  if (eligibility.hasMiddleware) {
+  if (eligibilityBase.hasMiddleware) {
     blockingReasons.push('middleware');
   }
-  if (eligibility.hasGlobalHook) {
+  if (eligibilityBase.hasGlobalHook) {
     blockingReasons.push('request observers');
   }
-  if (eligibility.hasCustomErrorFilter) {
+  if (eligibilityBase.hasCustomErrorFilter) {
     blockingReasons.push('custom error filter');
   }
-  if (eligibility.hasCustomBodyParser) {
+  if (eligibilityBase.hasCustomBodyParser) {
     blockingReasons.push('custom binder');
   }
   if (hasContentNegotiation) {
     blockingReasons.push('content negotiation');
   }
+  if (hasConditionalRequest) {
+    blockingReasons.push('conditional requests');
+  }
   if (isSseRoute) {
     blockingReasons.push('SSE streaming');
   }
   const isEligible = blockingReasons.length === 0;
-  if (!isEligible) {
-    eligibility.fallbackReason = `Full path required due to: ${blockingReasons.join(', ')}`;
-  } else {
-    eligibility.executionPath = 'fast';
-  }
+  const eligibility = Object.freeze({
+    ...eligibilityBase,
+    executionPath: isEligible ? 'fast' : 'full',
+    ...(isEligible ? {} : {
+      fallbackReason: `Full path required due to: ${blockingReasons.join(', ')}`
+    })
+  });
   return {
     eligibility,
     isEligible
@@ -130,7 +135,14 @@ export function getHandlerFastPathEligibility(handler) {
  * @param eligibility Eligibility metadata to expose through dispatcher observability.
  */
 export function setHandlerFastPathEligibility(handler, eligibility) {
-  handler[FAST_PATH_ELIGIBILITY_SYMBOL] = eligibility;
+  Object.defineProperty(handler, FAST_PATH_ELIGIBILITY_SYMBOL, {
+    configurable: false,
+    enumerable: false,
+    value: Object.freeze({
+      ...eligibility
+    }),
+    writable: false
+  });
 }
 
 /** Options shared by fast-path executor helpers. */