• Stars
    star
    902
  • Rank 50,637 (Top 1.0 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created about 11 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Simple session middleware for koa

koa-session

NPM version Node.js CI npm download

Simple session middleware for Koa. Defaults to cookie-based sessions and supports external stores.

Requires Node 8.0.0 or greater for async/await support

Installation

$ npm install koa-session

Notice

6.x changed the default cookie key from koa:sess to koa.sess to ensure set-cookie value valid with HTTP spec.see issue. If you want to be compatible with the previous version, you can manually set config.key to koa:sess.

Example

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,
  autoCommit: true, /** (boolean) automatically commit headers (default true) */
  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)*/
  secure: true, /** (boolean) secure cookie*/
  sameSite: null, /** (string) session cookie sameSite options (default null, don't set it) */
};

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');

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.

Custom encode/decode Support

Use options.encode and options.decode to customize your own encode/decode methods.

Hooks

  • valid(): valid session value before use it
  • beforeSave(): hook before save session

External Session Stores

The session is stored in a cookie by default, but it has some disadvantages:

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, ctx }): get session object by key
  • set(key, sess, maxAge, { rolling, changed, ctx }): set session object for key, with a maxAge (in ms)
  • destroy(key, {ctx}): 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 using 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(ctx), which defaults to uuid.v4().

If you want to add prefix for all external session id, you can use options.prefix, it will not work if options.genid(ctx) present.

If your session store requires data or utilities from context, opts.ContextStore is also 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.

Custom External Key

External key is used the cookie by default, but you can use options.externalKey to customize your own external key methods. options.externalKey with two methods:

  • get(ctx): get the external key
  • set(ctx, value): set the external key

Session#isNew

Returns true if the session is new.

if (this.session.isNew) {
  // user has not logged in
} else {
  // user has already logged in
}

Session#maxAge

Get cookie's maxAge.

Session#maxAge=

Set cookie's maxAge.

Session#externalKey

Get session external key, only exist when external session store present.

Session#save()

Save this session no matter whether it is populated.

Session#manuallyCommit()

Session headers are auto committed by default. Use this if autoCommit is set to false.

Destroying a session

To destroy a session simply set it to null:

this.session = null;

License

MIT

More Repositories

1

koa

Expressive middleware for node.js using ES2017 async functions
JavaScript
34,326
star
2

examples

Example Koa apps
JavaScript
4,471
star
3

jwt

Koa middleware for validating JSON Web Tokens
JavaScript
1,333
star
4

bodyparser

Koa body parsing middleware
TypeScript
1,273
star
5

static

Static file server middleware
JavaScript
1,124
star
6

compose

Middleware composition utility
JavaScript
986
star
7

koa-body

koa body parser middleware
TypeScript
923
star
8

router

Router middleware for Koa. Maintained by @forwardemail and @ladjs.
JavaScript
790
star
9

cors

Cross-Origin Resource Sharing(CORS) for koa
JavaScript
723
star
10

kick-off-koa

[MAINTAINERS WANTED] An intro to koa via a set of self-guided workshops
JavaScript
693
star
11

logger

Development style logging middleware
JavaScript
561
star
12

mount

Mount other Koa applications or middleware to a given pathname
JavaScript
549
star
13

ratelimit

Rate limiter middleware
JavaScript
466
star
14

joi-router

Configurable, input and output validated routing for koa
JavaScript
450
star
15

route

Simple route middleware
JavaScript
442
star
16

workshop

Koa Training Workshop
JavaScript
436
star
17

compress

Compress middleware for koa
JavaScript
432
star
18

koa.io

[MAINTAINERS WANTED] Realtime web framework combine koa and socket.io.
JavaScript
427
star
19

send

Transfer static files
TypeScript
420
star
20

generic-session

koa session store with memory, redis or others.
JavaScript
414
star
21

koa-redis

Redis storage for Koa session middleware/cache with Sentinel and Cluster support
JavaScript
352
star
22

koala

[SEEKING MAINTAINER] An HTTP/2 and ES6 Module-ready Koa Suite
JavaScript
320
star
23

static-cache

[MAINTAINERS WANTED] Static cache for koa
JavaScript
293
star
24

csrf

CSRF tokens for koa
JavaScript
265
star
25

react-view

A Koa view engine which renders React components on server
JavaScript
256
star
26

convert

Convert koa generator-based middleware to promise-based middleware
JavaScript
254
star
27

ejs

a koa view render middleware, support all feature of ejs
JavaScript
248
star
28

json

pretty-printed JSON response middleware
JavaScript
197
star
29

todo

a todo example write with koa and react
JavaScript
165
star
30

koa-hbs

Handlebars templates for Koa.js
JavaScript
159
star
31

cash

HTTP response caching for Koa. Supports Redis, in-memory store, and more!
JavaScript
154
star
32

onerror

an error handler for koa, hack ctx.onerror
JavaScript
139
star
33

basic-auth

blanket basic auth middleware
JavaScript
138
star
34

userauth

koa user auth middleware
JavaScript
137
star
35

multer

Middleware for handling `multipart/form-data` for koa, based on Express's multer.
JavaScript
137
star
36

response-time

X-Response-Time middleware
JavaScript
124
star
37

trie-router

Trie-routing for Koa
JavaScript
122
star
38

koa-roles

koa version of Connect-Roles
JavaScript
117
star
39

etag

ETag support for Koa responses
JavaScript
112
star
40

bunyan-logger

Koa middleware for bunyan request logging
JavaScript
108
star
41

favicon

Koa middleware for serving a favicon
JavaScript
104
star
42

error

Error response middleware (text, json, html)
JavaScript
103
star
43

rewrite

URL rewriting middleware
JavaScript
100
star
44

json-filter

Middleware allowing the client to filter the response to only what they need, reducing the amount of traffic over the wire.
JavaScript
92
star
45

json-error

Error handler for pure-JSON apps
JavaScript
89
star
46

qs

qs for koa, and use querystring more safely.
JavaScript
85
star
47

bigpipe-example

[DEPRECATED] BigPipe using koa and component
JavaScript
83
star
48

common

[DEPRECATED] USE INDIVIDUAL MODULES
JavaScript
77
star
49

locales

koa locales, i18n solution for koa
JavaScript
67
star
50

koa-lusca

koa version of lusca. Application security for koa.
JavaScript
65
star
51

cluster

Koa clustering and error handling utility
JavaScript
64
star
52

parameter

parameter validate middleware for koa, powered by parameter
JavaScript
62
star
53

conditional-get

Conditional GET middleware for koa
JavaScript
59
star
54

trace

generic tracing for koa
JavaScript
53
star
55

koa-range

[MAINTAINERS WANTED] range request implementation for koa, see http://tools.ietf.org/html/rfc7233
JavaScript
47
star
56

sendfile

basic file-sending utility for koa
JavaScript
45
star
57

koajs.com

The koajs.com website
HTML
42
star
58

mock

Simple web page mock middleware
JavaScript
40
star
59

body-parsers

collection of koa body parsers
JavaScript
37
star
60

koa-markdown

Auto convert markdown to html for koa. Inspired by connect-markdown
JavaScript
37
star
61

koa-gzip

[Deprecated] please use koa-compress instead
JavaScript
36
star
62

file-server

file serving middleware for koa
JavaScript
36
star
63

bundle

Generic asset pipeline with caching, etags, minification, gzipping and sourcemaps.
JavaScript
36
star
64

resourcer

A simple resource directory mounter for koa.
JavaScript
34
star
65

path-match

koa route middleware
JavaScript
33
star
66

html-minifier

minify HTML responses like some crazy guy
JavaScript
31
star
67

webcam-mjpeg-stream

[DEPRECATED] Stream JPEG snapshots from your Mac
JavaScript
28
star
68

timer

time your middleware
JavaScript
26
star
69

statsd

Statsd middleware
JavaScript
24
star
70

redis-session-sets

Koa Redis sessions with field-referencing cross sets
JavaScript
20
star
71

accesslog

Middleware for common log format access logs
JavaScript
19
star
72

is-json

check if a koa body should be interpreted as JSON
JavaScript
17
star
73

charset

use iconv-lite to encode the body and set charset to content-type
JavaScript
16
star
74

koa-safe-jsonp

Safe jsonp plusins for koa.
JavaScript
16
star
75

trace-influxdb

InfluxDB tracing for koa-trace
JavaScript
15
star
76

stateless-csrf

CSRF without sessions.
JavaScript
15
star
77

atomic-session

DEPRECATED
JavaScript
15
star
78

cross-cookies

Easily set cookies across subdomains
JavaScript
13
star
79

koa-github

simple github auth middleware for koa
JavaScript
13
star
80

s3-cache

Koa middleware to cache and serve from S3
JavaScript
11
star
81

eslint-config-koa

Koa's ESLint config, based on Standard
JavaScript
11
star
82

ctx-cache-control

Augment Koa with ctx.cacheControl(maxAge)
JavaScript
9
star
83

snapshot

take snapshot when request, cache by request path.
JavaScript
9
star
84

compressor

[DEPRECATED] Compress middleware for koa that always compresses
JavaScript
9
star
85

koa-fresh

DEPRECATED
JavaScript
8
star
86

cdn

[DEPRECATED] middleware for a koa-based CDN
JavaScript
7
star
87

koa-rt

koa rt with microtime
JavaScript
6
star
88

override-method

method override utility for koa
JavaScript
6
star
89

ctx-basic-auth

Augments Koa with ctx.basicAuth
JavaScript
5
star
90

resourcer-docs

[MAINTAINERS WANTED] Simple app that generates documentation for routes mounted using koa-resourcer.
JavaScript
5
star
91

middleware-hook

low-level hooks for your middleware
JavaScript
5
star
92

path

[DEPRECATED] path-matching middleware for koa
JavaScript
4
star
93

observable-redis-session

[DEPRECATED] Observable, atomic sessions for Koa using Redis
JavaScript
2
star
94

help

koa(1) executable for instant help
2
star
95

discussions

KoaJS Discussions
1
star