README
ExpressSessionMongoDB
Implementation of the store functionality conforming to the API specified in express-session project (https://github.com/expressjs/session).
This implementation uses the MongoDB database.
Requirements
A recent version of MongoDB (version 2.4.9 is installed on my machine) [1]
A recent version of Node.js (version 0.10.25 is installed on my machine) [1]
npm if you want the easy way to install this module.
Read the package.json file for other dependencies. The devDependencies are solely to run the tests and not required for production.
[1] Later versions should also work. If you find it not to be the case, let me know.
Installation
npm install express-session-mongodb
Running Tests
In the directory where the module is located, run the following 2 commands on the prompt:
- npm install
- npm test
Running the tests will a bit over a minute due to the TimeToLive test.
Usage
Example of the usage pattern for this module:
var Mongodb = require('mongodb');
var Store = require('express-session-mongodb');
var ExpressSession = require('express-session');
var Express = require('express');
var App = Express();
//Probably Some code
var StoreOptions = {'TimeToLive': 0, 'IndexSessionID': false}; //Read more below
MongoDB.MongoClient.connect("mongodb://localhost:27017/SomeDatabase", function(Err, DB) { //Obviously, your code will probably differ here
Store(DB, function(Err, SessionStore) {
var Options = {'secret': 'qwerty!', 'store': SessionStore}; //Look at the express-session project to find out all the options you can pass here
App.use(ExpressSession(Options));
//Probably more code
}, StoreOptions);
});
The express-session-mongodb module returns a function with the following signature:
function(<DBHandle>, <Callback>, <Options>);
<DBHandle> is the database handle that the store will operate on. It should be obtained using the MongoDB driver.
<Options> are the options you can pass to the session store instance. It is an object with the following properties:
- IndexSessionID: Can be either true or false (default). If true, session IDs will be indexed with a unique requirement in the MongoDB database, making the creation of sessions slower, but their access faster.
While theorically, an error should be reported if duplicate session IDs are created, this will never happen in practice because of the way the express-session project is implemented (the fact that the call it makes to create or update a session in the database are the same). Rather, if ever express-session somehow creates two sessions with duplicate IDs, one will overwrite the other. Obviously, a good key generator will make this occurence logically or probabilistically impossible.
Additional note: I tried passing a key generator that always generated the same key to express-session to see how it would react, but it appended some random string to the generated keys so express-session does seem to take extra precautions to avoid collisions.
TimeToLive: Integer than can be 0 (default) or greater. If greater than 0, a Time-to-Live index will be set which will represent how long (in seconds) a session can be idle in the database (neither written to nor accessed) before MongoDB deletes it. Note that according to the author of "MongoDB: The Definitive Guide", MongoDB check on Time-To-Live indexes about once per minute, so you should not rely on a session getting deleted the exact second it expires.
Filter: Can be true or false (default). If set to true, the '.', '