node-session

NodeSession

Since HTTP driven applications are stateless, sessions provide a way to store information about the user across requests. NodeSession ships with a variety of session back-ends available for use through a clean, unified API. Support for back-ends such as File and databases is included out of the box.

• Installation
• Session Usage
• Configuration
• Flash Data
• CSRF Token
• Database Sessions
• Session Drivers

Installation

The source is available for download from GitHub. Alternatively, you can install using Node Package Manager (npm):

npm install node-session

Session Usage

Initialization

var NodeSession = require('node-session');

// init
session = new NodeSession({secret: 'Q3UBzdH9GEfiRCTKbi5MTPyChpzXLsTD'});

// start session for an http request - response
// this will define a session property to the request object
session.startSession(req, res, callback)

Accessing sessions

The session can be accessed via the HTTP request's session property.

Storing An Item In The Session

req.session.put('key', 'value');

Push A Value Onto An Array Session Value

req.session.push('user.teams', 'developers');

Retrieving An Item From The Session

var value = req.session.get('key');

Retrieving An Item Or Returning A Default Value

var value = req.session.get('key', 'default');

Retrieving An Item And Forgetting It

var value = req.session.pull('key', 'default');

Retrieving All Data From The Session

var data = req.session.all();

Determining If An Item Exists In The Session

if (req.session.has('users'))
{
    //
}

Removing An Item From The Session

req.session.forget('key');

Removing All Items From The Session

req.session.flush();

Regenerating The Session ID

req.session.regenerate();

Flash Data

Sometimes you may wish to store items in the session only for the next request. You may do so using the req.session.flash method:

req.session.flash('key', 'value');

Reflashing The Current Flash Data For Another Request

req.session.reflash();

Reflashing Only A Subset Of Flash Data

req.session.keep('username', 'email');

CSRF Token

By default NodeSession generates and keeps CSRF token for your application in session.

Access CSRF token

req.session.getToken()

Regenerate CSRF token

req.session.regenerateToken()

configuration

Configuration options are passed during initialization of NodeSession module as an object. NodeSession supports following configuration options.

{
    /*
    |--------------------------------------------------------------------------
    | Encryption secret
    |--------------------------------------------------------------------------
    |
    | This secret key is used by the NodeSession to encrypt session and sign cookies
    | etc. This should be set to a random, 32 character string, otherwise these
    | encrypted strings will not be safe.
    |
    */

    'secret': 'Q3UBzdH9GEfiRCTKbi5MTPyChpzXLsTD'

    /*
     |--------------------------------------------------------------------------
     | Default Session Driver
     |--------------------------------------------------------------------------
     |
     | This option controls the default session "driver" that will be used on
     | requests. By default, NodeSession will use the lightweight file driver but
     | you may specify any of the other wonderful drivers provided here.
     |
     | Supported: "memory", "file", "database"
     |
     */

    'driver': 'file',

    /*
     |--------------------------------------------------------------------------
     | Session Lifetime
     |--------------------------------------------------------------------------
     |
     | Here you may specify the number of milli seconds that you wish the session
     | to be allowed to remain idle before it expires. If you want them
     | to immediately expire on the browser closing, set that option.
     |
     | Default lifetime value: 300000
     | Default expireOnClose value: false
     |
     */

    'lifetime': 300000, // 5 minutes

    'expireOnClose': false,



    /*
     |--------------------------------------------------------------------------
     | Session File Location
     |--------------------------------------------------------------------------
     |
     | When using the file session driver, we need a location where session
     | files may be stored. By default NodeSession will use the location shown here
     | but a different location may be specified. This is only needed for
     | file sessions.
     |
     */

    'files': process.cwd() + '/sessions',

    /*
     |--------------------------------------------------------------------------
     | Session Database Connection
     |--------------------------------------------------------------------------
     |
     | When using the "database" session driver, you may specify a connection that
     | should be used to manage these sessions.
     |
     | NodeSession uses Nodejs Waterline module for database interactions, hence
     | it supports all databases supported by waterline. Before you specify a
     | waterline adapter with your connection make sure that you have installed
     | it in your application.
     |
     | For example before using sail-mong adapter
     | Run:
     | npm install sails-mongo
     |
     */

    'connection': {
        'adapter': 'sails-mongo',
        'host': 'localhost',
        'port': 27017,
        'user': 'tron',
        'password': '',
        'database': 'tron'
    },

    /*
     |--------------------------------------------------------------------------
     | Session Database Table
     |--------------------------------------------------------------------------
     |
     | When using the "database" session driver, you may specify the table we
     | should use to manage the sessions. Of course, NodeSession uses `sessions`
     | by default; however, you are free to change this as needed.
     |
     */

    'table': 'sessions',

    /*
     |--------------------------------------------------------------------------
     | Session Sweeping Lottery
     |--------------------------------------------------------------------------
     |
     | Some session drivers must manually sweep their storage location to get
     | rid of old sessions from storage. Here are the chances that it will
     | happen on a given request. By default, the odds are 2 out of 100.
     |
     */

    'lottery': [2, 100],

    /*
     |--------------------------------------------------------------------------
     | Session Cookie Name
     |--------------------------------------------------------------------------
     |
     | Here you may change the name of the cookie used to identify a session
     | instance by ID. The name specified here will get used every time a
     | new session cookie is created by the NodeSession for every driver.
     |
     | default: 'node_session'
     |
     */

    'cookie': 'node_session',

    /*
     |--------------------------------------------------------------------------
     | Session Cookie Path
     |--------------------------------------------------------------------------
     |
     | The session cookie path determines the path for which the cookie will
     | be regarded as available. Typically, this will be the root path of
     | your application but you are free to change this when necessary.
     |
     | default: '/'
     |
     */

    'path': '/',

    /*
     |--------------------------------------------------------------------------
     | Session Cookie Domain
     |--------------------------------------------------------------------------
     |
     | Here you may change the domain of the cookie used to identify a session
     | in your application. This will determine which domains the cookie is
     | available to in your application.
     |
     | default: null
     |
     */

    'domain': null,

    /*
     |--------------------------------------------------------------------------
     | HTTPS Only Cookies
     |--------------------------------------------------------------------------
     |
     | By setting this option to true, session cookies will only be sent back
     | to the server if the browser has a HTTPS connection. This will keep
     | the cookie from being sent to you if it can not be done securely.
     |
     | default: false
     |
     */

    'secure': false

    /**
    |-----------------------------------------------------------------------------
    | Encrypt session
    |-----------------------------------------------------------------------------
    |
    | If you need all stored session data to be encrypted, set the encrypt
    | configuration option to true.
    |
    | default: false
    |
    */

    'encrypt': false
}

The NodeSession uses the flash session key internally, so you should not add an item to the session by that name.

Database Sessions

When using the database session driver, you may need to setup a table to contain the session items based on database. Below is a required schema for the table:

filed	type	index
id	string	unique
payload	string
lastActivity	integer

Session Drivers

The session "driver" defines where session data will be stored for each request. NodeSession ships with several great drivers out of the box:

• memory - sessions will be stored in memory. Memory session driver is purposely not designed for a production environment. It will leak memory under most conditions, does not scale past a single process, and is meant for debugging and developing.
• file - sessions will be stored in files in a specified location.
• database - sessions will be stored in a database.

To do

• Add redis session driver

License

The NodeSession is open-sourced software licensed under the MIT license.