@fluojs/runtime 1.0.0-beta.1 → 1.0.0-beta.2

package/README.ko.md

@@ -27,7 +27,7 @@ npm install @fluojs/runtime
 - **fluo 애플리케이션 부트스트랩**: 모듈을 실행 중인 HTTP 서버나 마이크로서비스로 변환할 때.
 - **DI 및 라이프사이클 오케스트레이션**: 모듈 그래프 컴파일, 프로바이더 연결 및 애플리케이션 훅(`onModuleInit`, `onApplicationBootstrap`)을 관리할 때.
 - **독립형 컨텍스트 생성**: HTTP 서버는 필요 없지만 DI가 필요한 CLI 태스크, 마이그레이션 또는 워커를 실행할 때.
-- **진단 및 검사**: 기계 읽기 가능한 형태나 Mermaid 기반의 모듈 그래프 토폴로지를 내보낼 때.
+- **진단 및 검사**: CLI 내보내기와 Studio 소유 그래프 보기/렌더링을 위한 기계 읽기 가능한 플랫폼 snapshot을 생산할 때.
 
 ## 퀵 스타트
 
@@ -125,7 +125,9 @@ class UsersModule {}
 - 요청 바디 파싱은 Web 표준 요청과 Node 기반 요청 모두에서 바이트가 스트리밍되는 동안 `maxBodySize`를 강제합니다.
 - 멀티파트 파싱은 누적 바디 크기가 설정된 `multipart.maxTotalSize`를 넘으면 즉시 거부되며, 런타임 어댑터는 별도 재정의가 없으면 이 한도를 `maxBodySize`와 동일하게 맞춥니다.
 - 응답 스트림 백프레셔 헬퍼는 `drain`, `close`, `error` 중 어느 경우에도 `waitForDrain()`을 완료시켜 끊어진 연결에서 스트리밍 작성기가 멈추지 않도록 합니다.
+- 런타임 health 모듈은 bootstrap이 ready로 표시하기 전까지 `/ready`를 HTTP 503과 `starting`으로 보고하며, 애플리케이션/컨텍스트 종료가 시작되는 즉시, 종료 시도가 실패하더라도 다시 `starting`으로 내려갑니다.
 - 시그널 기반 종료 헬퍼는 bounded drain semantics를 유지하면서 timeout/실패 상황을 로그와 `process.exitCode`로 보고하지만, 최종 프로세스 종료 소유권은 주변 호스트 런타임에 남겨 둡니다.
+- 플랫폼 snapshot 생산은 런타임에 남아 있고, 그래프 보기와 Mermaid 렌더링은 CLI 및 자동화 호출자가 소비하는 Studio 소유 계약입니다.
 
 ## 공개 API 개요
 
@@ -134,6 +136,7 @@ class UsersModule {}
 - `Application`: `ApplicationContext`를 확장하며 `listen()`, `dispatch()`, `state`를 포함합니다.
 - `ApplicationContext`: `get<T>(token)`, `close()` 기능을 제공하며 `container`와 `modules`에 접근할 수 있습니다.
 - `LifecycleHooks`: `OnModuleInit`, `OnApplicationBootstrap`, `OnModuleDestroy`, `OnApplicationShutdown`를 묶는 편의 union 타입입니다.
+- `createHealthModule(options)`: bootstrap 및 shutdown 라이프사이클 전이에 맞춰 readiness marker를 관리하는 런타임 소유 `/health`, `/ready` 모듈 팩토리입니다.
 - `defineModule(cls, metadata)`: 프로그래밍 방식의 모듈 정의 헬퍼입니다.
 - `bootstrapApplication(options)`: 저수준 비동기 부트스트랩 함수입니다.
 
@@ -174,6 +177,7 @@ import {
 - [@fluojs/di](../di): 의존성 주입(DI) 컨테이너 구현체.
 - [@fluojs/http](../http): HTTP 라우팅, 컨트롤러 및 디스패처.
 - [@fluojs/platform-nodejs](../platform-nodejs): 공식 Node.js HTTP 어댑터.
+- [@fluojs/studio](../studio): 런타임이 생산한 snapshot을 위한 뷰어 및 렌더링 헬퍼.
 
 ## 예제 소스
 

package/README.md

@@ -27,7 +27,7 @@ Use this package when you need to:
 - **Bootstrap a fluo application**: Convert your modules into a running HTTP server or microservice.
 - **Orchestrate DI and Lifecycle**: Manage module-graph compilation, provider wiring, and application hooks (`onModuleInit`, `onApplicationBootstrap`).
 - **Create Standalone Contexts**: Run CLI tasks, migrations, or workers that need DI but not an HTTP server.
-- **Diagnostic Inspection**: Export machine-readable or Mermaid-based module graph topology.
+- **Diagnostic Inspection**: Produce machine-readable platform snapshots for CLI export and Studio-owned graph viewing/rendering.
 
 ## Quick Start
 
@@ -125,7 +125,9 @@ class UsersModule {}
 - Request body parsing enforces `maxBodySize` while bytes are still streaming for both Web-standard and Node-backed requests.
 - Multipart parsing rejects payloads when the cumulative body size exceeds the configured `multipart.maxTotalSize`; runtime adapters default that limit to `maxBodySize` unless you override it.
 - Response stream backpressure helpers settle `waitForDrain()` on `drain`, `close`, or `error` so streaming writers do not hang on dead connections.
+- Runtime health modules report `/ready` as `starting` with HTTP 503 until bootstrap marks them ready, and they return to `starting` as soon as application/context shutdown begins, including failed shutdown attempts.
 - Signal-driven shutdown helpers preserve bounded drain semantics, log timeout/failure conditions, and set `process.exitCode` when shutdown does not finish cleanly, but they leave final process termination ownership to the surrounding host runtime.
+- Platform snapshot production stays in runtime; graph viewing and Mermaid rendering are Studio-owned contracts consumed by CLI and automation callers.
 
 ## Public API Overview
 
@@ -134,6 +136,7 @@ class UsersModule {}
 - `Application`: Extends `ApplicationContext` with `listen()`, `dispatch()`, and `state`.
 - `ApplicationContext`: Provides `get<T>(token)`, `close()`, and access to `container` and `modules`.
 - `LifecycleHooks`: Convenience union covering `OnModuleInit`, `OnApplicationBootstrap`, `OnModuleDestroy`, and `OnApplicationShutdown`.
+- `createHealthModule(options)`: Runtime-owned `/health` and `/ready` module factory whose readiness marker follows bootstrap and shutdown lifecycle transitions.
 - `defineModule(cls, metadata)`: Programmatic module definition helper.
 - `bootstrapApplication(options)`: Lower-level async bootstrap function.
 
@@ -174,6 +177,7 @@ Lower-level Node compression internals stay behind the `@fluojs/runtime/internal
 - [@fluojs/di](../di): Dependency injection container implementation.
 - [@fluojs/http](../http): HTTP routing, controllers, and dispatcher.
 - [@fluojs/platform-nodejs](../platform-nodejs): Official Node.js HTTP adapter.
+- [@fluojs/studio](../studio): Viewer and rendering helpers for runtime-produced snapshots.
 
 ## Example Sources
 

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EAEX,uBAAuB,EAGvB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EAEf,wBAAwB,EACxB,+BAA+B,EAC/B,yBAAyB,EAEzB,gBAAgB,EAChB,UAAU,EAKX,MAAM,YAAY,CAAC;AAoTpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,gBAAgB,GAAG,CAAC,CAIjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CA0B7G;AAkgBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,WAAW,CAAC,CA8GrG;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;OAOG;WACU,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,WAAW,CAAC;IAOzG;;;;;;;OAOG;WACU,wBAAwB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,kBAAkB,CAAC;IA6F9B;;;;;;;;OAQG;WACU,kBAAkB,CAC7B,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC;CAuBpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,oBAAc,CAAC"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EAEX,uBAAuB,EAGvB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EAEf,wBAAwB,EACxB,+BAA+B,EAC/B,yBAAyB,EAEzB,gBAAgB,EAChB,UAAU,EAKX,MAAM,YAAY,CAAC;AA0TpB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,gBAAgB,GAAG,CAAC,CAIjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CA0B7G;AAogBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,WAAW,CAAC,CAiHrG;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;OAOG;WACU,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,WAAW,CAAC;IAOzG;;;;;;;OAOG;WACU,wBAAwB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,kBAAkB,CAAC;IAgG9B;;;;;;;;OAQG;WACU,kBAAkB,CAC7B,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC;CAuBpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,oBAAc,CAAC"}

package/dist/bootstrap.js

@@ -67,6 +67,7 @@ async function runCleanupCallbacks(cleanups) {
 }
 async function closeRuntimeResources(options) {
   const errors = [];
+  resetReadinessState(options.modules);
   errors.push(...(await runCleanupCallbacks(options.runtimeCleanup)));
   try {
     await runShutdownHooks(options.lifecycleInstances, options.signal);
@@ -91,6 +92,7 @@ async function closeRuntimeResources(options) {
 }
 async function runBootstrapFailureCleanup(options) {
   const errors = [];
+  resetReadinessState(options.modules);
   errors.push(...(await runCleanupCallbacks(options.runtimeCleanup)));
   if (options.lifecycleInstances.length > 0) {
     try {
@@ -363,6 +365,7 @@ class FluoApplication {
         adapter: this.adapter,
         container: this.container,
         lifecycleInstances: this.lifecycleInstances,
+        modules: this.modules,
         runtimeCleanup: this.runtimeCleanup,
         signal
       });
@@ -403,6 +406,7 @@ class FluoApplicationContext {
       await closeRuntimeResources({
         container: this.container,
         lifecycleInstances: this.lifecycleInstances,
+        modules: this.modules,
         runtimeCleanup: this.runtimeCleanup,
         signal
       });
@@ -654,6 +658,7 @@ export async function bootstrapApplication(options) {
   const logger = options.logger ?? createConsoleApplicationLogger();
   let lifecycleInstances = [];
   let bootstrappedContainer;
+  let bootstrappedModules = [];
   const hasHttpAdapter = options.adapter !== undefined;
   const adapter = options.adapter ?? {
     async close() {},
@@ -689,6 +694,7 @@ export async function bootstrapApplication(options) {
       });
     }
     bootstrappedContainer = bootstrapped.container;
+    bootstrappedModules = bootstrapped.modules;
     const resolveLifecycleStart = timingEnabled ? runtimePerformance.now() : 0;
     lifecycleInstances = await resolveBootstrapLifecycleInstances(bootstrapped, runtimeProviders);
     lifecycleInstances.push({
@@ -726,6 +732,7 @@ export async function bootstrapApplication(options) {
       container: bootstrappedContainer,
       lifecycleInstances,
       logger,
+      modules: bootstrappedModules,
       runtimeCleanup,
       scope: 'application'
     });
@@ -764,6 +771,7 @@ export class FluoFactory {
     const logger = options.logger ?? createConsoleApplicationLogger();
     let lifecycleInstances = [];
     let bootstrappedContainer;
+    let bootstrappedModules = [];
     const runtimeCleanup = [];
     const platformShell = createRuntimePlatformShell(options.platform?.components);
     const timingEnabled = options.diagnostics?.timing === true;
@@ -794,6 +802,7 @@ export class FluoFactory {
         });
       }
       bootstrappedContainer = bootstrapped.container;
+      bootstrappedModules = bootstrapped.modules;
       const resolveLifecycleStart = timingEnabled ? runtimePerformance.now() : 0;
       lifecycleInstances = await resolveBootstrapLifecycleInstances(bootstrapped, runtimeProviders);
       lifecycleInstances.push({
@@ -823,6 +832,7 @@ export class FluoFactory {
         container: bootstrappedContainer,
         lifecycleInstances,
         logger,
+        modules: bootstrappedModules,
         runtimeCleanup,
         scope: 'application context'
       });

package/package.json

@@ -9,7 +9,7 @@
     "module-graph",
     "orchestration"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -67,14 +67,14 @@
     "dist"
   ],
   "dependencies": {
+    "@fluojs/config": "^1.0.0-beta.2",
     "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/config": "^1.0.0-beta.1",
-    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.2",
     "@fluojs/http": "^1.0.0-beta.1"
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/serialization": "^1.0.0-beta.1"
+    "@fluojs/serialization": "^1.0.0-beta.2"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",