Extending EventEmitter In Order To Create A Response Proxy In Node.js

I've been doing a lot of experimenting with Node.js lately and one thing that I thought might be useful would be some additional hooks into the various parts of the HTTP response lifecycle. When you create an HTTP server, each request provides a response stream to which you can write data; but, other than hooking into the "finish" event on the response, Node.js doesn't appear to offer any other events - at least none that I could find (the Node.js documentation is decidedly sparse on the matter). In order to learn more about events in Node.js, I wanted to see if I could use the EventEmitter class in order to create a response Proxy object that would publish more events during the HTTP response lifecycle.

The ResponseProxy() class that I created extends the EventEmitter class using prototypal inheritance. It exposes a smaller API but a more robust event set. In particular, I chose to publish the following four events during the HTTP response lifecycle:

• commitStart - Fires right before the headers are flushed to the client (which commits the response).
• commitEnd - Fires right after the headers have been flushed to the client.
• requestStart - Fires right before any content has been written to the response output.
• requestEnd - Fires right before the response is closed.

In order to make these events possible, each ResponseProxy() instance has to manage the way in which the response stream is used. In particular, it has to be very explicit about when the headers are written and when the underlying stream is actually closed. To do this, the ResponseProxy() class exposes the following methods:

• end( [ data [, encoding ]] ) - Closes the response with an optional output write.
• getResponse() - Returns the underlying response object.
• setHeader( name, value ) - Sets an HTTP header.
• setStatus( code [, text ] ) - Sets the HTTP response code.
• write( data [, encoding ] ) - Writes data to the output.

Ultimately, these methods just proxy the underlying HTTP response stream. But, in doing so, we can wrap event publication around the first "write" action and event publication around the "end" action.

Let's take a look at the code. In the following Node.js HTTP server, notice that every single request results in a new ResponseProxy() instance. Also notice that the response is altered both by direct calls as well as by event listeners.

Server.js - HTTP Server

Notice that our ResponseProxy() event listeners allow us to alter the headers right before the response is committed and to write output right before the response is closed. When we boot up the above HTTP server and make a request, we get the following response:

As you can see, our event-based publication and subscription functionality provided by the inherited EventEmitter class allows us to augment the response based on the response lifecycle in addition to explicit writing, flushing, and closing. Since the EventEmitter class is being inherited, however, it is critical that the super constructor - EventEmitter - be invoked during the initialization of each ResponseProxy() instance. This will prevent two proxy objects from accidentally sharing the same set of event listeners (theoretically).

In a simple request / response context, something like this would probably be unnecessary. However, if you were building a Node.js HTTP framework, I can easily see some powerful functionality provided by a more robust set of response lifecycle hooks. If nothing else, this helped me get more comfortable with the core event model being used in Node.js.

You Might Also Be Interested In: