pangolin/server/lib/lock.ts

export class LockManager {
    /**
     * Acquire a distributed lock using Redis SET with NX and PX options
     * @param lockKey - Unique identifier for the lock
     * @param ttlMs - Time to live in milliseconds
     * @returns Promise<boolean> - true if lock acquired, false otherwise
     */
    async acquireLock(
        lockKey: string,
        ttlMs: number = 30000
    ): Promise<boolean> {
        return true;
    }

    /**
     * Release a lock using Lua script to ensure atomicity
     * @param lockKey - Unique identifier for the lock
     */
    async releaseLock(lockKey: string): Promise<void> {}

    /**
     * Force release a lock regardless of owner (use with caution)
     * @param lockKey - Unique identifier for the lock
     */
    async forceReleaseLock(lockKey: string): Promise<void> {}

    /**
     * Check if a lock exists and get its info
     * @param lockKey - Unique identifier for the lock
     * @returns Promise<{exists: boolean, ownedByMe: boolean, ttl: number}>
     */
    async getLockInfo(lockKey: string): Promise<{
        exists: boolean;
        ownedByMe: boolean;
        ttl: number;
        owner?: string;
    }> {
        return { exists: true, ownedByMe: true, ttl: 0 };
    }

    /**
     * Extend the TTL of an existing lock owned by this worker
     * @param lockKey - Unique identifier for the lock
     * @param ttlMs - New TTL in milliseconds
     * @returns Promise<boolean> - true if extended successfully
     */
    async extendLock(lockKey: string, ttlMs: number): Promise<boolean> {
        return true;
    }

    /**
     * Attempt to acquire lock with retries and exponential backoff
     * @param lockKey - Unique identifier for the lock
     * @param ttlMs - Time to live in milliseconds
     * @param maxRetries - Maximum number of retry attempts
     * @param baseDelayMs - Base delay between retries in milliseconds
     * @returns Promise<boolean> - true if lock acquired
     */
    async acquireLockWithRetry(
        lockKey: string,
        ttlMs: number = 30000,
        maxRetries: number = 5,
        baseDelayMs: number = 100
    ): Promise<boolean> {
        return true;
    }

    /**
     * Execute a function while holding a lock
     * @param lockKey - Unique identifier for the lock
     * @param fn - Function to execute while holding the lock
     * @param ttlMs - Lock TTL in milliseconds
     * @returns Promise<T> - Result of the executed function
     */
    async withLock<T>(
        lockKey: string,
        fn: () => Promise<T>,
        ttlMs: number = 30000
    ): Promise<T> {
        const acquired = await this.acquireLock(lockKey, ttlMs);

        if (!acquired) {
            throw new Error(`Failed to acquire lock: ${lockKey}`);
        }

        try {
            return await fn();
        } finally {
            await this.releaseLock(lockKey);
        }
    }

    /**
     * Clean up expired locks - Redis handles this automatically, but this method
     * can be used to get statistics about locks
     * @returns Promise<{activeLocksCount: number, locksOwnedByMe: number}>
     */
    async getLockStatistics(): Promise<{
        activeLocksCount: number;
        locksOwnedByMe: number;
    }> {
        return { activeLocksCount: 0, locksOwnedByMe: 0 };
    }

    /**
     * Close the Redis connection
     */
    async disconnect(): Promise<void> {}
}

export const lockManager = new LockManager();