1// Distributed Lock using etcd (Raft-backed)
2// A lock granted by etcd is guaranteed held by at most one client cluster-wide
3 
4import { Etcd3 } from 'etcd3';
5 
6const etcd = new Etcd3({ hosts: process.env.ETCD_HOSTS?.split(',') });
7 
8async function withDistributedLock<T>(
9  lockName: string,
10  ttlSeconds: number,
11  operation: () => Promise<T>
12): Promise<T> {
TTL-based lease: etcd deletes the lock key if client crashes or disconnects
13  const lock = etcd.lock(lockName).ttl(ttlSeconds);
14 
15  try {
16    // Block until lock acquired (queued behind other holders)
lock.acquire() is blocking — queues behind other lock holders automatically
17    await lock.acquire();
18    console.log(`Acquired lock: ${lockName}`);
19 
20    return await operation();
21  } finally {
Always release in finally — even if operation throws an exception
22    // Always release — even if operation throws
23    await lock.release();
24  }
25}
26 
27// Usage: ensure only one instance processes a batch at a time
28await withDistributedLock(
29  'batch-processor:nightly-report',
30  30,  // 30s TTL — auto-released if process crashes (lease mechanism)
31  async () => {
32    await runNightlyReport();
33  }
34);
35 
Fencing tokens prevent zombie locks where a slow process uses an expired lock
36// Fencing tokens: handle the "slow process" problem
37// Problem: process holds lock, GC pause causes lock to expire,
38//          another process acquires lock → BOTH think they hold the lock
39//
40// Solution: etcd returns a monotonically increasing revision on each acquire.
41// Include this "fencing token" in writes to the shared resource.
42// Resource rejects writes with older tokens — zombie process rejected.