@nest-omni/core 4.1.3-3 → 4.1.3-30

package/redis-lock/lock-heartbeat.service.js

@@ -0,0 +1,232 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var LockHeartbeatService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LockHeartbeatService = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Lock heartbeat service
+ *
+ * Provides heartbeat mechanism for distributed lock instances.
+ * Each instance sends periodic heartbeats to Redis to indicate it's alive.
+ * Dead instances can be detected by checking if their heartbeat has expired.
+ *
+ * @example
+ * ```typescript
+ * constructor(private heartbeatService: LockHeartbeatService) {}
+ *
+ * async isInstanceAlive(instanceId: string): Promise<boolean> {
+ *   return this.heartbeatService.isInstanceAlive(instanceId);
+ * }
+ * ```
+ */
+let LockHeartbeatService = LockHeartbeatService_1 = class LockHeartbeatService {
+    constructor() {
+        this.logger = new common_1.Logger(LockHeartbeatService_1.name);
+        this.redis = null;
+        this.heartbeatTimer = null;
+        /**
+         * Heartbeat interval in milliseconds
+         * @default 5000 (5 seconds) - reduced for faster failure detection
+         */
+        this.heartbeatInterval = 5000;
+        /**
+         * Heartbeat TTL in seconds (3x interval for safety)
+         * @default 15 (15 seconds) - adjusted to match new interval
+         */
+        this.heartbeatTtl = 15;
+        this.instanceId = this.getInstanceId();
+    }
+    onModuleInit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                this.logger.warn('LockHeartbeatService initialized but no Redis client provided. Heartbeat functionality will not work.');
+                return;
+            }
+            // Send initial heartbeat
+            yield this.sendHeartbeat();
+            // Start periodic heartbeat
+            this.heartbeatTimer = setInterval(() => {
+                this.sendHeartbeat().catch((error) => {
+                    this.logger.error('Failed to send heartbeat:', error);
+                });
+            }, this.heartbeatInterval);
+            this.logger.log(`Heartbeat started for instance: ${this.instanceId}`);
+        });
+    }
+    onModuleDestroy() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Stop heartbeat timer
+            if (this.heartbeatTimer) {
+                clearInterval(this.heartbeatTimer);
+                this.heartbeatTimer = null;
+            }
+            // Remove heartbeat record
+            yield this.removeHeartbeat();
+            this.logger.log('Heartbeat stopped');
+        });
+    }
+    /**
+     * Set Redis client (required for dependency injection)
+     */
+    setRedisClient(redis) {
+        this.redis = redis;
+        this.logger.log('Redis client set for LockHeartbeatService');
+    }
+    /**
+     * Send heartbeat to Redis
+     * Stores instance information with TTL
+     */
+    sendHeartbeat() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return;
+            }
+            const key = `heartbeat:${this.instanceId}`;
+            const data = {
+                instanceId: this.instanceId,
+                timestamp: Date.now(),
+                pid: process.pid,
+            };
+            try {
+                // Set heartbeat with TTL (3x interval for safety)
+                yield this.redis.setex(key, this.heartbeatTtl, JSON.stringify(data));
+            }
+            catch (error) {
+                this.logger.error('Error sending heartbeat:', error);
+            }
+        });
+    }
+    /**
+     * Remove heartbeat record from Redis
+     */
+    removeHeartbeat() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return;
+            }
+            const key = `heartbeat:${this.instanceId}`;
+            try {
+                yield this.redis.del(key);
+            }
+            catch (error) {
+                this.logger.error('Error removing heartbeat:', error);
+            }
+        });
+    }
+    /**
+     * Check if an instance is alive by checking its heartbeat
+     *
+     * @param instanceId - Instance identifier to check
+     * @returns True if instance is alive (heartbeat exists), false otherwise
+     */
+    isInstanceAlive(instanceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                this.logger.warn('Redis client not available, cannot check instance status');
+                return false;
+            }
+            const key = `heartbeat:${instanceId}`;
+            try {
+                const exists = yield this.redis.exists(key);
+                return exists === 1;
+            }
+            catch (error) {
+                this.logger.error(`Error checking instance ${instanceId} status:`, error);
+                return false;
+            }
+        });
+    }
+    /**
+     * Get heartbeat information for an instance
+     *
+     * @param instanceId - Instance identifier
+     * @returns Heartbeat data or null if not found
+     */
+    getHeartbeatInfo(instanceId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return null;
+            }
+            const key = `heartbeat:${instanceId}`;
+            try {
+                const data = yield this.redis.get(key);
+                if (!data) {
+                    return null;
+                }
+                return JSON.parse(data);
+            }
+            catch (error) {
+                this.logger.error(`Error getting heartbeat info for ${instanceId}:`, error);
+                return null;
+            }
+        });
+    }
+    /**
+     * Get all active instances (with heartbeat)
+     *
+     * **Note**: Uses SCAN command to avoid blocking Redis in production.
+     *
+     * @returns Array of instance IDs that are currently alive
+     */
+    getActiveInstances() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.redis) {
+                return [];
+            }
+            try {
+                let cursor = '0';
+                const pattern = 'heartbeat:*';
+                const allKeys = [];
+                // Use SCAN to iterate through keys without blocking Redis
+                do {
+                    const [nextCursor, keys] = yield this.redis.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+                    cursor = nextCursor;
+                    allKeys.push(...keys);
+                } while (cursor !== '0');
+                return allKeys.map((key) => key.replace('heartbeat:', ''));
+            }
+            catch (error) {
+                this.logger.error('Error getting active instances:', error);
+                return [];
+            }
+        });
+    }
+    /**
+     * Get current instance ID
+     */
+    getInstanceId() {
+        // 1. Kubernetes Pod name
+        if (process.env.HOSTNAME) {
+            return process.env.HOSTNAME;
+        }
+        // 2. Custom instance ID
+        if (process.env.INSTANCE_ID) {
+            return process.env.INSTANCE_ID;
+        }
+        // 3. Generate unique ID
+        return `instance-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    }
+};
+exports.LockHeartbeatService = LockHeartbeatService;
+exports.LockHeartbeatService = LockHeartbeatService = LockHeartbeatService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [])
+], LockHeartbeatService);

package/redis-lock/redis-lock.module.d.ts

@@ -34,6 +34,12 @@ export interface RedisLockModuleOptions {
      * Default retry delay in milliseconds
      */
     defaultRetryDelay?: number;
+    /**
+     * Enable automatic lock cleanup on startup
+     * This includes heartbeat mechanism and comprehensive cleanup
+     * @default true
+     */
+    enableCleanup?: boolean;
 }
 /**
  * Redis Lock module with distributed locking support

package/redis-lock/redis-lock.module.js

@@ -13,6 +13,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisLockModule = exports.REDIS_LOCK_SERVICE = void 0;
 const common_1 = require("@nestjs/common");
 const redis_lock_service_1 = require("./redis-lock.service");
+const lock_heartbeat_service_1 = require("./lock-heartbeat.service");
+const comprehensive_lock_cleanup_service_1 = require("./comprehensive-lock-cleanup.service");
 const redis_lock_decorator_1 = require("./redis-lock.decorator");
 /**
  * Injection token for Redis Lock Service
@@ -52,44 +54,68 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
      * Register Redis Lock module with options
      */
     static forRoot(options) {
-        const { isGlobal = true, redisClient, defaultTtl, defaultKeyPrefix, defaultRetryCount, defaultRetryDelay, } = options;
-        return {
-            module: RedisLockModule_1,
-            global: isGlobal,
-            providers: [
-                // Redis client provider
-                {
-                    provide: 'REDIS_LOCK_CLIENT',
-                    useValue: redisClient,
+        const { isGlobal = true, redisClient, defaultTtl, defaultKeyPrefix, defaultRetryCount, defaultRetryDelay, enableCleanup = true, } = options;
+        const providers = [
+            // Redis client provider
+            {
+                provide: 'REDIS_LOCK_CLIENT',
+                useValue: redisClient,
+            },
+            // Redis Lock Service
+            {
+                provide: exports.REDIS_LOCK_SERVICE,
+                useFactory: () => {
+                    const service = new redis_lock_service_1.RedisLockService();
+                    service.setRedisClient(redisClient);
+                    if (defaultTtl) {
+                        service.setDefaultTtl(defaultTtl);
+                    }
+                    if (defaultKeyPrefix) {
+                        service.setDefaultKeyPrefix(defaultKeyPrefix);
+                    }
+                    if (defaultRetryCount !== undefined) {
+                        service.setDefaultRetryCount(defaultRetryCount);
+                    }
+                    if (defaultRetryDelay !== undefined) {
+                        service.setDefaultRetryDelay(defaultRetryDelay);
+                    }
+                    return service;
                 },
-                // Redis Lock Service
-                {
-                    provide: exports.REDIS_LOCK_SERVICE,
-                    useFactory: () => {
-                        const service = new redis_lock_service_1.RedisLockService();
-                        service.setRedisClient(redisClient);
-                        if (defaultTtl) {
-                            service.setDefaultTtl(defaultTtl);
-                        }
-                        if (defaultKeyPrefix) {
-                            service.setDefaultKeyPrefix(defaultKeyPrefix);
-                        }
-                        if (defaultRetryCount !== undefined) {
-                            service.setDefaultRetryCount(defaultRetryCount);
-                        }
-                        if (defaultRetryDelay !== undefined) {
-                            service.setDefaultRetryDelay(defaultRetryDelay);
-                        }
-                        return service;
-                    },
+            },
+            // Also provide the service class itself for direct injection
+            {
+                provide: redis_lock_service_1.RedisLockService,
+                useExisting: exports.REDIS_LOCK_SERVICE,
+            },
+        ];
+        const exportsList = [exports.REDIS_LOCK_SERVICE, redis_lock_service_1.RedisLockService];
+        // Add cleanup services if enabled
+        if (enableCleanup) {
+            providers.push(
+            // Heartbeat Service
+            {
+                provide: lock_heartbeat_service_1.LockHeartbeatService,
+                useFactory: () => {
+                    const service = new lock_heartbeat_service_1.LockHeartbeatService();
+                    service.setRedisClient(redisClient);
+                    return service;
                 },
-                // Also provide the service class itself for direct injection
-                {
-                    provide: redis_lock_service_1.RedisLockService,
-                    useExisting: exports.REDIS_LOCK_SERVICE,
+            }, 
+            // Comprehensive Cleanup Service
+            {
+                provide: comprehensive_lock_cleanup_service_1.ComprehensiveLockCleanupService,
+                useFactory: (lockService, heartbeatService) => {
+                    return new comprehensive_lock_cleanup_service_1.ComprehensiveLockCleanupService(lockService, heartbeatService);
                 },
-            ],
-            exports: [exports.REDIS_LOCK_SERVICE, redis_lock_service_1.RedisLockService],
+                inject: [redis_lock_service_1.RedisLockService, lock_heartbeat_service_1.LockHeartbeatService],
+            });
+            exportsList.push(lock_heartbeat_service_1.LockHeartbeatService, comprehensive_lock_cleanup_service_1.ComprehensiveLockCleanupService);
+        }
+        return {
+            module: RedisLockModule_1,
+            global: isGlobal,
+            providers,
+            exports: exportsList,
         };
     }
     /**
@@ -97,52 +123,85 @@ let RedisLockModule = RedisLockModule_1 = class RedisLockModule {
      */
     static forRootAsync(options) {
         var _a;
+        const providers = [
+            // Async options provider
+            {
+                provide: 'REDIS_LOCK_MODULE_OPTIONS',
+                useFactory: options.useFactory,
+                inject: options.inject || [],
+            },
+            // Redis client provider
+            {
+                provide: 'REDIS_LOCK_CLIENT',
+                useFactory: (moduleOptions) => moduleOptions.redisClient,
+                inject: ['REDIS_LOCK_MODULE_OPTIONS'],
+            },
+            // Redis Lock Service
+            {
+                provide: exports.REDIS_LOCK_SERVICE,
+                useFactory: (moduleOptions) => {
+                    const service = new redis_lock_service_1.RedisLockService();
+                    service.setRedisClient(moduleOptions.redisClient);
+                    if (moduleOptions.defaultTtl) {
+                        service.setDefaultTtl(moduleOptions.defaultTtl);
+                    }
+                    if (moduleOptions.defaultKeyPrefix) {
+                        service.setDefaultKeyPrefix(moduleOptions.defaultKeyPrefix);
+                    }
+                    if (moduleOptions.defaultRetryCount !== undefined) {
+                        service.setDefaultRetryCount(moduleOptions.defaultRetryCount);
+                    }
+                    if (moduleOptions.defaultRetryDelay !== undefined) {
+                        service.setDefaultRetryDelay(moduleOptions.defaultRetryDelay);
+                    }
+                    return service;
+                },
+                inject: ['REDIS_LOCK_MODULE_OPTIONS'],
+            },
+            // Also provide the service class itself for direct injection
+            {
+                provide: redis_lock_service_1.RedisLockService,
+                useExisting: exports.REDIS_LOCK_SERVICE,
+            },
+            // Heartbeat Service
+            {
+                provide: lock_heartbeat_service_1.LockHeartbeatService,
+                useFactory: (moduleOptions) => {
+                    // Only create if cleanup is enabled
+                    if (moduleOptions.enableCleanup === false) {
+                        return null;
+                    }
+                    const service = new lock_heartbeat_service_1.LockHeartbeatService();
+                    service.setRedisClient(moduleOptions.redisClient);
+                    return service;
+                },
+                inject: ['REDIS_LOCK_MODULE_OPTIONS'],
+            },
+            // Comprehensive Cleanup Service
+            {
+                provide: comprehensive_lock_cleanup_service_1.ComprehensiveLockCleanupService,
+                useFactory: (moduleOptions, lockService, heartbeatService) => {
+                    // Only create if cleanup is enabled
+                    if (moduleOptions.enableCleanup === false) {
+                        return null;
+                    }
+                    return new comprehensive_lock_cleanup_service_1.ComprehensiveLockCleanupService(lockService, heartbeatService);
+                },
+                inject: ['REDIS_LOCK_MODULE_OPTIONS', redis_lock_service_1.RedisLockService, lock_heartbeat_service_1.LockHeartbeatService],
+            },
+        ];
+        const exportsList = [
+            exports.REDIS_LOCK_SERVICE,
+            redis_lock_service_1.RedisLockService,
+            lock_heartbeat_service_1.LockHeartbeatService,
+            comprehensive_lock_cleanup_service_1.ComprehensiveLockCleanupService,
+        ];
         return {
             module: RedisLockModule_1,
             global: (_a = options.isGlobal) !== null && _a !== void 0 ? _a : true,
             imports: options.imports || [],
-            providers: [
-                // Async options provider
-                {
-                    provide: 'REDIS_LOCK_MODULE_OPTIONS',
-                    useFactory: options.useFactory,
-                    inject: options.inject || [],
-                },
-                // Redis client provider
-                {
-                    provide: 'REDIS_LOCK_CLIENT',
-                    useFactory: (moduleOptions) => moduleOptions.redisClient,
-                    inject: ['REDIS_LOCK_MODULE_OPTIONS'],
-                },
-                // Redis Lock Service
-                {
-                    provide: exports.REDIS_LOCK_SERVICE,
-                    useFactory: (moduleOptions) => {
-                        const service = new redis_lock_service_1.RedisLockService();
-                        service.setRedisClient(moduleOptions.redisClient);
-                        if (moduleOptions.defaultTtl) {
-                            service.setDefaultTtl(moduleOptions.defaultTtl);
-                        }
-                        if (moduleOptions.defaultKeyPrefix) {
-                            service.setDefaultKeyPrefix(moduleOptions.defaultKeyPrefix);
-                        }
-                        if (moduleOptions.defaultRetryCount !== undefined) {
-                            service.setDefaultRetryCount(moduleOptions.defaultRetryCount);
-                        }
-                        if (moduleOptions.defaultRetryDelay !== undefined) {
-                            service.setDefaultRetryDelay(moduleOptions.defaultRetryDelay);
-                        }
-                        return service;
-                    },
-                    inject: ['REDIS_LOCK_MODULE_OPTIONS'],
-                },
-                // Also provide the service class itself for direct injection
-                {
-                    provide: redis_lock_service_1.RedisLockService,
-                    useExisting: exports.REDIS_LOCK_SERVICE,
-                },
-            ],
-            exports: [exports.REDIS_LOCK_SERVICE, redis_lock_service_1.RedisLockService],
+            providers,
+            exports: exportsList,
         };
     }
     onModuleInit() {

package/redis-lock/redis-lock.service.d.ts

@@ -69,6 +69,24 @@ export interface LockOptions {
      * @default 0 (no automatic extension)
      */
     autoExtend?: number;
+    /**
+     * Whether to use exponential backoff for retry attempts
+     * If true, retry delay will increase exponentially: retryDelay * 2^(attempt-1)
+     * @default false
+     */
+    useExponentialBackoff?: boolean;
+    /**
+     * Maximum retry delay in milliseconds when using exponential backoff
+     * Ensures retry delay doesn't grow indefinitely
+     * @default 60000 (60 seconds)
+     */
+    maxRetryDelay?: number;
+    /**
+     * Random jitter to add to retry delay in milliseconds
+     * Helps prevent synchronized retries across multiple instances
+     * @default 0 (no jitter)
+     */
+    retryJitter?: number;
 }
 export interface LockResult {
     /**
@@ -116,6 +134,7 @@ export declare class RedisLockService implements OnModuleInit {
     private static globalInstance;
     private readonly logger;
     private redis;
+    private instanceId;
     private readonly defaultOptions;
     constructor();
     /**
@@ -228,6 +247,8 @@ export declare class RedisLockService implements OnModuleInit {
      *
      * WARNING: Use with caution in production! This will forcefully delete locks.
      *
+     * **Note**: Uses SCAN command to avoid blocking Redis in production.
+     *
      * @param pattern - Lock pattern (e.g., 'MyService:*' or '*:migration:*')
      * @param keyPrefix - Key prefix (default: 'lock')
      * @returns Number of locks deleted
@@ -280,6 +301,8 @@ export declare class RedisLockService implements OnModuleInit {
      * Get all active locks with optional pattern filtering
      * Useful for monitoring and debugging
      *
+     * **Note**: Uses SCAN command to avoid blocking Redis in production.
+     *
      * @param pattern - Optional pattern to filter locks (e.g., 'MyService:*')
      * @param keyPrefix - Key prefix (default: 'lock')
      * @returns Array of active lock information
@@ -296,10 +319,18 @@ export declare class RedisLockService implements OnModuleInit {
     private getRedis;
     /**
      * Generate a unique lock value
+     * Format: instanceId:timestamp:random:pid
      *
      * @returns Unique lock identifier
      */
     private generateLockValue;
+    /**
+     * Get instance identifier
+     * Used to distinguish different process instances in distributed environments
+     *
+     * @returns Instance identifier
+     */
+    private getInstanceId;
     /**
      * Build the full Redis key for a lock
      *