@nest-omni/core 4.1.3-2 → 4.1.3-20

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

@@ -21,39 +21,96 @@ var RedisLockService_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisLockService = exports.LockStrategy = void 0;
 const common_1 = require("@nestjs/common");
+/**
+ * Lock acquisition strategy
+ */
 var LockStrategy;
 (function (LockStrategy) {
+    /**
+     * Skip execution if lock cannot be acquired immediately
+     * This is the default behavior for backward compatibility
+     */
     LockStrategy["SKIP"] = "SKIP";
+    /**
+     * Throw an error if lock cannot be acquired
+     * Useful for critical operations that must have exclusive access
+     */
     LockStrategy["THROW"] = "THROW";
+    /**
+     * Wait/block until the lock can be acquired
+     * Will retry indefinitely with the specified retry delay
+     */
     LockStrategy["WAIT"] = "WAIT";
 })(LockStrategy || (exports.LockStrategy = LockStrategy = {}));
+/**
+ * Redis-based distributed lock service
+ *
+ * Provides thread-safe, distributed locking mechanism using Redis.
+ * Supports automatic lock expiration, retries, proper lock release,
+ * and automatic lock extension.
+ *
+ * @example
+ * ```typescript
+ * constructor(private lockService: RedisLockService) {}
+ *
+ * async processTask() {
+ *   const result = await this.lockService.acquireLock('task:process', { ttl: 60000 });
+ *
+ *   if (result.acquired) {
+ *     try {
+ *       // Do work
+ *     } finally {
+ *       await this.lockService.releaseLock('task:process', result.lockValue);
+ *     }
+ *   }
+ * }
+ * ```
+ */
 let RedisLockService = RedisLockService_1 = class RedisLockService {
     constructor() {
         this.logger = new common_1.Logger(RedisLockService_1.name);
         this.redis = null;
         this.defaultOptions = {
-            ttl: 300000,
-            retryCount: 0,
-            retryDelay: 100,
+            ttl: 300000, // 5 minutes
+            retryCount: 3, // Increased from 0 to provide reasonable retry attempts
+            retryDelay: 500, // Increased from 100 to reduce retry frequency
             keyPrefix: 'lock',
             throwOnFailure: false,
             strategy: LockStrategy.SKIP,
             waitTimeout: undefined,
-            autoExtend: 0,
+            autoExtend: 0, // No auto-extension by default
+            useExponentialBackoff: true, // Enable exponential backoff by default
+            maxRetryDelay: 30000, // Maximum retry delay of 30 seconds
+            retryJitter: 100, // Add random jitter to avoid synchronized retries
         };
+        // Set global instance when created
         if (!RedisLockService_1.globalInstance) {
             RedisLockService_1.globalInstance = this;
         }
+        // Initialize instance ID
+        this.instanceId = this.getInstanceId();
     }
+    /**
+     * Get the global singleton instance
+     * This allows decorators to access the service without dependency injection
+     */
     static getGlobalInstance() {
         return RedisLockService_1.globalInstance;
     }
+    /**
+     * Get or create the global singleton instance
+     * If no instance exists, it will create one
+     */
     static getOrCreateGlobalInstance() {
         if (!RedisLockService_1.globalInstance) {
             RedisLockService_1.globalInstance = new RedisLockService_1();
         }
         return RedisLockService_1.globalInstance;
     }
+    /**
+     * Set the global singleton instance
+     * Useful for testing or manual setup
+     */
     static setGlobalInstance(instance) {
         RedisLockService_1.globalInstance = instance;
     }
@@ -69,37 +126,93 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
     }
     onModuleDestroy() {
         return __awaiter(this, void 0, void 0, function* () {
+            // We don't manage the Redis connection lifecycle anymore
+            // The injected Redis client is managed by the Redis module
             this.logger.log('RedisLockService destroyed');
         });
     }
+    /**
+     * Set Redis client (required for dependency injection)
+     * This service requires an external Redis client to function
+     */
     setRedisClient(redis) {
         this.redis = redis;
         this.logger.log('Redis client set for RedisLockService');
     }
+    /**
+     * Set default TTL for locks
+     */
     setDefaultTtl(ttl) {
         this.defaultOptions.ttl = ttl;
     }
+    /**
+     * Set default key prefix for locks
+     */
     setDefaultKeyPrefix(prefix) {
         this.defaultOptions.keyPrefix = prefix;
     }
+    /**
+     * Set default retry count for lock acquisition
+     */
     setDefaultRetryCount(count) {
         this.defaultOptions.retryCount = count;
     }
+    /**
+     * Set default retry delay for lock acquisition
+     */
     setDefaultRetryDelay(delay) {
         this.defaultOptions.retryDelay = delay;
     }
+    /**
+     * Acquire a distributed lock
+     *
+     * @param key - Lock key (will be prefixed with 'lock:')
+     * @param options - Lock options
+     * @returns Lock acquisition result
+     */
     acquireLock(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, options = {}) {
+            var _a, _b, _c, _d, _e;
             const redis = yield this.getRedis();
             const opts = Object.assign(Object.assign({}, this.defaultOptions), options);
+            // Validate TTL
+            if (opts.ttl !== undefined) {
+                if (typeof opts.ttl !== 'number' || opts.ttl <= 0) {
+                    this.logger.warn(`Invalid TTL value: ${opts.ttl}. TTL must be a positive number. Using default TTL: ${this.defaultOptions.ttl}ms`);
+                    opts.ttl = this.defaultOptions.ttl;
+                }
+            }
+            // Validate waitTimeout
+            if (opts.waitTimeout !== undefined) {
+                if (typeof opts.waitTimeout !== 'number' || opts.waitTimeout <= 0) {
+                    this.logger.warn(`Invalid waitTimeout value: ${opts.waitTimeout}. waitTimeout must be a positive number. Ignoring waitTimeout.`);
+                    opts.waitTimeout = undefined;
+                }
+            }
+            // Validate retryCount
+            if (opts.retryCount !== undefined) {
+                if (typeof opts.retryCount !== 'number' || opts.retryCount < 0) {
+                    this.logger.warn(`Invalid retryCount value: ${opts.retryCount}. retryCount must be a non-negative number. Using default: ${this.defaultOptions.retryCount}`);
+                    opts.retryCount = this.defaultOptions.retryCount;
+                }
+            }
+            // Validate retryDelay
+            if (opts.retryDelay !== undefined) {
+                if (typeof opts.retryDelay !== 'number' || opts.retryDelay <= 0) {
+                    this.logger.warn(`Invalid retryDelay value: ${opts.retryDelay}. retryDelay must be a positive number. Using default: ${this.defaultOptions.retryDelay}ms`);
+                    opts.retryDelay = this.defaultOptions.retryDelay;
+                }
+            }
+            // Handle backward compatibility: if throwOnFailure is true, use THROW strategy
             if (opts.throwOnFailure && !options.strategy) {
                 opts.strategy = LockStrategy.THROW;
             }
             const lockKey = this.buildLockKey(key, opts.keyPrefix);
             const lockValue = this.generateLockValue();
+            // Determine max attempts based on strategy
             let maxAttempts;
             if (opts.strategy === LockStrategy.WAIT) {
-                maxAttempts = Number.MAX_SAFE_INTEGER;
+                maxAttempts = Number.MAX_SAFE_INTEGER; // Infinite retries for WAIT strategy
             }
             else {
                 maxAttempts = opts.retryCount + 1;
@@ -107,6 +220,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             let attempts = 0;
             const startTime = Date.now();
             while (attempts < maxAttempts) {
+                // Check timeout for WAIT strategy
                 if (opts.strategy === LockStrategy.WAIT && opts.waitTimeout) {
                     const elapsed = Date.now() - startTime;
                     if (elapsed >= opts.waitTimeout) {
@@ -116,9 +230,11 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                     }
                 }
                 try {
+                    // Use SET with NX (Not eXists) and PX (expiration in milliseconds)
                     const result = yield redis.set(lockKey, lockValue, 'PX', opts.ttl, 'NX');
                     if (result === 'OK') {
                         this.logger.debug(`Lock acquired: ${lockKey} (value: ${lockValue}, ttl: ${opts.ttl}ms, attempts: ${attempts + 1})`);
+                        // Set up auto-extension if enabled
                         let autoExtendTimer;
                         if (opts.autoExtend && opts.autoExtend > 0) {
                             autoExtendTimer = setInterval(() => __awaiter(this, void 0, void 0, function* () {
@@ -132,7 +248,9 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                         }
                         return { acquired: true, lockValue, autoExtendTimer };
                     }
+                    // Lock acquisition failed
                     attempts++;
+                    // For WAIT strategy, log less frequently to avoid spam
                     if (opts.strategy === LockStrategy.WAIT) {
                         if (attempts === 1 || attempts % 10 === 0) {
                             this.logger.debug(`Waiting for lock ${lockKey}... (attempt ${attempts})`);
@@ -141,19 +259,47 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                     else if (attempts < maxAttempts) {
                         this.logger.debug(`Lock acquisition failed for ${lockKey}, retrying... (${attempts}/${opts.retryCount})`);
                     }
+                    // Wait before next attempt (except for last attempt)
                     if (attempts < maxAttempts) {
-                        yield this.sleep(opts.retryDelay);
+                        // Add random jitter to avoid synchronized retries
+                        const jitter = opts.retryJitter ? Math.random() * opts.retryJitter : 0;
+                        const totalDelay = opts.retryDelay + jitter;
+                        yield this.sleep(totalDelay);
                     }
                 }
                 catch (error) {
-                    const errorMessage = `Error acquiring lock for ${lockKey}: ${error.message}`;
-                    this.logger.error(errorMessage, error.stack);
-                    if (opts.strategy === LockStrategy.THROW) {
-                        throw new Error(errorMessage);
+                    // Enhanced error classification and handling
+                    if (((_a = error.message) === null || _a === void 0 ? void 0 : _a.includes('ECONNREFUSED')) ||
+                        ((_b = error.message) === null || _b === void 0 ? void 0 : _b.includes('ECONNRESET')) ||
+                        error.code === 'ECONNREFUSED') {
+                        // Connection error, will retry - log at debug level
+                        this.logger.debug(`Redis connection error, will retry: ${error.message}`);
+                    }
+                    else if (((_c = error.message) === null || _c === void 0 ? void 0 : _c.includes('READONLY')) ||
+                        ((_d = error.message) === null || _d === void 0 ? void 0 : _d.includes('LOADING')) ||
+                        ((_e = error.message) === null || _e === void 0 ? void 0 : _e.includes('MASTERDOWN'))) {
+                        // Redis server error, log at warn level
+                        this.logger.warn(`Redis server error: ${error.message}`);
+                    }
+                    else {
+                        // Other errors, log at error level
+                        const errorMessage = `Error acquiring lock for ${lockKey}: ${error.message}`;
+                        this.logger.error(errorMessage, error.stack);
+                        if (opts.strategy === LockStrategy.THROW) {
+                            throw new Error(errorMessage);
+                        }
+                        return { acquired: false, error: errorMessage };
+                    }
+                    // For retryable errors, continue with retry logic
+                    attempts++;
+                    if (attempts < maxAttempts) {
+                        const jitter = opts.retryJitter ? Math.random() * opts.retryJitter : 0;
+                        const totalDelay = opts.retryDelay + jitter;
+                        yield this.sleep(totalDelay);
                     }
-                    return { acquired: false, error: errorMessage };
                 }
             }
+            // Max attempts reached
             const failureMessage = `Failed to acquire lock for ${lockKey} after ${attempts} attempts`;
             this.logger.warn(failureMessage);
             if (opts.strategy === LockStrategy.THROW) {
@@ -162,11 +308,23 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             return { acquired: false, error: failureMessage };
         });
     }
+    /**
+     * Release a distributed lock
+     *
+     * Uses Lua script to ensure atomic check-and-delete operation
+     * Only releases the lock if the value matches (prevents releasing someone else's lock)
+     *
+     * @param key - Lock key
+     * @param lockValue - Lock value obtained during acquisition
+     * @param keyPrefix - Key prefix (must match acquisition)
+     * @returns True if lock was released, false otherwise
+     */
     releaseLock(key_1, lockValue_1) {
         return __awaiter(this, arguments, void 0, function* (key, lockValue, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
             const lockKey = this.buildLockKey(key, keyPrefix);
             try {
+                // Lua script to atomically check and delete the lock
                 const script = `
         if redis.call("get", KEYS[1]) == ARGV[1] then
           return redis.call("del", KEYS[1])
@@ -190,11 +348,21 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Extend the expiration time of an existing lock
+     *
+     * @param key - Lock key
+     * @param lockValue - Lock value obtained during acquisition
+     * @param ttl - New TTL in milliseconds
+     * @param keyPrefix - Key prefix (must match acquisition)
+     * @returns True if lock was extended, false otherwise
+     */
     extendLock(key_1, lockValue_1, ttl_1) {
         return __awaiter(this, arguments, void 0, function* (key, lockValue, ttl, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
             const lockKey = this.buildLockKey(key, keyPrefix);
             try {
+                // Lua script to atomically check value and extend TTL
                 const script = `
         if redis.call("get", KEYS[1]) == ARGV[1] then
           return redis.call("pexpire", KEYS[1], ARGV[2])
@@ -218,6 +386,13 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Check if a lock exists
+     *
+     * @param key - Lock key
+     * @param keyPrefix - Key prefix
+     * @returns True if lock exists, false otherwise
+     */
     isLocked(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -232,6 +407,14 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Execute a function with automatic lock acquisition and release
+     *
+     * @param key - Lock key
+     * @param fn - Function to execute while holding the lock
+     * @param options - Lock options
+     * @returns Result of the function execution, or null if lock couldn't be acquired
+     */
     withLock(key_1, fn_1) {
         return __awaiter(this, arguments, void 0, function* (key, fn, options = {}) {
             const lockResult = yield this.acquireLock(key, options);
@@ -247,6 +430,7 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
                 throw error;
             }
             finally {
+                // Clear auto-extension timer if it exists
                 if (lockResult.autoExtendTimer) {
                     clearInterval(lockResult.autoExtendTimer);
                 }
@@ -254,6 +438,13 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Get lock information from Redis
+     *
+     * @param key - Lock key
+     * @param keyPrefix - Key prefix
+     * @returns Lock information including TTL and value
+     */
     getLockInfo(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -274,6 +465,13 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Force release a lock (use with caution)
+     *
+     * @param key - Lock key
+     * @param keyPrefix - Key prefix
+     * @returns True if lock was released, false otherwise
+     */
     forceRelease(key_1) {
         return __awaiter(this, arguments, void 0, function* (key, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
@@ -295,19 +493,54 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Clean up locks by pattern
+     * Useful for cleaning up locks after process restart or for specific services
+     *
+     * 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
+     *
+     * @example
+     * ```typescript
+     * // Clean up all locks for MyService
+     * await lockService.cleanupLocksByPattern('MyService:*');
+     *
+     * // Clean up all migration locks
+     * await lockService.cleanupLocksByPattern('*:migration:*');
+     * ```
+     */
     cleanupLocksByPattern(pattern_1) {
         return __awaiter(this, arguments, void 0, function* (pattern, keyPrefix = 'lock') {
             const redis = yield this.getRedis();
             const searchPattern = `${keyPrefix}:${pattern}`;
             try {
-                const keys = yield redis.keys(searchPattern);
-                if (keys.length === 0) {
+                let cursor = '0';
+                const allKeys = [];
+                // Use SCAN to iterate through keys without blocking Redis
+                do {
+                    const [nextCursor, keys] = yield redis.scan(cursor, 'MATCH', searchPattern, 'COUNT', 100);
+                    cursor = nextCursor;
+                    allKeys.push(...keys);
+                } while (cursor !== '0');
+                if (allKeys.length === 0) {
                     this.logger.debug(`No locks found matching pattern: ${searchPattern}`);
                     return 0;
                 }
-                const result = yield redis.del(...keys);
-                this.logger.log(`Cleaned up ${result} lock(s) matching pattern: ${searchPattern}`);
-                return result;
+                // Delete keys in batches to avoid blocking Redis
+                let deletedCount = 0;
+                const batchSize = 100;
+                for (let i = 0; i < allKeys.length; i += batchSize) {
+                    const batch = allKeys.slice(i, i + batchSize);
+                    const result = yield redis.del(...batch);
+                    deletedCount += result;
+                }
+                this.logger.log(`Cleaned up ${deletedCount} lock(s) matching pattern: ${searchPattern}`);
+                return deletedCount;
             }
             catch (error) {
                 this.logger.error(`Error cleaning up locks by pattern ${searchPattern}: ${error.message}`, error.stack);
@@ -315,6 +548,28 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Clean up locks on startup
+     * This method is useful for cleaning up stale locks from previous process instances
+     *
+     * WARNING: Only use this if you're sure the locks are from previous process instances!
+     *
+     * @param patterns - Array of lock patterns to clean up
+     * @param keyPrefix - Key prefix (default: 'lock')
+     * @returns Total number of locks deleted
+     *
+     * @example
+     * ```typescript
+     * // In your module's onModuleInit
+     * async onModuleInit() {
+     *   // Clean up locks from this service that might be left from previous restart
+     *   await this.lockService.cleanupOnStartup([
+     *     'MyService:*',
+     *     'AnotherService:*'
+     *   ]);
+     * }
+     * ```
+     */
     cleanupOnStartup(patterns_1) {
         return __awaiter(this, arguments, void 0, function* (patterns, keyPrefix = 'lock') {
             this.logger.log(`Starting lock cleanup for ${patterns.length} pattern(s) on startup...`);
@@ -327,10 +582,17 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             return totalDeleted;
         });
     }
+    /**
+     * Health check for Redis connection
+     * Returns information about Redis connectivity and lock service status
+     *
+     * @returns Health check result
+     */
     healthCheck() {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const redis = yield this.getRedis();
+                // Try to ping Redis
                 const pong = yield redis.ping();
                 if (pong === 'PONG') {
                     return {
@@ -356,20 +618,38 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * 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
+     */
     getActiveLocks() {
         return __awaiter(this, arguments, void 0, function* (pattern = '*', keyPrefix = 'lock') {
             const redis = yield this.getRedis();
             const searchPattern = `${keyPrefix}:${pattern}`;
             try {
-                const keys = yield redis.keys(searchPattern);
-                if (keys.length === 0) {
+                let cursor = '0';
+                const allKeys = [];
+                // Use SCAN to iterate through keys without blocking Redis
+                do {
+                    const [nextCursor, keys] = yield redis.scan(cursor, 'MATCH', searchPattern, 'COUNT', 100);
+                    cursor = nextCursor;
+                    allKeys.push(...keys);
+                } while (cursor !== '0');
+                if (allKeys.length === 0) {
                     return [];
                 }
-                const locks = yield Promise.all(keys.map((key) => __awaiter(this, void 0, void 0, function* () {
+                const locks = yield Promise.all(allKeys.map((key) => __awaiter(this, void 0, void 0, function* () {
                     const [value, ttl] = yield Promise.all([
                         redis.get(key),
                         redis.pttl(key),
                     ]);
+                    // Remove the key prefix for cleaner output
                     const cleanKey = key.startsWith(`${keyPrefix}:`)
                         ? key.substring(`${keyPrefix}:`.length)
                         : key;
@@ -387,6 +667,10 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             }
         });
     }
+    /**
+     * Get Redis connection
+     * Requires external Redis client to be set
+     */
     getRedis() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.redis) {
@@ -395,12 +679,51 @@ let RedisLockService = RedisLockService_1 = class RedisLockService {
             return this.redis;
         });
     }
+    /**
+     * Generate a unique lock value
+     * Format: instanceId:timestamp:random:pid
+     *
+     * @returns Unique lock identifier
+     */
     generateLockValue() {
-        return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}-${process.pid}`;
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 15);
+        const pid = process.pid;
+        return `${this.instanceId}:${timestamp}:${random}:${pid}`;
+    }
+    /**
+     * Get instance identifier
+     * Used to distinguish different process instances in distributed environments
+     *
+     * @returns Instance identifier
+     */
+    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)}`;
     }
+    /**
+     * Build the full Redis key for a lock
+     *
+     * @param key - Lock key
+     * @param prefix - Key prefix
+     * @returns Full Redis key
+     */
     buildLockKey(key, prefix = 'lock') {
         return `${prefix}:${key}`;
     }
+    /**
+     * Sleep for a specified duration
+     *
+     * @param ms - Milliseconds to sleep
+     */
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }

package/setup/bootstrap.setup.d.ts

@@ -1,2 +1,3 @@
+import '../common/boilerplate.polyfill';
 import type { NestExpressApplication } from '@nestjs/platform-express';
 export declare function bootstrapSetup(AppModule: any, SetupSwagger: any): Promise<NestExpressApplication<import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>>>;