Nitro Powered Motorcycles

    connect-datacache

    1.1.0 • Public • Published

    connect-datacache

    NPM Version NPM Downloads Build Status

    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

    Install

    npm i connect-datacache

    DownloadsWeekly Downloads

    17

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • adriantanasa