@fluojs/http 1.1.2 → 3.0.0

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

@@ -1,5 +1,31 @@
+import { appendVaryHeader } from '../header-helpers.js';
+import { applyResponseValidators } from './conditional-request-policy.js';
 import { resolveContentNegotiation, selectResponseFormatter } from './dispatch-content-negotiation.js';
 import { writeErrorResponse } from './dispatch-error-policy.js';
+import { applyRouteHeaders } from './dispatch-response-metadata.js';
+import { createByteRangeResponse, isByteRangeByteSource, shouldApplyByteRange } from '../byte-range-response.js';
+import { FRAMEWORK_RESPONSE_VALUE_FINALIZER, FRAMEWORK_RESPONSE_WRITER } from './response-integration.js';
+const BINARY_CONTENT_TYPE = 'application/octet-stream';
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+const TEXT_CONTENT_TYPE = 'text/plain; charset=utf-8';
+
+/** Selected representation metadata shared by success and conditional response writers. */
+
+/**
+ * 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 function resolveResponsePolicy(handler, request, contentNegotiation) {
+  const formatter = contentNegotiation ? selectResponseFormatter(handler, request, contentNegotiation) : undefined;
+  return {
+    formatter,
+    variesByAccept: formatter !== undefined
+  };
+}
 function resolveDefaultSuccessStatus(handler, value) {
   switch (handler.route.method) {
     case 'POST':
@@ -23,6 +49,20 @@ function isSimpleJsonResponseBody(value) {
   }
   return typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;
 }
+function readFrameworkResponseWriter(value) {
+  if (typeof value !== 'object' || value === null) {
+    return undefined;
+  }
+  const writer = Reflect.get(value, FRAMEWORK_RESPONSE_WRITER);
+  return typeof writer === 'function' ? writer : undefined;
+}
+function readFrameworkResponseValueFinalizer(requestContext) {
+  const finalizer = requestContext.metadata[FRAMEWORK_RESPONSE_VALUE_FINALIZER];
+  if (typeof finalizer !== 'function') {
+    return undefined;
+  }
+  return context => Reflect.apply(finalizer, undefined, [context]);
+}
 function isResponseBodyForbidden(status) {
   return status === 204 || status === 205 || status === 304;
 }
@@ -39,6 +79,33 @@ function readHeader(headers, name) {
 function isJsonContentType(contentType) {
   return contentType.toLowerCase().includes('application/json') || contentType.toLowerCase().endsWith('+json');
 }
+function applySuccessResponseMetadata(context) {
+  const {
+    formatter,
+    handler,
+    response,
+    value
+  } = context;
+  applyRouteHeaders(handler, response);
+  if (formatter) {
+    response.setHeader('Content-Type', formatter.mediaType);
+  }
+  if (handler.route.successStatus !== undefined) {
+    response.setStatus(handler.route.successStatus);
+  } else if (response.statusSet !== true) {
+    response.setStatus(resolveDefaultSuccessStatus(handler, value));
+  }
+}
+function applyImplicitHeadContentType(response, value) {
+  if (readHeader(response.headers, 'content-type') !== undefined || value === undefined) {
+    return;
+  }
+  if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+    response.setHeader('Content-Type', BINARY_CONTENT_TYPE);
+    return;
+  }
+  response.setHeader('Content-Type', typeof value === 'string' ? TEXT_CONTENT_TYPE : JSON_CONTENT_TYPE);
+}
 
 /**
  * Write success response.
@@ -47,10 +114,13 @@ function isJsonContentType(contentType) {
  * @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 function writeSuccessResponse(handler, request, response, value, contentNegotiation) {
+export async function writeSuccessResponse(handler, request, response, value, contentNegotiation, requestContext, validators, conditionalOutcome) {
   if (response.committed) {
     return;
   }
@@ -59,29 +129,90 @@ export function writeSuccessResponse(handler, request, response, value, contentN
       url,
       statusCode = 302
     } = handler.route.redirect;
+    applyResponseValidators(response, validators);
     response.redirect(statusCode, url);
     return;
   }
-  const formatter = contentNegotiation ? selectResponseFormatter(handler, request, contentNegotiation) : undefined;
-
-  // Write route-level headers only after successful formatter negotiation so
-  // that a negotiation failure does not leak success-only headers onto the
-  // error response.
-  for (const header of handler.route.headers ?? []) {
-    response.setHeader(header.name, header.value);
+  const responseValueFinalizer = readFrameworkResponseValueFinalizer(requestContext);
+  const responseValue = responseValueFinalizer ? await responseValueFinalizer({
+    handler,
+    request,
+    requestContext,
+    response,
+    value
+  }) : value;
+  const writerValue = readFrameworkResponseWriter(responseValue) ? responseValue : isByteRangeByteSource(responseValue) && shouldApplyByteRange(request, validators) ? createByteRangeResponse(responseValue) : undefined;
+  const responseWriter = writerValue ? readFrameworkResponseWriter(writerValue) : undefined;
+  if (responseWriter) {
+    applyResponseValidators(response, validators);
+    let successResponseMetadataApplied = false;
+    const applyWriterSuccessResponseMetadata = () => {
+      if (successResponseMetadataApplied) {
+        return;
+      }
+      successResponseMetadataApplied = true;
+      applySuccessResponseMetadata({
+        formatter: undefined,
+        handler,
+        response,
+        value: responseValue
+      });
+      applyResponseValidators(response, validators);
+    };
+    return responseWriter({
+      applySuccessResponseMetadata: applyWriterSuccessResponseMetadata,
+      handler,
+      request,
+      requestContext,
+      response,
+      validators,
+      value: writerValue
+    });
   }
-  if (formatter) {
-    response.setHeader('Content-Type', formatter.mediaType);
+  const responsePolicy = resolveResponsePolicy(handler, request, contentNegotiation);
+  const {
+    formatter
+  } = responsePolicy;
+  if (conditionalOutcome !== undefined) {
+    applyRouteHeaders(handler, response);
+    return writeConditionalResponse(response, conditionalOutcome, validators, responsePolicy);
   }
-  if (handler.route.successStatus !== undefined) {
-    response.setStatus(handler.route.successStatus);
-  } else if (response.statusSet !== true) {
-    response.setStatus(resolveDefaultSuccessStatus(handler, value));
+  applySuccessResponseMetadata({
+    formatter,
+    handler,
+    response,
+    value: responseValue
+  });
+  if (responsePolicy.variesByAccept) {
+    appendVaryHeader(response, 'Accept');
   }
-  if (!formatter && hasSimpleJsonResponseWriter(response) && canUseSimpleJsonFastPath(response, value)) {
-    return response.sendSimpleJson(value);
+  applyResponseValidators(response, validators);
+  if (request.method.toUpperCase() === 'HEAD') {
+    applyImplicitHeadContentType(response, responseValue);
+    return response.send(undefined);
   }
-  const responseBody = formatter ? formatter.format(value) : value;
+  if (!formatter && hasSimpleJsonResponseWriter(response) && canUseSimpleJsonFastPath(response, responseValue)) {
+    return response.sendSimpleJson(responseValue);
+  }
+  const responseBody = formatter ? formatter.format(responseValue) : responseValue;
   return response.send(responseBody);
 }
+
+/**
+ * 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 async function writeConditionalResponse(response, outcome, validators, responsePolicy) {
+  applyResponseValidators(response, validators);
+  if (responsePolicy.variesByAccept) {
+    appendVaryHeader(response, 'Accept');
+  }
+  response.setStatus(outcome === 'not-modified' ? 304 : 412);
+  await response.send(undefined);
+}
 export { resolveContentNegotiation, writeErrorResponse };

package/dist/dispatch/dispatcher.d.ts

@@ -1,5 +1,5 @@
 import type { Container } from '@fluojs/di';
-import type { Binder, ContentNegotiationOptions, ConverterLike, Dispatcher, DispatcherLogger, FrameworkRequest, FrameworkResponse, HandlerMapping, InterceptorLike, MiddlewareLike, RequestObserverLike } from '../types.js';
+import type { Binder, ConditionalRequestOptions, ContentNegotiationOptions, ConverterLike, Dispatcher, DispatcherLogger, FrameworkRequest, FrameworkResponse, HandlerMapping, HttpErrorRepresentationOptions, InterceptorLike, MiddlewareLike, RequestObserverLike } from '../types.js';
 import { type FastPathStats } from './fast-path/index.js';
 export type { FastPathEligibility, FastPathStats } from './fast-path/index.js';
 export { FAST_PATH_ELIGIBILITY_SYMBOL, FAST_PATH_STATS_SYMBOL } from './fast-path/index.js';
@@ -13,6 +13,8 @@ export interface CreateDispatcherOptions {
     binder?: Binder;
     /** Optional content negotiation configuration. */
     contentNegotiation?: ContentNegotiationOptions;
+    /** Optional dispatcher-owned HTTP conditional request policy. */
+    conditionalRequest?: ConditionalRequestOptions;
     /** Mapping of routes to their respective handlers. */
     handlerMapping: HandlerMapping;
     /** Global interceptors applied to all matched handlers. */
@@ -23,6 +25,8 @@ export interface CreateDispatcherOptions {
     fastPathDebugHeaders?: boolean;
     /** Optional global error handler. */
     onError?: ErrorHandler;
+    /** Optional application-owned HTML representation for HTTP-classified errors. */
+    errorRepresentation?: HttpErrorRepresentationOptions;
     /** Request-scope optimization hints supplied by runtime bootstrap. */
     requestScope?: {
         /** Global DTO converters used by the default binder. */

package/dist/dispatch/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,YAAY,CAAC;AAQnE,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAKjB,cAAc,EAEd,eAAe,EAEf,cAAc,EAId,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAKrB,OAAO,EAKL,KAAK,aAAa,EAOnB,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpK,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sDAAsD;IACtD,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE;QACb,wDAAwD;QACxD,oBAAoB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;KACjD,CAAC;IACF,qDAAqD;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA08BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAuF7E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAE5F;AAED,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,YAAY,CAAC;AAUnE,OAAO,KAAK,EACV,MAAM,EACN,yBAAyB,EACzB,yBAAyB,EACzB,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EAKjB,cAAc,EAEd,8BAA8B,EAC9B,eAAe,EAEf,cAAc,EAKd,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AAgBrB,OAAO,EAKL,KAAK,aAAa,EAEnB,MAAM,sBAAsB,CAAC;AAK9B,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,gEAAgE;AAChE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpK,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,iDAAiD;IACjD,aAAa,CAAC,EAAE,cAAc,EAAE,CAAC;IACjC,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C,sDAAsD;IACtD,cAAc,EAAE,cAAc,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAClC,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qCAAqC;IACrC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,8BAA8B,CAAC;IACrD,sEAAsE;IACtE,YAAY,CAAC,EAAE;QACb,wDAAwD;QACxD,oBAAoB,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;KACjD,CAAC;IACF,qDAAqD;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,qDAAqD;IACrD,aAAa,EAAE,SAAS,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgjCD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU,CAiG7E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAE5F;AAED,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC"}