koa-simple-session
v1.0.3
Published
koa session store by file, redis or others
Downloads
9
Readme
koa-simple-session
Session middleware for koa 2.x, easy use with reids, supports readonly session (use Object.freeze).
This middleware will only set a cookie when a session is manually set. Each time the session is modified (and only when the session is modified), it will reset the cookie and session.
Installation
$ npm install koa-simple-session
Examples
'use strict';
const Koa = require('koa');
const Redis = require('koa-simple-redis');
const session = require('koa-simple-session');
const app = new Koa();
function get(ctx) {
const session = ctx.session;
session.count = session.count || 0;
session.count++;
ctx.body = session.count;
}
function remove(ctx) {
ctx.session = null;
ctx.body = 0;
}
function regenerate(ctx) {
get(ctx);
return ctx.regenerateSession().then(() => {
get(ctx);
});
}
function freeze(ctx) {
// the session is not sync to redis
ctx.session.user = {
a: 'b'
};
Object.freeze(ctx.session);
ctx.body = ctx.session.user;
}
app.name = 'koa-session-test';
app.outputErrors = true;
app.keys = ['keys', 'keykeys'];
app.proxy = true;
app.use(session({
store: new Redis(),
}));
app.use(ctx => {
switch (ctx.path) {
case '/get':
get(ctx);
break;
case '/remove':
remove(ctx);
break;
case '/freeze':
freeze(ctx);
break;
case '/regenerate':
return regenerate(ctx);
}
});
app.listen(3000);
- After adding session middleware, you can use
this.session
to set or get the sessions. - Setting
this.session = null;
will destroy this session. - Altering
this.session.cookie
changes the cookie options of this user. Also you can use the cookie options in session the store. Use for examplecookie.maxAge
as the session store's ttl. - Calling
this.regenerateSession
will destroy any existing session and generate a new, empty one in its place. The new session will have a different ID.
Options
key
: cookie name defaulting tokoa.sid
prefix
: session prefix for store, defaulting tokoa:sess:
ttl
: ttl is for sessionStore's expiration time. it is different withcookie.maxAge
, default to null(means get ttl fromcookie.maxAge
).genSid
: default sid was generated by uid2, you can pass a function to replace itallowEmpty
: allow generation of empty sessionserrorHandler(err, type, ctx)
:Store.get
andStore.set
will throw in some situation, useerrorHandle
to handle these errors by yourself. Default will throw.reconnectTimeout
: When store is disconnected, don't throwstore unavailable
error immediately, waitreconnectTimeout
to reconnect, default is10s
.sessionIdStore
: object with get, set, reset methods for passing session id throw requests.valid
: valid(ctx, session), valid session value before use itbeforeSave
: beforeSave(ctx, session), hook before save sessionstore
: session store instance. It can be any Object that has the methodsset
,get
,destroy
cookie
: session cookie settings, defaulting to
{
httpOnly: true,
path: '/',
overwrite: true,
signed: true,
maxAge: 24 * 60 * 60 * 1000,
}
For a full list of cookie options see expressjs/cookies.
if you setcookie.maxAge
to 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.
Notice that ttl
is different from cookie.maxAge
, ttl
set the expire time of sessionStore. So if you set cookie.maxAge = null
, and ttl=ms('1d')
, the session will expired after one day, but the cookie will destroy when the user closes the browser.
And mostly you can just ignore options.ttl
, koa-simple-session
will parse cookie.maxAge
as the tll.
Hooks
valid()
: valid session value before use itbeforeSave()
: hook before save sessions
Session Store
You can use any other store to replace the default FileStore, it just needs to follow this api:
get(sid)
: get session object by sidset(sid, sess, ttl)
: set session object for sid, with a ttl (in ms)destroy(sid)
: destroy session for sid
the api needs to return a Promise.
And use these events to report the store's status.
connect
disconnect
License
MIT