roux

A simple, event-driven, parallel-processing, highly-opinionated API framework for node.js.

Roux is...

Simple:

Require Roux, and start it, that's it. Now you've got a RESTful JSON API running with many built-in features.

Event Driven:

Roux is not an MVC framework. Nor is it an MVVM. It's an event-driven API framework purpose-built to take advantage of the things Node.js does well, and to utilize server-resources as efficiently as possible. Rather than a typical server-to-router-to-controller setup...

Server > Routing Table > Controller > Model > Response

...Roux revolves around event emission and binding instead.

Server > event > Handler(s) > event(s) > Model(s) > event(s) > Response

When an incoming http request is received, the server emits an event which triggers any service-handlers that may be listening. These handlers process the request data then (may or may not) emit an event which triggers CRUD operations in models. Once all the triggered-events have fired and finished processing, the server sends a response to the user.

Parallel Processing:

Roux utilizes Node's clustering utilities to make optimal use of all available CPUs. Event listeners can each run on their own fork, so that multipe event handlers can process requests in parallel. This optimizes the speed at which a user receives the server response, and allows the server to support a large number of connections and processes.

Highly Opinionated:

Roux encourages a few key principles: statelessness, readability, useability, testabilitiy, and standards-conformance. As such, this framework is opinionated as to how you structure your code and your services.

Roux encourages the creation of functional, immutable, context-independent handlers, and object-oriented, CRUD-focused models. It encourages general-purpose, exportable code, and minimal app-specific procedure. Chained callbacks are discouraged, closures are avoided, and promises are used sparingly. Anything that encourages state is eschewed in favor of decoupled, parallel, idempotent procedures.

Roux supports structured, static services with clean, semantic, consistent paths. It enforces proper use of HTTP status codes and headers, and handles a number of best-practices (like rate-limiting and api-versioning) automatically behind the scenes.

Built in Features

Roux attempts to handle the use-cases that most APIs have in common, so that you can focus on writing only your app-specific code. Here are some of the features Roux out of the box:

• API versioning
• Environment-dependant configuration
• Debugging mode with verbose output
• Caching of GET requests
• Rate-limiting
• CORS and JSONP support
• HTTPS support
• Automatic timeouts

Getting Started

NPM Install

npm install roux --save

Setup your Project

Sample directory structure

package.json
config.js
index.js
/handlers
  /widget.js
  /...
/models
  /widget.js
  /...
/test
  /...

Sample index.js:

// Require Roux
var api = require('roux');
 
// Start your API
api.start();

Sample config.js:

var environments = {
  localhost: {
    server: {
    	port: 9999
    }
  },
  staging: {
    server: {
    	port: 80
    }
  },
  production: {
  	server: {
    	port: 443
    	https: true
    }
  }
};
 
module.exports = environments;
 

For a full list of configuration options, read the Wiki

Add your first handler

Sample handlers/widget.js:

var api = require('roux');
var handler = new api.handler();
 
// Define the services, methods, and api-versions the handler should bind to
handler.bindTo('/widget', 'GET', ['1.1', '1.2'], 'start');
 
// Primary logic for the handler
handler.functions.start = function(req,res){
 
    var parameters = {};	
    // Do stuff here. Namely, fill in the parameters based on info in the req object
    
    // Trigger the widget model to perform a CRUD operation
    handler.triggerModel('widget', 'read', parameters);
    
    // End the handler
    handler.end();
};
 
// Export the handler
module.exports = handler;

Add your first model

Sample models/widget.js:

var mongoose = require('mongoose');
var api = require('roux');
var model = new api.model();
 
// Define the events the model should bind to
model.bindTo('widget', 'read', 'start');
 
// Primary logic for the model
model.functions.start = function(req,res, parameters){
    var resource = mongoose.model('widgets');
    
    var data = {};
    // Do stuff here. Namely, get the data from the widget model using the parameters specified.
    
    // Add a payload to the response
    api.response.addPayload(data);
    
    model.end();	
};
 

Conventions / Best Practices

// Coming soon

License

The MIT License (MIT)

Copyright (c) 2015 Malcolm Diggs

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.