RiakPBC
RiakPBC is a low-level riak 2.0 protocol buffer client for node.js.
Contents
Installation
npm install --save riakpbc
Client
var RiakPBC = require('riakpbc');
var client = RiakPBC.createClient(/* options */);
Options
The options
object accepts the following parameters:
connectTimeout
: The timeout (in milliseconds) for creating a new connection. (Default:1000
)idleTimeout
: The amount of time (in milliseconds) that a node can be idle in the connection pool before it is released. (Default:30000
)minConnections
: The minimum number of connections to keep active in the connection pool. (Default:0
)maxConnections
: The maximum number of connections that may be active in the connection pool at any given time. (Default:10
)parseValues
: If set tofalse
, values will be returned as buffers rather than strings or parsed JSON. (Default:true
)nodes
: An array of{ host: 'string', port: number }
objects specifying all of the riak nodes to use. These are then load balanced via round-robin.host
: If only connecting to a single node, you may specify thehost
property directly rather than passing an array ofnodes
. (Default:'127.0.0.1'
)port
: Again, if only connecting to a single node, you may specify theport
directly. (Default:8087
)auth
: User and password, specified as a{ user: 'string', password: 'string' }
object, to use for authentication if using riak security.
Usage
For a full reference of all available methods, see the API Reference.
Methods that accept input have the signature (params, callback)
, where params
is an object containing the message to be sent to riak.
Methods that do not accept input have the signature (callback)
.
Callbacks have the signature (err, response)
.
If an error occurs, the err
object will be a standard Error
object wrapping the riak supplied RpbErrorResp message.
If the call was successful, response
will be the riak supplied message. Many calls do not return a value, or only return a value when certain flags are set, in these cases the response
will be an empty object {}
.
client.ping(function (err, response) {
if (err) {
return console.error('Failed to ping:', err);
}
console.log(response); // {}
});
Note that callbacks are always optional, and if not supplied the call will return a stream instead.
These streams will emit only an error
event if an error occurs. If the call is successful, the stream will emit one or more data
events and an end
event.
var keys = client.getKeys({ bucket: 'test' });
keys.on('error', function (err) {
console.error('An error occurred:', err);
});
keys.on('data', function (response) {
console.log('Got some keys:', response.keys); // this could fire multiple times
});
keys.on('end', function () {
console.log('Finished listing keys');
});
Data Conversions
RiakPBC attempts to stay as accurate as possible when converting data to and from protocol buffer encoding.
All available messages are documented in the Messages reference.
The primary data types that riak uses are handled as follows:
bytes
The bytes
type may be supplied as either a string
or a Buffer
.
By default, when translating a response message these fields will be converted to a string
unless they are the vclock
or context
properties. Since these values are intended to be binary only, they are left as a Buffer
.
In the case of RpbContent values, RiakPBC will convert the value
field to a string only if a content_type
was set, and begins with the string text
(as in text/plain
or text/xml
). In addition, if content_type
is set to application/json
RiakPBC will parse the value as JSON automatically.
This behavior can be overridden and Buffer
objects returned for all bytes
fields by setting { parseValues: false }
in your client options.
uint32/float
These fields will always be treated as a plain javascript number.
sint64
Since javascript does not properly handle 64 bit numbers, these are a special case.
When used as input, you may pass either a number (42
), a string ('-98549321293'
), or a long.js object.
In a reply, you will always receive a long.js object. These objects allow RiakPBC to properly support real 64 bit number values.
bool
These fields will always be treated as a plain javascript boolean (i.e. true
or false
).
enums
Several messages accept an enum field. RiakPBC exports these as variables on the main object to simplify input. They are as follows:
- IndexQueryType:
- RiakPBC.IndexType.Exact
- RiakPBC.IndexType.Range
- DataType:
- RiakPBC.DataType.Counter
- RiakPBC.DataType.Set
- RiakPBC.DataType.Map
- MapFieldType:
- RiakPBC.FieldType.Counter
- RiakPBC.FieldType.Set
- RiakPBC.FieldType.Register
- RiakPBC.FieldType.Flag
- RiakPBC.FieldType.Map
- FlagOp:
- RiakPBC.Flag.Enable
- RiakPBC.Flag.Disable
These variables are all simple numbers, however, so when RiakPBC returns a message containing one of these types you will receive a plain number. I would recommend using the exported variables for comparison purposes to maintain readable code.
Embedded Messages
All other types not documented here are an embedded message and are recursively encoded/decoded in the same fashion as the above types.