@fluojs/http 2.0.1 → 3.0.0

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

@@ -31,31 +31,37 @@ export interface FastPathEligibility {
     /** Whether adapter-level plugin behavior may affect execution. */
     readonly hasAdapterPluginInfluence: boolean;
     /** Resolved execution path, either 'fast' or 'full'. */
-    executionPath: 'fast' | 'full';
+    readonly executionPath: 'fast' | 'full';
     /** Explanation for full-path fallback when fast path is not selected. */
-    fallbackReason?: string;
+    readonly fallbackReason?: string;
 }
 /**
  * Statistics collected about fast path decisions for observability.
  */
 export interface FastPathStats {
     /** Total number of routes analyzed. */
-    totalRoutes: number;
+    readonly totalRoutes: number;
     /** Number of routes eligible for fast path. */
-    fastPathRoutes: number;
+    readonly fastPathRoutes: number;
     /** Number of routes using full path. */
-    fullPathRoutes: number;
+    readonly fullPathRoutes: number;
     /** Per-route eligibility details. */
-    routes: ReadonlyArray<Readonly<FastPathEligibility>>;
+    readonly routes: readonly Readonly<FastPathEligibility>[];
 }
 /**
- * Symbol used to attach fast path eligibility metadata to handler descriptors.
- * @internal
+ * Public symbol key for fast path eligibility metadata attached to dispatcher route snapshots.
+ *
+ * @remarks
+ * Adapter and diagnostics integrations can use this key to inspect the route's
+ * frozen {@link FastPathEligibility} metadata without accessing dispatcher-owned state.
  */
 export declare const FAST_PATH_ELIGIBILITY_SYMBOL: unique symbol;
 /**
- * Symbol used to attach fast path execution stats to dispatcher.
- * @internal
+ * Public symbol key for fast path execution statistics attached to a dispatcher.
+ *
+ * @remarks
+ * Adapter and diagnostics integrations can use this key to read the same
+ * {@link FastPathStats} value exposed by `getDispatcherFastPathStats(...)`.
  */
 export declare const FAST_PATH_STATS_SYMBOL: unique symbol;
 //# sourceMappingURL=eligibility.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,8DAA8D;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IAErC,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IAEtC,iDAAiD;IACjD,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAEvC,kEAAkE;IAClE,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAE5C,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/B,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IAEpB,+CAA+C;IAC/C,cAAc,EAAE,MAAM,CAAC;IAEvB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IAEvB,qCAAqC;IACrC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC,CAAC;CACtD;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,eAAgC,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,sBAAsB,eAA0B,CAAC"}
+{"version":3,"file":"eligibility.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/eligibility.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAEhC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,8DAA8D;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IAErC,yDAAyD;IACzD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IAEtC,iDAAiD;IACjD,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;IAEvC,kEAAkE;IAClE,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAE5C,wDAAwD;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAExC,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,wCAAwC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;CAC3D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,eAAgC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,eAA0B,CAAC"}

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

@@ -11,13 +11,19 @@
  */
 
 /**
- * Symbol used to attach fast path eligibility metadata to handler descriptors.
- * @internal
+ * Public symbol key for fast path eligibility metadata attached to dispatcher route snapshots.
+ *
+ * @remarks
+ * Adapter and diagnostics integrations can use this key to inspect the route's
+ * frozen {@link FastPathEligibility} metadata without accessing dispatcher-owned state.
  */
 export const FAST_PATH_ELIGIBILITY_SYMBOL = Symbol('fastPathEligibility');
 
 /**
- * Symbol used to attach fast path execution stats to dispatcher.
- * @internal
+ * Public symbol key for fast path execution statistics attached to a dispatcher.
+ *
+ * @remarks
+ * Adapter and diagnostics integrations can use this key to read the same
+ * {@link FastPathStats} value exposed by `getDispatcherFastPathStats(...)`.
  */
 export const FAST_PATH_STATS_SYMBOL = Symbol('fastPathStats');

package/dist/dispatch/fast-path/fast-path-executor.d.ts

@@ -1,6 +1,6 @@
 import type { RequestScopeContainer } from '@fluojs/di';
-import { type ResolvedContentNegotiation } from '../dispatch-response-policy.js';
 import type { Binder, FrameworkRequest, FrameworkResponse, HandlerDescriptor, RequestContext } from '../../types.js';
+import { type ResolvedContentNegotiation } from '../dispatch-response-policy.js';
 import type { FastPathExecutionResult } from './eligibility-checker.js';
 interface ExecuteFastPathOptions {
     binder?: Binder;

package/dist/dispatch/fast-path/fast-path-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fast-path-executor.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/fast-path-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOxD,OAAO,EAAE,KAAK,0BAA0B,EAAwB,MAAM,gCAAgC,CAAC;AACvG,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AASxE,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IAChD,mBAAmB,EAAE,qBAAqB,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,KAAK,OAAO,CAAC;IACnF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAoDlC;AASD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,EAC3D,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAWT"}
+{"version":3,"file":"fast-path-executor.d.ts","sourceRoot":"","sources":["../../../src/dispatch/fast-path/fast-path-executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOxD,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AASxE,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,0BAA0B,CAAC;IAChD,mBAAmB,EAAE,qBAAqB,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,KAAK,OAAO,CAAC;IACnF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAyDlC;AASD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE;IAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAAS,EAC3D,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAWT"}

package/dist/dispatch/fast-path/fast-path-executor.js

@@ -1,9 +1,10 @@
 import { DefaultBinder } from '../../adapters/binding.js';
 import { getCompiledDtoBindingPlan } from '../../adapters/dto-binding-plan.js';
 import { HttpDtoValidationAdapter } from '../../adapters/dto-validation-adapter.js';
-import { SseResponse } from '../../context/sse.js';
+import { SseResponse, waitForSseResponseCompletion } from '../../context/sse.js';
 import { RequestAbortedError } from '../../errors.js';
 import { writeSuccessResponse } from '../dispatch-response-policy.js';
+import { isRequestAborted } from '../request-abort.js';
 const defaultBinder = new DefaultBinder();
 const defaultValidator = new HttpDtoValidationAdapter();
 /**
@@ -49,7 +50,12 @@ export async function executeFastPath(options) {
     if (isRequestAborted(request)) {
       throw new RequestAbortedError();
     }
-    if (!(result instanceof SseResponse) && !response.committed) {
+    if (result instanceof SseResponse) {
+      await waitForSseResponseCompletion(result);
+      if (isRequestAborted(request)) {
+        throw new RequestAbortedError();
+      }
+    } else if (!response.committed) {
       const writeResult = writeSuccessResponse(handler, request, response, result, contentNegotiation, requestContext);
       if (isThenable(writeResult)) {
         await writeResult;
@@ -88,7 +94,4 @@ export function shouldUseFastPathForRequest(eligibility, request) {
     return false;
   }
   return true;
-}
-function isRequestAborted(request) {
-  return request.isAborted?.() ?? request.signal?.aborted === true;
 }

package/dist/dispatch/request-abort.d.ts

@@ -0,0 +1,22 @@
+import type { FrameworkRequest, RequestContext } from '../types.js';
+/**
+ * Reports whether the adapter-provided request abort probes have fired.
+ *
+ * @param request Adapter-normalized request to inspect.
+ * @returns Whether transport cancellation has been observed.
+ */
+export declare function isRequestAborted(request: FrameworkRequest): boolean;
+/**
+ * Reports whether a request context was cancelled by transport or response-stream closure.
+ *
+ * @param context Request context to inspect.
+ * @returns Whether cancellation has been observed.
+ */
+export declare function isRequestContextAborted(context: RequestContext): boolean;
+/**
+ * Marks a request context as cancelled by a response-stream disconnect.
+ *
+ * @param context Request context whose stream closed unexpectedly.
+ */
+export declare function markRequestContextAborted(context: RequestContext): void;
+//# sourceMappingURL=request-abort.d.ts.map

package/dist/dispatch/request-abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-abort.d.ts","sourceRoot":"","sources":["../../src/dispatch/request-abort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIpE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAGxE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAEvE"}

package/dist/dispatch/request-abort.js

@@ -0,0 +1,30 @@
+const REQUEST_ABORTED_BY_RESPONSE_STREAM = Symbol('fluo.http.requestAbortedByResponseStream');
+
+/**
+ * Reports whether the adapter-provided request abort probes have fired.
+ *
+ * @param request Adapter-normalized request to inspect.
+ * @returns Whether transport cancellation has been observed.
+ */
+export function isRequestAborted(request) {
+  return request.isAborted?.() === true || request.signal?.aborted === true;
+}
+
+/**
+ * Reports whether a request context was cancelled by transport or response-stream closure.
+ *
+ * @param context Request context to inspect.
+ * @returns Whether cancellation has been observed.
+ */
+export function isRequestContextAborted(context) {
+  return isRequestAborted(context.request) || context.metadata[REQUEST_ABORTED_BY_RESPONSE_STREAM] === true;
+}
+
+/**
+ * Marks a request context as cancelled by a response-stream disconnect.
+ *
+ * @param context Request context whose stream closed unexpectedly.
+ */
+export function markRequestContextAborted(context) {
+  context.metadata[REQUEST_ABORTED_BY_RESPONSE_STREAM] = true;
+}

package/dist/dispatch/response-integration.d.ts

@@ -0,0 +1,55 @@
+import type { FrameworkRequest, FrameworkResponse, HandlerDescriptor, RequestContext, ResponseValidators } from '../types.js';
+/** Shared response-entry brand recognized by the HTTP success-response policy. */
+export declare const FRAMEWORK_RESPONSE_WRITER: unique symbol;
+/** Request-local metadata key for response-value finalization before response writing. */
+export declare const FRAMEWORK_RESPONSE_VALUE_FINALIZER: unique symbol;
+/** Context supplied when an integration writes a successful framework response. */
+export type FrameworkResponseWriterContext = {
+    readonly applySuccessResponseMetadata: () => void;
+    readonly handler: HandlerDescriptor;
+    readonly request: FrameworkRequest;
+    readonly requestContext: RequestContext;
+    readonly response: FrameworkResponse;
+    /** Validators resolved by the dispatcher before the handler executed. */
+    readonly validators: ResponseValidators | undefined;
+    /** Finalized handler value that owns this response writer. */
+    readonly value: unknown;
+};
+/** Writer installed by an HTTP integration on one response entry. */
+export type FrameworkResponseWriter = (context: FrameworkResponseWriterContext) => ReturnType<FrameworkResponse['send']> | void;
+/** Context supplied when an integration finalizes a handler result before response writing. */
+export type FrameworkResponseValueFinalizerContext = {
+    readonly handler: HandlerDescriptor;
+    readonly request: FrameworkRequest;
+    readonly requestContext: RequestContext;
+    readonly response: FrameworkResponse;
+    readonly value: unknown;
+};
+/**
+ * Request-local transformation applied before the HTTP policy selects a response writer.
+ *
+ * Finalizers may resolve asynchronously. The dispatcher awaits their results and
+ * routes thrown errors and rejections through its normal error policy.
+ */
+export type FrameworkResponseValueFinalizer = (context: FrameworkResponseValueFinalizerContext) => unknown | Promise<unknown>;
+/**
+ * Brands a response entry with an integration-owned writer.
+ *
+ * @param entry Response entry returned by an HTTP handler.
+ * @param writer Writer invoked by the shared success-response policy.
+ * @returns The branded response entry.
+ */
+export declare function registerFrameworkResponseWriter<Entry extends object>(entry: Entry, writer: FrameworkResponseWriter): Entry;
+/**
+ * Registers a request-local handler-result finalizer for an HTTP integration.
+ *
+ * @param context Active request context whose metadata carries the finalizer.
+ * @param finalizer Transformation applied before response-writer selection.
+ *
+ * @remarks
+ * Multiple registrations compose in registration order. Each later finalizer
+ * receives the previous finalizer's resolved value, and any thrown error or
+ * rejection is handled by the dispatcher's existing error policy.
+ */
+export declare function registerFrameworkResponseValueFinalizer(context: Pick<RequestContext, 'metadata'>, finalizer: FrameworkResponseValueFinalizer): void;
+//# sourceMappingURL=response-integration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response-integration.d.ts","sourceRoot":"","sources":["../../src/dispatch/response-integration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,eAAyC,CAAC;AAEhF,0FAA0F;AAC1F,eAAO,MAAM,kCAAkC,eAAiD,CAAC;AAEjG,mFAAmF;AACnF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,QAAQ,CAAC,4BAA4B,EAAE,MAAM,IAAI,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACpD,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,8BAA8B,KACpC,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;AAElD,+FAA+F;AAC/F,MAAM,MAAM,sCAAsC,GAAG;IACnD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG,CAC5C,OAAO,EAAE,sCAAsC,KAC5C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,SAAS,MAAM,EAClE,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,uBAAuB,GAC9B,KAAK,CAOP;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,EACzC,SAAS,EAAE,+BAA+B,GACzC,IAAI,CAiBN"}

package/dist/dispatch/response-integration.js

@@ -0,0 +1,57 @@
+/** Shared response-entry brand recognized by the HTTP success-response policy. */
+export const FRAMEWORK_RESPONSE_WRITER = Symbol.for('fluo.http.responseWriter');
+
+/** Request-local metadata key for response-value finalization before response writing. */
+export const FRAMEWORK_RESPONSE_VALUE_FINALIZER = Symbol.for('fluo.http.responseValueFinalizer');
+
+/** Context supplied when an integration writes a successful framework response. */
+
+/** Writer installed by an HTTP integration on one response entry. */
+
+/** Context supplied when an integration finalizes a handler result before response writing. */
+
+/**
+ * Request-local transformation applied before the HTTP policy selects a response writer.
+ *
+ * Finalizers may resolve asynchronously. The dispatcher awaits their results and
+ * routes thrown errors and rejections through its normal error policy.
+ */
+
+/**
+ * Brands a response entry with an integration-owned writer.
+ *
+ * @param entry Response entry returned by an HTTP handler.
+ * @param writer Writer invoked by the shared success-response policy.
+ * @returns The branded response entry.
+ */
+export function registerFrameworkResponseWriter(entry, writer) {
+  Object.defineProperty(entry, FRAMEWORK_RESPONSE_WRITER, {
+    enumerable: false,
+    value: writer
+  });
+  return entry;
+}
+
+/**
+ * Registers a request-local handler-result finalizer for an HTTP integration.
+ *
+ * @param context Active request context whose metadata carries the finalizer.
+ * @param finalizer Transformation applied before response-writer selection.
+ *
+ * @remarks
+ * Multiple registrations compose in registration order. Each later finalizer
+ * receives the previous finalizer's resolved value, and any thrown error or
+ * rejection is handled by the dispatcher's existing error policy.
+ */
+export function registerFrameworkResponseValueFinalizer(context, finalizer) {
+  const existingFinalizer = context.metadata[FRAMEWORK_RESPONSE_VALUE_FINALIZER];
+  if (typeof existingFinalizer !== 'function') {
+    context.metadata[FRAMEWORK_RESPONSE_VALUE_FINALIZER] = finalizer;
+    return;
+  }
+  const previousFinalizer = existingFinalizer;
+  context.metadata[FRAMEWORK_RESPONSE_VALUE_FINALIZER] = async finalizerContext => finalizer({
+    ...finalizerContext,
+    value: await previousFinalizer(finalizerContext)
+  });
+}

package/dist/errors.d.ts

@@ -11,6 +11,10 @@ export declare class RouteConflictError extends FluoError {
 export declare class InvalidRoutePathError extends FluoError {
     constructor(message: string);
 }
+/** Error thrown when a generic route method is not a valid HTTP token or uses the reserved `ALL` sentinel. */
+export declare class InvalidHttpMethodError extends FluoError {
+    constructor(message: string);
+}
 /**
  * Error thrown when no handler matches the incoming request path or method.
  */
@@ -23,4 +27,10 @@ export declare class HandlerNotFoundError extends FluoError {
 export declare class RequestAbortedError extends FluoError {
     constructor(message?: string);
 }
+/** Error thrown when a supported adapter cannot emit one Early Hints response. */
+export declare class EarlyHintsWriteError extends FluoError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAA4C;CAGhE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,OAAO,EAAE,MAAM;CAG5B;AAED,8GAA8G;AAC9G,qBAAa,sBAAuB,SAAQ,SAAS;gBACvC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,EAAE,MAAM;CAG5B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,SAA4C;CAGhE;AAED,kFAAkF;AAClF,qBAAa,oBAAqB,SAAQ,SAAS;gBAE/C,OAAO,SAA0C,EACjD,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAOpC"}

package/dist/errors.js

@@ -22,6 +22,15 @@ export class InvalidRoutePathError extends FluoError {
   }
 }
 
+/** Error thrown when a generic route method is not a valid HTTP token or uses the reserved `ALL` sentinel. */
+export class InvalidHttpMethodError extends FluoError {
+  constructor(message) {
+    super(message, {
+      code: 'INVALID_HTTP_METHOD'
+    });
+  }
+}
+
 /**
  * Error thrown when no handler matches the incoming request path or method.
  */
@@ -42,4 +51,14 @@ export class RequestAbortedError extends FluoError {
       code: 'REQUEST_ABORTED'
     });
   }
+}
+
+/** Error thrown when a supported adapter cannot emit one Early Hints response. */
+export class EarlyHintsWriteError extends FluoError {
+  constructor(message = 'Failed to write HTTP 103 Early Hints.', options = {}) {
+    super(message, {
+      cause: options.cause,
+      code: 'EARLY_HINTS_WRITE_FAILED'
+    });
+  }
 }

package/dist/guards.d.ts

@@ -6,5 +6,5 @@ import type { GuardContext, GuardLike } from './types.js';
  * @param context The context.
  * @returns The run guard chain result.
  */
-export declare function runGuardChain(definitions: GuardLike[], context: GuardContext): Promise<void>;
+export declare function runGuardChain(definitions: readonly GuardLike[], context: GuardContext): Promise<void>;
 //# sourceMappingURL=guards.d.ts.map

package/dist/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAS,YAAY,EAAE,SAAS,EAAkB,MAAM,YAAY,CAAC;AAcjF;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAalG"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAS,YAAY,EAAE,SAAS,EAAkB,MAAM,YAAY,CAAC;AAcjF;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAa3G"}

package/dist/header-helpers.d.ts

@@ -0,0 +1,59 @@
+import type { FrameworkRequest, FrameworkResponse } from './types.js';
+/**
+ * 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 declare function getRequestHeader(request: FrameworkRequest, name: string): string | string[] | undefined;
+/**
+ * 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 declare function getResponseHeader(response: FrameworkResponse, name: string): string | string[] | undefined;
+/**
+ * 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 declare function hasResponseHeader(response: FrameworkResponse, name: string): boolean;
+/**
+ * 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 declare function buildContentDisposition(disposition: 'attachment' | 'inline', filename: string): string;
+/**
+ * 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 declare function readFirstNonEmptyRequestHeaderValue(request: FrameworkRequest, name: string): string | 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 declare function readJoinedNonEmptyRequestHeaderValues(request: FrameworkRequest, name: string): string | 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 declare function appendVaryHeader(response: FrameworkResponse, ...fields: string[]): void;
+//# sourceMappingURL=header-helpers.d.ts.map

package/dist/header-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-helpers.d.ts","sourceRoot":"","sources":["../src/header-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAmEtE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAE/B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAE/B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,OAAO,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,YAAY,GAAG,QAAQ,EACpC,QAAQ,EAAE,MAAM,GACf,MAAM,CAsCR;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAmBpB;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAqBpB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,MAAM,EAAE,MAAM,EAAE,GAClB,IAAI,CA0CN"}

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