connect-datacache

NodeJS express-session storage for IBM Bluemix Data Cache service.

Setup

npm install connect-datacache

Using the DataCache storage connector:

var session = require('express-session');
var DataCacheStore = require('connect-datacache')(session);
 
app.use(session({
    store: new DataCacheStore(options),
    secret: 'keyboard cat'
}));

Standard usage for Bluemix environment/dev environment - with fallback on MemoryStore:

dcStore = null;
try { 
    // by default is looking into bluemix cfenv services
    dcStore = new DataCacheStore();
} catch (err) {
    // log fallback on memory store for no DataCache service linked to app
}
 
app.use(session({
    store: dcStore,
    secret: 'keyboard cat'
}));

Storage Options

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

var store = new DataCacheStore({
        // required parameters when no custom client provided or no ENV credentials are set
        restResource: 'http://dcsdomain.bluemix.net/resources/datacaches/{gridName}',
        restResourceSecure: 'https://dcsdomain.bluemix.net/resources/datacaches/{gridName}',
        gridName: '{gridName}',
        username: '{username}',
        password: '{password}',
        // optional parameters - default values
        mapName: '{gridName}',
        eviction: 'LUT',
        locking: 'optimistic',
        contentType: 'application/json',
        secure: true,
        ttl: 3600,
        prefix: 'sess:',
        cfServiceName: null,
        client: null
    }
);

Bluemix environment

The datacache client is looking first for DataCache service cfenv values. For the Bluemix NodeJS app with a DataCache service associated the required parameters are read from ENV variables (credentials):

Environment Variables > VCAP_SERVICES

{
    "system_env_json": {
      "VCAP_SERVICES": {
         "DataCache-dedicated": [
            {
               "credentials": {
                 "catalogEndPoint": "...",
                 "restResource": "http://ip-numeric/resources/datacaches/SYS_GENERATED_GRIDNAME",
                 "restResourceSecure": "https://sdomain.bluemix.net/resources/datacaches/SYS_GENERATED_GRIDNAME",
                 "gridName": "SYS_GENERATED_GRIDNAME",
                 "username": "SYS_GENERATED_USERNAME",
                 "password": "SYS_GENERATED_PASSWORD"
               },
               "name": "datacache-service-name",
               "tags": []
            }
         ]
      }
   },
}

restResources/restResourceSecure

defaults: VCAP_SERVICES credentials values

Depending on the "secure" value, one of them is required if not found in ENV variables by cfenv.

mapName

For a Bluemix application it is required to have the same value as for "gridName". A resource is identified with a complete URI as:

http://secure.domain/resources/datacaches/SYS_GENERATED_GRIDNAME/MAP_NAME.EVICTION.LOCK/SESSION_KEY

ex: https://ecaas3.w3ibm.bluemix.net/resources/datacaches/Ae7hjz7tQjuxF44ncLAvuQGH/Ae7hjz7tQjuxF44ncLAvuQGH.LUT.O/sess:t7OQGXZ3x8TNp269-lf-wsdnUBx5OcU6

For non-Bluemix environments it can be customized as a namespace for data.

eviction

'LUT' - default - expires based on the Last Update Time
'NONE' - data is stored indefinitly (until si programaticaly deleted)
'LAT' - expires based on Last Access Time

locking

'optimistic' - default
'pessimistic'

contentType

'application/json' - default - turns on the JSON encoder/decoder for session data
other - saves session data as plain text

secure

true - default - uses 'restResourceSecure' as store entrypoint
false - uses 'restResource' as store entrypoint

ttl

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

prefix

custom prefix to be appended for all session keys

cfServiceName

allows using multiple Data Cache services for same application - loads credentials from ENV using service name;

var store = new DataCacheStore({'cfenvServiceName': 'datacache-service-name'});

client

offers option to pass an instance of DataCacheClient or inteface matching object -> turns optional all the required parameters/credentials

Contributing

PR code needs to pass the lint check and unit test

npm test

PR code should be covered by UT

npm run coverage

Resources

Attributions

The connect-datacache code is based on implementation from other express-session storages as: connect-redis