node-header-session v0.5.1

The middleware creates a simple session management via a HTTP header field that contains a token.

Node Header Session

The middleware creates a simple session management via a HTTP header field that contains a token. This is for a stateless RESTful service.

Installation

Setup

$ cd project/folder
$ git clone https://github.com/blueskyfish/node-header-session.git
$ cd node-header-session
$ npm install

Test

$npm test

The tests are written with mocha and chai

The project is programmed with VS Code. But you can use any other editor used.

DefinitelyTyped / tsd

I use the DefinitelyTyped / tsd for autocomplete the api from external libraries.

$ npm install -g tsd
$ tsd install

Usage

var
	express = require('express'),
	headerSession = require('node-header-session');

var
	app = express();

// register the middleware and the metrics request.
headerSession(app, {
	name: 'x-this-is-a-restful-header-field',
	debug: true,
	metricsUrl: '/metrics/rest-header',
	root: '/restful-services',
	genToken: function () {
		return // generate a unique id / token (may UUID())
	},
	validToken = function (token) {
		return true; // or "/test pattern/.test(token);
	}
	// storage (a session storage engine @see memory-storage.js
});

app.get('/', function (req, res) {
	console.log('token %s', req.headerSession.token);
	req.headerSession.getSession().then(
		function (session) {
			var
				count = session.count || 0;

			session.count = ++count;

			res.send({
				count: count
			});
		}
	);
});

app.listen(3000, function () {
	console.log('server is started...');
});

Options

The middleware will be configured with some options

Demo

The demo app is in the folder demo. Start the demo app with the following commands

$ cd demo
$ npm install
$ npm start

Open the Browser http://localhost:3000

Screenshot from Demo app

Storage Engine

The session values can be saved in the memory or in a database table or in a NOSQL engine. If no storage is defined, then a memory storage will create.

Storage Interface

Storage
+ load(token: string): promise
+ store(token: string, session: object): promise
+ info(): promise  // optional
+ clear(): void    // optional

Include Storage

• MemoryStorage session values are in the memory cach of the application.
• FileStorage session values are stored in the filesystem.

load(token: string): promise

The method load try to load the session values from the storage. In case of success the promise callback returns the session values.

storage.load(token).then(function (session) {
	// session values
});

store(token: string, values: object): promise

The method store try to store the session values into the storage. In case of sucess the promise callback returns the session values agian.

storage.store(token, sessionValues).then(function (session) {
	// session values
});

info(): promise

The method info try to collect the session information. In case of sucess the promise callback returns a list of session info. The session info should contains the token, the creation and modified date.

storage.info().then(function (sessionInfoList) {
	sessionInfoList.forEach(function (sessionInfo) {
		console.log('%s (%s, %s)', sessionInfo.token,
			sessionInfo.creation, sessionInfo.modified
		);
	});
}

(optional) clear(): void | promise

The method clear remove all sessions.

MemoryStorage

• All sessions are stored in the memory of the application.
• This storage is using only for testing or for the internal development.
• The storage doesn't need to configure.
• If no storage engine is specified when you configure the middleware, the Memory Storage is used automatically.

Inteface

MemoryStorage
+ load(token: string): promise
+ store(token: string, values: object): promise
+ info(): promise;
+ clear(): void

FileStorage

• All sessions are stored in the file system.
• Before the storage can be used, it must be konfigueriert with the method init.

Configuration

var
	storeage = require('./lib/file-storage');

storage.init({
	storagePath: '/tmp/path/for/write/and/read/sessionValues',
	blacklist: ['readme.md', 'config.json']
});

Interface

FileStorage
+ load(token: string): promise
+ store(token, values: object): promise
+ info(): promise;
+ appendblackList(blacklist: Array<String>): void;
+ clear(): promise

Routemap

• add a timeout for the header session
• Done improve the metrics output
• Done write tests
• Done session values to a storage engine
  • Done MemoryStorage
  • Done FileStorage
  • and more...
• Done create a own token generator function
• Done calidation function

If an important feature is missing or you find an error, please create an Issue
https://github.com/blueskyfish/node-header-session/issues

Dependencies

See in the file package.json

Third Party Tools

• NodeJS or io.js
• ExpressJS
• VS Code
• DefinitelyTyped / tsd

License

The MIT License (MIT)

Copyright (c) 2015 BlueSkyFish <blueskyfish@kirchnerei.de>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.