Simple session middleware for Koa. default is cookie-based session and support external store.
Requires Node 7.6 or greater for async/await support
$ npm install koa-session
View counter example:
const session = require('koa-session');
const Koa = require('koa');
const app = new Koa();
app.keys = ['some secret hurr'];
const CONFIG = {
key: 'koa:sess', /** (string) cookie key (default is koa:sess) */
/** (number || 'session') maxAge in ms (default is 1 days) */
/** 'session' will result in a cookie that expires when session/browser is closed */
/** Warning: If a session cookie is stolen, this cookie will never expire */
maxAge: 86400000,
overwrite: true, /** (boolean) can overwrite or not (default true) */
httpOnly: true, /** (boolean) httpOnly or not (default true) */
signed: true, /** (boolean) signed or not (default true) */
};
app.use(session(CONFIG, app));
// or if you prefer all default config, just use => app.use(session(app));
app.use(ctx => {
// ignore favicon
if (ctx.path === '/favicon.ico') return;
let n = ctx.session.views || 0;
ctx.session.views = ++n;
ctx.body = n + ' views';
});
app.listen(3000);
console.log('listening on port 3000');
The cookie name is controlled by the key
option, which defaults
to "koa:sess". All other options are passed to ctx.cookies.get()
and
ctx.cookies.set()
allowing you to control security, domain, path,
and signing among other settings.
Use options.encode
and options.decode
to customize your own encode/decode methods.
valid()
: valid session value before use itbeforeSave()
: hook before save session
Session will store in cookie by default, but it has some disadvantages:
- Session stored in client side unencrypted.
- Browser cookie always have length limit.
You can store the session content in external stores(redis, mongodb or other DBs) by pass options.store
with three methods(need to be async function):
get(key)
: get session object by keyset(key, sess, maxAge)
: set session object for key, with amaxAge
(in ms)destroy(key)
: destroy session for key
Once you passed options.store
, session is strong dependent on your external store, you can't access session if your external store is down. Use external session stores only if necessary, avoid use session as a cache, keep session lean and stored by cookie!
Returns true if the session is new.
if (this.session.isNew) {
// user has not logged in
} else {
// user has already logged in
}
Get cookie's maxAge.
Set cookie's maxAge.
Save this session no matter whether it is populated.
To destroy a session simply set it to null
:
this.session = null;
MIT