@fluojs/platform-fastify 1.0.0-beta.8 → 1.0.1

package/README.ko.md

@@ -11,6 +11,7 @@ fluo 런타임을 위한 Fastify 기반 HTTP 어댑터 패키지입니다.
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
 - [성능](#성능)
+- [적합성 커버리지](#적합성-커버리지)
 - [공개 API 개요](#공개-api-개요)
 - [트러블슈팅](#트러블슈팅)
 - [관련 패키지](#관련-패키지)
@@ -40,11 +41,15 @@ const app = await fluoFactory.create(AppModule, {
 await app.listen();
 ```
 
+`createFastifyAdapter()`는 기본 port로 `3000`을 사용하며 `process.env.PORT`를 읽지 않습니다. 잘못된 explicit port 값은 adapter setup 중 throw됩니다.
+
 ## 주요 패턴
 
 ### 멀티파트 및 Raw Body
 Fastify 어댑터는 내부 Fastify 플러그인을 통해 멀티파트 form-data 및 raw body 파싱을 기본적으로 지원하며, 이는 표준 fluo 요청 인터페이스를 통해 노출됩니다. `rawBody: true`를 활성화하면 멀티파트가 아닌 요청에서 `FrameworkRequest.rawBody`가 원본 요청 바이트를 그대로 보존하므로 webhook 서명 검증이나 기타 바이트 민감한 흐름에서 정확한 payload를 다시 사용할 수 있습니다. 어댑터를 직접 생성할 때는 멀티파트 제한을 두 번째 인자로 전달하고, `bootstrapFastifyApplication(...)` 및 `runFastifyApplication(...)`에서는 같은 설정을 `options.multipart` 아래에 전달하면 됩니다.
 
+Multipart request에서는 raw-body capture를 건너뜁니다. `multipart.maxTotalSize`를 생략하면 `maxBodySize`가 기본값이 되어 HTTP adapter 간 size limit이 portable하게 유지됩니다.
+
 ```typescript
 const adapter = createFastifyAdapter(
   {
@@ -126,7 +131,7 @@ await bootstrapFastifyApplication(AppModule, {
 ```
 
 ### 네이티브 라우트 등록과 안전한 폴백
-fluo 라우트 메타데이터를 Fastify 경로로 그대로 옮길 수 있는 경우, 어댑터는 모든 요청을 단일 와일드카드 라우트로 보내는 대신 Fastify 네이티브 per-route 핸들러를 등록합니다. 의미 보존이 가능한 unversioned route에서는 Fastify가 미리 고른 descriptor와 params를 공유 fluo dispatcher에 전달하므로 duplicate route matching을 건너뛰면서도 middleware, guards, interceptors, observers, SSE, multipart, raw body, streaming, error handling 의미론은 그대로 유지됩니다.
+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된 요청을 다시 매칭합니다.
 
@@ -143,12 +148,20 @@ fluo의 Fastify 어댑터는 높은 동시성 시나리오에서 raw Node.js 어
 
 *표준 `/health` 엔드포인트에서 `wrk`를 사용하여 측정되었습니다.*
 
+## 적합성 커버리지
+
+`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 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`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
+- `isFastifyMultipartTooLargeError(error)`: Fastify error shape 전반에서 multipart limit error를 감지합니다.
 - `FastifyHttpApplicationAdapter`: 핵심 어댑터 구현 클래스입니다.
+- Option type: `FastifyAdapterOptions`, `BootstrapFastifyApplicationOptions`, `RunFastifyApplicationOptions`, `CorsInput`, `FastifyApplicationSignal`.
 
 ## 트러블슈팅
 
@@ -156,6 +169,7 @@ fluo의 Fastify 어댑터는 높은 동시성 시나리오에서 raw Node.js 어
 - **미들웨어 문제**: `middleware` 옵션은 런타임 레벨의 `MiddlewareLike[]` 함수 배열을 받습니다. 이는 Fastify 플러그인이 아니며 다른 fluo 어댑터들과 공통으로 사용되는 표준 인터페이스를 따릅니다.
 - **로깅 (Logging)**: 로그 스트림 중복을 방지하기 위해 Fastify의 네이티브 로거가 비활성화됩니다. 모든 로깅 설정은 `runFastifyApplication` 또는 `bootstrapFastifyApplication`의 `logger` 옵션을 통해 이루어져야 합니다.
 - **글로벌 접두사 (Global Prefix)**: 내부 경로 또는 헬스 체크 엔드포인트에 접두사가 붙지 않도록 `globalPrefixExclude`를 적절히 설정하세요.
+- **Malformed Cookie**: 잘못된 cookie header는 request 실패로 이어지지 않고 보존됩니다.
 
 ## 관련 패키지
 

package/README.md

@@ -11,6 +11,7 @@ Fastify-backed HTTP adapter for the fluo runtime.
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
 - [Performance](#performance)
+- [Conformance Coverage](#conformance-coverage)
 - [Public API Overview](#public-api-overview)
 - [Troubleshooting](#troubleshooting)
 - [Related Packages](#related-packages)
@@ -40,11 +41,15 @@ const app = await fluoFactory.create(AppModule, {
 await app.listen();
 ```
 
+`createFastifyAdapter()` defaults to port `3000` and does not read `process.env.PORT`; invalid explicit port values throw during adapter setup.
+
 ## Common Patterns
 
 ### 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`.
 
+Raw-body capture is skipped for multipart requests. When `multipart.maxTotalSize` is omitted, it defaults to `maxBodySize` so size limits stay portable across HTTP adapters.
+
 ```typescript
 const adapter = createFastifyAdapter(
   {
@@ -126,7 +131,7 @@ await bootstrapFastifyApplication(AppModule, {
 ```
 
 ### Native Route Registration with Safe Fallback
-When fluo route metadata can be translated directly, the adapter registers Fastify-native per-route handlers 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 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.
 
@@ -143,12 +148,20 @@ fluo's Fastify adapter significantly outperforms the raw Node.js adapter in high
 
 *Measured using `wrk` on a standard `/health` endpoint.*
 
+## 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.
+
+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, 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.
+- `isFastifyMultipartTooLargeError(error)`: Detects multipart limit errors across Fastify error shapes.
 - `FastifyHttpApplicationAdapter`: The core adapter implementation.
+- Option types: `FastifyAdapterOptions`, `BootstrapFastifyApplicationOptions`, `RunFastifyApplicationOptions`, `CorsInput`, `FastifyApplicationSignal`.
 
 ## Troubleshooting
 
@@ -156,6 +169,7 @@ fluo's Fastify adapter significantly outperforms the raw Node.js adapter in high
 - **Middleware Issues**: The `middleware` option accepts runtime-level `MiddlewareLike[]` functions. These are not Fastify plugins and follow the standard middleware interface used across fluo adapters.
 - **Logging**: The native Fastify logger is disabled to prevent duplicate log streams. All logging should be configured via the fluo `logger` option in `runFastifyApplication` or `bootstrapFastifyApplication`.
 - **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.
 
 ## Related Packages
 

package/dist/adapter.js

@@ -778,6 +778,7 @@ function captureRawBodyPreParsingHook(request, _reply, payload, done) {
     transform(chunk, _encoding, callback) {
       const bufferChunk = Buffer.isBuffer(chunk) ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk) : Buffer.from(String(chunk), 'utf8');
       chunks.push(bufferChunk);
+      capture.receivedEncodedLength += bufferChunk.byteLength;
       callback(null, chunk);
     },
     flush(callback) {
@@ -787,6 +788,7 @@ function captureRawBodyPreParsingHook(request, _reply, payload, done) {
       callback();
     }
   });
+  capture.receivedEncodedLength = 0;
   payload.on('error', error => {
     capture.destroy(error);
   });

package/package.json

@@ -8,7 +8,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.0-beta.8",
+  "version": "1.0.1",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -38,12 +38,13 @@
     "@fastify/multipart": "^9.2.1",
     "fastify": "^5.8.5",
     "fastify-raw-body": "^5.0.0",
-    "@fluojs/http": "^1.0.0-beta.6",
-    "@fluojs/runtime": "^1.0.0-beta.8"
+    "@fluojs/http": "^1.0.0",
+    "@fluojs/runtime": "^1.0.1"
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/di": "^1.0.0-beta.5"
+    "@fluojs/di": "^1.0.1",
+    "@fluojs/testing": "^1.0.1"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",