@fluojs/http 2.0.1 → 3.0.0

package/dist/dispatch/dispatch-content-negotiation.js

@@ -1,31 +1,52 @@
 import { NotAcceptableException } from '../exceptions.js';
+import { readJoinedNonEmptyRequestHeaderValues } from '../header-helpers.js';
 
 /**
  * Describes the resolved content negotiation contract.
  */
 
 const NO_ACCEPTABLE_REPRESENTATION_MESSAGE = 'No acceptable response representation found.';
+class ContentNegotiationNotAcceptableException extends NotAcceptableException {}
 function normalizeMediaType(value) {
   return value.split(';')[0]?.trim().toLowerCase() ?? '';
 }
 function readAcceptHeader(request) {
-  const raw = request.headers.accept ?? request.headers.Accept;
-  const value = Array.isArray(raw) ? raw.join(',') : raw;
-  const normalized = value?.trim();
-  return normalized ? normalized : undefined;
+  return readJoinedNonEmptyRequestHeaderValues(request, 'accept');
 }
 function parseQuality(value) {
-  if (!value) {
-    return 1;
+  if (!/^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/.test(value)) {
+    return undefined;
   }
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0) {
-    return 0;
+  return Number(value);
+}
+
+/**
+ * Determines whether an error originated from response content negotiation.
+ *
+ * @param error Candidate error emitted while selecting a response formatter.
+ * @returns Whether the error requires `Vary: Accept` on its representation.
+ */
+export function isContentNegotiationNotAcceptableException(error) {
+  return error instanceof ContentNegotiationNotAcceptableException;
+}
+function isValidMediaRange(mediaRange) {
+  const [type, subtype, extra] = mediaRange.split('/');
+  if (!type || !subtype || extra !== undefined) {
+    return false;
   }
-  if (parsed > 1) {
-    return 1;
+  if (type === '*') {
+    return subtype === '*';
+  }
+  if (type.includes('*')) {
+    return false;
   }
-  return parsed;
+  if (subtype === '*') {
+    return true;
+  }
+  if (subtype.startsWith('*+')) {
+    return subtype.length > 2 && !subtype.slice(2).includes('*');
+  }
+  return !subtype.includes('*');
 }
 function getMediaRangeSpecificity(mediaRange) {
   if (mediaRange === '*/*') {
@@ -34,39 +55,46 @@ function getMediaRangeSpecificity(mediaRange) {
   if (mediaRange.endsWith('/*')) {
     return 1;
   }
-  return 2;
+  return mediaRange.includes('/*+') ? 2 : 3;
 }
 function parseAcceptHeader(acceptHeader) {
   const tokens = [];
-  for (const token of acceptHeader.split(',')) {
+  for (const [order, token] of acceptHeader.split(',').entries()) {
     const [rawMediaRange, ...parameterParts] = token.trim().split(';');
     const mediaRange = normalizeMediaType(rawMediaRange ?? '');
-    if (!mediaRange || !mediaRange.includes('/')) {
+    if (!isValidMediaRange(mediaRange)) {
       continue;
     }
     let quality = 1;
+    let qualityDefined = false;
+    let malformed = false;
     for (const parameterPart of parameterParts) {
-      const [name, value] = parameterPart.trim().split('=');
+      const [name, ...rawValues] = parameterPart.trim().split('=');
       if (name?.toLowerCase() === 'q') {
-        quality = parseQuality(value?.trim());
-        break;
+        if (qualityDefined || rawValues.length !== 1) {
+          malformed = true;
+          break;
+        }
+        const parsedQuality = parseQuality(rawValues[0]?.trim() ?? '');
+        if (parsedQuality === undefined) {
+          malformed = true;
+          break;
+        }
+        quality = parsedQuality;
+        qualityDefined = true;
       }
     }
-    if (quality <= 0) {
+    if (malformed) {
       continue;
     }
     tokens.push({
       mediaRange,
+      order,
       quality,
       specificity: getMediaRangeSpecificity(mediaRange)
     });
   }
-  return tokens.sort((left, right) => {
-    if (right.quality !== left.quality) {
-      return right.quality - left.quality;
-    }
-    return right.specificity - left.specificity;
-  });
+  return tokens;
 }
 function matchesMediaRange(mediaRange, mediaType) {
   if (mediaRange === '*/*') {
@@ -80,7 +108,25 @@ function matchesMediaRange(mediaRange, mediaType) {
   if (rangeType !== '*' && rangeType !== mediaTypeType) {
     return false;
   }
-  return rangeSubtype === '*' || rangeSubtype === mediaTypeSubtype;
+  if (rangeSubtype === '*') {
+    return true;
+  }
+  if (rangeSubtype.startsWith('*+')) {
+    return mediaTypeSubtype.endsWith(rangeSubtype.slice(1));
+  }
+  return rangeSubtype === mediaTypeSubtype;
+}
+function selectMostSpecificAcceptToken(mediaType, acceptTokens) {
+  let selected;
+  for (const token of acceptTokens) {
+    if (!matchesMediaRange(token.mediaRange, mediaType)) {
+      continue;
+    }
+    if (!selected || token.specificity > selected.specificity || token.specificity === selected.specificity && token.order < selected.order) {
+      selected = token;
+    }
+  }
+  return selected;
 }
 
 /**
@@ -155,7 +201,7 @@ export function selectResponseFormatter(handler, request, contentNegotiation) {
     normalizedMediaTypes: allowedNormalizedMediaTypes
   } = resolveAllowedFormatters(handler, contentNegotiation);
   if (!allowedFormatters.length) {
-    throw new NotAcceptableException(NO_ACCEPTABLE_REPRESENTATION_MESSAGE);
+    throw new ContentNegotiationNotAcceptableException(NO_ACCEPTABLE_REPRESENTATION_MESSAGE);
   }
   const defaultFormatter = resolveDefaultFormatter(allowedFormatters, allowedNormalizedMediaTypes, contentNegotiation);
   const acceptHeader = readAcceptHeader(request);
@@ -164,22 +210,23 @@ export function selectResponseFormatter(handler, request, contentNegotiation) {
   }
   const acceptTokens = parseAcceptHeader(acceptHeader);
   if (!acceptTokens.length) {
-    throw new NotAcceptableException(NO_ACCEPTABLE_REPRESENTATION_MESSAGE);
-  }
-  for (const token of acceptTokens) {
-    if (token.mediaRange === '*/*') {
-      return defaultFormatter;
-    }
-    let matchedFormatter;
-    for (let i = 0; i < allowedFormatters.length; i++) {
-      if (matchesMediaRange(token.mediaRange, allowedNormalizedMediaTypes[i])) {
-        matchedFormatter = allowedFormatters[i];
-        break;
-      }
+    throw new ContentNegotiationNotAcceptableException(NO_ACCEPTABLE_REPRESENTATION_MESSAGE);
+  }
+  let selectedFormatter;
+  let selectedToken;
+  for (let i = 0; i < allowedFormatters.length; i++) {
+    const formatter = allowedFormatters[i];
+    const token = selectMostSpecificAcceptToken(allowedNormalizedMediaTypes[i], acceptTokens);
+    if (!token || token.quality === 0 || selectedToken && (token.quality < selectedToken.quality || token.quality === selectedToken.quality && token.specificity < selectedToken.specificity)) {
+      continue;
     }
-    if (matchedFormatter) {
-      return matchedFormatter;
+    if (!selectedToken || token.quality > selectedToken.quality || token.specificity > selectedToken.specificity || formatter === defaultFormatter) {
+      selectedFormatter = formatter;
+      selectedToken = token;
     }
   }
-  throw new NotAcceptableException(NO_ACCEPTABLE_REPRESENTATION_MESSAGE);
+  if (selectedFormatter) {
+    return selectedFormatter;
+  }
+  throw new ContentNegotiationNotAcceptableException(NO_ACCEPTABLE_REPRESENTATION_MESSAGE);
 }

package/dist/dispatch/dispatch-error-negotiation.d.ts

@@ -0,0 +1,26 @@
+import type { RequestContext } from '../types.js';
+/** Error representation selected by HTTP content negotiation. */
+export type ErrorRepresentationKind = 'html' | 'json';
+/**
+ * Reads the normalized Accept header from one request context.
+ *
+ * @param context Active HTTP request context.
+ * @returns The normalized header value when present.
+ */
+export declare function readAcceptHeader(context: RequestContext): string | undefined;
+/**
+ * Determines whether an Accept header permits the HTML representation.
+ *
+ * @param acceptHeader Normalized Accept header value.
+ * @returns Whether HTML has a positive matching quality.
+ */
+export declare function canNegotiateHtml(acceptHeader: string | undefined): boolean;
+/**
+ * Selects the deterministic error representation for one Accept header.
+ *
+ * @param acceptHeader Normalized Accept header value.
+ * @param htmlAvailable Whether the application HTML provider is available.
+ * @returns The selected representation, or `undefined` when no offer is acceptable.
+ */
+export declare function selectErrorRepresentation(acceptHeader: string | undefined, htmlAvailable: boolean): ErrorRepresentationKind | undefined;
+//# sourceMappingURL=dispatch-error-negotiation.d.ts.map

package/dist/dispatch/dispatch-error-negotiation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-error-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-error-negotiation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMlD,iEAAiE;AACjE,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,CAAC;AA2EtD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAO1E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,aAAa,EAAE,OAAO,GACrB,uBAAuB,GAAG,SAAS,CAoCrC"}

package/dist/dispatch/dispatch-error-negotiation.js

@@ -0,0 +1,110 @@
+import { readFirstNonEmptyRequestHeaderValue } from '../header-helpers.js';
+const HTML_MEDIA_TYPE = 'text/html';
+const JSON_MEDIA_TYPE = 'application/json';
+
+/** Error representation selected by HTTP content negotiation. */
+
+function parseQuality(value) {
+  if (value === undefined) {
+    return 1;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : 0;
+}
+function mediaRangeSpecificity(mediaRange) {
+  if (mediaRange === '*/*') {
+    return 0;
+  }
+  return mediaRange.endsWith('/*') ? 1 : 2;
+}
+function parseAcceptHeader(value) {
+  const ranges = [];
+  for (const [order, token] of value.split(',').entries()) {
+    const [rawMediaRange, ...parameters] = token.trim().split(';');
+    const mediaRange = rawMediaRange?.trim().toLowerCase() ?? '';
+    if (!mediaRange.includes('/')) {
+      continue;
+    }
+    const qualityParameter = parameters.map(parameter => parameter.trim().split('=')).find(([name]) => name?.toLowerCase() === 'q');
+    ranges.push({
+      mediaRange,
+      order,
+      quality: parseQuality(qualityParameter?.[1]?.trim()),
+      specificity: mediaRangeSpecificity(mediaRange)
+    });
+  }
+  return ranges;
+}
+function mediaRangeMatches(mediaRange, mediaType) {
+  const [rangeType, rangeSubtype] = mediaRange.split('/');
+  const [type, subtype] = mediaType.split('/');
+  return rangeType !== undefined && rangeSubtype !== undefined && type !== undefined && subtype !== undefined && (rangeType === '*' || rangeType === type) && (rangeSubtype === '*' || rangeSubtype === subtype);
+}
+function bestRangeForMediaType(ranges, mediaType) {
+  return ranges.filter(range => mediaRangeMatches(range.mediaRange, mediaType)).sort((left, right) => right.specificity - left.specificity || left.order - right.order)[0];
+}
+
+/**
+ * Reads the normalized Accept header from one request context.
+ *
+ * @param context Active HTTP request context.
+ * @returns The normalized header value when present.
+ */
+export function readAcceptHeader(context) {
+  return readFirstNonEmptyRequestHeaderValue(context.request, 'accept');
+}
+
+/**
+ * Determines whether an Accept header permits the HTML representation.
+ *
+ * @param acceptHeader Normalized Accept header value.
+ * @returns Whether HTML has a positive matching quality.
+ */
+export function canNegotiateHtml(acceptHeader) {
+  if (acceptHeader === undefined) {
+    return false;
+  }
+  const range = bestRangeForMediaType(parseAcceptHeader(acceptHeader), HTML_MEDIA_TYPE);
+  return range !== undefined && range.quality > 0;
+}
+
+/**
+ * Selects the deterministic error representation for one Accept header.
+ *
+ * @param acceptHeader Normalized Accept header value.
+ * @param htmlAvailable Whether the application HTML provider is available.
+ * @returns The selected representation, or `undefined` when no offer is acceptable.
+ */
+export function selectErrorRepresentation(acceptHeader, htmlAvailable) {
+  if (acceptHeader === undefined) {
+    return 'json';
+  }
+  const ranges = parseAcceptHeader(acceptHeader);
+  const offers = htmlAvailable ? [{
+    kind: 'json',
+    mediaType: JSON_MEDIA_TYPE,
+    priority: 0
+  }, {
+    kind: 'html',
+    mediaType: HTML_MEDIA_TYPE,
+    priority: 1
+  }] : [{
+    kind: 'json',
+    mediaType: JSON_MEDIA_TYPE,
+    priority: 0
+  }];
+  const candidates = [];
+  for (const offer of offers) {
+    const range = bestRangeForMediaType(ranges, offer.mediaType);
+    if (range !== undefined && range.quality > 0) {
+      candidates.push({
+        kind: offer.kind,
+        priority: offer.priority,
+        quality: range.quality,
+        specificity: range.specificity
+      });
+    }
+  }
+  candidates.sort((left, right) => right.quality - left.quality || right.specificity - left.specificity || left.priority - right.priority);
+  return candidates[0]?.kind;
+}

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

@@ -1,11 +1,2 @@
-import type { FrameworkResponse } from '../types.js';
-/**
- * Write error response.
- *
- * @param error The error.
- * @param response The response.
- * @param requestId The request id.
- * @returns The write error response result.
- */
-export declare function writeErrorResponse(error: unknown, response: FrameworkResponse, requestId?: string): Promise<void>;
+export { writeErrorResponse } from './dispatch-error-representation.js';
 //# sourceMappingURL=dispatch-error-policy.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch-error-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-error-policy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAiBrD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvH"}
+{"version":3,"file":"dispatch-error-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-error-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC"}

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

@@ -1,33 +1 @@
-import { HandlerNotFoundError } from '../errors.js';
-import { HttpException, InternalServerErrorException, NotFoundException, createErrorResponse } from '../exceptions.js';
-function toHttpException(error) {
-  if (error instanceof HttpException) {
-    return error;
-  }
-  if (error instanceof HandlerNotFoundError) {
-    const message = error instanceof Error ? error.message : 'Resource not found.';
-    return new NotFoundException(message, {
-      cause: error
-    });
-  }
-  return new InternalServerErrorException('Internal server error.', {
-    cause: error
-  });
-}
-
-/**
- * Write error response.
- *
- * @param error The error.
- * @param response The response.
- * @param requestId The request id.
- * @returns The write error response result.
- */
-export async function writeErrorResponse(error, response, requestId) {
-  if (response.committed) {
-    return;
-  }
-  const httpError = toHttpException(error);
-  response.setStatus(httpError.status);
-  await response.send(createErrorResponse(httpError, requestId));
-}
+export { writeErrorResponse } from './dispatch-error-representation.js';

package/dist/dispatch/dispatch-error-representation.d.ts

@@ -0,0 +1,18 @@
+import type { DispatcherLogger, HandlerDescriptor, HttpErrorRepresentationOptions, RequestContext } from '../types.js';
+type WriteErrorResponseOptions = {
+    readonly handler?: HandlerDescriptor;
+    readonly logger?: DispatcherLogger;
+    readonly representation?: HttpErrorRepresentationOptions;
+    readonly varyAccept?: boolean;
+};
+/**
+ * Writes one HTTP-owned error representation when the response remains writable.
+ *
+ * @param error Failure classified by the HTTP dispatch pipeline.
+ * @param requestContext Active request and response context.
+ * @param options Matched-handler, logger, and optional HTML provider settings.
+ * @returns A promise that settles after the selected response is written or skipped.
+ */
+export declare function writeErrorResponse(error: unknown, requestContext: RequestContext, options?: WriteErrorResponseOptions): Promise<void>;
+export {};
+//# sourceMappingURL=dispatch-error-representation.d.ts.map

package/dist/dispatch/dispatch-error-representation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-error-representation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-error-representation.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,gBAAgB,EAEhB,iBAAiB,EAGjB,8BAA8B,EAC9B,cAAc,EACf,MAAM,aAAa,CAAC;AAcrB,KAAK,yBAAyB,GAAG;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,8BAA8B,CAAC;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAsEF;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EACd,cAAc,EAAE,cAAc,EAC9B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAoEf"}

package/dist/dispatch/dispatch-error-representation.js

@@ -0,0 +1,125 @@
+import { HandlerNotFoundError } from '../errors.js';
+import { createErrorResponse, HttpException, InternalServerErrorException, NotAcceptableException, NotFoundException } from '../exceptions.js';
+import { canNegotiateHtml, readAcceptHeader, selectErrorRepresentation } from './dispatch-error-negotiation.js';
+import { appendVaryHeader } from '../header-helpers.js';
+import { isRequestAborted } from './request-abort.js';
+const HTML_CONTENT_TYPE = 'text/html; charset=utf-8';
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+const NOT_ACCEPTABLE_MESSAGE = 'No acceptable response representation found.';
+const PROVIDER_FAILURE_MESSAGE = 'HTML error representation provider threw before response commit; falling back to canonical JSON.';
+function toHttpException(error) {
+  if (error instanceof HttpException) {
+    return error;
+  }
+  if (error instanceof HandlerNotFoundError) {
+    const message = error instanceof Error ? error.message : 'Resource not found.';
+    return new NotFoundException(message, {
+      cause: error
+    });
+  }
+  return new InternalServerErrorException('Internal server error.', {
+    cause: error
+  });
+}
+function isHttpRepresentationEligible(error) {
+  return error instanceof HttpException || error instanceof HandlerNotFoundError;
+}
+function createRepresentationContext(error, requestContext, handler) {
+  return {
+    container: requestContext.container,
+    error,
+    ...(handler === undefined ? {} : {
+      handler
+    }),
+    json: createErrorResponse(error, requestContext.requestId),
+    request: requestContext.request,
+    ...(requestContext.requestId === undefined ? {} : {
+      requestId: requestContext.requestId
+    })
+  };
+}
+async function isHtmlAvailable(provider, context) {
+  return provider.canRender === undefined || (await provider.canRender(context));
+}
+function setNegotiatedHeaders(response, contentType) {
+  response.setHeader('Content-Type', contentType);
+  appendVaryHeader(response, 'Accept');
+}
+async function writeBody(requestContext, status, contentType, body) {
+  if (requestContext.response.committed || isRequestAborted(requestContext.request)) {
+    return;
+  }
+  requestContext.response.setStatus(status);
+  setNegotiatedHeaders(requestContext.response, contentType);
+  await requestContext.response.send(requestContext.request.method.toUpperCase() === 'HEAD' ? undefined : body);
+}
+async function writeCanonicalJson(error, requestContext) {
+  await writeBody(requestContext, error.status, JSON_CONTENT_TYPE, createErrorResponse(error, requestContext.requestId));
+}
+
+/**
+ * Writes one HTTP-owned error representation when the response remains writable.
+ *
+ * @param error Failure classified by the HTTP dispatch pipeline.
+ * @param requestContext Active request and response context.
+ * @param options Matched-handler, logger, and optional HTML provider settings.
+ * @returns A promise that settles after the selected response is written or skipped.
+ */
+export async function writeErrorResponse(error, requestContext, options = {}) {
+  if (requestContext.response.committed || isRequestAborted(requestContext.request)) {
+    return;
+  }
+  if (options.varyAccept) {
+    appendVaryHeader(requestContext.response, 'Accept');
+  }
+  const httpError = toHttpException(error);
+  const provider = options.representation?.html;
+  if (provider === undefined || !isHttpRepresentationEligible(error)) {
+    requestContext.response.setStatus(httpError.status);
+    if (requestContext.request.method.toUpperCase() === 'HEAD') {
+      requestContext.response.setHeader('Content-Type', JSON_CONTENT_TYPE);
+      await requestContext.response.send(undefined);
+      return;
+    }
+    await requestContext.response.send(createErrorResponse(httpError, requestContext.requestId));
+    return;
+  }
+  const acceptHeader = readAcceptHeader(requestContext);
+  const representationContext = createRepresentationContext(httpError, requestContext, options.handler);
+  let htmlAvailable = false;
+  try {
+    htmlAvailable = canNegotiateHtml(acceptHeader) && (await isHtmlAvailable(provider, representationContext));
+  } catch (providerError) {
+    if (isRequestAborted(requestContext.request)) {
+      return;
+    }
+    options.logger?.error(PROVIDER_FAILURE_MESSAGE, providerError, 'HttpDispatcher');
+    await writeCanonicalJson(httpError, requestContext);
+    return;
+  }
+  const selected = selectErrorRepresentation(acceptHeader, htmlAvailable);
+  if (selected === undefined) {
+    await writeCanonicalJson(new NotAcceptableException(NOT_ACCEPTABLE_MESSAGE), requestContext);
+    return;
+  }
+  if (selected === 'json') {
+    await writeCanonicalJson(httpError, requestContext);
+    return;
+  }
+  if (requestContext.request.method.toUpperCase() === 'HEAD') {
+    await writeBody(requestContext, httpError.status, HTML_CONTENT_TYPE, undefined);
+    return;
+  }
+  let body;
+  try {
+    body = await provider.render(representationContext);
+  } catch (providerError) {
+    if (isRequestAborted(requestContext.request)) {
+      return;
+    }
+    options.logger?.error(PROVIDER_FAILURE_MESSAGE, providerError, 'HttpDispatcher');
+    await writeCanonicalJson(httpError, requestContext);
+    return;
+  }
+  await writeBody(requestContext, httpError.status, HTML_CONTENT_TYPE, body);
+}

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

@@ -0,0 +1,10 @@
+import type { FrameworkResponse, HandlerDescriptor } from '../types.js';
+/**
+ * Applies route-declared headers without setting success response metadata.
+ *
+ * @param handler Matched route descriptor that declares response headers.
+ * @param response Mutable adapter-normalized response.
+ * @returns Nothing.
+ */
+export declare function applyRouteHeaders(handler: HandlerDescriptor, response: FrameworkResponse): void;
+//# sourceMappingURL=dispatch-response-metadata.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-response-metadata.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAI/F"}

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

@@ -0,0 +1,12 @@
+/**
+ * Applies route-declared headers without setting success response metadata.
+ *
+ * @param handler Matched route descriptor that declares response headers.
+ * @param response Mutable adapter-normalized response.
+ * @returns Nothing.
+ */
+export function applyRouteHeaders(handler, response) {
+  for (const header of handler.route.headers ?? []) {
+    response.setHeader(header.name, header.value);
+  }
+}

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

@@ -1,6 +1,21 @@
-import type { FrameworkRequest, FrameworkResponse, HandlerDescriptor, RequestContext } from '../types.js';
+import type { FrameworkRequest, FrameworkResponse, HandlerDescriptor, RequestContext, ResponseFormatter, ResponseValidators } from '../types.js';
+import { type ConditionalRequestOutcome } from './conditional-request-policy.js';
 import { type ResolvedContentNegotiation, resolveContentNegotiation } from './dispatch-content-negotiation.js';
 import { writeErrorResponse } from './dispatch-error-policy.js';
+/** Selected representation metadata shared by success and conditional response writers. */
+export interface ResolvedResponsePolicy {
+    readonly formatter: ResponseFormatter | undefined;
+    readonly variesByAccept: boolean;
+}
+/**
+ * Resolves the representation policy before conditional request evaluation.
+ *
+ * @param handler Matched route descriptor.
+ * @param request Adapter-normalized request.
+ * @param contentNegotiation Configured response formatters.
+ * @returns Formatter selection and representation variance metadata.
+ */
+export declare function resolveResponsePolicy(handler: HandlerDescriptor, request: FrameworkRequest, contentNegotiation: ResolvedContentNegotiation | undefined): ResolvedResponsePolicy;
 /**
  * Write success response.
  *
@@ -8,11 +23,23 @@ import { writeErrorResponse } from './dispatch-error-policy.js';
  * @param request The request.
  * @param response The response.
  * @param value The value.
- * @param contentNegotiation The content negotiation.
+ * @param contentNegotiation The configured response formatters.
  * @param requestContext The active request context passed to custom response writers.
+ * @param validators Validators resolved before the route handler executes.
+ * @param conditionalOutcome Matched conditional outcome for formatter-managed responses.
  * @returns The write success response result.
  */
-export declare function writeSuccessResponse(handler: HandlerDescriptor, request: FrameworkRequest, response: FrameworkResponse, value: unknown, contentNegotiation: ResolvedContentNegotiation | undefined, requestContext: RequestContext): ReturnType<FrameworkResponse['send']> | void;
+export declare function writeSuccessResponse(handler: HandlerDescriptor, request: FrameworkRequest, response: FrameworkResponse, value: unknown, contentNegotiation: ResolvedContentNegotiation | undefined, requestContext: RequestContext, validators?: ResponseValidators, conditionalOutcome?: Exclude<ConditionalRequestOutcome, 'proceed'>): Promise<void>;
+/**
+ * Writes a bodyless conditional response through every supported adapter facade.
+ *
+ * @param response Mutable adapter-normalized response.
+ * @param outcome Selected non-proceed conditional request outcome.
+ * @param validators Current representation validators.
+ * @param responsePolicy Selected representation metadata.
+ * @returns A promise that settles after the adapter accepts the bodyless response.
+ */
+export declare function writeConditionalResponse(response: FrameworkResponse, outcome: Exclude<ConditionalRequestOutcome, 'proceed'>, validators: ResponseValidators | undefined, responsePolicy: ResolvedResponsePolicy): Promise<void>;
 export type { ResolvedContentNegotiation };
 export { resolveContentNegotiation, writeErrorResponse };
 //# sourceMappingURL=dispatch-response-policy.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch-response-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,0BAA0B,EAC/B,yBAAyB,EAE1B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AA8GhE;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,EAC1D,cAAc,EAAE,cAAc,GAC7B,UAAU,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CA+C9C;AAED,YAAY,EAAE,0BAA0B,EAAE,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"dispatch-response-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-response-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,KAAK,0BAA0B,EAC/B,yBAAyB,EAE1B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AA8BhE,2FAA2F;AAC3F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,GACzD,sBAAsB,CASxB;AA2GD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,kBAAkB,EAAE,0BAA0B,GAAG,SAAS,EAC1D,cAAc,EAAE,cAAc,EAC9B,UAAU,CAAC,EAAE,kBAAkB,EAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC,yBAAyB,EAAE,SAAS,CAAC,iBA6EnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,OAAO,CAAC,yBAAyB,EAAE,SAAS,CAAC,EACtD,UAAU,EAAE,kBAAkB,GAAG,SAAS,EAC1C,cAAc,EAAE,sBAAsB,GACrC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,YAAY,EAAE,0BAA0B,EAAE,CAAC;AAC3C,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,CAAC"}