@fluojs/terminus 1.0.4 → 1.0.5

package/README.ko.md

@@ -14,6 +14,7 @@ fluo 애플리케이션을 위한 헬스 인디케이터(Health Indicator) 툴
   - [DI 기반 인디케이터](#di-기반-인디케이터)
   - [실행 가드레일](#실행-가드레일)
   - [실패 시맨틱](#실패-시맨틱)
+- [NestJS 마이그레이션 경계](#nestjs-마이그레이션-경계)
 - [공개 API 개요](#공개-api-개요)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -106,6 +107,8 @@ Provider factory는 반복 등록할 수 있습니다. 각 인스턴스가 서
 
 커스텀 인디케이터가 멈추거나 느린 하위 서비스에 의존할 수 있다면 `execution.indicatorTimeoutMs`를 사용하세요. probe가 설정된 시간을 넘기면 Terminus는 무기한 대기하지 않고 해당 인디케이터를 `down`으로 표시합니다.
 
+Terminus는 같은 indicator instance에 대한 check도 직렬화합니다. Timeout된 probe나 느린 probe가 아직 실행 중일 때 다른 `/health` 또는 `/ready` 요청이 들어오면, Terminus는 같은 downstream에 겹치는 probe를 새로 시작하지 않고 해당 indicator를 새 요청에서 `down`으로 보고합니다. Built-in HTTP indicator는 자체 timeout이 만료되면 `fetch` 요청을 abort하지만, 다른 driver와 custom callback은 cancellation을 노출하지 않을 수 있으므로 원래 promise가 settle될 때까지 overlap을 막는 방식으로 보호합니다.
+
 ```typescript
 TerminusModule.forRoot({
   execution: {
@@ -121,7 +124,7 @@ TerminusModule.forRoot({
 
 ### 실패 시맨틱
 
-인디케이터가 실패하면 `HealthCheckError`를 던집니다. `TerminusHealthService`는 이 실패들을 모아 보고서를 작성합니다.
+인디케이터가 `down` 결과를 반환하거나 `HealthCheckError`를 던지면, `TerminusHealthService`는 이 실패들을 모아 보고서를 작성합니다.
 
 - 하나 이상의 인디케이터가 실패하면 `/health`는 HTTP `503`을 반환합니다.
 - 등록된 indicator가 실패하거나, custom readiness check가 `false`를 반환하거나, runtime shutdown이 시작되었거나, platform readiness가 `ready`가 아닌 경우 `/ready`는 HTTP `503`을 반환합니다. Platform `critical` metadata는 diagnostics에 보존되지만 HTTP readiness endpoint 자체는 binary ready/unavailable gate이며 warning severity bucket을 노출하지 않습니다.
@@ -130,11 +133,19 @@ TerminusModule.forRoot({
 - 지원하지 않는 status, 빈 결과, 객체가 아닌 인디케이터 결과는 조용히 버려지지 않고 `down` 진단으로 보고됩니다.
 - Blank indicator result key는 healthy entry로 기여하지 않고 `down` 진단으로 보고됩니다.
 - 같은 실행에서 이미 보고된 key를 다른 인디케이터가 다시 사용하면, Terminus는 먼저 기록된 entry를 유지하고 데이터를 조용히 덮어쓰는 대신 결정적인 `*-duplicate-key-error` contributor를 추가합니다.
-- 플랫폼 health/readiness 실패는 `/health` 응답에서 결정적인 `fluo-platform-health`, `fluo-platform-readiness` contributor로 노출됩니다.
+- 플랫폼 health/readiness 실패는 `/health` 응답에서 결정적인 `fluo-platform-health`, `fluo-platform-readiness` contributor로 노출됩니다. 이 key들은 platform diagnostic용으로 예약되어 있으며, platform failure 중 user indicator가 같은 key를 반환하면 Terminus는 platform payload를 예약 key 아래에 유지하고 runtime state를 떨어뜨리지 않도록 결정적인 `*-user-key-collision` diagnostic을 추가합니다.
 - Runtime diagnostics가 있으면 `/health` response에 platform health/readiness detail을 담은 `platform` block이 포함될 수 있습니다.
 - DI provider로 생성한 Drizzle indicator는 SQL probe보다 먼저 Drizzle lifecycle readiness/health state를 반영하므로, underlying driver가 raw ping을 아직 받을 수 있어도 종료 중이거나 중지된 통합은 `/health`와 `/ready`를 unavailable로 표시합니다.
 - Redis subpath로 생성한 Redis indicator는 `PING` 전에 `@fluojs/redis` client lifecycle state를 반영하므로, 종료 중이거나 연결이 끊긴 Redis client는 command 실행 전에도 `/health`와 `/ready`를 unavailable로 표시합니다.
 
+## NestJS 마이그레이션 경계
+
+`@nestjs/terminus`에서 마이그레이션할 때는 `TerminusModule.forRoot(...)`를 fluo의 기본 API로 취급하세요. fluo는 `HealthCheckService.check([...])`를 호출하는 controller-level `@HealthCheck()` 메서드를 주요 애플리케이션 계약으로 모델링하지 않습니다. 테스트나 커스텀 애플리케이션 코드에서 `TerminusHealthService.check()`를 직접 호출할 수는 있지만, 프로덕션 엔드포인트 등록은 indicator와 readiness hook을 module option에 두어 runtime `/health`와 `/ready` 경로가 platform diagnostics를 일관되게 포함하도록 해야 합니다.
+
+Terminus는 별도의 process-only liveness route도 기본으로 만들지 않습니다. 기본 route model은 집계 헬스를 위한 `GET /health`, readiness를 위한 `GET /ready`입니다. 배포 환경에서 좁은 의미의 process liveness probe가 필요하다면, Terminus가 NestJS-style 추가 route를 만들어 준다고 가정하지 말고 애플리케이션 또는 배포 계층에서 해당 probe를 정의하세요.
+
+Runtime-specific indicator는 subpath별로 분리되어 있습니다. Node.js memory 및 disk check에는 `@fluojs/terminus/node`를 사용하고, Redis check에는 `@fluojs/terminus/redis`를 사용하세요. Root package는 Redis optional-peer import를 root entrypoint 밖에 두고 Node disk filesystem access도 lazy하게 유지하므로, 애플리케이션은 runtime-specific probe를 명시적으로 opt in합니다.
+
 ## 공개 API 개요
 
 ### `TerminusModule`

package/README.md

@@ -14,6 +14,7 @@ Health indicator toolkit for fluo applications. `@fluojs/terminus` layers on top
   - [DI-Backed Indicators](#di-backed-indicators)
   - [Execution Guardrails](#execution-guardrails)
   - [Failure Semantics](#failure-semantics)
+- [NestJS Migration Boundaries](#nestjs-migration-boundaries)
 - [Public API Overview](#public-api-overview)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -106,6 +107,8 @@ Provider factories are repeatable. You may register multiple providers created b
 
 Use `execution.indicatorTimeoutMs` when custom indicators might hang or depend on slow downstreams. When a probe exceeds the configured timeout, Terminus marks that indicator as `down` instead of waiting forever.
 
+Terminus also serializes checks per indicator instance. If a timed-out or otherwise slow probe is still running when another `/health` or `/ready` request arrives, Terminus reports that indicator as `down` for the new request instead of starting an overlapping probe against the same downstream. Built-in HTTP indicators abort their `fetch` request when their own timeout expires; other drivers and custom callbacks may not expose cancellation, so they are protected from overlap until the original promise settles.
+
 ```typescript
 TerminusModule.forRoot({
   execution: {
@@ -121,7 +124,7 @@ Use `path` to mount the health endpoints under a custom path, and `readinessChec
 
 ### Failure Semantics
 
-When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthService` aggregates these failures into a report:
+When an indicator returns a `down` result or throws a `HealthCheckError`, the `TerminusHealthService` aggregates the failure into a report:
 
 - `/health` returns HTTP `503` if any indicator fails.
 - `/ready` returns HTTP `503` when registered indicators fail, a custom readiness check returns `false`, runtime shutdown has begun, or platform readiness is anything other than `ready`. Platform `critical` metadata is preserved in diagnostics, but the HTTP readiness endpoint itself is a binary ready/unavailable gate and does not expose warning severity buckets.
@@ -130,11 +133,19 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 - Unsupported, empty, or non-object indicator results are reported as `down` diagnostics instead of being silently discarded.
 - Blank indicator result keys are reported as `down` diagnostics instead of contributing healthy entries.
 - If an indicator reuses a key that was already reported earlier in the same run, Terminus keeps the first entry and adds a deterministic `*-duplicate-key-error` contributor instead of silently overwriting data.
-- Platform health/readiness failures are surfaced as deterministic `fluo-platform-health` and `fluo-platform-readiness` contributors in `/health` responses.
+- Platform health/readiness failures are surfaced as deterministic `fluo-platform-health` and `fluo-platform-readiness` contributors in `/health` responses. These keys are reserved for platform diagnostics; if a user indicator returns one of them during a platform failure, Terminus keeps the platform payload under the reserved key and adds a deterministic `*-user-key-collision` diagnostic instead of dropping runtime state.
 - `/health` responses may include a `platform` block with platform health/readiness details when runtime diagnostics are available.
 - Drizzle indicators created through the DI provider map Drizzle lifecycle readiness/health state before SQL probing, so shutdown or stopped integrations mark `/health` and `/ready` as unavailable even if the underlying driver still accepts a raw ping.
 - Redis indicators created through the Redis subpath map `@fluojs/redis` client lifecycle state before `PING`, so shutdown or disconnected Redis clients mark `/health` and `/ready` as unavailable even before command execution.
 
+## NestJS Migration Boundaries
+
+When migrating from `@nestjs/terminus`, treat `TerminusModule.forRoot(...)` as the primary fluo API. fluo does not model controller-level `@HealthCheck()` methods that call `HealthCheckService.check([...])` as the main application contract. You can still call `TerminusHealthService.check()` directly from tests or custom application code, but production endpoint registration should keep indicators and readiness hooks in module options so the runtime `/health` and `/ready` routes include platform diagnostics consistently.
+
+Terminus also does not create a separate process-only liveness route by default. The default route model remains `GET /health` for aggregated health and `GET /ready` for readiness. If your deployment requires a narrow process liveness probe, define that probe at the application or deployment layer instead of assuming Terminus will add a NestJS-style extra route.
+
+Runtime-specific indicators are split by subpath. Use `@fluojs/terminus/node` for Node.js memory and disk checks, and use `@fluojs/terminus/redis` for Redis checks. The root package keeps Redis optional-peer imports out of the root entrypoint and keeps Node disk filesystem access lazy so applications opt into runtime-specific probes explicitly.
+
 ## Public API Overview
 
 ### `TerminusModule`

package/dist/health-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../src/health-check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EAGhB,MAAM,YAAY,CAAC;AAyQpB;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,SAAyB,GAAG,iBAAiB,CAMhH;AAED,0FAA0F;AAC1F,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC;IAGrE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}
+{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../src/health-check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EAGhB,MAAM,YAAY,CAAC;AAqTpB;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,SAAyB,GAAG,iBAAiB,CAMhH;AAED,0FAA0F;AAC1F,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC;IAGrE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}

package/dist/health-check.js

@@ -1,4 +1,5 @@
 import { HealthCheckError } from './errors.js';
+const runningIndicatorChecks = new WeakMap();
 function normalizeIndicatorTimeoutMs(value) {
   if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
     return undefined;
@@ -8,6 +9,32 @@ function normalizeIndicatorTimeoutMs(value) {
 function createTimeoutMessage(timeoutMs) {
   return `Health indicator timed out after ${String(timeoutMs)}ms.`;
 }
+function createInFlightResult(key) {
+  return {
+    [key]: {
+      message: 'A previous health indicator probe is still running; Terminus will not start an overlapping probe for the same indicator instance.',
+      status: 'down'
+    }
+  };
+}
+function startSerializedIndicatorCheck(indicator, key) {
+  const runningCheck = runningIndicatorChecks.get(indicator);
+  if (runningCheck) {
+    return undefined;
+  }
+  const check = Promise.resolve().then(() => indicator.check(key));
+  runningIndicatorChecks.set(indicator, check);
+  check.then(() => {
+    if (runningIndicatorChecks.get(indicator) === check) {
+      runningIndicatorChecks.delete(indicator);
+    }
+  }, () => {
+    if (runningIndicatorChecks.get(indicator) === check) {
+      runningIndicatorChecks.delete(indicator);
+    }
+  });
+  return check;
+}
 async function withTimeout(promise, timeoutMs) {
   let timer;
   try {
@@ -137,8 +164,15 @@ function createDuplicateKeyFailure(indicatorKey, duplicateKeys, seenKeys) {
 async function runIndicator(indicator, index, executionOptions) {
   const key = inferIndicatorKey(indicator, index);
   const indicatorTimeoutMs = normalizeIndicatorTimeoutMs(executionOptions.indicatorTimeoutMs);
+  const runningCheck = startSerializedIndicatorCheck(indicator, key);
+  if (!runningCheck) {
+    return {
+      entries: Object.entries(createInFlightResult(key)),
+      indicatorKey: key
+    };
+  }
   try {
-    const result = indicatorTimeoutMs === undefined ? await indicator.check(key) : await withTimeout(indicator.check(key), indicatorTimeoutMs);
+    const result = indicatorTimeoutMs === undefined ? await runningCheck : await withTimeout(runningCheck, indicatorTimeoutMs);
     return {
       entries: normalizeIndicatorResult(key, result),
       indicatorKey: key

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAA4D,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAyQlH,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAA4D,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAiSlH,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}

package/dist/module.js

@@ -83,7 +83,7 @@ function createPlatformReadinessDiagnostic(readiness) {
   };
 }
 function createPlatformDiagnosticCollisionKey(diagnosticKey, seenKeys) {
-  const baseKey = `${diagnosticKey}-duplicate-key-error`;
+  const baseKey = `${diagnosticKey}-user-key-collision`;
   if (!seenKeys.has(baseKey)) {
     return baseKey;
   }
@@ -95,42 +95,51 @@ function createPlatformDiagnosticCollisionKey(diagnosticKey, seenKeys) {
   }
   return candidate;
 }
-function appendPlatformDiagnostic(entries, existingKeys, diagnosticKey, diagnostic) {
+function appendPlatformDiagnostic(entries, collisionEntries, diagnosticKey, diagnostic) {
   if (diagnostic === undefined) {
     return;
   }
-  if (!existingKeys.has(diagnosticKey) && !(diagnosticKey in entries)) {
-    entries[diagnosticKey] = diagnostic;
-    return;
+  if (diagnosticKey in collisionEntries) {
+    const collisionKey = createPlatformDiagnosticCollisionKey(diagnosticKey, new Set([...Object.keys(entries), ...Object.keys(collisionEntries)]));
+    entries[collisionKey] = {
+      message: `User health result key "${diagnosticKey}" is reserved for Terminus platform diagnostics; the platform diagnostic remains available under the reserved key.`,
+      status: 'down'
+    };
   }
-  const collisionKey = createPlatformDiagnosticCollisionKey(diagnosticKey, new Set([...existingKeys, ...Object.keys(entries)]));
-  entries[collisionKey] = {
-    message: `Platform diagnostic key "${diagnosticKey}" collided with an existing health result key.`,
-    status: 'down'
-  };
+  entries[diagnosticKey] = diagnostic;
+}
+function withoutKeys(entries, keys) {
+  return Object.fromEntries(Object.entries(entries).filter(([key]) => !keys.has(key)));
+}
+function remapContributors(contributors, reservedKeys, platformDiagnosticKeys) {
+  return contributors.filter(key => !reservedKeys.has(key) && !platformDiagnosticKeys.includes(key));
 }
 function withPlatformDiagnostics(report, health, readiness) {
   const platformDiagnostics = {};
   const healthDiagnostic = createPlatformHealthDiagnostic(health);
   const readinessDiagnostic = createPlatformReadinessDiagnostic(readiness);
-  const existingKeys = new Set(Object.keys(report.details));
-  appendPlatformDiagnostic(platformDiagnostics, existingKeys, 'fluo-platform-health', healthDiagnostic);
-  appendPlatformDiagnostic(platformDiagnostics, existingKeys, 'fluo-platform-readiness', readinessDiagnostic);
+  appendPlatformDiagnostic(platformDiagnostics, report.details, 'fluo-platform-health', healthDiagnostic);
+  appendPlatformDiagnostic(platformDiagnostics, report.details, 'fluo-platform-readiness', readinessDiagnostic);
   const platformDiagnosticKeys = Object.keys(platformDiagnostics);
+  const platformReservedKeys = new Set([...(healthDiagnostic ? ['fluo-platform-health'] : []), ...(readinessDiagnostic ? ['fluo-platform-readiness'] : [])]);
+  const reportDetails = withoutKeys(report.details, platformReservedKeys);
+  const reportInfo = withoutKeys(report.info, platformReservedKeys);
+  const reportError = withoutKeys(report.error, platformReservedKeys);
   return {
     ...report,
     contributors: {
-      down: [...report.contributors.down, ...platformDiagnosticKeys],
-      up: [...report.contributors.up]
+      down: [...remapContributors(report.contributors.down, platformReservedKeys, platformDiagnosticKeys), ...platformDiagnosticKeys],
+      up: remapContributors(report.contributors.up, platformReservedKeys, platformDiagnosticKeys)
     },
     details: {
-      ...report.details,
+      ...reportDetails,
       ...platformDiagnostics
     },
     error: {
-      ...report.error,
+      ...reportError,
       ...platformDiagnostics
     },
+    info: reportInfo,
     platform: {
       health,
       readiness

package/package.json

@@ -9,7 +9,7 @@
     "liveness",
     "health-check"
   ],
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -46,13 +46,13 @@
   "dependencies": {
     "@fluojs/core": "^1.0.3",
     "@fluojs/di": "^1.1.0",
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/runtime": "^1.1.6"
+    "@fluojs/http": "^1.1.2",
+    "@fluojs/runtime": "^1.1.8"
   },
   "peerDependencies": {
-    "@fluojs/drizzle": "^1.0.2",
-    "@fluojs/prisma": "^1.0.2",
-    "@fluojs/redis": "^1.0.1"
+    "@fluojs/drizzle": "^1.1.0",
+    "@fluojs/prisma": "^1.1.0",
+    "@fluojs/redis": "^1.0.2"
   },
   "peerDependenciesMeta": {
     "@fluojs/drizzle": {
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/testing": "^1.0.5"
+    "@fluojs/testing": "^1.0.6"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",