socketstream/socketstream

<a href="https://github.com/socketstream/socketstream/edit/master/src/docs/tutorials/en/http_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="http-middleware-page"><h2 id="http-middleware">HTTP Middleware</h2>
<p>SocketStream provides a stack of Connect HTTP middleware which is used internally to serve single-page clients, asset files and static files (e.g. images) in <code>client/static</code>.</p>
<p>The Connect <code>app</code> instance is accessible directly via the <code>ss.http.middleware</code> variable within <code>app.js</code>. The stack is loaded in this order:</p>
<h3 id="http-middleware_connect-middleware-order">Connect middleware order</h3>
<p>Any prepended middleware is loaded here, then we load:</p>
<ul>
<li>compress</li>
<li>cookieParser</li>
<li>favicon</li>
<li>session</li>
</ul>
<p>Any appended middleware is loaded here, then we load:</p>
<ul>
<li>eventMiddleware (handles loading client files when running in development mode)</li>
<li>static</li>
<li>staticCache (optional)</li>
</ul>
<h3 id="http-middleware_prepending-custom-middleware">Prepending custom middleware</h3>
<p>SocketStream allows you to prepend new middleware to the top of the stack (to be processed BEFORE SocketStream middleware) using:
<pre class="prettyprint linenums">
    ss.http.middleware.prepend()
</pre>
For example you could add:
<pre class="prettyprint linenums">
    ss.http.middleware.prepend( require('connect-winston')(winston) );
</pre>
<h3 id="http-middleware_appending-custom-middleware">Appending custom middleware</h3>
<p>Because SocketStream adds <code>connect.cookieParser()</code> and <code>connect.session()</code> to the stack, if the middleware you&#39;re wanting to use requires sessions support (i.e. access to <code>req.session</code>) it will need to be appended to the bottom of the stack AFTER SocketStream middleware has been loaded as so:
<pre class="prettyprint linenums">
    ss.http.middleware.append( everyauth.middleware() );
</pre>
Apart from determining where the middleware should be added, the <code>prepend()</code> and <code>append()</code> functions work in exactly the same way as <code>connect.use()</code>.</p>
<h3 id="http-middleware_loading-staticcache-middleware">Loading staticCache middleware</h3>
<p>In order to avoid making repeated fs.readFile requests for serving static files, you can load Connect&#39;s &#39;connect-static&#39; middleware, by passing this:
<pre class="prettyprint linenums">
    ss.http.set({
      staticCache: {
        maxObjects: 128,      // The number of objects to store in cache
        maxLength: 1024 * 256 // The file size limit for storing a file in cache, 256Kb
      }
    });
</pre>
<h3 id="http-middleware_passing-custom-http-middleware-settings">Passing custom HTTP middleware settings</h3>
<p>You can pass custom http middleware settings via <code>ss.http.set</code>:
<pre class="prettyprint linenums">
    ss.http.set({
      static: {
        maxAge: 30 * 24 * 60 * 60 * 1000 // cache static assets in the browser for 30 days
      },
      staticCache: {
        maxObjects: 128,       // The number of objects to store in cache
        maxLength: 1024 * 256 // The file size limit for storing a file in cache, 256Kb
      }
    });
</pre>
<p>At the moment, you can use this to set custom options for the following SS middleware:</p>
<ul>
<li>static</li>
<li>staticCache</li>
<li>session (secure flag only)</li>
<li>strategy</li>
</ul>
<p>We will find a way to make all of the middleware customisable in the near future.</p>
<h3 id="http-middleware_changing-the-http-middleware-approach">Changing the HTTP middleware approach</h3>
<p>Short of setting up your own middleware stack, you can pick a strategy other than the default.
The minimal strategy will leave out session and compress middleware. So you will have to manage
that yourself.</p>
<pre class="prettyprint linenums">
    ss.http.set({
        strategy: 'minimal'
    });
</pre>
<h3 id="http-middleware_setting-a-custom-http-middleware-strategy">Setting a custom HTTP middleware strategy</h3>
<p>As an experimental feature you can set your own strategy. You can base it on the default strategy
found in <a href="https://github.com/socketstream/socketstream/tree/master/lib/http">the source</a>.</p>
<p>It can be configured by</p>
<pre class="prettyprint linenums">
    ss.http.set({
        strategy: require('./my.own.strategy')
    });
</pre>
</div></div>