multilevel-agent

multilevel-agent

makes multilevel server/client simpler, with auto restart and reconnect.

Installation

npm install multilevel-agent

Usage

var multilevelAgent = require('multilevel-agent');

Server

var server = multilevelAgent.Server([options]);

The options could have below properties:

• location The directory where to storage your data(required).
• autostart A value indicates whether automatic start the SERVER or not, false as default.
• port Port of TCP server, 8081 as default.
• auth and access from multilevel
• options from levelup

Example

var server = multilevelAgent.Server({
  location: __dirname + '/db/',
  port: 8090,
  valueEncoding: 'json',
  auth: function (user, cb) {
    if (user.name == 'root' && user.pass == 'p@ss') {
      cb(null, {name: 'root'});
    } else {
      cb(new Error('not authorized'));
    }
  },
  access: function (user, db, method, args) {
    if (!user || user.name !== 'root') {
      if (/^put|^del|^batch|write/i.test(method)) {
        throw new Error('read-only access');
      }
    }
  }
});

See more from example/server.js.

Events

error

Emitted when an error occurs, e.g.:

server.on('error', function(err){

});

The err is an instance of Error, and in addition, err has one more property err.source, see more from sources.

connect

Emitted when a new TCP connection is made, e.g.:

server.on('connect', function(){

});

close

Emitted when the server/client/database closes, e.g.:

server.on('close', function(agent){

});

agent including two properties:

• source One of sources.
• event The original event.

This event is very important, and you can use agent.source to identify who emitted 'close' event, it could be one of sources. If it is 'tcp_server' or 'database', it means server or database has just crashed, you'd better restart your server. If you are using pm2, just exist the process then pm2 will auto restart your server:

server.on('close', function(agent){
  if(agent.source == multiAgent.Server.source.TCP_SERVER || agent.source == multiAgent.Server.source.DATABASE){
    process.exit(0);
    return;
  }
  // tcp_client closed? screw it.
});

Methods

start

Just start the server, if autostart is set to true, this effects nothing.

server.start();

stop

If current state equals multiAgent.Server.state.RUNNING, stops the server. Notes: The server is finally closed when all connections are ended and the server emits a 'close' event. So, if you really wanna shut down the server, just try process.exit(0).

server.stop();

Properties

options

The restructuring options.

console.log(server.options);

state

The current state of server, see more from states.

port

The port of TCP server.

Client

var client = multilevelAgent.Client([options]);

The options could have below properties:

• host The host of TCP server(required).
• port The port of TCP server which client connects to.
• manifest See multilevel.client([manifest]).

Example

var client = multilevelAgent.Client({
  host: 'localhost',
  port: 8090
});

See more from example/client.js.

API

Access multilevel's APIs through client.db, e.g.:

client.db.put('KEY', 'VALUE');
client.db.get('KEY', function(err, value){

});
// ...

Events

error

Emitted when an error occurs, e.g.:

server.on('error', function(err){

});

The err is an instance of Error, and in addition, err has one more property err.source, see more from sources.

connect

Emitted when a new TCP connection or Database is made, e.g.:

server.on('connect', function(){

});

reconnecting

Emitted when reconnecting to datababase/tcp server, e.g.:

client.on('reconnecting', function(recon){

})

The reconn indluding two properties:

• attempts The attempts number that CLIENT has tried reconnect to server.
• delay The next retry delay(milliseconds).

Properties

options

The restructuring options.

console.log(server.options);

state

The current state of server, see more from states.

Sources

Server

• 'database' equals multiAgent.Server.source.DATABASE.
• 'tcp_client' equals multiAgent.Server.source.TCP_CLIENT.
• 'tcp_server' equals multiAgent.Server.source.TCP_SERVER.
• 'level_server' equals multiAgent.Server.source.LEVEL_SERVER.

Client

• 'database' equals multiAgent.Client.source.DATABASE.
• 'tcp_client' equals multiAgent.Client.source.TCP_CLIENT.
• 'rpc_stream' equals multiAgent.Client.source.RPC_STREAM.
• 'level_server' equals multiAgent.Client.source.LEVEL_SERVER.

States

Server

• 'init' equals multiAgent.Server.state.INIT.
• 'running' equals multiAgent.Server.state.RUNNING.
• 'stop' equals multiAgent.Server.state.STOP.

Client

• 'init' equals multiAgent.Client.state.INIT.
• 'running' equals multiAgent.Client.state.RUNNING.
• 'stop' equals multiAgent.Client.state.STOP.

Test

Only test options.

npm test

Manual test:

• First: start server

  node example/server
  

• Second: run client

  node example/client
  

If you wanna make different tests, just edit the scripts under example folder.

License

Copyright 2014 Tjatse

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.