![\"crash_safely_using_domains_in_node.js\"](\"https:\/\/static.gosquared.com\/images\/liquidicity\/14_06_02_errors_01@2x.png\")
<\/p>\n<\/p>\n
In a previous post<\/a> about handling errors in Node.js programs, I took a look at how different flow control styles handle errors. I wanted to revisit the topic of error handling in a little more detail, and take a deeper look at an important error handling tool in Node.js: domains<\/a>. We’ll see how domains work, why you would use them, and how to go about it.<\/p>\n Before we start, I want to recommend a useful article about error handling<\/a> in Node by Joyent. I found it in their “Production Practises” documentation and it explains in good detail all of the essential information about errors in Node, such as the different kinds of error in a node program and the scenarios in which you might encounter them. It acts as a great primer to the material in this article, so take some time to absorb it and carry on with this after.<\/p>\n Domains<\/a> were introduced in Node.js v0.8 as a way of dealing with unhandled ‘error’ events, uncaught exceptions,\u00a0and even errors passed to callbacks via The general idea of domains is that if an error is not handled and is allowed to bubble up the stack all the way out of your program reaching\u00a0node itself, you can get Node.js to notify your domain about the error instead of freaking out and immediately exiting the process. The domain is set up by your program, allowing your program to decide what to do with an un-handled error in a controlled manner. Usually, the best course of action is to gracefully shut down your program and exit the process at an appropriate time.<\/p>\n A good example for why we should use domains is for a Node.js HTTP server. Imagine we have a simple HTTP server which invokes your program’s callback to handle each incoming request:<\/p>\n You can see there is a mistake in the In the example of a web server, we will likely be serving many clients concurrently, and if an exception happens during a request from one client, it will crash the server and abruptly hang up on that client as well as all the other clients! This can lead to all kinds of nasty consequences,\u00a0but at the very least it is damaging to our user’s experience.<\/p>\n So, here’s where we would use a domain. If we have a domain active, Node.js will tell that domain when an exception occurs. Our domain can then perform the necessary steps to gracefully shut down the program. In the case of our server program, we would want to:<\/p>\n A domain is an EventEmitter<\/a> object which, when “entered”, is accessible globally via By \u00a0attaching a listener to the domain’s In this example, we’re setting up a domain with an ‘error’ handler. We call What happens when we need to run a callback asynchronously, where the callback could be called after the domain has exited? How do we still ensure the domain will capture unhandled errors exuded by these callbacks? Node has an in-built method of doing this: domain binding.<\/p>\n The documentation<\/a> explains implicit and explicit binding.<\/p>\n Asynchronous callbacks are called\u00a0by\u00a0events and timers in Node. When you have a callback which is waiting for the result of a particular I\/O operation, the callback will be called on a different tick of the event loop to the one in which the I\/O operation was queued, and after the domain has exited.<\/p>\n To make sure their\u00a0callbacks\u00a0are called\u00a0in the context of\u00a0a domain,\u00a0event emitters and timers are\u00a0implicitly bound to a domain if it is active when they are created. This is what is meant by Implicit binding.<\/p>\n It is possible to re-assign the event emitter\u00a0or timer to another domain using\u00a0Explicit binding<\/a>. Likewise, the explicitly bound domain will be active while the callback is run.\u00a0\u00a0You can see this happening in events.js<\/a>.<\/p>\n Let’s see what happens with an event emitter:<\/p>\n So, let’s recap on what’s happening here.<\/p>\n Whenever an event is emitted on the EventEmitter object, the EventEmitter enters its bound domain immediately\u00a0before<\/em> the event listener is called, and exits the domain straight afterwards. This ensures that any error generated by the event listener will be routed to the EventEmitter’s domain, and not<\/em> the domain that might have been active before the event was fired.<\/p>\n This is one of the confusing aspects of domains: they exist globally, but event emitters and timers switch the global domain to their bound domain while running their listeners. Therefore, we can think of domains as different error handling contexts that switch as the thread of execution enters different areas of your program.<\/p>\n Now that we’ve seen how domains are set up and used, what actually happens when errors occur? That depends on the type of error, and as we’ve seen, there are 3 types: ‘error’ events, exceptions and error arguments passed to callbacks.<\/p>\n As we know, ‘error’ events are a special event type in Node. They are emitted by event emitters whenever there is a problem, for example socket errors such as\u00a0 When ‘error’ is emitted on an event emitter:<\/p>\n You can see this logic in events.js<\/a>. The following example illustrates the propagation of steps 1-3:<\/p>\n Exceptions bubble up the call stack until they are caught\u00a0by a try\/catch block. If they are not caught, they climb out of your program, causing Node to do the following:<\/p>\n In Node, the convention for callback arguments is When a callback runs, it is typically within a call stack with an event emitter or timer listener at the top. If the listener is called in the context of a bound domain, any uncaught errors coming from that callback will be handled by the domain.<\/p>\n However, if you’d like to ensure the callback runs in the context of a different domain, you can bind it to the desired domain using Furthermore, in a callback, you’d usually check for the err argument and handle it accordingly. Using\u00a0Why should I care about domains?<\/h2>\n
domain.intercept()<\/code><\/a>.<\/p>\n\nvar http = require('http');\nhttp.createServer(function(req, res) {\n \/\/ On 10% of requests this code will run and throw an exception\n if (Math.random() > 0.9) {\n woops.thisWillThrow();\n }\n}).listen(8000);\n\n<\/code><\/pre>\nif<\/code> block. If one of the requests try to run that code, an exception is thrown due to a ReferenceError<\/code><\/span> from the undefined woops<\/code><\/span> object.<\/p>\n\n
What is a domain, exactly?<\/h2>\n
process.domain<\/code> and require('domain').active<\/code>. Multiple domains can exist in the domain stack, which is simply an array internally in Node holding all domains in the order they were created. Only one domain can be active on the process at a time, and is only active when it is “entered”. This is so that when Node.js is running code, it knows which domain should be notified about any unhandled errors that might occur.<\/p>\nHow to use domains<\/h2>\n
'error'<\/code> event, you control what happens when the domain is notified of an error:<\/p>\n\nvar domain = require('domain');\nvar d = domain.create();\n\/\/ Domain emits 'error' when it's given an unhandled error\nd.on('error', function(err) {\n console.log(err.stack);\n\u00a0\/\/ Our handler should deal with the error in an appropriate way\n});\n\n\/\/ Enter this domain\nd.run(function() {\n \/\/ If an un-handled error originates from here, process.domain will handle it\n console.log(process.domain === d); \/\/ true\n});\n\n\/\/ domain has now exited. Any errors in code past this point will not be caught.\n<\/code><\/pre>\nd.run<\/code> to enter the domain. The domain will be active while the code in the callback runs. After the function completes, the domain is exited. We’re not waiting on any asynchronous I\/O here so the code in this example runs synchronously in the context of the domain.<\/p>\nImplicit\/explicit binding on event emitters and timers<\/h3>\n
var EventEmitter = require('events').EventEmitter;\nvar domain = require('domain');\n\n\/\/ Create 2 domains\nvar d1 = domain.create();\nvar d2 = domain.create();\n\n\/\/ Enter the first domain\nd1.run(function() {\n \/\/ This emitter is implicitly bound to d1\n \/\/ because it is created while process.domain === d1\n var implicitEmitter = new EventEmitter();\n implicitEmitter.on('someEvent', function() {\n console.log(process.domain === d1); \/\/ true\n });\n\n implicitEmitter.emit('someEvent');\n\n \/\/ Explicitly bind this emitter to another domain\n var explicitEmitter = new EventEmitter();\n d2.add(explicitEmitter);\n\n explicitEmitter.on('someEvent', function() {\n console.log(process.domain === d2); \/\/ true\n });\n\n explicitEmitter.emit('someEvent');\n});\n<\/code><\/pre>\nHow errors are routed<\/h2>\n
‘error’ events<\/h3>\n
'EACCES'<\/code> triggered by net.createServer.listen(1)<\/code>.<\/p>\n\n
\nvar EventEmitter = require('events').EventEmitter;\nvar domain = require('domain');\n\nvar emitter = new EventEmitter();\n\n\/\/ Bind to domain\nvar d1 = domain.create();\nd1.on('error', function(err) {\n console.log('Handled by domain:', err.stack);\n});\nd1.add(emitter);\n\n\/\/ Attach listener\nemitter.on('error', function(err) {\n console.log('Handled by listener:', err.stack);\n});\n\nemitter.emit('error', new Error('this will be handled by listener'));\nemitter.removeAllListeners('error');\nemitter.emit('error', new Error('this will be handled by domain'));\nd1.remove(emitter);\nemitter.emit('error', new Error('woops, unhandled error. This is converted to an exception. Time to crash!'));\n<\/code><\/pre>\nExceptions<\/h3>\n
\n
'error'<\/code> event on the domain object.<\/li>\n'uncaughtException'<\/code> event (there shouldn’t be<\/a>) and call them with the error if they exist.<\/li>\nCallback arguments<\/h3>\n
function(err, arg1, ...)<\/code>. If the asynchronous operation failed, err should\u00a0be passed as the first argument to the\u00a0callback and be an instance\u00a0of Error.<\/p>\nBinding domains directly to callbacks<\/h4>\n
domain.bind(fn)<\/code><\/a>.<\/p>\ndomain.intercept(fn)<\/code><\/a>, you can instead delegate the error checking and handling step to a domain.<\/p>\nIn conclusion<\/h3>\n