Distributed Locks

Coordinate processes across your cluster using TopGun’s distributed locking mechanism with built-in fencing tokens.

In a distributed system, you often need to ensure that only one client or process performs a specific action at a time (e.g., processing a payment, updating a shared resource). TopGun provides a simple API to acquire and release locks, backed by the server cluster.

Using Locks

The ttl (Time-To-Live) ensures the lock is automatically released if the client crashes.

import { TopGunClient } from '@topgunbuild/client';

// ... initialize client ...

async function processJob() {
  const lock = client.getLock('process-queue-1');

  // Acquire lock with 5 second TTL (auto-release if client crashes)
  const acquired = await lock.lock(5000);

  if (acquired) {
    try {
      console.log('Lock acquired, processing job...');
      // Perform critical section work here
      await doHeavyWork();
    } finally {
      // Always release the lock when done
      await lock.unlock();
      console.log('Lock released');
    }
  } else {
    console.log('Could not acquire lock, another worker is busy.');
  }
}

Fencing Tokens

When a lock is granted, the server returns a monotonically increasing number (the token).

Although the high-level lock() API handles this internally for release operations, you should ideally pass this token to any external storage systems you are modifying to verify that you still hold the valid lock.