@fluojs/redis 1.0.0-beta.3 → 1.0.0-beta.5

package/README.ko.md

@@ -79,6 +79,7 @@ export class CacheRepository {
 
 - 호출자가 옵션을 강제로 캐스팅하더라도 Fluo는 항상 `lazyConnect: true`를 강제하므로, 소켓은 import 시점이 아니라 애플리케이션 bootstrap 중에 열립니다.
 - bootstrap 단계에서는 클라이언트가 ioredis `wait` 상태일 때만 lifecycle service가 `connect()`를 호출합니다.
+- lifecycle이 소유한 `connect()`와 `quit()` 호출은 package timeout(기본 `10_000` ms)으로 제한되어, Redis 명령이 멈춰도 bootstrap/shutdown이 무기한 대기하지 않습니다. `lifecycle.connectTimeoutMs`와 `lifecycle.quitTimeoutMs`로 재정의할 수 있으며, host process가 의도적으로 무제한 대기를 소유하는 경우에만 `0`을 전달하세요.
 - shutdown 단계에서는 ready/connecting 계열 상태에 `quit()`를 우선 시도해 정상 종료를 노리고, wait/종료 전이 상태에서는 `disconnect()`를 직접 사용합니다.
 - `quit()`가 실패하면 Fluo는 `disconnect()`로 fallback하고, 그 뒤에도 클라이언트가 닫히지 않은 경우에만 에러를 다시 던집니다.
 
@@ -124,10 +125,12 @@ export class AnalyticsStore {
 
 ### 원시 클라이언트 접근 (Raw Client Access)
 
-파이프라인, Lua 스크립트, Pub/Sub 등 복잡한 Redis 명령이 필요한 경우 원시 클라이언트를 직접 주입받아 사용합니다.
+파이프라인이나 Lua 스크립트처럼 복잡한 Redis 명령이 필요한 경우 원시 클라이언트를 직접 주입받아 사용합니다.
 
 이미 `RedisService`를 주입받았다면 `redis.getRawClient()`로 같은 underlying `ioredis` instance에 접근할 수 있습니다.
 
+Redis Pub/Sub은 일반적인 shared-client 재사용의 예외입니다. Redis는 구독한 연결을 subscribe mode로 전환하므로, lifecycle-managed `REDIS_CLIENT`나 `RedisService.getRawClient()` 결과를 publisher와 subscriber로 동시에 사용하지 마세요. `client.duplicate()`로 전용 subscriber 연결을 만들거나 명시적인 `RedisModule.forRoot({ name: 'subscriber', ... })` 등록을 사용하고, 그 연결도 별도 lifecycle owner를 갖게 하세요.
+
 ```typescript
 import { Inject } from '@fluojs/core';
 import { REDIS_CLIENT } from '@fluojs/redis';
@@ -147,7 +150,7 @@ export class AdvancedService {
 
 ### 핵심 구성 요소
 - `RedisModule`: Redis 클라이언트 등록 및 수명 주기 훅을 관리합니다.
-- `RedisModule.forRoot(options)`: `name`을 생략하면 기본 Redis 클라이언트와 `RedisService` 파사드를 등록하고, `name`을 제공하면 추가 이름 있는 Redis 클라이언트를 등록합니다. 기본 등록은 기본적으로 global이고, 이름 있는 등록은 scoped입니다.
+- `RedisModule.forRoot(options)`: `name`을 생략하면 기본 Redis 클라이언트와 `RedisService` 파사드를 등록하고, `name`을 제공하면 추가 이름 있는 Redis 클라이언트를 등록합니다. 기본 등록은 기본적으로 global이고, 이름 있는 등록은 scoped입니다. `lifecycle.connectTimeoutMs`와 `lifecycle.quitTimeoutMs`로 Fluo가 소유한 연결 시작/종료 시간을 제한할 수 있습니다.
 - `RedisService`: JSON 코덱 지원 및 `get`/`set`/`del` 메서드를 제공하는 파사드입니다.
 - `REDIS_CLIENT`: 내부 `ioredis` 인스턴스에 접근하기 위한 DI 토큰입니다.
 - `DEFAULT_REDIS_CLIENT_NAME`: 안정적인 기본 Redis client name입니다.
@@ -157,7 +160,8 @@ export class AdvancedService {
 - `createRedisPlatformStatusSnapshot(input)`: Redis 연결 상태를 Fluo 플랫폼 health/readiness 스냅샷으로 변환합니다.
 
 ### 타입
-- `RedisModuleOptions`: `ioredis` 생성자에 전달되는 설정 옵션입니다.
+- `RedisModuleOptions`: Fluo가 module-only `name`, `global`, `lifecycle` 필드를 제거한 뒤 `ioredis` 생성자에 전달하는 설정 옵션입니다.
+- `RedisLifecycleOptions`: Fluo가 소유한 `connect()`와 `quit()` lifecycle command의 timeout을 조정하는 선택적 옵션입니다.
 - `PersistencePlatformStatusSnapshot`, `RedisStatusAdapterInput`: status snapshot input/output type입니다.
 
 ## 관련 패키지

package/README.md

@@ -79,6 +79,7 @@ export class CacheRepository {
 
 - Fluo always forces `lazyConnect: true`, even if callers cast options manually, so sockets open during application bootstrap instead of import time.
 - During bootstrap, the lifecycle service only calls `connect()` while the client is still in ioredis `wait` state.
+- Lifecycle-owned `connect()` and `quit()` calls are bounded by package timeouts (`10_000` ms by default) so bootstrap and shutdown do not wait forever on a stalled Redis command. Override them with `lifecycle.connectTimeoutMs` and `lifecycle.quitTimeoutMs`; pass `0` only when the host process intentionally owns an unbounded wait.
 - During shutdown, ready/connecting clients attempt `quit()` first for graceful teardown, while wait/closed-transition states use `disconnect()` directly.
 - If `quit()` fails, Fluo falls back to `disconnect()` and only rethrows when the client still remains open afterward.
 
@@ -124,10 +125,12 @@ export class AnalyticsStore {
 
 ### Raw Client Access
 
-If you need advanced Redis commands (pipelines, lua scripts, pub/sub), inject the raw client directly.
+If you need advanced Redis commands (pipelines or Lua scripts), inject the raw client directly.
 
 If you already injected `RedisService`, call `redis.getRawClient()` to access the same underlying `ioredis` instance.
 
+Redis Pub/Sub is the exception to ordinary shared-client reuse: Redis switches subscribed connections into subscribe mode, so do not use the lifecycle-managed `REDIS_CLIENT` or a `RedisService.getRawClient()` result as both publisher and subscriber. Create a dedicated subscriber connection with `client.duplicate()` (or an explicitly named `RedisModule.forRoot({ name: 'subscriber', ... })` registration) and let that connection have its own lifecycle owner.
+
 ```typescript
 import { Inject } from '@fluojs/core';
 import { REDIS_CLIENT } from '@fluojs/redis';
@@ -147,7 +150,7 @@ export class AdvancedService {
 
 ### Core
 - `RedisModule`: Registers Redis clients and lifecycle hooks.
-- `RedisModule.forRoot(options)`: Registers the default Redis client plus `RedisService` facade when `name` is omitted, or an additional named Redis client when `name` is provided. The default registration is global by default; named registrations are scoped.
+- `RedisModule.forRoot(options)`: Registers the default Redis client plus `RedisService` facade when `name` is omitted, or an additional named Redis client when `name` is provided. The default registration is global by default; named registrations are scoped. Use `lifecycle.connectTimeoutMs` and `lifecycle.quitTimeoutMs` to bound Fluo-owned connection startup and shutdown.
 - `RedisService`: Facade with JSON codec support and `get`/`set`/`del` methods.
 - `REDIS_CLIENT`: DI token for the underlying `ioredis` instance.
 - `DEFAULT_REDIS_CLIENT_NAME`: Stable default Redis client name.
@@ -157,7 +160,8 @@ export class AdvancedService {
 - `createRedisPlatformStatusSnapshot(input)`: Adapts Redis connection state into Fluo's platform health/readiness snapshot contract.
 
 ### Types
-- `RedisModuleOptions`: Configuration options passed directly to the `ioredis` constructor.
+- `RedisModuleOptions`: Configuration options passed to the `ioredis` constructor after Fluo removes module-only `name`, `global`, and `lifecycle` fields.
+- `RedisLifecycleOptions`: Optional timeout controls for Fluo-owned `connect()` and `quit()` lifecycle commands.
 - `PersistencePlatformStatusSnapshot`, `RedisStatusAdapterInput`: Status snapshot input/output types.
 
 ## Related Packages

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMhE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoGzE,yEAAyE;AACzE,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;CAYxD"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMhE,OAAO,KAAK,EAA6C,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA8GhG,yEAAyE;AACzE,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;CAYxD"}

package/dist/module.js

@@ -24,6 +24,7 @@ function getRedisLifecycleToken(name) {
 function normalizeRedisModuleOptions(options) {
   const {
     global,
+    lifecycle,
     name,
     ...clientOptions
   } = options;
@@ -37,10 +38,11 @@ function normalizeRedisModuleOptions(options) {
   return {
     clientOptions,
     global: normalizedName === undefined ? global ?? true : false,
+    lifecycleOptions: lifecycle ?? {},
     name: normalizedName
   };
 }
-function createRedisProviders(options, name) {
+function createRedisProviders(options, lifecycleOptions, name) {
   const clientToken = getRedisClientToken(name);
   if (clientToken === REDIS_CLIENT) {
     return [{
@@ -50,7 +52,15 @@ function createRedisProviders(options, name) {
         ...options,
         lazyConnect: true
       })
-    }, RedisService, RedisLifecycleService];
+    }, RedisService, {
+      inject: [REDIS_CLIENT],
+      provide: RedisLifecycleService,
+      scope: 'singleton',
+      useFactory: (...deps) => {
+        const [client] = deps;
+        return new RedisLifecycleService(client, undefined, lifecycleOptions);
+      }
+    }];
   }
   if (name === undefined) {
     throw new Error('Redis client name must be defined for named provider creation.');
@@ -77,7 +87,7 @@ function createRedisProviders(options, name) {
     scope: 'singleton',
     useFactory: (...deps) => {
       const [client] = deps;
-      return new RedisLifecycleService(client, name);
+      return new RedisLifecycleService(client, name, lifecycleOptions);
     }
   }];
 }
@@ -115,7 +125,7 @@ export class RedisModule {
     return defineModule(RedisModuleDefinition, {
       global: normalized.global,
       exports: normalized.name === undefined ? [REDIS_CLIENT, RedisService] : [clientToken, serviceToken],
-      providers: createRedisProviders(normalized.clientOptions, normalized.name)
+      providers: createRedisProviders(normalized.clientOptions, normalized.lifecycleOptions, normalized.name)
     });
   }
 }

package/dist/service.d.ts

@@ -1,17 +1,20 @@
 import type Redis from 'ioredis';
 import type { OnApplicationShutdown, OnModuleInit } from '@fluojs/runtime';
+import type { RedisLifecycleOptions } from './types.js';
 /**
  * Manages Redis client startup and shutdown as part of the application lifecycle.
  */
 export declare class RedisLifecycleService implements OnModuleInit, OnApplicationShutdown {
     private readonly client;
     private readonly clientName?;
-    constructor(client: Redis, clientName?: string | undefined);
+    private readonly lifecycleOptions;
+    constructor(client: Redis, clientName?: string | undefined, lifecycleOptions?: RedisLifecycleOptions);
     onModuleInit(): Promise<void>;
     onApplicationShutdown(): Promise<void>;
     createPlatformStatusSnapshot(): import("./status.js").PersistencePlatformStatusSnapshot;
     private shouldConnectOnInit;
     private disconnectIfPossible;
     private quitWithDisconnectFallback;
+    private describeClient;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAwB3E;;GAEG;AACH,qBACa,qBAAsB,YAAW,YAAY,EAAE,qBAAqB;IAE7E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;gBADX,MAAM,EAAE,KAAK,EACb,UAAU,CAAC,EAAE,MAAM,YAAA;IAGhC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ7B,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5C,4BAA4B;IAO5B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,oBAAoB;YAMd,0BAA0B;CAYzC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAI3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAiDxD;;GAEG;AACH,qBACa,qBAAsB,YAAW,YAAY,EAAE,qBAAqB;IAE7E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBAFhB,MAAM,EAAE,KAAK,EACb,UAAU,CAAC,EAAE,MAAM,YAAA,EACnB,gBAAgB,GAAE,qBAA0B;IAGzD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAY7B,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB5C,4BAA4B;IAO5B,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,oBAAoB;YAMd,0BAA0B;IAiBxC,OAAO,CAAC,cAAc;CAGvB"}

package/dist/service.js

@@ -9,6 +9,7 @@ import { createRedisPlatformStatusSnapshot } from './status.js';
 import { getRedisComponentId, REDIS_CLIENT } from './tokens.js';
 const QUITTABLE_STATUSES = new Set(['connect', 'connecting', 'ready', 'reconnecting']);
 const DISCONNECTABLE_STATUSES = new Set(['close', 'connect', 'connecting', 'ready', 'reconnecting', 'wait']);
+const DEFAULT_REDIS_LIFECYCLE_TIMEOUT_MS = 10_000;
 function isClosed(status) {
   return status === 'end';
 }
@@ -21,6 +22,26 @@ function isQuittable(status) {
 function isDisconnectable(status) {
   return DISCONNECTABLE_STATUSES.has(status);
 }
+function normalizeTimeoutMs(value) {
+  return value === undefined ? DEFAULT_REDIS_LIFECYCLE_TIMEOUT_MS : value;
+}
+async function withLifecycleTimeout(operation, timeoutMs, message) {
+  if (timeoutMs <= 0) {
+    return await operation;
+  }
+  let timeoutHandle;
+  try {
+    return await Promise.race([operation, new Promise((_resolve, reject) => {
+      timeoutHandle = setTimeout(() => {
+        reject(new Error(message));
+      }, timeoutMs);
+    })]);
+  } finally {
+    if (timeoutHandle !== undefined) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+}
 
 /**
  * Manages Redis client startup and shutdown as part of the application lifecycle.
@@ -30,15 +51,16 @@ class RedisLifecycleService {
   static {
     [_RedisLifecycleServic, _initClass] = _applyDecs(this, [Inject(REDIS_CLIENT)], []).c;
   }
-  constructor(client, clientName) {
+  constructor(client, clientName, lifecycleOptions = {}) {
     this.client = client;
     this.clientName = clientName;
+    this.lifecycleOptions = lifecycleOptions;
   }
   async onModuleInit() {
     if (!this.shouldConnectOnInit()) {
       return;
     }
-    await this.client.connect();
+    await withLifecycleTimeout(this.client.connect(), normalizeTimeoutMs(this.lifecycleOptions.connectTimeoutMs), `Redis client ${this.describeClient()} connect timed out after ${String(normalizeTimeoutMs(this.lifecycleOptions.connectTimeoutMs))}ms.`);
   }
   async onApplicationShutdown() {
     const status = this.client.status;
@@ -67,7 +89,7 @@ class RedisLifecycleService {
   }
   async quitWithDisconnectFallback() {
     try {
-      await this.client.quit();
+      await withLifecycleTimeout(this.client.quit(), normalizeTimeoutMs(this.lifecycleOptions.quitTimeoutMs), `Redis client ${this.describeClient()} quit timed out after ${String(normalizeTimeoutMs(this.lifecycleOptions.quitTimeoutMs))}ms.`);
       return;
     } catch (error) {
       this.disconnectIfPossible(this.client.status);
@@ -76,6 +98,9 @@ class RedisLifecycleService {
       }
     }
   }
+  describeClient() {
+    return this.clientName ?? 'default';
+  }
   static {
     _initClass();
   }

package/dist/types.d.ts

@@ -1,13 +1,24 @@
 import type { RedisOptions } from 'ioredis';
 type RedisConnectionOptions = Omit<RedisOptions, 'lazyConnect'>;
+/** Lifecycle timeout controls for Redis connections owned by Fluo. */
+export interface RedisLifecycleOptions {
+    /** Maximum time to wait for bootstrap `connect()` before failing startup. Defaults to `10_000`. */
+    connectTimeoutMs?: number;
+    /** Maximum time to wait for graceful shutdown `quit()` before forcing `disconnect()`. Defaults to `10_000`. */
+    quitTimeoutMs?: number;
+}
 /** Options accepted by the default unnamed Redis registration. */
 export type DefaultRedisModuleOptions = RedisConnectionOptions & {
     /** Whether the default Redis aliases should be visible globally. Defaults to `true`. */
     global?: boolean;
+    /** Timeout controls for lifecycle-owned `connect()` and `quit()` calls. */
+    lifecycle?: RedisLifecycleOptions;
     name?: undefined;
 };
 /** Options accepted by an additional named Redis registration. */
 export type NamedRedisModuleOptions = RedisConnectionOptions & {
+    /** Timeout controls for lifecycle-owned `connect()` and `quit()` calls. */
+    lifecycle?: RedisLifecycleOptions;
     /** Registration name used to derive named raw-client and facade tokens. */
     name: string;
     /** Named Redis registrations remain scoped to their importing module. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,KAAK,sBAAsB,GAAG,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AAEhE,kEAAkE;AAClE,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,GAAG;IAC/D,wFAAwF;IACxF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,GAAG;IAC7D,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC;AAErF,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,KAAK,sBAAsB,GAAG,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AAEhE,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+GAA+G;IAC/G,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,GAAG;IAC/D,wFAAwF;IACxF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,GAAG;IAC7D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC;AAErF,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,CAAC"}

package/package.json

@@ -9,7 +9,7 @@
     "connection",
     "lifecycle"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,12 +36,15 @@
     "dist"
   ],
   "dependencies": {
-    "ioredis": "^5.10.0",
-    "@fluojs/core": "^1.0.0-beta.4",
-    "@fluojs/di": "^1.0.0-beta.6",
-    "@fluojs/runtime": "^1.0.0-beta.11"
+    "@fluojs/core": "^1.0.0-beta.6",
+    "@fluojs/di": "^1.0.0-beta.8",
+    "@fluojs/runtime": "^1.0.0-beta.12"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.10.0"
   },
   "devDependencies": {
+    "ioredis": "^5.10.0",
     "vitest": "^3.2.4"
   },
   "scripts": {