Express (http://expressjs.com) popularized the term middleware in the Node.js world, binding it to a very specific design pattern. In Express, in fact, middleware represents a set of services, typically functions, that are organized in a pipeline and are responsible for processing incoming HTTP requests and relative responses.

Express is famous for being a very non-opinionated and minimalist web framework. Using the middleware pattern is an effective strategy for allowing developers to easily create and distribute new features that can be easily added to the current application, without the need to grow the minimalistic core of the framework.

An Express middleware has the following signature:

function(req, res, next) { ... } 

Here, req is the incoming HTTP request, res is the response, and next is the callback to be invoked when the current middleware has completed its tasks and that in turn triggers the next middleware in the pipeline.

Examples of the tasks carried out by Express  middleware include the following:

If we think about it, these are all tasks that are not strictly related to the main functionality of an application, nor essential parts of a minimal core of a web server; rather, they are accessories, components providing support to the rest of the application and allowing the actual request handlers to focus only on their main business logic. Essentially, those tasks are software in the middle.

The technique used to implement middleware in Express is not new; in fact, it can be considered the Node.js incarnation of the Intercepting Filter pattern and the Chain of Responsibility pattern. In more generic terms, it also represents a processing pipeline, which reminds us about streams. Today, in Node.js the word middleware is used well beyond the boundaries of the Express framework, and indicates a particular pattern whereby a set of processing units, filters, and handlers, under the form of functions, are connected to form an asynchronous sequence in order to perform the preprocessing and postprocessing of any kind of data. The main advantage of this pattern is flexibility; in fact, this pattern allows us to obtain a plugin infrastructure with incredibly little effort, providing an unobtrusive way for extending a system with new filters and handlers.

The following diagram shows the components of the middleware pattern:

The essential component of the pattern is the Middleware Manager, which is responsible for organizing and executing the middleware functions. The most important implementation details of the pattern are as follows:

There is no strict rule on how the data is processed and propagated in the pipeline. The strategies include:

The right approach depends on the way the Middleware Manager is implemented and on the type of processing carried out by the middleware itself.

Let's now demonstrate the pattern by building a middleware framework around the ØMQ (http://zeromq.org) messaging library. ØMQ (also known as ZMQ, or ZeroMQ) provides a simple interface for exchanging atomic messages across the network using a variety of protocols; it shines for its performance, and its basic set of abstractions are specifically built to facilitate the implementation of custom messaging architectures. For this reason, ØMQ is often chosen to build complex distributed systems.

The interface of ØMQ is pretty low-level; it only allows us to use strings and binary buffers for messages, so any encoding or custom formatting of data has to be implemented by the users of the library.

In the next example, we are going to build a middleware infrastructure to abstract the preprocessing and post processing of the data passing through a ØMQ socket, so that we can transparently work with JSON objects, but also seamlessly compress messages traveling over the wire.

module.exports = class ZmqMiddlewareManager { 
  constructor(socket) { 
    this.socket = socket; 
    this.inboundMiddleware = [];                    //[1] 
    this.outboundMiddleware = []; 
    socket.on('message', message => {               //[2] 
      this.executeMiddleware(this.inboundMiddleware, { 
        data: message 
      }); 
    }); 
  } 
 
  send(data) { 
    constmessage = { 
      data: data 
    }; 
 
    this.executeMiddleware(this.outboundMiddleware, message, 
      () => { 
        this.socket.send(message.data); 
      } 
    ); 
  } 
 
  use(middleware) { 
    if (middleware.inbound) { 
      this.inboundMiddleware.push(middleware.inbound); 
    } 
    if (middleware.outbound) { 
      this.outboundMiddleware.unshift(middleware.outbound); 
    } 
  } 
 
  executeMiddleware(middleware, arg, finish) { 
    function iterator(index) { 
      if (index === middleware.length) { 
        return finish && finish(); 
      } 
      middleware[index].call(this, arg, err => { 
        if (err) { 
          return console.log('There was an error: ' + err.message); 
        } 
        iterator.call(this, ++index); 
      }); 
    } 
 
    iterator.call(this, 0); 
  } 
}; 

module.exports.json = () => { 
  return { 
    inbound: function (message, next) { 
      message.data = JSON.parse(message.data.toString()); 
      next(); 
    }, 
    outbound: function (message, next) { 
      message.data = new Buffer(JSON.stringify(message.data)); 
      next(); 
    } 
  } 
}; 

const zmq = require('zmq'); 
const ZmqMiddlewareManager = require('./zmqMiddlewareManager'); 
const jsonMiddleware = require('./jsonMiddleware'); 
const reply = zmq.socket('rep'); 
reply.bind('tcp://127.0.0.1:5000'); 

const zmqm = new ZmqMiddlewareManager(reply); 
zmqm.use(jsonMiddleware.json()); 

zmqm.use({ 
  inbound: function (message, next) { 
    console.log('Received: ', message.data); 
    if (message.data.action === 'ping') { 
      this.send({action: 'pong', echo: message.data.echo}); 
    } 
    next(); 
  } 
}); 

const zmq = require('zmq'); 
const ZmqMiddlewareManager = require('./zmqMiddlewareManager'); 
const jsonMiddleware = require('./jsonMiddleware'); 
 
const request = zmq.socket('req'); 
request.connect('tcp://127.0.0.1:5000'); 

const zmqm = new ZmqMiddlewareManager(request); 
zmqm.use(jsonMiddleware.json()); 

zmqm.use({ 
  inbound: function (message, next) { 
    console.log('Echoed back: ', message.data); 
    next(); 
  } 
}); 

setInterval( () => { 
  zmqm.send({action: 'ping', echo: Date.now()}); 
}, 1000); 

node server

node client

In the previous paragraphs we saw how it's possible to implement the middleware pattern with callbacks and an example applied to a messaging system.

As we saw when we introduced it, the middleware pattern really shines in web frameworks as a handy mechanism to build "layers" of logic that can deal with input and output as data flows throughout the core of the application.

Apart from Express, another web framework which makes heavy use of the middleware pattern is Koa (http://koajs.com/). Koa is an extremely interesting framework mostly because of its radical choice to implement the middleware pattern only using ES2015 generator functions rather than using callbacks. We will see in a moment how this choice dramatically simplifies the way middleware can be written, but before moving to some code let's picture another way to visualize the middleware pattern, specific for this web framework:

In this representation, we have an incoming request that, before getting into the core of our app, traverses a number of middlewares. This part of the flow is called inbound or downstream. After the flow reaches the core of the app, it traverses all the middlewares again, but this time in an inverse order. This allows the middlewares to perform other actions after the main logic of the app has been executed and the response is ready to be sent to the user. This part of the flow is called outbound or upstream.

The representation above is sometime called "the onion" among programmers because of the way middleware wraps the core app, which reminds us of the layers of an onion.

Now let's create a new web application with Koa to see how we can easily write a custom middleware with generator functions.

Our app will be a very simple JSON API that returns the current timestamp in our server.

First of all, we need to install Koa:

npm install koa

Then we can write our new app.js:

const app = require('koa')(); 
 
app.use(function *(){ 
  this.body = {"now": new Date()}; 
}); 
 
app.listen(3000); 

It's important to notice that the core of our application is defined with a generator function within an app.use call. We will see in a moment that middlewares are added to the app in the exact same way and we will realize that the core of our app is, nonetheless, the last middleware added to the application (and which doesn't need to yield to another following item of middleware).

The first draft of our app is ready. We can now run it:

node app.js

We then point our browser to http://localhost:3000 to see it in action.

Notice that Koa takes care of converting the response to a JSON string and adds the correct content-type header when we set a JavaScript object to be the body of the current response.

Our API works great, but now we might decide that we would like to protect it from people abusing it and make sure people don't make more than one request in less than one second. This logic can be considered external to the business logic of our API, so we should add it by simply writing a new dedicated item of middleware. Let's write it as a separate module called rateLimit.js:

const lastCall = new Map(); 
 
module.exports = function *(next) { 
 
  // inbound 
  const now = new Date(); 
  if (lastCall.has(this.ip) && now.getTime() - 
      lastCall.get(this.ip).getTime() < 1000) { 
     return this.status = 429; // Too Many Requests 
  } 
 
  yield next; 
 
  // outbound 
  lastCall.set(this.ip, now); 
  this.set('X-RateLimit-Reset', now.getTime() + 1000); 
}; 

Our module exports a generator function that implements the logic for our middleware.

The first thing to notice is that we are using a Map object to store the time we received the last call from a given IP address. We will use this Map as a sort of in-memory database to be able to check whether a specific user is overloading our server with more than one request per second. Of course this implementation is just a dummy example and it's not ideal in a real case scenario, where it is better to just use external storage such as Redis or Memcache and a more refined logic to detect overloads.

We can see that the body of the middleware is divided in two logical parts, inbound and outbound, separated from the yield next call. In the inbound part, we haven't hit the core of the application yet, so it's the place where we need to check whether the user is exceeding our rate limit. If that is the case, we simply set the HTTP status code of the response to 429 (too many requests) and we return to stop the execution of the flow.

Another way we can progress to the next item of middleware is by calling yield next. This is where the magic happens: using generator functions and yield, the execution of the middleware is suspended to execute all the other middlewares in the list sequentially and only when the last item of middleware is executed (the real core of the app) the outbound flow can start and control is given back to every middleware in an inverted order, until the first middleware is called again.

When our middleware again receives control and the generator function is resumed, we take care of storing the timestamp for the successful call, and adding a X-RateLimit-Reset header to the request, to signal when the user will be able to make a new request.

To enable this middleware, we need to add the following line in our app.js before the existing app.use which contains the core logic of our app:

app.use(require('./rateLimit')); 

Now to see our new app in action, we need to restart our server and open our browser again. If we refresh the page quickly a few times, we will probably hit the rate limit and we should see the descriptive error message "Too Many Requests". This message is automatically added by Koa as a consequence of setting the status code to 429 and having an empty response body.