-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
travis-ci
committed
Jul 4, 2016
1 parent
0753c5e
commit cf050a9
Showing
2 changed files
with
181 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters