etcd3

etcd3

etcd3 aims is a high-quality, production-ready client for the Protocol Buffer-based etcdv3 API. It includes:

• load balancing
• fault handling and reconnections
• transactions
• software transactional memory
• high-level query builders
• lease management
• watchers
• user and role mocking management
• elections

and is type-safe for TypeScript consumers.

Quickstart

Install via:

npm install --save etcd3

Start building!

const { Etcd3 } = require('etcd3');
const client = new Etcd3();

(async () => {
  await client.put('foo').value('bar');

  const fooValue = await client.get('foo').string();
  console.log('foo was:', fooValue);

  const allFValues = await client.getAll().prefix('f').keys();
  console.log('all our keys starting with "f":', allFValues);

  await client.delete().all();
})();

API Documentation

Our TypeDoc docs are available here.

Our test cases are also readable.

Running tests

$ npm install
$ cd src/test/containers/3.2 && docker-compose up # in a separate shell
$ npm test
$ docker-compose down

Contributing

Running tests for this module requires running an etcd3 server locally. The tests try to use the default port initially, and you can configure this by setting the ETCD_ADDR environment variable, like export ETCD_ADDR=localhost:12345.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.

Changelog

1.1.0 2020-11-28

• feat: implement elections

  Implementation of elections, as seen in etcd's Go client. Elections are most commonly used if you need a single server in charge of a certain task; you run an election on every server where your program is running, and among them they will choose one "leader".

  There are two main entrypoints: campaigning via Election.campaign, and observing the leader via Election.observe.

  const os = require('os');
  const client = new Etcd3();
  const election = client.election('singleton-job');
  
  function runCampaign() {
    const campaign = election.campaign(os.hostname());
    campaign.on('elected', () => {
      // This server is now the leader! Let's start doing work
      doSomeWork();
    });
    campaign.on('error', error => {
      // An error happened that caused our campaign to fail. If we were the
      // leader, make sure to stop doing work (another server is the leader
      // now) and create a new campaign.
      console.error(error);
      stopDoingWork();
      setTimeout(runCampaign, 5000);
    });
  }
  
  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', () => {
      // Something happened that fatally interrupted observation.
      setTimeout(observeLeader, 5000);
    });
  }
  

  Thanks to @yujuiting for their help with the initial implementation. (see #66, #85).

• fix: deprecation: watcherBuilder.ignore() was available for "ignoring" types of events, but it actually did the opposite: it was an include-list, rather than a deny-list. It's deprecated in favor of watchBuilder.only()

• fix: buffers not allowed in typings Namespace.get(<key>)

• fix: prevent user errors in watcher event listeners from causing backoffs in the underlying stream