yuna
Version:
Extra zookeeper support for Illyria.
155 lines (104 loc) • 5.57 kB
Markdown
# Yuna (ユウナ)
The extra Zookeeper support for Illyria client pool.
[](https://www.npmjs.com/package/yuna) [](https://travis-ci.org/XadillaX/yuna) [](https://coveralls.io/r/XadillaX/yuna?branch=master&time=201505211829) [](https://david-dm.org/XadillaX/yuna)
## Installation
```sh
$ npm install --save yuna
```
> Yuna is a summoner embarking on a journey to defeat the world-threatening monster ***Sin***. And in this project, she will summon multiple connections of illyria to defeat the instability of servers.
## Usage
### Create
First of all, you should create a new `Yuna` object.
```javascript
var Yuna = require("yuna");
var yuna = Yuna.createPool(ZOOKEEPER_CONNECT_STRING, ZOOKEEPER_ROOT, ZOOKEEPER_PREFIX, OPTIONS);
```
> **Attention:** all of the params above in `Yuna.createPool` are optional.
The parameters and their default value are shown below.
| Parameter | Default | Description |
|------------------------------|-----------------|--------------------------------------------------------------------------------------|
| ZOOKEEPER_CONNECT_STRING | "127.0.0.1" | The connect string for zookeeper. |
| ZOOKEEPER_ROOT | "/illyria" | The root path for the certain server nodes. |
| ZOOKEEPER_PREFIX | "/HB_" | The prefix for the certain server nodes. |
| OPTIONS | [object Object] | The options for this pool. |
| OPTIONS.maxPool | 10 | The maximum client count in the pool. |
| OPTIONS.runTimeout | 10000 | Timeout for one sending operation in million second. (not including retry) |
| OPTIONS.connectTimeout | 5000 | Timeout for the connecting to the server in million second. |
| OPTIONS.retryForGetting | 5 | Times of retry for getting a usable connection. |
| OPTIONS.gettingRetryInterval | 200 | Interval for retry of getting a usable connection. |
| OPTIONS.zookeeper | {} | Refer to [Illyria document](https://github.com/XadillaX/illyria2#with-zookeeper-1). |
| OPTIONS.? | - | Refer to [io.js document](https://iojs.org/api/net.html#net_new_net_socket_options). |
> **Tip:** don't include `connectString`, `root` and `prefix` in option `OPTIONS.zookeeper` because it will be replaced by `ZOOKEEPER_CONNECT_STRING`, `ZOOKEEPER_ROOT` and `ZOOKEEPER_PREFIX`.
### Send
The main method you should use in your program is `Yuna::send`. The parameters are the same as [Illyria Client](https://github.com/XadillaX/illyria2#send-a-message-to-rpc-server).
```javascript
yuna.send("module", "method", DATA, function(err, data, conn) {
// `conn` is the current connection
console.log(err, data, conn);
});
```
### Cast
Using cast protocol to send the message. Reference to [Illyria Client](https://github.com/XadillaX/illyria2#send-a-cast-message-to-rpc-server).
```javascript
yuna.cast("module", "method", DATA, function(err, data, conn) {
// `conn` is the current connection
// and data will always be `undefined`
console.log(err, data, conn);
});
```
### Destroy
Destroy this Yuna pool and disconnect all the connections.
```javascript
yuna.destroy();
```
### New Connection
Most time you needn't to use this method. It usually be used by other functions of Yuna like the constructor function.
```javascript
yuna.newConnection([force], callback);
```
> The optional parameter `force` is defined to tell the function weather the connection will be created forcely and ignore the maximum connection count of the pool.
>
> The callback function is look like `function(err, conn) {}`.
### Get Connection
Most time you needn't to use this method. This method will return you a usable Illyria connection just now if you really want to do this.
```javascript
yuna.getConnection(function(err, conn) {
// DO SOMETHING
});
```
### Available Connection Count
Get current available connection count.
```javascript
var availables = yuna.availableCount();
```
### Client Position
Most time you needn't to use this method. It will tell the position of the connection you passed in in the connection pool.
```javascript
var idx = yuna.clientPosition(conn);
```
### Events
#### new
This event will be emitted when a new connection is set.
```javascript
yuna.on("new", function() {
// SOME CODE...
});
```
#### error
This event will be emitted when a connection has an error. (But Yuna will reconnect automatically)
```javascript
yuna.on("error", function() {
// SOME CODE...
});
```
#### close
This event will be emitted when a connection is disconnected.
```javascript
yuna.on("close", function() {
// SOME CODE...
});
```
## Contribution
You're welcome to make pull requests.
「雖然我覺得不怎麼可能有人會關注我」