@fluojs/platform-nodejs 1.0.5 → 2.0.0

package/README.ko.md

@@ -4,9 +4,12 @@
 
 fluo 런타임을 위한 raw Node.js HTTP 어댑터 패키지입니다.
 
+Coordinated Node 24 릴리스를 준비한다면 패키지 업그레이드 전에 [소비자 마이그레이션 가이드](../../docs/getting-started/migrate-node24.ko.md)를 따르세요.
+
 ## 목차
 
 - [설치](#설치)
+- [Runtime Node import 마이그레이션](#runtime-node-import-마이그레이션)
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
@@ -22,6 +25,19 @@ fluo 런타임을 위한 raw Node.js HTTP 어댑터 패키지입니다.
 npm install @fluojs/platform-nodejs
 ```
 
+이 패키지는 Node.js `>=24.0.0 <27`을 대상으로 하며 package manifest는 같은 `engines.node` 범위를 선언합니다. Node 24 LTS floor는 지원 정책 결정이며 RFC `QUERY` listener 동작은 이 지원 범위에서 계속 검증합니다. 이 패키지는 raw Node, Express, Fastify host가 사용하는 Node listener, filesystem, logger, compression, process-signal 구현을 소유합니다.
+
+## Runtime Node import 마이그레이션
+
+이전 mixed-runtime entrypoint에는 compatibility shim이 없습니다. Import를 직접 바꾸면 이동한 symbol 이름은 유지됩니다.
+
+| 제거된 import | 대체 import |
+| :--- | :--- |
+| `@fluojs/runtime/node` | `@fluojs/platform-nodejs` |
+| `@fluojs/runtime/internal-node` | `@fluojs/platform-nodejs/internal` |
+
+Root replacement는 `createNodeHttpAdapter`, `NodeHttpApplicationAdapter`, `bootstrapNodeApplication`, `runNodeApplication`, Node logger factory, shutdown registration helper, `createNodeFileSystemAssetSource`를 포함합니다. 기존 `createNodejsAdapter`, `bootstrapNodejsApplication`, `runNodejsApplication` alias도 유지됩니다.
+
 ## 사용 시점
 
 Express나 Fastify와 같은 중간 프레임워크의 오버헤드 없이 Node.js 내장 `http` 또는 `https` 모듈에서 직접 fluo 애플리케이션을 실행하려는 경우에 사용합니다. 최소한의 리소스 사용, 저수준 최적화 또는 표준 Node API가 선호되는 환경에 이상적입니다.
@@ -42,20 +58,26 @@ await app.listen();
 
 ## 주요 패턴
 
+### Early Hints
+
+Raw Node response는 `context.response.earlyHints`를 노출합니다. 이 optional capability를 확인한 뒤 HTTP `103` 하나마다 `write(...)`를 await하세요. 여러 write를 지원합니다. 각 write에는 비어 있지 않은 `link` value가 필요하며 Node가 허용하는 다른 informational field도 포함할 수 있습니다. Native write는 final response를 commit하거나 early field를 final header로 복사하지 않습니다. Late/native failure는 `EarlyHintsWriteError`로 reject되고 settlement 전에 연결이 끊기면 `RequestAbortedError`로 reject됩니다.
+
 ### 서버 옵션 커스텀
-어댑터는 문서화된 Node.js transport 옵션인 host/port 바인딩, HTTPS 설정, request body 제한, raw-body 보존, listen retry 설정, shutdown drain bound를 제공합니다.
+어댑터는 문서화된 Node.js transport 옵션인 host/port 바인딩, plain HTTP 또는 HTTPS 생성 설정, request body 제한, raw-body 보존, listen retry 설정, shutdown drain bound를 제공합니다.
 
 ```typescript
 const adapter = createNodejsAdapter({
-  port: 443,
-  https: {
-    key: fs.readFileSync('key.pem'),
-    cert: fs.readFileSync('cert.pem'),
+  port: 3000,
+  http: {
+    maxHeaderSize: 16_384,
+    joinDuplicateHeaders: true,
   },
   maxBodySize: 1_048_576,
 });
 ```
 
+`http`는 Node의 `node:http` `ServerOptions`를 받고 listener가 시작되기 전에 `createServer(options, handler)`로 전달합니다. `maxHeaderSize`, `insecureHTTPParser`, `joinDuplicateHeaders`, `highWaterMark` 같은 생성 시점 설정에 사용하세요. TLS에는 Node HTTPS server option이 담긴 `https`를 대신 제공하세요. `http`와 `https`는 동시에 사용할 수 없으며, 둘 다 제공하면 adapter가 server를 만들기 전에 throw하므로 어느 option도 조용히 무시되지 않습니다.
+
 `maxBodySize`는 바이트 수를 나타내는 숫자만 받습니다. 이 값은 raw Node 요청 바디가 아직 스트리밍되는 동안 바로 강제되며, 부트스트랩 시 `multipart.maxTotalSize`를 따로 재정의하지 않으면 같은 값이 멀티파트 전체 페이로드 한도의 기본값으로도 사용됩니다.
 
 `createNodejsAdapter()`는 기본 port로 `3000`을 사용하고 `process.env.PORT`를 무시하며, `port`, `maxBodySize`, `retryDelayMs`, `retryLimit`, adapter-level `shutdownTimeoutMs`가 잘못되면 throw합니다. 기본 request body cap은 `1 MiB`입니다.
@@ -88,17 +110,20 @@ await app.listen();
 ## 동작 계약
 
 - `createNodejsAdapter(options)`는 Node 내장 `http` 또는 `https` 서버 primitive 위에서 fluo를 직접 실행하는 adapter-first 진입점입니다.
+- `http`는 plain HTTP server 생성용 Node `node:http` `ServerOptions`를 받고, `https`는 기존 TLS 생성 option을 유지합니다. 호출자는 두 field 중 하나만 제공해야 합니다.
 - `maxBodySize`는 0 이상의 정수 바이트 수만 받으며, raw Node 요청 바이트가 아직 스트리밍되는 동안 강제되고, 부트스트랩/실행 헬퍼에서 `multipart.maxTotalSize`를 명시적으로 제공하지 않으면 멀티파트 전체 크기 한도의 기본값이 됩니다.
 - Raw Node adapter는 대소문자가 섞인 JSON 및 multipart `content-type` 값을 normalize하고, request body가 `maxBodySize`를 넘으면 `413`을 반환하며, `x-request-id`와 `x-correlation-id` fallback을 request context와 error response에 전파하고, `getServer()` / `getRealtimeCapability()`를 통해 server-backed realtime capability를 노출합니다.
 - `bootstrapNodejsApplication(module, options)`는 raw Node 어댑터가 포함된 애플리케이션을 만들지만 리스닝은 시작하지 않으므로 이후 `app.listen()`과 `app.close()` 생명주기는 호출자가 소유합니다.
 - `runNodejsApplication(module, options)`는 부트스트랩, 리스닝 시작, graceful shutdown 배선을 함께 수행합니다. Listen retry는 `retryLimit`/`retryDelayMs`를 따르고, shutdown은 bounded drain 전에 idle keep-alive connection을 닫으며, 시그널 기반 종료가 타임아웃되거나 실패하면 해당 상태를 로그와 `process.exitCode`로 보고합니다. 최종 프로세스 종료는 호스트 프로세스가 계속 소유합니다.
-- 고급 압축 및 shutdown 유틸리티 함수는 이 기본 platform startup surface가 아니라 `@fluojs/runtime/node` 또는 runtime 내부 seam에 남아 있습니다.
+- 지원되는 Node logger, shutdown, filesystem, raw adapter helper는 package root에 있고 저수준 request/response/compression plumbing은 `@fluojs/platform-nodejs/internal`에 있습니다.
 
 ## Conformance 커버리지
 
-`packages/platform-nodejs/src/index.test.ts`는 문서화된 Node.js 계약을 위한 package-local regression target입니다. 이 파일은 공유 `createHttpAdapterPortabilityHarness(...)` 검사를 실행하여 malformed cookie 보존, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body 제외, multipart 전체 크기 기본값, SSE framing, response stream drain settlement, host 및 HTTPS startup logging, shutdown signal listener cleanup을 검증합니다.
+`packages/platform-nodejs/src/index.test.ts`, `packages/platform-nodejs/src/lifecycle.test.ts`, `packages/platform-nodejs/src/lifecycle.integration.test.ts`는 문서화된 Node.js 계약을 위한 package-local regression target입니다. Adapter portability suite는 공유 `createHttpAdapterPortabilityHarness(...)` 검사를 실행하여 malformed cookie 보존, JSON/text raw-body capture, byte-exact raw-body capture, 단일 byte-range status/header/body semantic, multipart raw-body 제외, multipart 전체 크기 기본값, SSE framing, response stream drain settlement, host 및 HTTPS startup logging, shutdown signal listener cleanup을 검증합니다.
+
+이 패키지는 `HttpApplicationAdapter`를 노출하며 `platform.components`에 등록되는 runtime-managed `PlatformComponent`가 아닙니다. 따라서 generic `createPlatformConformanceHarness(...)` component lifecycle 검사는 이 패키지의 지원 계약 범위에 포함되지 않고, `createHttpAdapterPortabilityHarness(...)`가 적용되는 공유 harness입니다.
 
-같은 파일은 package-specific public surface, type alias, adapter-first startup, lifecycle option validation, listen retry behavior, idle keep-alive shutdown, `maxBodySize` failure, 대소문자가 섞인 JSON 및 multipart content-type parsing, `x-correlation-id` request ID fallback, server-backed realtime capability 노출도 함께 다룹니다. Startup behavior를 바꿀 때는 README 예제 포인터를 아래 테스트 파일 및 Node.js 챕터 예제와 맞춰 유지하세요.
+같은 regression target들은 package-specific public surface, type alias, adapter-first startup, plain HTTP 생성 option과 HTTPS conflict boundary, lifecycle option validation, 실제로 관찰되는 listen retry, active-request bounded drain, 정상 및 실패 signal-driven shutdown, `process.env.PORT` isolation, zero/default `maxBodySize` boundary, idle keep-alive shutdown, 대소문자가 섞인 JSON 및 multipart content-type parsing, `x-correlation-id` request ID fallback, server-backed realtime capability 노출도 함께 다룹니다. Startup behavior를 바꿀 때는 README 예제 포인터를 아래 테스트 파일 및 Node.js 챕터 예제와 맞춰 유지하세요.
 
 ## 공개 API 개요
 
@@ -106,10 +131,18 @@ await app.listen();
 - `bootstrapNodejsApplication(module, options)`: 리스너를 시작하지 않고 애플리케이션 인스턴스를 생성합니다.
 - `runNodejsApplication(module, options)`: 생명주기 관리를 포함하여 애플리케이션을 부트스트랩하고 시작합니다.
 - `BootstrapNodejsApplicationOptions`: bootstrap-only Node.js 애플리케이션 생성 옵션입니다.
-- `NodejsAdapterOptions`: `port`, `host`, `https`, `maxBodySize`, retry 설정, raw body 보존, shutdown timeout을 포함하는 `createNodejsAdapter(...)`의 transport-level 옵션입니다.
+- `NodejsAdapterOptions`: `port`, `host`, 상호 배타적인 `http` 또는 `https` 생성 option, `maxBodySize`, retry 설정, raw body 보존, shutdown timeout을 포함하는 `createNodejsAdapter(...)`의 transport-level 옵션입니다.
 - `NodejsApplicationSignal`: `runNodejsApplication(...)` shutdown 등록이 지원하는 시그널 이름입니다.
-- `NodejsHttpApplicationAdapter`: `createNodejsAdapter(...)`가 반환하는 어댑터 인스턴스를 설명하는 타입 전용 별칭이며, `@fluojs/runtime/node`가 공개하는 어댑터 surface를 그대로 보존합니다.
+- `NodejsHttpApplicationAdapter`: `createNodejsAdapter(...)`가 반환하는 어댑터 인스턴스를 설명하는 타입 전용 별칭이며, `@fluojs/platform-nodejs`가 공개하는 어댑터 surface를 그대로 보존합니다.
 - `RunNodejsApplicationOptions`: 부트스트랩, 리스닝 시작, graceful shutdown 배선을 한 번에 수행하기 위한 옵션입니다.
+- 이전 `@fluojs/runtime/node` export는 이 package root에서 이름을 유지합니다. `createNodeHttpAdapter`, `NodeHttpApplicationAdapter`, `bootstrapNodeApplication`, `runNodeApplication`, `createConsoleApplicationLogger`, `createJsonApplicationLogger`, `createNodeShutdownSignalRegistration`, `defaultNodeShutdownSignals`, `registerShutdownSignals`, `createNodeFileSystemAssetSource` 및 public option type이 포함됩니다.
+- `@fluojs/platform-nodejs/internal`: `@fluojs/runtime/internal-node`를 대체하는 first-party Node adapter integration seam이며 저수준 compression 및 request/response helper를 포함합니다.
+
+## Multipart 스트리밍
+
+애플리케이션 생성 시 `multipart: { strategy: 'stream' }`을 설정하면 multipart part가 `RequestContext.request.body`의 `AsyncIterable`로 노출됩니다. Node listener는 iterator를 미리 읽거나 버퍼링하지 않으며, file part를 소비할 때만 바이트를 가져옵니다. 버퍼링 multipart parsing은 기본값이며 fields와 `request.files`를 노출하고, 하나의 request body에서 stream 소비와 함께 사용할 수 없습니다.
+
+Runtime route dispatch는 route를 위해 만든 iterator를 소유하며 handler가 끝난 뒤 자동으로 `return()`을 호출해 active source를 cancel하고 release합니다. Standalone `parseMultipartStream(...)` consumer는 이 책임을 직접 집니다. iterator를 끝까지 소비하거나 일찍 끝낼 때 `return()`을 호출하세요.
 
 ## 관련 패키지
 
@@ -120,4 +153,6 @@ await app.listen();
 ## 예제 소스
 
 - `packages/platform-nodejs/src/index.test.ts`
+- `packages/platform-nodejs/src/lifecycle.test.ts`
+- `packages/platform-nodejs/src/lifecycle.integration.test.ts`
 - `book/intermediate/ch21-express-node.ko.md`

package/README.md

@@ -4,9 +4,12 @@
 
 Raw Node.js HTTP adapter package for the fluo runtime.
 
+Preparing for the coordinated Node 24 release? Follow the [consumer migration guide](../../docs/getting-started/migrate-node24.md) before upgrading packages.
+
 ## Table of Contents
 
 - [Installation](#installation)
+- [Runtime Node Import Migration](#runtime-node-import-migration)
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
@@ -22,6 +25,19 @@ Raw Node.js HTTP adapter package for the fluo runtime.
 npm install @fluojs/platform-nodejs
 ```
 
+This package targets Node.js `>=24.0.0 <27` and declares that exact `engines.node` range. The Node 24 LTS floor is a support-policy decision; listener-level RFC `QUERY` remains verified on the supported runtimes. The package owns the Node listener, filesystem, logger, compression, and process-signal implementations used by raw Node, Express, and Fastify hosts.
+
+## Runtime Node Import Migration
+
+The former mixed-runtime entrypoints have no compatibility shim. Update imports directly; moved symbols retain their names:
+
+| Removed import | Replacement |
+| :--- | :--- |
+| `@fluojs/runtime/node` | `@fluojs/platform-nodejs` |
+| `@fluojs/runtime/internal-node` | `@fluojs/platform-nodejs/internal` |
+
+The root replacement includes `createNodeHttpAdapter`, `NodeHttpApplicationAdapter`, `bootstrapNodeApplication`, `runNodeApplication`, Node logger factories, shutdown registration helpers, and `createNodeFileSystemAssetSource`. Existing `createNodejsAdapter`, `bootstrapNodejsApplication`, and `runNodejsApplication` aliases remain available.
+
 ## When to Use
 
 Use this package when you want to run a fluo application directly on the Node.js built-in `http` or `https` modules without the overhead of an intermediate framework like Express or Fastify. It is ideal for minimal footprints, custom low-level optimizations, or environments where standard Node APIs are preferred.
@@ -42,20 +58,26 @@ await app.listen();
 
 ## Common Patterns
 
+### Early Hints
+
+Raw Node responses expose `context.response.earlyHints`. Check that optional capability, then await `write(...)` once per HTTP `103`; multiple writes are supported. Each write requires a non-empty `link` value and may include other Node-permitted informational fields. The native write does not commit the final response or copy early fields into final headers. Late/native failures reject with `EarlyHintsWriteError`, and a disconnect before settlement rejects with `RequestAbortedError`.
+
 ### Customizing Server Options
-The adapter exposes the documented Node.js transport options: host/port binding, HTTPS configuration, request body limits, raw-body preservation, listen retry settings, and shutdown drain bounds.
+The adapter exposes the documented Node.js transport options: host/port binding, plain HTTP or HTTPS construction configuration, request body limits, raw-body preservation, listen retry settings, and shutdown drain bounds.
 
 ```typescript
 const adapter = createNodejsAdapter({
-  port: 443,
-  https: {
-    key: fs.readFileSync('key.pem'),
-    cert: fs.readFileSync('cert.pem'),
+  port: 3000,
+  http: {
+    maxHeaderSize: 16_384,
+    joinDuplicateHeaders: true,
   },
   maxBodySize: 1_048_576,
 });
 ```
 
+`http` accepts Node's `node:http` `ServerOptions` and passes them to `createServer(options, handler)` before the listener starts. Use it for construction-time settings such as `maxHeaderSize`, `insecureHTTPParser`, `joinDuplicateHeaders`, or `highWaterMark`. For TLS, provide `https` with Node's HTTPS server options instead. `http` and `https` are mutually exclusive; supplying both throws before the adapter creates a server, so no option is silently ignored.
+
 `maxBodySize` accepts a byte count number. It is enforced while the raw Node request body is still streaming, and the same limit becomes the default total multipart payload cap unless you override `multipart.maxTotalSize` during bootstrap.
 
 `createNodejsAdapter()` defaults to port `3000`, ignores `process.env.PORT`, and throws when `port`, `maxBodySize`, `retryDelayMs`, `retryLimit`, or adapter-level `shutdownTimeoutMs` are invalid. The default request body cap is `1 MiB`.
@@ -88,17 +110,20 @@ await app.listen();
 ## Behavioral Contracts
 
 - `createNodejsAdapter(options)` is the adapter-first entrypoint for running fluo directly on Node's built-in `http` or `https` server primitives.
+- `http` accepts Node `node:http` `ServerOptions` for plain HTTP server construction, while `https` keeps its existing TLS construction options; callers must supply at most one of those fields.
 - `maxBodySize` accepts a non-negative integer byte count, is enforced while raw Node request bytes are still streaming, and becomes the default multipart total-size cap unless `multipart.maxTotalSize` is explicitly provided through the bootstrap/run helpers.
 - The raw Node adapter normalizes mixed-case JSON and multipart `content-type` values, returns `413` when request bodies exceed `maxBodySize`, propagates `x-request-id` with `x-correlation-id` fallback into the request context and error responses, and exposes a server-backed realtime capability through `getServer()` / `getRealtimeCapability()`.
 - `bootstrapNodejsApplication(module, options)` creates an application with the raw Node adapter but does not start listening, so the caller owns the subsequent `app.listen()` and `app.close()` lifecycle.
 - `runNodejsApplication(module, options)` bootstraps, starts, and wires graceful shutdown. Listen retries honor `retryLimit`/`retryDelayMs`, shutdown closes idle keep-alive connections before bounded drain, and when signal-driven shutdown times out or fails it logs the condition and sets `process.exitCode`; final process termination remains owned by the host process.
-- Advanced compression and shutdown utility functions remain on `@fluojs/runtime/node` or internal runtime seams rather than this primary platform startup surface.
+- Supported Node logger, shutdown, filesystem, and raw adapter helpers live on the package root; lower-level request/response/compression plumbing lives on `@fluojs/platform-nodejs/internal`.
 
 ## Conformance Coverage
 
-`packages/platform-nodejs/src/index.test.ts` is the package-local regression target for the documented Node.js contract. It runs the shared `createHttpAdapterPortabilityHarness(...)` checks for malformed cookie preservation, JSON/text raw-body capture, byte-exact raw-body capture, multipart raw-body exclusion, multipart total-size defaults, SSE framing, response stream drain settlement, host and HTTPS startup logging, and shutdown signal listener cleanup.
+`packages/platform-nodejs/src/index.test.ts`, `packages/platform-nodejs/src/lifecycle.test.ts`, and `packages/platform-nodejs/src/lifecycle.integration.test.ts` are the package-local regression targets for the documented Node.js contract. The adapter portability suite runs the shared `createHttpAdapterPortabilityHarness(...)` checks for malformed cookie preservation, JSON/text raw-body capture, byte-exact raw-body capture, single byte-range status/header/body semantics, multipart raw-body exclusion, multipart total-size defaults, SSE framing, response stream drain settlement, host and HTTPS startup logging, and shutdown signal listener cleanup.
+
+This package exposes an `HttpApplicationAdapter`; it is not a runtime-managed `PlatformComponent` registered under `platform.components`. Therefore the generic `createPlatformConformanceHarness(...)` component lifecycle checks are outside this package's supported contract, while `createHttpAdapterPortabilityHarness(...)` is the applicable shared harness.
 
-The same file also covers the package-specific public surface, type aliases, adapter-first startup, lifecycle option validation, listen retry behavior, idle keep-alive shutdown, `maxBodySize` failures, mixed-case JSON and multipart content-type parsing, `x-correlation-id` request ID fallback, and server-backed realtime capability exposure. Keep README example pointers aligned with that test file and the Node.js chapter examples below when changing startup behavior.
+The same regression targets also cover the package-specific public surface, type aliases, adapter-first startup, plain HTTP construction options and their HTTPS conflict boundary, lifecycle option validation, observed listen retries, active-request bounded drain, normal and failed signal-driven shutdown, `process.env.PORT` isolation, zero and default `maxBodySize` boundaries, idle keep-alive shutdown, mixed-case JSON and multipart content-type parsing, `x-correlation-id` request ID fallback, and server-backed realtime capability exposure. Keep README example pointers aligned with those test files and the Node.js chapter examples below when changing startup behavior.
 
 ## Public API Overview
 
@@ -106,10 +131,18 @@ The same file also covers the package-specific public surface, type aliases, ada
 - `bootstrapNodejsApplication(module, options)`: Creates an application instance without starting the listener.
 - `runNodejsApplication(module, options)`: Bootstraps and starts the application with lifecycle management.
 - `BootstrapNodejsApplicationOptions`: Options for bootstrap-only Node.js application creation.
-- `NodejsAdapterOptions`: Transport-level options for `createNodejsAdapter(...)`, including `port`, `host`, `https`, `maxBodySize`, retry settings, raw body preservation, and shutdown timeout.
+- `NodejsAdapterOptions`: Transport-level options for `createNodejsAdapter(...)`, including `port`, `host`, mutually exclusive `http` or `https` construction options, `maxBodySize`, retry settings, raw body preservation, and shutdown timeout.
 - `NodejsApplicationSignal`: Supported signal names for `runNodejsApplication(...)` shutdown registration.
-- `NodejsHttpApplicationAdapter`: Type-only alias describing the adapter instances returned by `createNodejsAdapter(...)`, while preserving the public adapter surface exported from `@fluojs/runtime/node`.
+- `NodejsHttpApplicationAdapter`: Type-only alias describing the adapter instances returned by `createNodejsAdapter(...)`, while preserving the public adapter surface exported from `@fluojs/platform-nodejs`.
 - `RunNodejsApplicationOptions`: Options for one-call bootstrap, listen, and graceful shutdown wiring.
+- Former `@fluojs/runtime/node` exports keep their names on this package root: `createNodeHttpAdapter`, `NodeHttpApplicationAdapter`, `bootstrapNodeApplication`, `runNodeApplication`, `createConsoleApplicationLogger`, `createJsonApplicationLogger`, `createNodeShutdownSignalRegistration`, `defaultNodeShutdownSignals`, `registerShutdownSignals`, and `createNodeFileSystemAssetSource` plus their public option types.
+- `@fluojs/platform-nodejs/internal`: First-party Node adapter integration seam replacing `@fluojs/runtime/internal-node`; it includes lower-level compression and request/response helpers.
+
+## Multipart streaming
+
+Set `multipart: { strategy: 'stream' }` when creating the application to expose multipart parts through `RequestContext.request.body` as an `AsyncIterable`. The Node listener 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.
+
+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
 
@@ -120,4 +153,6 @@ The same file also covers the package-specific public surface, type aliases, ada
 ## Example Sources
 
 - `packages/platform-nodejs/src/index.test.ts`
+- `packages/platform-nodejs/src/lifecycle.test.ts`
+- `packages/platform-nodejs/src/lifecycle.integration.test.ts`
 - `book/intermediate/ch21-express-node.md`

package/dist/index.d.ts

@@ -1,52 +1,21 @@
-import { type BootstrapNodeApplicationOptions, bootstrapNodeApplication, type NodeApplicationSignal, type NodeHttpAdapterOptions, type NodeHttpApplicationAdapter, type RunNodeApplicationOptions, runNodeApplication } from '@fluojs/runtime/node';
-/**
- * Options accepted by `bootstrapNodejsApplication(...)` before the listener starts.
- *
- * @remarks
- * This type mirrors the supported Node application bootstrap options from `@fluojs/runtime/node`
- * while keeping the `@fluojs/platform-nodejs` public surface documented at its package boundary.
- */
+import { type BootstrapNodeApplicationOptions, bootstrapNodeApplication, type NodeApplicationSignal, type NodeHttpAdapterOptions, type NodeHttpApplicationAdapter, type RunNodeApplicationOptions, runNodeApplication } from './node/internal-node.js';
+export { type BootstrapNodeApplicationOptions, bootstrapNodeApplication, type CorsInput, createNodeHttpAdapter, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals, type NodeApplicationSignal, type NodeHttpAdapterOptions, NodeHttpApplicationAdapter, type RunNodeApplicationOptions, registerShutdownSignals, runNodeApplication, } from './node/internal-node.js';
+export * from './node/json-logger.js';
+export * from './node/logger.js';
+export { createNodeFileSystemAssetSource, type NodeFileSystemAssetPrecompression, type NodeFileSystemAssetSourceOptions, } from './node/node-static-assets.js';
+/** Options accepted by `bootstrapNodejsApplication(...)` before the listener starts. */
 export type BootstrapNodejsApplicationOptions = BootstrapNodeApplicationOptions;
-/**
- * POSIX signals that `runNodejsApplication(...)` can subscribe to for graceful shutdown.
- *
- * @remarks
- * Pass `false` to `RunNodejsApplicationOptions.shutdownSignals` when the host process owns signal
- * registration and should call `app.close()` itself.
- */
+/** POSIX signals that `runNodejsApplication(...)` can subscribe to for graceful shutdown. */
 export type NodejsApplicationSignal = NodeApplicationSignal;
-/**
- * Transport-level settings for the raw Node.js adapter factory.
- *
- * @remarks
- * `maxBodySize` is enforced while request bytes stream in and also seeds the multipart total-size
- * limit unless `bootstrapNodejsApplication(...)` or `runNodejsApplication(...)` provides an
- * explicit `multipart.maxTotalSize` value.
- */
+/** Transport-level settings for the raw Node.js adapter factory. */
 export type NodejsAdapterOptions = NodeHttpAdapterOptions;
-/**
- * Adapter instance returned by `createNodejsAdapter(...)`.
- *
- * @remarks
- * The alias preserves the public `@fluojs/runtime/node` adapter contract, including access to the
- * underlying Node server via `getServer()` for server-backed realtime integrations.
- */
+/** Adapter instance returned by `createNodejsAdapter(...)`. */
 export type NodejsHttpApplicationAdapter = NodeHttpApplicationAdapter;
-/**
- * Options accepted by `runNodejsApplication(...)` for one-call bootstrap, listen, and shutdown wiring.
- *
- * @remarks
- * Signal-driven shutdown logs timeout or failure conditions and sets `process.exitCode`, but final
- * process termination remains owned by the surrounding host runtime.
- */
+/** Options accepted by `runNodejsApplication(...)` for one-call bootstrap, listen, and shutdown wiring. */
 export type RunNodejsApplicationOptions = RunNodeApplicationOptions;
 /**
  * Bootstrap a fluo module with the raw Node.js adapter without starting the listener.
  *
- * @remarks
- * This alias keeps the package-level Node.js naming convention while delegating to the supported
- * `@fluojs/runtime/node` implementation.
- *
  * @param rootModule Root fluo module to bootstrap.
  * @param options Node.js bootstrap options applied before the listener starts.
  * @returns A fluo application instance whose listener is not started yet.
@@ -55,27 +24,13 @@ export declare const bootstrapNodejsApplication: typeof bootstrapNodeApplication
 /**
  * Create the raw Node.js HTTP adapter exposed by `@fluojs/platform-nodejs`.
  *
- * @remarks
- * Use this factory for adapter-first startup through `fluoFactory.create(...)` when the application
- * should run directly on Node's built-in `http` or `https` server primitives.
- *
  * @param options Transport-level Node.js settings such as port, retries, body-size limits, and HTTPS options.
  * @returns The Node.js HTTP adapter instance used by the Fluo runtime.
- *
- * @example
- * ```ts
- * const adapter = createNodejsAdapter({ port: 3000 });
- * ```
  */
-export declare function createNodejsAdapter(options?: NodeHttpAdapterOptions): NodeHttpApplicationAdapter;
+export declare function createNodejsAdapter(options?: NodejsAdapterOptions): NodejsHttpApplicationAdapter;
 /**
  * Bootstrap and start a fluo module on the raw Node.js adapter with lifecycle shutdown wiring.
  *
- * @remarks
- * This alias is the zero-boilerplate package entrypoint for Node.js hosts. It preserves the runtime
- * helper behavior: graceful shutdown is bounded and reported, while final process exit remains under
- * host ownership.
- *
  * @param rootModule Root fluo module to bootstrap and start.
  * @param options Node.js run options, including optional shutdown signal ownership.
  * @returns A started fluo application instance.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,+BAA+B,EACpC,wBAAwB,EAExB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,MAAM,iCAAiC,GAAG,+BAA+B,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,0BAA0B,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,MAAM,2BAA2B,GAAG,yBAAyB,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,EAAE,OAAO,wBAAmD,CAAC;AAEpG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,sBAA2B,GACnC,0BAA0B,CAE5B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,kBAAuC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,+BAA+B,EACpC,wBAAwB,EAExB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAC9B,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,KAAK,+BAA+B,EACpC,wBAAwB,EACxB,KAAK,SAAS,EACd,qBAAqB,EACrB,oCAAoC,EACpC,0BAA0B,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,0BAA0B,EAC1B,KAAK,yBAAyB,EAC9B,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,+BAA+B,EAC/B,KAAK,iCAAiC,EACtC,KAAK,gCAAgC,GACtC,MAAM,8BAA8B,CAAC;AAEtC,wFAAwF;AACxF,MAAM,MAAM,iCAAiC,GAAG,+BAA+B,CAAC;AAEhF,6FAA6F;AAC7F,MAAM,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE5D,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE1D,+DAA+D;AAC/D,MAAM,MAAM,4BAA4B,GAAG,0BAA0B,CAAC;AAEtE,2GAA2G;AAC3G,MAAM,MAAM,2BAA2B,GAAG,yBAAyB,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,OAAO,wBAAmD,CAAC;AAEpG;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,4BAA4B,CAE9B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,kBAAuC,CAAC"}

package/dist/index.js

@@ -1,53 +1,22 @@
-import { bootstrapNodeApplication, createNodeHttpAdapter, runNodeApplication } from '@fluojs/runtime/node';
+import { bootstrapNodeApplication, createNodeHttpAdapter, runNodeApplication } from './node/internal-node.js';
+export { bootstrapNodeApplication, createNodeHttpAdapter, createNodeShutdownSignalRegistration, defaultNodeShutdownSignals, NodeHttpApplicationAdapter, registerShutdownSignals, runNodeApplication } from './node/internal-node.js';
+export * from './node/json-logger.js';
+export * from './node/logger.js';
+export { createNodeFileSystemAssetSource } from './node/node-static-assets.js';
 
-/**
- * Options accepted by `bootstrapNodejsApplication(...)` before the listener starts.
- *
- * @remarks
- * This type mirrors the supported Node application bootstrap options from `@fluojs/runtime/node`
- * while keeping the `@fluojs/platform-nodejs` public surface documented at its package boundary.
- */
+/** Options accepted by `bootstrapNodejsApplication(...)` before the listener starts. */
 
-/**
- * POSIX signals that `runNodejsApplication(...)` can subscribe to for graceful shutdown.
- *
- * @remarks
- * Pass `false` to `RunNodejsApplicationOptions.shutdownSignals` when the host process owns signal
- * registration and should call `app.close()` itself.
- */
+/** POSIX signals that `runNodejsApplication(...)` can subscribe to for graceful shutdown. */
 
-/**
- * Transport-level settings for the raw Node.js adapter factory.
- *
- * @remarks
- * `maxBodySize` is enforced while request bytes stream in and also seeds the multipart total-size
- * limit unless `bootstrapNodejsApplication(...)` or `runNodejsApplication(...)` provides an
- * explicit `multipart.maxTotalSize` value.
- */
+/** Transport-level settings for the raw Node.js adapter factory. */
 
-/**
- * Adapter instance returned by `createNodejsAdapter(...)`.
- *
- * @remarks
- * The alias preserves the public `@fluojs/runtime/node` adapter contract, including access to the
- * underlying Node server via `getServer()` for server-backed realtime integrations.
- */
+/** Adapter instance returned by `createNodejsAdapter(...)`. */
 
-/**
- * Options accepted by `runNodejsApplication(...)` for one-call bootstrap, listen, and shutdown wiring.
- *
- * @remarks
- * Signal-driven shutdown logs timeout or failure conditions and sets `process.exitCode`, but final
- * process termination remains owned by the surrounding host runtime.
- */
+/** Options accepted by `runNodejsApplication(...)` for one-call bootstrap, listen, and shutdown wiring. */
 
 /**
  * Bootstrap a fluo module with the raw Node.js adapter without starting the listener.
  *
- * @remarks
- * This alias keeps the package-level Node.js naming convention while delegating to the supported
- * `@fluojs/runtime/node` implementation.
- *
  * @param rootModule Root fluo module to bootstrap.
  * @param options Node.js bootstrap options applied before the listener starts.
  * @returns A fluo application instance whose listener is not started yet.
@@ -57,17 +26,8 @@ export const bootstrapNodejsApplication = bootstrapNodeApplication;
 /**
  * Create the raw Node.js HTTP adapter exposed by `@fluojs/platform-nodejs`.
  *
- * @remarks
- * Use this factory for adapter-first startup through `fluoFactory.create(...)` when the application
- * should run directly on Node's built-in `http` or `https` server primitives.
- *
  * @param options Transport-level Node.js settings such as port, retries, body-size limits, and HTTPS options.
  * @returns The Node.js HTTP adapter instance used by the Fluo runtime.
- *
- * @example
- * ```ts
- * const adapter = createNodejsAdapter({ port: 3000 });
- * ```
  */
 export function createNodejsAdapter(options = {}) {
   return createNodeHttpAdapter(options);
@@ -76,11 +36,6 @@ export function createNodejsAdapter(options = {}) {
 /**
  * Bootstrap and start a fluo module on the raw Node.js adapter with lifecycle shutdown wiring.
  *
- * @remarks
- * This alias is the zero-boilerplate package entrypoint for Node.js hosts. It preserves the runtime
- * helper behavior: graceful shutdown is bounded and reported, while final process exit remains under
- * host ownership.
- *
  * @param rootModule Root fluo module to bootstrap and start.
  * @param options Node.js run options, including optional shutdown signal ownership.
  * @returns A started fluo application instance.

package/dist/internal.d.ts

@@ -0,0 +1,3 @@
+export * from './node/internal-node.js';
+export { createNodeEarlyHintsCapability } from './node/internal-node-early-hints.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/internal.js

@@ -0,0 +1,2 @@
+export * from './node/internal-node.js';
+export { createNodeEarlyHintsCapability } from './node/internal-node-early-hints.js';

package/dist/node/internal-node-compression.d.ts

@@ -0,0 +1,22 @@
+import type { ServerResponse } from 'node:http';
+import type { FrameworkResponseCompression } from '@fluojs/http';
+type Encoding = 'br' | 'gzip' | 'identity';
+/**
+ * Create node response compression.
+ *
+ * @param response The response.
+ * @param acceptEncoding The accept encoding.
+ * @returns The create node response compression result.
+ */
+export declare function createNodeResponseCompression(response: ServerResponse, acceptEncoding: string | undefined): FrameworkResponseCompression | undefined;
+/**
+ * Compress node response.
+ *
+ * @param response The response.
+ * @param body The body.
+ * @param encoding The encoding.
+ * @returns The compress node response result.
+ */
+export declare function compressNodeResponse(response: ServerResponse, body: Uint8Array, encoding: Exclude<Encoding, 'identity'>): Promise<void>;
+export {};
+//# sourceMappingURL=internal-node-compression.d.ts.map

package/dist/node/internal-node-compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-node-compression.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-compression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,cAAc,CAAC;AAiBtB,KAAK,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,cAAc,EACxB,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,4BAA4B,GAAG,SAAS,CAqB1C;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/node/internal-node-compression.js

@@ -0,0 +1,121 @@
+import { createBrotliCompress, createGzip } from 'node:zlib';
+const COMPRESS_THRESHOLD = 1024;
+const SKIP_CONTENT_TYPES = new Set(['image/', 'audio/', 'video/', 'application/zip', 'application/gzip', 'application/x-bzip', 'application/x-bzip2', 'application/x-xz', 'application/zstd', 'application/octet-stream']);
+/**
+ * Create node response compression.
+ *
+ * @param response The response.
+ * @param acceptEncoding The accept encoding.
+ * @returns The create node response compression result.
+ */
+export function createNodeResponseCompression(response, acceptEncoding) {
+  if (!acceptEncoding) {
+    return undefined;
+  }
+  return {
+    async write(body, options = {}) {
+      if (body.byteLength < COMPRESS_THRESHOLD || shouldSkipContentType(options.contentType)) {
+        return false;
+      }
+      const encoding = selectEncoding(acceptEncoding);
+      if (encoding === 'identity') {
+        return false;
+      }
+      await compressNodeResponse(response, body, encoding);
+      return true;
+    }
+  };
+}
+
+/**
+ * Compress node response.
+ *
+ * @param response The response.
+ * @param body The body.
+ * @param encoding The encoding.
+ * @returns The compress node response result.
+ */
+export function compressNodeResponse(response, body, encoding) {
+  if (response.destroyed || response.socket?.destroyed) {
+    return Promise.reject(new Error('Node response closed before compression completed.'));
+  }
+  const stream = encoding === 'br' ? createBrotliCompress() : createGzip();
+  response.setHeader('Content-Encoding', encoding);
+  response.removeHeader('Content-Length');
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      response.removeListener('close', rejectClosedResponse);
+      response.removeListener('error', rejectFailure);
+      response.removeListener('finish', resolveResponse);
+      stream.removeListener('error', rejectFailure);
+    };
+    const settle = (action, terminateStream = false) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (terminateStream) {
+        stream.unpipe(response);
+        stream.destroy();
+      }
+      cleanup();
+      action();
+    };
+    const rejectFailure = error => {
+      settle(() => reject(error), true);
+    };
+    const rejectClosedResponse = () => {
+      settle(() => reject(new Error('Node response closed before compression completed.')), true);
+    };
+    const resolveResponse = () => {
+      if (response.destroyed || !response.writableEnded) {
+        rejectClosedResponse();
+        return;
+      }
+      settle(resolve);
+    };
+    response.once('close', rejectClosedResponse);
+    response.once('error', rejectFailure);
+    response.once('finish', resolveResponse);
+    stream.once('error', rejectFailure);
+    stream.pipe(response);
+    stream.end(body);
+  });
+}
+function shouldSkipContentType(contentType) {
+  if (!contentType) {
+    return false;
+  }
+  const lower = contentType.toLowerCase();
+  for (const prefix of SKIP_CONTENT_TYPES) {
+    if (lower.startsWith(prefix)) {
+      return true;
+    }
+  }
+  return false;
+}
+function selectEncoding(acceptEncoding) {
+  if (!acceptEncoding) {
+    return 'identity';
+  }
+  const entries = acceptEncoding.split(',').map(entry => {
+    const [enc, qPart] = entry.trim().split(';');
+    const q = qPart ? parseFloat(qPart.replace('q=', '')) : 1;
+    return {
+      enc: enc?.trim() ?? '',
+      q: Number.isNaN(q) ? 1 : q
+    };
+  }).filter(entry => entry.q > 0).sort((a, b) => b.q - a.q);
+  for (const {
+    enc
+  } of entries) {
+    if (enc === 'br') {
+      return 'br';
+    }
+    if (enc === 'gzip') {
+      return 'gzip';
+    }
+  }
+  return 'identity';
+}

package/dist/node/internal-node-early-hints.d.ts

@@ -0,0 +1,11 @@
+import { type ServerResponse } from 'node:http';
+import { type FrameworkResponseEarlyHints } from '@fluojs/http';
+/**
+ * Create the request-scoped Early Hints writer shared by Node-backed adapters.
+ *
+ * @param response Native Node response that emits HTTP 103 informational responses.
+ * @param isCommitted Probe for facade-level final response ownership.
+ * @returns An Early Hints capability that settles on native write, error, or disconnect.
+ */
+export declare function createNodeEarlyHintsCapability(response: ServerResponse, isCommitted: () => boolean): FrameworkResponseEarlyHints;
+//# sourceMappingURL=internal-node-early-hints.d.ts.map

package/dist/node/internal-node-early-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-node-early-hints.d.ts","sourceRoot":"","sources":["../../src/node/internal-node-early-hints.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAGL,KAAK,2BAA2B,EAEjC,MAAM,cAAc,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,MAAM,OAAO,GACzB,2BAA2B,CA2E7B"}