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.
npm install connect-cloudant-store
Using the CloudantStore express-session storage:
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
var store = new CloudantStore(
{
url: 'https://MYUSERNAME:MYPASSWORD@MYACCOUNT.cloudant.com'
}
);
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 (public) environment :
var store = new CloudantStore(
{
instanceName: 'myCloudantServiceName',
vcapServices: JSON.parse(process.env.VCAP_SERVICES)
}
);
app.use(session({
store: store,
secret: 'keyboard cat'
}));
The storage class has a auto-clean specific method that has to be called in your code. It could be trigger for example from a setIterval timer. It checks if there is already a view available for getting the expired sessions from store db, and if not, is trying to create it. There are related optional parameters to customize the name of the view/design, set a top limit for items deleted per cleanup call.
store.on('connect', function() {
// set cleanup job every other hour
setInterval(function() { store.cleanupExpired(); }, 3600 * 1000);
});
Bellow is an example of creating an instance with the full list of parameters (default values highlighted):
var store = new CloudantStore({
// connector specific parameters
client: null, // new Cloudant(options)
database: 'sessions',
prefix: 'sess',
ttl: 86400,
disableTTLRefresh: false,
dbViewName: 'express_expired_sessions',
dbDesignName: 'expired_sessions',
dbRemoveExpMax: 100,
// Cloudant() parameters used if 'client' is not provided
url: undefined,
instanceName: undefined,
vcapServices: undefined,
}
);
Allows to create the Cloudant client based on the url (containing credentials)
ex:
https://MYUSERNAME:MYPASSWORD@MYACCOUNT.cloudant.com
Can be used for working on a dev environment (ex: docker cloudant-developer)
http://MYUSERNAME:MYPASSWORD@LOCALIP:LOCALPORT
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
Note: This will not work on Bluemix Dedicated because cloudant library is not searching by service name first, but instead by service type key first and second by service name (instanceName);
You can use directly a cfenv npm module to get a working Cloudant url by service name:
var svc = require('cfenv').getAppEnv().getServiceCreds('myCloudantServiceName');
if (svc) {
store = new CloudantStore(
{
url: svc.url
}
);
}
Offers the mechanism to inject an instance of Cloudant() module as the client -> replaces any of the Cloudant parameters above
session/storage time to live - overrides the session cookie maxAge value if present
Custom prefix to be appended for all session keys
Set a different database as the session database - needs to be created prior to the connector usage.
Disable the session storage TTL automatical refresh by disabling the "touch" method, in order to reduce the number of requests to Cloudant and the risk of conflicts. As a result the session will have a fixed duration from creation (of either the .ttl param or of the session.cookie.maxAge)
Name of the expired session view to be used for building the expired sessions list
Name of the couch db design name to be used for building the expired sessions list - if the design and the view is not found in the cloudant database, the first call to store.cleanupExpired() will try to create it.
Limits the maximum amount of sessions to be bulk deleted per each store.cleanupExpired() call.
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
PR code needs to pass the eslint check and unit test
npm test
PR code should have UT associated with a good coverage
npm run coverage
- 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
- https://hub.docker.com/r/ibmcom/cloudant-developer/
- The connect-cloudant-store code is inspired from from other express-session storage libraries as: connect-redis.