@fluojs/platform-express 1.0.6 → 2.0.0

package/README.ko.md

@@ -21,9 +21,15 @@ fluo 런타임을 위한 Express 기반 HTTP 어댑터 패키지입니다.
 npm install @fluojs/platform-express express
 ```
 
+`@fluojs/platform-express`는 Node.js `>=24.0.0 <27`이 필요합니다. Listener-level RFC `QUERY` 요청이 Express와 fluo dispatch에 도달하도록 package manifest는 `engines.node >=24.0.0 <27`을 선언합니다. Node 24 미만과 Node 27 이상은 제외됩니다. Deployment host가 Bun, Deno, Cloudflare Workers라면 fetch-style adapter를 선택하세요.
+
 ## 사용 시점
 
-fluo 애플리케이션의 기본 HTTP 엔진으로 Express를 사용하려는 경우에 이 패키지를 사용합니다. 이는 fluo의 데코레이터 기반 아키텍처 내에서 Express의 강력한 생태계, 성숙한 Node.js 서버 처리 및 친숙한 요청/응답 생명주기를 활용하는 데 유용합니다.
+fluo 애플리케이션의 기본 HTTP 엔진으로 Express를 사용하려는 경우에 이 패키지를 사용합니다. 기존 Express 운영 자산, 호스팅 관례, 서버 통합은 platform boundary 근처에 두고 controller, provider, guard, interceptor, middleware는 fluo 런타임 계약을 유지해야 할 때 유용합니다.
+
+Express를 host로 유지해도 NestJS legacy decorator 또는 reflection metadata semantics는 보존되지 않습니다. HTTP host를 변경하기 전에 controller와 provider를 TC39 표준 데코레이터로 마이그레이션하고, class-level `@Inject(...)`로 constructor token을 선언하며, 명시적 module/provider registration을 사용하세요. `experimentalDecorators`와 `emitDecoratorMetadata`는 비활성화한 상태로 유지해야 하며, Express adapter 교체는 NestJS dependency discovery compatibility layer가 아닙니다.
+
+Express 호환성은 native Express/Connect `(req, res, next)` middleware를 fluo의 애플리케이션 레벨 `middleware` 옵션에 직접 전달할 수 있다는 의미가 아닙니다. 이 옵션은 fluo middleware(`handle(context, next)`) 또는 route-scoped fluo middleware provider를 받습니다. Migration 전용 native handler는 adapter의 명시적 `nativeMiddleware` 옵션에 등록하거나, Fastify, raw Node.js, Bun, Deno, Workers adapter로도 이동할 수 있도록 fluo `Middleware` 계약 뒤에 감싸세요.
 
 ## 빠른 시작
 
@@ -43,16 +49,22 @@ await app.listen();
 
 ## 주요 패턴
 
+### Early Hints
+
+Express response는 underlying Node `ServerResponse`를 사용하는 optional `context.response.earlyHints` capability를 노출합니다. `103` 하나마다 `write(...)`를 await하면 final response 전에 여러 write를 관찰할 수 있습니다. Early field는 Express final header, status, body, commit state와 분리됩니다. Capability가 없으면 unsupported이며 late write와 disconnect는 no-op이 아니라 결정적으로 reject됩니다.
+
 ### 스트리밍 응답 처리 (SSE)
 Express 어댑터는 공유 `SseResponse` 유틸리티를 통해 Server-Sent Events(SSE)를 지원하며, Express 전용 스트림 처리를 추상화합니다.
 
 Express 기반 응답 스트림은 공유 fluo 백프레셔 계약도 따릅니다. `response.stream.waitForDrain()`은 `drain`, `close`, `error` 중 어느 쪽이 먼저 와도 완료되므로, 백프레셔가 풀리기 전에 클라이언트가 연결을 끊어도 스트리밍 작성기가 멈추지 않습니다.
 
 ```typescript
-@Get('events')
-async streamEvents(@Res() res: FrameworkResponse) {
-  const events = new SseResponse();
-  events.send({ data: 'hello' });
+import { Sse, SseResponse, type RequestContext } from '@fluojs/http';
+
+@Sse('events')
+async streamEvents(_input: undefined, ctx: RequestContext) {
+  const events = new SseResponse(ctx);
+  events.send({ data: 'hello' }, { event: 'ready' });
   return events;
 }
 ```
@@ -72,6 +84,47 @@ const adapter = createExpressAdapter(
 );
 ```
 
+### Express/Connect Middleware 경계
+Express adapter는 Express를 host HTTP engine으로 보존하지만 request pipeline middleware는 dispatcher가 소유합니다. Portable middleware는 fluo `Middleware` 계약으로 등록하세요.
+
+Adapter는 Express application을 직접 생성하고 소유하므로 기존 Express application을 채택하거나 재사용하는 방식은 지원하지 않습니다. Native Express handler는 construction-time `nativeMiddleware`로 제공해야 하며, bootstrap 이후 `use(...)`로 native stack에 middleware를 추가하는 방식은 지원하지 않습니다. 이식 가능한 동작은 fluo `Middleware`로 재작성하는 방식을 우선하세요.
+
+```typescript
+import type { Middleware } from '@fluojs/http';
+
+const compressionHeaders: Middleware = {
+  async handle(context, next) {
+    context.response.setHeader('vary', 'Accept-Encoding');
+    await next();
+  },
+};
+
+const app = await fluoFactory.create(AppModule, {
+  adapter: createExpressAdapter({ port: 3000 }),
+  middleware: [compressionHeaders],
+});
+```
+
+`compression()` 같은 Express/Connect function을 fluo middleware로 직접 전달하지 마세요. Migration 중 native handler를 유지해야 한다면 adapter construction이 완료되기 전에 명시적으로 등록하세요.
+
+```typescript
+import type { RequestHandler } from 'express';
+
+const legacyRequestTag: RequestHandler = (_request, response, next) => {
+  response.setHeader('x-migration-host', 'express');
+  next();
+};
+
+const adapter = createExpressAdapter({
+  nativeMiddleware: [legacyRequestTag],
+  port: 3000,
+});
+```
+
+`nativeMiddleware`는 배열 순서대로 adapter의 Express Router와 catch-all fluo dispatch보다 먼저 mount됩니다. `next()`를 호출하면 fluo middleware, guard, interceptor, handler로 계속 진행합니다. Native response를 끝내면 fluo dispatch에 들어가지 않고 그 자리에서 종료됩니다. Throw/rejected error와 `next(error)`는 Express error chain에 남으므로, native Express error handler는 같은 배열에서 자신이 처리할 middleware 뒤에 두세요. Dispatch 전에 발생한 실패는 fluo error filter나 envelope가 변환하지 않습니다.
+
+Native stack은 adapter 생성 시 고정됩니다. Adapter는 Node HTTP/S listener와 connection을 소유하지만 native middleware가 캡처한 timer, client, 기타 resource를 발견하거나 dispose하지 않습니다. 이 resource는 application bootstrap code가 정리해야 합니다. Route behavior, request-context mutation, cross-platform concern은 fluo middleware, guard, interceptor에 두세요.
+
 ### 안전한 fallback을 포함한 Native Route Registration
 어댑터는 의미 보존이 가능한 명시적 `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` route를 Express Router에 사전 등록하면서도, 실제 요청 처리는 계속 공유 fluo dispatcher를 통해 수행합니다.
 
@@ -81,16 +134,24 @@ const adapter = createExpressAdapter(
 
 문서화된 fluo semantics를 바꾸지 않기 위해 `/:id` 와 `/:slug`처럼 shape가 겹치는 파라미터 라우트, `@All(...)` 핸들러, `OPTIONS` 소유권, non-URI versioning, 그리고 duplicate slash/trailing slash 정규화에 의존하는 요청은 catch-all fallback 경로에 남겨둡니다.
 
+### Startup Retry와 Shutdown
+`listen()`은 adapter가 열린 상태인 동안에만 `retryDelayMs` 및 `retryLimit`에 따라 `EADDRINUSE`를 재시도합니다. 동시에 호출된 `listen()`은 서로 겹치는 retry loop를 시작하지 않고 첫 호출자의 in-flight startup lifecycle과 dispatcher를 공유합니다. Startup이 retry loop에서 대기 중일 때 `close()`가 호출되면, underlying Node server가 아직 listening 상태에 도달하지 않았더라도 adapter는 공유 listen attempt를 abort하고 그 작업이 settle될 때까지 기다린 뒤 `close()`를 완료합니다. `close()` 진행 중 호출된 `listen()`은 reject되며 `close()`가 resolve된 뒤 다시 시도할 수 있습니다. `close()`가 resolve된 뒤 막혀 있던 port를 해제해도 adapter가 나중에 bind되지 않으며, 다시 시작하려면 호출자가 명시적으로 `listen()`을 다시 호출해야 합니다.
+
+같은 adapter instance를 close 후 다시 listen하면 traffic을 받기 전에 native route descriptor registry를 새 dispatcher에서 갱신합니다. 유지된 Express Router layer는 현재 descriptor만 resolve하고 그 밖의 경우 full dispatcher matching으로 fallback하므로 native handoff metadata가 이전 application graph를 가리키지 않습니다.
+
 ## 어댑터 계약
 
 - **공유 dispatcher 소유권 유지**: Native Express Router 매치 이후에도 실제 요청은 공유 fluo dispatcher가 처리하므로 middleware, guards, interceptors, observers, params, error envelope 계약은 그대로 유지됩니다.
+- **Express application 소유권**: Adapter가 Express application을 생성하고 소유합니다. 기존 Express application을 채택하지 않고 post-bootstrap `use(...)` mutation도 노출하지 않습니다. 불가피한 native handler는 construction-time `nativeMiddleware`로 제공하고, 이식 가능한 동작은 fluo `Middleware`로 재작성하세요.
+- **Host engine 경계**: Express는 host/platform HTTP engine이지만 fluo는 native Express/Connect middleware를 fluo middleware로 재해석하지 않습니다. Application-level middleware는 공유 `Middleware` 계약을 구현하고, platform-specific `nativeMiddleware` 옵션은 routing 전에 native handler를 mount합니다.
+- **Native middleware 소유권**: Native handler는 선언 순서대로 실행되며 Express continuation, response termination, error-chain semantics를 유지합니다. Adapter shutdown은 listener와 connection을 닫지만 handler가 소유한 resource는 dispose하지 않습니다.
 - **안전한 fallback 범위**: `@All(...)` 핸들러와 shape가 겹치는 파라미터 라우트는 Express Router에 강제 등록하지 않고 의도적으로 catch-all fallback 경로에 둡니다.
 - **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된 요청을 기준으로 다시 매칭합니다.
 - **응답 serialization parity**: String response는 기본적으로 `text/plain`, object/array는 JSON, binary payload는 `application/octet-stream`으로 serialize되며 `set-cookie` 값은 병합됩니다.
-- **Startup과 shutdown**: 어댑터는 HTTP/HTTPS startup, retry option에 따른 `EADDRINUSE` 재시도, close 시 socket drain, 동시에 들어온 `close()` 호출의 단일 in-flight close lifecycle 재사용, shutdown timeout 이후 force-close를 지원하며, `shutdownTimeoutMs`가 `0`이면 즉시 force-close합니다.
+- **Startup과 shutdown**: 어댑터는 HTTP/HTTPS startup, adapter가 열린 상태에서 `retryLimit` 소진 전까지 retry option에 따른 `EADDRINUSE` 재시도, 동시 startup 호출자의 단일 in-flight listen lifecycle 및 dispatcher 재사용, `close()` 중 해당 공유 retry loop를 abort 및 join한 뒤 shutdown 완료 보고, close 진행 중 `listen()` reject, 이미 시작된 adapter에 대한 중복 `listen()` 호출의 idempotent 처리와 live dispatcher 보존, close 후 adapter를 다시 listen할 때 native route descriptor 갱신, 정상 close 시 idle keep-alive socket drain, 동시에 들어온 `close()` 호출의 단일 in-flight close lifecycle 재사용, shutdown timeout 이후 force-close를 지원하며, `shutdownTimeoutMs`가 `0`이면 즉시 force-close합니다.
 
 ## 공개 API 개요
 
@@ -98,10 +159,22 @@ const adapter = createExpressAdapter(
 - `bootstrapExpressApplication(module, options)`: 수동 제어를 위한 고급 부트스트랩 헬퍼입니다.
 - `runExpressApplication(module, options)`: 시그널 연결을 포함한 빠른 시작을 위한 호환 헬퍼입니다. timeout/실패 시에는 해당 상태를 로그와 `process.exitCode`로 보고하고, 최종 프로세스 종료는 주변 호스트에 맡깁니다.
 - `isExpressMultipartTooLargeError(error)`: adapter error shape 전반에서 multipart limit 감지를 정규화합니다.
-- `ExpressHttpApplicationAdapter`: 핵심 어댑터 구현 클래스입니다.
-- Option type: `ExpressAdapterOptions`, `BootstrapExpressApplicationOptions`, `RunExpressApplicationOptions`, `CorsInput`, `ExpressApplicationSignal`.
+- `ExpressServer`: `ExpressHttpApplicationAdapter.getServer()`가 infrastructure boundary에서 반환하는 adapter-owned `node:http` `Server` 또는 `node:https` `Server` union의 공개 type alias입니다.
+- `ExpressHttpApplicationAdapter`: 핵심 어댑터 구현 클래스입니다. `getServer()`는 좁은 platform integration을 위해 underlying Node HTTP/HTTPS server를 노출하며 `ExpressServer`를 반환하고, `getListenTarget()`은 startup 이후 resolved bind target과 public URL을 보고하며, `getRealtimeCapability()`는 realtime package가 사용하는 server-backed capability를 반환합니다. 이러한 helper는 모두 일반 애플리케이션 코드에 native server object를 퍼뜨리기보다 infrastructure boundary에만 두세요.
+- Option type: `ExpressAdapterOptions`, `BootstrapExpressApplicationOptions`, `RunExpressApplicationOptions`, `ExpressNativeMiddleware`, `CorsInput`, `ExpressApplicationSignal`.
+
+`createExpressAdapter(options, multipartOptions?)`는 `host`, `https`, `maxBodySize`, `nativeMiddleware`, `port`, `rawBody`, `retryDelayMs`, `retryLimit`, `shutdownTimeoutMs`를 지원합니다. `ExpressHttpApplicationAdapter`를 직접 생성하는 경우에도 factory와 같은 numeric validation이 적용됩니다.
+
+- `BootstrapExpressApplicationOptions`와 `RunExpressApplicationOptions`는 위의 adapter option과 함께 `cors`, `globalPrefix`, `globalPrefixExclude`, `middleware`, `multipart`, `nativeMiddleware`, `securityHeaders`, `logger`를 공통으로 받습니다.
+- `RunExpressApplicationOptions`만 signal-driven shutdown을 위한 `forceExitTimeoutMs`와 `shutdownSignals`를 추가로 받습니다.
+
+두 helper는 startup/shutdown diagnostics에 framework console logger를 기본으로 사용하며, `logger`가 제공되면 주입된 `ApplicationLogger`를 따릅니다.
+
+## Multipart 스트리밍
+
+Express를 bootstrap할 때 `multipart: { strategy: 'stream' }`을 설정하면 multipart part가 `RequestContext.request.body`의 `AsyncIterable`로 노출됩니다. Express는 iterator를 미리 읽거나 버퍼링하지 않으며, file part를 소비할 때만 바이트를 가져옵니다. 버퍼링 multipart parsing은 기본값이며 fields와 `request.files`를 노출하고, 하나의 request body에서 stream 소비와 함께 사용할 수 없습니다.
 
-`createExpressAdapter(options, multipartOptions?)`는 `host`, `https`, `maxBodySize`, `port`, `rawBody`, `retryDelayMs`, `retryLimit`, `shutdownTimeoutMs`를 지원합니다. `ExpressHttpApplicationAdapter`를 직접 생성하는 경우에도 factory와 같은 numeric validation이 적용됩니다. `bootstrapExpressApplication(...)`과 `runExpressApplication(...)`은 `cors`, `globalPrefix`, `globalPrefixExclude`, `middleware`, `multipart`, `securityHeaders`, `forceExitTimeoutMs`, `shutdownSignals`, `logger`도 받습니다. startup/shutdown diagnostics에는 framework console logger를 기본으로 사용하며, `logger`가 제공되면 주입된 `ApplicationLogger`를 따릅니다.
+Runtime route dispatch는 route를 위해 만든 iterator를 소유하며 handler가 끝난 뒤 자동으로 `return()`을 호출해 active source를 cancel하고 release합니다. Standalone `parseMultipartStream(...)` consumer는 이 책임을 직접 집니다. iterator를 끝까지 소비하거나 일찍 끝낼 때 `return()`을 호출하세요.
 
 ## 관련 패키지
 
@@ -112,4 +185,4 @@ const adapter = createExpressAdapter(
 ## 예제 소스
 
 - `packages/platform-express/src/adapter.test.ts`
-- `examples/minimal/src/main.ts` (Fastify 기반이지만 공유 `fluoFactory` 패턴을 보여줌)
+- 이 패키지는 아직 전용 `examples/platform-express` 앱을 제공하지 않습니다. Express bootstrap 형태는 이 README의 빠른 시작 및 native middleware scenario를 사용하고, native middleware ordering/termination/error propagation, SSE framing, native-route fallback parity, close/relisten 후 native descriptor 갱신, duplicate listen idempotency, retry exhaustion, shutdown 중 startup retry cancellation, idle keep-alive drain, forced shutdown을 포함한 실행 가능한 Express adapter coverage는 `packages/platform-express/src/adapter.test.ts`를 사용하세요. `examples/minimal/src/main.ts`는 Fastify 기반이므로 Express 예제 소스로 취급하지 않아야 합니다.

package/README.md

@@ -21,9 +21,15 @@ Express-backed HTTP adapter for the fluo runtime.
 npm install @fluojs/platform-express express
 ```
 
+`@fluojs/platform-express` requires Node.js `>=24.0.0 <27`. Its package manifest declares `engines.node >=24.0.0 <27` so listener-level RFC `QUERY` requests reach Express and fluo dispatch; Node versions below 24 and Node 27+ are excluded. Choose a fetch-style adapter instead when the deployment host is Bun, Deno, or Cloudflare Workers.
+
 ## When to Use
 
-Use this package when you want to run a fluo application using Express as the underlying HTTP engine. This is useful for leveraging Express's robust ecosystem, mature Node.js server handling, and familiar request/response lifecycle within the fluo decorator-based architecture.
+Use this package when you want to run a fluo application using Express as the underlying HTTP engine. This is useful when existing Express operational assets, hosting conventions, or server integrations need to stay near the platform boundary while controllers, providers, guards, interceptors, and middleware keep using fluo's runtime contracts.
+
+Keeping Express as the host does not preserve NestJS legacy decorator or reflection-metadata semantics. Before changing the HTTP host, migrate controllers and providers to TC39 standard decorators, declare constructor tokens with class-level `@Inject(...)`, and use explicit module/provider registration. Keep `experimentalDecorators` and `emitDecoratorMetadata` disabled; an Express adapter replacement is not a compatibility layer for NestJS dependency discovery.
+
+Express compatibility does not mean that native Express/Connect `(req, res, next)` middleware can be passed directly to fluo's application-level `middleware` option. That option accepts fluo middleware (`handle(context, next)`) or route-scoped fluo middleware providers. Register migration-only native handlers through the adapter's explicit `nativeMiddleware` option, or wrap the behavior behind the fluo `Middleware` contract so it remains portable to Fastify, raw Node.js, Bun, Deno, and Workers adapters.
 
 ## Quick Start
 
@@ -43,16 +49,22 @@ await app.listen();
 
 ## Common Patterns
 
+### Early Hints
+
+Express responses expose the optional `context.response.earlyHints` capability backed by the underlying Node `ServerResponse`. Await one `write(...)` per `103`; multiple writes are observable before the final response. Early fields stay separate from Express final headers, status, body, and commit state. Missing capability means unsupported, while late writes and disconnects reject deterministically instead of becoming no-ops.
+
 ### 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) {
-  const events = new SseResponse();
-  events.send({ data: 'hello' });
+import { Sse, SseResponse, type RequestContext } from '@fluojs/http';
+
+@Sse('events')
+async streamEvents(_input: undefined, ctx: RequestContext) {
+  const events = new SseResponse(ctx);
+  events.send({ data: 'hello' }, { event: 'ready' });
   return events;
 }
 ```
@@ -72,6 +84,47 @@ const adapter = createExpressAdapter(
 );
 ```
 
+### Express/Connect Middleware Boundary
+The Express adapter preserves Express as the host HTTP engine, but request pipeline middleware remains dispatcher-owned. Register portable middleware through the fluo `Middleware` contract:
+
+The adapter constructs and owns its Express application. Adopting or reusing an existing Express application is unsupported. Native Express handlers must be supplied through construction-time `nativeMiddleware`; after bootstrap, calling `use(...)` to append to the native stack is not a supported surface. Prefer rewriting portable behavior as fluo `Middleware`.
+
+```typescript
+import type { Middleware } from '@fluojs/http';
+
+const compressionHeaders: Middleware = {
+  async handle(context, next) {
+    context.response.setHeader('vary', 'Accept-Encoding');
+    await next();
+  },
+};
+
+const app = await fluoFactory.create(AppModule, {
+  adapter: createExpressAdapter({ port: 3000 }),
+  middleware: [compressionHeaders],
+});
+```
+
+Do not pass an Express/Connect function such as `compression()` directly as fluo middleware. If a migration must retain a native handler, register it explicitly before adapter construction completes:
+
+```typescript
+import type { RequestHandler } from 'express';
+
+const legacyRequestTag: RequestHandler = (_request, response, next) => {
+  response.setHeader('x-migration-host', 'express');
+  next();
+};
+
+const adapter = createExpressAdapter({
+  nativeMiddleware: [legacyRequestTag],
+  port: 3000,
+});
+```
+
+`nativeMiddleware` is mounted in array order before the adapter's Express Router and catch-all fluo dispatch. Calling `next()` continues into fluo middleware, guards, interceptors, and handlers. Ending the native response stops there without entering fluo dispatch. Thrown/rejected errors and `next(error)` remain in the Express error chain, so place any native Express error handler after the middleware it handles in the same array; fluo error filters and envelopes do not translate failures that occur before dispatch.
+
+The native stack is fixed when the adapter is created. The adapter owns its Node HTTP/S listener and connections, but it does not discover or dispose timers, clients, or other resources captured by native middleware; application bootstrap code must release those resources. Keep route behavior, request-context mutation, and cross-platform concerns in fluo middleware, guards, or interceptors.
+
 ### Native Route Registration with Safe Fallback
 The adapter pre-registers semantically safe Express Router handlers for explicit `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `HEAD` routes and still dispatches those requests through the shared fluo dispatcher.
 
@@ -81,16 +134,24 @@ If app middleware rewrites the framework request method or path after the adapte
 
 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.
 
+### Startup Retry and Shutdown
+`listen()` retries `EADDRINUSE` according to `retryDelayMs` and `retryLimit` only while the adapter remains open. Concurrent `listen()` calls share the first caller's in-flight startup lifecycle and dispatcher instead of starting overlapping retry loops. If `close()` is called while startup is waiting in that retry loop, the adapter aborts the shared listen attempt and waits for it to settle before `close()` resolves, even when the underlying Node server has not reached the listening state yet. A `listen()` call made while `close()` is in progress rejects and can be retried after `close()` resolves. Releasing the blocked port after `close()` resolves cannot make the adapter bind later; callers must invoke `listen()` again explicitly to start it.
+
+If the same adapter instance is listened again after close, its native route descriptor registry refreshes from the new dispatcher before traffic is served. Retained Express Router layers resolve only current descriptors and otherwise fall back to full dispatcher matching, so native handoff metadata never points at a previous application graph.
+
 ## Adapter Contract
 
 - **Shared dispatcher ownership**: Native Express Router matches still hand off to the shared fluo dispatcher, so middleware, guards, interceptors, observers, params, and error envelopes remain framework-defined.
+- **Express application ownership**: The adapter constructs and owns its Express application. It does not adopt an existing Express application, and it does not expose post-bootstrap `use(...)` mutation. Supply unavoidable native handlers through construction-time `nativeMiddleware`; prefer rewriting portable behavior as fluo `Middleware`.
+- **Host engine boundary**: Express is the host/platform HTTP engine, but fluo does not reinterpret native Express/Connect middleware as fluo middleware; application-level middleware must implement the shared `Middleware` contract, while the platform-specific `nativeMiddleware` option mounts native handlers before routing.
+- **Native middleware ownership**: Native handlers run in declared order and retain Express continuation, response termination, and error-chain semantics. Adapter shutdown closes the listener and connections but does not dispose resources owned by those handlers.
 - **Safe fallback scope**: `@All(...)` handlers and overlapping same-shape param routes intentionally stay on the catch-all fallback path instead of being force-registered through Express Router.
 - **OPTIONS ownership parity**: The adapter prevents Express Router from auto-answering `OPTIONS` for native routes, so unsupported methods still fall through to fluo dispatcher semantics and `@All(...)` handlers can continue to own `OPTIONS` when defined.
 - **Path normalization parity**: Requests that Express Router does not normalize the same way as fluo, such as duplicate-slash variants, still resolve through fallback dispatch so fluo's normalized route contract is preserved.
 - **Versioning parity**: Header/media-type/custom version selection remains dispatcher-owned even when Express Router handles the initial path match.
 - **Middleware rewrite parity**: App middleware that rewrites method or path invalidates native handoff and rematches the rewritten request.
 - **Response serialization parity**: String responses default to `text/plain`, objects/arrays serialize as JSON, binary payloads default to `application/octet-stream`, and `set-cookie` values are merged.
-- **Startup and shutdown**: The adapter supports HTTP/HTTPS startup, retries `EADDRINUSE` according to retry options, drains sockets on close, reuses one in-flight close lifecycle for concurrent `close()` calls, and can force-close connections after shutdown timeout, including immediate force-close when `shutdownTimeoutMs` is `0`.
+- **Startup and shutdown**: The adapter supports HTTP/HTTPS startup, retries `EADDRINUSE` according to retry options until `retryLimit` is exhausted while the adapter is open, reuses one in-flight listen lifecycle and its dispatcher for concurrent startup callers, aborts and joins that shared retry loop during `close()` before shutdown completion is reported, rejects `listen()` while close is in progress, treats duplicate `listen()` calls on an already-started adapter as idempotent without replacing the live dispatcher, refreshes native route descriptors when the adapter is listened again after close, drains idle keep-alive sockets on normal close, reuses one in-flight close lifecycle for concurrent `close()` calls, and can force-close connections after shutdown timeout, including immediate force-close when `shutdownTimeoutMs` is `0`.
 
 ## Public API Overview
 
@@ -98,10 +159,22 @@ To avoid changing documented fluo semantics, overlapping same-shape param routes
 - `bootstrapExpressApplication(module, options)`: Advanced bootstrap helper for manual control.
 - `runExpressApplication(module, options)`: Compatibility helper for quick startup with signal wiring. On timeout/failure it reports the condition through logging and `process.exitCode`, while leaving final process termination to the surrounding host.
 - `isExpressMultipartTooLargeError(error)`: Normalizes multipart limit detection across adapter error shapes.
-- `ExpressHttpApplicationAdapter`: The core adapter implementation class.
-- Option types: `ExpressAdapterOptions`, `BootstrapExpressApplicationOptions`, `RunExpressApplicationOptions`, `CorsInput`, `ExpressApplicationSignal`.
+- `ExpressServer`: Public type alias for the adapter-owned `node:http` `Server` or `node:https` `Server` union returned by `ExpressHttpApplicationAdapter.getServer()` at infrastructure boundaries.
+- `ExpressHttpApplicationAdapter`: The core adapter implementation class. `getServer()` exposes the underlying Node HTTP/HTTPS server for narrow platform integrations and returns `ExpressServer`, `getListenTarget()` reports the resolved bind target and public URL after startup, and `getRealtimeCapability()` returns the server-backed capability used by realtime packages. Keep these helpers at infrastructure boundaries instead of threading native server objects through ordinary application code.
+- Option types: `ExpressAdapterOptions`, `BootstrapExpressApplicationOptions`, `RunExpressApplicationOptions`, `ExpressNativeMiddleware`, `CorsInput`, `ExpressApplicationSignal`.
+
+`createExpressAdapter(options, multipartOptions?)` supports `host`, `https`, `maxBodySize`, `nativeMiddleware`, `port`, `rawBody`, `retryDelayMs`, `retryLimit`, and `shutdownTimeoutMs`. Direct `ExpressHttpApplicationAdapter` construction applies the same numeric validation as the factory.
+
+- `BootstrapExpressApplicationOptions` and `RunExpressApplicationOptions` share `cors`, `globalPrefix`, `globalPrefixExclude`, `middleware`, `multipart`, `nativeMiddleware`, `securityHeaders`, and `logger` in addition to the adapter options above.
+- `RunExpressApplicationOptions` alone adds `forceExitTimeoutMs` and `shutdownSignals` for signal-driven shutdown.
+
+Both helpers use the framework console logger by default for startup and shutdown diagnostics and honor an injected `ApplicationLogger` when `logger` is provided.
+
+## Multipart streaming
+
+Set `multipart: { strategy: 'stream' }` when bootstrapping Express to expose multipart parts through `RequestContext.request.body` as an `AsyncIterable`. Express creates the iterator without pre-reading or buffering it; consuming a file part pulls its bytes on demand. Buffered multipart parsing remains the default, exposes fields and `request.files`, and cannot be combined with stream consumption for the same request body.
 
-`createExpressAdapter(options, multipartOptions?)` supports `host`, `https`, `maxBodySize`, `port`, `rawBody`, `retryDelayMs`, `retryLimit`, and `shutdownTimeoutMs`. Direct `ExpressHttpApplicationAdapter` construction applies the same numeric validation as the factory. `bootstrapExpressApplication(...)` and `runExpressApplication(...)` also accept `cors`, `globalPrefix`, `globalPrefixExclude`, `middleware`, `multipart`, `securityHeaders`, `forceExitTimeoutMs`, `shutdownSignals`, and `logger`; they use the framework console logger by default for startup and shutdown diagnostics and honor an injected `ApplicationLogger` when provided.
+Runtime route dispatch owns an iterator created for a route and automatically calls `return()` after the handler finishes, cancelling and releasing an active source. Standalone `parseMultipartStream(...)` consumers own that responsibility: consume the iterator to completion or call `return()` when ending early.
 
 ## Related Packages
 
@@ -112,4 +185,4 @@ To avoid changing documented fluo semantics, overlapping same-shape param routes
 ## Example Sources
 
 - `packages/platform-express/src/adapter.test.ts`
-- `examples/minimal/src/main.ts` (Fastify-based, but demonstrates the shared `fluoFactory` pattern)
+- This package does not currently ship a dedicated `examples/platform-express` app. Use the Quick Start and native middleware scenario in this README for Express bootstrap shape and `packages/platform-express/src/adapter.test.ts` for executable Express adapter coverage, including native middleware ordering/termination/error propagation, SSE framing, native-route fallback parity, native descriptor refresh after close/relisten, duplicate listen idempotency, retry exhaustion, startup retry cancellation during shutdown, idle keep-alive drain, and forced shutdown. `examples/minimal/src/main.ts` is Fastify-based and should not be treated as an Express example source.

package/dist/adapter.d.ts

@@ -1,12 +1,14 @@
-import { type ServerOptions as HttpsServerOptions } from 'node:https';
+import type { Server as HttpServer } from 'node:http';
+import { type Server as HttpsServer, 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';
+import { type ErrorRequestHandler, type RequestHandler } from 'express';
+/**
+ * Defines a native Express/Connect middleware handler registered before fluo routing.
+ *
+ * @remarks Native middleware remains platform-specific and follows Express response and error-chain semantics.
+ */
+export type ExpressNativeMiddleware = RequestHandler | ErrorRequestHandler;
 /**
  * Describes the express adapter options contract.
  */
@@ -14,6 +16,7 @@ export interface ExpressAdapterOptions {
     host?: string;
     https?: HttpsServerOptions;
     maxBodySize?: number;
+    nativeMiddleware?: readonly ExpressNativeMiddleware[];
     port?: number;
     rawBody?: boolean;
     retryDelayMs?: number;
@@ -41,6 +44,7 @@ export interface BootstrapExpressApplicationOptions extends Omit<CreateApplicati
     maxBodySize?: number;
     middleware?: MiddlewareLike[];
     multipart?: MultipartOptions;
+    nativeMiddleware?: readonly ExpressNativeMiddleware[];
     port?: number;
     rawBody?: boolean;
     retryDelayMs?: number;
@@ -59,6 +63,10 @@ interface ExpressListenTarget {
     bindTarget: string;
     url: string;
 }
+/**
+ * The Node.js HTTP or HTTPS server owned by the Express adapter.
+ */
+export type ExpressServer = HttpServer | HttpsServer;
 /**
  * Represents the express http application adapter.
  */
@@ -72,16 +80,25 @@ export declare class ExpressHttpApplicationAdapter implements HttpApplicationAda
     private readonly maxBodySize;
     private readonly preserveRawBody;
     private readonly shutdownTimeoutMs;
+    private closing;
     private closeInFlight?;
     private dispatcher?;
+    private listenAbortController?;
+    private listenInFlight?;
     private readonly app;
+    private readonly nativeRouteDescriptors;
     private nativeRoutesReady;
     private readonly requestResponseFactory;
     private readonly router;
     private readonly server;
     private readonly sockets;
-    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;
+    constructor(port: number, host: string | undefined, retryDelayMs: number | undefined, retryLimit: number | undefined, httpsOptions: HttpsServerOptions | undefined, multipartOptions?: MultipartOptions | undefined, maxBodySize?: number, preserveRawBody?: boolean, shutdownTimeoutMs?: number, nativeMiddleware?: readonly ExpressNativeMiddleware[]);
+    /**
+     * Returns the Node.js HTTP or HTTPS server owned by this adapter.
+     *
+     * @returns The platform-owned Node.js HTTP or HTTPS server.
+     */
+    getServer(): ExpressServer;
     getRealtimeCapability(): import("@fluojs/http").ServerBackedHttpAdapterRealtimeCapability;
     getListenTarget(): ExpressListenTarget;
     listen(dispatcher: Dispatcher): Promise<void>;

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,15 +1,20 @@
 import { createServer as createHttpServer } from 'node:http';
 import { createServer as createHttpsServer } from 'node:https';
-import { Readable } from 'node:stream';
 import { BadRequestException, createErrorResponse, createServerBackedHttpAdapterRealtimeCapability, HttpException, InternalServerErrorException, PayloadTooLargeException } from '@fluojs/http';
 import { attachFrameworkRequestNativeRouteHandoff, bindRawRequestNativeRouteHandoff, consumeRawRequestNativeRouteHandoff, isRoutePathNormalizationSensitive } from '@fluojs/http/internal';
 import { bootstrapHttpAdapterApplication, runHttpAdapterApplication } from '@fluojs/runtime/internal/http-adapter';
-import { dispatchWithRequestResponseFactory } from '@fluojs/runtime/internal/request-response-factory';
-import { cloneRequestHeaders, createDeferredFrameworkRequestShell, createMemoizedAsyncValue, createRequestSignal, normalizePrimaryContentType, parseQueryParamsFromSearch, resolveAbsoluteRequestUrl, resolveRequestIdFromHeaders, snapshotSimpleQueryRecord, splitRawRequestUrl } from '@fluojs/runtime/internal-node';
-import { createConsoleApplicationLogger, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/runtime/node';
-import { parseMultipart } from '@fluojs/runtime/web';
+import { dispatchWithRequestResponseFactory, finalizeRouteOwnedMultipartBody } from '@fluojs/runtime/internal/request-response-factory';
+import { cloneRequestHeaders, createNodeEarlyHintsCapability, createDeferredFrameworkRequestShell, createMemoizedAsyncValue, createRequestSignal, normalizePrimaryContentType, parseQueryParamsFromSearch, resolveRequestIdFromHeaders, snapshotSimpleQueryRecord, splitRawRequestUrl } from '@fluojs/platform-nodejs/internal';
+import { createConsoleApplicationLogger, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals } from '@fluojs/platform-nodejs';
+import { parseMultipart, parseMultipartStream } from '@fluojs/runtime/web';
 import express from 'express';
 
+/**
+ * Defines a native Express/Connect middleware handler registered before fluo routing.
+ *
+ * @remarks Native middleware remains platform-specific and follows Express response and error-chain semantics.
+ */
+
 /**
  * Describes the express adapter options contract.
  */
@@ -34,19 +39,31 @@ const EXPRESS_NATIVE_ROUTE_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', '
  * Describes the run express application options contract.
  */
 
+/**
+ * The Node.js HTTP or HTTPS server owned by the Express adapter.
+ */
+
+function isExpressResponseTerminated(response) {
+  return response.writableEnded || response.destroyed;
+}
+
 /**
  * Represents the express http application adapter.
  */
 export class ExpressHttpApplicationAdapter {
+  closing = false;
   closeInFlight;
   dispatcher;
+  listenAbortController;
+  listenInFlight;
   app;
+  nativeRouteDescriptors = new Map();
   nativeRoutesReady = false;
   requestResponseFactory;
   router = express.Router();
   server;
   sockets = new Set();
-  constructor(port, host, retryDelayMs = 150, retryLimit = 20, httpsOptions, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+  constructor(port, host, retryDelayMs = 150, retryLimit = 20, httpsOptions, multipartOptions, maxBodySize = DEFAULT_MAX_BODY_SIZE, preserveRawBody = false, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS, nativeMiddleware = []) {
     this.port = port;
     this.host = host;
     this.retryDelayMs = retryDelayMs;
@@ -62,10 +79,16 @@ export class ExpressHttpApplicationAdapter {
     resolveNonNegativeIntegerOption('maxBodySize', this.maxBodySize, DEFAULT_MAX_BODY_SIZE);
     resolveNonNegativeIntegerOption('shutdownTimeoutMs', this.shutdownTimeoutMs, DEFAULT_SHUTDOWN_TIMEOUT_MS);
     this.app = express();
+    for (const middleware of nativeMiddleware) {
+      this.app.use(middleware);
+    }
     this.requestResponseFactory = createExpressRequestResponseFactory(this.multipartOptions, this.maxBodySize, this.preserveRawBody);
     this.server = createExpressServer(this.httpsOptions, this.app);
     this.app.use(this.router);
     this.app.use((request, response) => {
+      if (isExpressResponseTerminated(response)) {
+        return;
+      }
       void this.handleRequest(request, response);
     });
     this.server.on('connection', socket => {
@@ -75,6 +98,12 @@ export class ExpressHttpApplicationAdapter {
       });
     });
   }
+
+  /**
+   * Returns the Node.js HTTP or HTTPS server owned by this adapter.
+   *
+   * @returns The platform-owned Node.js HTTP or HTTPS server.
+   */
   getServer() {
     return this.server;
   }
@@ -85,57 +114,107 @@ export class ExpressHttpApplicationAdapter {
     return resolveListenTarget(this.server.address() ?? null, this.port, this.host, this.httpsOptions !== undefined);
   }
   async listen(dispatcher) {
+    if (this.closing) {
+      throw new Error('Express adapter is closing. Wait for close() to complete before listen().');
+    }
+    if (this.server.listening) {
+      return;
+    }
+    if (this.listenInFlight) {
+      await this.listenInFlight;
+      return;
+    }
     this.dispatcher = dispatcher;
     this.registerNativeRoutes(dispatcher);
-    await this.listenWithRetry();
+    const abortController = new AbortController();
+    this.listenAbortController = abortController;
+    const listenInFlight = this.listenWithRetry(abortController.signal).finally(() => {
+      if (this.listenInFlight === listenInFlight) {
+        this.listenInFlight = undefined;
+      }
+      if (this.listenAbortController === abortController) {
+        this.listenAbortController = undefined;
+      }
+    });
+    this.listenInFlight = listenInFlight;
+    await listenInFlight;
   }
   async close() {
     if (this.closeInFlight) {
       await waitForCloseWithTimeout(this.closeInFlight, this.shutdownTimeoutMs);
       return;
     }
-    if (!this.server.listening) {
-      this.dispatcher = undefined;
-      return;
-    }
-    const closePromise = closeServerWithDrain(this.server, this.sockets, this.shutdownTimeoutMs);
+    this.closing = true;
+    const closePromise = (async () => {
+      if (this.listenInFlight) {
+        this.listenAbortController?.abort();
+        await waitForCloseWithTimeout(ignoreCancelledListen(this.listenInFlight), this.shutdownTimeoutMs);
+      }
+      if (this.server.listening) {
+        await closeServerWithDrain(this.server, this.sockets, this.shutdownTimeoutMs);
+      }
+    })();
     const closeInFlight = closePromise.finally(() => {
+      this.closing = false;
       this.closeInFlight = undefined;
       this.dispatcher = undefined;
+      this.nativeRouteDescriptors.clear();
     });
     this.closeInFlight = closeInFlight;
     void closeInFlight.catch(() => {});
     await waitForCloseWithTimeout(closeInFlight, this.shutdownTimeoutMs);
   }
-  async listenWithRetry() {
+  async listenWithRetry(signal) {
     for (let attempt = 0;; attempt++) {
+      throwIfListenCancelled(signal);
       try {
-        await listenServer(this.server, this.port, this.host);
+        await listenServer({
+          host: this.host,
+          port: this.port,
+          server: this.server,
+          signal
+        });
+        if (signal.aborted) {
+          await closeServerBestEffort(this.server);
+          throw new ExpressListenCancelledError();
+        }
         return;
       } catch (error) {
         if (!isAddressInUseError(error) || attempt >= this.retryLimit) {
           throw error;
         }
         await closeServerSilently(this.server);
-        await delay(this.retryDelayMs);
+        await delay(this.retryDelayMs, signal);
       }
     }
   }
   registerNativeRoutes(dispatcher) {
+    const nativeRoutes = createExpressNativeRoutes(resolveDispatcherRouteDescriptors(dispatcher));
+    this.nativeRouteDescriptors.clear();
+    for (const route of nativeRoutes) {
+      for (const method of route.methods) {
+        const descriptor = route.descriptorsByMethod[method];
+        if (descriptor) {
+          this.nativeRouteDescriptors.set(`${method}:${route.path}`, descriptor);
+        }
+      }
+    }
     if (this.nativeRoutesReady) {
       return;
     }
-    const nativeRoutes = createExpressNativeRoutes(resolveDispatcherRouteDescriptors(dispatcher));
     Reflect.set(this.router, '__fluoNativeRoutes', nativeRoutes);
     for (const route of nativeRoutes) {
       this.router.all(route.path, (request, response, next) => {
+        if (isExpressResponseTerminated(response)) {
+          return;
+        }
         if (!route.methods.includes(request.method.toUpperCase())) {
           next();
           return;
         }
         const nativeMethod = request.method.toUpperCase();
         const requestPath = splitRawRequestUrl(request.originalUrl || request.url || '/').path;
-        const descriptor = route.descriptorsByMethod[nativeMethod];
+        const descriptor = this.nativeRouteDescriptors.get(`${nativeMethod}:${route.path}`);
         const params = normalizeNativeRouteParams(request.params);
         if (descriptor && !isRoutePathNormalizationSensitive(requestPath) && !hasNativeRouteParamSeparators(params)) {
           void this.handleNativeRouteRequest(descriptor, params, request, response);
@@ -168,8 +247,9 @@ export class ExpressHttpApplicationAdapter {
     const factory = this.requestResponseFactory;
     const frameworkResponse = factory.createResponse(response, request);
     const signal = factory.createRequestSignal(response);
+    let frameworkRequest;
     try {
-      const frameworkRequest = attachFrameworkRequestNativeRouteHandoff(await factory.createRequest(request, signal), {
+      frameworkRequest = attachFrameworkRequestNativeRouteHandoff(await factory.createRequest(request, signal), {
         descriptor,
         params
       });
@@ -189,6 +269,8 @@ export class ExpressHttpApplicationAdapter {
         return;
       }
       await factory.writeErrorResponse(error, frameworkResponse, factory.resolveRequestId(request));
+    } finally {
+      await finalizeRouteOwnedMultipartBody(frameworkRequest);
     }
   }
 }
@@ -287,7 +369,7 @@ function createExpressRequestResponseFactory(multipartOptions, maxBodySize = DEF
  * @returns The create express adapter result.
  */
 export function createExpressAdapter(options = {}, multipartOptions) {
-  return new ExpressHttpApplicationAdapter(resolvePort(options.port), options.host, resolveNonNegativeIntegerOption('retryDelayMs', options.retryDelayMs, 150), resolveNonNegativeIntegerOption('retryLimit', options.retryLimit, 20), options.https, multipartOptions, resolveNonNegativeIntegerOption('maxBodySize', options.maxBodySize, DEFAULT_MAX_BODY_SIZE), options.rawBody, resolveNonNegativeIntegerOption('shutdownTimeoutMs', options.shutdownTimeoutMs, DEFAULT_SHUTDOWN_TIMEOUT_MS));
+  return new ExpressHttpApplicationAdapter(resolvePort(options.port), options.host, resolveNonNegativeIntegerOption('retryDelayMs', options.retryDelayMs, 150), resolveNonNegativeIntegerOption('retryLimit', options.retryLimit, 20), options.https, multipartOptions, resolveNonNegativeIntegerOption('maxBodySize', options.maxBodySize, DEFAULT_MAX_BODY_SIZE), options.rawBody, resolveNonNegativeIntegerOption('shutdownTimeoutMs', options.shutdownTimeoutMs, DEFAULT_SHUTDOWN_TIMEOUT_MS), options.nativeMiddleware);
 }
 
 /**
@@ -318,9 +400,12 @@ export async function runExpressApplication(rootModule, options) {
   }, adapter, logger);
 }
 function createFrameworkResponse(response) {
-  return {
+  const headers = Object.fromEntries(Object.entries(response.getHeaders()).filter(entry => entry[1] !== undefined).map(([name, value]) => [name, typeof value === 'number' ? String(value) : value]));
+  let frameworkResponse;
+  frameworkResponse = {
     committed: response.headersSent || response.writableEnded,
-    headers: {},
+    earlyHints: createNodeEarlyHintsCapability(response, () => frameworkResponse.committed),
+    headers,
     raw: response,
     stream: createFrameworkResponseStream(response),
     redirect(status, location) {
@@ -329,11 +414,19 @@ function createFrameworkResponse(response) {
       this.committed = true;
       response.redirect(status, location);
     },
-    async send(body) {
+    async send(body, options) {
       if (response.writableEnded) {
         this.committed = true;
         return;
       }
+      if (options?.compression === false) {
+        disableNativeCompression(response);
+      }
+      if (body === undefined && response.req.method.toUpperCase() === 'HEAD') {
+        this.committed = true;
+        response.end();
+        return;
+      }
       const existingContentType = response.getHeader('content-type');
       const serialized = serializeResponseBody(body, typeof existingContentType === 'string' ? existingContentType : undefined);
       if (!response.hasHeader('content-type') && serialized.defaultContentType) {
@@ -373,6 +466,14 @@ function createFrameworkResponse(response) {
     statusCode: undefined,
     statusSet: false
   };
+  return frameworkResponse;
+}
+function disableNativeCompression(response) {
+  const cacheControl = response.getHeader('cache-control');
+  const value = Array.isArray(cacheControl) ? cacheControl.join(', ') : String(cacheControl ?? '');
+  if (!/\bno-transform\b/i.test(value)) {
+    response.setHeader('Cache-Control', value ? `${value}, no-transform` : 'no-transform');
+  }
 }
 function createFrameworkResponseStream(response) {
   return {
@@ -384,6 +485,9 @@ function createFrameworkResponseStream(response) {
     get closed() {
       return response.writableEnded;
     },
+    disableCompression() {
+      disableNativeCompression(response);
+    },
     flush() {
       response.flushHeaders?.();
     },
@@ -393,20 +497,33 @@ function createFrameworkResponseStream(response) {
         response.removeListener('close', listener);
       };
     },
+    onError(listener) {
+      response.on('error', listener);
+      return () => {
+        response.removeListener('error', listener);
+      };
+    },
     waitForDrain() {
       if (response.writableEnded || response.destroyed) {
         return Promise.resolve();
       }
-      return new Promise(resolve => {
-        const settle = () => {
-          response.removeListener('drain', settle);
-          response.removeListener('close', settle);
-          response.removeListener('error', settle);
+      return new Promise((resolve, reject) => {
+        const cleanup = () => {
+          response.removeListener('drain', resolveDrain);
+          response.removeListener('close', resolveDrain);
+          response.removeListener('error', rejectError);
+        };
+        const rejectError = error => {
+          cleanup();
+          reject(error);
+        };
+        const resolveDrain = () => {
+          cleanup();
           resolve();
         };
-        response.once('drain', settle);
-        response.once('close', settle);
-        response.once('error', settle);
+        response.once('drain', resolveDrain);
+        response.once('close', resolveDrain);
+        response.once('error', rejectError);
       });
     },
     write(chunk) {
@@ -424,10 +541,21 @@ async function createFrameworkRequest(request, signal, multipartOptions, maxBody
   let frameworkRequest;
   const materializeBody = createMemoizedAsyncValue(async () => {
     if (isMultipart) {
-      const parsed = await parseMultipartRequest(request, {
+      const resolvedMultipartOptions = {
         ...multipartOptions,
         maxTotalSize: multipartOptions?.maxTotalSize ?? maxBodySize
-      });
+      };
+      if (multipartOptions?.strategy === 'stream') {
+        frameworkRequest.body = parseMultipartStream({
+          body: request,
+          headers,
+          method: request.method,
+          signal,
+          url: rawUrl
+        }, resolvedMultipartOptions);
+        return;
+      }
+      const parsed = await parseMultipartRequest(request, resolvedMultipartOptions);
       frameworkRequest.body = parsed.fields;
       frameworkRequest.files = parsed.files;
       return;
@@ -481,12 +609,14 @@ function collectVersionSensitiveRouteKeys(descriptors) {
 }
 async function parseMultipartRequest(request, options = {}) {
   try {
-    return await parseMultipart({
-      body: Readable.toWeb(request),
-      headers: normalizeHeaders(request.headers),
-      method: request.method,
-      url: resolveAbsoluteRequestUrl(request.url)
-    }, options);
+    const result = await parseMultipart(request, options);
+    return {
+      fields: result.fields,
+      files: result.files.map(file => ({
+        ...file,
+        buffer: Buffer.from(file.buffer)
+      }))
+    };
   } catch (error) {
     if (isExpressMultipartTooLargeError(error)) {
       if (error instanceof PayloadTooLargeException) {
@@ -580,33 +710,74 @@ function resolveNonNegativeIntegerOption(name, value, defaultValue) {
   }
   return resolved;
 }
-async function listenServer(server, port, host) {
+async function listenServer(input) {
+  const {
+    host,
+    port,
+    server,
+    signal
+  } = input;
   await new Promise((resolve, reject) => {
-    const onError = error => {
-      cleanup();
-      reject(error);
-    };
-    const onListening = () => {
+    if (signal.aborted) {
+      reject(new ExpressListenCancelledError());
+      return;
+    }
+    let settled = false;
+    function onError(error) {
+      finishReject(error);
+    }
+    function onListening() {
+      finishResolve();
+    }
+    function onAbort() {
       cleanup();
-      resolve();
-    };
-    const cleanup = () => {
+      void closeServerBestEffort(server).then(() => {
+        finishReject(new ExpressListenCancelledError());
+      });
+    }
+    function cleanup() {
       server.off('error', onError);
       server.off('listening', onListening);
-    };
+      signal.removeEventListener('abort', onAbort);
+    }
+    function finishResolve() {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve();
+    }
+    function finishReject(error) {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      reject(error);
+    }
     server.once('error', onError);
     server.once('listening', onListening);
+    signal.addEventListener('abort', onAbort, {
+      once: true
+    });
     try {
       server.listen({
         host,
         port
       });
     } catch (error) {
-      cleanup();
-      reject(error);
+      finishReject(error);
     }
   });
 }
+function closeServerBestEffort(server) {
+  return new Promise(resolve => {
+    server.close(() => {
+      resolve();
+    });
+  });
+}
 function closeServerSilently(server) {
   if (!server.listening) {
     return Promise.resolve();
@@ -667,9 +838,47 @@ function isAddressInUseError(error) {
   }
   return error.code === 'EADDRINUSE';
 }
-function delay(ms) {
-  return new Promise(resolve => {
-    setTimeout(resolve, ms);
+class ExpressListenCancelledError extends Error {
+  name = 'ExpressListenCancelledError';
+  constructor() {
+    super('Express adapter startup was cancelled during shutdown.');
+  }
+}
+function throwIfListenCancelled(signal) {
+  if (signal.aborted) {
+    throw new ExpressListenCancelledError();
+  }
+}
+function isExpressListenCancelledError(error) {
+  return error instanceof ExpressListenCancelledError;
+}
+async function ignoreCancelledListen(listenPromise) {
+  try {
+    await listenPromise;
+  } catch (error) {
+    if (isExpressListenCancelledError(error)) {
+      return;
+    }
+    throw error;
+  }
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new ExpressListenCancelledError());
+      return;
+    }
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timeout);
+      reject(new ExpressListenCancelledError());
+    };
+    signal?.addEventListener('abort', onAbort, {
+      once: true
+    });
   });
 }
 function waitForCloseWithTimeout(closePromise, timeoutMs) {

package/package.json

@@ -8,7 +8,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.6",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
     "directory": "packages/platform-express"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -36,13 +36,14 @@
   ],
   "dependencies": {
     "express": "^5.1.0",
-    "@fluojs/http": "^1.1.1",
-    "@fluojs/runtime": "^1.1.7"
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/platform-nodejs": "^2.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.3",
-    "vitest": "^3.2.4",
-    "@fluojs/di": "^1.1.0"
+    "vitest": "^4.1.11",
+    "@fluojs/di": "^3.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",