connect-cloudant-store

connect-cloudant-store

NodeJS express-session storage connector for IBM Cloudant. The module is build on top of the cloudant npm module with promises plugin - the official Node JS Cloudant library.

Setup

npm install connect-cloudant-store

Using the CloudantStore session storage connector:

var session = require('express-session');
var CloudantStore = require('connect-cloudant-store')(session);
// example for local instance of cloudant - required params
// database 'sessions' needs to be created prior to usage
store = new CloudantStore(
    {
        url: 'https://MYUSERNAME:[e-mail]'
    }
);

store.on('connect', function() {
     // Cloudant Session store is ready for use
});

store.on('disconnect', function() {
    // failed to connect to cloudant db - by default falls back to MemoryStore
});

store.on('error', function(err) {
    // You can log the store errors to your app log
});

app.use(session({
    store: store,
    secret: 'keyboard cat'
}));

Standard usage for Bluemix environment/dev environment :

store = new CloudantStore(
    {
        instanceName: 'cloudant_service_name', 
        vcapServices: JSON.parse(process.env.VCAP_SERVICES)
    }
);

app.use(session({
    store: store,
    secret: 'keyboard cat'
}));

Store Parameters

Bellow is an example with the full list of parameters - with default values:

var store = new CloudantStore({
        // connector specific parameters
        client: null, // new Cloudant(options)
        database: 'sessions',
        prefix: 'sess',
        ttl: 86400,
        disableTTLRefresh: false,
        // Cloudant() parameters used if 'client' is not provided
        url: undefined,
        instanceName: undefined,
        vcapServices: undefined,
    }
);

Parameters

url

Allows to create the Cloudant client based on the url

ex: https://MYUSERNAME:[e-mail]

Can be used for working on dev environment

http://MYUSERNAME:MYPASSWORD@LOCALIP:LOCALPORT

vcapServices && instanceName

Allows to create the Cloudant client based on vcapServices JSON entry for your application and the name of the instance.

See: https://github.com/cloudant/nodejs-cloudant#initialization

client

Offers the mechanism to inject an instance of Cloudant() module as the client -> replaces any of the Cloudant parameters above

ttl

session/storage time to live - overrides the session cookie maxAge value if present

prefix

Custom prefix to be appended for all session keys

database

Set a different database as the session database - needs to be created prior to the connector usage.

Debugging

Local development

export DEBUG=connect:cloudant-store
# then run your Node.js application
npm start

For Bluemix - use the manifest.yml file to inject the ENV variable:

# ...
env:
    DEBUG: connect:cloudant-store
  services:
  - my-cloudant-service

Contributing

PR code needs to pass the eslint check and unit test

npm test

PR code should be covered by UT

npm run coverage

Resources

• https://cloudant.com/
• https://console.ng.bluemix.net/catalog/services/cloudant-nosql-db/
• https://github.com/cloudant/nodejs-cloudant
• https://www.npmjs.com/package/express-session

Attributions

• The connect-cloudant-store code is extendedn from from other express-session storage libraries as: connect-redis