-
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 bfa6812
Showing
2 changed files
with
179 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,201 @@ | ||
[![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. Return `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. Return `Promise`; | ||
- `index` (String): the path of the property to get. It need to be declare in [`indexes`'s 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" } } | ||
``` | ||
Field can be nested, as described by [`_.get`](https://lodash.com/docs#get). | ||
#### `getAll(index)` | ||
Get index Map. Return `Promise`; | ||
- `index` (String): the path of the property to get. It need to be declare in [indexes's 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` | ||
Synchronise FS folder with ETCD folder. | ||
```Shell | ||
$ squirrel-sync --hosts localhost:2379 ./fs-folder /etcd-folder | ||
``` | ||
### `squirrel-watch` | ||
Watch ETCD folder change. | ||
```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 allow 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 at all, we should indicate to squirrel which path we want to index. | ||
```JavaScript | ||
const squirrel = createSquirrel({ | ||
indexes: ['foo'] | ||
}); | ||
``` | ||
Now, we can get `file1` by its `foo` value. | ||
```JavaScript | ||
const file1 = await squirrel.getBy('foo', 'bar'); | ||
console.log(file1); // { "foo": "bar" } | ||
``` | ||
We can also get the map value of the index. | ||
```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's value, squirrel keep one of both. | ||
Squirrel scans all files, no matter their deep, which contain a JSON value. | ||
Index could be a complex path, as long as it work with [`_.get`](https://lodash.com/docs#get). | ||
# Fallback System | ||
By declaring `fallback` path, Squirrel is able to save its state every time it changes and to restore it to be faster available on start 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