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:
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 listeneremitter.emit('error',newError('First error'));// removing the emitter listener should force the exception// to bubble to the domainemitter.removeAllListeners('error');emitter.emit('error',newError('Second error'));// removing the emitter from the domain should have us converting// the error into an unhandled exceptiond1.remove(emitter);emitter.emit('error',newError('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:
varserver=require('http').createServer(function(req,res){vard=domain.create();d.on('error',function(er){console.error('error',er.stack);try{// make sure we close down within 30 secondsvarkilltimer=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 problemres.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 domaind.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.
An easy way to create an extensible API in Node.js is to use the EventEmitter class. It allows you to publish interesting injection points into your module so that client applications and libraries can respond when these events are emitted.
Simple example
In the following example, I’ll create a Dog class that exposes an event called bark. When this class internally decides that it’s time to bark, it will emit this event for us.
First of all, we define our class which includes a way to start the dog barking.
varutil=require('util');varEventEmitter=require('events').EventEmitter;varDog=function(name){varself=this;self.name=name;self.barkRandomly=function(){// WOOF WOOF!vardelay=parseInt(Math.random()*1000);setTimeout(function(){self.emit('bark',self);self.barkRandomly();},delay);};self.on('bark',function(dog){console.log(dog.name+' is barking!');});};util.inherits(Dog,EventEmitter);
The barkRandomly function will take a random interval of time and then emit the bark event for us. It’s an example for demonstration purposes so that you can see how you’d emit and event at the back end of a callback.
Note that the emit call allows us to specify some information about the event. In this example, we’ll just send the dog (or self) that’s currently barking.
Using the on function at the end, we’re also able to get the class itself to subscribe to its own bark event. The emit and on functions are available to us internally because we’ve used the inherits function from the util module to extend the Dog class with the attributes of EventEmitter.
All that’s left now is to create a dog and get it to bark.
varrover=newDog('Rover');rover.on('bark',function(dog){console.log('I just heard '+dog.name+' barking');});rover.barkRandomly();
Running this code, you’ll end up with a stream of barking notifications scrolling down your page.
Subscription management
Just as you can subscribe to an emitted event, you can remove a handler from the event when you are no longer interested in updates from it. To continue from the example above; if we had a handler that only cared if the dog barked for the first 3 times we could manage the subscription like so:
varrover=newDog('Rover');varnotificationCount=0;varhandler=function(dog){console.log('I just heard '+dog.name+' barking');notificationCount++;if(notificationCount==3){rover.removeListener('bark',handler);}};rover.on('bark',handler);
The operative line here being the call to removeListener.
You can simulate an irritable neighbor who would call the cops as soon as he heard your dog bark with a call to once which will fire once only, the first time it gets a notification:
rover.once('bark',function(dog){console.log('I\'VE HAD IT WITH THAT DOG, '+dog.name+'! I\'M CALLING THE COPS!');});
Finally, all subscribers can be removed from any given event with a call to removeAllListeners.
A really quick tip for persistently setting your video brightness level in Ubuntu, originally picked up from here.
Set the brightness level as you would normally with your control keys, then open a terminal to grab the current brightness setting:
cat /sys/class/backlight/acpi_video0/brightness
The value that you’re given as the output here can be used in your /etc/rc.local startup script. As the last item prior to theexit 0 statement, just add this:
As I write code in a lot of different languages using a lot of different frameworks, it makes sense for me to virtualise my development environments in such a way that they’re given their own isolated space so that they can’t infect each other. In today’s post, I’m going to walkthrough my development environment setup using Docker.
Setting up a Clojure environment
The example that I’ll use is the development container that I have setup for Clojure. First of all, I create a workspace for my Clojure development on my host machine, under my source directory like anything else. I’ll put this in ~/src/clojure.
In that folder, I create two scripts. run.sh which just gets a disposable container up and running and Dockerfile which is based off of the clojure:latest image from the docker hub repository, but just adds a couple of extra bits and pieces to help the development environment get started.
Dockerfile
The Dockerfile is pretty straight forward but relies on some magic. Unfortunately, here’s my solution loses its portability. DOH! But, I’m still unsure of how to get around this. To keep permissions and ownerships common between the host and the container (because we’ll be mounting a volume from the host), I create my developer account called michael as the next account after root. This is how it is on my host machine, so there’s no conflicting user/group ids.
FROM clojure:latest
RUN apt-get update && \
apt-get install -y sudo && \
apt-get clean && \
rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
RUN adduser --disabled-password --gecos '' michael && \
adduser michael sudo && \
echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
WORKDIR /home/michael
ENV HOME /home/michael
VOLUME ["/home/michael"]
USER michael
A couple of small things to note.
After installing sudo, I clean up any dead weight that apt-get may have left behind. This is just container maintenance to ensure that the image that’s generated is as small as possible.
We add the michael account with no password and directly into the sudo group. We also adjust the sudo config so that users in the sudo group can issue administrative commands without needing to supply a password.
From there, it’s all about making the home directory of michael centre stage for the container and switching to the michael user.
run.sh
The run script is fairly straight forward. All we need it to do is mount our current directory as a volume in the container and start bash. Of course, if you need to publish ports or create other volume mounts; here is where you’d do it.
#!/bin/bash
docker run -ti--rm-v$(pwd):/home/michael clojure:latest /bin/bash
Start developing
You’re done now. Everything creates in context of your non-root user. Your tools are available to you in your container and you’re free to develop using your editor on your host.
An interesting way of finding values that fall within a domain is to perform random sample analysis with the Monte Carlo method. This method of finding values relies on random values (lots of them) being measured against some form of deterministic calculation to determine if the value falls within the source function’s scope.
In today’s post, I’m going to illustrate how to use this method in some practical scenarios.
Approximating π
To approximate the value of π, we’re going to treat a square containing a quarter of a unit circle with a lot of random data. We only treat a quarter of a circle (which will contain angles 0 through 90) as we can easily mirror image a single quarter 4 times. Mathematically, you can consider the ratio of the circle’s area with respect to the square that contains it.
Circle area = πr^2
Square area = 2r^2 + 2r^2
= 4r^2
Ratio = πr^2 / 4r^2
= π/4
For every point that we randomly sample, the following must be true in order for us to consider the point as satisfying the circle:
rx^2 + ry^2 <= radius^2
This tells us, that from the midpoint 0,0, if the x and y values that we’ve randomly selected are within the bounds of the radius; we’ll consider it as “in”.
Once we’ve sampled enough data, we’ll take the ratio of points that are “in” and points that are “out”. We are still only dealing with a quarter of a circle, so we’ll multiply our result out as well and we should get close to π if we’ve sampled enough data. Here’s how it looks in python:
runs=1000000radius=1# get a batch of random points
rand_points=map(lambdax:(random()*radius,random()*radius),range(runs))# filter out the points that satisfy our equation
in_points=filter(lambda(x,y):((x*x)+(y*y))<=(radius*radius),rand_points)# calculate the ratio of points in the circle vs. points out of the circle
ratio=float(len(in_points))/float(runs)# multiply this figure by 4 to get all 4 quadrants considered
estimate=ratio*4
runs is the number of points that we’re going to sample. radius is only defined to be clear. If you were to change the radius of the tested area, your output ratio would need to be adjusted also.
Running this code a few times, I get the following results:
3.140356
3.14274
3.14064
3.142
3.140664
Area under a curve
When it comes to finding the area under a curve, nothing really beats numeric integration. In some cases though, your source function doesn’t quite allow for integration. In these cases, you can use a Monte Carlo simulation to work it out. For the purposes of this post though, I’ll work with x^2.
Let’s integrate it to begin with and work out what the area is between the x-axis points 0 and 3.
f(x) = x^2
ʃf(x) = x^3/3
area = ʃf(3) - ʃf(0)
= 9
So we’re looking for a value close to 9. It’s also important to note the values of our function’s output at the start of where we want to take the area from to the end as this will setup the bounds of our test:
f(x) = x^2
f(0) = 0
f(3) = 9
The area that we’ll be testing from is 0, 0 to 3, 9. The following code looks very similar to the π case. It has been adjusted to test the area and function:
runs=1000000max_x=3max_y=9# get a batch of random points
rand_points=map(lambdax:(random()*max_x,random()*max_y),range(runs))# filter out the points that satisfy our equation
in_points=filter(lambda(x,y):y<=(x*x),rand_points)# calculate the ratio of points in the curve area vs. points outside
ratio=float(len(in_points))/float(runs)# the estimate is the ratio over the area of the rectangle
estimate=ratio*(max_x*max_y)
Here’s some example outputs. Remember, our answer is 9; we want something close to that: