@fluojs/http 1.1.2 → 3.0.0

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

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

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;
@@ -13,7 +13,20 @@ interface ExecuteFastPathOptions {
     requestContext: RequestContext;
     response: FrameworkResponse;
 }
+/**
+ * Execute one handler through the compiled fast-path dispatcher plan.
+ *
+ * @param options Fast-path execution inputs for binding, handler invocation, and response writing.
+ * @returns The fast-path execution result, including a fallback error when the route cannot be executed safely.
+ */
 export declare function executeFastPath(options: ExecuteFastPathOptions): Promise<FastPathExecutionResult>;
+/**
+ * Determine whether a request may use the precompiled fast-path execution plan.
+ *
+ * @param eligibility The handler fast-path eligibility state computed during dispatcher setup.
+ * @param request The active request whose abort state can disable fast-path execution.
+ * @returns `true` when the request can use the fast-path executor.
+ */
 export declare function shouldUseFastPathForRequest(eligibility: {
     executionPath: 'fast' | 'full';
 } | undefined, request: FrameworkRequest): boolean;

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,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,uBAAuB,CAAC,CAoDlC;AASD,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,11 +1,18 @@
 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();
+/**
+ * Execute one handler through the compiled fast-path dispatcher plan.
+ *
+ * @param options Fast-path execution inputs for binding, handler invocation, and response writing.
+ * @returns The fast-path execution result, including a fallback error when the route cannot be executed safely.
+ */
 export async function executeFastPath(options) {
   const {
     binder,
@@ -43,8 +50,13 @@ export async function executeFastPath(options) {
     if (isRequestAborted(request)) {
       throw new RequestAbortedError();
     }
-    if (!(result instanceof SseResponse) && !response.committed) {
-      const writeResult = writeSuccessResponse(handler, request, response, result, contentNegotiation);
+    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;
       }
@@ -63,6 +75,14 @@ export async function executeFastPath(options) {
 function isThenable(value) {
   return typeof value === 'object' && value !== null && 'then' in value && typeof value.then === 'function';
 }
+
+/**
+ * Determine whether a request may use the precompiled fast-path execution plan.
+ *
+ * @param eligibility The handler fast-path eligibility state computed during dispatcher setup.
+ * @param request The active request whose abort state can disable fast-path execution.
+ * @returns `true` when the request can use the fast-path executor.
+ */
 export function shouldUseFastPathForRequest(eligibility, request) {
   if (!eligibility) {
     return false;
@@ -74,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"}