Socket
Socket
Sign inDemoInstall

memcached

Package Overview
Dependencies
4
Maintainers
1
Versions
33
Alerts
File Explorer

Advanced tools

npm Scripts
License

Install Socket

Detect and block malicious and high-risk dependencies

Install

Comparing version 0.1.2 to 0.1.3

.travis.yml
AUTHORS.md
test/common.js
test/fixtures/hotchicks.jpg
test/fixtures/lipsum.txt
test/memcached-add.test.js
test/memcached-cas.test.js
test/memcached-get-set.test.js
test/memcached-incr-decr.test.js
test/mocha.opts

11

lib/memcached.js

@@ -407,3 +407,3 @@ "use strict";

, flag = +tokens[2]
, expire = tokens[3]
, dataLen = tokens[3] // length of dataSet in raw bytes
, cas = tokens[4]

@@ -415,2 +415,11 @@ , multi = this.metaData[0] && this.metaData[0].multi || cas

// In parse data there is an '||' passing us the content of token
// if dataSet is empty. This may be fine for other types of responses,
// in the case of an empty string being stored in a key, it will
// result in unexpected behavior:
// https://github.com/3rd-Eden/node-memcached/issues/64
if (dataLen === '0') {
dataSet = '';
}
switch (flag) {

@@ -417,0 +426,0 @@ case FLAG_JSON:

5

package.json
{
"name": "memcached"
, "version": "0.1.2"
, "version": "0.1.3"
, "author": "Arnout Kazemier"

@@ -44,2 +44,5 @@ , "description": "A fully featured Memcached API client, supporting both single and clustered Memcached servers through consistent hashing and failover/failure. Memcached is rewrite of nMemcached, which will be deprecated in the near future."

}
, "scripts": {
"test": "./node_modules/.bin/mocha $(shell find test -name '*.test.js')"
}
}

243

README.md

@@ -1,18 +0,38 @@

#Memcached
#Memcached [![Build Status](https://secure.travis-ci.org/3rd-Eden/node-memcached.png?branch=master)](http://travis-ci.org/3rd-Eden/node-memcached)
`memcached` is a fully featured Memcached client for Node.js. `memcached` is build with scaling, high availability and exceptional performance in mind. We use consistent hashing to store the data across different nodes. Consistent hashing is a scheme that provides a hash table functionality in a way that adding or removing a server node does not significantly change the mapping of the keys to server nodes. The algorithm that is used for consistent hashing is the same as `libketama`.
`memcached` is a fully featured Memcached client for Node.js. `memcached` is
build with scaling, high availability and exceptional performance in mind. We
use consistent hashing to store the data across different nodes. Consistent
hashing is a scheme that provides a hash table functionality in a way that
adding or removing a server node does not significantly change the mapping of
the keys to server nodes. The algorithm that is used for consistent hashing is
the same as `libketama`.
There are different ways to handle errors for example, when a server becomes unavailable you can configure the client to see all requests to that server as cache misses until it goes up again. It's also possible to automatically remove the affected server from the consistent hashing algorithm or provide `memcached` with a failover server that can take the place of the unresponsive server.
There are different ways to handle errors for example, when a server becomes
unavailable you can configure the client to see all requests to that server as
cache misses until it goes up again. It's also possible to automatically remove
the affected server from the consistent hashing algorithm or provide `memcached`
with a failover server that can take the place of the unresponsive server.
When these issues occur the `memcached` client will emit different events where you can subscribe to containing detailed information about the issues.
When these issues occur the `memcached` client will emit different events where
you can subscribe to containing detailed information about the issues.
The client is configurable on different levels. There's a global configuration that you update so all you Memcached clusters will use the same failure configuration for example, but it's also possible to overwrite these changes per `memcached` instance.
The client is configurable on different levels. There's a global configuration
that you update so all you Memcached clusters will use the same failure
configuration for example, but it's also possible to overwrite these changes per
`memcached` instance.
### protocol
This module uses the ASCII protocol to communicate with the server, this makes it easier to debug for you are user as you can see what is send over the wire but also for me as developer. But this also means that SASL auth is not supported in this driver as that requires the use of the binary protocol. The ASCII protocol not only used by memcached but also by other databases and message queues, so that is a nice extra.
This module uses the ASCII protocol to communicate with the server, this makes
it easier to debug for you are user as you can see what is send over the wire
but also for me as developer. But this also means that SASL auth is not
supported in this driver as that requires the use of the binary protocol. The
ASCII protocol not only used by memcached but also by other databases and
message queues, so that is a nice extra.
## Setting up the client
The constructor of the `memcached` client take 2 different arguments `server locations` and `options`. Syntax:
The constructor of the `memcached` client take 2 different arguments `server
locations` and `options`. Syntax:

@@ -26,26 +46,33 @@ ``` js

The server locations is designed to work with different formats. These formats are all internally parsed to the correct format so our consistent hashing scheme can work with it. You can either use:
The server locations is designed to work with different formats. These formats
are all internally parsed to the correct format so our consistent hashing scheme
can work with it. You can either use:
1. **String**, this only works if you have are running a single server instance of Memcached.
It's as easy a suppling a string in the following format: `hostname:port`. For example
`192.168.0.102:11212` This would tell the client to connect to host `192.168.0.102` on
port number `11212`.
1. **String**, this only works if you have are running a single server instance
of Memcached. It's as easy a suppling a string in the following format:
`hostname:port`. For example `192.168.0.102:11212` This would tell the client
to connect to host `192.168.0.102` on port number `11212`.
2. **Array**, if you are running a single server you would only have to supply one item in the array.
The array format is particularly useful if you are running a cluster of Memcached servers. This will
allow you to spread the keys and load between the different servers. Giving you higher availability for
when one of your Memcached servers goes down.
3. **Object**, when you are running a cluster of Memcached servers it could happen to not all server can
allocate the same amount of memory. You might have a Memcached server with 128mb, 512, 128mb. If you would
the array structure all servers would have the same weight in the consistent hashing scheme. Spreading the
keys 33/33/33 over the servers. But as server 2 has more memory available you might want to give it more weight
so more keys get stored on that server. When you are using a object, the `key` should represent the server
location syntax and the value the weight of the server. By default all servers have a weight of 1.
`{ '192.168.0.102:11212': 1, '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 }` would generate a 25/50/25
distribution of the keys.
2. **Array**, if you are running a single server you would only have to supply
one item in the array. The array format is particularly useful if you are
running a cluster of Memcached servers. This will allow you to spread the keys
and load between the different servers. Giving you higher availability for
when one of your Memcached servers goes down.
3. **Object**, when you are running a cluster of Memcached servers it could
happen to not all server can allocate the same amount of memory. You might
have a Memcached server with 128mb, 512, 128mb. If you would the array
structure all servers would have the same weight in the consistent hashing
scheme. Spreading the keys 33/33/33 over the servers. But as server 2 has
more memory available you might want to give it more weight so more keys get
stored on that server. When you are using a object, the `key` should
represent the server location syntax and the value the weight of the server.
By default all servers have a weight of 1. `{ '192.168.0.102:11212': 1,
'192.168.0.103:11212': 2, '192.168.0.104:11212': 1 }` would generate a
25/50/25 distribution of the keys.
If you would implement one of the above formats, your constructor would something like this:
If you would implement one of the above formats, your constructor would
something like this:
``` js
```js
var memcached = new Memcached({ '192.168.0.102:11212': 1, '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 });

@@ -58,20 +85,32 @@ var memcached = new Memcached([ '192.168.0.102:11212', '192.168.0.103:11212', '192.168.0.104:11212' ]);

There 2 kinds of options that can be configured. A global configuration that will be inherited by all Memcached servers instances and a client specific configuration that can be used to overwrite the globals. The options should be formatted in an JavaScript `object`. They both use the same object structure:
There 2 kinds of options that can be configured. A global configuration that
will be inherited by all Memcached servers instances and a client specific
configuration that can be used to overwrite the globals. The options should be
formatted in an JavaScript `object`. They both use the same object structure:
* `maxKeySize`: *250*, the max size of they key allowed by the Memcached server.
* `maxExpiration`: *2592000*, the max expiration of keys by the Memcached server in milliseconds.
* `maxValue`: *1048576*, the max size of a value that is allowed by the Memcached server.
* `maxExpiration`: *2592000*, the max expiration of keys by the Memcached server
in milliseconds.
* `maxValue`: *1048576*, the max size of a value that is allowed by the
Memcached server.
* `poolSize`: *10*, the maximum connections we can allocate in our connection pool.
* `algorithm`: *crc32*, the hashing algorithm that should be used to generate the hashRing values.
* `reconnect`: *18000000*, when the server is marked as dead we will attempt to reconnect every x milliseconds.
* `timeout`: *5000*, after x ms the server should send a timeout if we can't connect. This will also be used close the connection if we are idle.
* `algorithm`: *crc32*, the hashing algorithm that should be used to generate
the hashRing values.
* `reconnect`: *18000000*, when the server is marked as dead we will attempt to
reconnect every x milliseconds.
* `timeout`: *5000*, after x ms the server should send a timeout if we can't
connect. This will also be used close the connection if we are idle.
* `retries`: *5*, amount of tries before we mark the server as dead.
* `retry`: *30000*, timeout between each retry in x milliseconds.
* `remove`: *false*, when the server is marked as dead you can remove it from the pool so all other will receive the keys instead.
* `failOverServers`: *undefined*, the ability use these servers as failover when the dead server get's removed from the consistent hashing scheme. This must be an array of servers confirm the server_locations specification.
* `keyCompression`: *true*, compress keys using md5 if they exceed the maxKeySize option.
* `remove`: *false*, when the server is marked as dead you can remove it from
the pool so all other will receive the keys instead.
* `failOverServers`: *undefined*, the ability use these servers as failover when
the dead server get's removed from the consistent hashing scheme. This must be
an array of servers confirm the server_locations specification.
* `keyCompression`: *true*, compress keys using md5 if they exceed the
maxKeySize option.
Example usage:
``` js
```js
var memcached = new Memcached('localhost:11212', {retries:10,retry:10000,remove:true,failOverServers:['192.168.0.103:11212']});

@@ -82,3 +121,3 @@ ```

``` js
```js
var Memcached = require('memcached');

@@ -99,3 +138,4 @@ // all global configurations should be applied to the .config object of the Client.

#### .connect
Fetches or generates a connection for the given server. The supplied callback function will receive a reference to the connection as argument.
Fetches or generates a connection for the given server. The supplied callback
function will receive a reference to the connection as argument.
If there are issues with the server connection, we are going to respond with cache-miss pattern.

@@ -105,5 +145,7 @@

`server`: *String*, The server that needs a connection, the format must be confirm the server_locations specification.
`server`: *String*, The server that needs a connection, the format must be
confirm the server_locations specification.
`callback`: *Function*, The callback function that receives the net.Stream connection. It will be called with 2 arguments `error` and `connection`.
`callback`: *Function*, The callback function that receives the net.Stream
connection. It will be called with 2 arguments `error` and `connection`.

@@ -114,4 +156,4 @@ Example:

memcached.connect( '192.168.0.103:11212', function( err, conn ){
if( err ) throw new Error( err );
console.log( conn.server );
if( err ) throw new Error( err );
console.log( conn.server );
});

@@ -122,3 +164,5 @@ ```

#### .multi
A small wrapper function that makes it easier to query multiple Memcached servers. It will return the location for each key or the complete list of servers.
A small wrapper function that makes it easier to query multiple Memcached
servers. It will return the location for each key or the complete list of
servers.

@@ -129,8 +173,10 @@ **Arguments**

`callback`: *Function*, The callback function for the data, it will be called for **each** key. It will be called with 4 arguments:
`callback`: *Function*, The callback function for the data, it will be called
for **each** key. It will be called with 4 arguments:
1. `server`: *String*, The server location.
2. `key`: *String*, The key associated with the server, if you didn't specify keys, this variable will be undefined.
3. `index`: *Number*, The current index of the loop
4. `total`: *Number*, The total amount server retrieved.
1. `server`: *String*, The server location.
2. `key`: *String*, The key associated with the server, if you didn't specify
keys, this variable will be undefined.
3. `index`: *Number*, The current index of the loop
4. `total`: *Number*, The total amount server retrieved.

@@ -141,7 +187,7 @@ Example:

memcached.multi( false, function( server, key, index, totals ){
if( err ) throw new Error( err );
this.connect( server, function( err, conn ){
console.log( "connection ready" )
})
if( err ) throw new Error( err );
this.connect( server, function( err, conn ){
console.log( "connection ready" )
})
});

@@ -153,11 +199,15 @@ ```

This is the core functionality of the `memcached` client. All public API's are routed through this function. It takes care of the argument validations
Server retrieval ( If the server argument isn't specified ). After all data ready a connection is asked for the private `connect` method and the command
is written to the Memcached server.
This is the core functionality of the `memcached` client. All public API's are
routed through this function. It takes care of the argument validations Server
retrieval ( If the server argument isn't specified ). After all data ready a
connection is asked for the private `connect` method and the command is written
to the Memcached server.
**Arguments**
`query`: *Object*, The metaData object, see the `Callbacks` section for the specification.
`query`: *Object*, The metaData object, see the `Callbacks` section for the
specification.
`server`: *String*, The server the to connect. This is only needed when the metaData object doesn't contain a key property to retrieve the server from.
`server`: *String*, The server the to connect. This is only needed when the
metaData object doesn't contain a key property to retrieve the server from.

@@ -168,10 +218,10 @@ Example:

memcached.command({
key: 'key', callback: function(){ console.dir( arguments ); },
key: 'key', callback: function(){ console.dir( arguments ); },
// validate the arguments
validate: [[ 'key', String ], [ 'callback', Function ]],
// validate the arguments
validate: [[ 'key', String ], [ 'callback', Function ]],
// used for the query
type: 'delete',
command: 'delete key'
// used for the query
type: 'delete',
command: 'delete key'
});

@@ -183,4 +233,6 @@ ```

A internal function for logging issues with connections. As there can be various of ways that an error occurs we need solid issue manager to handle
all these cases. For example server could crash or the Memcached server could respond with `SERVER ERROR <broken>`.
A internal function for logging issues with connections. As there can be various
of ways that an error occurs we need solid issue manager to handle all these
cases. For example server could crash or the Memcached server could respond with
`SERVER ERROR <broken>`.

@@ -191,5 +243,7 @@ **Arguments**

`Stream`: *net.Stream*, A reference to the connection stream where the error occurred on.
`Stream`: *net.Stream*, A reference to the connection stream where the error
occurred on.
`callback`: *Function* **(optional)**, The callback function of a potential request, it will be marked as cache miss if it was provided
`callback`: *Function* **(optional)**, The callback function of a potential
request, it will be marked as cache miss if it was provided

@@ -204,8 +258,16 @@ Example:

Each method requires a callback function. Once this function get executed there will be 2 variables applied:
Each method requires a callback function. Once this function get executed there
will be 2 variables applied:
* `error`: A error response if something went wrong while retrieving data from the Memcached server. Depending on the type of request this will either be an string or an Array with multiple errors.
* `response`: The actual result from the Memcached server. If the response is `false` or `undefined` than a cache miss occurred. Cache misses will also occur when there is an error. So you might want to check on errors first.
* `error`: A error response if something went wrong while retrieving data from
the Memcached server. Depending on the type of request this will either be an
string or an Array with multiple errors.
* `response`: The actual result from the Memcached server. If the response is
`false` or `undefined` than a cache miss occurred. Cache misses will also
occur when there is an error. So you might want to check on errors first.
When we have a successful response, the context of the callback function will shift to a metaData object. The metaData object contains all information that we used to generate the request for the Memcached server. The metaData object contains the following properties:
When we have a successful response, the context of the callback function will
shift to a metaData object. The metaData object contains all information that we
used to generate the request for the Memcached server. The metaData object
contains the following properties:

@@ -219,31 +281,44 @@ * `start`: Date in milliseconds when the request was received

And all the arguments you have send to the method, this depends on the method you have called.
And all the arguments you have send to the method, this depends on the method
you have called.
## Events
When connection issues occur we send out different notifications using the `EventEmitter` protocol. This can be useful for logging, notification and debugging purposes. Each event will receive details Object containing detailed information about the issues that occurred.
When connection issues occur we send out different notifications using the
`EventEmitter` protocol. This can be useful for logging, notification and
debugging purposes. Each event will receive details Object containing detailed
information about the issues that occurred.
### Details Object
The details Object contains the various of error messages that caused, the following 3 will always be present in all error events:
The details Object contains the various of error messages that caused, the
following 3 will always be present in all error events:
* `server`: the server where the issue occurred on
* `tokens`: a array of the parsed server string in `[port, hostname]` format.
* `messages`: a array containing all error messages that this server received. As messages are added to the array using .push(), the first issue will at the beginning and the latest error at the end of the array.
* `messages`: a array containing all error messages that this server received.
As messages are added to the array using .push(), the first issue will at the
beginning and the latest error at the end of the array.
The following properties depend on the type of event that is send. If we are still in our retry phase the details will also contain:
The following properties depend on the type of event that is send. If we are
still in our retry phase the details will also contain:
* `retries`: the amount of retries left before we mark the server as dead.
* `totalRetries`: the total amount of retries we did on this server, as when the server has been reconnected after it's dead the `retries` will be rest to defaults and messages will be removed.
* `totalRetries`: the total amount of retries we did on this server, as when the
server has been reconnected after it's dead the `retries` will be rest to
defaults and messages will be removed.
If the server is dead these details will be added:
* `totalReconnectsAttempted`: the total reconnects we have attempted. This is the success and failure combined.
* `totalReconnectsAttempted`: the total reconnects we have attempted. This is
the success and failure combined.
* `totalReconnectsSuccess`: the total successful reconnects we have made.
* `totalReconnectsFailed`: the total failed reconnects we have made.
* `totalDownTime`: the total down time that was generated. Formula: ( totalReconnectsFailed * reconnect_timeout ) + ( totalRetries * retry_timeout).
* `totalDownTime`: the total down time that was generated. Formula: (
totalReconnectsFailed * reconnect_timeout ) + ( totalRetries * retry_timeout).
### Events
There are `5` different events that the `memcached` client emits when connection issues occur.
There are `5` different events that the `memcached` client emits when connection
issues occur.

@@ -258,3 +333,3 @@ * `issue`: a issue occurred on one a server, we are going to attempt a retry next.

``` js
```js
var memcached = new Memcached([ '192.168.0.102:11212', '192.168.0.103:11212' ]);

@@ -261,0 +336,0 @@ memcached.on('failure', function( details ){ sys.error( "Server " + details.server + "went down due to: " + details.messages.join( '' ) ) });

AUTHORS
tests/common.js
tests/fixtures/hotchicks.jpg
tests/fixtures/lipsum.txt
tests/memcached-add.test.js
tests/memcached-cas.test.js
tests/memcached-get-set.test.js
tests/memcached-incr-decr.test.js
CHANGELOG

Sorry, the diff of this file is not supported yet

Makefile

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

About

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc