@fluojs/http 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,142 @@
+# @fluojs/http
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+라우트 메타데이터를 DTO 바인딩, 검증, 가드, 인터셉터, 응답 작성으로 이어지는 요청 파이프라인으로 바꾸는 HTTP 실행 레이어입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/http
+```
+
+## 사용 시점
+
+- `@Controller`, `@Get`, `@Post` 같은 데코레이터로 REST 스타일 엔드포인트를 선언할 때
+- `@FromBody`, `@FromPath`, `@FromQuery`로 요청 데이터를 DTO에 바인딩할 때
+- 가드, 인터셉터, 미들웨어를 예측 가능한 요청 라이프사이클에 얹고 싶을 때
+- 현재 요청을 `RequestContext`로 깊은 호출 스택에서 접근하고 싶을 때
+
+## 빠른 시작
+
+```ts
+import { Controller, FromBody, FromPath, Get, Post, RequestDto } from '@fluojs/http';
+import { IsString, MinLength } from '@fluojs/validation';
+
+class CreateUserDto {
+  @FromBody()
+  @IsString()
+  @MinLength(3)
+  name!: string;
+}
+
+@Controller('/users')
+export class UserController {
+  @Post('/')
+  @RequestDto(CreateUserDto)
+  create(input: CreateUserDto) {
+    return { id: '1', name: input.name };
+  }
+
+  @Get('/:id')
+  getById(@FromPath('id') id: string) {
+    return { id, name: 'John Doe' };
+  }
+}
+```
+
+### 라우트 경로 계약
+
+`@Controller()`, `@Get()`, `@Post()` 같은 HTTP 라우트 데코레이터는 다음만 허용합니다.
+
+- `/users`, `/healthz` 같은 literal 세그먼트
+- `/:id`, `/users/:userId/posts/:postId` 같은 full-segment path param
+
+트레일링 슬래시와 중복 슬래시는 라우트 매핑 단계에서 정규화되므로 `//users///:id/`는 `/users/:id`로 해석됩니다.
+
+라우트 데코레이터는 `*`, `?`, `/(.*)`, `user-:id`, `:id.json` 같은 wildcard, regex 유사 문법, mixed segment를 지원하지 않습니다. 와일드카드 매칭은 계속 `forRoutes('/users/*')` 같은 미들웨어 설정에서만 지원됩니다.
+
+## 주요 패턴
+
+### 가드와 인터셉터
+
+```ts
+import { Controller, Get, UseGuards, UseInterceptors } from '@fluojs/http';
+
+@Controller('/admin')
+@UseGuards(AdminGuard)
+@UseInterceptors(LoggingInterceptor)
+class AdminController {
+  @Get('/')
+  dashboard() {
+    return { data: 'secret' };
+  }
+}
+```
+
+### 비동기 요청 컨텍스트
+
+```ts
+import { getCurrentRequestContext } from '@fluojs/http';
+
+function someDeepHelper() {
+  const ctx = getCurrentRequestContext();
+  console.log(ctx?.requestId);
+}
+```
+
+### 프록시 뒤의 속도 제한
+
+`createRateLimitMiddleware(...)`는 기본적으로 raw socket `remoteAddress`만으로 클라이언트 식별자를 해석합니다. `Forwarded`, `X-Forwarded-For`, `X-Real-IP`를 신뢰하려면 해당 헤더를 신뢰 가능한 프록시가 덮어쓰는 환경에서만 `trustProxyHeaders: true`를 명시적으로 켜세요. 어댑터가 신뢰 가능한 프록시 체인도 raw socket 식별자도 제공하지 않는다면 공유 fallback 버킷에 의존하지 말고 명시적인 `keyResolver`를 설정하세요.
+
+### 서버 전송 이벤트
+
+```ts
+import { Get, SseResponse, type RequestContext } from '@fluojs/http';
+
+@Get('/events')
+stream(_input: undefined, ctx: RequestContext) {
+  const sse = new SseResponse(ctx);
+  sse.send({ message: 'hello' });
+  return sse;
+}
+```
+
+## 공개 API
+
+- **라우팅 데코레이터**: `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `All`
+- **바인딩 데코레이터**: `FromBody`, `FromQuery`, `FromPath`, `FromHeader`, `FromCookie`, `RequestDto`
+- **실행 데코레이터**: `UseGuards`, `UseInterceptors`, `HttpCode`, `Version`, `Header`, `Redirect`
+- **핵심 런타임 타입**: `RequestContext`, `FrameworkRequest`, `FrameworkResponse`, `SseResponse`
+- **예외**: `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `InternalServerErrorException`, `PayloadTooLargeException`
+- **헬퍼**: `createHandlerMapping`, `createDispatcher`, `createCorsMiddleware`, `createRateLimitMiddleware`, `getCurrentRequestContext`
+
+## 내부 서브경로 (`@fluojs/http/internal`)
+
+`./internal` 서브경로는 플랫폼 어댑터와 핵심 런타임에서 사용하는 저수준 유틸리티만 내보냅니다. 이들은 변경될 수 있으며 일반적인 애플리케이션 코드에서 사용해서는 안 됩니다.
+
+- `DefaultBinder`: 런타임 부트스트랩 경로에서 사용하는 기본 DTO/요청 바인더.
+- `resolveClientIdentity(request)`: 속도 제한과 런타임 통합에서 사용하는 보수적 클라이언트 식별 해석기.
+
+## 관련 패키지
+
+- `@fluojs/core`: 컨트롤러, 라우트, DTO 메타데이터를 저장합니다.
+- `@fluojs/validation`: HTTP 바인딩 이후 DTO를 검증합니다.
+- `@fluojs/runtime`: 부트스트랩 중 디스패처를 조립합니다.
+- `@fluojs/passport`: 같은 가드 체인 안에서 인증을 연결합니다.
+
+## 예제 소스
+
+- `examples/realworld-api/src/users/create-user.dto.ts`
+- `examples/auth-jwt-passport/src/auth/auth.controller.ts`
+- `packages/http/src/dispatch/dispatcher.test.ts`

package/README.md

@@ -0,0 +1,144 @@
+# @fluojs/http
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+The HTTP execution layer that turns route metadata into a request pipeline with binding, validation, guards, interceptors, and response writing.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/http
+```
+
+## When to Use
+
+Use this package when you need to:
+
+- define REST-style controllers with decorators such as `@Controller`, `@Get`, and `@Post`
+- bind request data into DTOs with `@FromBody`, `@FromPath`, `@FromQuery`, and related decorators
+- run guards, interceptors, and middleware in a predictable request lifecycle
+- access the active request through `RequestContext` without passing it through every function
+
+## Quick Start
+
+```ts
+import { Controller, FromBody, FromPath, Get, Post, RequestDto } from '@fluojs/http';
+import { IsString, MinLength } from '@fluojs/validation';
+
+class CreateUserDto {
+  @FromBody()
+  @IsString()
+  @MinLength(3)
+  name!: string;
+}
+
+@Controller('/users')
+export class UserController {
+  @Post('/')
+  @RequestDto(CreateUserDto)
+  create(input: CreateUserDto) {
+    return { id: '1', name: input.name };
+  }
+
+  @Get('/:id')
+  getById(@FromPath('id') id: string) {
+    return { id, name: 'John Doe' };
+  }
+}
+```
+
+### Route path contract
+
+HTTP route decorators such as `@Controller()`, `@Get()`, and `@Post()` accept only:
+
+- literal path segments like `/users` or `/healthz`
+- full-segment path params like `/:id` or `/users/:userId/posts/:postId`
+
+Trailing slashes and duplicate slashes are normalized during route mapping, so `//users///:id/` resolves to `/users/:id`.
+
+Route decorators do **not** support wildcard, regex-like, or mixed-segment syntax such as `*`, `?`, `/(.*)`, `user-:id`, or `:id.json`. Wildcard matching remains middleware-only via `forRoutes('/users/*')`.
+
+## Common Patterns
+
+### Guards and interceptors
+
+```ts
+import { Controller, Get, UseGuards, UseInterceptors } from '@fluojs/http';
+
+@Controller('/admin')
+@UseGuards(AdminGuard)
+@UseInterceptors(LoggingInterceptor)
+class AdminController {
+  @Get('/')
+  dashboard() {
+    return { data: 'secret' };
+  }
+}
+```
+
+### Async request context
+
+```ts
+import { getCurrentRequestContext } from '@fluojs/http';
+
+function someDeepHelper() {
+  const ctx = getCurrentRequestContext();
+  console.log(ctx?.requestId);
+}
+```
+
+### Rate limiting behind proxies
+
+`createRateLimitMiddleware(...)` resolves client identity from the raw socket `remoteAddress` by default. To trust `Forwarded`, `X-Forwarded-For`, or `X-Real-IP`, opt in with `trustProxyHeaders: true` only when your adapter sits behind a trusted proxy that overwrites those headers. If your adapter exposes neither a trusted proxy chain nor a raw socket identity, provide an explicit `keyResolver`.
+
+### Server-sent events
+
+```ts
+import { Get, SseResponse, type RequestContext } from '@fluojs/http';
+
+@Get('/events')
+stream(_input: undefined, ctx: RequestContext) {
+  const sse = new SseResponse(ctx);
+  sse.send({ message: 'hello' });
+  return sse;
+}
+```
+
+## Public API
+
+- **Routing decorators**: `Controller`, `Get`, `Post`, `Put`, `Patch`, `Delete`, `All`
+- **Binding decorators**: `FromBody`, `FromQuery`, `FromPath`, `FromHeader`, `FromCookie`, `RequestDto`
+- **Execution decorators**: `UseGuards`, `UseInterceptors`, `HttpCode`, `Version`, `Header`, `Redirect`
+- **Core runtime types**: `RequestContext`, `FrameworkRequest`, `FrameworkResponse`, `SseResponse`
+- **Exceptions**: `BadRequestException`, `UnauthorizedException`, `ForbiddenException`, `NotFoundException`, `InternalServerErrorException`, `PayloadTooLargeException`
+- **Helpers**: `createHandlerMapping`, `createDispatcher`, `createCorsMiddleware`, `createRateLimitMiddleware`, `getCurrentRequestContext`
+
+## Internal Subpath (`@fluojs/http/internal`)
+
+The `./internal` subpath exports only the low-level utilities used by platform adapters and the core runtime. These are subject to change and should not be used in typical application code.
+
+- `DefaultBinder`: Default DTO/request binder used by the runtime bootstrap path.
+- `resolveClientIdentity(request)`: Conservative client identity resolver used by rate limiting and other runtime integrations.
+
+## Related Packages
+
+- `@fluojs/core`: stores controller, route, and DTO metadata
+- `@fluojs/validation`: validates DTOs after HTTP binding
+- `@fluojs/runtime`: assembles the dispatcher during application bootstrap
+- `@fluojs/passport`: plugs auth guards into the same HTTP guard chain
+
+## Example Sources
+
+- `examples/realworld-api/src/users/create-user.dto.ts`
+- `examples/auth-jwt-passport/src/auth/auth.controller.ts`
+- `packages/http/src/dispatch/dispatcher.test.ts`

package/dist/adapter.d.ts

@@ -0,0 +1,58 @@
+import type { MaybePromise } from '@fluojs/core';
+import type { Dispatcher } from './types.js';
+export interface ServerBackedHttpAdapterRealtimeCapability {
+    kind: 'server-backed';
+    server: unknown;
+}
+export interface UnsupportedHttpAdapterRealtimeCapability {
+    kind: 'unsupported';
+    mode: 'no-op';
+    reason: string;
+}
+export interface FetchStyleHttpAdapterRealtimeCapability {
+    contract: 'raw-websocket-expansion';
+    kind: 'fetch-style';
+    mode: 'request-upgrade';
+    reason: string;
+    support: 'contract-only' | 'supported';
+    version: 1;
+}
+export type HttpAdapterRealtimeCapability = ServerBackedHttpAdapterRealtimeCapability | FetchStyleHttpAdapterRealtimeCapability | UnsupportedHttpAdapterRealtimeCapability;
+export declare function createServerBackedHttpAdapterRealtimeCapability(server: unknown): ServerBackedHttpAdapterRealtimeCapability;
+export declare function createUnsupportedHttpAdapterRealtimeCapability(reason: string): UnsupportedHttpAdapterRealtimeCapability;
+export declare function createFetchStyleHttpAdapterRealtimeCapability(reason: string, options?: {
+    support?: FetchStyleHttpAdapterRealtimeCapability['support'];
+}): FetchStyleHttpAdapterRealtimeCapability;
+/**
+ * Minimal HTTP adapter contract that binds the application lifecycle to a transport implementation.
+ */
+export interface HttpApplicationAdapter {
+    /**
+     * Returns the underlying transport server object when the adapter exposes one.
+     *
+     * @returns The transport-native server instance, or `undefined` when the adapter does not expose it.
+     */
+    getServer?(): unknown;
+    getRealtimeCapability?(): HttpAdapterRealtimeCapability;
+    /**
+     * Starts the adapter and binds request dispatching to the framework dispatcher.
+     *
+     * @param dispatcher Dispatcher created by `@fluojs/http` that executes the request pipeline.
+     * @returns A promise that resolves when the adapter is ready to accept requests.
+     */
+    listen(dispatcher: Dispatcher): MaybePromise<void>;
+    /**
+     * Stops the adapter and releases transport resources.
+     *
+     * @param signal Optional shutdown reason propagated by runtime lifecycle hooks.
+     * @returns A promise that resolves after transport shutdown is complete.
+     */
+    close(signal?: string): MaybePromise<void>;
+}
+/**
+ * Creates a no-op adapter that preserves lifecycle behavior without binding a real HTTP server.
+ *
+ * @returns A lifecycle-compatible adapter whose `listen()` and `close()` methods resolve immediately.
+ */
+export declare function createNoopHttpApplicationAdapter(): HttpApplicationAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +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,MAAM,WAAW,yCAAyC;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,wCAAwC;IACvD,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,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,MAAM,MAAM,6BAA6B,GACrC,yCAAyC,GACzC,uCAAuC,GACvC,wCAAwC,CAAC;AAE7C,wBAAgB,+CAA+C,CAC7D,MAAM,EAAE,OAAO,GACd,yCAAyC,CAK3C;AAED,wBAAgB,8CAA8C,CAC5D,MAAM,EAAE,MAAM,GACb,wCAAwC,CAM1C;AAED,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"}

package/dist/adapter.js

@@ -0,0 +1,42 @@
+export function createServerBackedHttpAdapterRealtimeCapability(server) {
+  return {
+    kind: 'server-backed',
+    server
+  };
+}
+export function createUnsupportedHttpAdapterRealtimeCapability(reason) {
+  return {
+    kind: 'unsupported',
+    mode: 'no-op',
+    reason
+  };
+}
+export function createFetchStyleHttpAdapterRealtimeCapability(reason, options = {}) {
+  return {
+    contract: 'raw-websocket-expansion',
+    kind: 'fetch-style',
+    mode: 'request-upgrade',
+    reason,
+    support: options.support ?? 'contract-only',
+    version: 1
+  };
+}
+
+/**
+ * Minimal HTTP adapter contract that binds the application lifecycle to a transport implementation.
+ */
+
+/**
+ * Creates a no-op adapter that preserves lifecycle behavior without binding a real HTTP server.
+ *
+ * @returns A lifecycle-compatible adapter whose `listen()` and `close()` methods resolve immediately.
+ */
+export function createNoopHttpApplicationAdapter() {
+  return {
+    async close() {},
+    getRealtimeCapability() {
+      return createUnsupportedHttpAdapterRealtimeCapability('No-op HTTP adapter does not expose a server-backed realtime capability.');
+    },
+    async listen() {}
+  };
+}

package/dist/adapters/binding.d.ts

@@ -0,0 +1,11 @@
+import { type Constructor } from '@fluojs/core';
+import type { ArgumentResolverContext, Binder, Converter, ConverterLike, ConverterTarget } from '../types.js';
+export declare class DefaultConverter implements Converter {
+    convert(value: unknown, _target: ConverterTarget): unknown;
+}
+export declare class DefaultBinder implements Binder {
+    private readonly converters;
+    constructor(converters?: readonly ConverterLike[]);
+    bind(dto: Constructor, context: ArgumentResolverContext): Promise<unknown>;
+}
+//# sourceMappingURL=binding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/adapters/binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAA6D,MAAM,cAAc,CAAC;AAK3H,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAoB,MAAM,aAAa,CAAC;AA4FhI,qBAAa,gBAAiB,YAAW,SAAS;IAChD,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO;CAG3D;AAyDD,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;CA0EjF"}

package/dist/adapters/binding.js

@@ -0,0 +1,185 @@
+import { InvariantError } from '@fluojs/core';
+import { getDtoBindingSchema } from '@fluojs/core/internal';
+import { BadRequestException } from '../exceptions.js';
+import { toInputErrorDetail } from '../input-error-detail.js';
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function isPlainObject(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+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 readSourceValue(request, source, propertyKey, key) {
+  const resolvedKey = resolveSourceKey(propertyKey, key);
+  switch (source) {
+    case 'path':
+      return request.params[resolvedKey];
+    case 'query':
+      return request.query[resolvedKey];
+    case 'header':
+      return readHeader(request, resolvedKey);
+    case 'cookie':
+      return request.cookies[resolvedKey];
+    case 'body':
+      {
+        if (!isPlainObject(request.body)) {
+          if (request.body !== undefined && request.body !== null) {
+            throw new BadRequestException('Request body must be a plain object.', {
+              details: [toInputErrorDetail({
+                code: 'INVALID_BODY',
+                message: 'Request body must be a plain object.',
+                source: 'body'
+              })]
+            });
+          }
+          return undefined;
+        }
+        return request.body[resolvedKey];
+      }
+  }
+}
+function validateBodyKeys(request, bodyKeys) {
+  if (request.body === undefined || request.body === null) {
+    return;
+  }
+  if (!isPlainObject(request.body)) {
+    throw new BadRequestException('Request body must be a plain object.', {
+      details: [toInputErrorDetail({
+        code: 'INVALID_BODY',
+        message: 'Request body must be a plain object.',
+        source: 'body'
+      })]
+    });
+  }
+  const details = [];
+  for (const key of Object.keys(request.body)) {
+    if (DANGEROUS_KEYS.has(key)) {
+      details.push(toInputErrorDetail({
+        code: 'DANGEROUS_KEY',
+        field: key,
+        message: `Dangerous body key ${key} is not allowed.`,
+        source: 'body'
+      }));
+      continue;
+    }
+    if (!bodyKeys.has(key)) {
+      details.push(toInputErrorDetail({
+        code: 'UNKNOWN_FIELD',
+        field: key,
+        message: `Unknown body field ${key}.`,
+        source: 'body'
+      }));
+    }
+  }
+  if (details.length > 0) {
+    throw new BadRequestException('Request body contains unsupported fields.', {
+      details
+    });
+  }
+}
+export class DefaultConverter {
+  convert(value, _target) {
+    return value;
+  }
+}
+function isConverter(value) {
+  return typeof value === 'object' && value !== null && 'convert' in value && typeof value.convert === 'function';
+}
+function isConverterToken(value) {
+  return typeof value === 'function' || typeof value === 'string' || typeof value === 'symbol';
+}
+async function resolveConverter(value, context, cache) {
+  if (!value) {
+    return undefined;
+  }
+  if (cache.has(value)) {
+    return cache.get(value);
+  }
+  if (isConverter(value)) {
+    cache.set(value, value);
+    return value;
+  }
+  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().');
+    }
+    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;
+  }
+}
+export class DefaultBinder {
+  constructor(converters = []) {
+    this.converters = converters;
+  }
+  async bind(dto, context) {
+    const schema = getDtoBindingSchema(dto);
+    const value = new dto();
+    const converterCache = new Map();
+    const bodyKeys = new Set(schema.filter(entry => entry.metadata.source === 'body').map(entry => resolveSourceKey(entry.propertyKey, entry.metadata.key)));
+    const globalConverters = (await Promise.all(this.converters.map(converter => resolveConverter(converter, context, converterCache)))).filter(converter => Boolean(converter));
+    validateBodyKeys(context.requestContext.request, bodyKeys);
+    const details = [];
+    for (const entry of schema) {
+      const rawValue = readSourceValue(context.requestContext.request, entry.metadata.source, entry.propertyKey, entry.metadata.key);
+      if (rawValue === undefined) {
+        if (entry.metadata.optional) {
+          continue;
+        }
+        details.push(toInputErrorDetail({
+          code: 'MISSING_FIELD',
+          field: toFieldName(entry.propertyKey),
+          message: `Missing required ${entry.metadata.source} field ${resolveSourceKey(entry.propertyKey, entry.metadata.key)}.`,
+          source: entry.metadata.source
+        }));
+        continue;
+      }
+      const target = {
+        dto,
+        handler: context.handler,
+        key: resolveSourceKey(entry.propertyKey, entry.metadata.key),
+        propertyKey: entry.propertyKey,
+        requestContext: context.requestContext,
+        source: entry.metadata.source
+      };
+      let convertedValue = rawValue;
+      for (const converter of globalConverters) {
+        convertedValue = await converter.convert(convertedValue, target);
+      }
+      const fieldConverter = await resolveConverter(entry.metadata.converter, context, converterCache);
+      if (fieldConverter) {
+        convertedValue = await fieldConverter.convert(convertedValue, target);
+      }
+      value[entry.propertyKey] = convertedValue;
+    }
+    if (details.length > 0) {
+      throw new BadRequestException('Request binding failed.', {
+        details
+      });
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,10 @@
+import { type Constructor } from '@fluojs/core';
+import type { Validator } from '../types.js';
+export declare class HttpDtoValidationAdapter implements Validator {
+    private readonly validator;
+    private throwBadRequestForValidationError;
+    private filterUnboundRequestDtoFields;
+    validate(value: unknown, target: Constructor): Promise<void>;
+    materialize<T>(value: unknown, target: Constructor<T>): Promise<T>;
+}
+//# sourceMappingURL=dto-validation-adapter.d.ts.map

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

@@ -0,0 +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;AAMhD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D,qBAAa,wBAAyB,YAAW,SAAS;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD,OAAO,CAAC,iCAAiC;IAMzC,OAAO,CAAC,6BAA6B;IAiB/B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAWzE"}

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

@@ -0,0 +1,46 @@
+import { getDtoBindingSchema } from '@fluojs/core/internal';
+import { DefaultValidator as BaseDefaultValidator, DtoValidationError } from '@fluojs/validation';
+import { BadRequestException } from '../exceptions.js';
+import { toInputErrorDetail } from '../input-error-detail.js';
+export class HttpDtoValidationAdapter {
+  validator = new BaseDefaultValidator();
+  throwBadRequestForValidationError(error) {
+    throw new BadRequestException(error.message, {
+      details: error.issues.map(issue => toInputErrorDetail(issue))
+    });
+  }
+  filterUnboundRequestDtoFields(value, target) {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    const source = value;
+    const filtered = Object.create(Object.getPrototypeOf(value));
+    for (const binding of getDtoBindingSchema(target)) {
+      if (Object.hasOwn(source, binding.propertyKey)) {
+        filtered[binding.propertyKey] = source[binding.propertyKey];
+      }
+    }
+    return filtered;
+  }
+  async validate(value, target) {
+    try {
+      const filteredValue = this.filterUnboundRequestDtoFields(value, target);
+      await this.validator.validate(filteredValue, target);
+    } catch (error) {
+      if (error instanceof DtoValidationError) {
+        this.throwBadRequestForValidationError(error);
+      }
+      throw error;
+    }
+  }
+  async materialize(value, target) {
+    try {
+      return await this.validator.materialize(value, target);
+    } catch (error) {
+      if (error instanceof DtoValidationError) {
+        this.throwBadRequestForValidationError(error);
+      }
+      throw error;
+    }
+  }
+}