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 express-session storage:
var session = ;var CloudantStore = session;// example for local instance of cloudant - required params// database 'sessions' needs to be created prior to usagevar store = url: 'https://MYUSERNAME:MYPASSWORD@MYACCOUNT.cloudant.com' ; store; store; store; app;
Standard usage for Bluemix (public) environment :
var store = instanceName: 'myCloudantServiceName' vcapServices: JSON ; app;
Using the session auto-clean feature
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;
Store Parameters
Bellow is an example of creating an instance with the full list of parameters (default values highlighted):
var store = // 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 ;
Parameters
url
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
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
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 = ;if svc store = url: svcurl ;
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.
disableTTLRefresh
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)
dbViewName
Name of the expired session view to be used for building the expired sessions list
dbDesignName
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.
dbRemoveExpMax
Limits the maximum amount of sessions to be bulk deleted per each store.cleanupExpired() call.
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 have UT associated with a good coverage
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
- https://hub.docker.com/r/ibmcom/cloudant-developer/
Attributions
- The connect-cloudant-store code is inspired from from other express-session storage libraries as: connect-redis.