@fluojs/http 1.1.2 → 3.0.0

package/dist/access-log-observer.d.ts

@@ -0,0 +1,77 @@
+import type { MaybePromise } from '@fluojs/core';
+import { type ResolveHttpConnectionOptions } from './connection.js';
+import type { RequestObserver } from './types.js';
+/** Structured lifecycle event emitted by {@link createAccessLogObserver}. */
+export type AccessLogEvent = AccessLogStartEvent | AccessLogErrorEvent | AccessLogFinishEvent;
+/** A non-terminal access log record emitted when dispatch begins. */
+export interface AccessLogStartEvent extends AccessLogRequestFields {
+    readonly event: 'http.access.start';
+}
+/** A non-terminal access log record emitted when request dispatch fails. */
+export interface AccessLogErrorEvent extends AccessLogRequestFields {
+    readonly errorName: string;
+    readonly event: 'http.access.error';
+}
+/** Terminal access log record emitted exactly once after request dispatch settles. */
+export interface AccessLogFinishEvent extends AccessLogRequestFields {
+    readonly durationMs: number;
+    readonly event: 'http.access.finish';
+    readonly outcome: AccessLogOutcome;
+    readonly responseHeaders?: Readonly<Record<string, string | readonly string[]>>;
+    readonly status?: number;
+}
+/** Common request fields carried by every structured access log event. */
+export interface AccessLogRequestFields {
+    readonly clientAddress?: string;
+    readonly matchedRoute?: string;
+    readonly method: string;
+    readonly path: string;
+    readonly requestHeaders?: Readonly<Record<string, string | readonly string[]>>;
+    readonly requestId?: string;
+}
+/** Terminal request result classified from the observed dispatch lifecycle. */
+export type AccessLogOutcome = 'aborted' | 'handled_error' | 'not_found' | 'success' | 'unhandled_error';
+/** Consumer-owned structured event sink used by an access log observer. */
+export interface AccessLogSink {
+    /**
+     * Receives one immutable access log lifecycle event.
+     *
+     * @param event Structured request lifecycle data with only allowlisted headers.
+     */
+    emit(event: AccessLogEvent): MaybePromise<void>;
+}
+/** Header policy applied independently to request and response access log fields. */
+export interface AccessLogHeaderOptions {
+    /** Header names to include. The default empty allowlist emits no headers. */
+    readonly allow?: readonly string[];
+    /** Additional header names whose values must be redacted when allowlisted. */
+    readonly redact?: readonly string[];
+}
+/** Options used to create a structured HTTP access log observer. */
+export interface CreateAccessLogObserverOptions {
+    /**
+     * Explicit connection trust policy used to include a client address.
+     *
+     * Omit this option to keep transport and forwarded identity out of access logs.
+     */
+    readonly clientIdentity?: ResolveHttpConnectionOptions;
+    /** Monotonic clock used to calculate terminal duration. Defaults to `performance.now()`. */
+    readonly clock?: () => number;
+    /** Allowlist and redaction policy for request and response headers. */
+    readonly headers?: AccessLogHeaderOptions;
+    /** Consumer-owned structured event destination. */
+    readonly sink: AccessLogSink;
+}
+/**
+ * Create a request observer that emits safe, structured access log lifecycle events.
+ *
+ * @param options Structured sink, optional client identity policy, header policy, and monotonic clock.
+ * @returns A request observer suitable for `CreateDispatcherOptions.observers`.
+ *
+ * @remarks
+ * The observer emits one start record, zero or more error records, and exactly one
+ * terminal finish record per admitted request. Header values are never emitted unless
+ * allowlisted, and authorization and cookie fields remain redacted even when allowed.
+ */
+export declare function createAccessLogObserver(options: CreateAccessLogObserverOptions): RequestObserver;
+//# sourceMappingURL=access-log-observer.d.ts.map

package/dist/access-log-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-log-observer.d.ts","sourceRoot":"","sources":["../src/access-log-observer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAyB,KAAK,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAE3F,OAAO,KAAK,EAIV,eAAe,EAChB,MAAM,YAAY,CAAC;AAWpB,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GACtB,mBAAmB,GACnB,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB,qEAAqE;AACrE,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;CACrC;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;CACrC;AAED,sFAAsF;AACtF,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,eAAe,GACf,WAAW,GACX,SAAS,GACT,iBAAiB,CAAC;AAEtB,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,qFAAqF;AACrF,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,oEAAoE;AACpE,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,4BAA4B,CAAC;IACvD,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAsGD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,eAAe,CAwEhG"}

package/dist/access-log-observer.js

@@ -0,0 +1,171 @@
+import { resolveHttpConnection } from './connection.js';
+import { isRequestContextAborted } from './dispatch/request-abort.js';
+const REDACTED_HEADER_VALUE = '[REDACTED]';
+const DEFAULT_REDACTED_HEADERS = new Set(['authorization', 'cookie', 'proxy-authorization', 'set-cookie', 'x-api-key']);
+
+/** Structured lifecycle event emitted by {@link createAccessLogObserver}. */
+
+/** A non-terminal access log record emitted when dispatch begins. */
+
+/** A non-terminal access log record emitted when request dispatch fails. */
+
+/** Terminal access log record emitted exactly once after request dispatch settles. */
+
+/** Common request fields carried by every structured access log event. */
+
+/** Terminal request result classified from the observed dispatch lifecycle. */
+
+/** Consumer-owned structured event sink used by an access log observer. */
+
+/** Header policy applied independently to request and response access log fields. */
+
+/** Options used to create a structured HTTP access log observer. */
+
+function normalizeHeaderName(name) {
+  return name.toLowerCase();
+}
+function createHeaderPolicy(options) {
+  const allowed = new Set((options?.allow ?? []).map(normalizeHeaderName));
+  const redacted = new Set(DEFAULT_REDACTED_HEADERS);
+  for (const header of options?.redact ?? []) {
+    redacted.add(normalizeHeaderName(header));
+  }
+  return {
+    allowed,
+    redacted
+  };
+}
+function collectAllowedHeaders(headers, policy) {
+  const selected = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const normalizedName = normalizeHeaderName(name);
+    if (value === undefined || !policy.allowed.has(normalizedName)) {
+      continue;
+    }
+    selected[normalizedName] = policy.redacted.has(normalizedName) ? REDACTED_HEADER_VALUE : Array.isArray(value) ? Object.freeze([...value]) : value;
+  }
+  return Object.keys(selected).length === 0 ? undefined : Object.freeze(selected);
+}
+function freezeAccessLogEvent(event) {
+  return Object.freeze(event);
+}
+function requestFields(state) {
+  return {
+    ...(state.clientAddress === undefined ? {} : {
+      clientAddress: state.clientAddress
+    }),
+    ...(state.matchedRoute === undefined ? {} : {
+      matchedRoute: state.matchedRoute
+    }),
+    method: state.request.method,
+    path: state.request.path,
+    ...(state.requestHeaders === undefined ? {} : {
+      requestHeaders: state.requestHeaders
+    }),
+    ...(state.requestId === undefined ? {} : {
+      requestId: state.requestId
+    })
+  };
+}
+function readErrorName(error) {
+  return error instanceof Error ? error.name : 'UnknownError';
+}
+function isRequestAborted(request) {
+  return request.signal?.aborted === true || request.isAborted?.() === true;
+}
+function resolveFinalStatus(response) {
+  return response.statusCode ?? (response.committed ? 200 : undefined);
+}
+function resolveOutcome(state, context, status) {
+  if (isRequestContextAborted(context.requestContext)) {
+    return 'aborted';
+  }
+  if (!state.hasError) {
+    return 'success';
+  }
+  if (state.matchedRoute === undefined && status === 404) {
+    return 'not_found';
+  }
+  return (status ?? 500) < 500 ? 'handled_error' : 'unhandled_error';
+}
+
+/**
+ * Create a request observer that emits safe, structured access log lifecycle events.
+ *
+ * @param options Structured sink, optional client identity policy, header policy, and monotonic clock.
+ * @returns A request observer suitable for `CreateDispatcherOptions.observers`.
+ *
+ * @remarks
+ * The observer emits one start record, zero or more error records, and exactly one
+ * terminal finish record per admitted request. Header values are never emitted unless
+ * allowlisted, and authorization and cookie fields remain redacted even when allowed.
+ */
+export function createAccessLogObserver(options) {
+  const headerPolicy = createHeaderPolicy(options.headers);
+  const clock = options.clock ?? performance.now.bind(performance);
+  const states = new WeakMap();
+  return {
+    onHandlerMatched(context) {
+      const state = states.get(context.requestContext);
+      if (state) {
+        state.matchedRoute = context.handler?.route.path;
+      }
+    },
+    async onRequestError(context, error) {
+      const state = states.get(context.requestContext);
+      if (!state) {
+        return;
+      }
+      state.hasError = true;
+      await options.sink.emit(freezeAccessLogEvent({
+        ...requestFields(state),
+        errorName: readErrorName(error),
+        event: 'http.access.error'
+      }));
+    },
+    async onRequestFinish(context) {
+      const state = states.get(context.requestContext);
+      if (!state) {
+        return;
+      }
+      states.delete(context.requestContext);
+      const responseHeaders = collectAllowedHeaders(context.requestContext.response.headers, headerPolicy);
+      const status = resolveFinalStatus(context.requestContext.response);
+      await options.sink.emit(freezeAccessLogEvent({
+        ...requestFields(state),
+        durationMs: Math.max(0, clock() - state.startedAt),
+        event: 'http.access.finish',
+        outcome: resolveOutcome(state, context, status),
+        ...(responseHeaders === undefined ? {} : {
+          responseHeaders
+        }),
+        ...(status === undefined ? {} : {
+          status
+        })
+      }));
+    },
+    async onRequestStart(context) {
+      const requestHeaders = collectAllowedHeaders(context.requestContext.request.headers, headerPolicy);
+      const clientAddress = options.clientIdentity === undefined ? undefined : resolveHttpConnection(context.requestContext.request, options.clientIdentity).clientAddress;
+      const state = {
+        ...(clientAddress === undefined ? {} : {
+          clientAddress
+        }),
+        hasError: false,
+        request: context.requestContext.request,
+        ...(requestHeaders === undefined ? {} : {
+          requestHeaders
+        }),
+        ...(context.requestContext.requestId === undefined ? {} : {
+          requestId: context.requestContext.requestId
+        }),
+        startedAt: clock()
+      };
+      states.set(context.requestContext, state);
+      await options.sink.emit(freezeAccessLogEvent({
+        ...requestFields(state),
+        event: 'http.access.start'
+      }));
+    }
+  };
+}

package/dist/adapter.d.ts

@@ -19,6 +19,7 @@ export interface UnsupportedHttpAdapterRealtimeCapability {
  * Describes the fetch style http adapter realtime capability contract.
  */
 export interface FetchStyleHttpAdapterRealtimeCapability {
+    bindingInstallation?: HttpAdapterRealtimeBindingInstallation;
     contract: 'raw-websocket-expansion';
     kind: 'fetch-style';
     mode: 'request-upgrade';
@@ -26,6 +27,13 @@ export interface FetchStyleHttpAdapterRealtimeCapability {
     support: 'contract-only' | 'supported';
     version: 1;
 }
+/**
+ * Versioned host installation seam for protocol-owned fetch-style realtime bindings.
+ */
+export interface HttpAdapterRealtimeBindingInstallation {
+    install(binding: unknown | undefined): void;
+    version: 1;
+}
 /**
  * Defines the http adapter realtime capability type.
  */
@@ -52,6 +60,7 @@ export declare function createUnsupportedHttpAdapterRealtimeCapability(reason: s
  * @returns The create fetch style http adapter realtime capability result.
  */
 export declare function createFetchStyleHttpAdapterRealtimeCapability(reason: string, options?: {
+    bindingInstallation?: Omit<HttpAdapterRealtimeBindingInstallation, 'version'>;
     support?: FetchStyleHttpAdapterRealtimeCapability['support'];
 }): FetchStyleHttpAdapterRealtimeCapability;
 /**

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,yCAAyC;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wCAAwC;IACvD,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uCAAuC;IACtD,QAAQ,EAAE,yBAAyB,CAAC;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,GAAG,WAAW,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GACrC,yCAAyC,GACzC,uCAAuC,GACvC,wCAAwC,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,+CAA+C,CAC7D,MAAM,EAAE,OAAO,GACd,yCAAyC,CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,8CAA8C,CAC5D,MAAM,EAAE,MAAM,GACb,wCAAwC,CAM1C;AAED;;;;;;GAMG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;CACzD,GACL,uCAAuC,CASzC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC;IAEtB,qBAAqB,CAAC,IAAI,6BAA6B,CAAC;IAExD;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,IAAI,sBAAsB,CAUzE"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,yCAAyC;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wCAAwC;IACvD,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uCAAuC;IACtD,mBAAmB,CAAC,EAAE,sCAAsC,CAAC;IAC7D,QAAQ,EAAE,yBAAyB,CAAC;IACpC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,GAAG,WAAW,CAAC;IACvC,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,sCAAsC;IACrD,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,MAAM,MAAM,6BAA6B,GACrC,yCAAyC,GACzC,uCAAuC,GACvC,wCAAwC,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,+CAA+C,CAC7D,MAAM,EAAE,OAAO,GACd,yCAAyC,CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,8CAA8C,CAC5D,MAAM,EAAE,MAAM,GACb,wCAAwC,CAM1C;AAED;;;;;;GAMG;AACH,wBAAgB,6CAA6C,CAC3D,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,mBAAmB,CAAC,EAAE,IAAI,CAAC,sCAAsC,EAAE,SAAS,CAAC,CAAC;IAC9E,OAAO,CAAC,EAAE,uCAAuC,CAAC,SAAS,CAAC,CAAC;CACzD,GACL,uCAAuC,CAqBzC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC;IAEtB,qBAAqB,CAAC,IAAI,6BAA6B,CAAC;IAExD;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,IAAI,sBAAsB,CAUzE"}

package/dist/adapter.js

@@ -10,6 +10,10 @@
  * Describes the fetch style http adapter realtime capability contract.
  */
 
+/**
+ * Versioned host installation seam for protocol-owned fetch-style realtime bindings.
+ */
+
 /**
  * Defines the http adapter realtime capability type.
  */
@@ -49,7 +53,7 @@ export function createUnsupportedHttpAdapterRealtimeCapability(reason) {
  * @returns The create fetch style http adapter realtime capability result.
  */
 export function createFetchStyleHttpAdapterRealtimeCapability(reason, options = {}) {
-  return {
+  const capability = {
     contract: 'raw-websocket-expansion',
     kind: 'fetch-style',
     mode: 'request-upgrade',
@@ -57,6 +61,16 @@ export function createFetchStyleHttpAdapterRealtimeCapability(reason, options =
     support: options.support ?? 'contract-only',
     version: 1
   };
+  if (options.bindingInstallation === undefined) {
+    return capability;
+  }
+  return {
+    ...capability,
+    bindingInstallation: {
+      install: options.bindingInstallation.install,
+      version: 1
+    }
+  };
 }
 
 /**

package/dist/adapters/binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAc,MAAM,cAAc,CAAC;AAI5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AAkDhI;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAyDD;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,GAAE,SAAS,aAAa,EAAO;IAEhE,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;CAuGjF"}
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAA8B,MAAM,cAAc,CAAC;AAI5E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AAkDhI;;GAEG;AACH,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAqED;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC9B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,GAAE,SAAS,aAAa,EAAO;IAEhE,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;CAuGjF"}

package/dist/adapters/binding.js

@@ -65,6 +65,12 @@ function isConverter(value) {
 function isConverterToken(value) {
   return typeof value === 'function' || typeof value === 'string' || typeof value === 'symbol';
 }
+function hasRegisteredConverter(container, token) {
+  if (typeof container !== 'object' || container === null || !('has' in container) || typeof container.has !== 'function') {
+    return undefined;
+  }
+  return container.has(token);
+}
 async function resolveConverter(value, context, cache) {
   if (!value) {
     return undefined;
@@ -79,24 +85,20 @@ async function resolveConverter(value, context, cache) {
   if (!isConverterToken(value)) {
     throw new InvariantError('Converter metadata must be a converter instance or DI token.');
   }
-  try {
-    const resolved = await context.requestContext.container.resolve(value);
-    if (!isConverter(resolved)) {
-      throw new InvariantError('Resolved converter token does not implement convert().');
+  if (typeof value === 'function' && hasRegisteredConverter(context.requestContext.container, value) === false) {
+    const instantiated = new value();
+    if (!isConverter(instantiated)) {
+      throw new InvariantError('Converter class must implement convert(value, target).');
     }
-    cache.set(value, resolved);
-    return resolved;
-  } catch (error) {
-    if (typeof value === 'function') {
-      const instantiated = new value();
-      if (!isConverter(instantiated)) {
-        throw new InvariantError('Converter class must implement convert(value, target).');
-      }
-      cache.set(value, instantiated);
-      return instantiated;
-    }
-    throw error;
+    cache.set(value, instantiated);
+    return instantiated;
+  }
+  const resolved = await context.requestContext.container.resolve(value);
+  if (!isConverter(resolved)) {
+    throw new InvariantError('Resolved converter token does not implement convert().');
   }
+  cache.set(value, resolved);
+  return resolved;
 }
 
 /**

package/dist/adapters/dto-binding-plan.d.ts

@@ -1,5 +1,5 @@
-import { type Constructor, type MetadataPropertyKey, type MetadataSource } from '@fluojs/core';
-import { type DtoFieldBindingMetadata } from '@fluojs/core/internal';
+import type { Constructor, MetadataPropertyKey, MetadataSource } from '@fluojs/core';
+import { type DtoFieldBindingMetadata } from '@fluojs/core/request-pipeline';
 import type { FrameworkRequest } from '../types.js';
 export interface CompiledDtoBindingPlanEntry {
     readonly converter?: DtoFieldBindingMetadata['converter'];

package/dist/adapters/dto-binding-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto-binding-plan.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-binding-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAKL,KAAK,uBAAuB,EAE7B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAcpD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACzD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,sBAAsB,CA4ClF"}
+{"version":3,"file":"dto-binding-plan.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-binding-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAKL,KAAK,uBAAuB,EAE7B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,KAAK,EAAE,gBAAgB,EAAwB,MAAM,aAAa,CAAC;AAoB1E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,2BAA2B,EAAE,CAAC;IACzD,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACzD;AAqDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,WAAW,GAAG,sBAAsB,CA4ClF"}

package/dist/adapters/dto-binding-plan.js

@@ -1,12 +1,19 @@
-import { getClassValidationRules, getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/internal';
+import { getClassValidationRules, getDtoBindingSchema, getDtoValidationSchema } from '@fluojs/core/request-pipeline';
+import { getRequestHeader } from '../header-helpers.js';
 function toFieldName(propertyKey) {
   return typeof propertyKey === 'string' ? propertyKey : String(propertyKey);
 }
 function resolveSourceKey(propertyKey, key) {
   return key ?? toFieldName(propertyKey);
 }
-function readHeader(request, key) {
-  return request.headers[key.toLowerCase()] ?? request.headers[key];
+function toPortableRequestFile(file) {
+  return {
+    buffer: file.buffer,
+    fieldname: file.fieldname,
+    mimetype: file.mimetype,
+    originalname: file.originalname,
+    size: file.size
+  };
 }
 const dtoBindingPlanCache = new WeakMap();
 function createSourceReader(source, sourceKey) {
@@ -16,11 +23,13 @@ function createSourceReader(source, sourceKey) {
     case 'query':
       return request => request.query[sourceKey];
     case 'header':
-      return request => readHeader(request, sourceKey);
+      return request => getRequestHeader(request, sourceKey);
     case 'cookie':
       return request => request.cookies[sourceKey];
     case 'body':
       return request => request.body?.[sourceKey];
+    case 'files':
+      return request => request.files?.filter(file => file.fieldname === sourceKey).map(toPortableRequestFile);
     default:
       return () => undefined;
   }

package/dist/adapters/dto-validation-adapter.d.ts

@@ -1,4 +1,5 @@
 import { type Constructor } from '@fluojs/core';
+import { type MaterializeOptions } from '@fluojs/validation';
 import type { Validator } from '../types.js';
 /**
  * Represents the http dto validation adapter.
@@ -7,6 +8,6 @@ export declare class HttpDtoValidationAdapter implements Validator {
     private readonly validator;
     private throwBadRequestForValidationError;
     validate(value: unknown, target: Constructor): Promise<void>;
-    materialize<T>(value: unknown, target: Constructor<T>): Promise<T>;
+    materialize<T>(value: unknown, target: Constructor<T>, options?: MaterializeOptions): Promise<T>;
 }
 //# sourceMappingURL=dto-validation-adapter.d.ts.map

package/dist/adapters/dto-validation-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dto-validation-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-validation-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAG9D;;GAEG;AACH,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMnC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWzE"}
+{"version":3,"file":"dto-validation-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/dto-validation-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAG9D;;GAEG;AACH,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMnC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;CAWvG"}

package/dist/adapters/dto-validation-adapter.js

@@ -27,9 +27,9 @@ export class HttpDtoValidationAdapter {
       throw error;
     }
   }
-  async materialize(value, target) {
+  async materialize(value, target, options) {
     try {
-      return await this.validator.materialize(value, target);
+      return await this.validator.materialize(value, target, options);
     } catch (error) {
       if (error instanceof DtoValidationError) {
         this.throwBadRequestForValidationError(error);

package/dist/byte-range-response.d.ts

@@ -0,0 +1,71 @@
+import type { FrameworkRequest, FrameworkResponse, ResponseValidators } from './types.js';
+type ByteRangeSource = ((() => ReadableStream<Uint8Array>) | ArrayBuffer | ReadableStream<Uint8Array> | Uint8Array);
+/**
+ * Input accepted by {@link createByteRangeResponse}.
+ *
+ * A streamed representation needs its exact full byte length so the response
+ * can evaluate `Range`, `If-Range`, and `HEAD` before consuming the stream.
+ * Pass a stream factory when `HEAD` must not construct the stream.
+ */
+export type ByteRangeResponseSource = ByteRangeSource;
+/** Options that describe a range-capable byte representation. */
+export interface ByteRangeResponseOptions {
+    /** Media type emitted when route metadata did not already choose one. */
+    readonly contentType?: string;
+    /** Exact representation size in bytes. Required for a `ReadableStream` source. */
+    readonly size?: number;
+}
+/** Internal byte-representation data shared by response writers. */
+export interface ByteRangeResponseEntry {
+    readonly contentType: string;
+    readonly size: number;
+    readonly source: ByteRangeResponseSource;
+}
+/** Inputs for writing a byte representation through a portable response facade. */
+export interface ByteRangeResponseWriteOptions {
+    readonly applySuccessResponseMetadata: () => void;
+    /** Whether adapter-owned dynamic compression may transform byte-backed responses. */
+    readonly compression?: boolean;
+    readonly entry: ByteRangeResponseEntry;
+    readonly request: FrameworkRequest;
+    readonly response: FrameworkResponse;
+    readonly validators: ResponseValidators | undefined;
+}
+/**
+ * Creates a response entry with RFC single-byte-range semantics.
+ *
+ * `Uint8Array` and `ArrayBuffer` values can be returned directly from a
+ * handler. Use this helper when returning a portable `ReadableStream`.
+ *
+ * @param source Byte representation or stream factory to expose with range support.
+ * @param options Optional content type and required stream size metadata.
+ * @returns A registered response entry that applies single-byte-range semantics.
+ */
+export declare function createByteRangeResponse(source: ByteRangeResponseSource, options?: ByteRangeResponseOptions): object;
+/**
+ * Returns whether a normal handler result is an automatically range-capable byte value.
+ *
+ * @param value Value to test for a byte representation.
+ * @returns `true` when the value is an `ArrayBuffer` or `Uint8Array`; otherwise `false`.
+ */
+export declare function isByteRangeByteSource(value: unknown): value is ArrayBuffer | Uint8Array;
+/**
+ * Determines whether an ordinary byte result requires byte-range processing.
+ *
+ * Explicit byte-range responses retain their full-response metadata behavior;
+ * this only guards automatic range handling for plain handler values.
+ *
+ * @param request Incoming request whose `Range` and `If-Range` fields are evaluated.
+ * @param validators Selected response validators used to evaluate `If-Range`.
+ * @returns `true` when the request has a valid byte range and `If-Range` permits it.
+ */
+export declare function shouldApplyByteRange(request: FrameworkRequest, validators: ResponseValidators | undefined): boolean;
+/**
+ * Writes one byte representation while preserving range and cancellation semantics.
+ *
+ * @param options Request, response, validators, and representation metadata.
+ * @returns A promise that settles after the representation completes or fails.
+ */
+export declare function writeByteRangeResponse(options: ByteRangeResponseWriteOptions): Promise<void>;
+export {};
+//# sourceMappingURL=byte-range-response.d.ts.map

package/dist/byte-range-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-range-response.d.ts","sourceRoot":"","sources":["../src/byte-range-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAA2B,kBAAkB,EAAE,MAAM,YAAY,CAAC;AASnH,KAAK,eAAe,GAAG,CACnB,CAAC,MAAM,cAAc,CAAC,UAAU,CAAC,CAAC,GAClC,WAAW,GACX,cAAc,CAAC,UAAU,CAAC,GAC1B,UAAU,CACb,CAAC;AAOF;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,eAAe,CAAC;AAEtD,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAED,mFAAmF;AACnF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,4BAA4B,EAAE,MAAM,IAAI,CAAC;IAClD,qFAAqF;IACrF,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,uBAAuB,EAC/B,OAAO,GAAE,wBAA6B,GACrC,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,GAAG,UAAU,CAEvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,kBAAkB,GAAG,SAAS,GACzC,OAAO,CAIT;AA4DD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAwGf"}