@nest-omni/core 4.1.3-1 → 4.1.3-10

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

@@ -0,0 +1,253 @@
+"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 ComprehensiveLockCleanupService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComprehensiveLockCleanupService = 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");
+/**
+ * Comprehensive lock cleanup service
+ *
+ * Provides safe and comprehensive lock cleanup mechanism for distributed environments.
+ * Combines instance-based precise cleanup with heartbeat-based dead instance detection.
+ *
+ * **Cleanup Strategy:**
+ * 1. **Immediate Precise Cleanup (0s):**
+ *    - Only cleans locks from the current instance
+ *    - Safe during rolling updates - won't affect other running instances
+ *
+ * 2. **Delayed Conservative Cleanup (60s):**
+ *    - Checks heartbeat of other instances
+ *    - Only cleans locks from dead instances (no heartbeat)
+ *    - Gives enough time for rolling updates to complete
+ *
+ * 3. **Graceful Shutdown Cleanup:**
+ *    - On SIGTERM/SIGINT, immediately cleans own locks
+ *    - Ensures locks are released before process exits
+ *    - Works with PM2 reload and Kubernetes rolling updates
+ *
+ * @example
+ * ```typescript
+ * // In your module
+ * @Module({
+ *   providers: [
+ *     RedisLockService,
+ *     LockHeartbeatService,
+ *     ComprehensiveLockCleanupService,
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+let ComprehensiveLockCleanupService = ComprehensiveLockCleanupService_1 = class ComprehensiveLockCleanupService {
+    constructor(lockService, heartbeatService) {
+        this.lockService = lockService;
+        this.heartbeatService = heartbeatService;
+        this.logger = new common_1.Logger(ComprehensiveLockCleanupService_1.name);
+        /**
+         * Grace period before cleaning other instances' locks (milliseconds)
+         * @default 60000 (60 seconds)
+         */
+        this.gracePeriod = 60000;
+        this.instanceId = this.getInstanceId();
+    }
+    onModuleInit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.log('Starting comprehensive lock cleanup...');
+            // Step 1: Immediate precise cleanup - only clean own instance's locks
+            yield this.cleanupOwnLocks();
+            // Step 2: Delayed cleanup - clean dead instances' locks after grace period
+            setTimeout(() => {
+                this.cleanupDeadInstanceLocks().catch((error) => {
+                    this.logger.error('Failed to cleanup dead instance locks:', error);
+                });
+            }, this.gracePeriod);
+        });
+    }
+    /**
+     * Clean up locks from the current instance
+     * Safe to run immediately - only affects locks created by this instance
+     */
+    cleanupOwnLocks() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.log(`Cleaning locks for this instance: ${this.instanceId}`);
+            try {
+                const allLocks = yield this.lockService.getActiveLocks('*', 'lock');
+                let deletedCount = 0;
+                for (const lock of allLocks) {
+                    if (this.isOwnLock(lock.value)) {
+                        this.logger.warn(`Found stale lock from this instance: ${lock.key}`);
+                        yield this.lockService.forceRelease(lock.key);
+                        deletedCount++;
+                    }
+                }
+                this.logger.log(`Cleaned up ${deletedCount} locks from this instance`);
+            }
+            catch (error) {
+                this.logger.error('Failed to cleanup own locks:', error);
+            }
+        });
+    }
+    /**
+     * Clean up locks from dead instances
+     * Only runs after grace period to avoid cleaning locks during rolling updates
+     */
+    cleanupDeadInstanceLocks() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.log('Cleaning locks from dead instances...');
+            try {
+                const allLocks = yield this.lockService.getActiveLocks('*', 'lock');
+                let deletedCount = 0;
+                for (const lock of allLocks) {
+                    // Skip own instance's locks
+                    if (this.isOwnLock(lock.value)) {
+                        continue;
+                    }
+                    // Extract instance ID from lock value
+                    const instanceId = this.extractInstanceId(lock.value);
+                    if (!instanceId) {
+                        // Cannot determine instance, skip (might be old format)
+                        continue;
+                    }
+                    // Check if instance is alive via heartbeat
+                    const isAlive = yield this.heartbeatService.isInstanceAlive(instanceId);
+                    if (!isAlive) {
+                        this.logger.warn(`Instance ${instanceId} is dead, removing lock: ${lock.key}`);
+                        yield this.lockService.forceRelease(lock.key);
+                        deletedCount++;
+                    }
+                }
+                this.logger.log(`Cleaned up ${deletedCount} locks from dead instances`);
+            }
+            catch (error) {
+                this.logger.error('Failed to cleanup dead instance locks:', error);
+            }
+        });
+    }
+    /**
+     * Check if a lock belongs to the current instance
+     *
+     * @param lockValue - Lock value to check
+     * @returns True if lock belongs to current instance
+     */
+    isOwnLock(lockValue) {
+        if (!lockValue) {
+            return false;
+        }
+        const instanceId = this.extractInstanceId(lockValue);
+        return instanceId === this.instanceId;
+    }
+    /**
+     * Extract instance ID from lock value
+     * Lock value format: instanceId:timestamp:random:pid
+     *
+     * @param lockValue - Lock value
+     * @returns Instance ID or null if cannot be extracted
+     */
+    extractInstanceId(lockValue) {
+        if (!lockValue) {
+            return null;
+        }
+        // New format: instanceId:timestamp:random:pid
+        const parts = lockValue.split(':');
+        return parts.length >= 1 ? parts[0] : null;
+    }
+    /**
+     * Get instance identifier
+     */
+    getInstanceId() {
+        return (process.env.HOSTNAME ||
+            process.env.INSTANCE_ID ||
+            `instance-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`);
+    }
+    /**
+     * Manually trigger cleanup of all stale locks
+     * Use with caution - this will clean both own and dead instance locks
+     */
+    manualCleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.log('Manual cleanup triggered');
+            const ownLocksCount = yield this.cleanupOwnLocksCount();
+            const deadLocksCount = yield this.cleanupDeadInstanceLocksCount();
+            this.logger.log(`Manual cleanup completed: ${ownLocksCount} own locks, ${deadLocksCount} dead locks`);
+            return {
+                ownLocks: ownLocksCount,
+                deadLocks: deadLocksCount,
+            };
+        });
+    }
+    cleanupOwnLocksCount() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const allLocks = yield this.lockService.getActiveLocks('*', 'lock');
+            let deletedCount = 0;
+            for (const lock of allLocks) {
+                if (this.isOwnLock(lock.value)) {
+                    yield this.lockService.forceRelease(lock.key);
+                    deletedCount++;
+                }
+            }
+            return deletedCount;
+        });
+    }
+    cleanupDeadInstanceLocksCount() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const allLocks = yield this.lockService.getActiveLocks('*', 'lock');
+            let deletedCount = 0;
+            for (const lock of allLocks) {
+                if (this.isOwnLock(lock.value)) {
+                    continue;
+                }
+                const instanceId = this.extractInstanceId(lock.value);
+                if (!instanceId) {
+                    continue;
+                }
+                const isAlive = yield this.heartbeatService.isInstanceAlive(instanceId);
+                if (!isAlive) {
+                    yield this.lockService.forceRelease(lock.key);
+                    deletedCount++;
+                }
+            }
+            return deletedCount;
+        });
+    }
+    /**
+     * Cleanup own locks on application shutdown
+     * Called when receiving SIGTERM/SIGINT (graceful shutdown)
+     */
+    onApplicationShutdown(signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.logger.log(`Application shutting down (signal: ${signal}), cleaning own locks...`);
+            try {
+                const deletedCount = yield this.cleanupOwnLocksCount();
+                this.logger.log(`Graceful shutdown cleanup completed: cleaned ${deletedCount} lock(s) from this instance`);
+            }
+            catch (error) {
+                this.logger.error('Failed to cleanup own locks on shutdown:', error);
+            }
+        });
+    }
+};
+exports.ComprehensiveLockCleanupService = ComprehensiveLockCleanupService;
+exports.ComprehensiveLockCleanupService = ComprehensiveLockCleanupService = ComprehensiveLockCleanupService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [redis_lock_service_1.RedisLockService,
+        lock_heartbeat_service_1.LockHeartbeatService])
+], ComprehensiveLockCleanupService);

package/redis-lock/examples/lock-strategy.examples.d.ts

@@ -1,9 +1,25 @@
+/**
+ * Lock Strategy Examples
+ *
+ * This file demonstrates the different lock acquisition strategies available in Redis Lock module.
+ */
 import { RedisLockService } from '../index';
+/**
+ * SKIP strategy - Skip execution if lock cannot be acquired
+ * This is the default behavior and is useful for scheduled tasks where you don't
+ * want to queue up requests if a previous execution is still running.
+ */
 export declare class SkipStrategyExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Example 1: Using decorator with SKIP strategy (default)
+     */
     scheduledTask(): Promise<void>;
+    /**
+     * Example 2: Using service directly with SKIP strategy
+     */
     processWithSkip(): Promise<{
         skipped: boolean;
         success?: undefined;
@@ -11,6 +27,9 @@ export declare class SkipStrategyExample {
         success: boolean;
         skipped?: undefined;
     }>;
+    /**
+     * Example 3: SKIP with retries
+     */
     processWithRetries(): Promise<{
         skipped: boolean;
         success?: undefined;
@@ -20,14 +39,28 @@ export declare class SkipStrategyExample {
     }>;
     private simulateLongRunning;
 }
+/**
+ * THROW strategy - Throw an error if lock cannot be acquired
+ * Use this for critical operations that must have exclusive access.
+ * If the lock cannot be acquired, an exception will be thrown.
+ */
 export declare class ThrowStrategyExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Example 1: Using decorator with THROW strategy
+     */
     criticalOperation(): Promise<void>;
+    /**
+     * Example 2: Using service with error handling
+     */
     processWithThrow(): Promise<{
         success: boolean;
     }>;
+    /**
+     * Example 3: Critical payment processing
+     */
     processPayment(orderId: string, amount: number): Promise<{
         success: boolean;
     }>;
@@ -35,11 +68,22 @@ export declare class ThrowStrategyExample {
     private chargePayment;
     private updateOrderStatus;
 }
+/**
+ * WAIT strategy - Block/wait until lock can be acquired
+ * Use this when you want to queue execution and ensure the operation eventually runs.
+ * The function will wait indefinitely (or until waitTimeout) for the lock to become available.
+ */
 export declare class WaitStrategyExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Example 1: Using decorator with WAIT strategy
+     */
     sequentialTask(): Promise<void>;
+    /**
+     * Example 2: WAIT with timeout
+     */
     processWithWaitTimeout(): Promise<{
         timeout: boolean;
         success?: undefined;
@@ -47,12 +91,24 @@ export declare class WaitStrategyExample {
         success: boolean;
         timeout?: undefined;
     }>;
+    /**
+     * Example 3: Sequential data processing
+     * Perfect for operations that must be processed in order
+     */
     processDataSequentially(userId: string, data: any): Promise<{
         success: boolean;
     }>;
+    /**
+     * Example 4: Queue-like behavior
+     * Multiple requests will queue and execute one by one
+     */
     processQueue(queueName: string, item: any): Promise<{
         success: boolean;
     }>;
+    /**
+     * Example 5: Database migration with WAIT
+     * Ensures migrations run sequentially across all instances
+     */
     runMigration(migrationName: string): Promise<{
         success: boolean;
     }>;
@@ -63,11 +119,44 @@ export declare class WaitStrategyExample {
     private processQueueItem;
     private executeMigration;
 }
+/**
+ * USE SKIP WHEN:
+ * - Running scheduled tasks where you don't want overlapping executions
+ * - Cron jobs that should skip if previous run is still in progress
+ * - Non-critical background tasks
+ * - Operations where it's okay to skip if busy
+ *
+ * USE THROW WHEN:
+ * - Critical operations that require exclusive access
+ * - Financial transactions
+ * - Operations where failure to acquire lock is an error
+ * - When you want to alert/fail fast if resource is busy
+ *
+ * USE WAIT WHEN:
+ * - Operations that must execute eventually
+ * - Sequential processing requirements
+ * - Queue-like behavior needed
+ * - Database migrations
+ * - Operations where order matters
+ * - When you want to ensure the operation runs (with optional timeout)
+ */
+/**
+ * Example: Combining strategies in a single service
+ */
 export declare class CombinedStrategiesExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Background cleanup - SKIP if already running
+     */
     cleanupOldData(): Promise<void>;
+    /**
+     * Payment processing - THROW if cannot get exclusive access
+     */
     processPayment(orderId: string): Promise<void>;
+    /**
+     * Report generation - WAIT to ensure it runs eventually
+     */
     generateReport(reportId: string): Promise<void>;
 }