session

Session data is not saved in the cookie itself, however cookies are used, so we must use the cookieParser() middleware before session().

Examples

connect.createServer(
    connect.cookieParser()
  , connect.session({ secret: 'keyboard cat' })
);

Options

• key cookie name defaulting to connect.sid
• store Session store instance
• fingerprint Custom fingerprint generating function
• cookie Session cookie settings, defaulting to { path: '/', httpOnly: true, maxAge: 14400000 }
• secret Secret string used to compute hash

Ignore Paths

By default /favicon.ico is the only ignored path, all others will utilize sessions, to manipulate the paths ignored, use connect.session.ignore.push('/my/path'). This works for full pathnames only, not segments nor substrings.

connect.session.ignore.push('/robots.txt');

req.session

To store or access session data, simply use the request property req.session, which is (generally) serialized as JSON by the store, so nested objects are typically fine. For example below is a user-specific view counter:

  connect(
      connect.cookieParser()
    , connect.session({ secret: 'keyboard cat', cookie: { maxAge: 60000 }})
    , connect.favicon()
    , function(req, res, next){
      var sess = req.session;
      if (sess.views) {
        res.setHeader('Content-Type', 'text/html');
        res.write('<p>views: ' + sess.views + '</p>');
        res.write('<p>expires in: ' + (sess.cookie.maxAge / 1000) + 's</p>');
        res.end();
        sess.views++;
      } else {
        sess.views = 1;
        res.end('welcome to the session demo. refresh!');
      }
    }
  ).listen(3000);

Session#regenerate()

To regenerate the session simply invoke the method, once complete a new SID and Session instance will be initialized at req.session.

 req.session.regenerate(function(err){
   // will have a new session here
 });

Session#destroy()

Destroys the session, removing req.session, will be re-generated next request.

 req.session.destroy(function(err){
   // cannot access session here
 });

Session#reload()

Reloads the session data.

 req.session.reload(function(err){
   // session updated
 });

Session#save()

Save the session.

 req.session.save(function(err){
   // session saved
 });

Session#touch()

Updates the .maxAge, and .lastAccess properties. Typically this is not necessary to call, as the session middleware does this for you.

Session#cookie

Each session has a unique cookie object accompany it. This allows you to alter the session cookie per visitor. For example we can set req.session.cookie.expires to false to enable the cookie to remain for only the duration of the user-agent.

Session#maxAge

Alternatively req.session.cookie.maxAge will return the time remaining in milliseconds, which we may also re-assign a new value to adjust the .expires property appropriately. The following are essentially equivalent

var hour = 3600000;
req.session.cookie.expires = new Date(Date.now() + hour);
req.session.cookie.maxAge = hour;

For example when maxAge is set to 60000 (one minute), and 30 seconds has elapsed it will return 30000 until the current request has completed, at which time req.session.touch() is called to update req.session.lastAccess, and reset req.session.maxAge to its original value.

req.session.cookie.maxAge;
// => 30000

Session Store Implementation

Every session store must implement the following methods

• .get(sid, callback)
• .set(sid, session, callback)
• .destroy(sid, callback)

Recommended methods include, but are not limited to:

• .length(callback)
• .clear(callback)

For an example implementation view the connect-redis repo.