@fluojs/platform-nodejs 1.0.0-beta.1 → 1.0.0-beta.2

package/README.ko.md

@@ -10,6 +10,7 @@ fluo 런타임을 위한 raw Node.js HTTP 어댑터 패키지입니다.
 - [사용 시점](#사용-시점)
 - [빠른 시작](#빠른-시작)
 - [주요 패턴](#주요-패턴)
+- [동작 계약](#동작-계약)
 - [공개 API 개요](#공개-api-개요)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -68,15 +69,28 @@ import { AppModule } from './app.module';
 await runNodejsApplication(AppModule, {
   port: 3000,
   globalPrefix: 'api',
+  shutdownSignals: ['SIGINT', 'SIGTERM'],
 });
 ```
 
+## 동작 계약
+
+- `createNodejsAdapter(options)`는 Node 내장 `http` 또는 `https` 서버 primitive 위에서 fluo를 직접 실행하는 adapter-first 진입점입니다.
+- `maxBodySize`는 raw Node 요청 바이트가 아직 스트리밍되는 동안 강제되며, 부트스트랩/실행 헬퍼에서 `multipart.maxTotalSize`를 명시적으로 제공하지 않으면 멀티파트 전체 크기 한도의 기본값이 됩니다.
+- `bootstrapNodejsApplication(module, options)`는 raw Node 어댑터가 포함된 애플리케이션을 만들지만 리스닝은 시작하지 않으므로 이후 `app.listen()`과 `app.close()` 생명주기는 호출자가 소유합니다.
+- `runNodejsApplication(module, options)`는 부트스트랩, 리스닝 시작, graceful shutdown 배선을 함께 수행합니다. 시그널 기반 종료가 타임아웃되거나 실패하면 해당 상태를 로그와 `process.exitCode`로 보고하며, 최종 프로세스 종료는 호스트 프로세스가 계속 소유합니다.
+- 고급 압축 및 shutdown 유틸리티 함수는 이 기본 platform startup surface가 아니라 `@fluojs/runtime/node` 또는 runtime 내부 seam에 남아 있습니다.
+
 ## 공개 API 개요
 
 - `createNodejsAdapter(options)`: raw Node.js HTTP 어댑터를 위한 기본 팩토리입니다.
 - `bootstrapNodejsApplication(module, options)`: 리스너를 시작하지 않고 애플리케이션 인스턴스를 생성합니다.
 - `runNodejsApplication(module, options)`: 생명주기 관리를 포함하여 애플리케이션을 부트스트랩하고 시작합니다.
+- `BootstrapNodejsApplicationOptions`: bootstrap-only Node.js 애플리케이션 생성 옵션입니다.
+- `NodejsAdapterOptions`: `port`, `host`, `https`, `maxBodySize`, retry 설정, raw body 보존, shutdown timeout을 포함하는 `createNodejsAdapter(...)`의 transport-level 옵션입니다.
+- `NodejsApplicationSignal`: `runNodejsApplication(...)` shutdown 등록이 지원하는 시그널 이름입니다.
 - `NodejsHttpApplicationAdapter`: `createNodejsAdapter(...)`가 반환하는 어댑터 인스턴스를 설명하는 타입 전용 별칭이며, `@fluojs/runtime/node`가 공개하는 어댑터 surface를 그대로 보존합니다.
+- `RunNodejsApplicationOptions`: 부트스트랩, 리스닝 시작, graceful shutdown 배선을 한 번에 수행하기 위한 옵션입니다.
 
 ## 관련 패키지
 

package/README.md

@@ -10,6 +10,7 @@ Raw Node.js HTTP adapter package for the fluo runtime.
 - [When to Use](#when-to-use)
 - [Quick Start](#quick-start)
 - [Common Patterns](#common-patterns)
+- [Behavioral Contracts](#behavioral-contracts)
 - [Public API Overview](#public-api-overview)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -68,15 +69,28 @@ import { AppModule } from './app.module';
 await runNodejsApplication(AppModule, {
   port: 3000,
   globalPrefix: 'api',
+  shutdownSignals: ['SIGINT', 'SIGTERM'],
 });
 ```
 
+## Behavioral Contracts
+
+- `createNodejsAdapter(options)` is the adapter-first entrypoint for running fluo directly on Node's built-in `http` or `https` server primitives.
+- `maxBodySize` is enforced while raw Node request bytes are still streaming, and it becomes the default multipart total-size cap unless `multipart.maxTotalSize` is explicitly provided through the bootstrap/run helpers.
+- `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. 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.
+
 ## Public API Overview
 
 - `createNodejsAdapter(options)`: Primary factory for the raw Node.js HTTP adapter.
 - `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.
+- `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`.
+- `RunNodejsApplicationOptions`: Options for one-call bootstrap, listen, and graceful shutdown wiring.
 
 ## Related Packages
 

package/dist/index.d.ts

@@ -1,11 +1,84 @@
-import { type NodeHttpAdapterOptions, type NodeHttpApplicationAdapter } from '@fluojs/runtime/node';
-export { bootstrapNodeApplication as bootstrapNodejsApplication, runNodeApplication as runNodejsApplication, } from '@fluojs/runtime/node';
-export type { BootstrapNodeApplicationOptions as BootstrapNodejsApplicationOptions, NodeApplicationSignal as NodejsApplicationSignal, NodeHttpAdapterOptions as NodejsAdapterOptions, NodeHttpApplicationAdapter as NodejsHttpApplicationAdapter, RunNodeApplicationOptions as RunNodejsApplicationOptions, } from '@fluojs/runtime/node';
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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, multipart, 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;
+/**
+ * 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.
+ */
+export declare const runNodejsApplication: typeof runNodeApplication;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAChC,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,wBAAwB,IAAI,0BAA0B,EACtD,kBAAkB,IAAI,oBAAoB,GAC3C,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EACV,+BAA+B,IAAI,iCAAiC,EACpE,qBAAqB,IAAI,uBAAuB,EAChD,sBAAsB,IAAI,oBAAoB,EAC9C,0BAA0B,IAAI,4BAA4B,EAC1D,yBAAyB,IAAI,2BAA2B,GACzD,MAAM,sBAAsB,CAAC;AAE9B;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,sBAA2B,GACnC,0BAA0B,CAE5B"}
+{"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"}

package/dist/index.js

@@ -1,11 +1,88 @@
-import { createNodeHttpAdapter } from '@fluojs/runtime/node';
-export { bootstrapNodeApplication as bootstrapNodejsApplication, runNodeApplication as runNodejsApplication } from '@fluojs/runtime/node';
+import { bootstrapNodeApplication, createNodeHttpAdapter, 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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, multipart, 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);
-}
+}
+
+/**
+ * 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.
+ */
+export const runNodejsApplication = runNodeApplication;

package/package.json

@@ -9,7 +9,7 @@
     "platform",
     "server"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "@fluojs/http": "^1.0.0-beta.1",
-    "@fluojs/runtime": "^1.0.0-beta.1"
+    "@fluojs/runtime": "^1.0.0-beta.2"
   },
   "devDependencies": {
     "vitest": "^3.2.4"