@fluojs/platform-fastify 1.0.9 → 2.0.0

package/README.ko.md

@@ -28,7 +28,7 @@ npm install @fluojs/platform-fastify
 
 ## 런타임 요구 사항
 
-`@fluojs/platform-fastify`는 Node.js HTTP adapter이며 `engines.node >=20.0.0`을 선언합니다. 이 패키지가 HTTP 서버를 소유하는 로컬 개발, CI, 컨테이너, 프로덕션 호스트는 Node.js 20 이상에서 실행해야 합니다. 비 Node 런타임에서는 이 Node 전용 adapter를 import하지 말고 `@fluojs/platform-bun`, `@fluojs/platform-deno`, 또는 `@fluojs/platform-cloudflare-workers`를 사용하세요.
+`@fluojs/platform-fastify`는 Node.js HTTP adapter이며 `engines.node >=24.0.0 <27`을 선언합니다. Listener-level RFC `QUERY` 요청이 Fastify wildcard fallback과 fluo dispatch에 도달하도록 이 패키지가 HTTP 서버를 소유하는 로컬 개발, CI, 컨테이너, 프로덕션 호스트는 이 정확한 범위의 Node.js에서 실행해야 합니다. Node 24 미만과 Node 27 이상은 제외됩니다. 비 Node 런타임에서는 이 Node 전용 adapter를 import하지 말고 `@fluojs/platform-bun`, `@fluojs/platform-deno`, 또는 `@fluojs/platform-cloudflare-workers`를 사용하세요.
 
 어댑터는 Fastify 기반 Node `http` 또는 `https` listener를 소유합니다. 포트, 인증서 material, hostname 같은 process-specific value는 애플리케이션 경계에 두고, 최종 option만 adapter에 명시적으로 전달하세요.
 
@@ -50,10 +50,18 @@ const app = await fluoFactory.create(AppModule, {
 await app.listen();
 ```
 
-`createFastifyAdapter()`는 기본 port로 `3000`을 사용하며 `process.env.PORT`를 읽지 않습니다. `port`, `maxBodySize`, `retryDelayMs`, `retryLimit`, `shutdownTimeoutMs` 같은 잘못된 explicit numeric option은 adapter setup 중 throw됩니다. `maxBodySize`와 `shutdownTimeoutMs`는 음수가 아닌 정수 byte/time limit이므로 `0`도 유효합니다. `maxBodySize: 0`은 빈 request body만 허용하고, `shutdownTimeoutMs: 0`은 다음 timer turn에 Fastify close가 timeout되도록 요청합니다.
+`createFastifyAdapter()`는 기본 port로 `3000`을 사용하며 `process.env.PORT`를 읽지 않습니다. `port`, `maxBodySize`, `retryDelayMs`, `retryLimit`, `shutdownTimeoutMs` 같은 잘못된 explicit numeric option은 adapter setup 중 throw됩니다. `maxBodySize`와 `shutdownTimeoutMs`는 음수가 아닌 정수 byte/time limit이므로 `0`도 유효합니다. `maxBodySize: 0`은 빈 request body만 허용하고, `shutdownTimeoutMs: 0`은 Fastify close를 즉시 시작합니다. `0`은 대기 시간만 제한하므로 close가 아직 settle되지 않았다면 대기는 다음 timer turn에 timeout될 수 있지만, 기반 Fastify close와 cleanup은 계속 진행됩니다.
 
 ## 주요 패턴
 
+### Early Hints
+
+Fastify response는 `reply.raw`를 통해 optional `context.response.earlyHints` capability를 노출합니다. `103` 하나마다 `write(...)`를 await하면 독립적으로 설정된 final response보다 먼저 여러 informational response가 전송됩니다. Early field는 Fastify final header를 채우거나 Fluo facade를 committed 상태로 만들지 않습니다. Late/native failure와 client disconnect는 결정적으로 reject됩니다.
+
+### 바이트 범위와 캐시 검증
+
+Fastify는 공유 `@fluojs/http` 단일 byte-range 및 `If-Range` contract를 보존합니다. Conditional-request 평가가 cache validator를 선택한 뒤 유효한 `Range: bytes=` 요청은 portable `206` identity-byte response를 만들고, `If-Range`는 선택된 validator를 재사용합니다. Malformed 또는 multi-range field는 전체 response를 유지하고 충족 불가능한 range는 body 없는 `416`을 만들며, `HEAD`는 stream을 소비하지 않고 GET metadata를 반영합니다.
+
 ### HTTPS/TLS 시작
 Fastify 프로세스가 TLS를 직접 소유할 때는 Node.js `https.ServerOptions`를 `createFastifyAdapter(...)`, `bootstrapFastifyApplication(...)`, 또는 `runFastifyApplication(...)`의 `https` option으로 전달하세요. Adapter는 Fastify를 HTTPS listener로 시작하며 startup log는 `https://host:port` URL을 보고합니다.
 
@@ -74,10 +82,10 @@ await app.listen();
 
 Adapter를 만들기 전에 certificate는 애플리케이션 configuration 또는 secret-management boundary에서 로드하세요. 이 패키지는 certificate file, `process.env`, `PORT`를 직접 읽지 않습니다. Load balancer, ingress, API gateway가 TLS를 종료한다면 `https`를 설정하지 말고 해당 infrastructure 뒤에서 Fastify adapter를 일반 HTTP로 실행하세요.
 
-`bootstrapFastifyApplication(...)`과 `runFastifyApplication(...)`도 같은 `https`, `host`, `port` option을 받습니다.
+`bootstrapFastifyApplication(...)`과 `runFastifyApplication(...)`도 같은 `https`, `host`, `port` option을 받습니다. `runFastifyApplication(...)`은 resolve되기 전에 listening을 시작하고 shutdown registration을 설치한 다음 실행 중인 application shell을 반환합니다.
 
 ```typescript
-await runFastifyApplication(AppModule, {
+const app = await runFastifyApplication(AppModule, {
   host: '127.0.0.1',
   https: {
     cert: tlsCertificate,
@@ -104,6 +112,14 @@ const adapter = createFastifyAdapter(
 );
 ```
 
+### 네이티브 Raw Request 및 Response 객체
+
+기본적으로 `RequestContext`의 이식 가능한 `FrameworkRequest` 및 `FrameworkResponse` field와 method를 사용하세요. `context.request`로 request 데이터를 읽고 `context.response`로 status, header, redirect, body를 작성하면 controller가 fluo HTTP adapter 간에 이식성을 유지합니다.
+
+Fastify의 공유 `raw` field는 의도적으로 비대칭입니다. `context.request.raw`는 기반 Node.js `IncomingMessage`이고 `context.response.raw`는 Fastify의 `FastifyReply`입니다. Request raw 객체는 `FastifyRequest`가 아니며 response raw 객체는 Node.js `ServerResponse`가 아닙니다.
+
+NestJS `@Req()` 또는 `@Res()` 코드를 마이그레이션할 때 이 `unknown` field에 안전하지 않은 cast를 의존하지 마세요. 이 adapter는 현재 typed Fastify-native request accessor를 공개하지 않습니다. 이식 가능한 framework 작업으로 충족할 수 없는 native Fastify 요구 사항이 있으면 shared controller 코드를 cast에 결합하지 말고 계약을 보존하는 typed accessor를 요청하세요.
+
 ### 서버 기반 실시간 통신 (Real-Time)
 Fastify는 `@fluojs/websockets`가 기본 Node.js HTTP 서버에 직접 연결될 수 있도록 `server-backed` 기능을 제공합니다.
 
@@ -165,11 +181,32 @@ await bootstrapFastifyApplication(AppModule, {
 });
 ```
 
+### 네이티브 Fastify 설정
+기본적으로는 이식 가능한 fluo 미들웨어를 사용하세요. 마이그레이션에서 Fastify 전용 플러그인, hook 또는 인스턴스 customisation을 유지해야 할 때는 construction-time `configureFastify` seam으로 설정합니다.
+
+```typescript
+const adapter = createFastifyAdapter({
+  configureFastify: async (fastify) => {
+    fastify.addHook('onRequest', async (request, reply) => {
+      reply.header('x-native-request-id', request.id);
+    });
+    fastify.setReplySerializer((payload) => JSON.stringify(payload) ?? '');
+  },
+  port: 3000,
+});
+```
+
+`configureFastify`는 어댑터가 생성하는 각 Fastify 인스턴스마다 한 번 실행되며, fluo가 multipart, raw-body, native-route, wildcard-route 처리를 등록하기 전에 완료됩니다. `bootstrapFastifyApplication(...)`과 `runFastifyApplication(...)`도 같은 옵션을 받습니다. 설정이 throw 또는 reject되면 해당 `listen()` 호출은 시작되지 않습니다. 실패한 인스턴스에는 설정을 다시 적용하지 않으며, 성공적으로 `close()`한 뒤의 다음 `listen()`은 새 인스턴스를 한 번 설정합니다. 이 seam에서 `setReplySerializer(...)`를 호출할 수는 있지만, 어댑터는 Fastify에 넘기기 전에 fluo response payload를 직렬화하므로 instance serializer는 fluo response를 customisation하지 않습니다.
+
+어댑터는 routing, CORS, logging, multipart와 raw-body 동작, response semantics, shutdown의 소유권을 계속 가집니다. Bootstrap 뒤 Fastify 인스턴스를 보관하거나 변경하지 말고, 기존 Fastify 인스턴스를 adoption하거나 이 hook을 native-route bypass로 사용하지 마세요. 이식 가능한 request 동작은 fluo `middleware`로 옮기세요.
+
 ### 네이티브 라우트 등록과 안전한 폴백
 fluo 라우트 메타데이터를 Fastify 경로로 그대로 옮길 수 있는 경우, 어댑터는 모든 요청을 단일 와일드카드 라우트로 보내는 대신 명시적 `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` route에 Fastify 네이티브 per-route 핸들러를 등록합니다. 의미 보존이 가능한 unversioned route에서는 Fastify가 미리 고른 descriptor와 params를 공유 fluo dispatcher에 전달하므로 duplicate route matching을 건너뛰면서도 middleware, guards, interceptors, observers, SSE, multipart, raw body, streaming, error handling 의미론은 그대로 유지됩니다.
 
 여러 라우트가 같은 method와 정규화된 param shape를 공유하는 경우(예: `/:id` 와 `/:slug`), `@All(...)`을 사용하는 경우, non-URI versioning에 의존하는 경우, 또는 duplicate slash / trailing slash 변형으로 들어온 경우에는 어댑터가 해당 요청을 의도적으로 와일드카드 fallback 경로에 남겨 둡니다. 이렇게 해서 Fastify 등록 단계에서 부팅 실패가 나거나 fluo의 등록 순서 기반 매칭 의미론이 좁아지지 않도록 보장합니다. app middleware가 native handoff 이후 framework request의 method 또는 path를 rewrite하면 dispatcher는 stale handoff를 무시하고 rewrite된 요청을 다시 매칭합니다.
 
+`QUERY`, `PURGE` 같은 검증된 custom method도 native fluo route handoff를 받지 않고 wildcard fallback dispatch에 남습니다. Fastify wildcard route가 요청을 받으려면 method 이름을 미리 알아야 하므로 adapter는 descriptor의 custom method를 body-bearing Fastify method로 등록하되 route selection은 계속 fluo에 맡깁니다. `ALL`은 wire method로 등록하지 않으며 `CONNECT`는 일반 controller routing conformance 범위 밖에 유지됩니다.
+
 어댑터는 매칭되지 않은 경로와 이식성에 민감한 경우, 그리고 공유 body/materialization 경로를 보존해야 하는 multipart request를 위해 와일드카드 fallback 라우트를 계속 유지하며, Fastify의 trailing slash / duplicate slash 정규화를 켜서 네이티브 선택 경로도 fluo의 문서화된 route path 계약과 맞추어 동작하도록 합니다. CORS 처리는 Fastify 플러그인이 아니라 fluo의 공유 middleware 경로가 계속 소유하고, `OPTIONS` 같은 미지원 메서드는 fluo route가 명시적으로 소유하지 않는 한 fallback dispatcher 경로로 흐릅니다.
 
 동시에 호출된 `listen()`은 하나의 startup promise를 공유하고 첫 번째 호출의 dispatcher를 유지합니다. Startup 이후 반복되는 `listen()` 호출은 live listener와 dispatcher를 변경하지 않는 no-op입니다. `close()`가 진행 중일 때 호출된 `listen()`은 shutdown이 settle될 때까지 기다린 뒤 새 listener를 시작하며, 해당 listener가 준비된 후에만 resolve됩니다. 바쁜 port 때문에 startup retry 중인 상태에서 `close()`를 호출하면 retry loop를 취소하고 해당 작업이 settle될 때까지 기다린 뒤 shutdown 완료를 보고하므로, caller가 shutdown이 끝났다고 믿은 뒤 닫힌 adapter가 나중에 bind되는 일이 없습니다. Adapter instance를 close 이후 다시 listen하면 native route handler가 traffic을 처리하기 전에 dispatcher descriptor를 새로 반영하므로 request handoff metadata가 이전 application graph를 가리키지 않습니다.
@@ -187,15 +224,15 @@ fluo의 Fastify 어댑터는 높은 동시성 시나리오에서 raw Node.js 어
 
 ## 적합성 커버리지
 
-`packages/platform-fastify/src/adapter.test.ts`는 문서화된 Fastify 어댑터 계약을 위한 package-local regression target입니다. 이 파일은 공유 `createHttpAdapterPortabilityHarness(...)` 검사를 실행하여 malformed cookie 보존, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body 제외, multipart total-size 기본값, SSE framing, response stream drain settlement, host 및 HTTPS startup logging, shutdown signal listener cleanup을 확인합니다.
+`packages/platform-fastify/src/adapter.test.ts`는 문서화된 Fastify 어댑터 계약을 위한 package-local regression target입니다. 이 파일은 공유 `createHttpAdapterPortabilityHarness(...)` 검사를 실행하여 conditional request, single-byte range 및 `If-Range`, custom `QUERY`/extension-method fallback, malformed cookie 보존, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body 제외, multipart total-size 기본값, SSE framing, response stream drain settlement, host 및 HTTPS startup logging, shutdown signal listener cleanup을 확인합니다.
 
-같은 파일은 Fastify 전용 native route registration과 wildcard fallback, duplicate shape route fallback, concurrent/repeated `listen()` idempotency, shutdown 중 startup retry cancellation, adapter reuse 시 native descriptor refresh, explicit `OPTIONS` route ownership, middleware/guard/interceptor/observer ordering, CORS ownership, global prefix behavior, malformed cookie preservation, response serialization parity, raw-body pre-parsing behavior, zero-valued body/shutdown limit, 대소문자 구분 없는 multipart detection, multipart limit handling도 함께 다룹니다. startup, routing, adapter portability behavior를 변경할 때는 README 예제 포인터를 이 테스트 파일 및 custom adapter book chapter와 맞추어 유지하세요.
+같은 파일은 Fastify 전용 native route registration과 wildcard fallback, duplicate shape route fallback, concurrent/repeated `listen()` idempotency, shutdown 중 startup retry cancellation, adapter reuse 시 native descriptor refresh, explicit `OPTIONS` route ownership, middleware/guard/interceptor/observer ordering, CORS ownership, global prefix behavior, malformed cookie preservation, response serialization parity, raw-body pre-parsing behavior, zero-valued body/shutdown limit, 기반 Fastify close를 계속 in-flight 상태로 두는 close 대기 timeout, 대소문자 구분 없는 multipart detection, multipart limit handling도 함께 다룹니다. startup, routing, adapter portability behavior를 변경할 때는 README 예제 포인터를 이 테스트 파일 및 custom adapter book chapter와 맞추어 유지하세요.
 
 ## 공개 API 개요
 
 - `createFastifyAdapter(options, multipartOptions?)`: Fastify 어댑터를 위한 권장 팩토리입니다. `options`에는 `host`, `port`, Node.js `https` server option 같은 transport startup knob이 포함됩니다. 선택적 두 번째 인자는 직접 어댑터를 생성할 때 `maxFileSize`, `maxFiles`, `maxTotalSize` 같은 multipart 제한을 설정합니다.
 - `bootstrapFastifyApplication(module, options)`: 암시적 리스닝 없이 수행하는 고급 부트스트랩입니다. Host가 bind 전에 앱을 구성해야 할 때 `https`를 포함한 같은 Fastify startup option을 받습니다.
-- `runFastifyApplication(module, options)`: 생명주기 관리를 포함한 빠른 시작 헬퍼이며 같은 `https` startup surface를 제공합니다. timeout/실패 시에는 해당 상태를 로그와 `process.exitCode`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
+- `runFastifyApplication(module, options)`: Application을 bootstrap하고 listening을 시작한 뒤 shutdown registration을 설치하며, 같은 `https` startup surface를 사용하는 실행 중인 shell을 반환합니다. Signal 기반 shutdown timeout/실패 시에는 해당 상태를 로그와 `process.exitCode`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
 - `isFastifyMultipartTooLargeError(error)`: Fastify error shape 전반에서 multipart limit error를 감지합니다.
 - `FastifyHttpApplicationAdapter`: 핵심 어댑터 구현 클래스입니다.
 - Option type: `FastifyAdapterOptions`, `BootstrapFastifyApplicationOptions`, `RunFastifyApplicationOptions`, `CorsInput`, `FastifyApplicationSignal`.
@@ -207,7 +244,14 @@ fluo의 Fastify 어댑터는 높은 동시성 시나리오에서 raw Node.js 어
 - **로깅 (Logging)**: 로그 스트림 중복을 방지하기 위해 Fastify의 네이티브 로거가 비활성화됩니다. `runFastifyApplication`과 `bootstrapFastifyApplication`은 framework console logger를 기본으로 선택하며, host나 test가 주입된 `ApplicationLogger`를 사용해야 할 때 `logger`를 받습니다.
 - **글로벌 접두사 (Global Prefix)**: 내부 경로 또는 헬스 체크 엔드포인트에 접두사가 붙지 않도록 `globalPrefixExclude`를 적절히 설정하세요.
 - **Malformed Cookie**: 잘못된 cookie header는 request 실패로 이어지지 않고 보존됩니다.
-- **HTTPS 시작**: Fastify 프로세스가 TLS를 소유한다면 Node.js 20 이상에서 adapter `https` option 아래에 certificate material을 전달하세요. Infrastructure가 TLS를 종료한다면 해당 경계 뒤에서 adapter를 일반 HTTP로 유지하세요.
+- **HTTPS 시작**: Fastify 프로세스가 TLS를 소유한다면 Node.js `>=24.0.0 <27`에서 adapter `https` option 아래에 certificate material을 전달하세요. Infrastructure가 TLS를 종료한다면 해당 경계 뒤에서 adapter를 일반 HTTP로 유지하세요.
+- **시작 및 종료 실패**: startup과 Fastify `onClose`가 모두 실패하면, `cause`를 읽고 쓰고 다시 읽을 수 있는 경우에만 caller는 원래 startup rejection과 `cause`의 close failure를 받습니다. 그 외에는 caller가 startup rejection을 `errors[0]`, close failure를 `errors[1]`로 갖는 startup-first `AggregateError`를 받습니다.
+
+## Multipart 스트리밍
+
+Fastify를 bootstrap할 때 `multipart: { strategy: 'stream' }`을 설정하면 multipart part가 `RequestContext.request.body`의 `AsyncIterable`로 노출됩니다. Fastify는 iterator를 미리 읽거나 버퍼링하지 않으며, file part를 소비할 때만 바이트를 가져옵니다. 이 mode에서는 file part가 `request.files`의 `UploadedFile` 값으로 materialize되지 않습니다. 버퍼링 multipart parsing은 기본값이며 하나의 request body에서 stream 소비와 함께 사용할 수 없습니다.
+
+Runtime route dispatch는 route를 위해 만든 iterator를 소유하며 handler가 끝난 뒤 자동으로 `return()`을 호출해 active source를 cancel하고 release합니다. Standalone `parseMultipartStream(...)` consumer는 이 책임을 직접 집니다. iterator를 끝까지 소비하거나 일찍 끝낼 때 `return()`을 호출하세요.
 
 ## 관련 패키지
 

package/README.md

@@ -28,7 +28,7 @@ npm install @fluojs/platform-fastify
 
 ## Runtime Requirements
 
-`@fluojs/platform-fastify` is a Node.js HTTP adapter and declares `engines.node >=20.0.0`. Run local development, CI, containers, and production hosts on Node.js 20 or newer when this package owns the HTTP server. Use `@fluojs/platform-bun`, `@fluojs/platform-deno`, or `@fluojs/platform-cloudflare-workers` for non-Node runtimes instead of importing this Node-specific adapter.
+`@fluojs/platform-fastify` is a Node.js HTTP adapter and declares `engines.node >=24.0.0 <27`. Run local development, CI, containers, and production hosts on a version in that exact range when this package owns the HTTP server so listener-level RFC `QUERY` requests reach Fastify wildcard fallback and fluo dispatch. Node versions below 24 and Node 27+ are excluded. Use `@fluojs/platform-bun`, `@fluojs/platform-deno`, or `@fluojs/platform-cloudflare-workers` for non-Node runtimes instead of importing this Node-specific adapter.
 
 The adapter owns a Fastify-backed Node `http` or `https` listener. Keep process-specific values such as ports, certificate material, and hostnames at the application boundary, then pass the final options into the adapter explicitly.
 
@@ -50,10 +50,18 @@ const app = await fluoFactory.create(AppModule, {
 await app.listen();
 ```
 
-`createFastifyAdapter()` defaults to port `3000` and does not read `process.env.PORT`; invalid explicit numeric options such as `port`, `maxBodySize`, `retryDelayMs`, `retryLimit`, and `shutdownTimeoutMs` throw during adapter setup. `maxBodySize` and `shutdownTimeoutMs` are non-negative integer byte/time limits, so `0` is valid: `maxBodySize: 0` allows only empty request bodies, and `shutdownTimeoutMs: 0` asks Fastify to close on the next timer turn.
+`createFastifyAdapter()` defaults to port `3000` and does not read `process.env.PORT`; invalid explicit numeric options such as `port`, `maxBodySize`, `retryDelayMs`, `retryLimit`, and `shutdownTimeoutMs` throw during adapter setup. `maxBodySize` and `shutdownTimeoutMs` are non-negative integer byte/time limits, so `0` is valid: `maxBodySize: 0` allows only empty request bodies, and `shutdownTimeoutMs: 0` starts Fastify close immediately. The zero value bounds only the wait: if close has not settled, the wait may time out on the next timer turn while the underlying Fastify close and cleanup continue.
 
 ## Common Patterns
 
+### Early Hints
+
+Fastify responses expose the optional `context.response.earlyHints` capability through `reply.raw`. Await one `write(...)` per `103`; multiple informational responses precede the independently configured final response. Early fields never populate Fastify final headers or mark the Fluo facade committed. Late/native failures and client disconnects reject deterministically.
+
+### Byte Ranges and Cache Validation
+
+Fastify preserves the shared `@fluojs/http` single-byte-range and `If-Range` contract. After conditional-request evaluation selects cache validators, a valid `Range: bytes=` request yields the portable `206` identity-byte response; `If-Range` reuses those selected validators, while malformed or multi-range fields retain the full response and an unsatisfiable range yields bodyless `416`. `HEAD` mirrors GET metadata without consuming a stream.
+
 ### HTTPS/TLS Startup
 When the Fastify process owns TLS directly, pass Node.js `https.ServerOptions` through the `https` option on `createFastifyAdapter(...)`, `bootstrapFastifyApplication(...)`, or `runFastifyApplication(...)`. The adapter starts Fastify with an HTTPS listener, and startup logs report the `https://host:port` URL.
 
@@ -74,10 +82,10 @@ await app.listen();
 
 Load certificates from your application configuration or secret-management boundary before constructing the adapter; the package does not read certificate files, `process.env`, or `PORT` by itself. If a load balancer, ingress, or API gateway terminates TLS, leave `https` unset and run the Fastify adapter as plain HTTP behind that infrastructure.
 
-`bootstrapFastifyApplication(...)` and `runFastifyApplication(...)` accept the same `https`, `host`, and `port` options:
+`bootstrapFastifyApplication(...)` and `runFastifyApplication(...)` accept the same `https`, `host`, and `port` options. `runFastifyApplication(...)` starts listening before it resolves, installs shutdown registration, and returns the running application shell:
 
 ```typescript
-await runFastifyApplication(AppModule, {
+const app = await runFastifyApplication(AppModule, {
   host: '127.0.0.1',
   https: {
     cert: tlsCertificate,
@@ -104,6 +112,14 @@ const adapter = createFastifyAdapter(
 );
 ```
 
+### Native Raw Request and Response Objects
+
+Use the portable `FrameworkRequest` and `FrameworkResponse` fields and methods on `RequestContext` by default. Read request data through `context.request`, then write status, headers, redirects, and bodies through `context.response`; this keeps controllers portable across fluo HTTP adapters.
+
+Fastify's shared `raw` fields are intentionally asymmetric: `context.request.raw` is the underlying Node.js `IncomingMessage`, while `context.response.raw` is Fastify's `FastifyReply`. The request raw object is not a `FastifyRequest`, and the response raw object is not a Node.js `ServerResponse`.
+
+Do not rely on unsafe casts of those `unknown` fields when migrating NestJS `@Req()` or `@Res()` code. This adapter does not currently expose a typed Fastify-native request accessor. If a portable framework operation cannot satisfy a native Fastify requirement, request a contract-preserving typed accessor rather than coupling shared controller code to a cast.
+
 ### Server-Backed Real-Time
 Fastify provides a `server-backed` capability that allows `@fluojs/websockets` to attach directly to the underlying Node.js HTTP server.
 
@@ -165,11 +181,32 @@ await bootstrapFastifyApplication(AppModule, {
 });
 ```
 
+### Native Fastify Configuration
+Use portable fluo middleware by default. When a migration must retain a Fastify-native plugin, hook, or instance customization, configure it through the construction-time `configureFastify` seam:
+
+```typescript
+const adapter = createFastifyAdapter({
+  configureFastify: async (fastify) => {
+    fastify.addHook('onRequest', async (request, reply) => {
+      reply.header('x-native-request-id', request.id);
+    });
+    fastify.setReplySerializer((payload) => JSON.stringify(payload) ?? '');
+  },
+  port: 3000,
+});
+```
+
+`configureFastify` runs once for each Fastify instance that the adapter creates, before fluo registers its multipart, raw-body, native-route, and wildcard-route handling. `bootstrapFastifyApplication(...)` and `runFastifyApplication(...)` accept the same option. A thrown or rejected configuration prevents that `listen()` call from starting; the failed instance is not configured again, while a later `listen()` after a successful `close()` configures the newly created instance once. Although this seam can call `setReplySerializer(...)`, the adapter serializes fluo response payloads before handing them to Fastify, so an instance serializer does not customize fluo responses.
+
+The adapter continues to own routing, CORS, logging, multipart and raw-body behavior, response semantics, and shutdown. Do not retain or mutate the Fastify instance after bootstrap, adopt an existing Fastify instance, or use this hook as a native-route bypass. Move portable request behavior to fluo `middleware` instead.
+
 ### Native Route Registration with Safe Fallback
 When fluo route metadata can be translated directly, the adapter registers Fastify-native per-route handlers for explicit `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD` routes instead of sending every request through a single wildcard route. For semantically safe unversioned routes, those native handlers hand a pre-matched descriptor and params to the shared fluo dispatcher so duplicate route matching is skipped without changing framework-owned guards, interceptors, observers, SSE, multipart, raw body, streaming, or error handling.
 
 When multiple routes share the same method and normalized param shape (for example `/:id` and `/:slug`), use `@All(...)`, depend on non-URI versioning, or arrive through duplicate-slash / trailing-slash variants, the adapter intentionally leaves those requests on the wildcard fallback path so Fastify registration cannot boot-fail or narrow fluo's matching semantics. If app middleware rewrites the framework request method or path after a native handoff was attached, the dispatcher ignores that stale handoff and rematches the rewritten request.
 
+Validated custom methods such as `QUERY` and `PURGE` also stay on wildcard fallback dispatch instead of receiving native fluo route handoffs. Fastify must know a method name before its wildcard route can accept that request, so the adapter registers descriptor custom methods with Fastify as body-bearing methods while still leaving route selection to fluo. `ALL` is never registered as a wire method, and `CONNECT` remains outside ordinary controller routing conformance.
+
 The adapter keeps a wildcard fallback route for unmatched paths and portability-sensitive cases, including multipart requests that must preserve the shared body/materialization path, and enables Fastify trailing-slash / duplicate-slash normalization so native selection stays aligned with fluo's documented route path contract. CORS handling remains owned by fluo's shared middleware path rather than Fastify plugins, and unsupported methods such as `OPTIONS` continue through the fallback dispatcher path unless a fluo route explicitly owns them.
 
 Concurrent `listen()` calls share one startup promise and preserve the dispatcher from the first call. After startup, repeated `listen()` calls are no-ops that keep the live listener and dispatcher unchanged. A `listen()` call made while `close()` is in flight waits for shutdown to settle, starts a fresh listener, and resolves only after that listener is ready. Calling `close()` while startup is retrying a busy port cancels the retry loop and waits for it to settle before reporting shutdown completion, so a closed adapter cannot bind later after the caller believes shutdown finished. If an adapter instance is listened again after close, native route handlers refresh their dispatcher descriptors before serving traffic so request handoff metadata cannot point at a previous application graph.
@@ -187,15 +224,15 @@ fluo's Fastify adapter significantly outperforms the raw Node.js adapter in high
 
 ## Conformance Coverage
 
-`packages/platform-fastify/src/adapter.test.ts` is the package-local regression target for the documented Fastify adapter contract. It runs the shared `createHttpAdapterPortabilityHarness(...)` checks for malformed cookie preservation, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body exclusion, multipart total-size defaults, SSE framing, response stream drain settlement, host and HTTPS startup logging, and shutdown signal listener cleanup.
+`packages/platform-fastify/src/adapter.test.ts` is the package-local regression target for the documented Fastify adapter contract. It runs the shared `createHttpAdapterPortabilityHarness(...)` checks for conditional requests, single-byte ranges and `If-Range`, custom `QUERY`/extension-method fallback, malformed cookie preservation, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body exclusion, multipart total-size defaults, SSE framing, response stream drain settlement, host and HTTPS startup logging, and shutdown signal listener cleanup.
 
-The same file also covers Fastify-specific native route registration with wildcard fallback, duplicate shape route fallback, concurrent and repeated `listen()` idempotency, startup retry cancellation during shutdown, native descriptor refresh on adapter reuse, explicit `OPTIONS` route ownership, middleware/guard/interceptor/observer ordering, CORS ownership, global prefix behavior, malformed cookie preservation, response serialization parity, raw-body pre-parsing behavior, zero-valued body/shutdown limits, case-insensitive multipart detection, and multipart limit handling. Keep README example pointers aligned with that test file and the custom adapter book chapter when changing startup, routing, or adapter portability behavior.
+The same file also covers Fastify-specific native route registration with wildcard fallback, duplicate shape route fallback, concurrent and repeated `listen()` idempotency, startup retry cancellation during shutdown, native descriptor refresh on adapter reuse, explicit `OPTIONS` route ownership, middleware/guard/interceptor/observer ordering, CORS ownership, global prefix behavior, malformed cookie preservation, response serialization parity, raw-body pre-parsing behavior, zero-valued body/shutdown limits, close wait timeouts that leave the underlying Fastify close in flight, case-insensitive multipart detection, and multipart limit handling. Keep README example pointers aligned with that test file and the custom adapter book chapter when changing startup, routing, or adapter portability behavior.
 
 ## Public API Overview
 
 - `createFastifyAdapter(options, multipartOptions?)`: Recommended factory for the Fastify adapter. `options` includes transport startup knobs such as `host`, `port`, and Node.js `https` server options. The optional second argument configures multipart limits such as `maxFileSize`, `maxFiles`, and `maxTotalSize` for direct adapter construction.
 - `bootstrapFastifyApplication(module, options)`: advanced bootstrap without implicit listening; accepts the same Fastify startup options, including `https`, when the host wants to construct the app before binding it.
-- `runFastifyApplication(module, options)`: Quick-start helper with lifecycle management and the same `https` startup surface. On timeout/failure it reports the condition through logging and `process.exitCode`, while leaving final process termination to the surrounding host.
+- `runFastifyApplication(module, options)`: Bootstraps the application, starts listening, installs shutdown registration, and returns the running shell with the same `https` startup surface. On signal-driven shutdown timeout/failure it reports the condition through logging and `process.exitCode`, while leaving final process termination to the surrounding host.
 - `isFastifyMultipartTooLargeError(error)`: Detects multipart limit errors across Fastify error shapes.
 - `FastifyHttpApplicationAdapter`: The core adapter implementation.
 - Option types: `FastifyAdapterOptions`, `BootstrapFastifyApplicationOptions`, `RunFastifyApplicationOptions`, `CorsInput`, `FastifyApplicationSignal`.
@@ -207,7 +244,14 @@ The same file also covers Fastify-specific native route registration with wildca
 - **Logging**: The native Fastify logger is disabled to prevent duplicate log streams. `runFastifyApplication` and `bootstrapFastifyApplication` select the framework console logger by default and accept `logger` for hosts or tests that need an injected `ApplicationLogger`.
 - **Global Prefix**: Use `globalPrefixExclude` to prevent the prefix from being applied to internal routes or health check endpoints.
 - **Malformed Cookies**: Malformed cookie headers are preserved rather than failing the request.
-- **HTTPS startup**: Use Node.js 20+ and pass certificate material under the adapter `https` option when the Fastify process owns TLS. If TLS is terminated by infrastructure, keep the adapter on plain HTTP behind that boundary.
+- **HTTPS startup**: Use Node.js `>=24.0.0 <27` and pass certificate material under the adapter `https` option when the Fastify process owns TLS. If TLS is terminated by infrastructure, keep the adapter on plain HTTP behind that boundary.
+- **Startup and shutdown failures**: When startup and Fastify `onClose` both fail, callers receive the original startup rejection with the close failure in `cause` only when `cause` can be read, written, and read back. Otherwise, callers receive a startup-first `AggregateError` whose `errors[0]` is the startup rejection and whose `errors[1]` is the close failure.
+
+## Multipart streaming
+
+Set `multipart: { strategy: 'stream' }` when bootstrapping Fastify to expose multipart parts through `RequestContext.request.body` as an `AsyncIterable`. Fastify creates the iterator without pre-reading or buffering it; consuming a file part pulls its bytes on demand. In this mode file parts are not materialized as `UploadedFile` values in `request.files`. Buffered multipart parsing remains the default and cannot be combined with stream consumption for the same request body.
+
+Runtime route dispatch owns an iterator created for a route and automatically calls `return()` after the handler finishes, cancelling and releasing an active source. Standalone `parseMultipartStream(...)` consumers own that responsibility: consume the iterator to completion or call `return()` when ending early.
 
 ## Related Packages
 

package/dist/adapter.d.ts

@@ -1,10 +1,16 @@
 import type { ServerOptions as HttpsServerOptions } from 'node:https';
 import { type CorsOptions, type Dispatcher, type HttpApplicationAdapter, type MiddlewareLike, type SecurityHeadersOptions } from '@fluojs/http';
 import type { Application, ApplicationLogger, CreateApplicationOptions, ModuleType, MultipartOptions } from '@fluojs/runtime';
+import { type FastifyInstance } from 'fastify';
 /**
  * Transport-level knobs for the standalone Fastify HTTP adapter factory.
  */
 export interface FastifyAdapterOptions {
+    /**
+     * Configures the internally created Fastify instance before fluo registers
+     * its multipart, raw-body, and route handling integrations.
+     */
+    configureFastify?: (app: FastifyInstance) => void | Promise<void>;
     host?: string;
     https?: HttpsServerOptions;
     maxBodySize?: number;
@@ -23,6 +29,7 @@ export type CorsInput = false | string | string[] | CorsOptions;
  * implicitly registering process shutdown listeners.
  */
 export interface BootstrapFastifyApplicationOptions extends Omit<CreateApplicationOptions, 'adapter' | 'logger' | 'middleware'> {
+    configureFastify?: FastifyAdapterOptions['configureFastify'];
     cors?: CorsInput;
     globalPrefix?: string;
     globalPrefixExclude?: readonly string[];
@@ -66,7 +73,9 @@ export declare class FastifyHttpApplicationAdapter implements HttpApplicationAda
     private readonly maxBodySize;
     private readonly preserveRawBody;
     private readonly shutdownTimeoutMs;
+    private readonly configureFastify?;
     private closeInFlight?;
+    private fastifyConfigurationInFlight?;
     private dispatcher?;
     private appClosed;
     private listenAbortController?;
@@ -76,7 +85,7 @@ export declare class FastifyHttpApplicationAdapter implements HttpApplicationAda
     private pluginsReady;
     private app;
     private readonly requestResponseFactory;
-    constructor(port: number, host: string | undefined, retryDelayMs: number | undefined, retryLimit: number | undefined, httpsOptions: HttpsServerOptions | undefined, multipartOptions?: MultipartOptions | undefined, maxBodySize?: number, preserveRawBody?: boolean, shutdownTimeoutMs?: number);
+    constructor(port: number, host: string | undefined, retryDelayMs: number | undefined, retryLimit: number | undefined, httpsOptions: HttpsServerOptions | undefined, multipartOptions?: MultipartOptions | undefined, maxBodySize?: number, preserveRawBody?: boolean, shutdownTimeoutMs?: number, configureFastify?: ((app: FastifyInstance) => void | Promise<void>) | undefined);
     getServer(): unknown;
     getRealtimeCapability(): import("@fluojs/http").ServerBackedHttpAdapterRealtimeCapability;
     getListenTarget(): FastifyListenTarget;
@@ -84,8 +93,10 @@ export declare class FastifyHttpApplicationAdapter implements HttpApplicationAda
     close(): Promise<void>;
     private closeApplication;
     private registerPluginsAndRoutes;
+    private configureFastifyInstance;
     private configureNativeRouteDescriptors;
     private registerNativeRoutes;
+    private registerCustomHttpMethods;
     private registerWildcardFallbackRoute;
     private listenWithRetry;
     private handleRequest;
@@ -115,14 +126,14 @@ export declare function createFastifyAdapter(options?: FastifyAdapterOptions, mu
  */
 export declare function bootstrapFastifyApplication(rootModule: ModuleType, options: BootstrapFastifyApplicationOptions): Promise<Application>;
 /**
- * Bootstrap and prepare a Fastify-backed application with shutdown registration.
+ * Bootstrap and start a Fastify-backed application with shutdown registration.
  *
- * This helper mirrors the README quick-start path: create the adapter, wire the
- * runtime, and attach signal handling so callers only need to invoke `listen()`.
+ * This helper creates the adapter, wires the runtime, awaits `listen()`, installs
+ * the configured shutdown registration, and only then returns the running application.
  *
  * @param rootModule Root application module compiled by the Fluo runtime.
  * @param options Runtime, adapter, and shutdown registration settings.
- * @returns A bootstrapped application shell ready to listen.
+ * @returns A running application shell after listening succeeds and shutdown registration completes.
  */
 export declare function runFastifyApplication(rootModule: ModuleType, options: RunFastifyApplicationOptions): Promise<Application>;
 /**

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -2,10 +2,11 @@ import { Transform } from 'node:stream';
 import multipart from '@fastify/multipart';
 import { createErrorResponse, createServerBackedHttpAdapterRealtimeCapability, HttpException, InternalServerErrorException, PayloadTooLargeException } from '@fluojs/http';
 import { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive } from '@fluojs/http/internal';
+import { parseMultipart, parseMultipartStream } from '@fluojs/runtime/web';
 import { bootstrapHttpAdapterApplication, runHttpAdapterApplication } from '@fluojs/runtime/internal/http-adapter';
 import { dispatchWithRequestResponseFactory } from '@fluojs/runtime/internal/request-response-factory';
-import { cloneHeaderValue, createDeferredFrameworkRequestShell, createMemoizedAsyncValue, createMemoizedValue, parseQueryParamsFromSearch, snapshotSimpleQueryRecord, splitRawRequestUrl } from '@fluojs/runtime/internal-node';
-import { createConsoleApplicationLogger, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/runtime/node';
+import { cloneHeaderValue, createDeferredFrameworkRequestShell, createMemoizedAsyncValue, createMemoizedValue, createNodeEarlyHintsCapability, parseQueryParamsFromSearch, snapshotSimpleQueryRecord, splitRawRequestUrl } from '@fluojs/platform-nodejs/internal';
+import { createConsoleApplicationLogger, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/platform-nodejs';
 import fastify from 'fastify';
 
 /**
@@ -38,6 +39,7 @@ const EMPTY_NATIVE_ROUTE_PARAMS = Object.freeze({});
  */
 export class FastifyHttpApplicationAdapter {
   closeInFlight;
+  fastifyConfigurationInFlight;
   dispatcher;
   appClosed = false;
   listenAbortController;
@@ -47,7 +49,7 @@ export class FastifyHttpApplicationAdapter {
   pluginsReady = false;
   app;
   requestResponseFactory;
-  constructor(port, host, retryDelayMs = 150, retryLimit = 20, httpsOptions, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+  constructor(port, host, retryDelayMs = 150, retryLimit = 20, httpsOptions, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS, configureFastify) {
     this.port = port;
     this.host = host;
     this.retryDelayMs = retryDelayMs;
@@ -57,6 +59,7 @@ export class FastifyHttpApplicationAdapter {
     this.maxBodySize = maxBodySize;
     this.preserveRawBody = preserveRawBody;
     this.shutdownTimeoutMs = shutdownTimeoutMs;
+    this.configureFastify = configureFastify;
     resolvePort(this.port);
     resolveNonNegativeIntegerOption('retryDelayMs', this.retryDelayMs, 150);
     resolveNonNegativeIntegerOption('retryLimit', this.retryLimit, 20);
@@ -87,6 +90,7 @@ export class FastifyHttpApplicationAdapter {
     if (this.appClosed) {
       this.app = createFastifyApp(this.httpsOptions, this.maxBodySize);
       this.appClosed = false;
+      this.fastifyConfigurationInFlight = undefined;
       this.pluginsReady = false;
     }
     this.dispatcher = dispatcher;
@@ -126,31 +130,78 @@ export class FastifyHttpApplicationAdapter {
     return waitForCloseWithTimeout(this.closeInFlight, this.shutdownTimeoutMs);
   }
   async closeApplication() {
-    if (this.listenInFlight) {
-      this.listenAbortController?.abort();
-      await ignoreCancelledListen(this.listenInFlight);
-    }
-    if (!this.app.server.listening) {
-      return;
-    }
+    let startupError;
+    let startupFailed = false;
+    let closeError;
+    let closeFailed = false;
     try {
-      await this.app.close();
+      if (this.listenInFlight) {
+        this.listenAbortController?.abort();
+        await ignoreCancelledListen(this.listenInFlight);
+      }
+    } catch (error) {
+      startupError = error;
+      startupFailed = true;
     } finally {
-      this.appClosed = true;
+      if (!this.appClosed) {
+        try {
+          await this.app.close();
+        } catch (error) {
+          closeError = error;
+          closeFailed = true;
+        } finally {
+          this.appClosed = true;
+        }
+      }
+    }
+    if (startupFailed) {
+      if (closeFailed) {
+        if (typeof startupError === 'object' && startupError !== null || typeof startupError === 'function') {
+          try {
+            const existingCause = Reflect.get(startupError, 'cause');
+            const closeFailure = existingCause === undefined ? closeError : new AggregateError([existingCause, closeError], 'Fastify startup and shutdown both failed.');
+            const causeAttached = Reflect.set(startupError, 'cause', closeFailure);
+            if (!causeAttached || Reflect.get(startupError, 'cause') !== closeFailure) {
+              startupError = new AggregateError([startupError, closeError], 'Fastify startup and shutdown both failed.');
+            }
+          } catch {
+            // Mutable rejection objects preserve identity only when cause can be read, written, and
+            // read back. Every other rejection value uses startup-first errors to expose both failures.
+            startupError = new AggregateError([startupError, closeError], 'Fastify startup and shutdown both failed.');
+          }
+        } else {
+          startupError = new AggregateError([startupError, closeError], 'Fastify startup and shutdown both failed.');
+        }
+      }
+      throw startupError;
+    }
+    if (closeFailed) {
+      throw closeError;
     }
   }
   async registerPluginsAndRoutes(dispatcher) {
     if (this.pluginsReady) {
       return;
     }
+    await this.configureFastifyInstance();
     await this.app.register(multipart);
     if (this.preserveRawBody) {
       this.app.addHook('preParsing', captureRawBodyPreParsingHook);
     }
-    this.registerNativeRoutes(resolveDispatcherRouteDescriptors(dispatcher));
+    const descriptors = resolveDispatcherRouteDescriptors(dispatcher);
+    this.registerCustomHttpMethods(descriptors);
+    this.registerNativeRoutes(descriptors);
     this.registerWildcardFallbackRoute();
     this.pluginsReady = true;
   }
+  configureFastifyInstance() {
+    if (!this.fastifyConfigurationInFlight) {
+      this.fastifyConfigurationInFlight = Promise.resolve().then(() => this.configureFastify?.(this.app)).catch(error => {
+        throw error;
+      });
+    }
+    return this.fastifyConfigurationInFlight;
+  }
   configureNativeRouteDescriptors(dispatcher) {
     this.nativeRouteDescriptors.clear();
     for (const route of createFastifyNativeRoutes(resolveDispatcherRouteDescriptors(dispatcher))) {
@@ -175,6 +226,17 @@ export class FastifyHttpApplicationAdapter {
       });
     }
   }
+  registerCustomHttpMethods(descriptors) {
+    for (const descriptor of descriptors) {
+      const method = descriptor.route.method;
+      if (method === 'ALL' || method === 'CONNECT' || this.app.supportedMethods.includes(method)) {
+        continue;
+      }
+      this.app.addHttpMethod(method, {
+        hasBody: true
+      });
+    }
+  }
   registerWildcardFallbackRoute() {
     this.app.all('*', async (request, reply) => {
       await this.handleRequest(request, reply);
@@ -424,7 +486,7 @@ function canonicalizeFastifyRouteShape(path) {
  * @returns A runtime `HttpApplicationAdapter` backed by Fastify.
  */
 export function createFastifyAdapter(options = {}, multipartOptions) {
-  return new FastifyHttpApplicationAdapter(resolvePort(options.port), options.host, options.retryDelayMs, options.retryLimit, options.https, multipartOptions, options.maxBodySize, options.rawBody, options.shutdownTimeoutMs);
+  return new FastifyHttpApplicationAdapter(resolvePort(options.port), options.host, options.retryDelayMs, options.retryLimit, options.https, multipartOptions, options.maxBodySize, options.rawBody, options.shutdownTimeoutMs, options.configureFastify);
 }
 
 /**
@@ -440,14 +502,14 @@ export async function bootstrapFastifyApplication(rootModule, options) {
 }
 
 /**
- * Bootstrap and prepare a Fastify-backed application with shutdown registration.
+ * Bootstrap and start a Fastify-backed application with shutdown registration.
  *
- * This helper mirrors the README quick-start path: create the adapter, wire the
- * runtime, and attach signal handling so callers only need to invoke `listen()`.
+ * This helper creates the adapter, wires the runtime, awaits `listen()`, installs
+ * the configured shutdown registration, and only then returns the running application.
  *
  * @param rootModule Root application module compiled by the Fluo runtime.
  * @param options Runtime, adapter, and shutdown registration settings.
- * @returns A bootstrapped application shell ready to listen.
+ * @returns A running application shell after listening succeeds and shutdown registration completes.
  */
 export async function runFastifyApplication(rootModule, options) {
   const logger = options.logger ?? createConsoleApplicationLogger();
@@ -459,6 +521,7 @@ export async function runFastifyApplication(rootModule, options) {
 }
 class MutableFastifyFrameworkResponse {
   committed;
+  earlyHints;
   headers = {};
   raw;
   statusCode;
@@ -467,6 +530,7 @@ class MutableFastifyFrameworkResponse {
   constructor(reply) {
     this.reply = reply;
     this.committed = reply.sent;
+    this.earlyHints = createNodeEarlyHintsCapability(reply.raw, () => this.committed);
     this.raw = reply;
   }
   get stream() {
@@ -479,11 +543,14 @@ class MutableFastifyFrameworkResponse {
     this.committed = true;
     this.reply.redirect(location, status);
   }
-  send(body) {
+  send(body, options) {
     if (this.reply.sent) {
       this.committed = true;
       return;
     }
+    if (options?.compression === false) {
+      disableNativeCompression(this.reply);
+    }
     const existingContentType = this.reply.getHeader('content-type');
     const serialized = serializeResponseBody(body, typeof existingContentType === 'string' ? existingContentType : undefined);
     if (!this.reply.hasHeader('content-type') && serialized.defaultContentType) {
@@ -506,9 +573,8 @@ class MutableFastifyFrameworkResponse {
   setHeader(name, value) {
     const lowerName = name.toLowerCase();
     if (lowerName === 'set-cookie') {
-      const merged = mergeSetCookieHeader(this.reply.getHeader(name), value);
-      this.reply.header(name, merged);
-      this.headers[name] = merged;
+      this.reply.header(name, value);
+      this.headers[name] = mergeSetCookieHeader(this.headers[name], value);
       return;
     }
     this.reply.header(name, value);
@@ -520,6 +586,13 @@ class MutableFastifyFrameworkResponse {
     this.statusSet = true;
   }
 }
+function disableNativeCompression(reply) {
+  const cacheControl = reply.getHeader('cache-control');
+  const value = Array.isArray(cacheControl) ? cacheControl.join(', ') : String(cacheControl ?? '');
+  if (!/\bno-transform\b/i.test(value)) {
+    reply.header('Cache-Control', value ? `${value}, no-transform` : 'no-transform');
+  }
+}
 function createFrameworkResponse(reply) {
   return new MutableFastifyFrameworkResponse(reply);
 }
@@ -547,6 +620,9 @@ function createFrameworkResponseStream(reply) {
     get closed() {
       return reply.raw.writableEnded;
     },
+    disableCompression() {
+      disableNativeCompression(reply);
+    },
     flush() {
       ensureHijacked();
       reply.raw.flushHeaders?.();
@@ -557,21 +633,34 @@ function createFrameworkResponseStream(reply) {
         reply.raw.removeListener('close', listener);
       };
     },
+    onError(listener) {
+      reply.raw.on('error', listener);
+      return () => {
+        reply.raw.removeListener('error', listener);
+      };
+    },
     waitForDrain() {
       ensureHijacked();
       if (reply.raw.writableEnded || reply.raw.destroyed) {
         return Promise.resolve();
       }
-      return new Promise(resolve => {
-        const settle = () => {
-          reply.raw.removeListener('drain', settle);
-          reply.raw.removeListener('close', settle);
-          reply.raw.removeListener('error', settle);
+      return new Promise((resolve, reject) => {
+        const cleanup = () => {
+          reply.raw.removeListener('drain', resolveDrain);
+          reply.raw.removeListener('close', resolveDrain);
+          reply.raw.removeListener('error', rejectError);
+        };
+        const rejectError = error => {
+          cleanup();
+          reject(error);
+        };
+        const resolveDrain = () => {
+          cleanup();
           resolve();
         };
-        reply.raw.once('drain', settle);
-        reply.raw.once('close', settle);
-        reply.raw.once('error', settle);
+        reply.raw.once('drain', resolveDrain);
+        reply.raw.once('close', resolveDrain);
+        reply.raw.once('error', rejectError);
       });
     },
     write(chunk) {
@@ -596,12 +685,23 @@ function createDeferredFrameworkRequest(request, signal, multipartOptions, maxBo
     let body = request.body;
     let files;
     if (isMultipart) {
-      const parsed = await parseMultipartRequest(request, {
+      const resolvedMultipartOptions = {
         ...multipartOptions,
         maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
-      });
-      body = parsed.fields;
-      files = parsed.files;
+      };
+      if (multipartOptions?.strategy === 'stream') {
+        body = parseMultipartStream({
+          body: request.raw,
+          headers: headerSnapshot,
+          method: request.method,
+          signal,
+          url: rawUrl
+        }, resolvedMultipartOptions);
+      } else {
+        const parsed = await parseMultipartRequest(request, resolvedMultipartOptions);
+        body = parsed.fields;
+        files = parsed.files;
+      }
     }
     frameworkRequest.body = body;
     if (files) {
@@ -702,59 +802,8 @@ function collectVersionSensitiveRouteKeys(descriptors) {
   }
   return new Set([...grouped.entries()].filter(([, current]) => current.count > 1 || current.hasVersioned).map(([routeKey]) => routeKey));
 }
-async function parseMultipartRequest(request, options = {}) {
-  const fields = {};
-  const files = [];
-  const maxFileSize = options.maxFileSize ?? 10 * 1024 * 1024;
-  const maxFiles = options.maxFiles ?? 10;
-  const maxTotalSize = options.maxTotalSize ?? 10 * 1024 * 1024;
-  const contentLength = Number(request.headers['content-length']);
-  let totalSize = 0;
-  if (Number.isFinite(contentLength) && contentLength > maxTotalSize) {
-    throw new PayloadTooLargeException('Request body exceeds the configured multipart limits.');
-  }
-  try {
-    for await (const part of request.parts({
-      limits: {
-        fileSize: maxFileSize,
-        files: maxFiles
-      }
-    })) {
-      if (part.type === 'file') {
-        if (files.length >= maxFiles) {
-          throw new PayloadTooLargeException(`Exceeded maximum file count of ${String(maxFiles)}.`);
-        }
-        const buffer = await part.toBuffer();
-        totalSize += buffer.byteLength;
-        if (totalSize > maxTotalSize) {
-          throw new PayloadTooLargeException('Request body exceeds the configured multipart limits.');
-        }
-        files.push({
-          buffer,
-          fieldname: part.fieldname,
-          mimetype: part.mimetype,
-          originalname: part.filename,
-          size: buffer.byteLength
-        });
-        continue;
-      }
-      const value = String(part.value ?? '');
-      totalSize += Buffer.byteLength(value, 'utf8');
-      if (totalSize > maxTotalSize) {
-        throw new PayloadTooLargeException('Request body exceeds the configured multipart limits.');
-      }
-      setMultiValue(fields, part.fieldname, value);
-    }
-  } catch (error) {
-    if (isFastifyMultipartTooLargeError(error)) {
-      throw new PayloadTooLargeException('Request body exceeds the configured multipart limits.');
-    }
-    throw error;
-  }
-  return {
-    fields,
-    files
-  };
+function parseMultipartRequest(request, options = {}) {
+  return parseMultipart(request.raw, options);
 }
 
 /**
@@ -798,18 +847,6 @@ function normalizeHeaders(headers) {
 function cloneRequestHeaders(headers) {
   return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, cloneHeaderValue(value)]));
 }
-function setMultiValue(target, key, value) {
-  const existing = target[key];
-  if (existing === undefined) {
-    target[key] = value;
-    return;
-  }
-  if (Array.isArray(existing)) {
-    existing.push(value);
-    return;
-  }
-  target[key] = [existing, value];
-}
 function createRequestSignal(response) {
   const controller = new AbortController();
   const abort = reason => {
@@ -900,8 +937,11 @@ function createRawBodyBufferChunk(chunk, encoding) {
   throw new TypeError(`Fastify raw-body capture received unsupported ${typeof chunk} stream chunk.`);
 }
 function isMultipartRequestContentType(contentType) {
+  return normalizePrimaryMediaType(contentType) === 'multipart/form-data';
+}
+function normalizePrimaryMediaType(contentType) {
   const primaryValue = Array.isArray(contentType) ? contentType[0] : contentType;
-  return typeof primaryValue === 'string' && primaryValue.toLowerCase().includes('multipart/form-data');
+  return primaryValue?.split(';')[0]?.trim().toLowerCase();
 }
 function resolveListenTarget(address, port, host, useHttps) {
   const protocol = useHttps ? 'https' : 'http';
@@ -1054,5 +1094,6 @@ function serializeResponseBody(body, contentType) {
   };
 }
 function isJsonContentType(contentType) {
-  return typeof contentType === 'string' && contentType.toLowerCase().includes('application/json');
+  const normalized = normalizePrimaryMediaType(contentType);
+  return normalized === 'application/json' || normalized?.endsWith('+json') === true;
 }

package/package.json

@@ -8,7 +8,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.9",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
     "directory": "packages/platform-fastify"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -36,15 +36,16 @@
   ],
   "dependencies": {
     "@fastify/multipart": "^9.2.1",
-    "fastify": "^5.8.5",
+    "fastify": "^5.12.3",
     "fastify-raw-body": "^5.0.0",
-    "@fluojs/http": "^2.0.1",
-    "@fluojs/runtime": "^2.0.1"
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/platform-nodejs": "^2.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "devDependencies": {
-    "vitest": "^3.2.4",
-    "@fluojs/di": "^2.0.0",
-    "@fluojs/testing": "^2.0.0"
+    "vitest": "^4.1.11",
+    "@fluojs/di": "^3.0.0",
+    "@fluojs/testing": "^3.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",