# Session : Web session

Since HTTP is a stateless protocol, when the server needs to record the state of the user, it needs to use session to identify the specific user.

The session is stored on the server and has a unique identifier. The server records the session ID in the cookie in the HTTP protocol, and the cookie implements the session tracking.

User can use the following code to import the Session module.

var session = require("middleware").session;

# Support

The following shows Session module APIs available for each permissions.

# Session Class

# Session(options)

• options {Object} Options to session.

Create a session middleware with the given options.

Session accepts these properties in the options object. Properties as follow:

# cookie

• {Object} Settings object for the session ID cookie. default:{ path: '/', httpOnly: true, secure: false, maxAge: null }.

The following are options that can be set in this object.

• cookie.domain

  • {string} Specifies the value for the Domain Set-Cookie attribute. By default, no domain is set, and most clients will consider the cookie to apply to only the current domain.

• cookie.expires

  • {Date} Specifies the Date object to be the value for the Expires Set-Cookie attribute. By default, no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application.
  NOTICE:

  If both expires and maxAge are set in the options, then the last one defined in the object is what is used.

  The expires option should not be set directly; instead only use the maxAgeoption.

• cookie.httpOnly

  • {Boolean} Specifies the boolean value for the HttpOnly Set-Cookie attribute. When truthy, the HttpOnly attribute is set, otherwise it is not.By default, the HttpOnlyattribute is set.
  NOTICE:

  Be careful when setting this to true, as compliant clients will not allow client-side JavaScript to see the cookie in document.cookie.

• cookie.maxAge

  • {Integer} Specifies the number (in milliseconds) to use when calculating the Expires Set-Cookie attribute. This is done by taking the current server time and adding maxAge milliseconds to the value to calculate an Expires datetime. By default,no maximum age is set.
  NOTICE:

  If both expires and maxAge are set in the options, then the last one defined in the object is what is used.

• cookie.path

  • {String} Specifies the value for the Path Set-Cookie. By default, this is set to '/', which is the root path of the domain.

• cookie.sameSite

  • {Boolean | String} Specifies the boolean or string to be the value for the SameSite Set-Cookie attribute.
    • true will set the SameSite attribute to Strict for strict same site enforcement.
    • false will not set the SameSite attribute.
    • 'lax' will set the SameSite attribute to Lax for lax same site enforcement.
    • 'strict' will set the SameSite attribute to Strict for strict same site enforcement.

  More information about the different enforcement levels can be found in the specification https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1.1open in new window.

  NOTICE:

  This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.

• cookie.secure

  • {Boolean} Specifies the boolean value for the Secure Set-Cookie attribute. When truthy, the Secure attribute is set, otherwise it is not. By default, the Secure attribute is not set.
  NOTICE:

  Be careful when setting this to true, as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection.

  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.

  The cookie.secure option can also be set to the special value 'auto' to have this setting automatically match the determined security of the connection. Be careful when using this setting if the site is available both as HTTP and HTTPS, as once the cookie is set on HTTPS, it will no longer be visible over HTTP.

# genid

• {Function} Function to call to generate a new session ID. Provide a function that returns a string that will be used as a session ID. The function is given req as the first argument if you want to use some value attached to req when generating the ID. default: internal uid module

app.use(session({
  genid: function(req) {
    return genuuid(); // use UUIDs for session IDs
  },
  secret: 'keyboard cat';
}));

# name

• {String} The name of the session ID cookie to set in the response (and read from in the request). default: 'connect.sid'

# resave

• {Boolean} Forces the session to be saved back to the session store, even if the session was never modified during the request. default: true

Depending on your store this may be necessary, but it can also create race conditions where a client makes two parallel requests to your server and changes made to the session in one request may get overwritten when the other request ends, even if it made no changes (this behavior also depends on what store you're using).

The default value is true, but using the default has been deprecated, as the default will change in the future. How do I know if this is necessary for my store? The best way to know is to check with your store if it implements the touch method. If it does, then you can safely set resave: false. If it does not implement the touch method and your store sets an expiration date on stored sessions, then you likely need resave: true.

# rolling

• {Boolean} Force a session identifier cookie to be set on every response. The expiration is reset to the original maxAge, resetting the expiration countdown. default: false

# saveUninitialized

• {Boolean} Forces a session that is "uninitialized" to be saved to the store. default: true

A session is uninitialized when it is new but not modified. Choosing false is useful for implementing login sessions, reducing server storage usage, or complying with laws that require permission before setting a cookie. Choosing false will also help with race conditions where a client makes multiple parallel requests without a session.

The default value is true, but using the default has been deprecated, as the default will change in the future.

# secret

• {String | Array} This is the secret used to sign the session ID cookie. Required option

This can be either a string for a single secret, or an array of multiple secrets. If an array of secrets is provided, only the first element will be used to sign the session ID cookie, while all the elements will be considered when verifying the signature in requests.

# store

• {Object} The session store instance, default: MemoryStore instance

# unset

• {String} Control the result of unsetting req.session (through delete, setting to null, etc.). default: 'keep'. Unset option as follow:
  • 'destroy' The session will be destroyed (deleted) when the response ends.
  • 'keep' The session in the store will be kept, but modifications made during the request are ignored and not saved.

# Request Object

# req.session

• {Session} Session object.

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.

# Example

Below is a user-specific view counter:

// Use the session middleware
app.use(session({ secret: "keyboard cat", cookie: { maxAge: 60000 } }));

// Access the session as req.session
app.get("/", function(req, res, next) {
  if (req.session.views) {
    req.session.views++;
    res.setHeader("Content-Type", "text/html");
    res.write("<p>views: " + req.session.views + "</p>");
    res.write("<p>expires in: " + req.session.cookie.maxAge / 1000 + "s</p>");
    res.end();
  } else {
    req.session.views = 1;
    res.end("welcome to the session demo. refresh!");
  }
});

# req.sessionID

• {String} Session id.

To get the ID of the loaded session, access the request property req.sessionID. This is simply a read-only value set when a session is loaded/created.

# Session Object

# session.id

• {String} Session id.

Each session has a unique ID associated with it. This property is an alias of req.sessionID and cannot be modified. It has been added to make the session ID accessible from the session object.

# session.cookie

• {Cookie} Cookie object.

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

# session.regenerate(callback)

• callback {Function} Regenerate the session callback, accepting an error.
  • error {Error} Error object.

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

# Example

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

# session.destroy(callback)

• callback {Function} Destroys the session callback, accepting an error.
  • error {Error} Error object.

Destroys the session and will unset the req.session property. Once complete, the callback will be invoked.

# Example

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

# session.reload(callback)

• callback {Function} Reloads the session callback, accepting an error.
  • error {Error} Error object.

Reloads the session data from the store and re-populates the req.session object. Once complete, the callback will be invoked.

# Example

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

# session.save(callback)

• callback {Function} Save the session callback, accepting an error.
  • error {Error} Error object.

Save the session back to the store, replacing the contents on the store with the contents in memory (though a store may do something else--consult the store's documentation for exact behavior).

This method is automatically called at the end of the HTTP response if the session data has been altered (though this behavior can be altered with various options in the middleware constructor). Because of this, typically this method does not need to be called.

# Example

There are some cases where it is useful to call this method, for example, redirects, long-lived requests or in WebSockets.

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.

# Cookie Object

# Cookie.maxAge

• {Integer} Alternatively cookie.maxAge will return the time remaining in milliseconds, which we may also re-assign a new value to adjust the expires property appropriately.

# Example

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.cookie.maxAge to its original value.

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

# Cookie.originalMaxAge

• {Integer} The original maxAge (time-to-live), in milliseconds, of the session cookie.

# Store Object Interface

Every session store must be an EventEmitter and implement specific methods. The following methods are the list of required, recommended, and optional.

• Required methods are ones that this module will always call on the store.
• Recommended methods are ones that this module will call on the store if available.
• Optional methods are ones this module does not call at all, but helps present uniform stores to users.

# store.all(callback)

• callback {Function} Arguments:
  • error {Error} Error object.
  • sessions {Array} Session object array.

Optional

This optional method is used to get all sessions in the store as an array.

# store.destroy(sid, callback)

• sid {String} Session id.
• callback {Function} Arguments:
  • error {Error} Error object.

Required

This required method is used to destroy/delete a session from the store given a session ID (sid). The callback should be called as callback(error) once the session is destroyed.

# store.clear(callback)

• callback {Function} Arguments:
  • error {Error} Error object.

Optional

This optional method is used to delete all sessions from the store. The callback should be called ascallback(error) once the store is cleared.

# store.length(callback)

• callback {Function} Arguments:
  • error {Error} Error object.
  • len {Integer} the count of all sessions in the store.

Optional

This optional method is used to get the count of all sessions in the store. The callback should be called as callback(error, len).

# store.get(sid, callback)

• sid {String} Session id.
• callback {Function} Arguments:
  • error {Error} Error object.
  • session {Session} Session object.

Required

This required method is used to get a session from the store given a session ID (sid). The callback should be called as callback(error, session).

The session argument should be a session if found, otherwise null or undefined if the session was not found (and there was no error). A special case is made when error.code === 'ENOENT' to act like callback(null, null).

# store.set(sid, session, callback)

• sid {String} Session id.
• session {Session} Session object.
• callback {Function} Arguments:
  • error {Error} Error object.

Required

This required method is used to upsert a session into the store given a session ID (sid) and session (session) object. The callback should be called as callback(error) once the session has been set in the store.

# store.touch(sid, session, callback)

• sid {String} Session id.
• session {Session} Session object.
• callback {Function} Arguments:
  • error {Error} Error object.

Recommended

This recommended method is used to touch a given session given a session ID (sid) and session (session) object. The callback should be called as callback(error) once the session has been touched.

This is primarily used when the store will automatically delete idle sessions and this method is used to signal to the store the given session is active, potentially resetting the idle timer.

# MemoryStore Class

The default server-side session storage, MemoryStore, 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.

# SqliteStore Class

SqliteStore is a implement of sqlite3 Store.

# SQLiteStore(options)

• options {Object} Initialize SQLiteStore with the given options.
  • table {String} Table name of store. default: 'sessions.db'
  • db {String} Database name of store. default: same as table
  • dir {String} Directory to database. default: '.'
  • concurrentDb {Boolean} Use in concurrent connection, the table journal*mode will be set :wal. default: false

# Example

A simple example using Session to store page views for a user.

var socket = require("socket");
var WebApp = require("webapp");
var iosched = require("iosched");
var session = require("middleware").session;

// Create app.
var app = WebApp.create("app", 0, socket.sockaddr(socket.INADDR_ANY, 8000));

app.use(
  session({
    secret: "keyboard cat",
    resave: false,
    saveUninitialized: true,
    cookie: {
      maxAge: 24 * 3600 * 1000,
    },
    store: new session.SqliteStore(),
  })
);

app.use(function(req, res, next) {
  if (!req.session.views) {
    req.session.views = {};
  }

  // count the views
  var pathname = req.url;
  req.session.views[pathname] = (req.session.views[pathname] || 0) + 1;

  next();
});

app.get("/foo", function(req, res, next) {
  res.send("you viewed this page " + req.session.views["/foo"] + " times");
});

app.get("/bar", function(req, res, next) {
  res.send("you viewed this page " + req.session.views["/bar"] + " times");
});

// Start app.
app.start();

// Event loop.
while (true) {
  iosched.poll();
}