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

package/README.ko.md

@@ -115,7 +115,7 @@ stream(_input: undefined, ctx: RequestContext) {
 
 ## 요청 정리와 런타임 이식성
 
-디스패처는 활성 dispatch 동안에만 `AsyncLocalStorage`로 `RequestContext`를 바인딩하고, 요청 observer가 끝난 뒤 `finally` 경로에서 request-scoped DI 컨테이너를 dispose합니다. 이 동작은 정상 성공, 처리된 오류, 중단된 요청 경로에서 request-scoped provider가 다음 요청으로 새지 않게 합니다.
+디스패처는 활성 dispatch 동안에만 `AsyncLocalStorage`로 `RequestContext`를 바인딩합니다. 요청이 controller graph, middleware, guard, interceptor, observer, DTO converter, custom binder 또는 수동 `getCurrentRequestContext()` / `assertRequestContext()` container 접근을 통해 request-scoped DI를 사용할 수 있으면, 디스패처는 요청 observer가 끝난 뒤 `finally` 경로에서 isolated request-scoped DI 컨테이너를 생성하고 dispose합니다. Singleton-only route는 `RequestContext.container`가 접근되기 전까지 이 컨테이너 lifecycle을 건너뛰어 baseline 경로의 불필요한 per-request allocation을 피하면서도, graph가 모호하거나 request-scoped이면 request-scoped provider isolation을 유지합니다. 따라서 공개 `RequestContext.container` 읽기는 request-scoped provider resolve에 항상 안전합니다. singleton-only fast path는 내부 dispatcher 최적화일 뿐, 공개 context가 root container를 노출한다는 약속이 아닙니다.
 
 어댑터는 플랫폼이 제공한다면 `FrameworkRequest.signal`에 `AbortSignal`을 전달해야 합니다. SSE에서는 가능하면 `FrameworkResponse.stream.onClose(...)`도 노출해야 합니다. `SseResponse`는 request abort와 raw stream close를 모두 구독하고, 멱등하게 닫히며, 어느 쪽이 먼저 종료되더라도 등록한 listener를 제거합니다.
 
@@ -133,6 +133,9 @@ stream(_input: undefined, ctx: RequestContext) {
 `./internal` 서브경로는 플랫폼 어댑터와 핵심 런타임에서 사용하는 저수준 유틸리티만 내보냅니다. 이들은 변경될 수 있으며 일반적인 애플리케이션 코드에서 사용해서는 안 됩니다.
 
 - `DefaultBinder`: 런타임 부트스트랩 경로에서 사용하는 기본 DTO/요청 바인더.
+- `bindRawRequestNativeRouteHandoff(...)` / `attachFrameworkRequestNativeRouteHandoff(...)`: public dispatcher API를 넓히지 않고 의미 보존이 가능한 native route match를 재사용하기 위한 내부 adapter/runtime 헬퍼.
+- Native route handoff는 framework request에 붙는 시점의 method와 path를 함께 스냅샷합니다. app middleware가 handler matching 전에 둘 중 하나를 rewrite하면 dispatcher는 stale handoff를 무시하고 일반 route matching으로 fallback합니다.
+- `isRoutePathNormalizationSensitive(path)`: duplicate slash와 trailing slash 요청을 generic dispatcher 경로에 남기기 위한 내부 guard.
 - `resolveClientIdentity(request)`: 속도 제한과 런타임 통합에서 사용하는 보수적 클라이언트 식별 해석기.
 
 ## 관련 패키지

package/README.md

@@ -117,7 +117,7 @@ stream(_input: undefined, ctx: RequestContext) {
 
 ## Request Cleanup and Portability
 
-The dispatcher binds `RequestContext` with `AsyncLocalStorage` for the active dispatch only and disposes the request-scoped DI container from its `finally` path after request observers finish. This keeps per-request providers from leaking across normal success, handled error, and aborted request paths.
+The dispatcher binds `RequestContext` with `AsyncLocalStorage` for the active dispatch only. When a request may use request-scoped DI through its controller graph, middleware, guards, interceptors, observers, DTO converters, a custom binder, or manual `getCurrentRequestContext()` / `assertRequestContext()` container access, the dispatcher creates and disposes an isolated request-scoped DI container from its `finally` path after request observers finish. Singleton-only routes skip that container lifecycle until `RequestContext.container` is accessed, so the baseline path avoids unnecessary per-request allocation while preserving request-scoped provider isolation whenever the graph is ambiguous or request-scoped. Public `RequestContext.container` reads are therefore always safe for resolving request-scoped providers; the singleton-only fast path is an internal dispatcher optimization, not a promise that the public context exposes the root container.
 
 Adapters should pass an `AbortSignal` on `FrameworkRequest.signal` when the platform exposes one. For SSE, adapters should also expose `FrameworkResponse.stream.onClose(...)` when possible; `SseResponse` listens to both request abort and raw stream close, closes idempotently, and removes registered listeners when either side terminates first.
 
@@ -135,6 +135,9 @@ Adapters should pass an `AbortSignal` on `FrameworkRequest.signal` when the plat
 The `./internal` subpath exports only the low-level utilities used by platform adapters and the core runtime. These are subject to change and should not be used in typical application code.
 
 - `DefaultBinder`: Default DTO/request binder used by the runtime bootstrap path.
+- `bindRawRequestNativeRouteHandoff(...)` / `attachFrameworkRequestNativeRouteHandoff(...)`: Internal adapter/runtime helpers for reusing semantically safe native route matches without widening the public dispatcher API.
+- Native route handoffs snapshot the framework request method and path when attached; if app middleware rewrites either value before handler matching, the dispatcher ignores the stale handoff and falls back to normal route matching.
+- `isRoutePathNormalizationSensitive(path)`: Internal guard for keeping duplicate-slash and trailing-slash requests on the generic dispatcher path.
 - `resolveClientIdentity(request)`: Conservative client identity resolver used by rate limiting and other runtime integrations.
 
 ## Related Packages

package/dist/adapters/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAA6D,MAAM,cAAc,CAAC;AAK3H,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AA4FhI;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAyDD;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,GAAE,SAAS,aAAa,EAAO;IAEhE,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;CA0EjF"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAI5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AAiDhI;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAyDD;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,GAAE,SAAS,aAAa,EAAO;IAEhE,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;CA+DjF"}

package/dist/adapters/binding.js

@@ -1,7 +1,7 @@
 import { InvariantError } from '@fluojs/core';
-import { getDtoBindingSchema } from '@fluojs/core/internal';
 import { BadRequestException } from '../exceptions.js';
 import { toInputErrorDetail } from '../input-error-detail.js';
+import { getCompiledDtoBindingPlan } from './dto-binding-plan.js';
 const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function isPlainObject(value) {
   if (typeof value !== 'object' || value === null) {
@@ -10,44 +10,6 @@ function isPlainObject(value) {
   const prototype = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
-function toFieldName(propertyKey) {
-  return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
-}
-function resolveSourceKey(propertyKey, key) {
-  return key ?? toFieldName(propertyKey);
-}
-function readHeader(request, key) {
-  return request.headers[key.toLowerCase()] ?? request.headers[key];
-}
-function readSourceValue(request, source, propertyKey, key) {
-  const resolvedKey = resolveSourceKey(propertyKey, key);
-  switch (source) {
-    case 'path':
-      return request.params[resolvedKey];
-    case 'query':
-      return request.query[resolvedKey];
-    case 'header':
-      return readHeader(request, resolvedKey);
-    case 'cookie':
-      return request.cookies[resolvedKey];
-    case 'body':
-      {
-        if (!isPlainObject(request.body)) {
-          if (request.body !== undefined && request.body !== null) {
-            throw new BadRequestException('Request body must be a plain object.', {
-              details: [toInputErrorDetail({
-                code: 'INVALID_BODY',
-                message: 'Request body must be a plain object.',
-                source: 'body'
-              })]
-            });
-          }
-          return undefined;
-        }
-        return request.body[resolvedKey];
-      }
-  }
-}
 function validateBodyKeys(request, bodyKeys) {
   if (request.body === undefined || request.body === null) {
     return;
@@ -144,40 +106,39 @@ export class DefaultBinder {
     this.converters = converters;
   }
   async bind(dto, context) {
-    const schema = getDtoBindingSchema(dto);
+    const plan = getCompiledDtoBindingPlan(dto);
     const value = new dto();
     const converterCache = new Map();
-    const bodyKeys = new Set(schema.filter(entry => entry.metadata.source === 'body').map(entry => resolveSourceKey(entry.propertyKey, entry.metadata.key)));
     const globalConverters = (await Promise.all(this.converters.map(converter => resolveConverter(converter, context, converterCache)))).filter(converter => Boolean(converter));
-    validateBodyKeys(context.requestContext.request, bodyKeys);
+    validateBodyKeys(context.requestContext.request, plan.bodyKeys);
     const details = [];
-    for (const entry of schema) {
-      const rawValue = readSourceValue(context.requestContext.request, entry.metadata.source, entry.propertyKey, entry.metadata.key);
+    for (const entry of plan.entries) {
+      const rawValue = entry.read(context.requestContext.request);
       if (rawValue === undefined) {
-        if (entry.metadata.optional) {
+        if (entry.optional) {
           continue;
         }
         details.push(toInputErrorDetail({
           code: 'MISSING_FIELD',
-          field: toFieldName(entry.propertyKey),
-          message: `Missing required ${entry.metadata.source} field ${resolveSourceKey(entry.propertyKey, entry.metadata.key)}.`,
-          source: entry.metadata.source
+          field: entry.fieldName,
+          message: `Missing required ${entry.source} field ${entry.sourceKey}.`,
+          source: entry.source
         }));
         continue;
       }
       const target = {
         dto,
         handler: context.handler,
-        key: resolveSourceKey(entry.propertyKey, entry.metadata.key),
+        key: entry.sourceKey,
         propertyKey: entry.propertyKey,
         requestContext: context.requestContext,
-        source: entry.metadata.source
+        source: entry.source
       };
       let convertedValue = rawValue;
       for (const converter of globalConverters) {
         convertedValue = await converter.convert(convertedValue, target);
       }
-      const fieldConverter = await resolveConverter(entry.metadata.converter, context, converterCache);
+      const fieldConverter = await resolveConverter(entry.converter, context, converterCache);
       if (fieldConverter) {
         convertedValue = await fieldConverter.convert(convertedValue, target);
       }

package/dist/adapters/dto-binding-plan.d.ts

@@ -0,0 +1,19 @@
+import { type Constructor, type MetadataPropertyKey, type MetadataSource } from '@fluojs/core';
+import { type DtoFieldBindingMetadata } from '@fluojs/core/internal';
+import type { FrameworkRequest } from '../types.js';
+export interface CompiledDtoBindingPlanEntry {
+    readonly converter?: DtoFieldBindingMetadata['converter'];
+    readonly fieldName: string;
+    readonly optional: boolean;
+    readonly propertyKey: MetadataPropertyKey;
+    readonly read: (request: FrameworkRequest) => unknown;
+    readonly source: MetadataSource;
+    readonly sourceKey: string;
+}
+export interface CompiledDtoBindingPlan {
+    readonly bodyKeys: ReadonlySet<string>;
+    readonly entries: readonly CompiledDtoBindingPlanEntry[];
+    readonly propertyKeys: readonly MetadataPropertyKey[];
+}
+export declare function getCompiledDtoBindingPlan(dto: Constructor): CompiledDtoBindingPlan;
+//# sourceMappingURL=dto-binding-plan.d.ts.map

package/dist/adapters/dto-binding-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto-binding-plan.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-binding-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAmD,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEtH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAcpD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACvD;AAqBD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,sBAAsB,CA4BlF"}

package/dist/adapters/dto-binding-plan.js

@@ -0,0 +1,54 @@
+import { getDtoBindingSchema } from '@fluojs/core/internal';
+function toFieldName(propertyKey) {
+  return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
+}
+function resolveSourceKey(propertyKey, key) {
+  return key ?? toFieldName(propertyKey);
+}
+function readHeader(request, key) {
+  return request.headers[key.toLowerCase()] ?? request.headers[key];
+}
+const dtoBindingPlanCache = new WeakMap();
+function createSourceReader(source, sourceKey) {
+  switch (source) {
+    case 'path':
+      return request => request.params[sourceKey];
+    case 'query':
+      return request => request.query[sourceKey];
+    case 'header':
+      return request => readHeader(request, sourceKey);
+    case 'cookie':
+      return request => request.cookies[sourceKey];
+    case 'body':
+      return request => request.body?.[sourceKey];
+    default:
+      return () => undefined;
+  }
+}
+export function getCompiledDtoBindingPlan(dto) {
+  const cached = dtoBindingPlanCache.get(dto);
+  if (cached) {
+    return cached;
+  }
+  const entries = getDtoBindingSchema(dto).map(entry => {
+    const sourceKey = resolveSourceKey(entry.propertyKey, entry.metadata.key);
+    return {
+      ...(entry.metadata.converter === undefined ? {} : {
+        converter: entry.metadata.converter
+      }),
+      fieldName: toFieldName(entry.propertyKey),
+      optional: entry.metadata.optional === true,
+      propertyKey: entry.propertyKey,
+      read: createSourceReader(entry.metadata.source, sourceKey),
+      source: entry.metadata.source,
+      sourceKey
+    };
+  });
+  const next = {
+    bodyKeys: new Set(entries.filter(entry => entry.source === 'body').map(entry => entry.sourceKey)),
+    entries,
+    propertyKeys: entries.map(entry => entry.propertyKey)
+  };
+  dtoBindingPlanCache.set(dto, next);
+  return next;
+}

package/dist/adapters/dto-validation-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto-validation-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-validation-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAMhD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D;;GAEG;AACH,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMzC,OAAO,CAAC,6BAA6B;IAiB/B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWzE"}
+{"version":3,"file":"dto-validation-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-validation-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAG9D;;GAEG;AACH,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMzC,OAAO,CAAC,6BAA6B;IAiB/B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWzE"}

package/dist/adapters/dto-validation-adapter.js

@@ -1,7 +1,8 @@
-import { getDtoBindingSchema } from '@fluojs/core/internal';
 import { DefaultValidator as BaseDefaultValidator, DtoValidationError } from '@fluojs/validation';
 import { BadRequestException } from '../exceptions.js';
 import { toInputErrorDetail } from '../input-error-detail.js';
+import { getCompiledDtoBindingPlan } from './dto-binding-plan.js';
+
 /**
  * Represents the http dto validation adapter.
  */
@@ -18,9 +19,9 @@ export class HttpDtoValidationAdapter {
     }
     const source = value;
     const filtered = Object.create(Object.getPrototypeOf(value));
-    for (const binding of getDtoBindingSchema(target)) {
-      if (Object.hasOwn(source, binding.propertyKey)) {
-        filtered[binding.propertyKey] = source[binding.propertyKey];
+    for (const propertyKey of getCompiledDtoBindingPlan(target).propertyKeys) {
+      if (Object.hasOwn(source, propertyKey)) {
+        filtered[propertyKey] = source[propertyKey];
       }
     }
     return filtered;

package/dist/dispatch/dispatch-handler-policy.d.ts

@@ -1,3 +1,4 @@
+import type { RequestScopeContainer } from '@fluojs/di';
 import type { Binder, HandlerDescriptor, RequestContext } from '../types.js';
 /**
  * Invoke controller handler.
@@ -5,7 +6,8 @@ import type { Binder, HandlerDescriptor, RequestContext } from '../types.js';
  * @param handler The handler.
  * @param requestContext The request context.
  * @param binder The binder.
+ * @param controllerContainer Container used for resolving the controller instance before handler invocation.
  * @returns The invoke controller handler result.
  */
-export declare function invokeControllerHandler(handler: HandlerDescriptor, requestContext: RequestContext, binder?: Binder): Promise<unknown>;
+export declare function invokeControllerHandler(handler: HandlerDescriptor, requestContext: RequestContext, binder?: Binder, controllerContainer?: RequestScopeContainer): Promise<unknown>;
 //# sourceMappingURL=dispatch-handler-policy.d.ts.map

package/dist/dispatch/dispatch-handler-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-handler-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-handler-policy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA2B,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKtG;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,cAAc,EAAE,cAAc,EAC9B,MAAM,GAAE,MAAsB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAuBlB"}
+{"version":3,"file":"dispatch-handler-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-handler-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAIxD,OAAO,KAAK,EAA2B,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKtG;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,cAAc,EAAE,cAAc,EAC9B,MAAM,GAAE,MAAsB,EAC9B,mBAAmB,GAAE,qBAAgD,GACpE,OAAO,CAAC,OAAO,CAAC,CAuBlB"}

package/dist/dispatch/dispatch-handler-policy.js

@@ -10,10 +10,11 @@ const defaultValidator = new HttpDtoValidationAdapter();
  * @param handler The handler.
  * @param requestContext The request context.
  * @param binder The binder.
+ * @param controllerContainer Container used for resolving the controller instance before handler invocation.
  * @returns The invoke controller handler result.
  */
-export async function invokeControllerHandler(handler, requestContext, binder = defaultBinder) {
-  const controller = await requestContext.container.resolve(handler.controllerToken);
+export async function invokeControllerHandler(handler, requestContext, binder = defaultBinder, controllerContainer = requestContext.container) {
+  const controller = await controllerContainer.resolve(handler.controllerToken);
   const method = controller[handler.methodName];
   if (typeof method !== 'function') {
     throw new InvariantError(`Controller ${handler.controllerToken.name} does not expose handler method ${handler.methodName}.`);

package/dist/dispatch/dispatch-response-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatch-response-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAcrB;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,GACzD,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAC;AACzD,YAAY,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"dispatch-response-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EAEzB,KAAK,0BAA0B,EAChC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAgErB;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,GACzD,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAC;AACzD,YAAY,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/dispatch/dispatch-response-policy.js

@@ -11,6 +11,34 @@ function resolveDefaultSuccessStatus(handler, value) {
       return 200;
   }
 }
+function canUseSimpleJsonFastPath(response, value) {
+  return isSimpleJsonResponseBody(value) && !isResponseBodyForbidden(response.statusCode) && hasJsonCompatibleContentType(response);
+}
+function hasSimpleJsonResponseWriter(response) {
+  return typeof response.sendSimpleJson === 'function';
+}
+function isSimpleJsonResponseBody(value) {
+  if (Array.isArray(value)) {
+    return true;
+  }
+  return typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+function isResponseBodyForbidden(status) {
+  return status === 204 || status === 205 || status === 304;
+}
+function hasJsonCompatibleContentType(response) {
+  const contentType = readHeader(response.headers, 'content-type');
+  return contentType === undefined || isJsonContentType(contentType);
+}
+function readHeader(headers, name) {
+  const lowerName = name.toLowerCase();
+  const entry = Object.entries(headers).find(([headerName]) => headerName.toLowerCase() === lowerName);
+  const value = entry?.[1];
+  return typeof value === 'string' ? value : undefined;
+}
+function isJsonContentType(contentType) {
+  return contentType.toLowerCase().includes('application/json') || contentType.toLowerCase().endsWith('+json');
+}
 
 /**
  * Write success response.
@@ -50,6 +78,10 @@ export async function writeSuccessResponse(handler, request, response, value, co
   } else if (response.statusSet !== true) {
     response.setStatus(resolveDefaultSuccessStatus(handler, value));
   }
+  if (!formatter && hasSimpleJsonResponseWriter(response) && canUseSimpleJsonFastPath(response, value)) {
+    await response.sendSimpleJson(value);
+    return;
+  }
   const responseBody = formatter ? formatter.format(value) : value;
   await response.send(responseBody);
 }

package/dist/dispatch/dispatcher.d.ts

@@ -1,5 +1,5 @@
 import type { Container } from '@fluojs/di';
-import type { Binder, ContentNegotiationOptions, Dispatcher, DispatcherLogger, FrameworkRequest, FrameworkResponse, HandlerMapping, InterceptorLike, MiddlewareLike, RequestObserverLike } from '../types.js';
+import type { Binder, ContentNegotiationOptions, ConverterLike, Dispatcher, DispatcherLogger, FrameworkRequest, FrameworkResponse, HandlerMapping, InterceptorLike, MiddlewareLike, RequestObserverLike } from '../types.js';
 /**
  * Type definition for a global HTTP error handler function.
  */
@@ -22,6 +22,11 @@ export interface CreateDispatcherOptions {
     observers?: RequestObserverLike[];
     /** Optional global error handler. */
     onError?: ErrorHandler;
+    /** Request-scope optimization hints supplied by runtime bootstrap. */
+    requestScope?: {
+        /** Global DTO converters used by the default binder. */
+        converterDefinitions?: readonly ConverterLike[];
+    };
     logger?: DispatcherLogger;
     /** Root DI container for creating request scopes. */
     rootContainer: Container;

package/dist/dispatch/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAW5C,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAGjB,cAAc,EACd,eAAe,EAEf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpK;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sDAAsD;IACtD,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;CAC1B;AA8SD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAoC7E"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,YAAY,CAAC;AAanE,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAGjB,cAAc,EACd,eAAe,EAEf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpK;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sDAAsD;IACtD,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE;QACb,wDAAwD;QACxD,oBAAoB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;KACjD,CAAC;IACF,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;CAC1B;AA8bD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAuD7E"}

package/dist/dispatch/dispatcher.js

@@ -1,10 +1,12 @@
+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 { RequestAbortedError } from '../errors.js';
 import { runGuardChain } from '../guards.js';
 import { runInterceptorChain } from '../interceptors.js';
-import { runMiddlewareChain } from '../middleware/middleware.js';
+import { isMiddlewareRouteConfig, matchRoutePattern, runMiddlewareChain } from '../middleware/middleware.js';
 import { createRequestContext, runWithRequestContext } from '../context/request-context.js';
 import { SseResponse } from '../context/sse.js';
 
@@ -59,14 +61,98 @@ function readRequestId(request) {
   const normalized = value?.trim();
   return normalized ? normalized : undefined;
 }
-function createDispatchContext(request, response, rootContainer) {
-  return createRequestContext({
-    container: rootContainer.createRequestScope(),
+function createDispatchContext(request, response, container, promoteOnContainerAccess) {
+  const context = createRequestContext({
+    container,
     metadata: {},
     request,
     requestId: readRequestId(request),
     response
   });
+  if (!promoteOnContainerAccess) {
+    return context;
+  }
+  let activeContainer = container;
+  Object.defineProperty(context, 'container', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      activeContainer = promoteOnContainerAccess();
+      return activeContainer;
+    },
+    set(value) {
+      activeContainer = value;
+    }
+  });
+  return context;
+}
+function createRootDispatchScope(rootContainer) {
+  return {
+    container: rootContainer,
+    requestScoped: false
+  };
+}
+function createRequestDispatchScope(rootContainer) {
+  return {
+    container: rootContainer.createRequestScope(),
+    requestScoped: true
+  };
+}
+function activeMiddlewareMayRequireRequestScope(definitions, request) {
+  return definitions.some(definition => {
+    if (!isMiddlewareRouteConfig(definition)) {
+      return true;
+    }
+    return definition.routes.length === 0 || definition.routes.some(route => matchRoutePattern(route, request.path));
+  });
+}
+function requestDtoMayRequireRequestScope(handler, options) {
+  if (!handler.route.request) {
+    return false;
+  }
+  if ((options.requestScope?.converterDefinitions ?? []).length > 0) {
+    return true;
+  }
+  if (options.binder) {
+    return true;
+  }
+  const plan = getCompiledDtoBindingPlan(handler.route.request);
+  return plan.entries.some(entry => entry.converter !== undefined);
+}
+function handlerMethodMayUseRequestContext(handler) {
+  const method = handler.controllerToken.prototype[handler.methodName];
+  return typeof method === 'function' && method.length >= 2;
+}
+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 dispatchStartMayRequireRequestScope(request, observers, options) {
+  return observers.length > 0 || activeMiddlewareMayRequireRequestScope(options.appMiddleware ?? [], request);
+}
+function ensureRequestScope(context) {
+  if (context.dispatchScope.requestScoped) {
+    return;
+  }
+  context.dispatchScope = createRequestDispatchScope(context.options.rootContainer);
+  context.requestContext.container = context.dispatchScope.container;
 }
 function ensureRequestNotAborted(request) {
   if (request.signal?.aborted) {
@@ -111,7 +197,7 @@ function mergeInterceptors(globalInterceptors, routeInterceptors) {
   }
   return [...globalInterceptors, ...routeInterceptors];
 }
-async function dispatchMatchedHandler(handler, requestContext, observers, contentNegotiation, binder, globalInterceptors, logger) {
+async function dispatchMatchedHandler(handler, requestContext, controllerContainer, observers, contentNegotiation, binder, globalInterceptors, logger) {
   const routeGuards = handler.route.guards ?? [];
   if (routeGuards.length > 0) {
     const guardContext = {
@@ -124,10 +210,10 @@ async function dispatchMatchedHandler(handler, requestContext, observers, conten
     return;
   }
   const routeInterceptors = handler.route.interceptors ?? [];
-  const result = globalInterceptors.length === 0 && routeInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder) : await runInterceptorChain(mergeInterceptors(globalInterceptors, routeInterceptors), {
+  const result = globalInterceptors.length === 0 && routeInterceptors.length === 0 ? await invokeControllerHandler(handler, requestContext, binder, controllerContainer) : await runInterceptorChain(mergeInterceptors(globalInterceptors, routeInterceptors), {
     handler,
     requestContext
-  }, async () => invokeControllerHandler(handler, requestContext, binder));
+  }, async () => invokeControllerHandler(handler, requestContext, binder, controllerContainer));
   ensureRequestNotAborted(requestContext.request);
   if (!(result instanceof SseResponse) && !requestContext.response.committed) {
     await writeSuccessResponse(handler, requestContext.request, requestContext.response, result, contentNegotiation);
@@ -167,8 +253,11 @@ async function runDispatchPipeline(context) {
     if (context.response.committed) {
       return;
     }
-    const match = matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
+    const match = readFrameworkRequestNativeRouteHandoff(appMiddlewareContext.request) ?? matchHandlerOrThrow(context.options.handlerMapping, appMiddlewareContext.request);
     context.matchedHandler = match.descriptor;
+    if (handlerMayRequireRequestScope(match.descriptor, appMiddlewareContext.request, context.options)) {
+      ensureRequestScope(context);
+    }
     updateRequestParams(context.requestContext, match.params);
     await notifyHandlerMatched(context, match.descriptor);
     const moduleMiddlewareContext = {
@@ -177,7 +266,7 @@ async function runDispatchPipeline(context) {
       response: context.response
     };
     await runMiddlewareChain(match.descriptor.metadata.moduleMiddleware ?? [], moduleMiddlewareContext, async () => {
-      await dispatchMatchedHandler(match.descriptor, context.requestContext, context.observers, context.contentNegotiation, context.options.binder, context.options.interceptors ?? [], context.options.logger);
+      await dispatchMatchedHandler(match.descriptor, context.requestContext, context.dispatchScope.container, context.observers, context.contentNegotiation, context.options.binder, context.options.interceptors ?? [], context.options.logger);
     });
   });
 }
@@ -207,11 +296,23 @@ export function createDispatcher(options) {
       return options.handlerMapping.descriptors.map(descriptor => cloneHandlerDescriptor(descriptor));
     },
     async dispatch(request, response) {
-      const phaseContext = {
+      const dispatchRequest = createDispatchRequest(request);
+      const dispatchScope = dispatchStartMayRequireRequestScope(dispatchRequest, observers, options) ? createRequestDispatchScope(options.rootContainer) : 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,
         observers,
         options,
-        requestContext: createDispatchContext(createDispatchRequest(request), response, options.rootContainer),
+        requestContext,
         response
       };
       await runWithRequestContext(phaseContext.requestContext, async () => {
@@ -222,10 +323,13 @@ export function createDispatcher(options) {
           await handleDispatchError(phaseContext, error);
         } finally {
           await notifyRequestFinish(phaseContext);
-          try {
-            await phaseContext.requestContext.container.dispose();
-          } catch (error) {
-            logDispatchFailure(options.logger, 'Request-scoped container dispose threw an error.', error);
+          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);
+            }
           }
         }
       });

package/dist/dispatch/native-route-handoff.d.ts

@@ -0,0 +1,53 @@
+import type { FrameworkRequest, HandlerMatch } from '../types.js';
+/** Internal handoff payload that lets adapters skip duplicate route matching safely. */
+export type NativeRouteHandoff = HandlerMatch;
+/**
+ * Associates one adapter-selected route handoff with a raw platform request.
+ *
+ * Platform adapters call this before translating the native request into a
+ * `FrameworkRequest`, allowing the shared dispatcher to reuse the semantically
+ * safe native match without changing the public dispatcher surface.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ */
+export declare function bindRawRequestNativeRouteHandoff(rawRequest: object, handoff: NativeRouteHandoff): void;
+/**
+ * Reads and clears a native route handoff previously bound to a raw request.
+ *
+ * Request factories consume this once while constructing `FrameworkRequest`
+ * instances so the handoff remains request-local and does not leak across
+ * platform object reuse.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @returns The cloned handoff when one was registered for this request.
+ */
+export declare function consumeRawRequestNativeRouteHandoff(rawRequest: unknown): NativeRouteHandoff | undefined;
+/**
+ * Stores a pre-matched native route handoff on one framework request.
+ *
+ * @param request Framework request that should carry the adapter-native match.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ * @returns The same request instance for fluent adapter construction.
+ */
+export declare function attachFrameworkRequestNativeRouteHandoff(request: FrameworkRequest, handoff: NativeRouteHandoff): FrameworkRequest;
+/**
+ * Reads a pre-matched native route handoff from one framework request.
+ *
+ * @param request Framework request being dispatched.
+ * @returns The cloned handoff when the adapter supplied one.
+ */
+export declare function readFrameworkRequestNativeRouteHandoff(request: FrameworkRequest): NativeRouteHandoff | undefined;
+/**
+ * Reports whether a request path depends on fluo's normalization semantics.
+ *
+ * Duplicate slashes and trailing slashes are intentionally normalized by the
+ * shared matcher. Adapters use this helper to keep those requests on the
+ * generic dispatcher path when native routing may not preserve identical path
+ * selection semantics.
+ *
+ * @param path Raw framework request path.
+ * @returns `true` when normalization would change the incoming path.
+ */
+export declare function isRoutePathNormalizationSensitive(path: string): boolean;
+//# sourceMappingURL=native-route-handoff.d.ts.map

package/dist/dispatch/native-route-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-route-handoff.d.ts","sourceRoot":"","sources":["../../src/dispatch/native-route-handoff.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAsBlE,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEtG;AAED;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CAAC,UAAU,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAavG;AAED;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CACtD,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB,GAC1B,gBAAgB,CAYlB;AAED;;;;;GAKG;AACH,wBAAgB,sCAAsC,CACpD,OAAO,EAAE,gBAAgB,GACxB,kBAAkB,GAAG,SAAS,CAWhC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvE"}

package/dist/dispatch/native-route-handoff.js

@@ -0,0 +1,94 @@
+import { normalizeRoutePath } from '../route-path.js';
+const FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF = Symbol('fluo.http.nativeRouteHandoff');
+const RAW_REQUEST_NATIVE_ROUTE_HANDOFFS = new WeakMap();
+function cloneNativeRouteHandoff(handoff) {
+  return {
+    descriptor: handoff.descriptor,
+    params: {
+      ...handoff.params
+    }
+  };
+}
+
+/** Internal handoff payload that lets adapters skip duplicate route matching safely. */
+
+/**
+ * Associates one adapter-selected route handoff with a raw platform request.
+ *
+ * Platform adapters call this before translating the native request into a
+ * `FrameworkRequest`, allowing the shared dispatcher to reuse the semantically
+ * safe native match without changing the public dispatcher surface.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ */
+export function bindRawRequestNativeRouteHandoff(rawRequest, handoff) {
+  RAW_REQUEST_NATIVE_ROUTE_HANDOFFS.set(rawRequest, cloneNativeRouteHandoff(handoff));
+}
+
+/**
+ * Reads and clears a native route handoff previously bound to a raw request.
+ *
+ * Request factories consume this once while constructing `FrameworkRequest`
+ * instances so the handoff remains request-local and does not leak across
+ * platform object reuse.
+ *
+ * @param rawRequest Raw platform request object used as the lookup key.
+ * @returns The cloned handoff when one was registered for this request.
+ */
+export function consumeRawRequestNativeRouteHandoff(rawRequest) {
+  if (typeof rawRequest !== 'object' || rawRequest === null) {
+    return undefined;
+  }
+  const handoff = RAW_REQUEST_NATIVE_ROUTE_HANDOFFS.get(rawRequest);
+  if (!handoff) {
+    return undefined;
+  }
+  RAW_REQUEST_NATIVE_ROUTE_HANDOFFS.delete(rawRequest);
+  return cloneNativeRouteHandoff(handoff);
+}
+
+/**
+ * Stores a pre-matched native route handoff on one framework request.
+ *
+ * @param request Framework request that should carry the adapter-native match.
+ * @param handoff Pre-matched descriptor and params selected by the adapter.
+ * @returns The same request instance for fluent adapter construction.
+ */
+export function attachFrameworkRequestNativeRouteHandoff(request, handoff) {
+  Reflect.set(request, FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF, {
+    handoff: cloneNativeRouteHandoff(handoff),
+    method: request.method,
+    path: request.path
+  });
+  return request;
+}
+
+/**
+ * Reads a pre-matched native route handoff from one framework request.
+ *
+ * @param request Framework request being dispatched.
+ * @returns The cloned handoff when the adapter supplied one.
+ */
+export function readFrameworkRequestNativeRouteHandoff(request) {
+  const record = Reflect.get(request, FRAMEWORK_REQUEST_NATIVE_ROUTE_HANDOFF);
+  if (!record || record.method !== request.method || record.path !== request.path) {
+    return undefined;
+  }
+  return cloneNativeRouteHandoff(record.handoff);
+}
+
+/**
+ * Reports whether a request path depends on fluo's normalization semantics.
+ *
+ * Duplicate slashes and trailing slashes are intentionally normalized by the
+ * shared matcher. Adapters use this helper to keep those requests on the
+ * generic dispatcher path when native routing may not preserve identical path
+ * selection semantics.
+ *
+ * @param path Raw framework request path.
+ * @returns `true` when normalization would change the incoming path.
+ */
+export function isRoutePathNormalizationSensitive(path) {
+  return normalizeRoutePath(path) !== path;
+}

package/dist/internal.d.ts

@@ -1,3 +1,4 @@
 export { DefaultBinder } from './adapters/binding.js';
 export { resolveClientIdentity } from './client-identity.js';
+export { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive, readFrameworkRequestNativeRouteHandoff, type NativeRouteHandoff, } from './dispatch/native-route-handoff.js';
 //# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EACL,wCAAwC,EACxC,gCAAgC,EAChC,mCAAmC,EACnC,iCAAiC,EACjC,sCAAsC,EACtC,KAAK,kBAAkB,GACxB,MAAM,oCAAoC,CAAC"}

package/dist/internal.js

@@ -1,2 +1,3 @@
 export { DefaultBinder } from './adapters/binding.js';
-export { resolveClientIdentity } from './client-identity.js';
+export { resolveClientIdentity } from './client-identity.js';
+export { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive, readFrameworkRequestNativeRouteHandoff } from './dispatch/native-route-handoff.js';

package/package.json

@@ -10,7 +10,7 @@
     "controller",
     "rest"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -42,8 +42,8 @@
   ],
   "dependencies": {
     "@fluojs/core": "^1.0.0-beta.2",
-    "@fluojs/di": "^1.0.0-beta.4",
-    "@fluojs/validation": "^1.0.0-beta.1"
+    "@fluojs/validation": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.5"
   },
   "devDependencies": {
     "vitest": "^3.2.4"