@fluojs/http 1.1.2 → 3.0.0

package/dist/header-helpers.js

@@ -0,0 +1,185 @@
+function normalizeHeaderName(name) {
+  const normalized = name.trim().toLowerCase();
+  return normalized.length > 0 ? normalized : undefined;
+}
+function findCaseInsensitiveHeaderEntry(headers, headerName) {
+  const normalizedHeaderName = normalizeHeaderName(headerName);
+  if (!normalizedHeaderName) {
+    return undefined;
+  }
+  let firstMatch;
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== normalizedHeaderName) {
+      continue;
+    }
+    if (value !== undefined) {
+      return [name, value];
+    }
+    firstMatch ??= [name, value];
+  }
+  return firstMatch;
+}
+function parseHeaderTokens(values) {
+  const tokens = [];
+  for (const value of values) {
+    for (const token of value.split(',')) {
+      const normalized = token.trim();
+      if (normalized.length > 0) {
+        tokens.push(normalized);
+      }
+    }
+  }
+  return tokens;
+}
+function readJoinedNonEmptyHeaderValue(value) {
+  if (Array.isArray(value)) {
+    const normalizedValues = value.map(entry => entry.trim()).filter(entry => entry.length > 0);
+    return normalizedValues.length > 0 ? normalizedValues.join(',') : undefined;
+  }
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+}
+
+/**
+ * Reads one request header without flattening multi-value arrays.
+ *
+ * @param request Adapter-normalized request carrying the inbound headers map.
+ * @param name Header name to resolve case-insensitively.
+ * @returns The original scalar, array, or `undefined` stored on the request.
+ */
+export function getRequestHeader(request, name) {
+  return findCaseInsensitiveHeaderEntry(request.headers, name)?.[1];
+}
+
+/**
+ * Reads one response header without flattening multi-value arrays.
+ *
+ * @param response Adapter-normalized response carrying the outbound headers map.
+ * @param name Header name to resolve case-insensitively.
+ * @returns The original scalar, array, or `undefined` stored on the response.
+ */
+export function getResponseHeader(response, name) {
+  return findCaseInsensitiveHeaderEntry(response.headers, name)?.[1];
+}
+
+/**
+ * Checks whether one response header is present without mutating the response.
+ *
+ * @param response Adapter-normalized response carrying the outbound headers map.
+ * @param name Header name to resolve case-insensitively.
+ * @returns `true` when a matching response header has a value.
+ */
+export function hasResponseHeader(response, name) {
+  return getResponseHeader(response, name) !== undefined;
+}
+
+/**
+ * Creates a portable Content-Disposition value with ASCII and UTF-8 filename parameters.
+ *
+ * @param disposition Whether the response is an `attachment` or rendered `inline`.
+ * @param filename Original filename to encode for a response header.
+ * @returns A Content-Disposition field value with escaped ASCII and RFC 8187 UTF-8 parameters.
+ * @throws {TypeError} When the disposition is unsupported or the filename contains CR or LF.
+ */
+export function buildContentDisposition(disposition, filename) {
+  if (disposition !== 'attachment' && disposition !== 'inline') {
+    throw new TypeError('Content-Disposition disposition must be attachment or inline.');
+  }
+  if (filename.includes('\r') || filename.includes('\n')) {
+    throw new TypeError('Content-Disposition filenames cannot contain CR or LF characters.');
+  }
+  const asciiFilename = filename.replace(/[^\x20-\x7E]/gu, '?').replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+  const utf8Filename = Array.from(new TextEncoder().encode(filename), byte => {
+    const isAlphaNumeric = byte >= 0x30 && byte <= 0x39 || byte >= 0x41 && byte <= 0x5a || byte >= 0x61 && byte <= 0x7a;
+    const isRfc8187Punctuation = byte === 0x21 || byte === 0x23 || byte === 0x24 || byte === 0x26 || byte === 0x2b || byte === 0x2d || byte === 0x2e || byte === 0x5e || byte === 0x5f || byte === 0x60 || byte === 0x7c || byte === 0x7e;
+    return isAlphaNumeric || isRfc8187Punctuation ? String.fromCharCode(byte) : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+  }).join('');
+  return `${disposition}; filename="${asciiFilename}"; filename*=UTF-8''${utf8Filename}`;
+}
+
+/**
+ * Reads the first non-empty request header value across duplicate case variants.
+ *
+ * @param request Adapter-normalized request carrying the inbound headers map.
+ * @param name Header name to resolve case-insensitively.
+ * @returns The first trimmed scalar or joined array value that is not blank.
+ */
+export function readFirstNonEmptyRequestHeaderValue(request, name) {
+  const normalizedHeaderName = normalizeHeaderName(name);
+  if (!normalizedHeaderName) {
+    return undefined;
+  }
+  for (const [headerName, value] of Object.entries(request.headers)) {
+    if (headerName.toLowerCase() !== normalizedHeaderName) {
+      continue;
+    }
+    const normalizedValue = readJoinedNonEmptyHeaderValue(value);
+    if (normalizedValue !== undefined) {
+      return normalizedValue;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Reads and joins every non-empty request header field value in wire order.
+ *
+ * @param request Adapter-normalized request carrying the inbound headers map.
+ * @param name Header name to resolve case-insensitively.
+ * @returns Comma-delimited values from every matching field, or `undefined` when all are blank.
+ */
+export function readJoinedNonEmptyRequestHeaderValues(request, name) {
+  const normalizedHeaderName = normalizeHeaderName(name);
+  if (!normalizedHeaderName) {
+    return undefined;
+  }
+  const values = [];
+  for (const [headerName, value] of Object.entries(request.headers)) {
+    if (headerName.toLowerCase() !== normalizedHeaderName) {
+      continue;
+    }
+    const normalizedValue = readJoinedNonEmptyHeaderValue(value);
+    if (normalizedValue !== undefined) {
+      values.push(normalizedValue);
+    }
+  }
+  return values.length > 0 ? values.join(',') : undefined;
+}
+
+/**
+ * Appends one or more fields to the response `Vary` header with case-insensitive deduplication.
+ *
+ * @param response Mutable framework response facade that owns the header map.
+ * @param fields Header field names or comma-delimited field lists to append.
+ * @returns Nothing. The helper updates the response header map in place when needed.
+ */
+export function appendVaryHeader(response, ...fields) {
+  const existingEntries = Object.entries(response.headers).filter(([name]) => name.toLowerCase() === 'vary');
+  const existingTokens = parseHeaderTokens(existingEntries.flatMap(([, value]) => Array.isArray(value) ? value : [value]));
+  const appendedTokens = parseHeaderTokens(fields);
+  const mergedTokens = [...existingTokens, ...appendedTokens];
+  if (mergedTokens.length === 0) {
+    return;
+  }
+  const canonicalHeaderName = existingEntries[0]?.[0] ?? 'Vary';
+  for (const [name] of existingEntries.slice(1)) {
+    delete response.headers[name];
+  }
+  if (mergedTokens.some(token => token === '*')) {
+    response.setHeader(canonicalHeaderName, '*');
+    return;
+  }
+  const dedupedTokens = [];
+  const seen = new Set();
+  for (const token of mergedTokens) {
+    const normalized = token.toLowerCase();
+    if (seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    dedupedTokens.push(token);
+  }
+  if (dedupedTokens.length > 0) {
+    response.setHeader(canonicalHeaderName, dedupedTokens.join(', '));
+  }
+}

package/dist/index.d.ts

@@ -1,17 +1,2 @@
-export * from './adapter.js';
-export * from './middleware/correlation.js';
-export * from './middleware/cors.js';
-export { All, Controller, Convert, Delete, FromBody, FromCookie, FromHeader, FromPath, FromQuery, Get, Head, Header, HttpCode, Optional, Options, Patch, Post, Produces, Put, Redirect, RequestDto, Sse, UseGuards, UseInterceptors, Version, } from './decorators.js';
-export * from './dispatch/dispatcher.js';
-export type { FastPathEligibility, FastPathStats } from './dispatch/fast-path/index.js';
-export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats, getDispatcherFastPathStats, } from './dispatch/dispatcher.js';
-export * from './errors.js';
-export * from './exceptions.js';
-export * from './mapping.js';
-export { forRoutes, isMiddlewareRouteConfig, matchRoutePattern, normalizeRoutePattern, } from './middleware/middleware.js';
-export * from './middleware/rate-limit.js';
-export * from './context/request-context.js';
-export * from './middleware/security-headers.js';
-export * from './context/sse.js';
-export * from './types.js';
+export * from './index.portable.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,GAAG,EACH,UAAU,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,UAAU,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,QAAQ,EACR,UAAU,EACV,GAAG,EACH,SAAS,EACT,eAAe,EACf,OAAO,GACR,MAAM,iBAAiB,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxF,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC;AACjD,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,15 +1,4 @@
-export * from './adapter.js';
-export * from './middleware/correlation.js';
-export * from './middleware/cors.js';
-export { All, Controller, Convert, Delete, FromBody, FromCookie, FromHeader, FromPath, FromQuery, Get, Head, Header, HttpCode, Optional, Options, Patch, Post, Produces, Put, Redirect, RequestDto, Sse, UseGuards, UseInterceptors, Version } from './decorators.js';
-export * from './dispatch/dispatcher.js';
-export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats, getDispatcherFastPathStats } from './dispatch/dispatcher.js';
-export * from './errors.js';
-export * from './exceptions.js';
-export * from './mapping.js';
-export { forRoutes, isMiddlewareRouteConfig, matchRoutePattern, normalizeRoutePattern } from './middleware/middleware.js';
-export * from './middleware/rate-limit.js';
-export * from './context/request-context.js';
-export * from './middleware/security-headers.js';
-export * from './context/sse.js';
-export * from './types.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { registerImmediateAsyncLocalStorageConstructor } from './context/request-context-node-store.js';
+registerImmediateAsyncLocalStorageConstructor(AsyncLocalStorage);
+export * from './index.portable.js';

package/dist/index.portable.d.ts

@@ -0,0 +1,25 @@
+export * from './adapter.js';
+export * from './access-log-observer.js';
+export { createByteRangeResponse, } from './byte-range-response.js';
+export type { ByteRangeResponseOptions, ByteRangeResponseSource, } from './byte-range-response.js';
+export { createStaticAssetsMiddleware, } from './static-assets.js';
+export type { StaticAsset, StaticAssetAcceptedEncoding, StaticAssetContentEncoding, StaticAssetNotAcceptable, StaticAssetResolveContext, StaticAssetResolution, StaticAssetSource, StaticAssetsMiddleware, StaticAssetsMiddlewareOptions, } from './static-assets.js';
+export * from './context/request-context.js';
+export * from './context/sse.js';
+export * from './connection.js';
+export * from './cookie-helpers.js';
+export { All, Controller, Convert, Delete, FromBody, FromCookie, FromFiles, FromHeader, FromPath, FromQuery, Get, Head, Header, HttpCode, Optional, Options, Patch, Post, Produces, Put, Query, Redirect, RequestDto, Route, Sse, UseGuards, UseInterceptors, Version, } from './decorators.js';
+export * from './dispatch/dispatcher.js';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats, getDispatcherFastPathStats, } from './dispatch/dispatcher.js';
+export type { FastPathEligibility, FastPathStats } from './dispatch/fast-path/index.js';
+export * from './errors.js';
+export * from './exceptions.js';
+export { appendVaryHeader, buildContentDisposition, getRequestHeader, getResponseHeader, hasResponseHeader, } from './header-helpers.js';
+export * from './mapping.js';
+export * from './middleware/correlation.js';
+export * from './middleware/cors.js';
+export { forRoutes, isMiddlewareRouteConfig, matchRoutePattern, normalizeRoutePattern, } from './middleware/middleware.js';
+export * from './middleware/rate-limit.js';
+export * from './middleware/security-headers.js';
+export * from './types.js';
+//# sourceMappingURL=index.portable.d.ts.map

package/dist/index.portable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.portable.d.ts","sourceRoot":"","sources":["../src/index.portable.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,WAAW,EACX,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,GAAG,EACH,UAAU,EACV,OAAO,EACP,MAAM,EACN,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACR,SAAS,EACT,GAAG,EACH,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,UAAU,EACV,KAAK,EACL,GAAG,EACH,SAAS,EACT,eAAe,EACf,OAAO,GACR,MAAM,iBAAiB,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACxF,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACL,SAAS,EACT,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,YAAY,CAAC"}

package/dist/index.portable.js

@@ -0,0 +1,21 @@
+export * from './adapter.js';
+export * from './access-log-observer.js';
+export { createByteRangeResponse } from './byte-range-response.js';
+export { createStaticAssetsMiddleware } from './static-assets.js';
+export * from './context/request-context.js';
+export * from './context/sse.js';
+export * from './connection.js';
+export * from './cookie-helpers.js';
+export { All, Controller, Convert, Delete, FromBody, FromCookie, FromFiles, FromHeader, FromPath, FromQuery, Get, Head, Header, HttpCode, Optional, Options, Patch, Post, Produces, Put, Query, Redirect, RequestDto, Route, Sse, UseGuards, UseInterceptors, Version } from './decorators.js';
+export * from './dispatch/dispatcher.js';
+export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL, formatFastPathStats, getDispatcherFastPathStats } from './dispatch/dispatcher.js';
+export * from './errors.js';
+export * from './exceptions.js';
+export { appendVaryHeader, buildContentDisposition, getRequestHeader, getResponseHeader, hasResponseHeader } from './header-helpers.js';
+export * from './mapping.js';
+export * from './middleware/correlation.js';
+export * from './middleware/cors.js';
+export { forRoutes, isMiddlewareRouteConfig, matchRoutePattern, normalizeRoutePattern } from './middleware/middleware.js';
+export * from './middleware/rate-limit.js';
+export * from './middleware/security-headers.js';
+export * from './types.js';

package/dist/internal.d.ts

@@ -1,6 +1,8 @@
 export { createFetchStyleHttpAdapterRealtimeCapability, type HttpApplicationAdapter, } from './adapter.js';
 export { DefaultBinder } from './adapters/binding.js';
 export { resolveClientIdentity } from './client-identity.js';
+export { getCompiledRouteIdentity } from './compiled-route-identity.js';
+export { FRAMEWORK_RESPONSE_VALUE_FINALIZER, FRAMEWORK_RESPONSE_WRITER, registerFrameworkResponseValueFinalizer, registerFrameworkResponseWriter, type FrameworkResponseValueFinalizer, type FrameworkResponseValueFinalizerContext, type FrameworkResponseWriter, type FrameworkResponseWriterContext, } from './dispatch/response-integration.js';
+export { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive, type NativeRouteHandoff, readFrameworkRequestNativeRouteHandoff, } from './dispatch/native-route-handoff.js';
 export type { Dispatcher } from './types.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,EACL,6CAA6C,EAC7C,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,wCAAwC,EACxC,gCAAgC,EAChC,mCAAmC,EACnC,iCAAiC,EACjC,sCAAsC,EACtC,KAAK,kBAAkB,GACxB,MAAM,oCAAoC,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6CAA6C,EAC7C,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EACL,kCAAkC,EAClC,yBAAyB,EACzB,uCAAuC,EACvC,+BAA+B,EAC/B,KAAK,+BAA+B,EACpC,KAAK,sCAAsC,EAC3C,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,GACpC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,wCAAwC,EACxC,gCAAgC,EAChC,mCAAmC,EACnC,iCAAiC,EACjC,KAAK,kBAAkB,EACvB,sCAAsC,GACvC,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/internal.js

@@ -1,4 +1,6 @@
 export { createFetchStyleHttpAdapterRealtimeCapability } from './adapter.js';
 export { DefaultBinder } from './adapters/binding.js';
 export { resolveClientIdentity } from './client-identity.js';
+export { getCompiledRouteIdentity } from './compiled-route-identity.js';
+export { FRAMEWORK_RESPONSE_VALUE_FINALIZER, FRAMEWORK_RESPONSE_WRITER, registerFrameworkResponseValueFinalizer, registerFrameworkResponseWriter } from './dispatch/response-integration.js';
 export { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive, readFrameworkRequestNativeRouteHandoff } from './dispatch/native-route-handoff.js';

package/dist/mapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAIV,cAAc,EAEd,aAAa,EAIb,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAOpB,UAAU,2BAA2B;IACnC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AA6VD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,cAAc,CAuEpH"}
+{"version":3,"file":"mapping.d.ts","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAIV,cAAc,EAId,aAAa,EAOb,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAQpB,UAAU,2BAA2B;IACnC,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAycD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,cAAc,CA8EpH"}

package/dist/mapping.js

@@ -1,6 +1,8 @@
 import { getControllerMetadata, getRouteMetadata } from '@fluojs/core/internal';
+import { attachCompiledRouteIdentity } from './compiled-route-identity.js';
 import { getRouteProducesMetadata } from './decorators.js';
 import { RouteConflictError } from './errors.js';
+import { isMiddlewareRouteConfig } from './middleware/middleware.js';
 import { extractRoutePathParams, normalizeRoutePath, parseRoutePath } from './route-path.js';
 import { VersioningType } from './types.js';
 function joinPaths(basePath, routePath) {
@@ -19,16 +21,27 @@ function applyVersionPrefix(path, version) {
 function normalizeVersionValue(version) {
   return version.trim().replace(/^v/i, '');
 }
-function readHeaderValue(request, headerName) {
-  const normalizedHeaderName = headerName.trim().toLowerCase();
+function normalizeHeaderName(headerName) {
+  const normalized = headerName.trim().toLowerCase();
+  return normalized.length > 0 ? normalized : undefined;
+}
+function getMatchingRequestHeaderValues(request, headerName) {
+  const normalizedHeaderName = normalizeHeaderName(headerName);
   if (!normalizedHeaderName) {
-    return undefined;
+    return [];
   }
-  for (const [key, raw] of Object.entries(request.headers)) {
-    if (key.toLowerCase() !== normalizedHeaderName) {
-      continue;
+  const matches = [];
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (name.toLowerCase() === normalizedHeaderName) {
+      matches.push(value);
     }
-    const values = Array.isArray(raw) ? raw : [raw];
+  }
+  return matches;
+}
+function readHeaderValue(request, headerName) {
+  const matches = getMatchingRequestHeaderValues(request, headerName);
+  for (const match of matches) {
+    const values = Array.isArray(match) ? match : [match];
     for (const value of values) {
       const normalized = value?.trim();
       if (normalized) {
@@ -38,11 +51,25 @@ function readHeaderValue(request, headerName) {
   }
   return undefined;
 }
+function readCombinedHeaderValue(request, headerName) {
+  const matches = getMatchingRequestHeaderValues(request, headerName);
+  const values = [];
+  for (const match of matches) {
+    const entries = Array.isArray(match) ? match : [match];
+    for (const entry of entries) {
+      const normalized = entry?.trim();
+      if (normalized) {
+        values.push(normalized);
+      }
+    }
+  }
+  return values.length > 0 ? values.join(',') : undefined;
+}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 function extractVersionFromMediaType(request, key) {
-  const accept = readHeaderValue(request, 'accept');
+  const accept = readCombinedHeaderValue(request, 'accept');
   if (!accept) {
     return undefined;
   }
@@ -209,12 +236,12 @@ function matchParameterizedRoute(candidate, incomingSegments) {
   }
   return params;
 }
-function createHandlerDescriptors(source, versioning) {
+function createHandlerDescriptors(source, versioning, sourceIndex) {
   const controllerMetadata = getControllerMetadata(source.controllerToken) ?? {
     basePath: ''
   };
   const descriptors = [];
-  for (const propertyKey of getControllerMethodNames(source.controllerToken)) {
+  for (const [methodIndex, propertyKey] of getControllerMethodNames(source.controllerToken).entries()) {
     const routeMetadata = getRouteMetadata(source.controllerToken.prototype, propertyKey);
     if (!routeMetadata) {
       continue;
@@ -223,7 +250,7 @@ function createHandlerDescriptors(source, versioning) {
     const routePath = joinPaths(controllerMetadata.basePath, routeMetadata.path);
     const effectivePath = versioning.type === VersioningType.URI ? applyVersionPrefix(routePath, effectiveVersion) : routePath;
     const produces = getRouteProducesMetadata(source.controllerToken, propertyKey);
-    descriptors.push({
+    descriptors.push(attachCompiledRouteIdentity({
       controllerToken: source.controllerToken,
       metadata: {
         controllerPath: controllerMetadata.basePath,
@@ -244,12 +271,12 @@ function createHandlerDescriptors(source, versioning) {
         path: effectivePath,
         version: effectiveVersion
       }
-    });
+    }, `v1:${sourceIndex}:${methodIndex}`));
   }
   return descriptors;
 }
 function buildDescriptorList(sources, versioning) {
-  const descriptors = sources.flatMap(source => createHandlerDescriptors(source, versioning));
+  const descriptors = sources.flatMap((source, sourceIndex) => createHandlerDescriptors(source, versioning, sourceIndex));
   const seen = new Set();
   for (const descriptor of descriptors) {
     const routeVersion = descriptor.route.version === undefined ? '<none>' : normalizeVersionValue(descriptor.route.version);
@@ -261,6 +288,59 @@ function buildDescriptorList(sources, versioning) {
   }
   return descriptors;
 }
+function freezeDescriptorSnapshot(descriptors) {
+  const snapshot = descriptors.map(descriptor => {
+    const {
+      metadata,
+      route
+    } = descriptor;
+    const frozenMetadata = Object.freeze({
+      ...metadata,
+      moduleMiddleware: freezeModuleMiddlewareSnapshot(metadata.moduleMiddleware),
+      pathParams: Object.freeze([...metadata.pathParams])
+    });
+    const frozenRoute = Object.freeze({
+      ...route,
+      ...(route.guards ? {
+        guards: Object.freeze([...route.guards])
+      } : {}),
+      ...(route.headers ? {
+        headers: Object.freeze(route.headers.map(header => Object.freeze({
+          ...header
+        })))
+      } : {}),
+      ...(route.interceptors ? {
+        interceptors: Object.freeze([...route.interceptors])
+      } : {}),
+      ...(route.produces ? {
+        produces: Object.freeze([...route.produces])
+      } : {}),
+      ...(route.redirect ? {
+        redirect: Object.freeze({
+          ...route.redirect
+        })
+      } : {})
+    });
+    return Object.freeze({
+      ...descriptor,
+      metadata: frozenMetadata,
+      route: frozenRoute
+    });
+  });
+  return Object.freeze(snapshot);
+}
+function freezeModuleMiddlewareSnapshot(definitions) {
+  const snapshot = definitions.map(definition => {
+    if (!isMiddlewareRouteConfig(definition)) {
+      return definition;
+    }
+    return Object.freeze({
+      middleware: definition.middleware,
+      routes: Object.freeze([...definition.routes])
+    });
+  });
+  return Object.freeze(snapshot);
+}
 
 /**
  * Create handler mapping.
@@ -271,9 +351,9 @@ function buildDescriptorList(sources, versioning) {
  */
 export function createHandlerMapping(sources, options) {
   const versioning = resolveVersioning(options);
-  const descriptors = buildDescriptorList(sources, versioning);
+  const descriptors = freezeDescriptorSnapshot(buildDescriptorList(sources, versioning));
   const descriptorIndex = buildDescriptorIndex(descriptors);
-  return {
+  const mapping = {
     descriptors,
     match(request) {
       const method = request.method.toUpperCase();
@@ -323,4 +403,9 @@ export function createHandlerMapping(sources, options) {
       return undefined;
     }
   };
+  Object.defineProperty(mapping, 'descriptors', {
+    configurable: false,
+    writable: false
+  });
+  return mapping;
 }

package/dist/middleware/correlation.d.ts

@@ -1,4 +1,12 @@
-import type { Middleware } from '../types.js';
+import type { Middleware, MiddlewareLike, RequestContext } from '../types.js';
+/**
+ * Initializes correlation-aware request contexts before lifecycle observers run.
+ *
+ * @internal
+ * @param middleware Global middleware definitions registered with the dispatcher.
+ * @param context Request context to initialize.
+ */
+export declare function initializeCorrelationMiddlewareRequestContext(middleware: readonly MiddlewareLike[], context: RequestContext): void;
 /**
  * Create correlation middleware.
  *

package/dist/middleware/correlation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../../src/middleware/correlation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsB9C;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,UAAU,CAYxD"}
+{"version":3,"file":"correlation.d.ts","sourceRoot":"","sources":["../../src/middleware/correlation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAuBhG;;;;;;GAMG;AACH,wBAAgB,6CAA6C,CAC3D,UAAU,EAAE,SAAS,cAAc,EAAE,EACrC,OAAO,EAAE,cAAc,GACtB,IAAI,CAUN;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,UAAU,CAWxD"}

package/dist/middleware/correlation.js

@@ -1,16 +1,28 @@
+import { resolveRequestId } from '../context/request-id.js';
 const REQUEST_ID_HEADER = 'x-request-id';
-const CORRELATION_ID_HEADER = 'x-correlation-id';
-function resolveInboundRequestId(headers) {
-  const requestId = headers[REQUEST_ID_HEADER] ?? headers[CORRELATION_ID_HEADER];
-  const value = Array.isArray(requestId) ? requestId[0] : requestId;
-  return value ?? createRequestId();
+const CORRELATION_REQUEST_CONTEXT_INITIALIZER = Symbol('fluo.http.correlationRequestContextInitializer');
+function initializeCorrelationRequestContext(context, request = context.request) {
+  const requestId = context.requestId ?? resolveRequestId(request);
+  if (requestId === undefined) {
+    throw new Error('Correlation request ID generation unexpectedly returned undefined.');
+  }
+  context.requestId = requestId;
+  return requestId;
 }
-function createRequestId() {
-  const randomUUID = globalThis.crypto?.randomUUID;
-  if (randomUUID) {
-    return randomUUID.call(globalThis.crypto);
+
+/**
+ * Initializes correlation-aware request contexts before lifecycle observers run.
+ *
+ * @internal
+ * @param middleware Global middleware definitions registered with the dispatcher.
+ * @param context Request context to initialize.
+ */
+export function initializeCorrelationMiddlewareRequestContext(middleware, context) {
+  for (const definition of middleware) {
+    if (typeof definition === 'object' && definition !== null && CORRELATION_REQUEST_CONTEXT_INITIALIZER in definition) {
+      definition[CORRELATION_REQUEST_CONTEXT_INITIALIZER](context);
+    }
   }
-  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
 }
 
 /**
@@ -20,11 +32,10 @@ function createRequestId() {
  */
 export function createCorrelationMiddleware() {
   return {
+    [CORRELATION_REQUEST_CONTEXT_INITIALIZER]: initializeCorrelationRequestContext,
     async handle(context, next) {
-      if (!context.requestContext.requestId) {
-        context.requestContext.requestId = resolveInboundRequestId(context.request.headers);
-      }
-      context.response.setHeader(REQUEST_ID_HEADER, context.requestContext.requestId);
+      const requestId = initializeCorrelationRequestContext(context.requestContext, context.request);
+      context.response.setHeader(REQUEST_ID_HEADER, requestId);
       await next();
     }
   };

package/dist/middleware/cors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACvF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CA0D1E"}
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACvF,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA4BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CA0D1E"}

package/dist/middleware/cors.js

@@ -1,3 +1,5 @@
+import { appendVaryHeader, getRequestHeader } from '../header-helpers.js';
+
 /**
  * Describes the cors options contract.
  */
@@ -35,7 +37,7 @@ export function createCorsMiddleware(options = {}) {
   const allowMethods = options.allowMethods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
   return {
     async handle(context, next) {
-      const requestOriginHeader = context.request.headers.origin;
+      const requestOriginHeader = getRequestHeader(context.request, 'origin');
       const requestOrigin = Array.isArray(requestOriginHeader) ? requestOriginHeader[0] : requestOriginHeader;
       const origin = resolveOrigin(options, requestOrigin);
       if (origin) {
@@ -50,14 +52,11 @@ export function createCorsMiddleware(options = {}) {
       setHeaderIfValue(context.response, 'Access-Control-Allow-Credentials', options.allowCredentials ? 'true' : undefined);
       setHeaderIfValue(context.response, 'Access-Control-Max-Age', options.maxAge !== undefined ? String(options.maxAge) : undefined);
       if (origin && origin !== '*') {
-        const existingVary = context.response.headers['vary'] ?? context.response.headers['Vary'];
-        const varyValues = existingVary ? Array.isArray(existingVary) ? existingVary : String(existingVary).split(',').map(v => v.trim()) : [];
-        if (!varyValues.some(v => v.toLowerCase() === 'origin')) {
-          varyValues.push('Origin');
-        }
-        context.response.setHeader('Vary', varyValues.join(', '));
+        appendVaryHeader(context.response, 'Origin');
       }
-      if (context.request.method === 'OPTIONS') {
+      const requestedPreflightMethod = getRequestHeader(context.request, 'access-control-request-method');
+      const hasPreflightMethod = Array.isArray(requestedPreflightMethod) ? requestedPreflightMethod.length > 0 : requestedPreflightMethod !== undefined;
+      if (context.request.method === 'OPTIONS' && hasPreflightMethod) {
         context.response.setStatus(204);
         await context.response.send(undefined);
         return;

package/dist/middleware/middleware.d.ts

@@ -1,12 +1,12 @@
 import type { Constructor } from '@fluojs/core';
-import type { Middleware, MiddlewareContext, MiddlewareLike, MiddlewareRouteConfig, Next } from '../types.js';
+import type { Middleware, MiddlewareContext, MiddlewareLike, MiddlewareRouteConfig, MiddlewareRouteSnapshot, MiddlewareSnapshotLike, Next } from '../types.js';
 /**
  * Is middleware route config.
  *
  * @param value The value.
  * @returns The is middleware route config result.
  */
-export declare function isMiddlewareRouteConfig(value: MiddlewareLike): value is MiddlewareRouteConfig;
+export declare function isMiddlewareRouteConfig(value: MiddlewareLike | MiddlewareSnapshotLike): value is MiddlewareRouteConfig | MiddlewareRouteSnapshot;
 /**
  * Normalize route pattern.
  *
@@ -38,5 +38,5 @@ export declare function forRoutes<T extends Constructor<Middleware>>(middlewareC
  * @param terminal The terminal.
  * @returns The run middleware chain result.
  */
-export declare function runMiddlewareChain(definitions: MiddlewareLike[], context: MiddlewareContext, terminal: Next): Promise<void>;
+export declare function runMiddlewareChain(definitions: readonly (MiddlewareLike | MiddlewareSnapshotLike)[], context: MiddlewareContext, terminal: Next): Promise<void>;
 //# sourceMappingURL=middleware.d.ts.map