@fluojs/terminus 1.0.1 → 1.0.3

package/README.ko.md

@@ -24,6 +24,12 @@ fluo 애플리케이션을 위한 헬스 인디케이터(Health Indicator) 툴
 pnpm add @fluojs/terminus
 ```
 
+Redis indicator subpath를 사용할 때만 선택적 peer를 설치하세요.
+
+```bash
+pnpm add @fluojs/redis ioredis
+```
+
 `path`로 health endpoint를 custom path 아래에 mount할 수 있고, `readinessChecks`로 애플리케이션별 readiness logic을 Terminus indicator 및 platform readiness check와 합성할 수 있습니다.
 
 ## 사용 시점
@@ -92,6 +98,8 @@ TerminusModule.forRoot({
 });
 ```
 
+`@fluojs/terminus/redis`를 통해 만든 Redis indicator는 `@fluojs/redis`에서 받은 client가 있으면 lifecycle-aware로 동작합니다. Terminus는 `PING`을 보내기 전에 Redis connection state를 `createRedisPlatformStatusSnapshot(...)`으로 매핑하므로, client가 `wait`, `connecting`, `reconnecting`, `close`, `end` 상태이면 raw ping만 믿지 않고 `/health`와 `/ready`를 unavailable로 표시합니다. Custom `ping` callback은 manual probe용으로 계속 지원되지만, lifecycle metadata는 Redis client가 `status`를 노출할 때만 붙습니다.
+
 Drizzle의 경우 `createDrizzleHealthIndicatorProvider()`는 `@fluojs/drizzle`이 노출하는 lifecycle-aware `DrizzleDatabase` wrapper를 우선 사용합니다. Drizzle이 종료 중이거나 중지되었거나 `DrizzleDatabase.createPlatformStatusSnapshot()` 기준으로 준비되지 않은 상태이면 SQL probe를 실행하기 전에 해당 indicator를 `down`으로 보고합니다. legacy raw `DRIZZLE_DATABASE` handle만 등록된 경우에는 기존 lightweight SQL probe 동작을 유지합니다.
 
 Provider factory는 반복 등록할 수 있습니다. 각 인스턴스가 서로 다른 indicator key나 dependency option을 사용한다면 같은 factory가 만든 provider 여러 개를 하나의 `indicatorProviders` 배열에 등록할 수 있으며, Terminus는 나중에 등록된 같은 타입 provider가 앞선 provider를 덮어쓰지 않도록 각 provider 인스턴스를 별도 DI token으로 보관합니다.
@@ -125,6 +133,7 @@ TerminusModule.forRoot({
 - 플랫폼 health/readiness 실패는 `/health` 응답에서 결정적인 `fluo-platform-health`, `fluo-platform-readiness` contributor로 노출됩니다.
 - 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로 표시합니다.
 
 ## 공개 API 개요
 
@@ -151,6 +160,7 @@ TerminusModule.forRoot({
 
 - `RedisHealthIndicator`, `createRedisHealthIndicator()`, `createRedisHealthIndicatorProvider()`
   - Redis 전용 인디케이터 헬퍼는 선택적 Redis 피어가 설치되지 않은 환경에서도 루트 패키지 import가 안전하도록 전용 subpath에서 export됩니다.
+  - Provider는 기본적으로 default `@fluojs/redis` client token을 resolve하고, `clientName`이 있으면 named token을 resolve하며, Redis platform status semantics를 readiness 진단에 재사용합니다.
 
 ### `@fluojs/terminus/node`
 

package/README.md

@@ -24,6 +24,12 @@ Health indicator toolkit for fluo applications. `@fluojs/terminus` layers on top
 pnpm add @fluojs/terminus
 ```
 
+Install the optional peer only when you use the Redis indicator subpath:
+
+```bash
+pnpm add @fluojs/redis ioredis
+```
+
 ## When to Use
 
 - When you need to monitor external dependencies (databases, Redis, APIs) as part of your application's health status.
@@ -90,6 +96,8 @@ TerminusModule.forRoot({
 });
 ```
 
+Redis indicators created through `@fluojs/terminus/redis` are lifecycle-aware when they receive a client from `@fluojs/redis`. Terminus maps the Redis connection state with `createRedisPlatformStatusSnapshot(...)` before sending `PING`, so clients in `wait`, `connecting`, `reconnecting`, `close`, or `end` states mark `/health` and `/ready` unavailable instead of relying on a raw ping alone. Custom `ping` callbacks remain supported for manual probes, but lifecycle metadata is only attached when a Redis client exposes its `status`.
+
 For Drizzle, `createDrizzleHealthIndicatorProvider()` prefers the lifecycle-aware `DrizzleDatabase` wrapper exported by `@fluojs/drizzle`. The indicator reports `down` before probing SQL whenever Drizzle is shutting down, stopped, or otherwise not ready according to `DrizzleDatabase.createPlatformStatusSnapshot()`. If only the legacy raw `DRIZZLE_DATABASE` handle is registered, the provider keeps the previous lightweight SQL probe behavior.
 
 Provider factories are repeatable. You may register multiple providers created by the same factory in one `indicatorProviders` array when each instance uses a distinct indicator key or dependency option; Terminus keeps every provider instance under its own DI token instead of letting later same-type providers overwrite earlier ones.
@@ -125,6 +133,7 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 - Platform health/readiness failures are surfaced as deterministic `fluo-platform-health` and `fluo-platform-readiness` contributors in `/health` responses.
 - `/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.
 
 ## Public API Overview
 
@@ -151,6 +160,7 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 
 - `RedisHealthIndicator`, `createRedisHealthIndicator()`, `createRedisHealthIndicatorProvider()`
   - Redis-specific indicator helpers are exported from the dedicated subpath so the root package stays import-safe without the optional Redis peer installed.
+  - The provider resolves the default `@fluojs/redis` client token by default, or a named token when `clientName` is supplied, and reuses Redis platform status semantics for readiness diagnostics.
 
 ### `@fluojs/terminus/node`
 

package/dist/indicators/redis.d.ts

@@ -1,31 +1,49 @@
 import type { Provider } from '@fluojs/di';
+import { type RedisStatusAdapterInput } from '@fluojs/redis';
 import type { HealthIndicator, HealthIndicatorResult } from '../types.js';
 interface RedisClientLike {
     ping?: () => Promise<unknown>;
+    status?: RedisStatusAdapterInput['status'];
 }
-/** Options for probing Redis connectivity. */
+/**
+ * Options for probing Redis connectivity.
+ *
+ * `client` may be a raw `ioredis`-compatible handle resolved from `@fluojs/redis`.
+ * When that handle exposes a Redis `status`, Terminus maps the lifecycle state into
+ * health/readiness metadata before issuing `PING`, so shutdown or disconnected clients
+ * fail readiness even if a raw ping callback would still be callable.
+ */
 export interface RedisHealthIndicatorOptions {
+    /** Raw Redis client to probe. Its `status` is used for lifecycle-aware readiness when available. */
     client?: RedisClientLike;
+    /** Named Redis registration to resolve when using `createRedisHealthIndicatorProvider(...)`. */
     clientName?: string;
+    /** Indicator result key override. Defaults to the key passed to `check(...)`, then `redis`. */
     key?: string;
+    /** Custom ping callback for manual probes or tests. Lifecycle state is only mapped when `client.status` is available. */
     ping?: () => Promise<unknown> | unknown;
+    /** Maximum time to wait for the ping operation. Defaults to `2_000` ms. */
     timeoutMs?: number;
 }
 /**
  * Create a Redis health indicator.
  *
- * @param options Optional Redis client, ping callback, timeout, and key override.
- * @returns A health indicator that checks Redis with `PING` semantics.
+ * @param options Optional Redis client, named-client hint, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Redis lifecycle status before `PING` when client state is available.
  */
 export declare function createRedisHealthIndicator(options?: RedisHealthIndicatorOptions): HealthIndicator;
 /**
  * Create a provider that resolves a Redis client from DI and wraps it as an indicator.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * The provider resolves `getRedisClientToken(options.clientName)`, preserving the
+ * default-vs-named client lifecycle boundary from `@fluojs/redis` while keeping the
+ * Redis-specific peer dependency isolated to `@fluojs/terminus/redis`.
+ *
+ * @param options Optional named-client hint, timeout, key override, or custom ping callback.
  * @returns A factory provider that exposes `RedisHealthIndicator` from the DI container.
  */
 export declare function createRedisHealthIndicatorProvider(options?: Omit<RedisHealthIndicatorOptions, 'client'>): Provider;
-/** Health indicator that checks Redis reachability with a ping-like operation. */
+/** Health indicator that maps Redis lifecycle status and checks reachability with a ping-like operation. */
 export declare class RedisHealthIndicator implements HealthIndicator {
     private readonly options;
     readonly key: string | undefined;

package/dist/indicators/redis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/indicators/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmBD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CAErG;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQtH;AAED,kFAAkF;AAClF,qBAAa,oBAAqB,YAAW,eAAe;IAG9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,2BAAgC;IAIhE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAczD"}
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/indicators/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAA+E,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAG1I,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oGAAoG;IACpG,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CAErG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQtH;AAED,4GAA4G;AAC5G,qBAAa,oBAAqB,YAAW,eAAe;IAG9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,2BAAgC;IAIhE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAwBzD"}

package/dist/indicators/redis.js

@@ -1,7 +1,14 @@
-import { getRedisClientToken } from '@fluojs/redis';
+import { createRedisPlatformStatusSnapshot, getRedisClientToken, getRedisComponentId } from '@fluojs/redis';
 import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
 
-/** Options for probing Redis connectivity. */
+/**
+ * Options for probing Redis connectivity.
+ *
+ * `client` may be a raw `ioredis`-compatible handle resolved from `@fluojs/redis`.
+ * When that handle exposes a Redis `status`, Terminus maps the lifecycle state into
+ * health/readiness metadata before issuing `PING`, so shutdown or disconnected clients
+ * fail readiness even if a raw ping callback would still be callable.
+ */
 
 const DEFAULT_REDIS_TIMEOUT_MS = 2_000;
 async function runRedisPing(options) {
@@ -15,12 +22,46 @@ async function runRedisPing(options) {
   }
   await client.ping();
 }
+function createRedisLifecycleDownResult(indicatorKey, options) {
+  const status = options.client?.status;
+  if (!status) {
+    return undefined;
+  }
+  const snapshot = createRedisPlatformStatusSnapshot({
+    componentId: getRedisComponentId(options.clientName),
+    status
+  });
+  if (snapshot.health.status === 'healthy' && snapshot.readiness.status === 'ready') {
+    return undefined;
+  }
+  const message = snapshot.readiness.reason ?? snapshot.health.reason ?? `Redis lifecycle reported health=${snapshot.health.status} readiness=${snapshot.readiness.status}.`;
+  return createDownResult(indicatorKey, message, {
+    details: snapshot.details,
+    healthStatus: snapshot.health.status,
+    readinessStatus: snapshot.readiness.status
+  });
+}
+function createRedisLifecycleUpDetails(options) {
+  const status = options.client?.status;
+  if (!status) {
+    return {};
+  }
+  const snapshot = createRedisPlatformStatusSnapshot({
+    componentId: getRedisComponentId(options.clientName),
+    status
+  });
+  return {
+    details: snapshot.details,
+    healthStatus: snapshot.health.status,
+    readinessStatus: snapshot.readiness.status
+  };
+}
 
 /**
  * Create a Redis health indicator.
  *
- * @param options Optional Redis client, ping callback, timeout, and key override.
- * @returns A health indicator that checks Redis with `PING` semantics.
+ * @param options Optional Redis client, named-client hint, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Redis lifecycle status before `PING` when client state is available.
  */
 export function createRedisHealthIndicator(options = {}) {
   return new RedisHealthIndicator(options);
@@ -29,7 +70,11 @@ export function createRedisHealthIndicator(options = {}) {
 /**
  * Create a provider that resolves a Redis client from DI and wraps it as an indicator.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * The provider resolves `getRedisClientToken(options.clientName)`, preserving the
+ * default-vs-named client lifecycle boundary from `@fluojs/redis` while keeping the
+ * Redis-specific peer dependency isolated to `@fluojs/terminus/redis`.
+ *
+ * @param options Optional named-client hint, timeout, key override, or custom ping callback.
  * @returns A factory provider that exposes `RedisHealthIndicator` from the DI container.
  */
 export function createRedisHealthIndicatorProvider(options = {}) {
@@ -44,7 +89,7 @@ export function createRedisHealthIndicatorProvider(options = {}) {
   };
 }
 
-/** Health indicator that checks Redis reachability with a ping-like operation. */
+/** Health indicator that maps Redis lifecycle status and checks reachability with a ping-like operation. */
 export class RedisHealthIndicator {
   key;
   constructor(options = {}) {
@@ -55,9 +100,16 @@ export class RedisHealthIndicator {
     const indicatorKey = resolveIndicatorKey('redis', this.options.key ?? key);
     const timeoutMs = this.options.timeoutMs ?? DEFAULT_REDIS_TIMEOUT_MS;
     try {
+      const lifecycleDownResult = createRedisLifecycleDownResult(indicatorKey, this.options);
+      if (lifecycleDownResult) {
+        throwHealthCheckError('Redis health check failed.', lifecycleDownResult);
+      }
       await withIndicatorTimeout(runRedisPing(this.options), timeoutMs, indicatorKey);
-      return createUpResult(indicatorKey);
+      return createUpResult(indicatorKey, createRedisLifecycleUpDetails(this.options));
     } catch (error) {
+      if (error instanceof Error && error.name === 'HealthCheckError') {
+        throw error;
+      }
       throwHealthCheckError('Redis health check failed.', createDownResult(indicatorKey, error instanceof Error ? error.message : 'Redis health check failed.'));
     }
   }

package/package.json

@@ -9,7 +9,7 @@
     "liveness",
     "health-check"
   ],
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -44,14 +44,14 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.1",
-    "@fluojs/di": "^1.0.1",
-    "@fluojs/http": "^1.0.0",
-    "@fluojs/runtime": "^1.0.1"
+    "@fluojs/core": "^1.0.3",
+    "@fluojs/di": "^1.0.3",
+    "@fluojs/http": "^1.1.0",
+    "@fluojs/runtime": "^1.1.1"
   },
   "peerDependencies": {
-    "@fluojs/drizzle": "^1.0.0",
-    "@fluojs/prisma": "^1.0.0",
+    "@fluojs/drizzle": "^1.0.1",
+    "@fluojs/prisma": "^1.0.1",
     "@fluojs/redis": "^1.0.0"
   },
   "peerDependenciesMeta": {
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/testing": "^1.0.1"
+    "@fluojs/testing": "^1.0.3"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",