koa-session
Simple session middleware for Koa. Defaults to cookie-based sessions and supports external stores.
Requires Node 7.6 or greater for async/await support
Installation
$ npm install koa-session
Example
View counter example:
const session = ;const Koa = ;const app = ; appkeys = '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) */ rolling: false /** (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 is false) */ renew: false /** (boolean) renew session when session is nearly expired, so we can always keep user logged in. (default is false)*/; app;// or if you prefer all default config, just use => app.use(session(app)); app; app;console;
API
Options
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.
encode/decode
Support
Custom Use options.encode
and options.decode
to customize your own encode/decode methods.
Hooks
valid()
: valid session value before use itbeforeSave()
: hook before save session
External Session Stores
The session is stored in a cookie by default, but it has some disadvantages:
- Session is stored on client side unencrypted
- Browser cookies always have length limits
You can store the session content in external stores (Redis, MongoDB or other DBs) by passing options.store
with three methods (these need to be async functions):
get(key, maxAge, { rolling })
: get session object by keyset(key, sess, maxAge, { rolling, changed })
: set session object for key, with amaxAge
(in ms)destroy(key)
: destroy session for key
Once you pass options.store
, session storage is dependent on your external store -- you can't access the session if your external store is down. Use external session stores only if necessary, avoid uisng session as a cache, keep the session lean, and store it in a cookie if possible!
The way of generating external session id is controlled by the options.genid
, which defaults to Date.now() + '-' + uid.sync(24)
.
If you want to add prefix for all external session id, you can use options.prefix
, it will not work if options.genid
present.
If your session store requires data or utilities from context, opts.ContextStore
is alse supported. ContextStore
must be a class which claims three instance methods demonstrated above. new ContextStore(ctx)
will be executed on every request.
Events
koa-session
will emit event on app
when session expired or invalid:
session:missed
: can't get session value from external store.session:invalid
: session value is invalid.session:expired
: session value is expired.
Session#isNew
Returns true if the session is new.
if thissessionisNew // user has not logged in else // user has already logged in
Session#maxAge
Get cookie's maxAge.
Session#maxAge=
Set cookie's maxAge.
Session#save()
Save this session no matter whether it is populated.
Destroying a session
To destroy a session simply set it to null
:
thissession = null;
License
MIT