@fluojs/http 1.0.0-beta.4 → 1.0.0-beta.6

package/dist/dispatch/dispatcher.js

@@ -1,23 +1,23 @@
-import { readFrameworkRequestNativeRouteHandoff } from './native-route-handoff.js';
-import { invokeControllerHandler } from './dispatch-handler-policy.js';
-import { resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
-import { matchHandlerOrThrow, updateRequestParams } from './dispatch-routing-policy.js';
 import { getCompiledDtoBindingPlan } from '../adapters/dto-binding-plan.js';
+import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
+import { SseResponse } 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 { createRequestContext, runWithRequestContext } from '../context/request-context.js';
-import { SseResponse } from '../context/sse.js';
+import { invokeControllerHandler } from './dispatch-handler-policy.js';
+import { resolveContentNegotiation, writeErrorResponse, writeSuccessResponse } from './dispatch-response-policy.js';
+import { matchHandlerOrThrow, updateRequestParams } from './dispatch-routing-policy.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';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL } from './fast-path/index.js';
 
-/**
- * Type definition for a global HTTP error handler function.
- */
+/** Type definition for a global HTTP error handler function. */
 
-/**
- * Options for creating an HTTP {@link Dispatcher}.
- */
+/** Options for creating an HTTP {@link Dispatcher}. */
 
+const EMPTY_NATIVE_FAST_PATH_HANDLER_EXECUTION_PLANS = new WeakMap();
+const EMPTY_NATIVE_FAST_PATH_OBSERVERS = [];
 function logDispatchFailure(logger, message, error) {
   if (logger) {
     logger.error(message, error, 'HttpDispatcher');
@@ -26,15 +26,37 @@ function logDispatchFailure(logger, message, error) {
   console.error(`[fluo][HttpDispatcher] ${message}`, error);
 }
 function createDispatchRequest(request) {
-  return {
-    ...request,
+  const dispatchRequest = {
+    get cookies() {
+      return request.cookies;
+    },
+    get headers() {
+      return request.headers;
+    },
+    get query() {
+      return request.query;
+    },
+    body: request.body,
+    method: request.method,
     params: {
       ...request.params
-    }
+    },
+    path: request.path,
+    raw: request.raw,
+    rawBody: request.rawBody,
+    requestId: request.requestId,
+    signal: request.signal,
+    url: request.url
   };
+  const nativeRouteHandoff = readFrameworkRequestNativeRouteHandoff(request);
+  const files = request.files;
+  if (files !== undefined) {
+    dispatchRequest.files = files;
+  }
+  return nativeRouteHandoff ? attachFrameworkRequestNativeRouteHandoff(dispatchRequest, nativeRouteHandoff) : dispatchRequest;
 }
 function cloneHandlerDescriptor(descriptor) {
-  return {
+  const cloned = {
     ...descriptor,
     metadata: {
       ...descriptor.metadata,
@@ -54,8 +76,16 @@ function cloneHandlerDescriptor(descriptor) {
       } : 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();
@@ -72,16 +102,53 @@ function createDispatchContext(request, response, container, promoteOnContainerA
   if (!promoteOnContainerAccess) {
     return context;
   }
+
+  // Wrap the container to only promote to request scope when resolve() is actually called.
+  // This allows fast-path handlers to check ctx.container without triggering scope creation.
   let activeContainer = container;
+  let wrappedContainer;
+  let promoted = false;
+  const ensurePromoted = () => {
+    if (!promoted) {
+      activeContainer = promoteOnContainerAccess();
+      promoted = true;
+    }
+    return activeContainer;
+  };
+  const getWrappedContainer = () => {
+    if (!wrappedContainer) {
+      wrappedContainer = {
+        async resolve(token) {
+          const targetContainer = ensurePromoted();
+          return targetContainer.resolve(token);
+        },
+        async dispose() {
+          // If promotion never happened, this is a no-op.
+          // This prevents accidentally disposing the root container when a
+          // captured container reference is used after a singleton-only request.
+          if (!promoted) {
+            return;
+          }
+          return activeContainer.dispose();
+        }
+      };
+    }
+    return wrappedContainer;
+  };
   Object.defineProperty(context, 'container', {
     configurable: true,
     enumerable: true,
     get() {
-      activeContainer = promoteOnContainerAccess();
-      return activeContainer;
+      // If promotion has already occurred, return the actual container.
+      if (promoted) {
+        return activeContainer;
+      }
+      // Return the wrapped container that will promote on resolve().
+      return getWrappedContainer();
     },
     set(value) {
       activeContainer = value;
+      promoted = true;
     }
   });
   return context;
@@ -106,6 +173,25 @@ function activeMiddlewareMayRequireRequestScope(definitions, request) {
     return definition.routes.length === 0 || definition.routes.some(route => matchRoutePattern(route, request.path));
   });
 }
+function compileMiddlewareScopePlan(definitions) {
+  const conditionalDefinitions = [];
+  for (const definition of definitions) {
+    if (!isMiddlewareRouteConfig(definition) || definition.routes.length === 0) {
+      return {
+        alwaysRequiresRequestScope: true,
+        conditionalDefinitions: []
+      };
+    }
+    conditionalDefinitions.push(definition);
+  }
+  return {
+    alwaysRequiresRequestScope: false,
+    conditionalDefinitions
+  };
+}
+function compiledMiddlewareMayRequireRequestScope(plan, request) {
+  return plan.alwaysRequiresRequestScope || activeMiddlewareMayRequireRequestScope(plan.conditionalDefinitions, request);
+}
 function requestDtoMayRequireRequestScope(handler, options) {
   if (!handler.route.request) {
     return false;
@@ -126,26 +212,29 @@ function handlerMethodMayUseRequestContext(handler) {
 function hasRequestScopeInspector(container) {
   return typeof container === 'object' && container !== null && 'hasRequestScopedDependency' in container && typeof container.hasRequestScopedDependency === 'function';
 }
-function handlerMayRequireRequestScope(handler, request, options) {
-  if (handler.route.guards && handler.route.guards.length > 0) {
-    return true;
-  }
-  if ((options.interceptors ?? []).length > 0 || (handler.route.interceptors ?? []).length > 0) {
-    return true;
-  }
-  if (activeMiddlewareMayRequireRequestScope(handler.metadata.moduleMiddleware, request)) {
-    return true;
-  }
-  if (requestDtoMayRequireRequestScope(handler, options)) {
-    return true;
-  }
-  if (handlerMethodMayUseRequestContext(handler)) {
-    return true;
-  }
-  return hasRequestScopeInspector(options.rootContainer) ? options.rootContainer.hasRequestScopedDependency(handler.controllerToken) : true;
+function compileHandlerExecutionPlan(handler, options) {
+  const routeGuards = handler.route.guards ?? [];
+  const requestScope = compileMiddlewareScopePlan(handler.metadata.moduleMiddleware);
+  const mergedInterceptors = mergeInterceptors(options.interceptors ?? [], handler.route.interceptors ?? []);
+  return {
+    mergedInterceptors,
+    requestScope,
+    requiresRequestScope: routeGuards.length > 0 || mergedInterceptors.length > 0 || requestScope.alwaysRequiresRequestScope || requestDtoMayRequireRequestScope(handler, options) || handlerMethodMayUseRequestContext(handler) || (hasRequestScopeInspector(options.rootContainer) ? options.rootContainer.hasRequestScopedDependency(handler.controllerToken) : true),
+    routeGuards
+  };
 }
-function dispatchStartMayRequireRequestScope(request, observers, options) {
-  return observers.length > 0 || activeMiddlewareMayRequireRequestScope(options.appMiddleware ?? [], request);
+function handlerMayRequireRequestScope(plan, request) {
+  return plan.requiresRequestScope || compiledMiddlewareMayRequireRequestScope(plan.requestScope, request);
+}
+function compileDispatchStartPlan(observers, appMiddleware) {
+  const requestScope = compileMiddlewareScopePlan(appMiddleware);
+  return {
+    requestScope,
+    requiresRequestScope: observers.length > 0 || requestScope.alwaysRequiresRequestScope
+  };
+}
+function dispatchStartMayRequireRequestScope(plan, request) {
+  return plan.requiresRequestScope || compiledMiddlewareMayRequireRequestScope(plan.requestScope, request);
 }
 function ensureRequestScope(context) {
   if (context.dispatchScope.requestScoped) {
@@ -155,10 +244,38 @@ function ensureRequestScope(context) {
   context.requestContext.container = context.dispatchScope.container;
 }
 function ensureRequestNotAborted(request) {
-  if (request.signal?.aborted) {
+  if (isRequestAborted(request)) {
     throw new RequestAbortedError();
   }
 }
+function isRequestAborted(request) {
+  return request.isAborted?.() ?? request.signal?.aborted === true;
+}
+function resolveFastPathHandlerRuntimeCache(handler, cache) {
+  const cached = cache.get(handler);
+  if (cached) {
+    return cached;
+  }
+  const method = handler.controllerToken.prototype[handler.methodName];
+  const compiled = {
+    method: typeof method === 'function' ? method : undefined
+  };
+  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;
 }
@@ -197,8 +314,8 @@ function mergeInterceptors(globalInterceptors, routeInterceptors) {
   }
   return [...globalInterceptors, ...routeInterceptors];
 }
-async function dispatchMatchedHandler(handler, requestContext, controllerContainer, observers, contentNegotiation, binder, globalInterceptors, logger) {
-  const routeGuards = handler.route.guards ?? [];
+async function dispatchMatchedHandler(handler, executionPlan, requestContext, controllerContainer, observers, contentNegotiation, binder, logger) {
+  const routeGuards = executionPlan.routeGuards;
   if (routeGuards.length > 0) {
     const guardContext = {
       handler,
@@ -209,8 +326,7 @@ async function dispatchMatchedHandler(handler, requestContext, controllerContain
   if (requestContext.response.committed) {
     return;
   }
-  const routeInterceptors = handler.route.interceptors ?? [];
-  const result = globalInterceptors.length === 0 && routeInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder, controllerContainer) : await runInterceptorChain(mergeInterceptors(globalInterceptors, routeInterceptors), {
+  const result = executionPlan.mergedInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder, controllerContainer) : await runInterceptorChain(executionPlan.mergedInterceptors, {
     handler,
     requestContext
   }, async () => invokeControllerHandler(handler, requestContext, binder, controllerContainer));
@@ -222,6 +338,68 @@ async function dispatchMatchedHandler(handler, requestContext, controllerContain
     await observer.onRequestSuccess?.(context, result);
   }, logger, handler);
 }
+function resolveHandlerExecutionPlan(handler, executionPlans, options) {
+  const cached = executionPlans.get(handler);
+  if (cached) {
+    return cached;
+  }
+  const compiled = compileHandlerExecutionPlan(handler, options);
+  executionPlans.set(handler, compiled);
+  return compiled;
+}
+async function dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathRuntimeCache) {
+  const eligibility = getHandlerFastPathEligibility(match.descriptor);
+  if (!shouldUseFastPathForRequest(eligibility, request)) {
+    return false;
+  }
+  const dispatchRequest = request;
+  const dispatchScope = createRootDispatchScope(options.rootContainer);
+  let phaseContext;
+  let containerPromotionOpen = true;
+  const requestContext = createDispatchContext(dispatchRequest, response, dispatchScope.container, () => {
+    if (!containerPromotionOpen) {
+      return phaseContext.dispatchScope.container;
+    }
+    ensureRequestScope(phaseContext);
+    return phaseContext.dispatchScope.container;
+  });
+  phaseContext = {
+    contentNegotiation,
+    dispatchScope,
+    fastPathRuntimeCache,
+    handlerExecutionPlans: EMPTY_NATIVE_FAST_PATH_HANDLER_EXECUTION_PLANS,
+    observers: EMPTY_NATIVE_FAST_PATH_OBSERVERS,
+    options,
+    requestContext,
+    response
+  };
+  phaseContext.matchedHandler = match.descriptor;
+  updateRequestParams(phaseContext.requestContext, match.params);
+  await runWithRequestContext(phaseContext.requestContext, async () => {
+    try {
+      ensureRequestNotAborted(phaseContext.requestContext.request);
+      const fastPathSuccess = await tryFastPathExecution(match.descriptor, phaseContext);
+      if (!fastPathSuccess) {
+        throw new Error(`Native route ${match.descriptor.route.method}:${match.descriptor.route.path} was not fast-path executable.`);
+      }
+    } catch (error) {
+      await handleDispatchError(phaseContext, error);
+    } finally {
+      if (!phaseContext.dispatchScope.requestScoped) {
+        phaseContext.requestContext.container = phaseContext.dispatchScope.container;
+      }
+      containerPromotionOpen = false;
+      if (phaseContext.dispatchScope.requestScoped) {
+        try {
+          await phaseContext.dispatchScope.container.dispose();
+        } catch (error) {
+          logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+        }
+      }
+    }
+  });
+  return true;
+}
 async function notifyRequestStart(context) {
   await notifyObserversSafely(context.observers, context.requestContext, async (observer, observationContext) => {
     await observer.onRequestStart?.(observationContext);
@@ -242,6 +420,36 @@ async function notifyRequestFinish(context) {
     await observer.onRequestFinish?.(observationContext);
   }, context.options.logger, context.matchedHandler);
 }
+async function tryFastPathExecution(handler, context) {
+  const eligibility = getHandlerFastPathEligibility(handler);
+  if (!eligibility || eligibility.executionPath !== 'fast') {
+    return false;
+  }
+  if (typeof context.dispatchScope.container.resolve !== 'function') {
+    ensureRequestScope(context);
+  }
+  const runtimeCache = resolveFastPathHandlerRuntimeCache(handler, context.fastPathRuntimeCache);
+  const controllerOrPromise = resolveFastPathController(handler, context.dispatchScope.container, runtimeCache);
+  const controller = isPromiseLike(controllerOrPromise) ? await controllerOrPromise : controllerOrPromise;
+  const fastPathResult = await executeFastPath({
+    binder: context.options.binder,
+    contentNegotiation: context.contentNegotiation,
+    controller,
+    controllerContainer: context.dispatchScope.container,
+    handler,
+    method: runtimeCache.method,
+    request: context.requestContext.request,
+    requestContext: context.requestContext,
+    response: context.response
+  });
+  if (fastPathResult.executed) {
+    return true;
+  }
+  if (fastPathResult.error) {
+    throw fastPathResult.error;
+  }
+  return false;
+}
 async function runDispatchPipeline(context) {
   ensureRequestNotAborted(context.requestContext.request);
   const appMiddlewareContext = {
@@ -249,16 +457,28 @@ async function runDispatchPipeline(context) {
     requestContext: context.requestContext,
     response: context.response
   };
-  await runMiddlewareChain(context.options.appMiddleware ?? [], appMiddlewareContext, async () => {
+  const dispatchMatchedRoute = async () => {
     if (context.response.committed) {
       return;
     }
     const match = readFrameworkRequestNativeRouteHandoff(appMiddlewareContext.request) ?? matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
     context.matchedHandler = match.descriptor;
-    if (handlerMayRequireRequestScope(match.descriptor, appMiddlewareContext.request, context.options)) {
+    updateRequestParams(context.requestContext, match.params);
+    const eligibility = getHandlerFastPathEligibility(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)) {
+      const fastPathSuccess = await tryFastPathExecution(match.descriptor, context);
+      if (fastPathSuccess) {
+        return;
+      }
+    }
+    const executionPlan = resolveHandlerExecutionPlan(match.descriptor, context.handlerExecutionPlans, context.options);
+    if (handlerMayRequireRequestScope(executionPlan, appMiddlewareContext.request)) {
       ensureRequestScope(context);
     }
-    updateRequestParams(context.requestContext, match.params);
     await notifyHandlerMatched(context, match.descriptor);
     const moduleMiddlewareContext = {
       request: context.requestContext.request,
@@ -266,12 +486,18 @@ async function runDispatchPipeline(context) {
       response: context.response
     };
     await runMiddlewareChain(match.descriptor.metadata.moduleMiddleware ?? [], moduleMiddlewareContext, async () => {
-      await dispatchMatchedHandler(match.descriptor, context.requestContext, context.dispatchScope.container, context.observers, context.contentNegotiation, context.options.binder, context.options.interceptors ?? [], context.options.logger);
+      await dispatchMatchedHandler(match.descriptor, executionPlan, context.requestContext, context.dispatchScope.container, context.observers, context.contentNegotiation, context.options.binder, context.options.logger);
     });
-  });
+  };
+  const appMiddleware = context.options.appMiddleware ?? [];
+  if (appMiddleware.length === 0) {
+    await dispatchMatchedRoute();
+    return;
+  }
+  await runMiddlewareChain(appMiddleware, appMiddlewareContext, dispatchMatchedRoute);
 }
 async function handleDispatchError(context, error) {
-  if (error instanceof RequestAbortedError || context.requestContext.request.signal?.aborted) {
+  if (error instanceof RequestAbortedError || isRequestAborted(context.requestContext.request)) {
     return;
   }
   await notifyRequestError(context, error);
@@ -291,13 +517,31 @@ async function handleDispatchError(context, error) {
 export function createDispatcher(options) {
   const contentNegotiation = resolveContentNegotiation(options.contentNegotiation);
   const observers = options.observers ?? [];
+  const appMiddleware = options.appMiddleware ?? [];
+  const dispatchStartPlan = compileDispatchStartPlan(observers, appMiddleware);
+  const fastPathRuntimeCache = new WeakMap();
+  const handlerExecutionPlans = new WeakMap();
+  const adapter = options.adapter ?? 'default';
+  const fastPathEligibilities = [];
+  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));
     },
+    async dispatchNativeRoute(match, request, response) {
+      return dispatchNativeFastRoute(match, request, response, options, contentNegotiation, fastPathRuntimeCache);
+    },
     async dispatch(request, response) {
       const dispatchRequest = createDispatchRequest(request);
-      const dispatchScope = dispatchStartMayRequireRequestScope(dispatchRequest, observers, options) ? createRequestDispatchScope(options.rootContainer) : createRootDispatchScope(options.rootContainer);
+      const dispatchScope = dispatchStartMayRequireRequestScope(dispatchStartPlan, dispatchRequest) ? createRequestDispatchScope(options.rootContainer) : createRootDispatchScope(options.rootContainer);
       let phaseContext;
       let containerPromotionOpen = true;
       const requestContext = createDispatchContext(dispatchRequest, response, dispatchScope.container, () => {
@@ -310,6 +554,8 @@ export function createDispatcher(options) {
       phaseContext = {
         contentNegotiation,
         dispatchScope,
+        fastPathRuntimeCache,
+        handlerExecutionPlans,
         observers,
         options,
         requestContext,
@@ -317,12 +563,19 @@ export function createDispatcher(options) {
       };
       await runWithRequestContext(phaseContext.requestContext, async () => {
         try {
-          await notifyRequestStart(phaseContext);
+          if (observers.length > 0) {
+            await notifyRequestStart(phaseContext);
+          }
           await runDispatchPipeline(phaseContext);
         } catch (error) {
           await handleDispatchError(phaseContext, error);
         } finally {
-          await notifyRequestFinish(phaseContext);
+          if (observers.length > 0) {
+            await notifyRequestFinish(phaseContext);
+          }
+          if (!phaseContext.dispatchScope.requestScoped) {
+            phaseContext.requestContext.container = phaseContext.dispatchScope.container;
+          }
           containerPromotionOpen = false;
           if (phaseContext.dispatchScope.requestScoped) {
             try {
@@ -335,5 +588,17 @@ export function createDispatcher(options) {
       });
     }
   };
+  dispatcher[FAST_PATH_STATS_SYMBOL] = fastPathStats;
   return dispatcher;
-}
+}
+
+/**
+ * Reads automatic fast-path eligibility statistics attached to a dispatcher.
+ *
+ * @param dispatcher Dispatcher returned by {@link createDispatcher}.
+ * @returns Fast-path statistics when available.
+ */
+export function getDispatcherFastPathStats(dispatcher) {
+  return dispatcher[FAST_PATH_STATS_SYMBOL];
+}
+export { formatFastPathStats } from './fast-path/index.js';

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

@@ -0,0 +1,18 @@
+import type { FastPathEligibility, FastPathStats } from './eligibility.js';
+interface PathDebugInfo {
+    executionPath: 'fast' | 'full';
+    fallbackReason?: string;
+    routeId: string;
+}
+export declare function createPathDebugInfo(eligibility: FastPathEligibility): PathDebugInfo;
+export declare function addPathDebugHeader(setHeader: (name: string, value: string) => void, info: PathDebugInfo): void;
+export declare function createFastPathStats(eligibilities: readonly FastPathEligibility[]): FastPathStats;
+/**
+ * Formats dispatcher fast-path statistics for debug logs and benchmark output.
+ *
+ * @param stats Fast-path statistics returned by {@link getDispatcherFastPathStats}.
+ * @returns A human-readable route breakdown.
+ */
+export declare function formatFastPathStats(stats: FastPathStats): string;
+export {};
+//# sourceMappingURL=debug-visibility.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,39 @@
+const DEBUG_HEADER_NAME = 'X-Fluo-Path';
+export function createPathDebugInfo(eligibility) {
+  return {
+    executionPath: eligibility.executionPath,
+    fallbackReason: eligibility.fallbackReason,
+    routeId: eligibility.routeId
+  };
+}
+export function addPathDebugHeader(setHeader, info) {
+  const value = info.executionPath === 'fast' ? `fast; route=${info.routeId}` : `full; route=${info.routeId}; reason=${info.fallbackReason ?? 'none'}`;
+  setHeader(DEBUG_HEADER_NAME, value);
+}
+export function createFastPathStats(eligibilities) {
+  const fastPathRoutes = eligibilities.filter(e => e.executionPath === 'fast').length;
+  return {
+    fastPathRoutes,
+    fullPathRoutes: eligibilities.length - fastPathRoutes,
+    routes: eligibilities,
+    totalRoutes: eligibilities.length
+  };
+}
+
+/**
+ * Formats dispatcher fast-path statistics for debug logs and benchmark output.
+ *
+ * @param stats Fast-path statistics returned by {@link getDispatcherFastPathStats}.
+ * @returns A human-readable route breakdown.
+ */
+export function formatFastPathStats(stats) {
+  const fastPathPercent = stats.totalRoutes === 0 ? '0.0' : (stats.fastPathRoutes / stats.totalRoutes * 100).toFixed(1);
+  const fullPathPercent = stats.totalRoutes === 0 ? '0.0' : (stats.fullPathRoutes / stats.totalRoutes * 100).toFixed(1);
+  const lines = ['=== Fast Path Statistics ===', `Total routes: ${String(stats.totalRoutes)}`, `Fast path: ${String(stats.fastPathRoutes)} (${fastPathPercent}%)`, `Full path: ${String(stats.fullPathRoutes)} (${fullPathPercent}%)`, '', 'Route breakdown:'];
+  for (const route of stats.routes) {
+    const status = route.executionPath === 'fast' ? 'FAST' : 'FULL';
+    const reason = route.fallbackReason ? ` (${route.fallbackReason})` : '';
+    lines.push(`  [${status}] ${route.routeId}${reason}`);
+  }
+  return lines.join('\n');
+}

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

@@ -0,0 +1,22 @@
+import type { Container } from '@fluojs/di';
+import type { Binder, HandlerDescriptor } from '../../types.js';
+import type { CreateDispatcherOptions } from '../dispatcher.js';
+import { type FastPathEligibility } from './eligibility.js';
+interface CompiledEligibilityPlan {
+    eligibility: FastPathEligibility;
+    isEligible: boolean;
+}
+export declare function compileFastPathEligibility(handler: HandlerDescriptor, options: CreateDispatcherOptions, adapter: string): CompiledEligibilityPlan;
+export declare function getHandlerFastPathEligibility(handler: HandlerDescriptor): FastPathEligibility | undefined;
+export declare function setHandlerFastPathEligibility(handler: HandlerDescriptor, eligibility: FastPathEligibility): void;
+export interface FastPathExecutorOptions {
+    binder?: Binder;
+    rootContainer: Container;
+}
+export interface FastPathExecutionResult {
+    executed: boolean;
+    result?: unknown;
+    error?: unknown;
+}
+export {};
+//# sourceMappingURL=eligibility-checker.d.ts.map

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

@@ -0,0 +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,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,MAAM,GACd,uBAAuB,CAgEzB;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,GACzB,mBAAmB,GAAG,SAAS,CAIjC;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,WAAW,EAAE,mBAAmB,GAC/B,IAAI,CAGN;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}