From cf050a90b6e344c127d28f6b29e2e66a02abbfae Mon Sep 17 00:00:00 2001 From: travis-ci Date: Mon, 4 Jul 2016 15:32:28 +0200 Subject: [PATCH] Update documentation --- README.md | 194 +++++++++++++++++++++++++++++++++++++++++---- docker-compose.yml | 2 +- 2 files changed, 181 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index de828de..b797480 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,203 @@ [![Build Status](https://travis-ci.org/CoorpAcademy/squirrel.svg?branch=master)](https://travis-ci.com/CoorpAcademy/squirrel) [![Coverage Status](https://coveralls.io/repos/github/CoorpAcademy/squirrel/badge.svg?branch=master)](https://coveralls.io/github/CoorpAcademy/squirrel?branch=master) -# squirrel -Watch etcd folder and keep it synchronized. +Keep a replication of ETCD folder locally for low latency querying. +Provide index system to access a file without scan all nodes tree. -## Install -```shell +# Summary + +- [Install](#install) +- [Usage](#usage) + - [Node Interface](#node-interface) + - [`get(path)`](#getpath) + - [`getBy(index, key)`](#getbyindex-key) + - [`getAll(index)`](#getallindex) + - [Command Line Interface](#command-line-interface) + - [`squirrel-sync`](#squirrel-sync) + - [`squirrel-watch`](#squirrel-watch) +- [Index System](#index-system) +- [Fallback System](#fallback-system) +- [Test](#test) + +# Install + +```Shell $ npm install --save @coorpacademy/squirrel ``` +```JavaScript +import createSquirrel from '@coorpacademy/squirrel'; +``` -## Usage -### Command Line Interface +# Usage +## Node Interface + +```JavaScript +const squirrel = createSquirrel({ + hosts: 'http://localhost:2379', + auth: null, + ca: null, + key: null, + cert: null, + + cwd: '/', + fallback: '/tmp/squirrel.json', + indexes: ['foo', 'bar.baz'] +}); ``` -squirrel-sync --hosts localhost:2379,localhost:2379 ./my-folder /etcd-folder -squirrel-watch --hosts localhost:2379,localhost:2379 /etcd-folder + +Options: +- `hosts`: ETCD hosts. [more](https://github.com/stianeikeland/node-etcd/#etcdhosts--1270012379-options) +- `auth`: A hash containing `{user: "username", pass: "password"}` for basic auth. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) +- `ca`: Ca certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) +- `key`: Client key. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) +- `cert`: Client certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) +- `cwd`: ETCD current working directory. +- `fallback`: Temporary file to save ETCD replicat. +- `indexes`: Array of key to index. + +### Methods + +Consider the following folder: + + +```Shell +/ +├── bar +│   └── baz { "bar": { "baz": "qux" } } +└── foo { "foo": "bar" } ``` -### Retrieve a Client +#### `get(path)` +Get file by path. Returns `Promise`; +- `path` (String): the path of the file to get. -## Test -You may run test with +```JavaScript +const foo = await squirrel.get('/foo'); +console.log(foo); // { "foo": "bar" } + +const barBaz = await squirrel.get('/bar/baz'); +console.log(barBaz); // { "bar": { "baz": "qux" } } ``` -$ npm test + +#### `getBy(index, key)` + +Get by index value. Returns `Promise`; + +- `index` (String): the path of the property to get. It need to be declared in the [`indexes` options](#node-interface) +- `key` (String): the value to match + +```JavaScript +const foo = await squirrel.getBy('foo', 'bar'); +console.log(foo); // { "foo": "bar" } + +const barBaz = await squirrel.getBy('bar.baz', 'qux'); +console.log(barBaz); // { "bar": { "baz": "qux" } } +``` + +Fields can be nested, as described by [`_.get`](https://lodash.com/docs#get). + +#### `getAll(index)` + +Get index Map. Returns `Promise`; + +- `index` (String): the path of the property to get. It need to be declared in the [`indexes` options](#node-interface) + +```JavaScript +const foo = await squirrel.getAll('foo'); +console.log(foo); // { "bar": { "foo": "bar" } } + +const barBaz = await squirrel.getAll('bar.baz'); +console.log(barBaz); // { "qux": { "bar": { "baz": "qux" } } } ``` -Please note that test use an actual etcd service +## Command Line Interface +### `squirrel-sync` + +Synchronize FS folder with ETCD folder. + +```Shell +$ squirrel-sync --hosts localhost:2379 ./fs-folder /etcd-folder +``` +### `squirrel-watch` +Watch ETCD folder changes. + +```Shell +$ squirrel-watch --hosts localhost:2379 /etcd-folder +``` + +### Arguments + +- `--hosts="host1,host2"`: ETCD hosts. [more](https://github.com/stianeikeland/node-etcd/#etcdhosts--1270012379-options) +- `--ca=/file.ca`: Ca certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) +- `--key=/file.key`: Client key. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) +- `--cert=/file.cert`: Client certificate. [more](https://github.com/stianeikeland/node-etcd/#constructor-options) + +# Index System + +Squirrel allows to put JSON in file. In this case, it could be indexes to access directly. Consider the following ETCD directory. + +```Shell +/ +├── file1 { "foo": "bar" } +├── file2 { "foo": "baz" } +└── file3 { "foo": "qux" } +``` + +First of all, we should indicate Squirrel which paths we want to index. + +```JavaScript +const squirrel = createSquirrel({ + indexes: ['foo'] +}); +``` + +Now, we can get the contents of `file1` by searching for its `foo` value. + +```JavaScript +const file1 = await squirrel.getBy('foo', 'bar'); +console.log(file1); // { "foo": "bar" } +``` + +We can also get the value of the index as an object. + +```JavaScript +const fooIndex = await squirrel.getAll('foo'); +console.log(fooIndex); +/* +{ + "bar": { "foo": "bar" }, + "baz": { "foo": "baz" }, + "qux": { "foo": "qux" } +} + */ +``` + +If two files have the same index value, Squirrel keeps one of two. + +Squirrel scans all files, no matter how deep, that contain a JSON value. + +Index could be a complex path, as long as it works with [`_.get`](https://lodash.com/docs#get). + +# Fallback System + +By declaring a `fallback` path, Squirrel is able : +- to save its state every time a change is made +- to restore the state to be faster on the next restart even if ETCD isn't available. + +# Test + +You may run tests with + +```Shell +$ npm test +``` -## [Marble](./MARBLE.md) +# [Marble](./MARBLE.md) diff --git a/docker-compose.yml b/docker-compose.yml index dc4e05f..74db89e 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,4 +3,4 @@ etcd: ports: - "2379:2379" - "4001:4001" - command: -listen-client-urls 'http://0.0.0.0:2379,http://0.0.0.0:4001' -advertise-client-urls 'http://0.0.0.0:2379,http://0.0.0.0:4001' + command: etcd --listen-client-urls 'http://0.0.0.0:2379' --advertise-client-urls 'http://0.0.0.0:2379'