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

package/README.ko.md

@@ -126,11 +126,11 @@ await bootstrapFastifyApplication(AppModule, {
 ```
 
 ### 네이티브 라우트 등록과 안전한 폴백
-fluo 라우트 메타데이터를 Fastify 경로로 그대로 옮길 수 있는 경우, 어댑터는 모든 요청을 단일 와일드카드 라우트로 보내는 대신 Fastify 네이티브 per-route 핸들러를 등록합니다. 이 네이티브 핸들러도 최종적으로는 공통 fluo dispatcher로 위임하므로 params, versioning, middleware, guards, interceptors, observers, SSE, multipart, raw body, streaming, error handling 의미론은 그대로 유지됩니다.
+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 의미론은 그대로 유지됩니다.
 
-여러 라우트가 같은 method와 정규화된 param shape를 공유하는 경우(예: `/:id` 와 `/:slug`), 어댑터는 해당 shape를 의도적으로 와일드카드 fallback 경로에 남겨 둡니다. 이렇게 해서 Fastify 등록 단계에서 부팅 실패가 나거나 fluo의 등록 순서 기반 매칭 의미론이 좁아지지 않도록 보장합니다.
+여러 라우트가 같은 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 계약과 맞추어 동작하도록 합니다.
+어댑터는 매칭되지 않은 경로와 이식성에 민감한 경우를 위해 와일드카드 fallback 라우트를 계속 유지하며, Fastify의 trailing slash / duplicate slash 정규화를 켜서 네이티브 선택 경로도 fluo의 문서화된 route path 계약과 맞추어 동작하도록 합니다. CORS 처리는 Fastify 플러그인이 아니라 fluo의 공유 middleware 경로가 계속 소유하고, `OPTIONS` 같은 미지원 메서드는 fluo route가 명시적으로 소유하지 않는 한 fallback dispatcher 경로로 흐릅니다.
 
 ## 성능
 

package/README.md

@@ -126,11 +126,11 @@ 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 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 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.
+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.
+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.
 
 ## Performance
 

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,6 +2,7 @@ import { Transform } from 'node:stream';
 import multipart from '@fastify/multipart';
 import fastify from 'fastify';
 import { createServerBackedHttpAdapterRealtimeCapability, createErrorResponse, HttpException, InternalServerErrorException, PayloadTooLargeException } from '@fluojs/http';
+import { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive } from '@fluojs/http/internal';
 import { createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/runtime/node';
 import { bootstrapHttpAdapterApplication, runHttpAdapterApplication } from '@fluojs/runtime/internal/http-adapter';
 import { dispatchWithRequestResponseFactory } from '@fluojs/runtime/internal/request-response-factory';
@@ -16,7 +17,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'];
+const FASTIFY_NATIVE_ROUTE_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'];
 
 /**
  * Bootstrap options for creating a Fastify-backed application without
@@ -102,6 +103,14 @@ export class FastifyHttpApplicationAdapter {
     for (const route of createFastifyNativeRoutes(descriptors)) {
       this.app.route({
         handler: async (request, reply) => {
+          const requestPath = readRequestPathFromRawUrl(request.raw.url);
+          const params = normalizeNativeRouteParams(request.params);
+          if (!isRoutePathNormalizationSensitive(requestPath) && !hasNativeRouteParamSeparators(params)) {
+            bindRawRequestNativeRouteHandoff(request.raw, {
+              descriptor: route.descriptor,
+              params
+            });
+          }
           await this.handleRequest(request, reply);
         },
         method: route.method,
@@ -151,6 +160,9 @@ function createFastifyRequestResponseFactory(multipartOptions, maxBodySize = DEF
     createResponse(reply) {
       return createFrameworkResponse(reply);
     },
+    async materializeRequest(request) {
+      await materializeFrameworkRequestBody(request);
+    },
     resolveRequestId(request) {
       return resolveRequestIdFromHeaders(request.raw.headers);
     },
@@ -167,29 +179,34 @@ function resolveDispatcherRouteDescriptors(dispatcher) {
 function createFastifyNativeRoutes(descriptors) {
   const candidates = new Map();
   const shapePaths = new Map();
+  const versionSensitiveRouteKeys = collectVersionSensitiveRouteKeys(descriptors);
   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);
-      }
+    if (!isFastifyNativeRouteDescriptor(descriptor) || versionSensitiveRouteKeys.has(`${descriptor.route.method}:${descriptor.route.path}`)) {
       continue;
     }
-    registerFastifyNativeRouteCandidate(candidates, shapePaths, descriptor.route.method, path);
+    registerFastifyNativeRouteCandidate(candidates, shapePaths, descriptor);
   }
   return [...candidates.values()].filter(candidate => shapePaths.get(candidate.shapeKey)?.size === 1).map(({
+    descriptor,
     method,
     path
   }) => ({
+    descriptor,
     method,
     path
   }));
 }
-function registerFastifyNativeRouteCandidate(candidates, shapePaths, method, path) {
+function isFastifyNativeRouteDescriptor(descriptor) {
+  return descriptor.route.method !== 'ALL' && FASTIFY_NATIVE_ROUTE_METHODS.includes(descriptor.route.method) && descriptor.route.version === undefined;
+}
+function registerFastifyNativeRouteCandidate(candidates, shapePaths, descriptor) {
+  const method = descriptor.route.method;
+  const path = descriptor.route.path;
   const routeKey = `${method}:${path}`;
   const shapeKey = `${method}:${canonicalizeFastifyRouteShape(path)}`;
   if (!candidates.has(routeKey)) {
     candidates.set(routeKey, {
+      descriptor,
       method,
       path,
       shapeKey
@@ -254,11 +271,15 @@ export async function runFastifyApplication(rootModule, options) {
   }, adapter);
 }
 function createFrameworkResponse(reply) {
+  let activeStream;
   return {
     committed: reply.sent,
     headers: {},
     raw: reply,
-    stream: createFrameworkResponseStream(reply),
+    get stream() {
+      activeStream ??= createFrameworkResponseStream(reply);
+      return activeStream;
+    },
     redirect(status, location) {
       this.setStatus(status);
       this.setHeader('Location', location);
@@ -278,6 +299,17 @@ function createFrameworkResponse(reply) {
       this.committed = true;
       await reply.send(serialized.payload);
     },
+    async sendSimpleJson(body) {
+      if (reply.sent) {
+        this.committed = true;
+        return;
+      }
+      if (!reply.hasHeader('content-type')) {
+        reply.header('content-type', 'application/json; charset=utf-8');
+      }
+      this.committed = true;
+      await reply.send(JSON.stringify(body));
+    },
     setHeader(name, value) {
       const lowerName = name.toLowerCase();
       if (lowerName === 'set-cookie') {
@@ -356,43 +388,92 @@ function createFrameworkResponseStream(reply) {
   };
 }
 async function createFrameworkRequest(request, signal, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
+  return createDeferredFrameworkRequest(request, signal, multipartOptions, maxBodySize, preserveRawBody);
+}
+function createDeferredFrameworkRequest(request, signal, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
   const rawUrl = request.raw.url ?? '/';
-  const url = new URL(rawUrl, 'http://localhost');
-  const headers = normalizeHeaders(request.headers);
-  const contentType = headers['content-type'];
-  const isMultipart = typeof contentType === 'string' && contentType.includes('multipart/form-data');
-  let body = request.body;
-  let files;
-  if (isMultipart) {
-    const parsed = await parseMultipartRequest(request, {
-      ...multipartOptions,
-      maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
-    });
-    body = parsed.fields;
-    files = parsed.files;
-  }
+  const urlParts = splitRawRequestUrl(rawUrl);
+  const headerSnapshot = cloneRequestHeaders(request.headers);
+  const headers = createMemoizedValue(() => normalizeHeaders(headerSnapshot));
+  const cookieHeader = cloneHeaderValue(headerSnapshot.cookie);
+  const cookies = createMemoizedValue(() => parseCookieHeader(cookieHeader));
+  const query = createMemoizedValue(() => parseQueryParamsFromSearch(urlParts.search));
+  const isMultipart = isMultipartRequestContentType(headerSnapshot['content-type']);
+  const materializeBody = createMemoizedAsyncValue(async () => {
+    let body = request.body;
+    let files;
+    if (isMultipart) {
+      const parsed = await parseMultipartRequest(request, {
+        ...multipartOptions,
+        maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
+      });
+      body = parsed.fields;
+      files = parsed.files;
+    }
+    frameworkRequest.body = body;
+    if (files) {
+      frameworkRequest.files = files;
+    }
+    if (preserveRawBody && !isMultipart) {
+      const rawBodyValue = request.rawBody;
+      if (rawBodyValue !== undefined) {
+        frameworkRequest.rawBody = rawBodyValue;
+      }
+    }
+  });
   const frameworkRequest = {
-    body,
-    cookies: parseCookieHeader(Array.isArray(headers.cookie) ? headers.cookie[0] : headers.cookie),
-    headers,
+    get cookies() {
+      return cookies();
+    },
+    get headers() {
+      return headers();
+    },
     method: request.method,
     params: {},
-    path: url.pathname,
-    query: parseQueryParams(url.searchParams),
+    path: urlParts.path,
+    get query() {
+      return query();
+    },
     raw: request.raw,
     signal,
-    url: url.pathname + url.search
+    url: urlParts.path + urlParts.search,
+    materializeBody
   };
-  if (files) {
-    frameworkRequest.files = files;
+  const nativeRouteHandoff = consumeRawRequestNativeRouteHandoff(request.raw);
+  return nativeRouteHandoff ? attachFrameworkRequestNativeRouteHandoff(frameworkRequest, nativeRouteHandoff) : frameworkRequest;
+}
+async function materializeFrameworkRequestBody(request) {
+  await request.materializeBody?.();
+  delete request.materializeBody;
+}
+function normalizeNativeRouteParams(params) {
+  if (typeof params !== 'object' || params === null) {
+    return {};
   }
-  if (preserveRawBody && !isMultipart) {
-    const rawBodyValue = request.rawBody;
-    if (rawBodyValue !== undefined) {
-      frameworkRequest.rawBody = rawBodyValue;
+  return Object.fromEntries(Object.entries(params).flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : value === undefined ? [] : [[key, String(value)]]));
+}
+function hasNativeRouteParamSeparators(params) {
+  return Object.values(params).some(value => value.includes('/'));
+}
+function collectVersionSensitiveRouteKeys(descriptors) {
+  const grouped = new Map();
+  for (const descriptor of descriptors) {
+    if (!FASTIFY_NATIVE_ROUTE_METHODS.includes(descriptor.route.method)) {
+      continue;
     }
+    const routeKey = `${descriptor.route.method}:${descriptor.route.path}`;
+    const current = grouped.get(routeKey) ?? {
+      count: 0,
+      hasVersioned: false
+    };
+    current.count += 1;
+    current.hasVersioned ||= descriptor.route.version !== undefined;
+    grouped.set(routeKey, current);
   }
-  return frameworkRequest;
+  return new Set([...grouped.entries()].filter(([, current]) => current.count > 1 || current.hasVersioned).map(([routeKey]) => routeKey));
+}
+function readRequestPathFromRawUrl(rawUrl) {
+  return splitRawRequestUrl(rawUrl ?? '/').path;
 }
 async function parseMultipartRequest(request, options = {}) {
   const fields = {};
@@ -487,6 +568,9 @@ function normalizeHeaders(headers) {
   }
   return normalized;
 }
+function parseQueryParamsFromSearch(search) {
+  return parseQueryParams(new URLSearchParams(search));
+}
 function parseQueryParams(searchParams) {
   const query = {};
   for (const [key, value] of searchParams.entries()) {
@@ -504,10 +588,11 @@ function parseQueryParams(searchParams) {
   return query;
 }
 function parseCookieHeader(cookieHeader) {
-  if (!cookieHeader) {
+  const normalizedCookieHeader = Array.isArray(cookieHeader) ? cookieHeader.join('; ') : cookieHeader;
+  if (!normalizedCookieHeader) {
     return {};
   }
-  return Object.fromEntries(cookieHeader.split(';').map(pair => pair.trim()).filter(Boolean).map(pair => {
+  return Object.fromEntries(normalizedCookieHeader.split(';').map(pair => pair.trim()).filter(Boolean).map(pair => {
     const index = pair.indexOf('=');
     if (index === -1) {
       return [pair.trim(), ''];
@@ -520,6 +605,55 @@ function parseCookieHeader(cookieHeader) {
     }
   }));
 }
+function createMemoizedValue(factory) {
+  let initialized = false;
+  let value;
+  return () => {
+    if (!initialized) {
+      value = factory();
+      initialized = true;
+    }
+    return value;
+  };
+}
+function createMemoizedAsyncValue(factory) {
+  let promise;
+  return () => {
+    promise ??= factory();
+    return promise;
+  };
+}
+function cloneHeaderValue(value) {
+  return Array.isArray(value) ? [...value] : value;
+}
+function cloneRequestHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, cloneHeaderValue(value)]));
+}
+function splitRawRequestUrl(rawUrl) {
+  if (rawUrl.startsWith('http://') || rawUrl.startsWith('https://')) {
+    const url = new URL(rawUrl);
+    return {
+      path: url.pathname,
+      search: url.search
+    };
+  }
+  const queryStart = rawUrl.indexOf('?');
+  const hashStart = rawUrl.indexOf('#');
+  const pathEndCandidates = [queryStart, hashStart].filter(index => index >= 0);
+  const pathEnd = pathEndCandidates.length > 0 ? Math.min(...pathEndCandidates) : rawUrl.length;
+  const path = rawUrl.slice(0, pathEnd) || '/';
+  if (queryStart === -1) {
+    return {
+      path,
+      search: ''
+    };
+  }
+  const searchEnd = hashStart >= 0 && hashStart > queryStart ? hashStart : rawUrl.length;
+  return {
+    path,
+    search: rawUrl.slice(queryStart, searchEnd)
+  };
+}
 function setMultiValue(target, key, value) {
   const existing = target[key];
   if (existing === undefined) {

package/package.json

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