websocket-tarantool-driver

Node.js driver for tarantool 1.7+

Websocket browser tarantool driver for 1.7+

Code architecture and some features in version 3 borrowed from the ioredis.

msgpack-lite package used as MsgPack encoder/decoder.

Table of contents

• Installation
• Configuration
• Usage example
• Msgpack implementation
• API reference
• Debugging
• Contributions
• Changelog

Installation

npm install --save websocket-tarantool-driver

Configuration

new Tarantool([port], [host], [options]) ⇐ EventEmitter

Creates a Tarantool instance, extends EventEmitter.

Connection related custom events:

• "reconnecting" - emitted when the client try to reconnect, first argument is retry delay in ms.
• "connect" - emitted when the client connected and auth passed (if username and password provided), first argument is an object with host and port of the Taranool server.

Param	Type	Default	Description
[port]	number | string | Object	3301	Port of the Tarantool server, or a URI string (see the examples in tarantool configuration doc), or the options object(see the third argument).
[host]	string | Object	"localhost"	Host of the Tarantool server, when the first argument is a URL string, this argument is an object represents the options.
[options]	Object		Other options.
[options.port]	number	6379	Port of the Tarantool server.
[options.host]	string	"localhost"	Host of the Tarantool server.
[options.username]	string	null	If set, client will authenticate with the value of this option when connected.
[options.password]	string	null	If set, client will authenticate with the value of this option when connected.
[options.timeout]	number	0	The milliseconds before a timeout occurs during the initial connection to the Tarantool server.
[options.lazyConnect]	boolean	false	By default, When a new Tarantool instance is created, it will connect to Tarantool server automatically. If you want to keep disconnected util a command is called, you can pass the lazyConnect option to the constructor.
[options.reserveHosts]	array	[]	Array of strings - reserve hosts. Client will try to connect to hosts from this array after loosing connection with current host and will do it cyclically. See example below.
[options.beforeReserve]	number	2	Number of attempts to reconnect before connect to next host from the reserveHosts
[options.retryStrategy]	function		See below

Reserve hosts example:

let connection = new Tarantool({
    endpoint: 'ws://localhost:8080',
})
// connect to mail.ru:33013 -> dead 
//                  ↓
// trying connect to mail.ru:33033 -> dead
//                  ↓
// trying connect to 127.0.0.1:3301 -> dead
//                  ↓
// trying connect to mail.ru:33013 ...etc

Retry strategy

By default, node-tarantool-driver client will try to reconnect when the connection to Tarantool is lost except when the connection is closed manually by tarantool.disconnect().

It's very flexible to control how long to wait to reconnect after disconnection using the retryStrategy option:

var tarantool = new Tarantool({
  // This is the default value of `retryStrategy`
  retryStrategy: function (times) {
    var delay = Math.min(times * 50, 2000);
    return delay;
  }
});

retryStrategy is a function that will be called when the connection is lost. The argument times means this is the nth reconnection being made and the return value represents how long (in ms) to wait to reconnect. When the return value isn't a number, node-tarantool-driver will stop trying to reconnect, and the connection will be lost forever if the user doesn't call tarantool.connect() manually.

This feature is borrowed from the ioredis

Usage example

We use TarantoolConnection instance and connect before other operations. Methods call return promise(https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Promise). Available methods with some testing: select, update, replace, insert, delete, auth, destroy.

var TarantoolConnection = require('web-tarantool-driver');
var conn = new TarantoolConnection('ws://localhost:8080');

// select arguments space_id, index_id, limit, offset, iterator, key
conn.select(512, 0, 1, 0, 'eq', [50])
    .then(funtion(results){
        doSomeThingWithResults(results);
    });

API reference

tarantool.connect() ⇒ Promise

Resolve if connected. Or reject if not.

tarantool.select(spaceId: Number or String, indexId: Number or String, limit: Number, offset: Number, iterator: Iterator, key: tuple) ⇒ Promise

Iterators. Available iterators: 'eq', 'req', 'all', 'lt', 'le', 'ge', 'gt', 'bitsAllSet', 'bitsAnySet', 'bitsAllNotSet'.

It's just select. Promise resolve array of tuples.

Some examples:

conn.select(512, 0, 1, 0, 'eq', [50]);
//same as
conn.select('test', 'primary', 1, 0, 'eq', [50]);

You can use space name or index name instead of id, but it will some requests for get this metadata. That information actual for delete, replace, insert, update too.

tarantool.selectCb(spaceId: Number or String, indexId: Number or String, limit: Number, offset: Number, iterator: Iterator, key: tuple, callback: function(success), callback: function(error))

Same as tarantool.select but with callbacks.

tarantool.delete(spaceId: Number or String, indexId: Number or String, key: tuple) ⇒ Promise

Promise resolve an array of deleted tuples.

tarantool.update(spaceId: Number or String, indexId: Number or String, key: tuple, ops) ⇒ Promise

Possible operators.

Promise resolve an array of updated tuples.

tarantool.insert() ⇒ Promise

More you can read here: Insert

Promise resolve a new tuple.

tarantool.upsert(spaceId: Number or String, ops: array of operations, tuple: tuple) ⇒ Promise

About operation: Upsert

Possible operators.

Promise resolve nothing.

tarantool.replace(spaceId: Number or String, tuple: tuple) ⇒ Promise

More you can read here: Replace

Promise resolve a new or replaced tuple.

tarantool.call(functionName: String, args...) ⇒ Promise

Call a function with arguments.

You can create function on tarantool side:

function myget(id)
    val = box.space.batched:select{id}
    return val[1]
end

And then use something like this:

conn.call('myget', 4)
    .then(function(value){
        console.log(value);
    });

If you have a 2 arguments function just send a second arguments in this way:

conn.call('my2argumentsfunc', 'first', 'second argument')

And etc like this.

Because lua support a multiple return it's always return array or undefined.

tarantool.eval(expression: String) ⇒ Promise

Evaluate and execute the expression in Lua-string. Eval

Promise resolve result:any.

Example:

conn.eval('return box.session.user()')
    .then(function(res){
        console.log('current user is:' res[0])
    })

tarantool.ping() ⇒ Promise

Promise resolve true.

tarantool.destroy(interupt: Boolean) ⇒ Promise

Deprecated

tarantool.disconnect()

Disconnect from Tarantool.

This method closes the connection immediately, and may lose some pending replies that haven't written to client.

Debugging

Set environment variable "DEBUG" to "tarantool-driver:*"

Contributions

It's ok you can do whatever you need. I add log options for some technical information it can be help for you. If i don't answer i just miss email :( it's a lot emails from github so please write me to [e-mail] directly if i don't answer in one day.

Changelog

0.0.0

Publish version. Don't work auth. Work select, insert certainly.