koa-session

What is koa-session?

koa-session is a session middleware for Koa, a popular web framework for Node.js. It provides a way to manage user sessions, including storing session data, setting session cookies, and handling session expiration.

What are koa-session's main functionalities?

Basic Session Setup

This code sets up a basic Koa application with session management. It configures the session middleware with various options like cookie key, max age, and httpOnly flag. The middleware is then used to track the number of views for each session.

const Koa = require('koa');
const session = require('koa-session');
const app = new Koa();

app.keys = ['some secret hurr'];
const CONFIG = {
  key: 'koa:sess', // cookie key (default is koa:sess)
  maxAge: 86400000, // cookie's max age in ms (1 day)
  autoCommit: true, // automatically commit headers (default true)
  overwrite: true, // can overwrite or not (default true)
  httpOnly: true, // httpOnly or not (default true)
  signed: true, // signed or not (default true)
  rolling: false, // Force a session identifier cookie to be set on every response. The expiration is reset to the original maxAge, resetting the expiration countdown.
  renew: false, // renew session when session is nearly expired, so we can always keep user logged in.
};

app.use(session(CONFIG, app));

app.use(ctx => {
  if (ctx.path === '/favicon.ico') return;
  let n = ctx.session.views || 0;
  ctx.session.views = ++n;
  ctx.body = n + ' views';
});

app.listen(3000);

Custom Session Store

This code demonstrates how to use a custom session store with koa-session. The custom store is implemented using a simple in-memory Map. The store object provides methods for getting, setting, and destroying session data.

const Koa = require('koa');
const session = require('koa-session');
const app = new Koa();

app.keys = ['some secret hurr'];

const store = {
  storage: new Map(),
  get(key) {
    return this.storage.get(key);
  },
  set(key, sess) {
    this.storage.set(key, sess);
  },
  destroy(key) {
    this.storage.delete(key);
  }
};

const CONFIG = {
  store,
};

app.use(session(CONFIG, app));

app.use(ctx => {
  if (ctx.path === '/favicon.ico') return;
  let n = ctx.session.views || 0;
  ctx.session.views = ++n;
  ctx.body = n + ' views';
});

app.listen(3000);

Session Regeneration

This code shows how to regenerate a session in koa-session. When the user accesses the '/regenerate' path, the session is regenerated, which can be useful for security purposes, such as after a user logs in.

const Koa = require('koa');
const session = require('koa-session');
const app = new Koa();

app.keys = ['some secret hurr'];
const CONFIG = {};

app.use(session(CONFIG, app));

app.use(async ctx => {
  if (ctx.path === '/favicon.ico') return;
  if (ctx.path === '/regenerate') {
    await ctx.regenerateSession();
    ctx.body = 'Session regenerated';
  } else {
    let n = ctx.session.views || 0;
    ctx.session.views = ++n;
    ctx.body = n + ' views';
  }
});

app.listen(3000);

Other packages similar to koa-session

express-session

express-session is a session middleware for Express, another popular web framework for Node.js. It provides similar functionalities to koa-session, such as session storage, cookie management, and session expiration. However, it is designed to work with Express rather than Koa.

cookie-session

cookie-session is a lightweight session middleware that stores session data in cookies rather than on the server. This can be useful for small session data and simplifies the setup by not requiring a session store. It works with both Koa and Express.

koa-generic-session

koa-generic-session is another session middleware for Koa. It provides more flexibility and customization options compared to koa-session, such as support for different session stores and more advanced session management features.

README

koa-session

Simple cookie-based session middleware for Koa.

Installation

$ npm install koa-session

Example

View counter example:

var session = require('koa-session');
var koa = require('koa');
var app = koa();

app.use(session());

app.use(function(next){
  return function *(){
    var n = this.session.views || 0;
    this.session.views = ++n;
    this.session.save();
    this.body = n + ' views';
  }
})

app.listen(3000);
console.log('listening on port 3000');

Semantics

This module provides "guest" sessions, meaning any visitor will have a session, authenticated or not. If a session is new a Set-Cookie will be produced regardless of populating the session.

API

Options

The cookie name is controlled by the key option, which defaults to "koa:sess". All other options are passed to ctx.cookie.get() and ctx.cookie.set() allowing you to control security, domain, path, and signing among other settings.

Session#save()

To commit changes to a session you must explicitly invoke this.session.save(), which performs the Set-Cookie.

Session#sid

15-byte session-unique identifier.

License

MIT