Create sessions and load them automatically in connection before actions are called.
For Actionhero 8 and 9, use version 1.*
For Actionhero 11, use version 11.*
If upgrading from v1 to v11 or higher, please note that code will need to be updated to reflect usage and config file changes.
To install, run npm install ah-autosession-plugin
A configuration file should then exist at config/plugins/ah-autosession-plugin.js which lists and explains all the plugin options.
exports.default = {
"ah-autosession-plugin": function(api){
return {
name: 'ah-autosession-plugin', // middleware name
priority: 20, // middleware priority
global: true, // middleware global value. if false, must manually specify on each page
default_behaviour: "required", // 'required'=prevent action if session missing, 'load'=load if exists but don't require it, 'off'=don't attempt to load session
global_override_key: "autosession", // if an action doesn't require it, like login or public page, set action.autosession = false
connection_param: "session", // where will the session data be available in data object? data.session
app_id: "sess", // app id used by redis_sessions
valid: { // custom regex validators used by redis_sessions
app: /^([a-zA-Z0-9_-]){1,20}$/, // make sure it allows app_id set above
id: /^([a-zA-Z0-9_-]){1,128}$/, // this should validate your user ids
token: /^([a-zA-Z0-9]){64}$/, // validates token (don't change unless you know what you're doing)
ip: /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$|^unknown$|^testServer$/, // allows ip address, "unknown", or "testServer"
//ip: /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/, // use this if you want to throw error on invalid/missing ip
},
prefix: 'ah:sess:', // redis prefix
ttl:1000 * 60 * 60 * 24 * 14, // session time to live; 1000 * 60 * 60 * 24 * 14 = two weeks
token_param: "t", // this is the name of the token parameter added to all actions that use autosession
error: {
required: {code:"token_required"},
invalid: {code:"token_not_found"},
},
};
}
};
As soon as the plugin is installed, all actions will start attempting to load session data if a token is sent.
The global default option can be overridden on a per-action basis by adding the parameter autosession to the action with a value of 'load' [attempt to load a session if a session token is sent], 'required' [require an existing session in order to run an action], or 'off' [don't autoload anything].
Example 1: For a system that tries to store session information for each user but doesn't necessarily require it, set the global default_behaviour to 'load', and the plugin will then attempt to load session data on every action, but not require it to exist to run the action.
Example 2: For a closed system that requires authentication, set the config default_behaviour value to 'required' and then create an authentication action with autosession: 'off' or autosession: false. Unauthorized users will then be able to call that action and only that action.
Example 3: For a system that is mostly open but requires authentication on a few actions, you would set the config default_behaviour to 'off' and then add autosession: 'required' to any actions that need it.
Using your own authentication system, after a user is authenticated call api.autosession.createSession:
// ttl, ip, and app are optional by default
api.autosession.create(user_id, {ttl:session_lifespan, ip:ip_address, app:app_id}, function(err, tokendata) {
// tokendata.token can now be sent back to the user
});
The data object contains a simple key/value list where values can be string, number, boolean or null.
To remove keys set them to null.
Keys that are not supplied will not be touched.
api.autosession.set(token, data, function(err, result) {
// result = all the session data
});
Session data is added to the connection object for each action. You can access it like so:
var user_id = connection.session.id;
var some_data = connection.session.d.some_data; // note that any data stored with .set() is stored in session.d
If you would like to change 'session' to something else, it can be changed in the config file.
api.autosession.kill(token, function(err, result) {
// result = {kill:1} on success or {kill:0} on failure
});
api.autosession.killAll(user_id, function(err, result) {
// result = {kill:number of sessions ended} on success or {kill:0} on failure
});
The plugin is basically a wrapper to make redis-sessions less of a hassle, with some added actionhero-specific functionality. Please read the redis-sessions page to find out more about how the sessions are being stored.
If you need direct access to the redis-sessions object, it is available at api.autosession.rs