@eyecone/blastmedia-registry v1.0.2

Registry

Module

The registry is a shared environment holding configurations in a key-value fashion.

Atm, it uses Etcd (& node-etcd). Etcd needs to be installed & accessible (remember firewalls!).

Methods

.createRegistryValue(key, options)

returns a RegistryValue watching the key

.createRegistryValues(map)

returns an Object containing RegistryValue properties.

const rethinkdbData = registry.createRegistryValues({
  hostname  : '/blastmedia/databases/rethinkdb/hostname',
  port      : '/blastmedia/databases/rethinkdb/port',
  password  : '/blastmedia/databases/rethinkdb/password',
  database  : '/blastmedia/databases/rethinkdb/services/shorturls/database',
  table     : '/blastmedia/databases/rethinkdb/services/shorturls/table'
});
console.log(rethinkdbData.hostname);

.registerService(name, hostname, port, serviceInfos = {}, registryPath = '/blastmedia/services/${name}')

.getService(name, callback)

.getServices(raw = false)

The class wraps the node-etcd methods & allows to use promises if no callback is specified.

Basic usage from node-etcd

var Registry = require('@eyecone/blastmedia-registry');
var registry = new Registry();
registry.set("key", "value");
registry.get("key", console.log);

Callbacks follows the default (error, result) nodejs convention:

function callback(err, res) {
    console.log("Error: ", err);
    console.log("Return: ", res);
}
registry.get("key", callback);
// Error: null
// Return: { action: 'get', node: { key: '/key', value: 'value', modifiedIndex: 4, createdIndex: 4 } }

Methods

Registry(hosts = '127.0.0.1:2379', options)

Create a new etcd client for a single host etcd setup

registry = new Registry();
registry = new Registry("127.0.0.1:2379");
registry = new Registry("http://127.0.0.1:2379");
registry = new Registry("https://127.0.0.1:2379");
registry = new Registry(["http://127.0.0.1:2379"]);

Registry(hosts, options)

Create a new etcd client for a clustered etcd setup. Client will connect to servers in random order. On failure it will try the next server. When all servers have failed it will callback with error. If it suspects the cluster is in leader election mode it will retry up to 3 times with exp backoff. Number of retries can be controlled by adding { maxRetries: x } as an option to requests.

registry = new Registry(['127.0.0.1:2379','192.168.1.1:2379']);
registry = new Registry(['http://127.0.0.1:2379','http://192.168.1.1:2379']);

.set(key, value = null, options, callback)

Set key to value, or create key/directory.

registry.set("key");
registry.set("key", "value");
registry.set("key", "value", console.log);
registry.set("key", "value", { ttl: 60 }, console.log);
registry.set("key", "value", { maxRetries: 3 }, console.log);

Available options include:

• ttl (time to live in seconds)
• prevValue (previous value, for compare and swap)
• prevExist (existance test, for compare and swap)
• prevIndex (previous index, for compare and swap)

Will create a directory when used without value (value=null): registry.set("directory/");

.compareAndSwap(key, value, oldvalue, options, callback)

Convenience method for test and set (set with {prevValue: oldvalue})

registry.compareAndSwap("key", "newvalue", "oldvalue");
registry.compareAndSwap("key", "newValue", "oldValue", options, console.log);

Alias: .testAndSet()

.get(key, options, callback)

Get a key or path.

registry.get("key", console.log);
registry.get("key", { recursive: true }, console.log);

Available options include:

• recursive (bool, list all values in directory recursively)
• wait (bool, wait for changes to key)
• waitIndex (wait for changes after given index)

.del(key, options, callback)

Delete a key or path

registry.del("key");
registry.del("key", console.log);
registry.del("key/", { recursive: true }, console.log);

Available options include:

• recursive (bool, delete recursively)

Alias: .delete()

.compareAndDelete(key, oldvalue, options, callback)

Convenience method for test and delete (delete with {prevValue: oldvalue})

registry.compareAndDelete("key", "oldvalue");
registry.compareAndDelete("key", "oldValue", options, console.log);

Alias: .testAndDelete()

.mkdir(dir, options, callback)

Create a directory

registry.mkdir("dir");
registry.mkdir("dir", console.log);
registry.mkdir("dir/", options, console.log);

.rmdir(dir, options, callback)

Remove a directory

registry.rmdir("dir");
registry.rmdir("dir", console.log);
registry.rmdir("dir/", { recursive: true }, console.log);

Available options include:

• recursive (bool, delete recursively)

.create(path, value, options, callback)

Atomically create in-order keys.

registry.create("queue", "first")
registry.create("queue", "next", console.log)

Alias: .post()

.watch(key, options, callback)

This is a convenience method for get with {wait: true}.

registry.watch("key");
registry.watch("key", console.log);

The watch command is pretty low level, it does not handle reconnects or timeouts (Etcd will disconnect you after 5 minutes). Use the .watcher() below if you do not wish to handle this yourself.

.watchIndex(key, index, options, callback)

This is a convenience method for get with {wait: true, waitIndex: index}.

registry.watchIndex("key", 7, console.log);

See .watch() above.

.watcher(key, index, options)

Returns an eventemitter for watching for changes on a key

watcher = registry.watcher("key");
watcher.on("change", console.log); // Triggers on all changes
watcher.on("set", console.log);    // Triggers on specific changes (set ops)
watcher.on("delete", console.log); // Triggers on delete.
watcher2 = registry.watcher("key", null, {recursive: true});
watcher2.on("error", console.log);

You can cancel a watcher by calling .stop().

Signals:

• change - emitted on value change
• reconnect - emitted on reconnect
• error - emitted on invalid content
• <etcd action> - the etcd action that triggered the watcher (ex: set, delete).
• stop - watcher was canceled.
• resync - watcher lost sync (server cleared and outdated the index).

It will handle reconnects and timeouts for you, it will also resync (best effort) if it loses sync with Etcd (Etcd only keeps 1000 items in its event history - for high frequency setups it's possible to fall behind).

Use the .watch() command in you need more direct control.

.raw(method, key, value, options, callback)

Bypass the API and do raw queries. Method must be one of: PUT, GET, POST, PATCH, DELETE

registry.raw("GET", "v2/stats/leader", null, {}, callback)
registry.raw("PUT", "v2/keys/key", "value", {}, callback)

Remember to provide the full path, without any leading '/'

.machines(callback)

Returns information about etcd nodes in the cluster

registry.machines(console.log);

.leader(callback)

Return the leader in the cluster

registry.leader(console.log);

.leaderStats(callback)

Return statistics about cluster leader

registry.leaderStats(console.log);

.selfStats(callback)

Return statistics about connected etcd node

registry.selfStats(console.log);

Synchronous operations

The library supports a set of basic synchronous/blocking operations that can be useful during program startup (used like fs.readFileSync).

Synchronous functions perform the etcd request immediately (blocking) and return the following:

{
  err // Error message or null if request completed successfully
  body // Body of the message or null if error
  headers // Headers from the response
}

.setSync(key, value = null, options)

Synchronously set key to value, or create key/directory.

registry.setSync("key");
registry.setSync("key", "value");
registry.setSync("key", "value", { ttl: 60 });
registry.setSync("key", "value", { maxRetries: 3 });

Same options and function as .set().

.getSync(key, options)

Get a key or path.

registry.getSync("key");
registry.getSync("key", { recursive: true });

.delSync(key, options)

Synchronously delete a key or path

registry.delSync("key");
registry.delSync("key/", { recursive: true });

The available options are the same as .del() above.

.mkdirSync(dir, options)

Synchronously create a directory

registry.mkdirSync("dir");
registry.mkdirSync("dir/", options);

.rmdirSync(dir, options)

Synchronously remove a directory

registry.rmdirSync("dir");
registry.rmdirSync("dir/", { recursive: true });

The available options are the same as .rmdir() above.