@fluojs/platform-express 1.0.0-beta.3 → 1.0.0-beta.5

package/README.ko.md

@@ -44,6 +44,8 @@ await app.listen();
 ### 스트리밍 응답 처리 (SSE)
 Express 어댑터는 공유 `SseResponse` 유틸리티를 통해 Server-Sent Events(SSE)를 지원하며, Express 전용 스트림 처리를 추상화합니다.
 
+Express 기반 응답 스트림은 공유 fluo 백프레셔 계약도 따릅니다. `response.stream.waitForDrain()`은 `drain`, `close`, `error` 중 어느 쪽이 먼저 와도 완료되므로, 백프레셔가 풀리기 전에 클라이언트가 연결을 끊어도 스트리밍 작성기가 멈추지 않습니다.
+
 ```typescript
 @Get('events')
 async streamEvents(@Res() res: FrameworkResponse) {
@@ -71,9 +73,11 @@ const adapter = createExpressAdapter(
 ### 안전한 fallback을 포함한 Native Route Registration
 이제 어댑터는 의미 보존이 가능한 명시적 HTTP 메서드 라우트를 Express Router에 사전 등록하면서도, 실제 요청 처리는 계속 공유 fluo dispatcher를 통해 수행합니다.
 
-덕분에 guards, interceptors, observers, body parsing, raw body 캡처, SSE, 오류 응답은 기존과 같은 framework-owned 실행 경로를 유지하면서, Express가 먼저 일부 경로 매칭 비용을 줄일 수 있습니다.
+의미 보존이 가능한 unversioned route에서는 Express가 미리 고른 descriptor와 params를 공유 dispatcher에 전달하므로 duplicate route matching을 건너뛰면서도 guards, interceptors, observers, body parsing, raw body 캡처, SSE, 오류 응답은 기존과 같은 framework-owned 실행 경로를 유지합니다.
+
+어댑터가 native handoff를 붙인 뒤 app middleware가 framework request의 method 또는 path를 rewrite하면 dispatcher는 그 handoff를 stale로 보고 원래 Express match를 재사용하지 않고 rewrite된 요청을 다시 매칭합니다.
 
-문서화된 fluo semantics를 바꾸지 않기 위해 `/:id` 와 `/:slug`처럼 shape가 겹치는 파라미터 라우트, `@All(...)` 핸들러, `OPTIONS` 소유권, 그리고 duplicate slash/trailing slash 정규화에 의존하는 요청은 catch-all fallback 경로에 남겨둡니다.
+문서화된 fluo semantics를 바꾸지 않기 위해 `/:id` 와 `/:slug`처럼 shape가 겹치는 파라미터 라우트, `@All(...)` 핸들러, `OPTIONS` 소유권, non-URI versioning, 그리고 duplicate slash/trailing slash 정규화에 의존하는 요청은 catch-all fallback 경로에 남겨둡니다.
 
 ## 어댑터 계약
 
@@ -82,6 +86,7 @@ const adapter = createExpressAdapter(
 - **OPTIONS 소유권 parity**: 어댑터는 native route에 대해 Express Router가 `OPTIONS`를 자동 응답하지 못하게 막아, 미지원 메서드도 계속 fluo dispatcher semantics로 흘러가고 `@All(...)` 핸들러가 정의된 경우 `OPTIONS`도 그대로 소유할 수 있게 합니다.
 - **경로 정규화 parity**: duplicate slash 변형처럼 Express Router와 fluo의 정규화 방식이 다를 수 있는 요청도 fallback dispatch를 통해 fluo의 normalized route contract를 유지합니다.
 - **버저닝 parity**: Express Router가 최초 path match를 하더라도 header/media-type/custom version 선택은 계속 dispatcher가 최종 결정합니다.
+- **Middleware rewrite parity**: App middleware가 method/path를 rewrite하면 native handoff는 무효화되고 rewrite된 요청을 기준으로 다시 매칭합니다.
 
 ## 공개 API 개요
 

package/README.md

@@ -44,6 +44,8 @@ await app.listen();
 ### Handling Streaming Responses (SSE)
 The Express adapter supports Server-Sent Events (SSE) via the shared `SseResponse` utility, abstracting away the Express-specific stream handling.
 
+Express-backed response streams also honor the shared fluo backpressure contract: `response.stream.waitForDrain()` settles on `drain`, `close`, or `error`, so streaming writers do not hang when clients disconnect before backpressure clears.
+
 ```typescript
 @Get('events')
 async streamEvents(@Res() res: FrameworkResponse) {
@@ -71,9 +73,11 @@ const adapter = createExpressAdapter(
 ### Native Route Registration with Safe Fallback
 The adapter now pre-registers semantically safe Express Router handlers for explicit HTTP methods and still dispatches those requests through the shared fluo dispatcher.
 
-This keeps guards, interceptors, observers, body parsing, raw body capture, SSE, and error responses on the same framework-owned execution path while allowing Express to short-circuit some path matching work first.
+For semantically safe unversioned routes, Express hands the pre-matched descriptor and params to the shared dispatcher so duplicate route matching is skipped while guards, interceptors, observers, body parsing, raw body capture, SSE, and error responses stay on the same framework-owned execution path.
+
+If app middleware rewrites the framework request method or path after the adapter attaches a native handoff, the dispatcher treats that handoff as stale and rematches the rewritten request instead of reusing the original Express match.
 
-To avoid changing documented fluo semantics, overlapping same-shape param routes such as `/:id` and `/:slug`, `@All(...)` handlers, `OPTIONS` ownership, and requests that rely on fluo's duplicate-slash/trailing-slash normalization stay on the catch-all fallback path.
+To avoid changing documented fluo semantics, overlapping same-shape param routes such as `/:id` and `/:slug`, `@All(...)` handlers, `OPTIONS` ownership, non-URI versioning, and requests that rely on fluo's duplicate-slash/trailing-slash normalization stay on the catch-all fallback path.
 
 ## Adapter Contract
 

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,10 +1,11 @@
 import { createServer as createHttpServer } from 'node:http';
 import { createServer as createHttpsServer } from 'node:https';
 import { Readable } from 'node:stream';
-import { URL } from 'node:url';
 import express from 'express';
 import { BadRequestException, 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 { cloneRequestHeaders, createDeferredFrameworkRequestShell, createMemoizedAsyncValue, createRequestSignal, normalizePrimaryContentType, parseQueryParamsFromSearch, resolveAbsoluteRequestUrl, resolveRequestIdFromHeaders, snapshotSimpleQueryRecord, splitRawRequestUrl } from '@fluojs/runtime/internal-node';
 import { parseMultipart } from '@fluojs/runtime/web';
 import { bootstrapHttpAdapterApplication, runHttpAdapterApplication } from '@fluojs/runtime/internal/http-adapter';
 import { dispatchWithRequestResponseFactory } from '@fluojs/runtime/internal/request-response-factory';
@@ -129,6 +130,16 @@ export class ExpressHttpApplicationAdapter {
           next();
           return;
         }
+        const nativeMethod = request.method.toUpperCase();
+        const requestPath = splitRawRequestUrl(request.originalUrl || request.url || '/').path;
+        const descriptor = route.descriptorsByMethod[nativeMethod];
+        const params = normalizeNativeRouteParams(request.params);
+        if (descriptor && !isRoutePathNormalizationSensitive(requestPath) && !hasNativeRouteParamSeparators(params)) {
+          bindRawRequestNativeRouteHandoff(request, {
+            descriptor,
+            params
+          });
+        }
         void this.handleRequest(request, response);
       });
     }
@@ -150,38 +161,46 @@ function resolveDispatcherRouteDescriptors(dispatcher) {
 function createExpressNativeRoutes(descriptors) {
   const candidates = new Map();
   const shapePaths = new Map();
+  const versionSensitiveRouteKeys = collectVersionSensitiveRouteKeys(descriptors);
   for (const descriptor of descriptors) {
-    if (descriptor.route.method === 'ALL') {
+    if (!isExpressNativeRouteDescriptor(descriptor) || versionSensitiveRouteKeys.has(`${descriptor.route.method}:${descriptor.route.path}`)) {
       continue;
     }
-    registerExpressNativeRouteCandidate(candidates, shapePaths, descriptor.route.method, descriptor.route.path);
+    registerExpressNativeRouteCandidate(candidates, shapePaths, descriptor);
   }
   const routesByPath = new Map();
   for (const candidate of candidates.values()) {
     if (shapePaths.get(candidate.shapeKey)?.size !== 1) {
       continue;
     }
-    let methods = routesByPath.get(candidate.path);
-    if (!methods) {
-      methods = new Set();
-      routesByPath.set(candidate.path, methods);
+    let route = routesByPath.get(candidate.path);
+    if (!route) {
+      route = {
+        descriptorsByMethod: {},
+        methods: new Set()
+      };
+      routesByPath.set(candidate.path, route);
     }
-    methods.add(candidate.method);
+    route.methods.add(candidate.method);
+    route.descriptorsByMethod[candidate.method] = candidate.descriptor;
   }
-  return [...routesByPath.entries()].map(([path, methods]) => ({
-    methods: [...methods],
+  return [...routesByPath.entries()].map(([path, route]) => ({
+    descriptorsByMethod: route.descriptorsByMethod,
+    methods: [...route.methods],
     path
   }));
 }
-function registerExpressNativeRouteCandidate(candidates, shapePaths, method, path) {
-  if (!EXPRESS_NATIVE_ROUTE_METHODS.includes(method)) {
-    return;
-  }
-  const nativeMethod = method;
+function isExpressNativeRouteDescriptor(descriptor) {
+  return descriptor.route.method !== 'ALL' && EXPRESS_NATIVE_ROUTE_METHODS.includes(descriptor.route.method) && descriptor.route.version === undefined;
+}
+function registerExpressNativeRouteCandidate(candidates, shapePaths, descriptor) {
+  const nativeMethod = descriptor.route.method;
+  const path = descriptor.route.path;
   const routeKey = `${nativeMethod}:${path}`;
   const shapeKey = `${nativeMethod}:${canonicalizeExpressRouteShape(path)}`;
   if (!candidates.has(routeKey)) {
     candidates.set(routeKey, {
+      descriptor,
       method: nativeMethod,
       path,
       shapeKey
@@ -209,6 +228,9 @@ function createExpressRequestResponseFactory(multipartOptions, maxBodySize = DEF
     createResponse(response) {
       return createFrameworkResponse(response);
     },
+    async materializeRequest(request) {
+      await materializeFrameworkRequestBody(request);
+    },
     resolveRequestId(request) {
       return resolveRequestIdFromHeaders(request.headers);
     },
@@ -281,6 +303,18 @@ function createFrameworkResponse(response) {
       this.committed = true;
       response.send(serialized.payload);
     },
+    async sendSimpleJson(body) {
+      if (response.writableEnded) {
+        this.committed = true;
+        return;
+      }
+      const serialized = serializeResponseBody(body);
+      if (!response.hasHeader('content-type') && serialized.defaultContentType) {
+        response.setHeader('content-type', serialized.defaultContentType);
+      }
+      this.committed = true;
+      response.send(serialized.payload);
+    },
     setHeader(name, value) {
       const lowerName = name.toLowerCase();
       if (lowerName === 'set-cookie') {
@@ -321,11 +355,19 @@ function createFrameworkResponseStream(response) {
       };
     },
     waitForDrain() {
-      if (response.writableEnded) {
+      if (response.writableEnded || response.destroyed) {
         return Promise.resolve();
       }
       return new Promise(resolve => {
-        response.once('drain', () => resolve());
+        const settle = () => {
+          response.removeListener('drain', settle);
+          response.removeListener('close', settle);
+          response.removeListener('error', settle);
+          resolve();
+        };
+        response.once('drain', settle);
+        response.once('close', settle);
+        response.once('error', settle);
       });
     },
     write(chunk) {
@@ -335,44 +377,68 @@ function createFrameworkResponseStream(response) {
 }
 async function createFrameworkRequest(request, signal, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false) {
   const rawUrl = request.originalUrl || request.url || '/';
-  const url = new URL(rawUrl, 'http://localhost');
-  const headers = normalizeHeaders(request.headers);
-  const contentType = readPrimaryHeaderValue(headers['content-type']);
-  const isMultipart = typeof contentType === 'string' && contentType.includes('multipart/form-data');
-  let body;
-  let files;
-  let rawBody;
-  if (isMultipart) {
-    const parsed = await parseMultipartRequest(request, {
-      ...multipartOptions,
-      maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
-    });
-    body = parsed.fields;
-    files = parsed.files;
-  } else {
+  const urlParts = splitRawRequestUrl(rawUrl);
+  const headers = normalizeHeaders(cloneRequestHeaders(request.headers));
+  const querySnapshot = snapshotSimpleQueryRecord(request.query);
+  const contentType = normalizePrimaryContentType(headers['content-type']);
+  const isMultipart = contentType === 'multipart/form-data';
+  let frameworkRequest;
+  const materializeBody = createMemoizedAsyncValue(async () => {
+    if (isMultipart) {
+      const parsed = await parseMultipartRequest(request, {
+        ...multipartOptions,
+        maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
+      });
+      frameworkRequest.body = parsed.fields;
+      frameworkRequest.files = parsed.files;
+      return;
+    }
     const bodyResult = await readRequestBody(request, headers['content-type'], maxBodySize, preserveRawBody);
-    body = bodyResult.body;
-    rawBody = bodyResult.rawBody;
-  }
-  const frameworkRequest = {
-    body,
-    cookies: parseCookieHeader(Array.isArray(headers.cookie) ? headers.cookie[0] : headers.cookie),
+    frameworkRequest.body = bodyResult.body;
+    if (bodyResult.rawBody) {
+      frameworkRequest.rawBody = bodyResult.rawBody;
+    }
+  });
+  frameworkRequest = createDeferredFrameworkRequestShell({
+    cookieHeader: headers.cookie,
     headers,
+    materializeBody,
     method: request.method,
-    params: {},
-    path: url.pathname,
-    query: parseQueryParams(url.searchParams),
+    path: urlParts.path,
+    query: querySnapshot,
+    queryFactory: () => parseQueryParamsFromSearch(urlParts.search),
     raw: request,
     signal,
-    url: url.pathname + url.search
-  };
-  if (files) {
-    frameworkRequest.files = files;
+    url: urlParts.path + urlParts.search
+  });
+  const nativeRouteHandoff = consumeRawRequestNativeRouteHandoff(request);
+  return nativeRouteHandoff ? attachFrameworkRequestNativeRouteHandoff(frameworkRequest, nativeRouteHandoff) : frameworkRequest;
+}
+function normalizeNativeRouteParams(params) {
+  if (typeof params !== 'object' || params === null) {
+    return {};
   }
-  if (rawBody) {
-    frameworkRequest.rawBody = rawBody;
+  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 (!EXPRESS_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));
 }
 async function parseMultipartRequest(request, options = {}) {
   try {
@@ -380,7 +446,7 @@ async function parseMultipartRequest(request, options = {}) {
       body: Readable.toWeb(request),
       headers: normalizeHeaders(request.headers),
       method: request.method,
-      url: new URL(request.url ?? '/', 'http://localhost').toString()
+      url: resolveAbsoluteRequestUrl(request.url)
     }, options);
   } catch (error) {
     if (isExpressMultipartTooLargeError(error)) {
@@ -437,57 +503,6 @@ function normalizeHeaders(headers) {
   }
   return normalized;
 }
-function parseQueryParams(searchParams) {
-  const query = {};
-  for (const [key, value] of searchParams.entries()) {
-    const current = query[key];
-    if (current === undefined) {
-      query[key] = value;
-      continue;
-    }
-    if (Array.isArray(current)) {
-      current.push(value);
-      continue;
-    }
-    query[key] = [current, value];
-  }
-  return query;
-}
-function parseCookieHeader(cookieHeader) {
-  if (!cookieHeader) {
-    return {};
-  }
-  return Object.fromEntries(cookieHeader.split(';').map(pair => pair.trim()).filter(Boolean).map(pair => {
-    const index = pair.indexOf('=');
-    if (index === -1) {
-      return [pair.trim(), ''];
-    }
-    const rawValue = pair.slice(index + 1).trim();
-    try {
-      return [pair.slice(0, index).trim(), decodeURIComponent(rawValue)];
-    } catch {
-      return [pair.slice(0, index).trim(), rawValue];
-    }
-  }));
-}
-function createRequestSignal(response) {
-  const controller = new AbortController();
-  const abort = reason => {
-    if (!controller.signal.aborted) {
-      controller.abort(new Error(reason));
-    }
-  };
-  response.once('close', () => {
-    if (!response.writableEnded) {
-      abort('Response closed before response commit.');
-    }
-  });
-  return controller.signal;
-}
-function resolveRequestIdFromHeaders(headers) {
-  const requestId = headers['x-request-id'] ?? headers['x-correlation-id'];
-  return Array.isArray(requestId) ? requestId[0] : requestId;
-}
 function createExpressServer(httpsOptions, app) {
   return httpsOptions ? createHttpsServer(httpsOptions, app) : createHttpServer(app);
 }
@@ -658,8 +673,8 @@ async function readRequestBody(request, contentType, maxBodySize = DEFAULT_MAX_B
       rawBody: preserveRawBody ? rawBody : undefined
     };
   }
-  const primaryContentType = readPrimaryHeaderValue(contentType);
-  if (typeof primaryContentType === 'string' && primaryContentType.includes('application/json')) {
+  const primaryContentType = normalizePrimaryContentType(contentType);
+  if (primaryContentType === 'application/json') {
     try {
       return {
         body: JSON.parse(bodyText),
@@ -669,7 +684,7 @@ async function readRequestBody(request, contentType, maxBodySize = DEFAULT_MAX_B
       throw new BadRequestException('Request body contains invalid JSON.');
     }
   }
-  if (typeof primaryContentType === 'string' && primaryContentType.includes('application/x-www-form-urlencoded')) {
+  if (primaryContentType === 'application/x-www-form-urlencoded') {
     return {
       body: parseUrlEncodedBody(bodyText),
       rawBody: preserveRawBody ? rawBody : undefined
@@ -688,11 +703,9 @@ function parseUrlEncodedBody(bodyText) {
   }
   return fields;
 }
-function readPrimaryHeaderValue(headerValue) {
-  if (Array.isArray(headerValue)) {
-    return headerValue[0];
-  }
-  return headerValue;
+async function materializeFrameworkRequestBody(request) {
+  await request.materializeBody?.();
+  delete request.materializeBody;
 }
 function setMultiValue(target, key, value) {
   const existing = target[key];

package/package.json

@@ -8,7 +8,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,12 +36,13 @@
   ],
   "dependencies": {
     "express": "^5.1.0",
-    "@fluojs/http": "^1.0.0-beta.3",
-    "@fluojs/runtime": "^1.0.0-beta.4"
+    "@fluojs/http": "^1.0.0-beta.5",
+    "@fluojs/runtime": "^1.0.0-beta.7"
   },
   "devDependencies": {
     "@types/express": "^5.0.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@fluojs/di": "^1.0.0-beta.5"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",