express-session

What is express-session?

The express-session npm package is a middleware for Express applications that enables server-side session management. It allows you to store and access user data as they interact with your web application. The package creates a session ID for each client and uses it to store data across multiple HTTP requests.

What are express-session's main functionalities?

Session Initialization

This code initializes the express-session middleware with a secret to sign the session ID cookie, and configuration options such as 'resave', 'saveUninitialized', and 'cookie' settings.

const express = require('express');
const session = require('express-session');

const app = express();

app.use(session({
  secret: 'keyboard cat',
  resave: false,
  saveUninitialized: true,
  cookie: { secure: true }
}));

Storing Session Data

This code demonstrates how to store data in the session object. The value 'This is saved in session' is stored under the key 'myValue' in the session.

app.use(session({ /* ... */ }));

app.get('/save', function(req, res) {
  // Save a value to the session
  req.session.myValue = 'This is saved in session';
  res.send('Session value stored.');
});

Retrieving Session Data

This code shows how to retrieve data from the session. It accesses the value stored under the key 'myValue' and sends it in the HTTP response.

app.get('/retrieve', function(req, res) {
  // Retrieve a value from the session
  const myValue = req.session.myValue;
  res.send(`Session value: ${myValue}`);
});

Destroying a Session

This code provides an example of how to destroy a session, effectively logging out the user. It handles any errors that might occur during the destruction process.

app.get('/logout', function(req, res) {
  // Destroy the session
  req.session.destroy(function(err) {
    if(err) {
      return res.send('Error destroying session');
    }
    res.send('Session destroyed');
  });
});

Other packages similar to express-session

cookie-session

The cookie-session package is similar to express-session but stores the session data directly in a cookie on the client-side, rather than on the server. This can be simpler and more scalable for some applications, but it is less secure and has limitations on the amount of data you can store.

connect-redis

Connect-redis is a Redis session store for the express-session package. It requires express-session to be installed and configured, but it uses Redis to store session data, which can be more performant and scalable for applications with a high number of sessions.

connect-mongo

Connect-mongo is a MongoDB session store for the express-session package. Similar to connect-redis, it leverages MongoDB to store session data, providing a scalable and performant solution for managing sessions in Express applications.

README

THIS REPOSITORY NEEDS A MAINTAINER. IF YOU'RE INTERESTED IN MAINTAINING THIS REPOSITORY, PLEASE LET US KNOW!

express-session

API

var express      = require('express')
var cookieParser = require('cookie-parser')
var session      = require('express-session')

var app = express()

app.use(cookieParser()) // required before session.
app.use(session({
    secret: 'keyboard cat'
  , proxy: true // if you do SSL outside of node.
}))

session(options)

Setup session store with the given options.

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

Options

• name - cookie name (formerly known as key). (default: 'connect.sid')
• store - session store instance.
• secret - session cookie is signed with this secret to prevent tampering.
• proxy - trust the reverse proxy when setting secure cookies (via "x-forwarded-proto"). (default: false)
• cookie - session cookie settings.
  • (default: { path: '/', httpOnly: true, secure: false, maxAge: null })
• rolling - forces a cookie set on every response. This resets the expiration date. (default: false)
• resave - forces session to be saved even when unmodified. (default: true)

Cookie options

Please note that secure: true is a recommended option. However, it requires an https-enabled website, i.e., HTTPS is necessary for secure cookies. If secure is set, and you access your site over HTTP, the cookie will not be set. If you have your node.js behind a proxy and are using secure: true, you need to enable the proxy option:

app.use(cookieParser())
app.use(session({
    secret: 'keyboard cat'
  , proxy: true // if you do SSL outside of node.
  , cookie: { secure: true }
}))

By default cookie.maxAge is null, meaning no "expires" parameter is set so the cookie becomes a browser-session cookie. When the user closes the browser the cookie (and session) will be removed.

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:

app.use(cookieParser())
app.use(session({ secret: 'keyboard cat', cookie: { maxAge: 60000 }}))

app.use(function(req, res, next) {
  var sess = req.session
  if (sess.views) {
    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()
  } else {
    sess.views = 1
    res.end('welcome to the session demo. refresh!')
  }
})

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()

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

Session.touch()

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

req.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.

Cookie.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 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.