Cogs and Levers A blog full of technical stuff

Handling Exceptions with Domains in Node.js

16 May 2015

Safely responding to error scenarios can be difficult at times. Changing the context of when exceptions are raised amplifies and complicates the problem somewhat.

In today’s post, I’m going to walk through some simple usage of the Domain module in Node.js and how it can be applied in scenarios to make your software more fault tolerant overall.

What are Domains?

The description of a domain given in the API documentation sums it up best, I think:

Domains provide a way to handle multiple different IO operations as a single group. If any of the event emitters or callbacks registered to a domain emit an error event, or throw an error, then the domain object will be notified, rather than losing the context of the error in the process.on('uncaughtException') handler, or causing the program to exit immediately with an error code.

Going off the information in my previous post about eventing, the error events generated by EventEmitter objects are going to be registered inside of the domain allowing us a greater level of control and visibility in exception cases, no matter the context.

A simple example

In this example, we’ll create a generic EventEmitter and domain and we’ll see how the chain of error handling occurs:

var EventEmitter = require('events').EventEmitter;
var domain = require('domain');

var d1 = domain.create();
var emitter = new EventEmitter();

d1.on('error', function (err) {
    console.log('Domain: ' + err.stack);
});

d1.add(emitter);

emitter.on('error', function (err) {
    console.log('Listener: ' + err.stack);
});

We’ve created the domain d1 and have attached an error handler to it. We’ve also created our EventEmitter called emitter and attached a handler to it as well. The following code now starts to raise errors:

// this one gets handled by the emitter listener
emitter.emit('error', new Error('First error'));

// removing the emitter listener should force the exception
// to bubble to the domain
emitter.removeAllListeners('error');
emitter.emit('error', new Error('Second error'));

// removing the emitter from the domain should have us converting
// the error into an unhandled exception
d1.remove(emitter);
emitter.emit('error', new Error('Third error'));

As the comments read, we have our error being reported in different places as objects get detached from one another. The output of which looks like this:

Listener: Error: First error
    at Object.<anonymous> (/home/michael/event1.js:19:23)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:501:10)
    at startup (node.js:129:16)
    at node.js:814:3
Domain: Error: Second error
    at Object.<anonymous> (/home/michael/event1.js:24:23)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:501:10)
    at startup (node.js:129:16)
    at node.js:814:3
events.js:85
      throw er; // Unhandled 'error' event
            ^
Error: Third error
    at Object.<anonymous> (/home/michael/event1.js:29:23)
    at Module._compile (module.js:460:26)
    at Object.Module._extensions..js (module.js:478:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:501:10)
    at startup (node.js:129:16)
    at node.js:814:3

Our exceptions are reported to our attached handler on emitter first. Once it’s been removed as a handler, the error is then reported to the domain d1. Once the domain has no knowledge of emitter, the last error manifests as an unhandled error.

Implicit and Explicit Binding

An interesting point made in the documentation is about implicit and explicit binding.

If domains are in use, then all new EventEmitter objects (including Stream objects, requests, responses, etc.) will be implicitly bound to the active domain at the time of their creation.

So, if we’re in a scenario where we’re creating EventEmitter objects inside of the domain, there’s no need to add them using the add function.

In a lot of cases you aren’t afforded this luxury. The objects that you want to observe are created at a higher scope or just generally before the domain is constructed; in these cases you need to use the add function.

A little more RealWorld™

The api documentation contains a great example usage of the domain module in conjunction with the cluster model. It illustrates the ability to give your application a higher level of resilience against errors thrown so that not all of your uses are effected by a single rogue request.

The following started as an excerpt from the aforementioned documentation, but has been adapted for this article:

var server = require('http').createServer(function(req, res) {
    var d = domain.create();
    d.on('error', function(er) {
      console.error('error', er.stack);

      try {
        // make sure we close down within 30 seconds
        var killtimer = setTimeout(function() {
          process.exit(1);
        }, 30000);

        // But don't keep the process open just for that!
        killtimer.unref();

        // stop taking new requests.
        server.close();

        // Let the master know we're dead.  This will trigger a
        // 'disconnect' in the cluster master, and then it will fork
        // a new worker.
        cluster.worker.disconnect();

        // try to send an error to the request that triggered the problem
        res.statusCode = 500;
        res.setHeader('content-type', 'text/plain');
        res.end('Oops, there was a problem!\n');
      } catch (er2) {
        // oh well, not much we can do at this point.
        console.error('Error sending 500!', er2.stack);
      }
    });

    // explicitly added req and res to the domain
    d.add(req);
    d.add(res);

    // Now run the handler function in the domain.
    d.run(function() {
      handleRequest(req, res);
    });
});

server.listen(PORT);

The run method at the end is really the error pillow for our request handler. We don’t really know what went wrong in unhandled exception cases, all we know is that “something” went wrong. Safest course of action in these conditions is to shut down the failing server and start again.

Pretty neat.

Related Posts