@fluojs/platform-fastify 1.0.7 → 1.0.9

package/README.ko.md

@@ -7,6 +7,7 @@ fluo 런타임을 위한 Fastify 기반 HTTP 어댑터 패키지입니다.
 ## 목차
 
 - [설치](#설치)
+- [런타임 요구 사항](#런타임-요구-사항)
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
@@ -20,9 +21,17 @@ fluo 런타임을 위한 Fastify 기반 HTTP 어댑터 패키지입니다.
 ## 설치
 
 ```bash
-npm install @fluojs/platform-fastify fastify
+npm install @fluojs/platform-fastify
 ```
 
+`fastify`, `@fastify/multipart`, raw-body 지원은 이 adapter package의 runtime dependency로 포함되어 있으므로, 애플리케이션이 fluo 밖에서 Fastify API를 직접 사용하지 않는 한 별도의 `fastify` dependency를 추가할 필요가 없습니다.
+
+## 런타임 요구 사항
+
+`@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`를 사용하세요.
+
+어댑터는 Fastify 기반 Node `http` 또는 `https` listener를 소유합니다. 포트, 인증서 material, hostname 같은 process-specific value는 애플리케이션 경계에 두고, 최종 option만 adapter에 명시적으로 전달하세요.
+
 ## 사용 시점
 
 fluo 애플리케이션을 위한 고성능 HTTP 어댑터가 필요한 경우 이 패키지를 사용합니다. Fastify는 낮은 오버헤드와 효율적인 요청 처리로 잘 알려져 있으며, 높은 처리량과 동시성이 요구되는 프로덕션 fluo 애플리케이션에 권장되는 선택입니다.
@@ -45,8 +54,41 @@ await app.listen();
 
 ## 주요 패턴
 
+### HTTPS/TLS 시작
+Fastify 프로세스가 TLS를 직접 소유할 때는 Node.js `https.ServerOptions`를 `createFastifyAdapter(...)`, `bootstrapFastifyApplication(...)`, 또는 `runFastifyApplication(...)`의 `https` option으로 전달하세요. Adapter는 Fastify를 HTTPS listener로 시작하며 startup log는 `https://host:port` URL을 보고합니다.
+
+```typescript
+const app = await fluoFactory.create(AppModule, {
+  adapter: createFastifyAdapter({
+    host: '0.0.0.0',
+    port: 3443,
+    https: {
+      cert: tlsCertificate,
+      key: tlsPrivateKey,
+    },
+  }),
+});
+
+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을 받습니다.
+
+```typescript
+await runFastifyApplication(AppModule, {
+  host: '127.0.0.1',
+  https: {
+    cert: tlsCertificate,
+    key: tlsPrivateKey,
+  },
+  port: 3443,
+});
+```
+
 ### 멀티파트 및 Raw Body
-Fastify 어댑터는 내부 Fastify 플러그인을 통해 멀티파트 form-data 및 raw body 파싱을 기본적으로 지원하며, 이는 표준 fluo 요청 인터페이스를 통해 노출됩니다. `rawBody: true`를 활성화하면 멀티파트가 아닌 요청에서 `FrameworkRequest.rawBody`가 원본 요청 바이트를 그대로 보존하므로 webhook 서명 검증이나 기타 바이트 민감한 흐름에서 정확한 payload를 다시 사용할 수 있습니다. 어댑터를 직접 생성할 때는 멀티파트 제한을 두 번째 인자로 전달하고, `bootstrapFastifyApplication(...)` 및 `runFastifyApplication(...)`에서는 같은 설정을 `options.multipart` 아래에 전달하면 됩니다.
+Fastify 어댑터는 내부 Fastify 플러그인을 통해 멀티파트 form-data 및 raw body 파싱을 기본적으로 지원하며, 이는 표준 fluo 요청 인터페이스를 통해 노출됩니다. Multipart file은 runtime-neutral `FrameworkRequest.files` seam에 adapter-provided value로 붙으며, Fastify 요청에서는 body materialization 이후 fluo `UploadedFile` 객체로 채워집니다. `rawBody: true`를 활성화하면 멀티파트가 아닌 요청에서 `FrameworkRequest.rawBody`가 원본 요청 바이트를 그대로 보존하므로 webhook 서명 검증이나 기타 바이트 민감한 흐름에서 정확한 payload를 다시 사용할 수 있습니다. 어댑터를 직접 생성할 때는 멀티파트 제한을 두 번째 인자로 전달하고, `bootstrapFastifyApplication(...)` 및 `runFastifyApplication(...)`에서는 같은 설정을 `options.multipart` 아래에 전달하면 됩니다.
 
 Multipart request에서는 `Multipart/Form-Data`처럼 대소문자가 섞인 `Content-Type` media 값도 포함해 raw-body capture를 건너뜁니다. `multipart.maxTotalSize`를 생략하면 `maxBodySize`가 기본값이 되어 HTTP adapter 간 size limit이 portable하게 유지됩니다.
 
@@ -128,7 +170,9 @@ fluo 라우트 메타데이터를 Fastify 경로로 그대로 옮길 수 있는
 
 여러 라우트가 같은 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된 요청을 다시 매칭합니다.
 
-어댑터는 매칭되지 않은 경로와 이식성에 민감한 경우를 위해 와일드카드 fallback 라우트를 계속 유지하며, Fastify의 trailing slash / duplicate slash 정규화를 켜서 네이티브 선택 경로도 fluo의 문서화된 route path 계약과 맞추어 동작하도록 합니다. CORS 처리는 Fastify 플러그인이 아니라 fluo의 공유 middleware 경로가 계속 소유하고, `OPTIONS` 같은 미지원 메서드는 fluo route가 명시적으로 소유하지 않는 한 fallback dispatcher 경로로 흐릅니다.
+어댑터는 매칭되지 않은 경로와 이식성에 민감한 경우, 그리고 공유 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를 가리키지 않습니다.
 
 ## 성능
 
@@ -145,13 +189,13 @@ 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을 확인합니다.
 
-같은 파일은 Fastify 전용 native route registration과 wildcard fallback, duplicate shape route fallback, middleware/guard/interceptor/observer ordering, CORS ownership, global prefix behavior, malformed cookie preservation, response serialization parity, raw-body pre-parsing behavior, 대소문자 구분 없는 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, 대소문자 구분 없는 multipart detection, multipart limit handling도 함께 다룹니다. startup, routing, adapter portability behavior를 변경할 때는 README 예제 포인터를 이 테스트 파일 및 custom adapter book chapter와 맞추어 유지하세요.
 
 ## 공개 API 개요
 
-- `createFastifyAdapter(options)`: Fastify 어댑터를 위한 권장 팩토리입니다.
-- `bootstrapFastifyApplication(module, options)`: 암시적 리스닝 없이 수행하는 고급 부트스트랩입니다.
-- `runFastifyApplication(module, options)`: 생명주기 관리를 포함한 빠른 시작 헬퍼입니다. timeout/실패 시에는 해당 상태를 로그와 `process.exitCode`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
+- `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`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
 - `isFastifyMultipartTooLargeError(error)`: Fastify error shape 전반에서 multipart limit error를 감지합니다.
 - `FastifyHttpApplicationAdapter`: 핵심 어댑터 구현 클래스입니다.
 - Option type: `FastifyAdapterOptions`, `BootstrapFastifyApplicationOptions`, `RunFastifyApplicationOptions`, `CorsInput`, `FastifyApplicationSignal`.
@@ -163,6 +207,7 @@ 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로 유지하세요.
 
 ## 관련 패키지
 

package/README.md

@@ -7,6 +7,7 @@ Fastify-backed HTTP adapter for the fluo runtime.
 ## Table of Contents
 
 - [Installation](#installation)
+- [Runtime Requirements](#runtime-requirements)
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
@@ -20,9 +21,17 @@ Fastify-backed HTTP adapter for the fluo runtime.
 ## Installation
 
 ```bash
-npm install @fluojs/platform-fastify fastify
+npm install @fluojs/platform-fastify
 ```
 
+`fastify`, `@fastify/multipart`, and raw-body support are bundled as runtime dependencies of this adapter package, so application projects do not need a separate `fastify` dependency unless they use Fastify APIs directly outside fluo.
+
+## 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.
+
+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.
+
 ## When to Use
 
 Use this package when you need a high-performance HTTP adapter for your fluo application. Fastify is known for its low overhead and efficient request handling, making it the recommended choice for production fluo applications requiring high throughput and concurrency.
@@ -45,8 +54,41 @@ await app.listen();
 
 ## Common Patterns
 
+### 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.
+
+```typescript
+const app = await fluoFactory.create(AppModule, {
+  adapter: createFastifyAdapter({
+    host: '0.0.0.0',
+    port: 3443,
+    https: {
+      cert: tlsCertificate,
+      key: tlsPrivateKey,
+    },
+  }),
+});
+
+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:
+
+```typescript
+await runFastifyApplication(AppModule, {
+  host: '127.0.0.1',
+  https: {
+    cert: tlsCertificate,
+    key: tlsPrivateKey,
+  },
+  port: 3443,
+});
+```
+
 ### Multipart and Raw Body
-The Fastify adapter includes built-in support for multipart form-data and raw body parsing via internal Fastify plugins, exposed through the standard fluo request interface. When `rawBody: true` is enabled, `FrameworkRequest.rawBody` preserves the original request bytes for non-multipart requests so webhook signature verification and other byte-sensitive flows can replay the exact payload. When you construct the adapter directly, pass multipart limits as the second argument. `bootstrapFastifyApplication(...)` and `runFastifyApplication(...)` accept the same multipart settings under `options.multipart`.
+The Fastify adapter includes built-in support for multipart form-data and raw body parsing via internal Fastify plugins, exposed through the standard fluo request interface. Multipart files are attached to the runtime-neutral `FrameworkRequest.files` seam as adapter-provided values; Fastify requests populate it with fluo `UploadedFile` objects after body materialization. When `rawBody: true` is enabled, `FrameworkRequest.rawBody` preserves the original request bytes for non-multipart requests so webhook signature verification and other byte-sensitive flows can replay the exact payload. When you construct the adapter directly, pass multipart limits as the second argument. `bootstrapFastifyApplication(...)` and `runFastifyApplication(...)` accept the same multipart settings under `options.multipart`.
 
 Raw-body capture is skipped for multipart requests, including mixed-case `Content-Type` media values such as `Multipart/Form-Data`. When `multipart.maxTotalSize` is omitted, it defaults to `maxBodySize` so size limits stay portable across HTTP adapters.
 
@@ -128,7 +170,9 @@ When fluo route metadata can be translated directly, the adapter registers Fasti
 
 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.
 
-The adapter keeps a wildcard fallback route for unmatched paths and portability-sensitive cases, 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.
+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.
 
 ## Performance
 
@@ -145,13 +189,13 @@ fluo's Fastify adapter significantly outperforms the raw Node.js adapter in high
 
 `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.
 
-The same file also covers Fastify-specific native route registration with wildcard fallback, duplicate shape route fallback, middleware/guard/interceptor/observer ordering, CORS ownership, global prefix behavior, malformed cookie preservation, response serialization parity, raw-body pre-parsing behavior, 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, 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)`: Recommended factory for the Fastify adapter.
-- `bootstrapFastifyApplication(module, options)`: advanced bootstrap without implicit listening.
-- `runFastifyApplication(module, options)`: Quick-start helper with lifecycle management. On timeout/failure it reports the condition through logging and `process.exitCode`, while leaving final process termination to the surrounding host.
+- `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.
 - `isFastifyMultipartTooLargeError(error)`: Detects multipart limit errors across Fastify error shapes.
 - `FastifyHttpApplicationAdapter`: The core adapter implementation.
 - Option types: `FastifyAdapterOptions`, `BootstrapFastifyApplicationOptions`, `RunFastifyApplicationOptions`, `CorsInput`, `FastifyApplicationSignal`.
@@ -163,6 +207,7 @@ 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.
 
 ## Related Packages
 

package/dist/adapter.d.ts

@@ -1,12 +1,6 @@
 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, UploadedFile } from '@fluojs/runtime';
-declare module '@fluojs/http' {
-    interface FrameworkRequest {
-        files?: UploadedFile[];
-        rawBody?: Uint8Array;
-    }
-}
+import type { Application, ApplicationLogger, CreateApplicationOptions, ModuleType, MultipartOptions } from '@fluojs/runtime';
 /**
  * Transport-level knobs for the standalone Fastify HTTP adapter factory.
  */
@@ -74,8 +68,13 @@ export declare class FastifyHttpApplicationAdapter implements HttpApplicationAda
     private readonly shutdownTimeoutMs;
     private closeInFlight?;
     private dispatcher?;
+    private appClosed;
+    private listenAbortController?;
+    private listenInFlight?;
+    private listenState;
+    private readonly nativeRouteDescriptors;
     private pluginsReady;
-    private readonly app;
+    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);
     getServer(): unknown;
@@ -83,7 +82,9 @@ export declare class FastifyHttpApplicationAdapter implements HttpApplicationAda
     getListenTarget(): FastifyListenTarget;
     listen(dispatcher: Dispatcher): Promise<void>;
     close(): Promise<void>;
+    private closeApplication;
     private registerPluginsAndRoutes;
+    private configureNativeRouteDescriptors;
     private registerNativeRoutes;
     private registerWildcardFallbackRoute;
     private listenWithRetry;

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

@@ -39,6 +39,11 @@ const EMPTY_NATIVE_ROUTE_PARAMS = Object.freeze({});
 export class FastifyHttpApplicationAdapter {
   closeInFlight;
   dispatcher;
+  appClosed = false;
+  listenAbortController;
+  listenInFlight;
+  listenState = 'idle';
+  nativeRouteDescriptors = new Map();
   pluginsReady = false;
   app;
   requestResponseFactory;
@@ -69,28 +74,70 @@ export class FastifyHttpApplicationAdapter {
   getListenTarget() {
     return resolveListenTarget(this.app.server.address() ?? null, this.port, this.host, this.httpsOptions !== undefined);
   }
-  async listen(dispatcher) {
+  listen(dispatcher) {
+    if (this.closeInFlight) {
+      return this.closeInFlight.then(() => this.listen(dispatcher));
+    }
+    if (this.listenState === 'listening') {
+      return Promise.resolve();
+    }
+    if (this.listenInFlight) {
+      return this.listenInFlight;
+    }
+    if (this.appClosed) {
+      this.app = createFastifyApp(this.httpsOptions, this.maxBodySize);
+      this.appClosed = false;
+      this.pluginsReady = false;
+    }
     this.dispatcher = dispatcher;
-    await this.registerPluginsAndRoutes(dispatcher);
-    await this.listenWithRetry();
+    this.configureNativeRouteDescriptors(dispatcher);
+    const abortController = new AbortController();
+    this.listenAbortController = abortController;
+    this.listenState = 'starting';
+    const listenInFlight = this.registerPluginsAndRoutes(dispatcher).then(() => this.listenWithRetry(abortController.signal)).then(() => {
+      this.listenState = 'listening';
+    }, error => {
+      this.listenState = 'idle';
+      throw error;
+    }).finally(() => {
+      if (this.listenInFlight === listenInFlight) {
+        this.listenInFlight = undefined;
+      }
+      if (this.listenAbortController === abortController) {
+        this.listenAbortController = undefined;
+      }
+    });
+    this.listenInFlight = listenInFlight;
+    return listenInFlight;
   }
-  async close() {
-    if (this.closeInFlight) {
-      await waitForCloseWithTimeout(this.closeInFlight, this.shutdownTimeoutMs);
-      return;
+  close() {
+    if (!this.closeInFlight) {
+      const closeInFlight = this.closeApplication().finally(() => {
+        if (this.closeInFlight === closeInFlight) {
+          this.closeInFlight = undefined;
+        }
+        this.listenState = 'idle';
+        this.dispatcher = undefined;
+        this.nativeRouteDescriptors.clear();
+      });
+      this.closeInFlight = closeInFlight;
+      void closeInFlight.catch(() => {});
+    }
+    return waitForCloseWithTimeout(this.closeInFlight, this.shutdownTimeoutMs);
+  }
+  async closeApplication() {
+    if (this.listenInFlight) {
+      this.listenAbortController?.abort();
+      await ignoreCancelledListen(this.listenInFlight);
     }
     if (!this.app.server.listening) {
-      this.dispatcher = undefined;
       return;
     }
-    const closePromise = this.app.close();
-    const closeInFlight = closePromise.finally(() => {
-      this.closeInFlight = undefined;
-      this.dispatcher = undefined;
-    });
-    this.closeInFlight = closeInFlight;
-    void closeInFlight.catch(() => {});
-    await waitForCloseWithTimeout(closeInFlight, this.shutdownTimeoutMs);
+    try {
+      await this.app.close();
+    } finally {
+      this.appClosed = true;
+    }
   }
   async registerPluginsAndRoutes(dispatcher) {
     if (this.pluginsReady) {
@@ -104,14 +151,21 @@ export class FastifyHttpApplicationAdapter {
     this.registerWildcardFallbackRoute();
     this.pluginsReady = true;
   }
+  configureNativeRouteDescriptors(dispatcher) {
+    this.nativeRouteDescriptors.clear();
+    for (const route of createFastifyNativeRoutes(resolveDispatcherRouteDescriptors(dispatcher))) {
+      this.nativeRouteDescriptors.set(route.routeKey, route.descriptor);
+    }
+  }
   registerNativeRoutes(descriptors) {
     for (const route of createFastifyNativeRoutes(descriptors)) {
       this.app.route({
         handler: async (request, reply) => {
           const urlParts = splitRawRequestUrl(request.raw.url ?? '/');
           const params = normalizeNativeRouteParams(request.params);
-          if (!isRoutePathNormalizationSensitive(urlParts.path) && !hasNativeRouteParamSeparators(params)) {
-            await this.handleNativeRouteRequest(route.descriptor, params, urlParts, request, reply);
+          const descriptor = this.nativeRouteDescriptors.get(route.routeKey);
+          if (descriptor && !isRoutePathNormalizationSensitive(urlParts.path) && !hasNativeRouteParamSeparators(params)) {
+            await this.handleNativeRouteRequest(descriptor, params, urlParts, request, reply);
             return;
           }
           await this.handleRequest(request, reply);
@@ -126,19 +180,21 @@ export class FastifyHttpApplicationAdapter {
       await this.handleRequest(request, reply);
     });
   }
-  async listenWithRetry() {
+  async listenWithRetry(signal) {
     for (let attempt = 0;; attempt++) {
+      throwIfListenCancelled(signal);
       try {
         await this.app.listen({
           host: this.host,
           port: this.port
         });
+        throwIfListenCancelled(signal);
         return;
       } catch (error) {
         if (!isAddressInUseError(error) || attempt >= this.retryLimit) {
           throw error;
         }
-        await delay(this.retryDelayMs);
+        await delay(this.retryDelayMs, signal);
       }
     }
   }
@@ -209,6 +265,7 @@ function createNativeFastFrameworkRequest(request, lazySignal, urlParts, maxBody
   if (Number.isFinite(contentLength) && contentLength > maxBodySize) {
     throw new PayloadTooLargeException('Request body exceeds the size limit.');
   }
+  assertBodyWithinMaxBodySize(request.body, maxBodySize);
   const frameworkRequest = createDeferredFrameworkRequestShell({
     cookieHeader: cloneHeaderValue(request.headers.cookie),
     headersFactory: () => normalizeHeaders(cloneRequestHeaders(request.headers)),
@@ -217,7 +274,7 @@ function createNativeFastFrameworkRequest(request, lazySignal, urlParts, maxBody
     query: readSimpleQueryRecord(request.query),
     queryFactory: () => parseQueryParamsFromSearch(urlParts.search),
     raw: request.raw,
-    requestId: resolvePrimaryRequestIdFromHeaders(request.raw.headers),
+    requestId: resolveRequestIdFromHeaders(request.raw.headers),
     signal: lazySignal.signal,
     url: urlParts.path + urlParts.search
   });
@@ -314,11 +371,13 @@ function createFastifyNativeRoutes(descriptors) {
   return [...candidates.values()].filter(candidate => shapePaths.get(candidate.shapeKey)?.size === 1).map(({
     descriptor,
     method,
-    path
+    path,
+    routeKey
   }) => ({
     descriptor,
     method,
-    path
+    path,
+    routeKey
   }));
 }
 function isFastifyNativeRouteDescriptor(descriptor) {
@@ -334,6 +393,7 @@ function registerFastifyNativeRouteCandidate(candidates, shapePaths, descriptor)
       descriptor,
       method,
       path,
+      routeKey,
       shapeKey
     });
   }
@@ -550,6 +610,7 @@ function createDeferredFrameworkRequest(request, signal, multipartOptions, maxBo
     if (preserveRawBody && !isMultipart) {
       const rawBodyValue = request.rawBody;
       if (rawBodyValue !== undefined) {
+        assertBodyWithinMaxBodySize(rawBodyValue, maxBodySize);
         frameworkRequest.rawBody = rawBodyValue;
       }
     }
@@ -563,11 +624,12 @@ function createDeferredFrameworkRequest(request, signal, multipartOptions, maxBo
     query: querySnapshot,
     queryFactory: () => parseQueryParamsFromSearch(urlParts.search),
     raw: request.raw,
-    requestId: resolvePrimaryRequestIdFromHeaders(headerSnapshot),
+    requestId: resolveRequestIdFromHeaders(headerSnapshot),
     signal,
     url: urlParts.path + urlParts.search
   });
   if (!needsDeferredBodyMaterialization) {
+    assertBodyWithinMaxBodySize(request.body, maxBodySize);
     frameworkRequest.body = request.body;
   }
   const nativeRouteHandoff = consumeRawRequestNativeRouteHandoff(request.raw);
@@ -603,6 +665,26 @@ function hasNativeRouteParamSeparators(params) {
   }
   return false;
 }
+function assertBodyWithinMaxBodySize(body, maxBodySize) {
+  if (resolveFastifyBodySize(body) > maxBodySize) {
+    throw new PayloadTooLargeException('Request body exceeds the size limit.');
+  }
+}
+function resolveFastifyBodySize(body) {
+  if (body === undefined || body === null) {
+    return 0;
+  }
+  if (typeof body === 'string') {
+    return Buffer.byteLength(body, 'utf8');
+  }
+  if (Buffer.isBuffer(body)) {
+    return body.byteLength;
+  }
+  if (body instanceof Uint8Array) {
+    return body.byteLength;
+  }
+  return 1;
+}
 function collectVersionSensitiveRouteKeys(descriptors) {
   const grouped = new Map();
   for (const descriptor of descriptors) {
@@ -746,14 +828,10 @@ function resolveRequestIdFromHeaders(headers) {
   const requestId = headers['x-request-id'] ?? headers['x-correlation-id'];
   return Array.isArray(requestId) ? requestId[0] : requestId;
 }
-function resolvePrimaryRequestIdFromHeaders(headers) {
-  const requestId = headers['x-request-id'];
-  return Array.isArray(requestId) ? requestId[0] : requestId;
-}
 function createFastifyApp(httpsOptions, maxBodySize) {
   if (httpsOptions) {
     return fastify({
-      bodyLimit: maxBodySize,
+      bodyLimit: resolveFastifyBodyLimit(maxBodySize),
       exposeHeadRoutes: false,
       https: httpsOptions,
       logger: false,
@@ -764,7 +842,7 @@ function createFastifyApp(httpsOptions, maxBodySize) {
     });
   }
   return fastify({
-    bodyLimit: maxBodySize,
+    bodyLimit: resolveFastifyBodyLimit(maxBodySize),
     exposeHeadRoutes: false,
     logger: false,
     routerOptions: {
@@ -773,6 +851,9 @@ function createFastifyApp(httpsOptions, maxBodySize) {
     }
   });
 }
+function resolveFastifyBodyLimit(maxBodySize) {
+  return Math.max(maxBodySize, 1);
+}
 function captureRawBodyPreParsingHook(request, _reply, payload, done) {
   if (isMultipartRequestContentType(request.headers['content-type'])) {
     done(null, payload);
@@ -780,8 +861,14 @@ function captureRawBodyPreParsingHook(request, _reply, payload, done) {
   }
   const chunks = [];
   const capture = new Transform({
-    transform(chunk, _encoding, callback) {
-      const bufferChunk = Buffer.isBuffer(chunk) ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk) : Buffer.from(String(chunk), 'utf8');
+    transform(chunk, encoding, callback) {
+      let bufferChunk;
+      try {
+        bufferChunk = createRawBodyBufferChunk(chunk, encoding);
+      } catch (error) {
+        callback(error instanceof Error ? error : new Error(String(error)));
+        return;
+      }
       chunks.push(bufferChunk);
       capture.receivedEncodedLength += bufferChunk.byteLength;
       callback(null, chunk);
@@ -800,6 +887,18 @@ function captureRawBodyPreParsingHook(request, _reply, payload, done) {
   payload.pipe(capture);
   done(null, capture);
 }
+function createRawBodyBufferChunk(chunk, encoding) {
+  if (Buffer.isBuffer(chunk)) {
+    return chunk;
+  }
+  if (chunk instanceof Uint8Array) {
+    return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  }
+  if (typeof chunk === 'string') {
+    return Buffer.from(chunk, encoding);
+  }
+  throw new TypeError(`Fastify raw-body capture received unsupported ${typeof chunk} stream chunk.`);
+}
 function isMultipartRequestContentType(contentType) {
   const primaryValue = Array.isArray(contentType) ? contentType[0] : contentType;
   return typeof primaryValue === 'string' && primaryValue.toLowerCase().includes('multipart/form-data');
@@ -853,9 +952,46 @@ function isAddressInUseError(error) {
   }
   return error.code === 'EADDRINUSE';
 }
-function delay(ms) {
-  return new Promise(resolve => {
-    setTimeout(resolve, ms);
+class FastifyListenCancelledError extends Error {
+  constructor() {
+    super('Fastify adapter startup was cancelled during shutdown.');
+  }
+}
+function throwIfListenCancelled(signal) {
+  if (signal.aborted) {
+    throw new FastifyListenCancelledError();
+  }
+}
+function isFastifyListenCancelledError(error) {
+  return error instanceof FastifyListenCancelledError;
+}
+async function ignoreCancelledListen(listenPromise) {
+  try {
+    await listenPromise;
+  } catch (error) {
+    if (isFastifyListenCancelledError(error)) {
+      return;
+    }
+    throw error;
+  }
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new FastifyListenCancelledError());
+      return;
+    }
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(new FastifyListenCancelledError());
+    };
+    signal?.addEventListener('abort', onAbort, {
+      once: true
+    });
   });
 }
 function waitForCloseWithTimeout(closePromise, timeoutMs) {

package/package.json

@@ -8,7 +8,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.7",
+  "version": "1.0.9",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -38,13 +38,13 @@
     "@fastify/multipart": "^9.2.1",
     "fastify": "^5.8.5",
     "fastify-raw-body": "^5.0.0",
-    "@fluojs/http": "^1.1.1",
-    "@fluojs/runtime": "^1.1.7"
+    "@fluojs/http": "^2.0.1",
+    "@fluojs/runtime": "^2.0.1"
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/di": "^1.1.0",
-    "@fluojs/testing": "^1.0.5"
+    "@fluojs/di": "^2.0.0",
+    "@fluojs/testing": "^2.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",