docs/partials/tutorials/request_middleware.html
<a href="https://github.com/socketstream/socketstream/edit/master/src/docs/tutorials/en/request_middleware.ngdoc" class="improve-docs"><i class="icon-edit"> </i>Improve this doc</a><h1><code ng:non-bindable=""></code>
<div><span class="hint"></span>
</div>
</h1>
<div><div class="request-middleware-page"><h2 id="request-middleware">Request Middleware</h2>
<p>Request Middleware allows you to inspect, transform, redirect or drop incoming requests over the websocket, HTTP API, or REPL (using <code>ss-console</code>).</p>
<p>If you've used Connect HTTP middleware before the concept and API will be instantly familiar. Essentially incoming requests can be processed through a chain of middleware BEFORE they arrive at their final destination - typically the RPC command you are requesting.</p>
<p>Middleware can be provided internally, via external modules, or custom-defined in your app.</p>
<p>Regardless, all middleware is invoked using the <code>req.use()</code> command from within your <code>server/rpc</code> code.</p>
<h4 id="request-middleware_internal-middleware">Internal Middleware</h4>
<p>Right now SocketStream provides two simple internal middleware functions: <code>debug</code> and <code>session</code>.</p>
<h5 id="request-middleware_internal-middleware_debug">debug</h5>
<p>The <code>debug</code> middleware will output the contents of the <code>req</code> object to the terminal, useful when you're debugging problems. It takes an optional argument indicating which color to output the message in:</p>
<pre class="prettyprint linenums">
// server/rpc/app.js
exports.actions = function(req, res, ss){
// output all incoming requests to the console in cyan
req.use('debug', 'cyan');
return {
square: function(n){
res(n * n);
}
}
}
</pre>
<h5 id="request-middleware_internal-middleware_session">session</h5>
<p>The <code>session</code> middleware instructs SocketStream to retrieve the user's session from the session store BEFORE executing the next action:</p>
<pre class="prettyprint linenums">
// server/rpc/app.js
exports.actions = function(req, res, ss){
// load user's session into req.session
req.use('session');
return {
square: function(n){
res(n * n);
}
}
}
</pre>
<p>Try adding <code>req.use('debug')</code> after <code>req.use('session')</code> to see how the session data has been loaded into <code>req.session</code>. Remember, the order you call middleware in is very important.</p>
<h4 id="request-middleware_using-third-party-middleware">Using third-party middleware</h4>
<p>Simply pass the module/function directly. E.g:
<pre class="prettyprint linenums">
req.use(require('text-utils').sanitize, {anyConfig: 'can be passed here'});
</pre>
<h4 id="request-middleware_creating-your-own-middleware">Creating your own Middleware</h4>
<p>Creating custom middleware in your application is easy.</p>
<p>Let's start by creating an RPC action which multiplies incoming numbers (the first param).</p>
<pre class="prettyprint linenums">
// server/rpc/app.js
exports.actions = function(req, res, ss){
// pass the multiplier to the second arg
req.use(multiplyNumber, 2);
return {
showResult: function(n){
res('The incoming number is ' + n);
}
}
}
// define my custom middleware function
multiplyNumber = function(multiplier){
return function(req, res, next){
var = num = req.params[0];
if (num && typeof(num) == 'number')
req.params[0] = (num * multiplier);
next() // indicates middleware is finished processing
}
}
</pre>
<p>Let's test this out in the browser:
<pre class="prettyprint linenums">
ss.rpc('app.showResult', 80) // outputs "The incoming number is 160" to the console
</pre>
<h5 id="request-middleware_creating-your-own-middleware_using-middleware-for-authorization">Using Middleware for Authorization</h5>
<p>Request Middleware is the perfect way to check if a user is authorized before proceeding further:</p>
<pre class="prettyprint linenums">
// server/rpc/app.js
exports.actions = function(req, res, ss){
// check user is logged in before proceeding
req.use(checkAuthenticated);
return {
topSecret: function(){
// this function will only be called if user is logged in
res(bankCodes);
}
}
}
// define custom middleware to ensure user is logged in
checkAuthenticated = function(){
return function(req, res, next){
if (req.session && req.session.userId) return next();
res('Access denied'); // prevent request from continuing
}
}
</pre>
<p>You could take this one step further and load the user's data from a database and attach it to <code>req.user</code>.</p>
<h4 id="request-middleware_sharing-middleware-across-multiple-files">Sharing middleware across multiple files</h4>
<p>Once you've created your custom middleware you'll probably want to use it across multiple files. SocketStream makes this easy by allowing middleware to be placed in <code>server/middleware</code> and loaded into an API Tree.</p>
<p>For example let's move the <code>checkAuthenticated</code> function above to its new home in <code>server/middleware/admin/user.js</code>:</p>
<pre class="prettyprint linenums">
// server/middleware/admin/user.js
exports.checkAuthenticated = function(){
return function(req, res, next){
if (req.session && req.session.userId) return next();
res(false); // Access denied: prevent request from continuing
}
}
</pre>
<p>You can now call this function from any <code>server/rpc</code> file with:
<pre class="prettyprint linenums">
req.use('session');
req.use('admin.user.checkAuthenticated');
</pre>
<p>Note: <code>req.use('session')</code> must be called first as the <code>checkAuthenticated</code> middleware uses the <code>req.session</code> object.</p>
<p>Although you strictly don't have to, we highly recommend creating at least one folder in <code>server/middleware</code> to store your custom middleware to prevent any future namespace conflicts.</p>
<h4 id="request-middleware_food-for-thought">Food for thought</h4>
<p>Request Middleware allows for many exciting new opportunities around models and scaling.</p>
<p>For example you could write your own middleware which handles CRUD requests (create, update, delete, etc) and forwards them directly to MongoDB, or use <a href="https://github.com/hookio/hook.io">Hook.IO</a> to forward incoming requests to a different system altogether.</p>
<p>Bear in mind there's no need to define any RPC actions at all if your middleware can respond to all incoming requests.</p>
<p>We'll be exploring all these ideas in the future when time permits, but you don't have to wait for us. Start experimenting today and publish your middleware module on npm for everyone to use.</p>
</div></div>