etcd3 Node Client

Software Transactional Memory (STM) allows you to execute a block of code containing multiple reads and writes as a single atomic transaction. The system automatically handles retries if a conflict is detected.

Critical Rule: Inside the .transact() block, all reads and writes must go through the provided tx object, not the main etcd3 client. If you use the client directly, those operations will not be tracked by the transaction and atomicity will be lost.

Workflow:

1. Call etcd3.stm(options).transact(tx => { ... }).
2. Use tx.get(key), tx.put(key), and tx.delete() within the block.
3. The library tracks all operations in a ReadSet and WriteSet.
4. Upon completion of the function, the library attempts to commit all changes atomically. If a conflict is detected, it retries the entire block up to the configured retries limit.

const amount = 42;

etcd3.stm().transact(tx => {
  return Promise.all([
    tx.get('bank/account1').number(),
    tx.get('bank/account2').number(),
  ]).then(([balance1, balance2]) => {
    if (balance1 < amount) {
      throw new Error('You do not have enough money to transfer!');
    }

    return Promise.all([
      tx.put('bank/account1').value(balance1 - amount),
      tx.put('bank/account2').value(balance2 + amount),
    ]);
  });
});

The Election class allows multiple distributed nodes to participate in an election to choose a single leader. This is commonly used to ensure only one server performs a specific task (like a singleton job) in a cluster.

There are two primary patterns:

1. Campaigning: Using election.campaign(value) to attempt to become the leader. You listen for the elected event to know when you have successfully acquired leadership.
2. Observing: Using election.observe() to monitor the current leader without participating in the election. You listen for the change event to react to leadership transitions.

Important Lifecycle Notes:

• Campaigns are tied to a TTL (Time To Live). If the underlying lease is lost, the campaign fails and an error event is emitted.
• Observers must be closed using observer.cancel() to prevent resource leaks.
• If a leader node crashes or fails, a new leader will be elected from the remaining candidates.

const os = require('os');
const client = new Etcd3();
const election = client.election('singleton-job');

// Pattern 1: Campaigning for leadership
function runCampaign() {
  const campaign = election.campaign(os.hostname());
  
  campaign.on('elected', () => {
    // This server is now the leader!
    doSomeWork();
  });

  campaign.on('error', error => {
    // Campaign failed (e.g. lease lost). 
    // Stop work and attempt to re-campaign after a delay.
    console.error(error);
    stopDoingWork();
    setTimeout(runCampaign, 5000);
  });
}

// Pattern 2: Observing the leader
async function observeLeader() {
  const observer = await election.observe();
  console.log('The current leader is', observer.leader());
  
  observer.on('change', leader => {
    console.log('The new leader is', leader);
  });

  observer.on('error', () => {
    // Fatal interruption in observation. Re-observe after delay.
    setTimeout(observeLeader, 5000);
  });
}

The faultHandling option allows you to define how the client handles errors using Cockatiel policies. The client uses a two-tier approach: a global policy and a host policy. When the global policy retries, it picks a new host.

Available configuration keys:

• host: A function (hostname: string) => IPolicy that returns a policy applied to a specific host (e.g., a circuit breaker).
• global: An IPolicy applied to all calls (e.g., a retry policy).
• watchBackoff: An IBackoff used by the watch manager for reconnecting watch streams.

Default Behavior:

• global: A three-retry policy.
• host: A circuit breaker that opens for 5 seconds after 3 consecutive failures.
• watchBackoff: Exponential backoff with a max 30s delay and decorrelated jitter.

To disable all fault handling, use Policy.noop for both host and global.

import { Etcd3, isRecoverableError } from 'etcd3';
import { Policy, ConsecutiveBreaker, ExponentialBackoff } from 'cockatiel';

const etcd = new Etcd3({
  faultHandling: {
    host: () =>
      Policy.handleWhen(isRecoverableError).circuitBreaker(5_000, new ConsecutiveBreaker(3)),
    global: Policy.handleWhen(isRecoverableError).retry(3),
    watchBackoff: new ExponentialBackoff(),
  },
});

The ComparatorBuilder allows you to build complex, atomic transactions (Compare-and-Swap/Locking patterns) using if, then, and else clauses.

Comparison Targets

When using .and(), you can compare against:

• Value: The value of the key.
• Version: The key's version.
• Create: The creation revision (create_revision).
• Mod: The modification revision (mod_revision).
• Lease: The lease associated with the key.

Comparison Operators

Supported operators via the comparator map:

• == or ===: Equal
• != or !==: Not Equal
• >: Greater
• <: Less

Transaction Workflow

1. Use .and(key, target, operator, value) to add comparison clauses.
2. Use .then(...clauses) to define operations if the comparison succeeds.
3. Use .else(...clauses) to define operations if the comparison fails.
4. Call .commit() to execute the transaction.

// Example: Implementing a distributed lock
const id = uuid.v4();

function lock() {
  return client.if('my_lock', 'Create', '==', 0)
    .then(client.put('my_lock').value(id))
    .else(client.get('my_lock'))
    .commit()
    .then(result => console.log(result.succeeded === id ? 'lock acquired' : 'already locked'));
}

function unlock() {
  return client.if('my_lock', 'Value', '==', id)
    .then(client.delete().key('my_lock'))
    .commit();
}