@fluojs/platform-fastify 1.0.0-beta.2 → 1.0.0-beta.4

package/README.ko.md

@@ -43,7 +43,7 @@ await app.listen();
 ## 주요 패턴
 
 ### 멀티파트 및 Raw Body
-Fastify 어댑터는 내부 Fastify 플러그인을 통해 멀티파트 form-data 및 raw body 파싱을 기본적으로 지원하며, 이는 표준 fluo 요청 인터페이스를 통해 노출됩니다. 어댑터를 직접 생성할 때는 멀티파트 제한을 두 번째 인자로 전달하고, `bootstrapFastifyApplication(...)` 및 `runFastifyApplication(...)`에서는 같은 설정을 `options.multipart` 아래에 전달하면 됩니다.
+Fastify 어댑터는 내부 Fastify 플러그인을 통해 멀티파트 form-data 및 raw body 파싱을 기본적으로 지원하며, 이는 표준 fluo 요청 인터페이스를 통해 노출됩니다. `rawBody: true`를 활성화하면 멀티파트가 아닌 요청에서 `FrameworkRequest.rawBody`가 원본 요청 바이트를 그대로 보존하므로 webhook 서명 검증이나 기타 바이트 민감한 흐름에서 정확한 payload를 다시 사용할 수 있습니다. 어댑터를 직접 생성할 때는 멀티파트 제한을 두 번째 인자로 전달하고, `bootstrapFastifyApplication(...)` 및 `runFastifyApplication(...)`에서는 같은 설정을 `options.multipart` 아래에 전달하면 됩니다.
 
 ```typescript
 const adapter = createFastifyAdapter(
@@ -65,6 +65,9 @@ Fastify는 `@fluojs/websockets`가 기본 Node.js HTTP 서버에 직접 연결
 export class MyGateway {}
 ```
 
+### 스트리밍 응답
+Fastify 기반 응답 스트림은 SSE 및 기타 스트리밍 writer가 사용하는 공통 fluo 스트림 계약을 지원합니다. `response.stream.waitForDrain()`은 기본 응답이 `drain`, `close`, 또는 `error`를 내보낼 때 settle되므로, 클라이언트가 연결을 끊거나 backpressure가 해소되기 전에 스트림이 닫혀도 writer가 멈춰 있지 않습니다.
+
 ### CORS 설정
 CORS는 부트스트랩 옵션을 통해 처리됩니다. fluo는 별도의 Fastify 플러그인에 의존하지 않고 내부 CORS 로직을 관리합니다.
 
@@ -122,6 +125,13 @@ await bootstrapFastifyApplication(AppModule, {
 });
 ```
 
+### 네이티브 라우트 등록과 안전한 폴백
+fluo 라우트 메타데이터를 Fastify 경로로 그대로 옮길 수 있는 경우, 어댑터는 모든 요청을 단일 와일드카드 라우트로 보내는 대신 Fastify 네이티브 per-route 핸들러를 등록합니다. 이 네이티브 핸들러도 최종적으로는 공통 fluo dispatcher로 위임하므로 params, versioning, middleware, guards, interceptors, observers, SSE, multipart, raw body, streaming, error handling 의미론은 그대로 유지됩니다.
+
+여러 라우트가 같은 method와 정규화된 param shape를 공유하는 경우(예: `/:id` 와 `/:slug`), 어댑터는 해당 shape를 의도적으로 와일드카드 fallback 경로에 남겨 둡니다. 이렇게 해서 Fastify 등록 단계에서 부팅 실패가 나거나 fluo의 등록 순서 기반 매칭 의미론이 좁아지지 않도록 보장합니다.
+
+어댑터는 매칭되지 않은 경로와 이식성에 민감한 경우를 위해 와일드카드 fallback 라우트를 계속 유지하며, Fastify의 trailing slash / duplicate slash 정규화를 켜서 네이티브 선택 경로도 fluo의 문서화된 route path 계약과 맞추어 동작하도록 합니다.
+
 ## 성능
 
 fluo의 Fastify 어댑터는 높은 동시성 시나리오에서 raw Node.js 어댑터보다 훨씬 뛰어난 성능을 발휘합니다.

package/README.md

@@ -43,7 +43,7 @@ await app.listen();
 ## 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 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. 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`.
 
 ```typescript
 const adapter = createFastifyAdapter(
@@ -65,6 +65,9 @@ Fastify provides a `server-backed` capability that allows `@fluojs/websockets` t
 export class MyGateway {}
 ```
 
+### Streaming Responses
+Fastify-backed response streams support the shared fluo stream contract used by SSE and other streaming writers. `response.stream.waitForDrain()` settles when the underlying response emits `drain`, `close`, or `error`, so writers do not hang when a client disconnects or the stream closes before backpressure clears.
+
 ### CORS Configuration
 CORS is handled via bootstrap options. fluo manages the underlying CORS logic rather than relying on a separate Fastify plugin.
 
@@ -122,6 +125,13 @@ 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. Those native handlers still hand off to the shared fluo dispatcher, so params, versioning, middleware, guards, interceptors, observers, SSE, multipart, raw body, streaming, and error handling keep the same framework-level semantics.
+
+When multiple routes share the same method and normalized param shape (for example `/:id` and `/:slug`), the adapter intentionally leaves that shape on the wildcard fallback path so Fastify registration cannot boot-fail or narrow fluo's registration-order matching semantics.
+
+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.
+
 ## Performance
 
 fluo's Fastify adapter significantly outperforms the raw Node.js adapter in high-concurrency scenarios.

package/dist/adapter.d.ts

@@ -83,7 +83,9 @@ export declare class FastifyHttpApplicationAdapter implements HttpApplicationAda
     getListenTarget(): FastifyListenTarget;
     listen(dispatcher: Dispatcher): Promise<void>;
     close(): Promise<void>;
-    private registerPluginsAndRoute;
+    private registerPluginsAndRoutes;
+    private registerNativeRoutes;
+    private registerWildcardFallbackRoute;
     private listenWithRetry;
     private handleRequest;
 }

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

@@ -1,6 +1,6 @@
+import { Transform } from 'node:stream';
 import multipart from '@fastify/multipart';
 import fastify from 'fastify';
-import fastifyRawBody from 'fastify-raw-body';
 import { createServerBackedHttpAdapterRealtimeCapability, createErrorResponse, HttpException, InternalServerErrorException, PayloadTooLargeException } from '@fluojs/http';
 import { createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/runtime/node';
 import { bootstrapHttpAdapterApplication, runHttpAdapterApplication } from '@fluojs/runtime/internal/http-adapter';
@@ -16,6 +16,7 @@ import { dispatchWithRequestResponseFactory } from '@fluojs/runtime/internal/req
 
 const DEFAULT_MAX_BODY_SIZE = 1 * 1024 * 1024;
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+const FASTIFY_NATIVE_ROUTE_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'];
 
 /**
  * Bootstrap options for creating a Fastify-backed application without
@@ -62,7 +63,7 @@ export class FastifyHttpApplicationAdapter {
   }
   async listen(dispatcher) {
     this.dispatcher = dispatcher;
-    await this.registerPluginsAndRoute();
+    await this.registerPluginsAndRoutes(dispatcher);
     await this.listenWithRetry();
   }
   async close() {
@@ -85,23 +86,33 @@ export class FastifyHttpApplicationAdapter {
     }
     await waitForCloseWithTimeout(closeInFlight, this.shutdownTimeoutMs);
   }
-  async registerPluginsAndRoute() {
+  async registerPluginsAndRoutes(dispatcher) {
     if (this.pluginsReady) {
       return;
     }
     await this.app.register(multipart);
     if (this.preserveRawBody) {
-      await this.app.register(fastifyRawBody, {
-        encoding: 'utf8',
-        field: 'rawBody',
-        global: true,
-        runFirst: true
+      this.app.addHook('preParsing', captureRawBodyPreParsingHook);
+    }
+    this.registerNativeRoutes(resolveDispatcherRouteDescriptors(dispatcher));
+    this.registerWildcardFallbackRoute();
+    this.pluginsReady = true;
+  }
+  registerNativeRoutes(descriptors) {
+    for (const route of createFastifyNativeRoutes(descriptors)) {
+      this.app.route({
+        handler: async (request, reply) => {
+          await this.handleRequest(request, reply);
+        },
+        method: route.method,
+        url: route.path
       });
     }
+  }
+  registerWildcardFallbackRoute() {
     this.app.all('*', async (request, reply) => {
       await this.handleRequest(request, reply);
     });
-    this.pluginsReady = true;
   }
   async listenWithRetry() {
     for (let attempt = 0;; attempt++) {
@@ -150,6 +161,51 @@ function createFastifyRequestResponseFactory(multipartOptions, maxBodySize = DEF
     }
   };
 }
+function resolveDispatcherRouteDescriptors(dispatcher) {
+  return dispatcher.describeRoutes?.() ?? [];
+}
+function createFastifyNativeRoutes(descriptors) {
+  const candidates = new Map();
+  const shapePaths = new Map();
+  for (const descriptor of descriptors) {
+    const path = descriptor.route.path;
+    if (descriptor.route.method === 'ALL') {
+      for (const method of FASTIFY_NATIVE_ROUTE_METHODS) {
+        registerFastifyNativeRouteCandidate(candidates, shapePaths, method, path);
+      }
+      continue;
+    }
+    registerFastifyNativeRouteCandidate(candidates, shapePaths, descriptor.route.method, path);
+  }
+  return [...candidates.values()].filter(candidate => shapePaths.get(candidate.shapeKey)?.size === 1).map(({
+    method,
+    path
+  }) => ({
+    method,
+    path
+  }));
+}
+function registerFastifyNativeRouteCandidate(candidates, shapePaths, method, path) {
+  const routeKey = `${method}:${path}`;
+  const shapeKey = `${method}:${canonicalizeFastifyRouteShape(path)}`;
+  if (!candidates.has(routeKey)) {
+    candidates.set(routeKey, {
+      method,
+      path,
+      shapeKey
+    });
+  }
+  let paths = shapePaths.get(shapeKey);
+  if (!paths) {
+    paths = new Set();
+    shapePaths.set(shapeKey, paths);
+  }
+  paths.add(path);
+}
+function canonicalizeFastifyRouteShape(path) {
+  const segments = path.split('/').filter(Boolean).map(segment => segment.startsWith(':') ? ':' : segment);
+  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+}
 
 /**
  * Create the recommended Fastify adapter for `FluoFactory.create(...)`.
@@ -278,11 +334,19 @@ function createFrameworkResponseStream(reply) {
     },
     waitForDrain() {
       ensureHijacked();
-      if (reply.raw.writableEnded) {
+      if (reply.raw.writableEnded || reply.raw.destroyed) {
         return Promise.resolve();
       }
       return new Promise(resolve => {
-        reply.raw.once('drain', () => resolve());
+        const settle = () => {
+          reply.raw.removeListener('drain', settle);
+          reply.raw.removeListener('close', settle);
+          reply.raw.removeListener('error', settle);
+          resolve();
+        };
+        reply.raw.once('drain', settle);
+        reply.raw.once('close', settle);
+        reply.raw.once('error', settle);
       });
     },
     write(chunk) {
@@ -325,7 +389,7 @@ async function createFrameworkRequest(request, signal, multipartOptions, maxBody
   if (preserveRawBody && !isMultipart) {
     const rawBodyValue = request.rawBody;
     if (rawBodyValue !== undefined) {
-      frameworkRequest.rawBody = typeof rawBodyValue === 'string' ? Buffer.from(rawBodyValue, 'utf8') : rawBodyValue;
+      frameworkRequest.rawBody = rawBodyValue;
     }
   }
   return frameworkRequest;
@@ -490,15 +554,54 @@ function createFastifyApp(httpsOptions, maxBodySize) {
   if (httpsOptions) {
     return fastify({
       bodyLimit: maxBodySize,
+      exposeHeadRoutes: false,
       https: httpsOptions,
-      logger: false
+      logger: false,
+      routerOptions: {
+        ignoreDuplicateSlashes: true,
+        ignoreTrailingSlash: true
+      }
     });
   }
   return fastify({
     bodyLimit: maxBodySize,
-    logger: false
+    exposeHeadRoutes: false,
+    logger: false,
+    routerOptions: {
+      ignoreDuplicateSlashes: true,
+      ignoreTrailingSlash: true
+    }
   });
 }
+function captureRawBodyPreParsingHook(request, _reply, payload, done) {
+  if (isMultipartRequestContentType(request.headers['content-type'])) {
+    done(null, payload);
+    return;
+  }
+  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');
+      chunks.push(bufferChunk);
+      callback(null, chunk);
+    },
+    flush(callback) {
+      if (chunks.length > 0) {
+        request.rawBody = Buffer.concat(chunks);
+      }
+      callback();
+    }
+  });
+  payload.on('error', error => {
+    capture.destroy(error);
+  });
+  payload.pipe(capture);
+  done(null, capture);
+}
+function isMultipartRequestContentType(contentType) {
+  const primaryValue = Array.isArray(contentType) ? contentType[0] : contentType;
+  return typeof primaryValue === 'string' && primaryValue.includes('multipart/form-data');
+}
 function resolveListenTarget(address, port, host, useHttps) {
   const protocol = useHttps ? 'https' : 'http';
   const resolvedPort = typeof address === 'object' && address !== null ? address.port : port;

package/package.json

@@ -8,7 +8,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "@fastify/multipart": "^9.2.1",
     "fastify": "^5.8.5",
     "fastify-raw-body": "^5.0.0",
-    "@fluojs/http": "^1.0.0-beta.1",
-    "@fluojs/runtime": "^1.0.0-beta.1"
+    "@fluojs/http": "^1.0.0-beta.3",
+    "@fluojs/runtime": "^1.0.0-beta.4"
   },
   "devDependencies": {
     "vitest": "^3.2.4"