autohost
Convention-based, opinionated HTTP server library based on express. Lovingly ripped from the guts of Anvil.
This library is experimental and rapidly changing.
Features
- Resource-based: define protocol-agnostic resources that interact via HTTP or WebSockets
- Auto-reloads resources on file change
- Supports server-side websockets and socket.io
- UI dashboard to review resources' routes, topics and hosted paths
UI Dashboard
Simple navigate to /_autohost to review the current set of resources:
Quick Start
var host = require( 'autohost' )();
host.init();
Configuration
While the configuration can be provided optionally to the init call, it's recommended to pass this during instantiation after the require.
The object literal follows the format:
{
appName: ''
static: './public',
resources: './resource',
port: 8800,
allowedOrigin: 'leankit.com',
websockets: true,
socketIO: true
}
Recommended
var autohost = require( 'autohost' )( {
appName: 'demo',
port: 8881
} );
Resources
Resources are expected to be simple modules that return a parameterless function resulting in a JS literal that follows the format:
{
name: 'resource-name',
resources: '',
actions: [
{
alias: 'send',
verb: 'get',
topic: 'send',
path: '',
handle: function( envelope ) {
}
}
]
}
Authentication
Authentication support is supplied via Passport integration. Your application is expected to provide a strategy and authentication method. You can also provide a regex path to make part of your path open to anonymous access.
You must set this up BEFORE calling .init, calling it after initialization will probably cause 'splosions.
var passport = require( 'passport' );
var BasicStrategy = require( 'passport-http' ).BasicStrategy;
var host = require( '../src/autohost.js' )();
host.withPassportStrategy(
new BasicStrategy({}, function( username, password, done ) {
if( username == 'anon' || ( username == 'admin' && password == 'admin' ) ) {
done( null, username );
} else {
done( null, false );
}
} ),
passport.authenticate( 'basic', { session: false } ),
/^[\/]anon.*/ );
Authorization
The general approach is this:
- every action in the system is made available to the authorization strategy on start-up
- an action may be assigned to one or more roles in your authorization strategy
- a user may be assigned to one or more roles in your authorization strategy
- when a user attempts to activate an action, the action roles are checked against the user roles
- if a match is found in both lists, the action completes
- if the user has no roles that match any of the action's roles, the action is rejected (403)
- if the action has NO roles assigned to it, the user will be able to activate despite roles
This basically goes against least-priviledge. If this is a problem, assign a baseline 'authenticated' or 'user' role to every action returned to you during server start-up OR always return either of these during the 'getRolesFor' call.
The authorization strategy MUST implement 3 calls:
actionList( list, done )
Will recieve a hashmap of resources and resource action names. Action names follow a namespace convention of {resource name}.{alias}. The done call back MUST be called.
Here's an example of the format.
{
'_autohost': [
'_autohost.api',
'_autohost.resources',
'_autohost.actions',
'_autohost.connected-sockets'
]
}
This is provided to your auth provider so that actions can automatically be updated (as in storage) on-the-fly when the server spins up.
getUserRoles( user, done ) -- done( err, roles )
Given a user's id, this must return any roles assigned to the user in the system. Done must be called with error or roles. An exception should never be allowed to bubble up through this call.
getRolesFor( action ) -- done( err, roles )
During activation, the action name ( resource.alias ) is passed to this call to determine what roles are able to activate the action. If you don't want actions to default to enabled despite user role, ALWAYS return at least some baseline role ( i.e. 'user', 'authenticated', etc. ).
Done must be called with error or roles. An exception should never be allowed to bubble up through this call.
Auth admin panel (Experimental)
In order to use this feature, you must provide an authorization strategy with several additional calls. It should go without saying that you're expected invoke the callback with either the result or an error.
Documentation on this API coming soon, see autohost-riak-auth library for an example
Web Socket Stuff
WebSocket-Node library
When establishing a connection to autohost using the WebSocket-Node client, you'll need to append '/websocket' to the end of the URL. This enables autohost to support both socket.io and WebSocket-Node simultaneously.
Methods
- sendToClient( id, topic, message ) - sends message to specific client via websocket (returns true if successful)
- notifyClients( topic, message ) - sends message to all clients via web sockets
Events
- 'socket.client.connected', { socket: socketConnection } - raised when a client connects
- 'socket.client.identified', { socket: socketConnection, id: id } - raised when client reports unique id
- 'socket.client.closed', { socket: socketConnection, id: id } - raised when client disconnects the websocket connection
TO DO
- Add support for clustering (multiple listening processes)
- Add support for user authentication and authorization (access) logging
- Add support for rate limiting
- Better logging
- More thorough error handling
License
MIT License - http://opensource.org/licenses/MIT