@fluojs/http 1.1.2 → 3.0.0

package/dist/decorators.js

@@ -1,10 +1,12 @@
 import { defineControllerMetadata, defineDtoFieldBindingMetadata, defineRouteMetadata, ensureMetadataSymbol, getControllerMetadata, getDtoFieldBindingMetadata, getRouteMetadata, getStandardMetadataBag as readStandardMetadataBag } from '@fluojs/core/internal';
+import { InvalidHttpMethodError } from './errors.js';
 import { validateRoutePath } from './route-path.js';
 const standardControllerMetadataKey = Symbol.for('fluo.standard.controller');
 const standardRouteMetadataKey = Symbol.for('fluo.standard.route');
 const standardDtoBindingMetadataKey = Symbol.for('fluo.standard.dto-binding');
 const legacyRouteMetadataStore = new WeakMap();
 const legacyDtoBindingMetadataStore = new WeakMap();
+const httpMethodTokenPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 ensureMetadataSymbol();
 function normalizeProducesMediaTypes(mediaTypes) {
   const normalized = [];
@@ -17,6 +19,16 @@ function normalizeProducesMediaTypes(mediaTypes) {
   }
   return normalized;
 }
+function normalizeHttpRouteMethod(method) {
+  if (!httpMethodTokenPattern.test(method)) {
+    throw new InvalidHttpMethodError(`HTTP route method "${method}" must be a non-empty HTTP token.`);
+  }
+  const normalized = method.toUpperCase();
+  if (normalized === 'ALL') {
+    throw new InvalidHttpMethodError('HTTP route method "ALL" is reserved for the @All() wildcard decorator.');
+  }
+  return normalized;
+}
 function mergeUnique(existing, values) {
   const merged = [...(existing ?? [])];
   for (const value of values) {
@@ -185,7 +197,7 @@ function mergeStandardDtoBinding(metadata, propertyKey, partial) {
   });
 }
 function createRouteDecorator(method, produces) {
-  return path => {
+  return (path = '') => {
     validateRoutePath(path, `@${method}() path`);
     const decorator = (valueOrTarget, contextOrPropertyKey) => {
       if (isStandardDecoratorContext(contextOrPropertyKey)) {
@@ -302,66 +314,89 @@ export function Version(version) {
 /**
  * Registers a `GET` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `GET` handler mapping.
  */
 export const Get = createRouteDecorator('GET');
 /**
  * Registers a server-sent events route handler as `GET` with `text/event-stream` produces metadata.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `GET` SSE handler mapping.
  *
  * @remarks
  * Handlers may return `SseResponse` for manual control or `AsyncIterable<SseMessage<T> | T>` for managed dispatcher streaming.
  */
 export const Sse = createRouteDecorator('GET', ['text/event-stream']);
+/**
+ * Registers a route handler for one validated HTTP method token.
+ *
+ * @param method HTTP method token, canonicalized to uppercase before metadata registration.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
+ * @returns A method decorator that registers the method-specific handler mapping.
+ *
+ * @throws {InvalidHttpMethodError} When `method` is empty, contains non-token characters, or is the reserved `ALL` sentinel.
+ *
+ * @remarks
+ * Adapter wire support remains runtime-specific. `CONNECT` is outside ordinary routing conformance,
+ * and custom methods are not implied to be OpenAPI Path Item operations.
+ */
+export function Route(method, path = '') {
+  return createRouteDecorator(normalizeHttpRouteMethod(method))(path);
+}
+/**
+ * Registers an RFC `QUERY` route handler.
+ *
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
+ * @returns A method decorator that registers a `QUERY` handler mapping.
+ */
+export const Query = (path = '') => Route('QUERY', path);
 /**
  * Registers a `POST` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `POST` handler mapping.
  */
 export const Post = createRouteDecorator('POST');
 /**
  * Registers a `PUT` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `PUT` handler mapping.
  */
 export const Put = createRouteDecorator('PUT');
 /**
  * Registers a `PATCH` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `PATCH` handler mapping.
  */
 export const Patch = createRouteDecorator('PATCH');
 /**
  * Registers a `DELETE` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `DELETE` handler mapping.
  */
 export const Delete = createRouteDecorator('DELETE');
 /**
  * Registers an `OPTIONS` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers an `OPTIONS` handler mapping.
  */
 export const Options = createRouteDecorator('OPTIONS');
 /**
  * Registers a `HEAD` route handler.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers a `HEAD` handler mapping.
  */
 export const Head = createRouteDecorator('HEAD');
 /**
  * Registers a route handler that matches all HTTP methods.
  *
- * @param path Route path relative to the controller base path.
+ * @param path Relative route path; omission or `undefined` uses `''`, preserving the controller prefix.
  * @returns A method decorator that registers an all-method handler mapping.
  */
 export const All = createRouteDecorator('ALL');
@@ -447,6 +482,18 @@ export const FromCookie = createDtoFieldDecorator('cookie');
  * @returns A field decorator that marks the binding source as `body`.
  */
 export const FromBody = createDtoFieldDecorator('body');
+/**
+ * Binds a DTO field from portable multipart files.
+ *
+ * The binding always yields a readonly array when the request exposes a file
+ * collection, preserving adapter order and filtering by the optional field name.
+ * An absent file collection remains absent so `@Optional()` can opt out of the
+ * normal required-field error.
+ *
+ * @param key Optional multipart field-name filter. Defaults to the DTO field name.
+ * @returns A field decorator that marks the binding source as `files`.
+ */
+export const FromFiles = createDtoFieldDecorator('files');
 
 /**
  * Marks a DTO field binding as optional.

package/dist/dispatch/conditional-request-policy.d.ts

@@ -0,0 +1,67 @@
+import type { ConditionalRequestContext, ConditionalRequestOptions, FrameworkResponse, FrameworkResponseSendOptions, ResponseValidators } from '../types.js';
+/** Dispatcher outcome selected by RFC conditional request evaluation. */
+export type ConditionalRequestOutcome = 'not-modified' | 'precondition-failed' | 'proceed';
+/** Result of one dispatcher-owned conditional request evaluation. */
+export interface ConditionalRequestResult {
+    /** Whether dispatch continues, produces 304, or produces 412. */
+    readonly outcome: ConditionalRequestOutcome;
+    /** Current representation validators that must remain visible to adapters. */
+    readonly validators: ResponseValidators | undefined;
+}
+/**
+ * Parses one RFC HTTP-date value using the supplied RFC850 reference year.
+ *
+ * @internal This seam keeps two-digit RFC850 year tests deterministic.
+ * @param header Raw HTTP-date header value.
+ * @param referenceYear Year used to expand an RFC850 two-digit year.
+ * @returns Parsed UTC timestamp in milliseconds, or `undefined` for invalid input.
+ */
+export declare function parseHttpDate(header: string | undefined, referenceYear?: number): number | undefined;
+/**
+ * Determines whether `If-Range` permits applying a requested byte range.
+ *
+ * A missing field permits the range. Entity-tag validation requires an exact
+ * strong match; valid dates match when the selected representation has not
+ * changed since that instant. All malformed or unavailable validators fall
+ * back to the complete representation.
+ *
+ * @param request Incoming request whose `If-Range` field is evaluated.
+ * @param validators Selected response validators used to match `If-Range`.
+ * @returns `true` when `If-Range` is absent or matches the selected representation.
+ */
+export declare function matchesIfRange(request: ConditionalRequestContext['request'], validators: ResponseValidators | undefined): boolean;
+/**
+ * Resolve the RFC validator precedence result before the selected route executes.
+ *
+ * @param options Dispatcher conditional request configuration.
+ * @param context Matched request and route descriptor.
+ * @returns The dispatch outcome and validators to preserve in the response.
+ */
+export declare function resolveConditionalRequest(options: ConditionalRequestOptions, context: ConditionalRequestContext): Promise<ConditionalRequestResult>;
+/**
+ * Evaluates conditional request fields against an already selected representation.
+ *
+ * @param request Adapter-normalized request carrying conditional request fields.
+ * @param resolution Current representation existence and validators.
+ * @returns The selected conditional outcome and validators.
+ */
+export declare function resolveConditionalRequestRepresentation(request: ConditionalRequestContext['request'], resolution: Awaited<ReturnType<ConditionalRequestOptions['resolve']>>): ConditionalRequestResult;
+/**
+ * Applies selected response validators through the portable response facade.
+ *
+ * @param response Mutable adapter-normalized response.
+ * @param validators Current representation validators, when available.
+ * @returns Nothing. The response receives only validator metadata.
+ */
+export declare function applyResponseValidators(response: FrameworkResponse, validators: ResponseValidators | undefined): 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 options Optional adapter response-write controls.
+ * @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, options?: FrameworkResponseSendOptions): Promise<void>;
+//# sourceMappingURL=conditional-request-policy.d.ts.map

package/dist/dispatch/conditional-request-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conditional-request-policy.d.ts","sourceRoot":"","sources":["../../src/dispatch/conditional-request-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EAEzB,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,yEAAyE;AACzE,MAAM,MAAM,yBAAyB,GAAG,cAAc,GAAG,qBAAqB,GAAG,SAAS,CAAC;AAE3F,qEAAqE;AACrE,MAAM,WAAW,wBAAwB;IACvC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACrD;AA+LD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,SAA8B,GAC1C,MAAM,GAAG,SAAS,CA+DpB;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,UAAU,EAAE,kBAAkB,GAAG,SAAS,GACzC,OAAO,CAsBT;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAGnC;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,yBAAyB,CAAC,SAAS,CAAC,EAC7C,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,yBAAyB,CAAC,SAAS,CAAC,CAAC,CAAC,GACpE,wBAAwB,CAiD1B;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,kBAAkB,GAAG,SAAS,GACzC,IAAI,CAUN;AACD;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,OAAO,CAAC,yBAAyB,EAAE,SAAS,CAAC,EACtD,UAAU,EAAE,kBAAkB,GAAG,SAAS,EAC1C,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/dispatch/conditional-request-policy.js

@@ -0,0 +1,297 @@
+import { readFirstNonEmptyRequestHeaderValue } from '../header-helpers.js';
+
+/** Dispatcher outcome selected by RFC conditional request evaluation. */
+
+/** Result of one dispatcher-owned conditional request evaluation. */
+
+function formatEntityTag(tag) {
+  return `${tag.strength === 'weak' ? 'W/' : ''}"${tag.opaqueValue}"`;
+}
+const INVALID_ENTITY_TAG_LIST = {
+  kind: 'invalid'
+};
+const HTTP_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const HTTP_WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const HTTP_WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+function isOptionalWhitespace(character) {
+  return character === ' ' || character === '\t';
+}
+function isEntityTagCharacter(character) {
+  const code = character.charCodeAt(0);
+  return code === 0x21 || code >= 0x23 && code <= 0x7e || code >= 0x80 && code <= 0xff;
+}
+function isValidEntityTag(tag) {
+  return [...tag.opaqueValue].every(isEntityTagCharacter);
+}
+function parseEntityTagList(value) {
+  let position = 0;
+  const skipOptionalWhitespace = () => {
+    while (isOptionalWhitespace(value[position])) {
+      position += 1;
+    }
+  };
+  skipOptionalWhitespace();
+  if (value[position] === '*') {
+    position += 1;
+    skipOptionalWhitespace();
+    return position === value.length ? {
+      kind: 'wildcard'
+    } : INVALID_ENTITY_TAG_LIST;
+  }
+  const tags = [];
+  while (position < value.length) {
+    const weak = value.startsWith('W/', position);
+    if (weak) {
+      position += 2;
+    }
+    if (value[position] !== '"') {
+      return INVALID_ENTITY_TAG_LIST;
+    }
+    position += 1;
+    const opaqueStart = position;
+    while (position < value.length && value[position] !== '"') {
+      if (!isEntityTagCharacter(value[position])) {
+        return INVALID_ENTITY_TAG_LIST;
+      }
+      position += 1;
+    }
+    if (value[position] !== '"') {
+      return INVALID_ENTITY_TAG_LIST;
+    }
+    tags.push({
+      opaqueValue: value.slice(opaqueStart, position),
+      strength: weak ? 'weak' : 'strong'
+    });
+    position += 1;
+    skipOptionalWhitespace();
+    if (position === value.length) {
+      return {
+        kind: 'tags',
+        tags
+      };
+    }
+    if (value[position] !== ',') {
+      return INVALID_ENTITY_TAG_LIST;
+    }
+    position += 1;
+    skipOptionalWhitespace();
+    if (position === value.length) {
+      return INVALID_ENTITY_TAG_LIST;
+    }
+  }
+  return INVALID_ENTITY_TAG_LIST;
+}
+function matchesEntityTag(parsed, current, comparison, resourceExists) {
+  if (parsed.kind === 'wildcard') {
+    return resourceExists;
+  }
+  if (parsed.kind !== 'tags' || !current || !isValidEntityTag(current)) {
+    return false;
+  }
+  return parsed.tags.some(requested => requested.opaqueValue === current.opaqueValue && (comparison === 'weak' || requested.strength === 'strong' && current.strength === 'strong'));
+}
+function parseMonth(value) {
+  const month = HTTP_MONTHS.indexOf(value);
+  return month === -1 ? undefined : month;
+}
+function parseDecimal(value) {
+  if (!/^\d+$/.test(value)) {
+    return undefined;
+  }
+  return Number(value);
+}
+function parseClock(hour, minute, second) {
+  const parsedHour = parseDecimal(hour);
+  const parsedMinute = parseDecimal(minute);
+  const parsedSecond = parseDecimal(second);
+  if (parsedHour === undefined || parsedMinute === undefined || parsedSecond === undefined || parsedHour > 23 || parsedMinute > 59 || parsedSecond > 59) {
+    return undefined;
+  }
+  return {
+    hour: parsedHour,
+    minute: parsedMinute,
+    second: parsedSecond
+  };
+}
+function createHttpDateTimestamp(weekday, day, month, year, hour, minute, second, weekdayNames) {
+  const parsedDay = parseDecimal(day);
+  const parsedMonth = parseMonth(month);
+  const parsedYear = parseDecimal(year);
+  const clock = parseClock(hour, minute, second);
+  if (parsedDay === undefined || parsedMonth === undefined || parsedYear === undefined || clock === undefined || parsedDay < 1 || parsedDay > 31 || !weekdayNames.includes(weekday)) {
+    return undefined;
+  }
+  const date = new Date(0);
+  date.setUTCFullYear(parsedYear, parsedMonth, parsedDay);
+  date.setUTCHours(clock.hour, clock.minute, clock.second, 0);
+  if (date.getUTCFullYear() !== parsedYear || date.getUTCMonth() !== parsedMonth || date.getUTCDate() !== parsedDay || weekdayNames[date.getUTCDay()] !== weekday) {
+    return undefined;
+  }
+  return date.getTime();
+}
+
+/**
+ * Parses one RFC HTTP-date value using the supplied RFC850 reference year.
+ *
+ * @internal This seam keeps two-digit RFC850 year tests deterministic.
+ * @param header Raw HTTP-date header value.
+ * @param referenceYear Year used to expand an RFC850 two-digit year.
+ * @returns Parsed UTC timestamp in milliseconds, or `undefined` for invalid input.
+ */
+export function parseHttpDate(header, referenceYear = new Date().getUTCFullYear()) {
+  if (!header) {
+    return undefined;
+  }
+  const imfFixdate = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(header);
+  if (imfFixdate) {
+    return createHttpDateTimestamp(imfFixdate[1], imfFixdate[2], imfFixdate[3], imfFixdate[4], imfFixdate[5], imfFixdate[6], imfFixdate[7], HTTP_WEEKDAYS);
+  }
+  const rfc850 = /^(Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/.exec(header);
+  if (rfc850) {
+    const twoDigitYear = parseDecimal(rfc850[4]);
+    if (twoDigitYear === undefined) {
+      return undefined;
+    }
+    let year = Math.floor(referenceYear / 100) * 100 + twoDigitYear;
+    if (year > referenceYear + 50) {
+      year -= 100;
+    }
+    return createHttpDateTimestamp(rfc850[1], rfc850[2], rfc850[3], String(year), rfc850[5], rfc850[6], rfc850[7], HTTP_WEEKDAY_NAMES);
+  }
+  const asctime = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) ( {1}\d|\d{2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/.exec(header);
+  if (!asctime) {
+    return undefined;
+  }
+  return createHttpDateTimestamp(asctime[1], asctime[3].trim(), asctime[2], asctime[7], asctime[4], asctime[5], asctime[6], HTTP_WEEKDAYS);
+}
+function normalizeLastModified(lastModified) {
+  if (!lastModified || Number.isNaN(lastModified.getTime())) {
+    return undefined;
+  }
+  return Math.floor(lastModified.getTime() / 1_000) * 1_000;
+}
+function isSafeMethod(method) {
+  const normalized = method.toUpperCase();
+  return normalized === 'GET' || normalized === 'HEAD';
+}
+
+/**
+ * Determines whether `If-Range` permits applying a requested byte range.
+ *
+ * A missing field permits the range. Entity-tag validation requires an exact
+ * strong match; valid dates match when the selected representation has not
+ * changed since that instant. All malformed or unavailable validators fall
+ * back to the complete representation.
+ *
+ * @param request Incoming request whose `If-Range` field is evaluated.
+ * @param validators Selected response validators used to match `If-Range`.
+ * @returns `true` when `If-Range` is absent or matches the selected representation.
+ */
+export function matchesIfRange(request, validators) {
+  const ifRange = readFirstNonEmptyRequestHeaderValue(request, 'if-range');
+  if (!ifRange) {
+    return true;
+  }
+  const tags = parseEntityTagList(ifRange);
+  if (tags.kind === 'tags' && tags.tags.length === 1) {
+    const [tag] = tags.tags;
+    return tag?.strength === 'strong' && validators?.etag?.strength === 'strong' && tag.opaqueValue === validators.etag.opaqueValue;
+  }
+  const ifRangeDate = parseHttpDate(ifRange);
+  const lastModified = normalizeLastModified(validators?.lastModified);
+  return ifRangeDate !== undefined && lastModified !== undefined && lastModified <= ifRangeDate;
+}
+
+/**
+ * Resolve the RFC validator precedence result before the selected route executes.
+ *
+ * @param options Dispatcher conditional request configuration.
+ * @param context Matched request and route descriptor.
+ * @returns The dispatch outcome and validators to preserve in the response.
+ */
+export async function resolveConditionalRequest(options, context) {
+  const resolution = await options.resolve(context);
+  return resolveConditionalRequestRepresentation(context.request, resolution);
+}
+
+/**
+ * Evaluates conditional request fields against an already selected representation.
+ *
+ * @param request Adapter-normalized request carrying conditional request fields.
+ * @param resolution Current representation existence and validators.
+ * @returns The selected conditional outcome and validators.
+ */
+export function resolveConditionalRequestRepresentation(request, resolution) {
+  const validators = resolution.exists ? resolution.validators : undefined;
+  const ifMatch = parseEntityTagList(readFirstNonEmptyRequestHeaderValue(request, 'if-match') ?? '');
+  if (ifMatch.kind !== 'invalid') {
+    if (!matchesEntityTag(ifMatch, validators?.etag, 'strong', resolution.exists)) {
+      return {
+        outcome: 'precondition-failed',
+        validators
+      };
+    }
+  } else {
+    const lastModified = normalizeLastModified(validators?.lastModified);
+    const ifUnmodifiedSince = parseHttpDate(readFirstNonEmptyRequestHeaderValue(request, 'if-unmodified-since'));
+    if (ifUnmodifiedSince !== undefined && lastModified !== undefined && lastModified > ifUnmodifiedSince) {
+      return {
+        outcome: 'precondition-failed',
+        validators
+      };
+    }
+  }
+  const ifNoneMatch = parseEntityTagList(readFirstNonEmptyRequestHeaderValue(request, 'if-none-match') ?? '');
+  if (ifNoneMatch.kind !== 'invalid') {
+    if (matchesEntityTag(ifNoneMatch, validators?.etag, 'weak', resolution.exists)) {
+      return {
+        outcome: isSafeMethod(request.method) ? 'not-modified' : 'precondition-failed',
+        validators
+      };
+    }
+  } else {
+    const lastModified = normalizeLastModified(validators?.lastModified);
+    const ifModifiedSince = parseHttpDate(readFirstNonEmptyRequestHeaderValue(request, 'if-modified-since'));
+    if (isSafeMethod(request.method) && ifModifiedSince !== undefined && lastModified !== undefined && lastModified <= ifModifiedSince) {
+      return {
+        outcome: 'not-modified',
+        validators
+      };
+    }
+  }
+  return {
+    outcome: 'proceed',
+    validators
+  };
+}
+
+/**
+ * Applies selected response validators through the portable response facade.
+ *
+ * @param response Mutable adapter-normalized response.
+ * @param validators Current representation validators, when available.
+ * @returns Nothing. The response receives only validator metadata.
+ */
+export function applyResponseValidators(response, validators) {
+  if (validators?.etag && isValidEntityTag(validators.etag)) {
+    response.setHeader('ETag', formatEntityTag(validators.etag));
+  }
+  const lastModified = normalizeLastModified(validators?.lastModified);
+  if (lastModified !== undefined) {
+    response.setHeader('Last-Modified', new Date(lastModified).toUTCString());
+  }
+}
+/**
+ * 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 options Optional adapter response-write controls.
+ * @returns A promise that settles after the adapter accepts the bodyless response.
+ */
+export async function writeConditionalResponse(response, outcome, validators, options) {
+  applyResponseValidators(response, validators);
+  response.setStatus(outcome === 'not-modified' ? 304 : 412);
+  await response.send(undefined, options);
+}

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

@@ -1,3 +1,4 @@
+import { NotAcceptableException } from '../exceptions.js';
 import type { ContentNegotiationOptions, FrameworkRequest, HandlerDescriptor, ResponseFormatter } from '../types.js';
 /**
  * Describes the resolved content negotiation contract.
@@ -7,6 +8,13 @@ export interface ResolvedContentNegotiation {
     formatters: ResponseFormatter[];
     normalizedMediaTypes: string[];
 }
+/**
+ * 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 declare function isContentNegotiationNotAcceptableException(error: unknown): error is NotAcceptableException;
 /**
  * Resolve content negotiation.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"dispatch-content-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-content-negotiation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAQrB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AA2GD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CA+BhI;AAqCD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAC7C,iBAAiB,CA2CnB"}
+{"version":3,"file":"dispatch-content-negotiation.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatch-content-negotiation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AASrB;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,iBAAiB,CAAC;IACpC,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAsBD;;;;;GAKG;AACH,wBAAgB,0CAA0C,CACxD,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,sBAAsB,CAEjC;AA4ID;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,yBAAyB,GAAG,SAAS,GAAG,0BAA0B,GAAG,SAAS,CA+BhI;AAqCD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,EAAE,0BAA0B,GAC7C,iBAAiB,CA4DnB"}