Improve this doc

HTTP Middleware

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 client/static.

The Connect app instance is accessible directly via the ss.http.middleware variable within app.js. The stack is loaded in this order:

Connect middleware order

Any prepended middleware is loaded here, then we load:

Any appended middleware is loaded here, then we load:

Prepending custom middleware

SocketStream allows you to prepend new middleware to the top of the stack (to be processed BEFORE SocketStream middleware) using:

    ss.http.middleware.prepend()
For example you could add:
    ss.http.middleware.prepend( require('connect-winston')(winston) );

Appending custom middleware

Because SocketStream adds connect.cookieParser() and connect.session() to the stack, if the middleware you're wanting to use requires sessions support (i.e. access to req.session) it will need to be appended to the bottom of the stack AFTER SocketStream middleware has been loaded as so:

    ss.http.middleware.append( everyauth.middleware() );
Apart from determining where the middleware should be added, the prepend() and append() functions work in exactly the same way as connect.use().

Loading staticCache middleware

In order to avoid making repeated fs.readFile requests for serving static files, you can load Connect's 'connect-static' middleware, by passing this:

    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
      }
    });

Passing custom HTTP middleware settings

You can pass custom http middleware settings via ss.http.set:

    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
      }
    });

At the moment, you can use this to set custom options for the following SS middleware:

We will find a way to make all of the middleware customisable in the near future.

Changing the HTTP middleware approach

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.

    ss.http.set({
        strategy: 'minimal'
    });

Setting a custom HTTP middleware strategy

As an experimental feature you can set your own strategy. You can base it on the default strategy found in the source.

It can be configured by

    ss.http.set({
        strategy: require('./my.own.strategy')
    });