1 | # egg-session
|
2 |
|
3 | [![NPM version][npm-image]][npm-url]
|
4 | [![build status][travis-image]][travis-url]
|
5 | [![Test coverage][codecov-image]][codecov-url]
|
6 | [![David deps][david-image]][david-url]
|
7 | [![Known Vulnerabilities][snyk-image]][snyk-url]
|
8 | [![npm download][download-image]][download-url]
|
9 |
|
10 | [npm-image]: https://img.shields.io/npm/v/egg-session.svg?style=flat-square
|
11 | [npm-url]: https://npmjs.org/package/egg-session
|
12 | [travis-image]: https://img.shields.io/travis/eggjs/egg-session.svg?style=flat-square
|
13 | [travis-url]: https://travis-ci.org/eggjs/egg-session
|
14 | [codecov-image]: https://codecov.io/github/eggjs/egg-session/coverage.svg?branch=master
|
15 | [codecov-url]: https://codecov.io/github/eggjs/egg-session?branch=master
|
16 | [david-image]: https://img.shields.io/david/eggjs/egg-session.svg?style=flat-square
|
17 | [david-url]: https://david-dm.org/eggjs/egg-session
|
18 | [snyk-image]: https://snyk.io/test/npm/egg-session/badge.svg?style=flat-square
|
19 | [snyk-url]: https://snyk.io/test/npm/egg-session
|
20 | [download-image]: https://img.shields.io/npm/dm/egg-session.svg?style=flat-square
|
21 | [download-url]: https://npmjs.org/package/egg-session
|
22 |
|
23 | Session plugin for egg, based on [koa-session](https://github.com/koajs/session).
|
24 |
|
25 | ## Install
|
26 |
|
27 | ```bash
|
28 | $ npm i egg-session --save
|
29 | ```
|
30 |
|
31 | ## Usage
|
32 |
|
33 | egg-session is a built-in plugin in egg and enabled by default.
|
34 |
|
35 | ```js
|
36 | // {app_root}/config/plugin.js
|
37 | exports.session = true; // enable by default
|
38 | ```
|
39 |
|
40 | ### External Store
|
41 |
|
42 | egg-session support external store, you can store your sessions in redis, memcached or other databases.
|
43 |
|
44 | For example, if you want to store session in redis, you must:
|
45 |
|
46 | 1. Dependent [egg-redis](https://github.com/eggjs/egg-redis)
|
47 |
|
48 | ```bash
|
49 | npm i --save egg-redis
|
50 | ```
|
51 |
|
52 | 2. Import egg-redis as a plugin and set the configuration
|
53 |
|
54 | ```js
|
55 | // config/plugin.js
|
56 | exports.redis = {
|
57 | enable: true,
|
58 | package: 'egg-redis',
|
59 | };
|
60 | ```
|
61 |
|
62 | ```js
|
63 | // config/config.default.js
|
64 | exports.redis = {
|
65 | // your redis configurations
|
66 | };
|
67 | ```
|
68 |
|
69 | 3. Implement a session store with redis
|
70 |
|
71 | ```js
|
72 | // app.js
|
73 |
|
74 | module.exports = app => {
|
75 | // set redis session store
|
76 | // session store must have 3 methods
|
77 | // define sessionStore in `app.js` so you can access `app.redis`
|
78 | app.sessionStore = {
|
79 | async get(key) {
|
80 | const res = await app.redis.get(key);
|
81 | if (!res) return null;
|
82 | return JSON.parse(res);
|
83 | },
|
84 |
|
85 | async set(key, value, maxAge) {
|
86 | // maxAge not present means session cookies
|
87 | // we can't exactly know the maxAge and just set an appropriate value like one day
|
88 | if (!maxAge) maxAge = 24 * 60 * 60 * 1000;
|
89 | value = JSON.stringify(value);
|
90 | await app.redis.set(key, value, 'PX', maxAge);
|
91 | },
|
92 |
|
93 | async destroy(key) {
|
94 | await app.redis.del(key);
|
95 | },
|
96 | };
|
97 |
|
98 | // session store can be a session store class
|
99 | // app.sessionStore = class Store {
|
100 | // constructor(app) {
|
101 | // this.app = app;
|
102 | // }
|
103 | // async get() {}
|
104 | // async set() {}
|
105 | // async destroy() {}
|
106 | // };
|
107 | };
|
108 | ```
|
109 |
|
110 | Once you use external session 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!**
|
111 |
|
112 | ## Configuration
|
113 |
|
114 | Support all configurations in [koa-session](https://github.com/koajs/session).
|
115 |
|
116 | [View the default configurations](https://github.com/eggjs/egg-session/blob/master/config/config.default.js)
|
117 |
|
118 | ## Questions & Suggestions
|
119 |
|
120 | Please open an issue [here](https://github.com/eggjs/egg/issues).
|
121 |
|
122 | ## License
|
123 |
|
124 | [MIT](https://github.com/eggjs/egg-session/blob/master/LICENSE)
|
125 |
|
\ | No newline at end of file |